Amazon EKS에 Amazon EFS 볼륨을 장착하는 문제를 해결하려면 어떻게 해야 하나요?

해결 방법

문제 해결을 시작하기 전에 다음 사전 요구 사항이 충족되는지 확인하세요.

• ebs-csi-controller-sa service account IAM 역할에 필요한 AWS Identity and Access Management(IAM) 권한.
  **참고:**사용자의 서비스 계정 관련 문제를 해결하려면, Amazon EBS CSI 드라이버 컨트롤러 서비스 계정의 IAM 역할 및 역할 권한 확인 섹션을 참조하세요.
• 포드와 같은 명칭 공간에 있는 유효한PersistentVolumeClaim (PVC)(GitHub 웹 사이트에서 설정).
• 인트리 권한 설정자kubernetes.io/aws-ebs(Kubernetes 웹 사이트에서 설정)를 사용하는 유효한 EBS 기억 영역 클래스 정의. 또는 EBS Container Storage Interface(CSI) 드라이버 권한 설정자ebs.csi.aws.com(GitHub 웹 사이트에서 설정)을 사용하는 기억 영역 클래스 정의도 있습니다.

Amazon EBS CSI 드라이버 컨트롤러 및 노드 포드가 실행 중인지 확인

EBS CSI 드라이버는 배포로 실행되는 컨트롤러 포드와 대몬(daemon) 세트로 실행되는 노드 포드로 구성됩니다. 사용자의 클러스터에서 이러한 포드가 실행되는지 확인하려면, 다음 명령을 실행합니다.

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

**참고:**Windows 작업자 노드와 AWS Fargate는 EBS CSI 드라이버를 지원하지 않습니다.

설치된EBS CSI 드라이버 버전이 사용자 클러스터의 Kubernetes 버전(GitHub 웹 사이트에서 설정)과 호환되는지 확인하세요.

PVC가 EBS 영구 볼륨에 바인딩할 때 문제가 발생했는지 확인

PVC에서 문제가 발생했는지 확인하려면, 다음 명령을 실행하여 이벤트를 확인하세요. 다음 예제 명령에서 PVC\ _NAME과 NAMESPACE를 사용자의 환경에 맞는 정확한 값으로 바꾸세요.

kubectl describe pvc PVC_NAME -n NAMESPACE

동적 볼륨 권한 설정을 사용하는 경우, 반환된 이벤트를 검토하여 볼륨 권한 설정의 성공 또는 실패 여부를 확인하세요. 다음 예와 같이, PVC가 바인딩 되는 해당 영구 볼륨 이름도 볼 수 있습니다.

Name:          ebs-claim
Namespace:     default
StorageClass:  ebs-sc
Status:        Bound
Volume:        pvc-5cbd76de-6f15-41e4-9948-2bba2574e205
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-57d4cbb9cc-dr9cd_8f0373e8-4e58-4dd0-b83c-da6f9ad5d5ce  External provisioner is provisioning volume for claim "default/ebs-claim"
  Normal  ProvisioningSucceeded  5m18s                  ebs.csi.aws.com_ebs-csi-controller-57d4cbb9cc-dr9cd_8f0373e8-4e58-4dd0-b83c-da6f9ad5d5ce  Successfully provisioned volume pvc-5cbd76de-6f15-41e4-9948-2bba2574e205

권한 설정이 실패한 경우, 이벤트에서 오류 메시지를 확인하세요.

Amazon EBS CSI 컨트롤러 포드의 로그를 검토하세요

장착 실패의 원인을 확인하려면, 컨트롤러 포드 로그를 확인합니다. 볼륨이 생성 중에 실패하면,ebs-plugin과 csi-provisioner 로그를 참조하세요. efs-plugin 컨테이너 로그를 검색하려면, 다음 명령을 실행합니다.

kubectl logs deployment/ebs-csi-controller -n kube-system -c ebs-plugin

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

csi-provisioner 컨테이너 로그를 검색하려면, 다음 명령을 실행합니다.

kubectl logs deployment/ebs-csi-controller -n kube-system -c csi-provisioner

EBS 볼륨이 포드에 연결되지 않는 경우, csi-attacher 로그를 검토하세요. csi-attacher 컨테이너 로그를 검색하려면, 다음 명령을 실행합니다.

kubectl logs deployment/ebs-csi-controller -n kube-system -c csi-attacher

Amazon EBS CSI 드라이버 컨트롤러 서비스 계정의 IAM 역할 및 역할의 권한을 확인하세요

**참고:**EBS CSI 드라이버의 디버깅 효율성을 높이려면, 디버그 로그 옵션(GitHub 웹 사이트에서 설정)을 설정하세요.

