Amazon EKS에서 Amazon EFS 볼륨 탑재 관련 문제를 해결하려면 어떻게 해야 합니까?

해결 방법

사전 요구 사항:

• Amazon EFS 파일 시스템의 가용 영역에 대한 각 워커 노드 서브넷에 탑재 대상이 있는지 확인하십시오.
• Amazon EFS 스토리지 클래스 정의에 efs.csi.aws.com을 사용하는지 확인하십시오. 자세한 내용은 GitHub 웹 사이트에서 EFS 스토리지 클래스를 참조하십시오.
• PersistentVolumeClaim 및 PersistentVolume을 사용하는지 확인하십시오. 자세한 내용은 GitHub 웹 사이트의 PersistentVolumeClaim 및 PersistentVolume을 참조하십시오.
  참고: 동적 프로비저닝을 사용하는 경우 PersistentVolumeClaim 및 PersistentVolume을 사용할 필요가 없습니다. 자세한 내용은 GitHub 웹 사이트의 동적 프로비저닝을 참조하십시오.
• EKS 클러스터에 Amazon EFS CSI 드라이버 애드온을 설치했는지 확인하십시오.

EKS 워커 노드에서 Amazon EFS API로 네트워크를 올바르게 구성했는지 확인

EFS 워커 노드와 EFS 컨트롤러 포드에서 Amazon EFS API에 액세스할 수 있는지 확인하십시오.

Amazon EFS API에 도달하도록 네트워크를 구성하지 않으면 다음 오류 메시지 중 하나가 표시될 수 있습니다.

• "failed to provision volume with StorageClass "xxxx": rpc error: code = DeadlineExceeded desc = context deadline exceeded"
• "Could not start amazon-efs-mount-watchdog, unrecognized init system "bash" Mount attempt x/3 failed due to timeout after 15 sec"
• "Unable to attach or mount volumes: timed out waiting for the condition"

아웃바운드 인터넷 액세스가 없는 프라이빗 클러스터를 사용하는 경우 com.amazonaws.region.elasticfilesystem 가상 프라이빗 클라우드(VPC) 엔드포인트를 VPC에 포함해야 합니다. 워커 노드 및 포드 서브넷에서 포트 443으로 트래픽을 전송하도록 허용하는 VPC 엔드포인트의 보안 그룹에 대한 인바운드 규칙을 만듭니다. VPC 엔드포인트에 연결된 정책에 필요한 권한이 있는지 확인하십시오.

Amazon EFS 탑재 대상을 올바르게 구성했는지 확인

EKS 노드가 실행되는 각 가용 영역에 Amazon EFS 탑재 대상을 만들었는지 확인하십시오. 예를 들어 워커 노드를 us-east-1a 및 us-east-1b에 분산한 경우, 탑재하려는 EFS 파일 시스템의 두 가용 영역에 탑재 대상을 만드십시오.

탑재 대상을 올바르게 구성하지 않으면 다음과 같은 오류 메시지가 표시될 수 있습니다.

"Output: Failed to resolve "fs-xxxxxx.efs.us-east-1.amazonaws.com" - The file system mount target ip address cannot be found"

Amazon EFS 파일 시스템 및 워커 노드와 연결된 보안 그룹이 NFS 트래픽을 허용하는지 확인

보안 그룹이 트래픽을 허용하지 않는 경우 다음과 같은 오류 메시지를 받을 수 있습니다.

• "Could not start amazon-efs-mount-watchdog, unrecognized init system "bash" Mount attempt x/3 failed due to timeout after 15 sec"
• "failed to provision volume with StorageClass "xxxx": rpc error: code = DeadlineExceeded desc = context deadline exceeded"
• "Unable to attach or mount volumes: timed out waiting for the condition"

Amazon EFS 파일 시스템의 보안 그룹에는 클러스터 VPC에 대한 CIDR(Classless Inter-Domain Routing)의 네트워크 파일 시스템(NFS) 트래픽을 허용하는 인바운드 규칙이 있어야 합니다. 인바운드 트래픽에 포트 2049를 허용합니다.

포드가 EFS 볼륨을 탑재하지 못하는 워커 노드와 연결된 보안 그룹에는 아웃바운드 규칙이 있어야 합니다. 아웃바운드 규칙은 포트 2049에서 EFS 파일 시스템으로 전달되는 NFS 트래픽을 허용해야 합니다.

Amazon EFS 파일 시스템에서 하위 디렉터리 경로를 만들었는지 확인

영구 볼륨에 하위 디렉터리 경로를 추가하는 경우 Amazon EFS CSI 드라이버는 파일 시스템에 하위 디렉터리 경로를 만들지 않습니다. 탑재 작업이 성공하려면 파일 시스템에 하위 디렉터리가 이미 있어야 합니다. 하위 디렉터리가 파일 시스템에 없는 경우 다음과 같은 오류 메시지가 표시될 수 있습니다.

"Output: mount.nfs4: mounting fs-18xxxxxx.efs.us-east-1.amazonaws.com:/path-in-dir:/ failed, reason given by server: No such file or directory"

