액세스 항목

액세스 항목 (Access entry) 생성

Amazon EKS 클러스터에 대한 액세스 항목(access entry)을 생성하는 방법을 설명합니다. 액세스 항목은 IAM 보안 주체(principal)에게 클러스터에 대한 액세스 권한을 부여하는 핵심 메커니즘입니다.

출처: 문서

본문

액세스 항목을 생성하기 전에 다음 사항을 고려하세요.

먼저 인증 모드가 올바르게 설정되어 있어야 합니다. 자세한 내용은 "액세스 항목을 사용하도록 인증 모드 변경"을 참고하세요.

액세스 항목에는 기존 IAM 보안 주체 하나, 그리고 오직 하나의 Amazon Resource Name(ARN)만 포함됩니다. 하나의 IAM 보안 주체는 둘 이상의 액세스 항목에 포함될 수 없습니다. 지정하는 ARN에 대한 추가 고려 사항은 다음과 같습니다.

IAM 모범 사례에서는 장기 자격 증명을 가진 IAM 사용자보다 단기 자격 증명을 가진 IAM 역할을 사용하여 클러스터에 액세스할 것을 권장합니다. 자세한 내용은 IAM 사용 설명서의 "임시 자격 증명을 사용하여 AWS에 액세스하도록 ID 공급자와의 페더레이션을 인간 사용자에게 요구"를 참고하세요.
ARN이 IAM 역할을 가리키는 경우 경로(path)를 포함할 수 있습니다. 그러나 aws-auth ConfigMap 항목의 ARN에는 경로를 포함할 수 없습니다. 예를 들어 ARN은 arn:aws:iam:::role/ 또는 arn:aws:iam:::role/ 형식이 될 수 있습니다.
액세스 항목의 유형이 STANDARD가 아닌 경우(다음 고려 사항 참고), ARN은 클러스터가 있는 AWS 계정과 동일한 계정에 있어야 합니다. 유형이 STANDARD인 경우 ARN은 클러스터가 있는 계정과 같거나 다른 AWS 계정에 있을 수 있습니다.
액세스 항목이 생성된 후에는 IAM 보안 주체를 변경할 수 없습니다.
해당 ARN을 가진 IAM 보안 주체를 삭제하더라도 액세스 항목은 자동으로 삭제되지 않습니다. 삭제한 IAM 보안 주체의 ARN을 가진 액세스 항목은 직접 삭제하는 것이 좋습니다. 액세스 항목을 삭제하지 않고 IAM 보안 주체를 다시 생성하는 경우, ARN이 동일하더라도 액세스 항목은 작동하지 않습니다. 그 이유는 재생성된 IAM 보안 주체의 roleID나 userID(aws sts get-caller-identity AWS CLI 명령으로 확인 가능)가 원래 보안 주체와 다르기 때문입니다. 액세스 항목에서는 IAM 보안 주체의 roleID나 userID를 볼 수 없지만, Amazon EKS는 이를 액세스 항목과 함께 저장합니다.

각 액세스 항목에는 유형(type)이 있습니다. 액세스 항목의 유형은 해당 항목이 연결된 리소스의 종류에 따라 결정되며, 권한을 정의하지는 않습니다. 유형을 지정하지 않으면 Amazon EKS는 유형을 자동으로 STANDARD로 설정합니다.

EC2_LINUX - Linux 또는 Bottlerocket 자체 관리(self-managed) 노드에 사용되는 IAM 역할용
EC2_WINDOWS - Windows 자체 관리 노드에 사용되는 IAM 역할용
FARGATE_LINUX - AWS Fargate(Fargate)에 사용되는 IAM 역할용
HYBRID_LINUX - 하이브리드 노드에 사용되는 IAM 역할용
STANDARD - 유형을 지정하지 않을 때의 기본값
EC2 - EKS Auto Mode 사용자 지정 노드 클래스용. 자세한 내용은 "노드 클래스 액세스 항목 생성"을 참고하세요.

액세스 항목이 생성된 후에는 유형을 변경할 수 없습니다.

관리형 노드 그룹이나 Fargate 프로필에 사용되는 IAM 역할에 대해서는 액세스 항목을 생성할 필요가 없습니다. EKS는 (활성화된 경우) 액세스 항목을 생성하거나, (액세스 항목을 사용할 수 없는 경우) 인증 구성 맵(auth config map)을 업데이트합니다.

