Wie installiere ich den Amazon S3-CSI-Treiber auf meinen Amazon EKS-Clustern?

Behebung

Hinweis: Wenn du beim Ausführen von AWS Command Line Interface (AWS CLI)-Befehlen Fehlermeldungen erhältst, findest du weitere Informationen dazu unter Problembehandlung bei der AWS CLI. Stelle außerdem sicher, dass du die neueste Version von AWS CLI verwendest.

Voraussetzungen:

• Installiere die Befehlszeilentools kubectl und eksctl.
• Erstelle einen AWS Identity and Access Management (IAM, Identitäts- und Zugriffsmanagement) OpenID Connect (OIDC)-Anbieter für den Cluster.
• Verwende IAM-Rollen für Servicekonten (IRSA), da du EKS Pod Identity nicht mit dem Amazon S3-CSI-Treiber verwenden kannst.

Führe den folgenden AWS-CLI-Befehl describe-cluster aus, um die OIDC-Aussteller-ID abzurufen:

aws eks describe-cluster --name your_cluster_name --query "cluster.identity.oidc.issuer" --output text | cut -d '/' -f 5

Hinweis: Ersetze your_cluster_name durch deinen Amazon EKS-Clusternamen.

Um zu überprüfen, ob du einen IAM-OIDC-Anbieter konfiguriert hast, führe den folgenden Befehl list-open-id-connect-providers aus:

aws iam list-open-id-connect-providers | grep your_OIDC_ID | cut -d "/" -f4

Hinweis: Ersetze YOUR_OIDC_ID durch deine OIDC-ID. Wenn die Ausgabe leer ist, musst du einen IAM-OIDC-Anbieter erstellen.

Um den IAM-OIDC-Anbieter zu erstellen, führe den folgenden Befehl aus:

eksctl utils associate-iam-oidc-provider --cluster your_cluster_name --approve

Hinweis: Ersetze your_cluster_name durch deinen Clusternamen.

Den Amazon S3-CSI-Treiber bereitstellen

Führe die folgenden Schritte aus:

1. Erstelle eine IAM-Richtlinie, die auf deinen Anforderungen basiert.
   Universale Bucket-Richtlinie:

   cat <<EOF > iam-policy.json
   {
      "Version": "2012-10-17",
      "Statement": [
           {
               "Sid": "MountpointFullBucketAccess",
               "Effect": "Allow",
               "Action": [
                   "s3:ListBucket"
               ],
               "Resource": [
                   "arn:aws:s3:::your_bucket_name"
               ]
           },
           {
               "Sid": "MountpointFullObjectAccess",
               "Effect": "Allow",
               "Action": [
                   "s3:GetObject",
                   "s3:PutObject",
                   "s3:AbortMultipartUpload",
                   "s3:DeleteObject"
               ],
               "Resource": [
                   "arn:aws:s3:::your_bucket_name/*"
               ]
           }
      ]
   }
   EOF

   Hinweis: Ersetze your_bucket_name durch deinen Bucket-Namen.
   Verzeichnis-Bucket-Richtlinie:

   cat <<EOF > iam-policy.json
   {
       "Version": "2012-10-17",
       "Statement": [
           {
               "Effect": "Allow",
               "Action": "s3express:CreateSession",
               "Resource": "arn:aws:s3express:YOUR_AWS_REGION:YOUR_AWS_ACCOUNT_ID:bucket/your_bucket_name--az_id--x-s3"
           }
       ]
   }
   EOF

   Hinweis: Ersetze YOUR_AWS_REGION durch deine AWS-Region, YOUR_AWS_ACCOUNT_ID durch dein AWS-Konto, your_bucket_name durch deinen Bucket-Namen und az_id durch deine Availability Zone.
2. Führe den folgenden Befehl create-policy aus, um eine IAM-Richtlinie mit dem Namen AmazonS3CSIDriverPolicy zu erstellen:

   aws iam create-policy --policy-name AmazonS3CSIDriverPolicy --policy-document file://iam-policy.json

   Hinweis: Ersetze iam-policy.json durch deine IAM-Richtlinien-JSON-Datei.
