Amazon EKS 클러스터의 액세스 항목 관련 문제를 해결하려면 어떻게 해야 합니까?

해결 방법

전제 조건: Amazon EKS 클러스터는 Kubernetes 버전 1.23 이상에서 실행됩니다.

참고: AWS Command Line Interface(AWS CLI) 명령을 실행할 때 오류가 발생하면 AWS CLI의 오류 해결을 참조하십시오. 또한 최신 AWS CLI 버전을 사용하고 있는지 확인하십시오.

인증 모드 오류

클러스터의 인증 모드를 수정할 때 다음과 같은 오류 메시지가 표시됩니다.

• "An error occurred (InvalidParameterException) when calling the UpdateClusterConfig operation: Unsupported authentication mode update from API_AND_CONFIG_MAP to CONFIG_MAP."
• "An error occurred (InvalidParameterException) when calling the UpdateClusterConfig operation: Unsupported authentication mode update from API to CONFIG_MAP."
• "An error occurred (InvalidParameterException) when calling the UpdateClusterConfig operation: Unsupported authentication mode update from API to API_AND_CONFIG_MAP."

인증 모드를 설정하면 작업을 되돌릴 수 없습니다. 예를 들어 모드를 API로 변경한 후에는 CONFIG_MAP 또는 API_AND_CONFIG_MAP으로 돌아갈 수 없습니다. 자세한 내용은 간소화된 Amazon EKS 액세스 관리 제어에 대한 심층 분석을 참조하십시오.

인증 모드 오류를 방지하려면 aws-auth ConfigMap 대신 액세스 항목을 사용하십시오.

AccessDeniedException 오류

AWS Identity and Access Management(IAM) 위탁자에 액세스 항목을 사용할 수 있는 충분한 권한이 없는 경우 오류 메시지가 표시됩니다. 오류 메시지는 다음과 비슷합니다.

"An error occurred (AccessDeniedException) when calling the CreateAccessEntry operation: User: [principalARN] is not authorized to perform: eks:CreateAccessEntry on resource: arn:aws:eks:us-east-1:000000000:cluster/your-eks-cluster."

이 문제를 해결하려면 요청을 수행하는 IAM 위탁자의 IAM 정책에 다음 권한을 추가하십시오.

• CreateAccessEntry
• ListAccessEntries
• DescribeAccessEntry
• DeleteAccessEntry
• UpdateAccessEntry

CONFIG_MAP에서 API_AND_CONFIG_MAP으로 마이그레이션 또는 업데이트 문제

액세스 항목을 CONFIG_MAP에서 API_AND_CONFIG_MAP으로 마이그레이션하거나 업데이트할 때 다음 알림이 표시됩니다.

“기존 ConfigMap/AWS-Auth에 정의된 노드 IAM 역할의 매핑이 액세스 항목으로 자동 추가되었습니다. 그러나 aws-auth에서는 이 역할이 두 개의 system:nodes/system:bootstrappers 그룹으로 정의되지만 액세스 항목 측에서는 system:nodes/만 있습니다.”

마이그레이션 프로세스에서 기본적으로 노드 IAM 역할을 system:nodes 그룹에 매핑하므로 문제를 해결해야 하는 오류는 없습니다.

액세스 항목을 마이그레이션한 후에는 system:bootstrappers 그룹이 부여하는 aws-auth ConfigMap 또는 IAM 액세스 항목 구성이 더 이상 필요하지 않습니다. 노드는 system:nodes 그룹이 부여한 권한으로 모든 작업을 수행할 수 있습니다. system:nodes 그룹은 CONFIG_MAP에서 API_AND_CONFIG_MAP으로 마이그레이션하여 액세스 항목에서 불필요한 그룹이 제거되었음을 확인합니다.

유형 오류

액세스 항목의 대상 IAM 위탁자로 IAM 역할을 설정하지 않으면 다음 오류가 발생합니다.

"AccessEntry principalArn must be IAM role when using types [EC2_LINUX, EC2_WINDOWS, FARGATE_LINUX]."

이 문제를 해결하려면 다음 액세스 항목 유형 중 하나를 사용하십시오.

• EC2_LINUX
• EC2_WINDOWS
• FARGATE_LINUX

액세스 항목 유형에 대한 자세한 내용은 액세스 항목 만들기를 참조하십시오.

사용자 이름 오류

액세스 항목을 만들 때 잘못된 사용자 이름을 입력하면 다음과 같은 오류 메시지가 표시됩니다.

"The username must not begin with [eks:, aws:, system:, amazon:, iam:]."

사용자 이름을 직접 지정하는 경우 다음 접두사로 사용자 이름을 시작할 수 없습니다.

• eks:
• aws:
• system:
• amazon:
• iam:

이 문제를 해결하려면 사용자 이름이 액세스 항목에 대한 사용자 이름 요구 사항을 준수하는지 확인하십시오. 사용자 이름 요구 사항에 대한 자세한 내용은 액세스 항목 만들기를 참조하십시오.

참고: 잠재적 오류를 방지하려면 Amazon EKS에서 사용자 이름을 자동으로 생성하도록 하는 것이 가장 좋습니다.

권한 오류

Amazon EKS에서 클러스터의 Kubernetes RBAC(역할 기반 액세스 제어) 객체에 지정된 그룹 이름이 포함되어 있는지 확인하지 않기 때문에 권한 오류가 발생합니다. Amazon EKS는 지정한 그룹 이름이 클러스터의 바인딩에 있는지 확인하지 않습니다.

이 문제를 해결하려면 다음 작업을 수행하십시오.

• aws-auth ConfigMap 또는 IAM 액세스 항목이 Kubernetes RoleBinding 또는 ClusterRoleBinding에서 주체로 지정한 그룹을 성공적으로 생성하는지 확인합니다.
• 액세스 항목의 Kubernetes 그룹에 대한 참조의 철자와 형식이 올바른지 확인합니다.

서비스 연결 역할 오류

액세스 항목을 만들 때 서비스 연결 역할을 지정하면 다음과 같은 오류 메시지가 표시됩니다.

"The caller is not allowed to modify access entries with a principalArn value of a Service Linked Role."

액세스 항목은 서비스 연결 역할을 지원하지 않습니다. 따라서 위탁자 Amazon 리소스 이름(ARN)이 서비스 연결 역할인 경우에는 액세스 항목을 만들 수 없습니다. ARN으로 서비스 연결 역할을 식별할 수 있습니다. 예를 들어 arn:aws:iam::*:role/aws-service-role/* ARN은 서비스 연결 역할에 대한 것입니다.

클러스터에 대한 서비스 연결 역할의 액세스 권한을 부여하려면 CONFIG_MAP 또는 API_AND_CONFIG_MAP 인증 모드를 사용하여 aws-auth ConfigMap에서 서비스 연결 역할을 지정합니다.

관련 정보

ConfigMap을 사용하여 IAM 사용자에게 Kubernetes 액세스 권한 부여