Comment puis-je utiliser le stockage persistant dans Amazon EKS ?

Brève description

Configurez le stockage persistant dans Amazon EKS à l’aide de l’une des options suivantes :

• Pilote d’interface de stockage de conteneur (CSI) Amazon Elastic Block Store (Amazon EBS)
• Pilote d’interface de stockage de conteneur (CSI) Amazon Elastic File System (Amazon EFS)

Pour utiliser l’une de ces options, suivez les étapes décrites dans l’une des sections suivantes :

• Option A : déployer et tester le pilote CSI Amazon EBS
• Option B : déployer et tester le pilote CSI Amazon EFS

Les commandes de cet article nécessitent la version 1.14 ou ultérieure de kubectl. Pour avoir accès à votre version de kubectl, exécutez la commande suivante :

kubectl version --client --short

Remarque : il est recommandé d’installer la version ultérieure des pilotes. Pour plus d’informations, consultez les référentiels GitHub du pilote CSI Amazon EBS et du pilote CSI Amazon EFS.

Résolution

Remarque : si des erreurs surviennent lors de l’exécution des commandes de l’interface de la ligne de commande AWS (AWS CLI), vérifiez que vous utilisez bien la version la plus récente de l’AWS CLI.

Avant de suivre les instructions données dans l’une ou l’autre section, vous devez :

1. Installer l’AWS CLI.

2. Définir les autorisations AWS Identity and Access Management (AWS IAM) pour créer et associer une politique au rôle de composant master Amazon EKS Rôle du pilote CSI.
   Remarque : les commandes des sections suivantes n’utilisent pas toujours la variable**--region**. Si vous n’utilisez pas --region, les commandes utilisent la valeur par défaut de votre région AWS. Pour vérifier la valeur par défaut, exécutez la commande configuration de l’AWS CLI.

3. Créez votre cluster Amazon EKS et joignez-y vos composants master.
   Remarque : exécutez la commande kubectl obtenir les nœuds, afin de vérifier que vos composants master sont bien associés à votre cluster.

4. Pour vérifier l’existence du fournisseur AWS IAM OpenID Connect (OIDC) pour votre cluster, exécutez la commande suivante :

   aws eks describe-cluster --name your_cluster_name --query "cluster.identity.oidc.issuer" --output text

   Remarque : remplacez your_cluster_name par le nom de votre cluster.

5. Vérifiez que votre fournisseur IAM OIDC est bien configuré :

   aws iam list-open-id-connect-providers | grep OIDC_PROVIDER_ID

   Remarque : remplacer l’ID du fournisseur oidc par votre ID OIDC. Si le message d’erreur No OpenIDConnect provider found in your account s’affiche, vous devez créer un fournisseur IAM OIDC.

6. Installez ou mettez à jour eksctl.

7. Créez un fournisseur IAM OIDC :

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

   Remarque : remplacez my-cluster par le nom de votre cluster.

Option A : déployer et tester le pilote CSI Amazon EBS

Déployez le pilote CSI Amazon EBS :

1. créez un fichier de politique de confiance IAM, comme dans l’exemple suivant :

   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": {
           "StringEquals": {
             "oidc.eks.YOUR_AWS_REGION.amazonaws.com/id/<XXXXXXXXXX45D83924220DC4815XXXXX>:aud": "sts.amazonaws.com",
             "oidc.eks.YOUR_AWS_REGION.amazonaws.com/id/<XXXXXXXXXX45D83924220DC4815XXXXX>:sub": "system:serviceaccount:kube-system:ebs-csi-controller-sa"
           }
         }
       }
     ]
   }
   EOF

   Remarque : remplacez YOUR_AWS_ACCOUNT_ID par l’ID de votre compte AWS. Remplacez YOUR_AWS_REGION par votre région AWS. Remplacez your OIDC ID par le résultat de la création de votre fournisseur IAM OIDC.

2. Créez un rôle IAM nommé Amazon_EBS_CSI_Driver :

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

3. associez la politique IAM gérée par AWS pour le pilote CSI EBS au rôle IAM que vous avez créé :

   aws iam attach-role-policy \
   --policy-arn arn:aws:iam::aws:policy/service-role/AmazonEBSCSIDriverPolicy \
   --role-name AmazonEKS_EBS_CSI_Driver

