Comment installer le pilote CSI Amazon S3 sur mes clusters Amazon EKS ?

Résolution

Remarque : Si des erreurs surviennent lorsque vous exécutez des commandes de l'interface de la ligne de commande AWS (AWS CLI), consultez la section Résoudre des erreurs liées à l’AWS CLI. Vérifiez également que vous utilisez bien la version la plus récente de l’AWS CLI.

Prérequis :

• Installez les outils de ligne de commande kubectl et eksctl.
• Créez un fournisseur OpenID Connect (OIDC) de Gestion des identités et des accès AWS (AWS IAM) pour votre cluster.
• Utilisez les rôles IAM pour les comptes de service (IRSA) car vous ne pouvez pas utiliser l’identité du pod EKS avec le pilote CSI Amazon S3.

Pour obtenir votre ID d'émetteur OIDC, exécutez la commande describe-cluster de l'AWS CLI suivante :

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

Remarque : Remplacez your_cluster_name par le nom du cluster Amazon EKS.

Pour vérifier si vous avez configuré un fournisseur OIDC IAM, exécutez la commande list-open-id-connect-providers suivante :

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

Remarque : Remplacez YOUR_OIDC_ID par votre ID OIDC. Si la sortie est vide, vous devez créer un fournisseur OIDC IAM.

Exécutez la commande suivante pour créer un fournisseur IAM OIDC :

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

Remarque : Remplacez your_cluster_name par le nom de votre cluster.

Déployer le pilote CSI Amazon S3

Procédez comme suit :

1. Créez une politique IAM en fonction de vos besoins.
   Politique de compartiment à usage général :

   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

   Remarque : Remplacez your_bucket_name par le nom de votre compartiment.
   Politique de compartiment de répertoires :

   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

   Remarque : Remplacez YOUR_AWS_REGION par votre région AWS, YOUR_AWS_ACCOUNT_ID par votre compte AWS, your_bucket_name par le nom de votre compartiment et az_id par votre zone de disponibilité.
2. Exécutez la commande create-policy suivante pour créer une politique IAM nommée AmazonS3CSIDriverPolicy :

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

   Remarque : Remplacez iam-policy.json par votre fichier JSON de politique IAM.
3. Créez la politique d’approbation IAM suivante :

   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

   Remarque : Remplacez YOUR_AWS_ACCOUNT_ID par l’ID de votre compte, YOUR_AWS_REGION par votre région et YOUR_OIDC_ID par l’ID de votre OIDC.
4. Exécutez la commande create-role suivante pour créer un rôle IAM nommé AmazonEKS_S3_CSI_DriverRole :

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

   Remarque : Remplacez trust-policy.json par votre fichier JSON de politique d’approbation IAM.
5. Exécutez la commande attach-role-policy suivante pour associer la politique au rôle IAM :

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

   Remarque : Remplacez YOUR_AWS_ACCOUNT_ID par l’ID de votre compte AWS.
6. Exécutez la commande create-addon suivante pour déployer le pilote CSI Amazon S3 sur votre cluster :

   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

   Remarque : Remplacez your_cluster_name par le nom de votre cluster et YOUR_AWS_ACCOUNT_ID par l’ID de votre compte. Pour installer le pilote Amazon CSI S3 avec Kustomize ou Helm, consultez la section Installation sur le site Web de GitHub.

Pour permettre aux utilisateurs de remplacer des fichiers existants, ajoutez l'indicateur --allow-overwrite au volume persistant. Vous devez ajouter toutes les écritures de manière séquentielle depuis le début du fichier. Vous ne pouvez pas ajouter de fichiers. Vous devez plutôt remplacer le contenu existant par un nouveau contenu. Toutefois, pour les compartiments de répertoires de la classe de stockage Amazon S3 Express One Zone, vous pouvez ajouter des fichiers existants. Pour ce faire, ajoutez l'indicateur --incremental-upload au volume persistant. Commencez également par la fin du fichier pour ajouter séquentiellement toutes les écritures. Pour plus d'informations, consultez la page Lecture et écriture de fichiers et Configuration sur le site Web de GitHub.

