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

해결 방법

---

Amazon EFS 볼륨을 Amazon EKS 클러스터에 탑재할 때, 포드에서 다음 오류 중 하나가 발생할 수 있습니다:

• "출력: mount.nfs4: mounting fs-18xxxxxx.efs.us-east-1.amazonaws.com:/path-in-dir:/ 탑재에 실패함, 서버에서 지정한 사유: 해당 파일이나 디렉터리가 없음"
• "출력: “fs-xxxxxx.efs.us-west-2.amazonaws.com”을 해결하지 못함 - 파일 시스템 ID가 올바른지 확인"
• “mount.nfs4: 127.0.0.1:/를 탑재하는 동안 서버에 의해 액세스가 거부됨”
• "mount.nfs: 연결 시간 초과”
• "볼륨을 연결하거나 탑재할 수 없음: 조건을 기다리는 동안 시간 초과"

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

• 각 작업자 노드 서브넷에서 탑재 대상으로 생성된 Amazon EFS 파일 시스템.
• efs.csi.aws.com 프로비저너를 사용하는 유효한 EFS 스토리지 클래스(GitHub 웹 사이트) 정의.
• 유효한 PersistentVolumeClaim(PVC) 정의 및 PersistentVolume 정의. (GitHub 웹 사이트에서) 동적 프로비저닝을 사용하는 경우에는 필요하지 않습니다.
• 클러스터에 설치된 Amazon EFS CSI 드라이버.

탑재 대상이 올바르게 구성되었는지 확인

EKS 노드가 실행 중인 각 가용 영역에서 EFS 탑재 대상을 생성해야 합니다. 예를 들어, 작업자 노드가 US-EAST-1A 및 US-EAST-1B에 분산되어 있다고 가정합니다. 이 경우 탑재하려는 EFS 파일 시스템에 대한 탑재 대상을 두 가용 영역 모두에 생성합니다. 탑재 대상을 올바르게 생성하지 않으면 EFS 파일 시스템을 탑재하는 포드가 다음과 유사한 오류를 반환합니다.

"출력: “fs-xxxxxx.efs.us-west-2.amazonaws.com”을 해결하지 못함 - 파일 시스템 ID가 올바른지 확인."

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

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

포드가 EFS 볼륨 탑재에 실패하는 워커 노드와 연결된 보안 그룹에는 아웃바운드 규칙이 있어야 합니다. 특히, 이 아웃바운드 규칙은 EFS 파일 시스템에 대한 NFS 트래픽(포트 2049)을 허용해야 합니다.

보안 그룹이 NFS 트래픽을 허용하지 않는 경우 파일 시스템을 탑재하는 포드는 다음 오류를 반환합니다.

• "mount.nfs: 연결 시간 초과”
• "볼륨을 연결하거나 탑재할 수 없음: 조건을 기다리는 동안 시간 초과"

포드를 하위 디렉터리에 탑재하는 경우 EFS 파일 시스템에 하위 디렉터리가 생성되었는지 확인

영구 볼륨에 하위 경로를 추가하는 경우 EFS CSI 드라이버는 파일 시스템에 하위 디렉터리 경로를 생성하지 않습니다. 탑재 작업이 성공하려면 디렉터리가 이미 있어야 합니다. 파일 시스템에 하위 경로가 없으면 포드가 실패하고 다음 오류가 발생합니다.

"출력: mount.nfs4: mounting fs-18xxxxxx.efs.us-east-1.amazonaws.com:/path-in-dir:/ 탑재에 실패함, 서버에서 지정한 사유: 해당 파일이나 디렉터리가 없음"

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

EFS CSI 드라이버를 사용하여 EFS를 탑재할 때 EFS 탑재 도우미는 VPC에 Amazon DNS 서버를 사용하도록 요구합니다.

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

DNS 서버를 확인하려면 작업자 노드에 로그인하고 다음 명령을 실행합니다.

nslookup fs-4fxxxxxx.efs.region.amazonaws.com AMAZON\_PROVIDED\_DNS\_IP

참고: 리전을 AWS 리전으로 바꿉니다. AMAZON_PROVIDED_DNS_IP를 DNS IP 주소로 바꿉니다. 기본적으로 이 값은 VPC 네트워크 범위(10.0.0.0)에 2를 더한 값입니다.

클러스터 VPC에서 사용자 지정 DNS 서버를 사용하는 경우 모든 *.amazonaws.com 요청을 Amazon DNS 서버로 전달하도록 이 DNS 서버를 구성합니다. 이러한 요청이 전달되지 않으면 다음 메시지와 유사한 오류가 발생하여 포드가 실패합니다.

"출력: “fs-4 fxxxxxx.efs.us-west-2.amazonaws.com”을 해결하지 못함 - 파일 시스템 ID가 올바른지 확인."

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

경우에 따라 EFS 파일 시스템 정책이 탑재 권한을 특정 IAM 역할로 제한하도록 구성되어 있습니다. 이 경우 EFS 탑재 도우미는 탑재 작업 중에 -o iam 탑재 옵션을 전달해야 합니다. CSI 드라이버가 (GitHub 웹 사이트에서) iam 탑재 옵션을 추가하도록 허용하려면 spec.mountOptions 속성을 포함합니다.

다음 예제는 PersistentVolume 사양입니다.

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

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

“mount.nfs4: 127.0.0.1:/를 탑재하는 동안 서버에 의해 액세스가 거부됨”

Amazon EFS CSI 드라이버 컨트롤러 서비스 계정에 올바른 IAM 역할로 주석을 지정하고 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

다음 단계를 완료했는지 확인합니다.

• 클러스터에 대해 IAM OIDC 공급자를 생성했습니다.
• efs-csi-controller-sa 서비스 계정과 연결된 IAM 역할에는 EFS API 호출을 수행하는 데 필요한 권한(GitHub 웹 사이트에서 제공)이 있습니다.
• 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": {
			"StringEquals": {
				"oidc.eks.region-code.amazonaws.com/id/EXAMPLED539D4633E53DE1B71EXAMPLE:sub": "system:serviceaccount:kube-system:efs-csi-controller-sa"
			}
		}
	}\]
}

EFS CSI 드라이버 포드가 실행 중인지 확인합니다.

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 드라이버 포드 로그 확인

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