EFS 파일 시스템에 하위 디렉터리가 있는지 확인하려면 EC2 인스턴스에 EFS 파일 시스템을 탑재하고 콘텐츠를 나열합니다. 하위 디렉터리가 없는 경우 mkdir 명령을 사용하여 하위 디렉터리를 만드십시오.

클러스터의 VPC가 Amazon DNS 서버를 사용하는지 확인

Amazon EFS CSI 드라이버를 사용하여 EFS 볼륨을 탑재할 때는 VPC용 Amazon DNS 서버를 사용해야 합니다.

참고: Amazon이 제공한 DNS만 Amazon EFS 서비스의 파일 시스템 DNS를 확인할 수 있습니다.

DNS 서버를 확인하려면 워커 노드에 로그인한 후 다음 명령을 실행합니다.

nslookup fs-4fxxxxxx.efs.region.amazonaws.com AMAZON_PROVIDED_DNS_IP

참고: region을 AWS 리전으로 바꾸십시오. AMAZON_PROVIDED_DNS_IP를 DNS IP 주소로 바꾸십시오.

사용자 지정 DNS 서버가 요청을 전달하지 않으면 다음과 같은 오류 메시지가 표시될 수 있습니다.

"Output: Failed to resolve "fs-xxxxxx.efs.us-west-2.amazonaws.com" - The file system mount target ip address cannot be found"

클러스터 VPC가 사용자 지정 DNS 서버를 사용하는 경우 모든 *.amazonaws.com 요청을 Amazon DNS 서버로 전달하도록 이 DNS 서버를 구성합니다.

제한적인 파일 시스템 정책을 사용할 때 PersistentVolume 정의에 iam 탑재 옵션이 있는지 확인

제한적인 파일 시스템 정책을 사용하여 iam 탑재 옵션을 추가하지 않으면 포드가 실패하고 다음 오류 메시지가 표시됩니다.

"mount.nfs4: access denied by server while mounting 127.0.0.1:/"

탑재 권한을 특정 AWS Identity and Access Management(IAM) 역할로 제한하도록 Amazon EFS 파일 시스템을 구성한 경우 -o iam 탑재를 사용하십시오. CSI 드라이버가 IAM 탑재 옵션을 추가하도록 허용하려면 spec.mountOptions 속성을 포함합니다.

예:

apiVersion: v1  
kind: PersistentVolume  
metadata:  
  name: efs-pv1  
spec:  
  mountOptions:  
    - iam

Amazon EFS CSI 드라이버 컨트롤러 서비스 계정에 필요한 권한이 있는 올바른 IAM 역할로 주석을 지정했는지 확인

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

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

출력 예시:

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

계정에 올바른 AWS Identity and Access Management(IAM) 역할 및 권한이 있는지 확인하려면 클러스터의 IAM OIDC 제공업체를 확인하십시오. efs-csi-controller-sa 서비스 계정과 연결된 IAM 역할에 EFS API 호출을 수행하는 데 필요한 권한이 있는지 확인합니다. 그런 다음, IAM 역할의 신뢰 정책이 서비스 계정 efs-csi-controller-sa를 신뢰하는지 확인합니다.

IAM 역할 신뢰 정책 예시:

{  
  "Version": "2012-10-17",  
  "Statement": [  
    {  
      "Effect": "Allow",  
      "Principal": {  
        "Federated": "arn:aws:iam::111122223333:oidc-provider/oidc.eks.region-code.amazonaws.com/id/EXAMPLED539D4633E53DE1B71EXAMPLE"  
      },  
      "Action": "sts:AssumeRoleWithWebIdentity",  
      "Condition": {  
        "StringLike": {  
          "oidc.eks.region-code.amazonaws.com/id/EXAMPLED539D4633E53DE1B71EXAMPLE:sub": "system:serviceaccount:kube-system:efs-csi-*",  
          "oidc.eks.region-code.amazonaws.com/id/EXAMPLED539D4633E53DE1B71EXAMPLE:aud": "sts.amazonaws.com"  
        }  
      }  
    }  
  ]  
}

EFS CSI 드라이버 포드가 실행 중인지 확인

다음 명령을 실행하여 클러스터에서 이러한 포드가 활성 상태인지 확인합니다.

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

포드가 파일 시스템을 탑재하지 못하는 EC2 워커 노드의 EFS 탑재 작업 확인

포드의 Amazon EKS 워커 노드에 로그인합니다. 그런 다음, EFS 탑재 도우미를 사용하여 EFS 파일 시스템을 워커 노드에 수동으로 탑재합니다. 탑재 작업을 테스트하려면 다음 명령을 실행합니다.

sudo mount -t efs -o tls file-system-dns-name efs-mount-point/

워커 노드가 파일 시스템을 탑재할 수 있는 경우 CSI 컨트롤러 및 CSI 노드 포드에서 efs-plugin 로그를 검토합니다.

EFS CSI 드라이버 포드 로그를 확인하여 탑재 실패의 원인 파악

볼륨이 탑재되지 않는 경우 efs-plugin 로그를 검토하십시오. efs-plugin 컨테이너 로그를 검색하려면 다음 명령을 실행합니다.

kubectl logs deployment/efs-csi-controller -n kube-system -c efs-plugin  
kubectl logs daemonset/efs-csi-node -n kube-system -c efs-plugin