3. Erstelle die folgende IAM-Vertrauensrichtlinie:

   cat <<EOF > trust-policy.json
   {
       "Version": "2012-10-17",
       "Statement": [
         {
           "Effect": "Allow",
           "Principal": {
             "Federated": "arn:aws:iam::YOUR_AWS_ACCOUNT_ID:oidc-provider/oidc.eks.YOUR_AWS_REGION.amazonaws.com/id/your_OIDC_ID"
           },
           "Action": "sts:AssumeRoleWithWebIdentity",
           "Condition": {
             "StringLike": {
               "oidc.eks.YOUR_AWS_REGION.amazonaws.com/id/your_OIDC_ID:sub": "system:serviceaccount:kube-system:s3-csi-*",
               "oidc.eks.YOUR_AWS_REGION.amazonaws.com/id/your_OIDC_ID:aud": "sts.amazonaws.com"
             }
           }
         }
       ]
   }
   EOF

   Hinweis: Ersetze YOUR_AWS_ACCOUNT_ID durch dein Konto, YOUR_AWS_REGION durch deine Region und YOUR_OIDC_ID durch deine OIDC-ID.
4. Führe den folgenden Befehl create-role aus, um eine IAM-Rolle mit dem Namen AmazonEKS_S3_CSI_DriverRole zu erstellen:

   aws iam create-role --role-name AmazonEKS_S3_CSI_DriverRole  --assume-role-policy-document file://"trust-policy.json"

   Hinweis: Ersetze trust-policy.json durch deine IAM-Vertrauensrichtlinien-JSON-Datei.
5. Führe den folgenden Befehl attach-role-policy aus, um die Richtlinie an die IAM-Rolle anzufügen:

   aws iam attach-role-policy  --policy-arn arn:aws:iam::YOUR_AWS_ACCOUNT_ID:policy/AmazonS3CSIDriverPolicy --role-name AmazonEKS_S3_CSI_DriverRole

   Hinweis: Ersetze YOUR_AWS_ACCOUNT_ID durch deine AWS-Konto-ID.
6. Führe den folgenden Befehl create-addon aus, um den Amazon S3-CSI-Treiber auf dem Cluster bereitzustellen:

   aws eks  create-addon --cluster-name your_cluster_name --addon-name aws-mountpoint-s3-csi-driver --service-account-role-arn arn:aws:iam::YOUR_AWS_ACCOUNT_ID:role/AmazonEKS_S3_CSI_DriverRole

   Hinweis: Ersetze your_cluster_name durch deinen Clusternamen und YOUR_AWS_ACCOUNT_ID durch deine Konto-ID. Informationen zur Installation des Amazon S3-CSI-Treibers mit Kustomize oder Helm findest du unter Installation auf der GitHub-Website.

Um Benutzern das Überschreiben vorhandener Dateien zu ermöglichen, füge dem persistenten Volume das Flag --allow-overwrite hinzu. Du musst alle Schreibvorgänge nacheinander vom Anfang der Datei aus hinzufügen. Du kannst keine Dateien anfügen. Stattdessen musst du vorhandenen Inhalt durch neuen Inhalt ersetzen. Für Verzeichnis-Buckets in der Amazon S3 Express One Zone-Speicherklasse kannst du jedoch vorhandene Dateien anfügen. Füge dazu dem persistenten Volume das Flag --incremental-upload hinzu. Beginne außerdem am Ende der Datei, um nacheinander alle Schreibvorgänge hinzuzufügen. Weitere Informationen findest du unter Reading and writing files (Dateien lesen und schreiben) und Configure (Konfigurieren) auf der GitHub-Website.

Der Amazon S3-CSI-Treiber-Bereitstellungspunkt verwendet nur statische Bereitstellung. Du kannst keine dynamische Bereitstellung verwenden oder neue Buckets erstellen. Volumes, die du am Bereitstellungspunkt einbindest, können nicht alle POSIX-Dateisystem-Features nutzen. Weitere Informationen findest du unter Mountpoint for Amazon S3 file system behavior (Dateisystemverhalten des Mountpoint für Amazon S3) auf der GitHub-Website. Wenn die Anwendungen komplette Dateisysteme benötigen, empfiehlt es sich, Amazon Elastic File System (Amazon EFS) oder Amazon FSx zu verwenden.

Den Amazon S3-CSI-Treiber testen

Um den Amazon S3-CSI-Treiber zu testen, stelle eine Beispielanwendung bereit, die statische Bereitstellung für die Pods verwendet. Schritte und Beispiele findest du unter Static provisioning example (Beispiel für statische Bereitstellung) auf der GitHub-Website.

