¿Cómo instalo el controlador de CSI de Amazon S3 en mis clústeres de Amazon EKS?

Solución

Nota: Si se muestran errores al ejecutar comandos de la Interfaz de la línea de comandos de AWS (AWS CLI), consulta Solución de problemas de AWS CLI. Además, asegúrate de utilizar la versión más reciente de la AWS CLI.

Requisitos previos:

• Instala las herramientas de la línea de comandos kubectl y eksctl.
• Crea un proveedor de OpenID Connect (OIDC) de AWS Identity and Access Management (IAM) para tu clúster.
• Usa los roles de IAM para las cuentas de servicio (IRSA) porque no puedes usar Pod Identity de EKS con el controlador de CSI de Amazon S3.

Para obtener tu ID de emisor de OIDC, ejecuta el siguiente comando describe-cluster de la AWS CLI:

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

Nota: Sustituye your_cluster_name por el nombre de tu clúster de Amazon EKS.

Para comprobar si has configurado un proveedor de OIDC de IAM, ejecuta el siguiente comando list-open-id-connect-providers:

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

Nota: Sustituye YOUR_OIDC_ID por tu ID de OIDC. Si la salida está vacía, debes crear un proveedor de OIDC de IAM.

Para crear un proveedor de OIDC de IAM, ejecuta el siguiente comando:

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

Nota: Sustituye your_cluster_name por el nombre de tu clúster.

Despliegue del controlador de CSI de Amazon S3

Sigue estos pasos:

1. Crea una política de IAM en función de tus requisitos.
   Política de bucket de uso general:

   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

   Nota: Sustituye your-bucket-name por el nombre de tu bucket.
   Política de bucket de directorio:

   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

   Nota: Sustituye YOUR_AWS_REGION por tu región de AWS, YOUR_AWS_ACCOUNT_ID por tu cuenta de AWS, your_bucket_name por el nombre de tu bucket y az_id por tu zona de disponibilidad.
2. Ejecuta el siguiente comando create-policy para crear una política de IAM denominada AmazonS3CSIDriverPolicy:

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

   Nota: Sustituye iam-policy.json por el archivo JSON de tu política de IAM.
3. Crea la siguiente política de confianza de IAM:

   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

   Nota: Sustituye YOUR_AWS_ACCOUNT_ID por tu cuenta, YOUR_AWS_REGION por tu región y YOUR_OIDC_ID por tu ID de OIDC.
4. Ejecuta el siguiente comando create-role para crear un rol de IAM denominado AmazonEKS_S3_CSI_DriverRole:

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

   Nota: Sustituye trust-policy.json por el archivo JSON de la política de confianza de IAM.
5. Ejecuta el siguiente comando attach-role-policy para adjuntar la política al rol de IAM:

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

   Nota: Sustituye YOUR_AWS_ACCOUNT_ID por el ID de tu cuenta de AWS.
6. Ejecuta el siguiente comando create-addon para desplegar el controlador de CSI de Amazon S3 en tu clúster:

   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

   Nota: Sustituye your_cluster_name por el nombre del clúster y YOUR_AWS_ACCOUNT_ID por el ID de tu cuenta. Para instalar el controlador de CSI de Amazon S3 con Kustomize o Helm, consulta Instalación en el sitio web de GitHub.

Para permitir a los usuarios sobrescribir los archivos existentes, agrega el indicador --allow-overwrite al volumen persistente. Debes agregar todas las escrituras de forma secuencial desde el principio del archivo. No puedes anexar archivos. En su lugar, debes sustituir el contenido existente por contenido nuevo. Sin embargo, en el caso de los buckets de directorio de la clase de almacenamiento Amazon S3 Express One Zone, puedes anexar los archivos existentes. Para ello, agrega el indicador --incremental-upload al volumen persistente. Además, comienza desde el final del archivo para agregar secuencialmente todas las escrituras. Para obtener más información, consulta Lectura y escritura de archivos y Configuración en el sitio web de GitHub.

El punto de montaje del controlador de CSI de Amazon S3 solo usa aprovisionamiento estático. No puedes usar el aprovisionamiento dinámico ni crear buckets nuevos. Los volúmenes que se montan en el punto de montaje no pueden utilizar todas las características del sistema de archivos POSIX. Para obtener más información, consulta el comportamiento del sistema de archivos Mountpoint para Amazon S3 en el sitio web de GitHub. Si tus aplicaciones requieren sistemas de archivos completos, se recomienda utilizar Amazon Elastic File System (Amazon EFS) o Amazon FSx.

Prueba del controlador de CSI de Amazon S3

Para probar el controlador de CSI de Amazon S3, despliega una aplicación de muestra que utilice el aprovisionamiento estático para los pods. Para ver pasos y ejemplos, consulta el ejemplo de aprovisionamiento estático en el sitio web de GitHub.

Solución de problemas con el controlador de CSI de Amazon S3

El controlador de CSI de Amazon S3 no funciona como se esperaba

Para comprobar que los pods del nodo del controlador de CSI de Amazon S3 se están ejecutando, ejecuta el siguiente comando:

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

Para revisar los registros de los pods del controlador de CSI de Amazon S3, ejecuta el siguiente comando:

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

Asegúrate de que el bucket de Amazon S3 esté en la misma región que el clúster de Amazon EKS. Si el bucket y el clúster se encuentran en regiones diferentes, actualiza mountOptions para incluir la región.

Configuración del ejemplo:

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 el controlador de CSI de Amazon S3 no funciona en imágenes de máquina de Amazon (AMI) de Bottlerocket, ejecuta el siguiente comando para comprobar la versión de la imagen del contenedor:

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

En el resultado del comando, asegúrate de que la versión de la imagen del contenedor sea superior o igual a la v1.4.0. Se recomienda utilizar la versión más reciente del controlador de CSI de Amazon S3. Para obtener la versión más reciente, consulta las versiones de mountpoint-s3-csi-driveren el sitio web de GitHub.

Los usuarios de tu contenedor no pueden acceder al bucket de Amazon S3

De forma predeterminada, solo el usuario que montó el bucket de S3 puede acceder al directorio montado. Esto ocurre incluso cuando configuras los permisos y los ajustes de propiedad para permitir que otros usuarios del contenedor accedan al bucket.

Para permitir que otros usuarios que no sean raíz accedan al directorio montado, actualiza mountOptions para incluir la opción --allow-other. Para permitir que el usuario raíz acceda al directorio montado como un usuario diferente, utiliza --allow-root.

Ejemplo de política:

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

Aparece el error «Volume capability not supported»

Al usar el controlador de CSI de Amazon S3, es posible que recibas un mensaje de error similar al del siguiente ejemplo:

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

Recibes el error anterior cuando utilizas un modo de acceso que el controlador de CSI de Amazon S3 no admite, como ReadWriteOncePod o ReadWriteOnce. Solo puedes usar los modos de acceso ReadWriteMany o ReadOnlyMany.