4. Déployez le pilote CSI Amazon EBS.

   aws eks create-addon \
    --cluster-name my-cluster \
    --addon-name aws-ebs-csi-driver \
    --service-account-role-arn arn:aws:iam::
   YOUR_AWS_ACCOUNT_ID:role/AmazonEKS_EBS_CSI_DriverRole

   Remarque : remplacez my-cluster par le nom de votre cluster et YOUR_AWS_ACCOUNT_ID par l’ID de votre compte AWS.

   Vous pouvez déployer le pilote CSI EBS à l’aide de Kustomize, Helm ou d’un module complémentaire géré par Amazon EKS. Cet exemple utilise la fonctionnalité complémentaire Amazon EKS pour déployer le pilote. Pour plus d’informations, consultez le guide d’installation du pilote aws-ebs-csi-driver sur GitHub.

5. Vérifiez que le pilote CSI EBS est bien installé :

   eksctl get addon --cluster my-cluster | grep ebs

   Une installation réussie renvoie le résultat suivant :

   aws-ebs-csi-driver    v1.20.0-eksbuild.1    ACTIVE    0    arn:aws:iam::YOUR_AWS_ACCOUNT_ID:role/AmazonEKS_EBS_CSI_Driver

Tester le pilote CSI Amazon EBS :

Vous pouvez tester votre pilote CSI Amazon EBS à l’aide d’un exemple d’application qui utilise le l’approvisionnement dynamique des pods. Le volume Amazon EBS est approvisionné à la demande.

1. Clonez le référentiel aws-ebs-csi-driver à partir d’AWS GitHub :

   git clone https://github.com/kubernetes-sigs/aws-ebs-csi-driver.git

2. Remplacez votre répertoire de travail par le dossier contenant les fichiers de test du pilote Amazon EBS :

   cd aws-ebs-csi-driver/examples/kubernetes/dynamic-provisioning/

3. Créez les ressources Kubernetes requises pour effectuer les tests :

   kubectl apply -f manifests/

   Remarque : la commande kubectl crée un StorageClass, un PersistentVolumeClaim (PVC) et un pod. Le pod fait référence aux PVC. Un volume Amazon EBS est approvisionné uniquement lorsque le pod est créé. Pour plus d’informations, consultez les sections Storage classes et PersistentVolumeClaims sur le site Web de Kubernetes.

4. Décrivez la classe de stockage ebs-sc :

   kubectl describe storageclass ebs-sc

5. Consultez les pods dans l’espace de noms par défaut et attendez que l’état du pod d’application passe à En cours d’exécution. Par exemple :

   kubectl get pods --watch

6. affichez le volume persistant créé en raison du pod qui fait référence au PVC :

   kubectl get pv

7. affichez les informations relatives au volume persistant :

   kubectl describe pv your_pv_name

   Remarque : remplacez your_pv_name par le nom du volume persistant renvoyé à l’étape 6 de la section précédente. La valeur de la propriété Source.VolumeHandle dans le résultat est l’ID du volume Amazon EBS physique créé dans votre compte.

8. Vérifiez que le pod écrit des données sur le volume :

   kubectl exec -it app -- cat /data/out.txt

   Remarque : la sortie de la commande affiche la date et l’heure actuelles stockées dans le fichier /data/out.txt. Le fichier comprend le jour, le mois, la date et l’heure.

Option B : déployer et tester le pilote CSI Amazon EFS

Avant de déployer le pilote CSI, créez un rôle IAM qui permet au compte de service du pilote CSI de passer des appels aux API d’AWS en votre nom.

1. Téléchargez le document de politique IAM à partir de GitHub :

   curl -o iam-policy-example.json https://raw.githubusercontent.com/kubernetes-sigs/aws-efs-csi-driver/master/docs/iam-policy-example.json

2. Créez une politique IAM :

   aws iam create-policy \
       --policy-name AmazonEKS_EFS_CSI_Driver_Policy \
       --policy-document file://iam-policy-example.json

3. Exécutez la commande suivante pour déterminer l’URL du fournisseur OIDC de votre cluster :

   aws eks describe-cluster --name your_cluster_name --query "cluster.identity.oidc.issuer" --output text

   Remarque : à l’étape 3, remplacez your_cluster_name par le nom de votre cluster.