액세스 항목의 유형이 STANDARD인 경우, 액세스 항목에 사용자 이름(username)을 지정할 수 있습니다. 사용자 이름 값을 지정하지 않으면 Amazon EKS는 액세스 항목의 유형과 지정한 IAM 보안 주체가 IAM 역할인지 IAM 사용자인지에 따라 다음 값 중 하나를 자동으로 설정합니다. 특별한 이유가 없다면 사용자 이름을 직접 지정하지 말고 Amazon EKS가 자동으로 생성하도록 두는 것을 권장합니다. 직접 사용자 이름을 지정하는 경우:

사용자 이름은 system:, eks:, aws:, amazon:, iam:으로 시작할 수 없습니다.
사용자 이름이 IAM 역할을 위한 것이라면, 사용자 이름 끝에 {{SessionName}} 또는 {{SessionNameRaw}}를 추가할 것을 권장합니다. {{SessionName}} 또는 {{SessionNameRaw}}를 사용자 이름에 추가하는 경우, 사용자 이름에는 {{SessionName}} 앞에 콜론이 포함되어야 합니다. 이 역할이 수임되면 역할 수임 시 지정된 AWS STS 세션 이름이 자동으로 클러스터에 전달되어 CloudTrail 로그에 나타납니다. 예를 들어 사용자 이름을 john{{SessionName}}으로 할 수 없고, :john{{SessionName}} 또는 jo:hn{{SessionName}} 형식이어야 합니다. 콜론은 {{SessionName}} 앞에만 있으면 됩니다. 아래 표에서 Amazon EKS가 생성하는 사용자 이름에는 ARN이 포함됩니다. ARN에는 콜론이 포함되므로 이 요구 사항을 충족합니다. 사용자 이름에 {{SessionName}}을 포함하지 않으면 콜론이 필요하지 않습니다. {{SessionName}}에서는 특수 문자 "@"가 세션 이름에서 "-"로 바뀝니다. {{SessionNameRaw}}는 세션 이름의 모든 특수 문자를 유지합니다.

IAM 보안 주체 유형	유형	Amazon EKS가 자동으로 설정하는 사용자 이름 값
사용자	`STANDARD`	사용자의 ARN. 예: `arn:aws:iam:::user/`
역할	`STANDARD`	역할 수임 시의 STS ARN. Amazon EKS는 역할에 `{{SessionName}}`을 추가합니다. 예: `arn:aws:sts:::assumed-role//{{SessionName}}`. 지정한 역할의 ARN에 경로가 포함된 경우, Amazon EKS는 생성된 사용자 이름에서 경로를 제거합니다.
역할	`EC2_LINUX` 또는 `EC2_WINDOWS`	`system:node:{{EC2PrivateDNSName}}`
역할	`FARGATE_LINUX`	`system:node:{{SessionName}}`
역할	`HYBRID_LINUX`	`system:node:{{SessionName}}`

액세스 항목이 생성된 후에는 사용자 이름을 변경할 수 있습니다.

액세스 항목의 유형이 STANDARD이고 Kubernetes RBAC 인증을 사용하려는 경우, 액세스 항목에 하나 이상의 그룹 이름(group name)을 추가할 수 있습니다. 액세스 항목을 생성한 후에는 그룹 이름을 추가하고 제거할 수 있습니다. IAM 보안 주체가 클러스터의 Kubernetes 객체에 액세스하려면 Kubernetes 역할 기반 인증(RBAC) 객체를 생성하고 관리해야 합니다. 그룹 이름을 kind: Group의 subject로 지정하는 Kubernetes RoleBinding 또는 ClusterRoleBinding 객체를 클러스터에 생성하세요. Kubernetes는 바인딩의 roleRef에 지정한 Kubernetes Role 또는 ClusterRole 객체에서 지정한 클러스터 객체에 대한 IAM 보안 주체 액세스를 승인합니다. 그룹 이름을 지정하는 경우 Kubernetes RBAC 객체에 익숙할 것을 권장합니다. 자세한 내용은 Kubernetes 문서의 "RBAC 인증 사용"을 참고하세요.

중요: Amazon EKS는 클러스터에 존재하는 Kubernetes RBAC 객체가 지정한 그룹 이름을 포함하는지 확인하지 않습니다. 예를 들어 현재 존재하지 않는 그룹에 대한 액세스 항목을 생성하면 Amazon EKS는 오류 없이 구성을 수락하지만, 일치하는 Kubernetes RBAC 리소스가 생성될 때까지 IAM 보안 주체는 아무 권한도 갖지 않습니다.