Beheben von Problemen mit dem Amazon S3-CSI-Treiber

**Dein Amazon S3-CSI-Treiber funktioniert nicht wie erwartet **

Führe den folgenden Befehl aus, um zu überprüfen, ob die Amazon S3-CSI-Treiberknoten-Pods ausgeführt werden:

kubectl get all -l app.kubernetes.io/name=aws-mountpoint-s3-csi-driver -n kube-system

Führe den folgenden Befehl aus, um die Protokolle der Amazon S3-CSI-Treiber-Pods zu überprüfen:

kubectl logs daemonset/s3-csi-node -n kube-system -c s3-plugin:

Stelle sicher, dass sich der Amazon S3-Bucket in derselben Region wie der Amazon EKS-Cluster befindet. Wenn sich der Bucket und der Cluster in verschiedenen Regionen befinden, aktualisiere die mountOptions, um die Region einzubeziehen.

Beispielkonfiguration:

apiVersion: v1
kind: PersistentVolume
metadata:
  name: s3-pv-1
spec:
  accessModes:
  - ReadWriteMany
  capacity:
    storage: 10Gi
  csi:
    driver: s3.csi.aws.com
    volumeAttributes:
      bucketName: bucket name
    volumeHandle: s3-csi-driver-volume
  mountOptions:
  - region us-west-2
  - allow-other     
  persistentVolumeReclaimPolicy: Retain
  volumeMode: Filesystem

Wenn der Amazon S3-CSI-Treiber auf Bottlerocket Amazon Machine Images (AMIs) nicht funktioniert, führe den folgenden Befehl aus, um die Container-Image-Version zu überprüfen:

kubectl get ds s3-csi-node -n kube-system -ojsonpath="{range .spec.template.spec.containers[*]}{.image}{'\n'}{end}"

Stelle in der Befehlsausgabe sicher, dass die Container-Image-Version größer oder gleich v1.4.0 ist. Es hat sich bewährt, die neueste Amazon S3-CSI-Treiberversion zu verwenden. Die neueste Version findest du unter mountpoint-s3-csi-driver Releases (mountpoint-s3-csi-driver-Versionen) auf der GitHub-Website.

Benutzer in deinem Container können nicht auf den Amazon S3-Bucket zugreifen

Standardmäßig kann nur der Benutzer, der den S3-Bucket eingebunden hat, auf das eingebundene Verzeichnis zugreifen. Dies tritt auch dann auf, wenn du Berechtigungen und Eigentümereinstellungen so konfigurierst, dass andere Benutzer im Container auf den Bucket zugreifen können.

Um anderen Nicht-Root-Benutzern den Zugriff auf das eingebundene Verzeichnis zu ermöglichen, aktualisiere mountOptions so, dass es die Option --allow-other enthält. Um dem Root-Benutzer den Zugriff auf das eingebundene Verzeichnis als anderer Benutzer zu ermöglichen, verwende --allow-root.

Beispiel für eine Richtlinie:

apiVersion: v1
kind: PersistentVolume
metadata:
  name: s3-pv-1
spec:
  accessModes:
  - ReadWriteMany
  capacity:
    storage: 10Gi
  csi:
    driver: s3.csi.aws.com
    volumeAttributes:
      bucketName: bucket name
    volumeHandle: s3-csi-driver-volume
  mountOptions:
  - region us-west-2
  - allow-other                        
  persistentVolumeReclaimPolicy: Retain
  volumeMode: Filesystem

Du erhältst die Fehlermeldung „Volume capability not supported“

Wenn du den Amazon S3-CSI-Treiber verwendest, erhältst du möglicherweise eine Fehlermeldung, die dem folgenden Beispiel ähnelt:

„Warning FailedMount 39s (x8 over 104s) kubelet MountVolume.SetUp failed for volume "s3-pv-1" : rpc error: code = InvalidArgument desc = Volume capability not supported“

Du erhältst den obigen Fehler, wenn du einen Zugriffsmodus verwendest, den der Amazon S3-CSI-Treiber nicht unterstützt, wie ReadWriteOncePod oder ReadWriteOnce. Du kannst nur die Zugriffsmodi ReadWriteMany oder ReadOnlyMany verwenden.