Como soluciono problemas com minhas montagens de volume do Amazon EFS no Amazon EKS?
Quero montar volumes do Amazon Elastic Block Store (Amazon EBS) no meu cluster do Amazon Elastic Kubernetes Service (Amazon EKS). No entanto, recebo o erro "Timeout expired waiting for volumes to attach or mount for pod".
Resolução
Pré-requisitos:
- Defina as permissões necessárias do AWS Identity and Access Management (AWS IAM) na conta de serviço ebs-csi-controller-sa na sua política do IAM.
- Verifique se você tem um PersistentVolumeClaim (PVC) válido no mesmo namespace do seu pod. Para ver um exemplo de arquivo PVC, consulte claim.yaml no site do GitHub.
- Certifique-se de ter uma definição de classe de armazenamento do Amazon EBS válida que use o provisionador ebs.csi.aws.com do driver Container Storage Interface (CSI) do Amazon EBS. Para obter mais informações, consulte Amazon EBS no site do Kubernetes.
Verifique se o controlador do driver CSI do Amazon EBS e os pods de nós estão em execução
O driver CSI do Amazon EBS consiste em pods de controlador que são executados como uma implantação e pods de nós que são executados como um conjunto de daemon. Para verificar se seu cluster executa esses pods, execute o seguinte comando:
kubectl get all -l app.kubernetes.io/name=aws-ebs-csi-driver -n kube-system
Observação: os nós de processamento do Windows e o AWS Fargate não oferecem suporte ao driver CSI do Amazon EBS.
Certifique-se de que a versão do driver CSI do Amazon EBS instalada é compatível com a versão do Kubernetes do seu cluster. Para obter mais informações, consulte Amazon EBS CSI driver (Driver CSI do Amazon EBS) no site do GitHub.
Se seu cluster não executar esses pods, adquira o driver CSI do Amazon EBS.
Verifique se há problemas de PVC
Para verificar se o PVC encontra problemas, execute o comando a seguir para visualizar os eventos:
kubectl describe pvc PVC_NAME -n NAMESPACE
Observação: substitua PVC_NAME pelo nome do seu PVC e NAMESPACE pelo seu namespace.
Se você usa o provisionamento dinâmico de volume, analise a saída retornada dos eventos para saber se o provisionamento de volume foi bem-sucedido ou falhou. Também é possível ver o nome do volume persistente vinculado ao PVC.
Exemplo de saída:
Name: ebs-claimNamespace: default StorageClass: ebs-sc Status: Bound Volume: pvc-12345678-1234-1234-1234-123456789abc Annotations: pv.kubernetes.io/bind-completed: yes pv.kubernetes.io/bound-by-controller: yes volume.beta.kubernetes.io/storage-provisioner: ebs.csi.aws.com volume.kubernetes.io/selected-node: ip-10-0-2-57.ec2.internal . . . . . . . . . . Events: Type Reason Age From Message ---- ------ ---- ---- ------- . . . . . Normal Provisioning 5m22s ebs.csi.aws.com_ebs-csi-controller-5a6b7c8d9e-f1g2h_12345678-1234-1234-1234-123456789abc External provisioner is provisioning volume for claim "default/ebs-claim" Normal ProvisioningSucceeded 5m18s ebs.csi.aws.com_ebs-csi-controller-5a6b7c8d9e-f1g2h_12345678-1234-1234-1234-123456789abc Successfully provisioned volume pvc-12345678-1234-1234-1234-123456789abc
Analise os logs dos pods do controlador do CSI do Amazon EBS
Se o volume falhar durante a criação, consulte os logs de ebs-plugin e csi-provisioner.
Para recuperar o log de contêiner de ebs-plugin, execute os seguintes comandos:
kubectl logs deployment/ebs-csi-controller -n kube-system -c ebs-plugin kubectl logs daemonset/ebs-csi-node -n kube-system -c ebs-plugin
Para recuperar o log de contêiner de csi-provisioner, execute o seguinte comando:
kubectl logs deployment/ebs-csi-controller -n kube-system -c csi-provisioner
Se os volumes do Amazon EBS falharem ao serem anexados ao pod, analise os logs de csi-attacher. Para recuperar os logs do contêiner de csi-attacher, execute o seguinte comando:
kubectl logs deployment/ebs-csi-controller -n kube-system -c csi-attacher
Procure informações nos logs que possam ajudá-lo a solucionar o erro. Para obter mais informações, consulte AWSSupport-TroubleshootEbsCsiDriversForEks.
Verifique as permissões do IAM para o controlador do CSI do Amazon EBS
Observação: para aumentar a eficiência de depuração do driver CSI do Amazon EBS, defina aws-sdk-debug-log como true (verdadeiro). Para obter mais informações, consulte Driver options (Opções de driver) no site do GitHub.
Os seguintes problemas resultam em erros unauthorized em seus eventos de PVC ou em seus logs de ebs-csi-controller:
- Permissões ausentes no perfil do IAM
- Um perfil do IAM incorreto que está associado à conta de serviço
Para resolver esses problemas, anote a conta de serviço do controlador do driver CSI do Amazon EBS com o perfil e permissões corretos do IAM. Para verificar o perfil e as permissões do IAM da conta de serviço, conclua as etapas a seguir:
-
Para saber se a conta de serviço do pod ebs-csi-controller tem a anotação correta, execute o seguinte comando:
kubectl get sa ebs-csi-controller-sa -n kube-system -o jsonpath='{.metadata.annotations}'Observação: os perfis do IAM para contas de serviço (IAM roles for service accounts, IRSA) usam a anotação para vincular o perfil do IAM à conta de serviço.
-
Na saída do comando, verifique se a seguinte anotação está presente:
eks.amazonaws.com/role-arn: arn:aws:iam::111122223333:role/AmazonEKS_EBS_CSI_DriverRole -
Verifique se você criou o provedor IAM OpenID Connect (OIDC) no seu cluster.
-
Verifique se o perfil do IAM tem permissões para realizar chamadas de API do Amazon EBS. Certifique-se de que a política de confiança do perfil do IAM confia na conta de serviço ebs-csi-controller-sa.
-
Verifique se o AWS CloudTrail faz as chamadas para CreateVolume, AttachVolume e DetachVolume. Para descobrir se o perfil do IAM da conta de serviço do controlador ou o perfil do IAM do nó de processamento está fazendo as chamadas de API, analise os logs do CloudTrail. Os logs mostram qual identidade do IAM está executando as ações.
Resolva erros de programação e anexação de volumes
Cada volume persistente tem uma afinidade de nó que limita a anexação de volumes persistentes aos nós em uma única Zona de disponibilidade. Isso ocorre porque é possível anexar volumes do Amazon EBS somente a pods ou nós executados na mesma Zona de disponibilidade em que você os criou. Se os pods programados para nós em uma Zona de disponibilidade usarem o volume persistente do Amazon EBS em outra Zona de disponibilidade, você receberá este erro:
"FailedScheduling: 1 node(s) had volume node affinity conflict"
Para solucionar esse erro, use StatefulSets em vez de uma implantação. Isso cria um volume do Amazon EBS exclusivo para cada pod do StatefulSets na mesma Zona de disponibilidade do pod. Para obter mais informações, consulte StatefulSets no site do Kubernetes.
Importante: não é possível montar um volume do Amazon EBS em dois pods diferentes que são executados em dois nós de processamento diferentes. É possível anexar o volume do Amazon EBS aos pods que são executados em um nó, mas não é possível anexá-lo a outro nó ao mesmo tempo.
Para verificar a afinidade de nós do volume persistente, execute o comando a seguir:
kubectl describe pv PERSISTENT_VOLUME_NAME
Observação: substitua PERSISTENT_VOLUME_NAME pelo nome do seu volume persistente.
Se você tentar anexar seu volume do Amazon EBS a dois pods em nós de processamento diferentes e o pod falhar, você pode receber a seguinte mensagem de erro:
"Warning FailedAttachVolume 2m38s attachdetach-controller Multi-Attach error for volume "pvc-1cccsdfdc8-fsdf6-43d6-a1a9-ea837hf7h57fa" Volume is already exclusively attached to one node and can't be attached to another"
Para resolver esse erro, verifique se somente um pod por vez usa um volume persistente apoiado pelo Amazon EBS em um único nó. Os volumes do Amazon EBS são compatíveis somente com o modo de acesso ReadWriteOnce (RWO). Isso significa que só é possível anexar o volume a um nó por vez.
Verifique se seus pods de controlador do Amazon EBS podem se conectar à API do Amazon EC2
Se você obtiver erros de tempo limite de conexão nos logs de ebs-csi-controller, o controlador do CSI do Amazon EBS pode não estar conectado à API do Amazon Elastic Compute Cloud (Amazon EC2). Se os pods do controlador tiverem problemas de conectividade ao criar seu PVC, você pode receber a seguinte mensagem de erro:
"Warning ProvisioningFailed persistentvolumeclaim/storage-volume-1 failed to provision volume with StorageClass "ebs-sc": rpc error: code = DeadlineExceeded desc = context deadline exceeded"
Para resolver esse erro, verifique se as sub-redes dos pods de controlador do Amazon EBS podem se conectar à API do Amazon EC2. Se você executa um cluster privado com um proxy HTTP/HTTPS, verifique se os pods do controlador do CSI do Amazon EBS podem usar o proxy HTTP/HTTPS. A instalação do Helm do driver CSI do Amazon EBS é compatível com a configuração de um proxy HTTP/HTTPS. Para obter mais informações, consulte values.yaml no site do GitHub.
A mensagem de erro anterior também pode estar relacionada a um problema com o OIDC. Para solucionar problemas de OIDC, consulte Como solucionar problemas de um provedor de OIDC e IRSA no Amazon EKS?
Ative a criptografia do Amazon EBS
Certifique-se de que parameters.encrypted esteja definido como true (verdadeiro) no manifesto da classe de armazenamento. Para verificar a configuração, execute o seguinte comando:
kubectl describe sc STORAGE_CLASS_NAME
Observação: substitua STORAGE_CLASS_NAME pelo nome da sua classe de armazenamento.
É possível manter a chave gerenciada pela AWS no AWS Key Management Service (AWS KMS) com o alias aws/ebs criado em seu nome como a chave de criptografia padrão. Ou é possível escolher uma chave de criptografia simétrica gerenciada pelo cliente. Para obter mais informações, consulte Habilitar a criptografia do Amazon EBS por padrão.
O driver CSI do Amazon EBS exige acesso às chaves gerenciadas pelo cliente que criptografam ou descriptografam o volume. Caso contrário, a criação do volume expira e não é possível criar nem gerenciar volumes criptografados do Amazon EBS.
Para resolver esse problema, certifique-se de que o perfil do IAM do controlador do CSI do Amazon EBS tem as permissões do exemplo a seguir:
{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "kms:CreateGrant", "kms:ListGrants", "kms:RevokeGrant" ], "Resource": ["custom-key-arn"], "Condition": { "Bool": { "kms:GrantIsForAWSResource": "true" } } }, { "Effect": "Allow", "Action": [ "kms:Encrypt", "kms:Decrypt", "kms:ReEncrypt*", "kms:GenerateDataKey*", "kms:DescribeKey" ], "Resource": ["custom-key-arn"] } ] }
Defina a política de chave do AWS KMS para permitir explicitamente que o perfil do IAM do controlador do CSI do Amazon EBS acesse a chave do AWS KMS. Para obter mais informações, consulte Política de AWS KMS chaves necessária para uso com volumes criptografados.
- Tópicos
- Containers
- Idioma
- Português
Vídeos relacionados


This article was reviewed and updated on 2026-03-23.
Conteúdo relevante
feita há um ano
AWS OFICIALAtualizada há um ano