쿠버네티스가 IAM 보안 주체에게 클러스터의 Kubernetes 객체 액세스를 승인하는 대신, 또는 그와 더불어, Amazon EKS 액세스 정책을 액세스 항목에 연결할 수 있습니다. Amazon EKS는 액세스 정책의 권한으로 IAM 보안 주체가 클러스터의 Kubernetes 객체에 액세스하도록 승인합니다. 액세스 정책의 권한 범위를 지정한 Kubernetes 네임스페이스로 제한할 수 있습니다. 액세스 정책을 사용하면 Kubernetes RBAC 객체를 관리할 필요가 없습니다. 자세한 내용은 "액세스 정책을 액세스 항목에 연결"을 참고하세요.

EC2_LINUX 또는 EC2_WINDOWS 유형의 액세스 항목을 생성하는 경우, 액세스 항목을 생성하는 IAM 보안 주체는 iam:PassRole 권한이 있어야 합니다. 자세한 내용은 IAM 사용 설명서의 "사용자에게 역할을 AWS 서비스에 전달할 권한 부여"를 참고하세요.

일반적인 IAM 동작과 마찬가지로 액세스 항목 생성 및 업데이트는 최종적으로 일관성(eventually consistent)을 가지며, 초기 API 호출이 성공적으로 반환된 후에도 몇 초가 걸릴 수 있습니다. 애플리케이션이 이러한 지연을 감안하도록 설계해야 합니다. 액세스 항목 생성이나 업데이트를 애플리케이션의 중요한 고가용성 코드 경로에 포함하지 말고, 덜 자주 실행되는 별도의 초기화 또는 설정 루틴에서 변경하는 것을 권장합니다. 또한 프로덕션 워크플로가 의존하기 전에 변경 사항이 전파되었는지 반드시 확인하세요.