EBS CSI 드라이버 컨트롤러 서비스 계정에 올바른 IAM 역할이 연결되었는지 확인하세요. 또한 IAM 역할에 필요한 권한이 있는지 확인하세요.

다음과 같은 문제로 인해 사용자의 PVC 이벤트 또는ebs-csi-controller 로그에 unauthorized 오류가 발생합니다.

• IAM 역할에 권한이 없음.
• 잘못된 IAM 역할이 서비스 계정과 연결됨.

1.    ebs-csi-controller 포드의 서비스 계정에 올바른 주석이 있는지 확인하려면, 다음 명령을 실행합니다.

kubectl describe sa ebs-csi-controller-sa -n kube-system

2.    다음 주석이 존재하는지 확인합니다.

eks.amazonaws.com/role-arn: arn:aws:iam::111122223333:role/AmazonEKS_EBS_CSI_DriverRole

3.    클러스터용 IAM OpenID Connect(OIDC) 공급자를 생성했는지 확인하세요. 또한 IAM 역할에 EBS API 호출을 수행하는 데 필요한 권한이 있는지 확인하세요. IAM 역할의 신뢰 정책이 서비스 계정 ebs-csi-controller-sa를 신뢰하는지 확인하세요.

3.    AWS CloudTrail에서 CreateVolume, AttachVolume 및DetachVolume 호출을 수행하는지 확인합니다. 이 작업을 수행하려면, CloudTrail 로그를 검토하세요. 또한 로그를 검토하여 호출을 수행하는 주체를 확인하세요. 이렇게 하면 컨트롤러나 작업자 노드 IAM 역할이 서비스 계정 IAM 역할을 사용하는지 확인할 수 있습니다.

영구 볼륨의 노드 관련성 확인

각 영구 볼륨에는 영구 볼륨의 연결을 단일 가용성 영역 내의 노드에 제한하는 노드 관련성이 있습니다. 이는 EBS 볼륨을 생성한 같은 가용성 영역에서 실행되는 포드 또는 노드에만 사용자가 EBS 볼륨을 연결할 수 있기 때문입니다. 한 가용성 영역의 노드에 대해 예정된 포드가 다른 가용성 영역의 EBS 영구 볼륨을 사용하는 경우, 다음 오류가 발생합니다.

"FailedScheduling: 1 node(s) had volume node affinity conflict"

이를 방지하려면, 배치 대신StatefulSets(Kubernetes 웹 사이트에서 설정)를 사용하세요. 이렇게 하면 포드와 같은 가용성 영역에 있는 StatefulSets의 각 포드에 대해 고유한 EBS 볼륨을 생성할 수 있습니다.

영구 볼륨의 노드 관련성을 확인하려면, 다음 명령을 실행합니다. PERSISTENT_VOLUME_NAME을 사용자의 볼륨 이름으로 바꾸세요.

kubectl describe pv PERSISTENT_VOLUME_NAME

**참고:**두 개의 서로 다른 작업자 노드에서 실행되는 두 개의 다른 포드에 EBS 볼륨을 장착할 수 없습니다. EBS 볼륨을 한 노드에서 실행되는 포드에는 연결할 수 있지만, 동시에 다른 노드에 연결할 수는 없습니다. EBS 볼륨을 서로 다른 작업자 노드에 있는 두 개의 포드에 연결하려고 하면, 포드가 실패하고 다음 오류가 발생합니다.

"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"

사용자의 EBS 컨트롤러 포드가 Amazon Elastic Compute Cloud(Amazon EC2) API에 연결되어 있는지 확인

ebs-csi-controller 로그에 연결 타임아웃 오류가 표시되는 경우, EBS CSI 컨트롤러는 Amazon EC2 API에 연결되지 않았을 수 있습니다. 사용자의 PVC를 생성할 때 컨트롤러 포드에 연결 문제가 있으면, 다음 오류가 표시됩니다.

"Warning ProvisioningFailed persistentvolumeclaim/storage-volume-1 failed to provision volume with StorageClass "ebs-sc": rpc error: code = DeadlineExceeded desc = context deadline exceeded"

이 오류를 해결하려면, EBS 컨트롤러 포드의 서브넷이 EC2 API에 연결되어 있는지 확인하세요. HTTP/HTTPS 프록시를 사용하여 사설 클러스터를실행하는 경우, EBS CSI 컨트롤러 포드가 HTTP/HTTPS 프록시를 사용할 수 있는지 확인하세요. EBS CSI 드라이버의 헬름 설치는 HTTP/HTTPS 프록시의 설정을 지원(Kubernetes 웹 사이트에서 설정)합니다.

이 메시지는 OIDC와 관련된 문제일 수도 있습니다. OIDC 문제를 해결하려면, Amazon EKS에서 OIDC 공급자와 IRSA의 문제를 해결하려면 어떻게 해야 합니까?를 참조하세요.