Le point de montage du pilote Amazon S3 CSI utilise uniquement le provisionnement statique. Vous ne pouvez pas utiliser le provisionnement dynamique ni créer de nouveaux compartiments. Les volumes que vous montez sur le point de montage ne peuvent pas utiliser toutes les fonctionnalités du système de fichiers POSIX. Pour plus d'informations, consultez la page Point de montage pour le comportement du système de fichiers Amazon S3 sur le site Web de GitHub. Si vos applications nécessitent des systèmes de fichiers complets, il est recommandé d'utiliser Amazon Elastic File System (Amazon EFS) ou Amazon FSx.

Tester le pilote CSI Amazon S3

Pour tester le pilote CSI Amazon S3, déployez un exemple d'application qui utilise le provisionnement statique pour les pods. Pour obtenir des étapes et des exemples, consultez la page Exemple de provisionnement statique sur le site Web de GitHub.

Résoudre les problèmes liés au pilote CSI Amazon S3

Votre pilote CSI Amazon S3 ne fonctionne pas comme prévu

Pour vérifier que les pods du nœud du pilote CSI Amazon S3 sont en cours d'exécution, exécutez la commande suivante :

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

Pour consulter les journaux des modules du pilote CSI Amazon S3, exécutez la commande suivante :

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

Assurez-vous que le compartiment Amazon S3 se trouve dans la même région que le cluster Amazon EKS. Si le compartiment et le cluster se trouvent dans des régions différentes, mettez à jour les options de montage pour inclure la région.

Exemple de configuration :

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

Si le pilote CSI Amazon S3 ne fonctionne pas sur les Amazon Machine Images (AMI) Bottlerocket, exécutez la commande suivante pour vérifier la version de l'image du conteneur :

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

Dans la sortie de la commande, assurez-vous que la version de l'image du conteneur est supérieure ou égale à la version 1.4.0. Il est recommandé d'utiliser la dernière version du pilote CSI Amazon S3. Pour la dernière version, consultez la page mountpoint-s3-csi-driver Releases sur le site Web de GitHub.

Les utilisateurs de votre conteneur ne peuvent pas accéder au compartiment Amazon S3

Par défaut, seul l'utilisateur qui a monté le compartiment S3 peut accéder à votre répertoire monté. Cela se produit même lorsque vous configurez les autorisations et les paramètres de propriété pour permettre aux autres utilisateurs du conteneur d'accéder au compartiment.

Pour permettre à d'autres utilisateurs non racine d'accéder à votre répertoire monté, mettez à jour mountOptions pour inclure l'option --allow-other. Pour permettre à l'utilisateur racine d'accéder à votre répertoire monté en tant qu'utilisateur différent, utilisez --allow-root.

Exemple de politique :

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

L’erreur « Volume capability not supported » (Capacité de volume non prise en charge) s'affiche

Lorsque vous utilisez le pilote CSI Amazon S3, vous pouvez recevoir un message d'erreur similaire à l'exemple suivant :

« Warning FailedMount 39s (x8 over 104s) kubelet MountVolume.SetUp failed for volume "s3-pv-1" : rpc error: code = InvalidArgument desc = Volume capability not supported » (Avertissement Échec de MountVolume.SetUp du kubelet FailedMount 39s (x8 sur 104s) pour le volume "s3-pv-1" : code rpc : code = desc InvalidArgument = Capacité de volume non prise en charge)

L'erreur précédente s'affiche lorsque vous utilisez un mode d'accès que le pilote CSI Amazon S3 ne prend pas en charge, tel que ReadWriteOncePod ou ReadWriteOnce. Vous ne pouvez utiliser que les modes d'accès ReadWriteMany ou ReadOnlyMany.