액세스 항목은 서비스 연결 역할(service linked role)을 지원하지 않습니다. 보안 주체 ARN이 서비스 연결 역할인 액세스 항목은 생성할 수 없습니다. 서비스 연결 역할은 arn:aws:iam::*:role/aws-service-role/* 형식의 ARN으로 식별할 수 있습니다.

AWS Management Console 또는 AWS CLI를 사용하여 액세스 항목을 생성할 수 있습니다.

AWS Management Console

Amazon EKS 콘솔을 엽니다.
액세스 항목을 생성할 클러스터의 이름을 선택합니다.
Access 탭을 선택합니다.
Create access entry를 선택합니다.
IAM principal에서 기존 IAM 역할 또는 사용자를 선택합니다. IAM 모범 사례에서는 장기 자격 증명을 가진 IAM 사용자보다 단기 자격 증명을 가진 IAM 역할로 클러스터에 액세스할 것을 권장합니다. 자세한 내용은 IAM 사용 설명서의 "임시 자격 증명을 사용하여 AWS에 액세스하도록 ID 공급자와의 페더레이션을 인간 사용자에게 요구"를 참고하세요.
Type에서 액세스 항목이 자체 관리형 Amazon EC2 노드에 사용되는 노드 역할용이라면 EC2 Linux 또는 EC2 Windows를 선택합니다. 그렇지 않으면 기본값(Standard)을 그대로 둡니다.
선택한 Type이 Standard이고 Username을 지정하려면 사용자 이름을 입력합니다.
선택한 Type이 Standard이고 IAM 보안 주체에 Kubernetes RBAC 인증을 사용하려면 Groups에 이름을 하나 이상 지정합니다. 그룹 이름을 지정하지 않고 Amazon EKS 인증을 사용하려면 이후 단계나 액세스 항목 생성 후에 액세스 정책을 연결할 수 있습니다.
(선택 사항) Tags에서 액세스 항목에 라벨을 지정합니다. 예를 들어 동일한 태그를 가진 모든 리소스를 더 쉽게 찾을 수 있습니다.
Next를 선택합니다.
Add access policy 페이지에서 선택한 Type이 Standard이고 Amazon EKS가 IAM 보안 주체에게 클러스터의 Kubernetes 객체에 대한 권한을 승인하도록 하려면 다음 단계를 완료합니다. 그렇지 않으면 Next를 선택합니다.
- Policy name에서 액세스 정책을 선택합니다. 액세스 정책의 권한은 볼 수 없지만, Kubernetes 사용자 대면 ClusterRole 객체와 유사한 권한을 포함합니다. 자세한 내용은 Kubernetes 문서의 "사용자 대면 역할"을 참고하세요.
- 다음 옵션 중 하나를 선택합니다:
  - Cluster – IAM 보안 주체가 클러스터의 모든 Kubernetes 객체에 대해 액세스 정책의 권한을 갖도록 Amazon EKS가 승인하길 원하는 경우 선택합니다.
  - Kubernetes namespace – IAM 보안 주체가 클러스터의 특정 Kubernetes 네임스페이스에 있는 모든 Kubernetes 객체에 대해 액세스 정책의 권한을 갖도록 Amazon EKS가 승인하길 원하는 경우 선택합니다. Namespace에는 클러스터의 Kubernetes 네임스페이스 이름을 입력합니다. 추가 네임스페이스를 추가하려면 Add new namespace를 선택하고 네임스페이스 이름을 입력합니다.
- 추가 정책을 추가하려면 Add policy를 선택합니다. 각 정책의 범위는 다르게 지정할 수 있지만, 각 정책은 한 번만 추가할 수 있습니다.
Next를 선택합니다.
액세스 항목 구성을 검토합니다. 잘못된 부분이 있으면 Previous를 선택해 단계를 돌아가 수정합니다. 구성이 올바르면 Create를 선택합니다.

AWS CLI

AWS CLI를 설치합니다. 설치 방법은 AWS Command Line Interface 사용 설명서의 "Installing"을 참고하세요.

액세스 항목을 생성하려면 다음 예제 중 원하는 것을 사용할 수 있습니다.

자체 관리형 Amazon EC2 Linux 노드 그룹에 대한 액세스 항목을 생성합니다. my-cluster를 클러스터 이름으로, 111122223333을 AWS 계정 ID로, EKS-my-cluster-self-managed-ng-1을 노드 IAM 역할 이름으로 바꾸세요. 노드 그룹이 Windows 노드 그룹이라면 EC2_LINUX를 EC2_WINDOWS로 바꾸세요.

aws eks create-access-entry --cluster-name my-cluster --principal-arn arn:aws:iam::111122223333:role/EKS-my-cluster-self-managed-ng-1 --type EC2_LINUX

STANDARD가 아닌 다른 유형을 지정하면 --kubernetes-groups 옵션을 사용할 수 없습니다. 유형이 STANDARD가 아니므로 이 액세스 항목에는 액세스 정책을 연결할 수 없습니다.

Amazon EC2 자체 관리형 노드 그룹에 사용되지 않는 IAM 역할이 Kubernetes를 통해 클러스터 액세스를 승인받도록 하는 액세스 항목을 생성합니다. my-cluster를 클러스터 이름으로, 111122223333을 AWS 계정 ID로, my-role을 IAM 역할 이름으로 바꾸세요. Viewers는 클러스터의 Kubernetes RoleBinding 또는 ClusterRoleBinding 객체에 지정한 그룹 이름으로 바꾸세요.

aws eks create-access-entry --cluster-name my-cluster --principal-arn arn:aws:iam::111122223333:role/my-role --type STANDARD --username Viewers --kubernetes-groups Viewers

IAM 사용자가 클러스터에 인증할 수 있게 하는 액세스 항목을 생성합니다. 가능은 하지만 IAM 모범 사례에서는 장기 자격 증명을 가진 IAM 사용자보다 단기 자격 증명을 가진 IAM 역할로 클러스터에 액세스할 것을 권장한다는 점을 보여주기 위한 예제입니다. 자세한 내용은 IAM 사용 설명서의 "임시 자격 증명을 사용하여 AWS에 액세스하도록 ID 공급자와의 페더레이션을 인간 사용자에게 요구"를 참고하세요.

aws eks create-access-entry --cluster-name my-cluster --principal-arn arn:aws:iam::111122223333:user/my-user --type STANDARD --username my-user

이 사용자가 Kubernetes API 검색 역할(API discovery roles)의 권한보다 클러스터에 더 많은 액세스 권한을 갖게 하려면, --kubernetes-groups 옵션이 사용되지 않으므로 액세스 항목에 액세스 정책을 연결해야 합니다. 자세한 내용은 "액세스 정책을 액세스 항목에 연결"과 Kubernetes 문서의 "API 검색 역할"을 참고하세요.

더 알아보기 (Learn more)

공식 문서