Como faço para instalar o driver CSI do Amazon S3 nos meus clusters do Amazon EKS?

Resolução

Observação: se você receber erros ao executar comandos da AWS Command Line Interface (AWS CLI), consulte Solução de problemas da AWS CLI. Além disso, verifique se você está usando a versão mais recente da AWS CLI.

Pré-requisitos:

• Instale as ferramentas de linha de comando kubectl e eksctl.
• Crie um provedor do AWS Identity and Access Management (IAM) OpenID Connect (OIDC) para seu cluster.
• Use perfis do IAM para contas de serviço (IRSA) porque não é possível usar o Identidade de Pods do EKS com o driver CSI Amazon S3.

Para obter seu ID de emissor do OIDC, execute o seguinte comando describe-cluster da AWS CLI:

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

Observação: substitua your-cluster-name pelo nome do seu cluster do Amazon EKS.

Para verificar se você configurou um provedor IAM OIDC, execute o seguinte comando list-open-id-connect-providers:

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

Observação: substitua YOUR_OIDC_ID pelo seu ID OIDC. Se a saída estiver vazia, você deverá criar um provedor IAM OIDC.

Para criar o provedor OIDC do IAM, execute o seguinte comando:

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

Observação: substitua your_cluster_name pelo nome do seu cluster.

Implante o driver CSI do Amazon S3

Conclua as etapas a seguir:

1. Crie uma política do IAM com base em seus requisitos.
   Política de bucket de uso geral:

   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

   Observação: substitua your_bucket_name pelo nome do seu bucket.
   Política de bucket de diretório:

   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

   Observação: substitua YOUR_AWS_REGION pela sua região da AWS, YOUR_AWS_ACCOUNT_ID pela sua conta da AWS, your_bucket_name pelo nome do seu bucket e az_id pela sua zona de disponibilidade.
2. Execute o seguinte comando create-policy para criar uma política do IAM chamada AmazonS3CSIDriverPolicy:

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

   Observação: substitua iam-policy.json pelo seu arquivo JSON de política do IAM.
3. Crie a seguinte política de confiança do 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

   Observação: substitua YOUR_AWS_ACCOUNT_ID pela sua conta, YOUR_AWS_REGION pela sua Região e YOUR_OIDC_ID pelo seu ID do OIDC.
4. Execute o seguinte comando create-role para criar um perfil do IAM chamado AmazonEKS_S3_CSI_DriverRole:

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

   Observação: substitua trust-policy.json pelo arquivo JSON da política de confiança do IAM.
5. Execute o seguinte comando attach-role-policy para anexar a política ao perfil do IAM:

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

   Observação: substitua YOUR_AWS_ACCOUNT_ID pelo ID da sua conta da AWS.
6. Execute o seguinte comando create-addon para implantar o driver CSI do Amazon S3 em seu 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

   Observação: substitua your_cluster_name pelo nome do seu cluster e YOUR_AWS_ACCOUNT_ID pelo ID da sua conta. Para instalar o driver CSI do Amazon S3 com o Kustomize ou o Helm, consulte Instalação no site do GitHub.

Para permitir que os usuários substituam arquivos existentes, adicione a sinalização \ --allow-overwrite ao volume persistente. Você deve adicionar todas as gravações sequencialmente desde o início do arquivo. Não é possível acrescentar arquivos. Em vez disso, você deve substituir o conteúdo existente por um novo conteúdo. No entanto, para buckets de diretório na classe de armazenamento Amazon S3 Express One Zone, é possível acrescentar arquivos existentes. Para fazer isso, adicione o sinalizador \ --incremental-upload ao volume persistente. Além disso, comece do final do arquivo para adicionar sequencialmente todas as gravações. Para obter mais informações, consulte Ler e gravar arquivos e Configurar no site do GitHub.

O ponto de montagem do driver CSI Amazon S3 usa somente provisionamento estático. Não é possível usar o provisionamento dinâmico nem criar novos buckets. Os volumes que você monta no ponto de montagem não podem usar todos os atributos do sistema de arquivos POSIX. Para obter mais informações, consulte o comportamento do sistema de arquivos Mountpoint para Amazon S3 no site do GitHub. Se suas aplicações exigirem sistemas de arquivos completos, é uma prática recomendada usar o Amazon Elastic File System (Amazon EFS) ou o Amazon FSx.

Teste o driver CSI do Amazon S3

Para testar o driver CSI do Amazon S3, implante uma aplicação de amostra que usa provisionamento estático para os pods. Para ver etapas e exemplos, consulte exemplo de provisionamento estático no site do GitHub.

Solucionar problemas com o driver CSI do Amazon S3

Seu driver CSI do Amazon S3 não está funcionando conforme o esperado

Para verificar se os pods do nó do driver CSI do Amazon S3 estão em execução, execute o seguinte comando:

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

Para revisar os logs dos pods do driver CSI do Amazon S3, execute o seguinte comando:

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

Certifique-se de que o bucket do Amazon S3 esteja na mesma região do cluster Amazon EKS. Se o bucket e o cluster estiverem em regiões diferentes, atualize as mountOptions para incluir a Região.

Exemplo de configuração:

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

Se o driver CSI do Amazon S3 não funcionar em imagens de máquina da Amazon (AMIs) do Bottlerocket, execute o seguinte comando para verificar a versão da imagem do contêiner:

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

Na saída do comando, certifique-se de que a versão da imagem do contêiner seja maior ou igual à v1.4.0. É uma prática recomendada usar a versão mais recente do driver CSI do Amazon S3. Para a versão mais recente, consulte os lançamentos do mountpoint-s3-csi-driver no site do GitHub.

Os usuários em seu contêiner não podem acessar o bucket do Amazon S3

Por padrão, somente o usuário que montou o bucket do S3 pode acessar seu diretório montado. Isso ocorre mesmo quando você define as configurações de permissões e propriedade para permitir que outros usuários no contêiner acessem o bucket.

Para permitir que outros usuários que não sejam o usuário-raiz acessem seu diretório montado, atualize as mountOptions para incluir a opção --allow-other. Para permitir que o usuário-raiz acesse seu diretório montado como um usuário diferente, use --allow-root.

Exemplo 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

Você recebe o erro “Volume capability not supported”

Ao usar o driver CSI do Amazon S3, você pode receber uma mensagem de erro semelhante ao exemplo a seguir:

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

Você recebe o erro anterior ao usar um modo de acesso que o driver CSI do Amazon S3 não suporta, como ReadWriteOncePod ou ReadWriteOnce. É possível usar somente os modos de acesso ReadWriteMany ou ReadOnlyMany.