4. Créez la politique de confiance IAM suivante, puis accordez l’action AssumeRoleWithWebIdentity à votre compte de service Kubernetes :

   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/<XXXXXXXXXX45D83924220DC4815XXXXX>"
         },
         "Action": "sts:AssumeRoleWithWebIdentity",
         "Condition": {
           "StringEquals": {
             "oidc.eks.YOUR_AWS_REGION.amazonaws.com/id/<XXXXXXXXXX45D83924220DC4815XXXXX>:sub": "system:serviceaccount:kube-system:efs-csi-controller-sa"
           }
         }
       }
     ]
   }
   EOF

   Remarque : à l’étape 4, remplacez YOUR_AWS_ACCOUNT_ID par l’ID de votre compte AWS. Remplacez YOUR_AWS_REGION par votre région AWS. Remplacez XXXXXXXXXX45D83924220DC4815XXXXX par la valeur renvoyée à l’étape 3.

5. Créez un rôle IAM :

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

6. Associez votre nouvelle politique IAM au rôle :

   aws iam attach-role-policy \
     --policy-arn arn:aws:iam::<AWS_ACCOUNT_ID>:policy/AmazonEKS_EFS_CSI_Driver_Policy \
     --role-name AmazonEKS_EFS_CSI_DriverRole

7. Enregistrez le contenu suivant dans un fichier nommé efs-service-account.yaml.

   ---
   apiVersion: v1
   kind: ServiceAccount
   metadata:
     labels:
       app.kubernetes.io/name: aws-efs-csi-driver
     name: efs-csi-controller-sa
     namespace: kube-system
     annotations:
       eks.amazonaws.com/role-arn: arn:aws:iam::<AWS_ACCOUNT_ID>:role/AmazonEKS_EFS_CSI_DriverRole

8. Créez le compte de service Kubernetes sur votre cluster. Le compte de service Kubernetes nommé efs-csi-controller-sa est annoté avec le rôle IAM que vous avez créé.

   kubectl apply -f efs-service-account.yaml

9. Installez le pilote à l’aide d’images stockées dans le registre public Amazon ECR en téléchargeant le manifeste :

   kubectl kustomize "github.com/kubernetes-sigs/aws-efs-csi-driver/deploy/kubernetes/overlays/stable/?ref=release-1.5" > public-ecr-driver.yaml

   Remarque : vous pouvez installer le pilote CSI EFS à l’aide de Helm et de Kustomize avec AWS Private ou Public Registry. Pour plus d’informations, consultez la documentation du pilote CSI Amazon EFS.

   Modifiez ensuite le fichier public-ecr-driver.yaml pour supprimer le manifeste efs-csi-controller-sa :

   apiVersion: v1
   kind: ServiceAccount
   metadata:
     labels:
       app.kubernetes.io/name: aws-efs-csi-driver
     name: efs-csi-controller-sa
     namespace: kube-system

Déployer le pilote CSI Amazon EFS

Le pilote CSI Amazon EFS permet à plusieurs pods d’écrire simultanément sur un volume grâce au mode ReadWriteMany.

1. Pour déployer le pilote CSI Amazon EFS, appliquez le manifeste :

   kubectl apply -f public-ecr-driver.yaml

2. si votre cluster ne contient que des pods AWS Fargate (sans nœuds), déployez le pilote à l’aide de la commande suivante (toutes les régions) :

   kubectl apply -f https://raw.githubusercontent.com/kubernetes-sigs/aws-efs-csi-driver/master/deploy/kubernetes/base/csidriver.yaml

Créer un système de fichiers Amazon EFS

1. Obtenir l’ID du VPC de votre cluster Amazon EKS :

   aws eks describe-cluster --name your_cluster_name --query "cluster.resourcesVpcConfig.vpcId" --output text

   Remarque : à l’étape 3, remplacez your_cluster_name par le nom de votre cluster.

2. Obtenir la plage d’adresses CIDR de votre cluster VPC :

   aws ec2 describe-vpcs --vpc-ids YOUR_VPC_ID --query "Vpcs[].CidrBlock" --output text

   Remarque : à l’étape 4, remplacez la YOUR_VPC_ID par l’ID du VPC de l’étape 3 de la section précédente.

3. Créez un groupe de sécurité qui autorise le trafic entrant du système de fichiers réseau (NFS) de vos points de montage Amazon EFS :

   aws ec2 create-security-group --description efs-test-sg --group-name efs-sg --vpc-id YOUR_VPC_ID

   Remarque : remplacez YOUR_VPC_ID par le résultat de l’étape 3 de la section précédente. Enregistrez l’identifiant GroupId pour une utilisation ultérieure.

4. Ajoutez une règle entrante NFS afin de favoriser la communication entre les ressources de votre VPC et votre système de fichiers Amazon EFS :

   aws ec2 authorize-security-group-ingress --group-id sg-xxx --protocol tcp --port 2049 --cidr YOUR_VPC_CIDR

   Remarque : remplacez YOUR_VPC_CIDR par le résultat de l’étape 4 de la section précédente. Remplacez sg-xxx par l’ID du groupe de sécurité indiqué à l’étape 5 de la section précédente.

5. Créez un système de fichiers Amazon EFS pour votre cluster Amazon EKS :

   aws efs create-file-system --creation-token eks-efs

   Remarque : enregistrez le FileSystemId pour une utilisation ultérieure.

6. Pour créer une cible de montage pour Amazon EFS, exécutez la commande suivante :

   aws efs create-mount-target --file-system-id FileSystemId --subnet-id SubnetID --security-group sg-xxx

   Important : veillez à exécuter la commande pour toutes les zones de disponibilité avec l’identifiant SubnetID dans la zone de disponibilité où se trouvent vos composants master. Remplacez FileSystemId par le résultat de l’étape 7 de la section précédente (où vous avez créé le système de fichiers Amazon EFS). Remplacez sg-xxx par le résultat de l’étape 5 précédente (où vous avez créé le groupe de sécurité). Remplacez SubnetID par le sous-réseau utilisé par vos composants masters. Pour créer des cibles de montage dans plusieurs sous-réseaux, vous devez exécuter la commande à l’étape 8 séparément pour chaque ID de sous-réseau. Il est recommandé de créer une cible de montage dans chaque zone de disponibilité où s’exécutent vos composants master.

   Remarque : vous pouvez créer des cibles de montage pour toutes les zones de disponibilité où les composants master sont lancés. Ensuite, toutes les instances Amazon Elastic Compute Cloud (Amazon EC2) de la zone de disponibilité avec la cible de montage peuvent utiliser le système de fichiers.

Le système de fichiers Amazon EFS et ses cibles de montage sont désormais en cours d’exécution et prêts à être utilisés par les pods du cluster.

Tester le pilote CSI Amazon EFS

Vous pouvez tester le pilote CSI Amazon EFS en déployant deux pods qui écrivent dans le même fichier.

1. Clonez le référentiel aws-efs-csi-driver à partir d’AWS GitHub :

   git clone https://github.com/kubernetes-sigs/aws-efs-csi-driver.git

2. Remplacez votre répertoire de travail par le dossier contenant les fichiers de test du pilote CSI Amazon EFS :

   cd aws-efs-csi-driver/examples/kubernetes/multiple_pods/

3. Récupérez l’ID de votre système de fichiers Amazon EFS créé précédemment :

   aws efs describe-file-systems --query "FileSystems[*].FileSystemId" --output text

   Remarque : si la commande de l’étape 3 renvoie plusieurs résultats, vous pouvez utiliser l’ID du système de fichiers Amazon EFS que vous avez enregistré précédemment.

4. Dans le fichier specs/pv.yaml, remplacez la valeur spec.csi.volumeHandle par votre identifiant FileSystemId Amazon EFS des étapes précédentes.

5. Créez les ressources Kubernetes requises pour effectuer les tests :

   kubectl apply -f specs/

   Remarque : la commande kubectl de l’étape 5 précédente crée une classe de stockage Amazon EFS, une PVC, un volume persistant et deux pods (app1 et app2).

6. Répertoriez les volumes persistants dans l’espace de noms par défaut, puis recherchez un volume persistant au moyen de la demande default/efs-claim :

   kubectl get pv efs-pv

7. Décrivez le volume persistant :

   kubectl describe pv efs-pv

8. Vérifiez si les deux pods écrivent des données dans le fichier :

   kubectl exec -it app1 -- tail /data/out1.txt  
   kubectl exec -it app2 -- tail /data/out1.txt

   Patientez environ une minute. Le résultat indique la date actuelle écrite dans /data/out1.txt par les deux pods.

   Informations connexes

   Résolution des problèmes liés à Amazon EFS