Amazon EKS capability IAM 역할

EKS Capabilities는 capability IAM 역할(capability role)을 구성해야 해요. Capabilities는 이 역할을 사용해 AWS 서비스에서 작업을 수행하고, 자동으로 생성된 access entries를 통해 클러스터의 Kubernetes 리소스에 접근해요.

capability 생성 중에 capability 역할을 지정하기 전에 capability 유형에 적합한 신뢰 정책과 권한으로 IAM 역할을 만들어야 해요. 이 IAM 역할이 만들어지면 여러 capability 리소스에 재사용할 수 있어요.

출처: 문서

본문

Capability 역할 요구 사항

capability 역할은 다음 요구 사항을 충족해야 해요.

역할이 클러스터 및 capability 리소스와 같은 AWS 계정에 있어야 해요
EKS capabilities 서비스가 역할을 맡도록 허용하는 신뢰 정책이 있어야 해요
capability 유형과 사용 사례 요구 사항에 적합한 권한이 있어야 해요(capability 유형별 권한 참고)

Capability 역할의 신뢰 정책

모든 capability 역할은 다음 신뢰 정책을 포함해야 해요.

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "Service": "capabilities.eks.amazonaws.com"
      },
      "Action": [
        "sts:AssumeRole",
        "sts:TagSession"
      ]
    }
  ]
}

이 신뢰 정책은 EKS가 다음을 수행할 수 있게 해줘요.

AWS API 작업을 수행하기 위해 역할을 맡기
감사와 추적 목적으로 세션에 태그 지정하기

Capability 유형별 권한

필요한 IAM 권한은 사용 중인 capability와 배포 모델에 따라 달라져요.

참고

ACK와 함께 IAM Role Selectors를 사용하는 프로덕션 배포, 또는 AWS 서비스 통합 없이 kro나 Argo CD를 사용하는 경우 capability 역할은 신뢰 정책 외에 IAM 권한이 필요하지 않을 수 있어요.

kro (Kube Resource Orchestrator)

필요한 IAM 권한이 없어요. 연결된 정책 없이 capability 역할을 만들 수 있어요. kro는 Kubernetes 리소스를 만들고 관리하는 데 Kubernetes RBAC 권한만 필요해요.

AWS Controllers for Kubernetes (ACK)

ACK는 두 가지 권한 모델을 지원해요.

간단한 설정 (개발/테스트): AWS 서비스 권한을 capability 역할에 직접 추가해요. 시작하기, 단일 계정 배포, 또는 모든 사용자가 같은 권한이 필요한 경우에 적합해요.
프로덕션 모범 사례: IAM Role Selectors를 사용해 최소 권한 접근을 구현해요. 이 방식을 사용하면 capability 역할은 서비스별 역할을 맡는 sts:AssumeRole 권한만 있으면 돼요. capability 역할 자체에는(S3나 RDS 같은) AWS 서비스 권한을 추가하지 않고, 그 권한들은 특정 네임스페이스에 매핑된 개별 IAM 역할에 부여돼요.

IAM Role Selectors를 사용하면 다음이 가능해져요.

네임스페이스 수준 권한 격리
교차 계정 리소스 관리
팀별 IAM 역할
최소 권한 보안 모델

IAM Role Selector 방식의 예시 capability 역할 정책:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": "sts:AssumeRole",
      "Resource": [
        "arn:aws:iam::111122223333:role/ACK-S3-Role",
        "arn:aws:iam::111122223333:role/ACK-RDS-Role",
        "arn:aws:iam::444455556666:role/ACKCrossAccountRole"
      ]
    }
  ]
}

IAM Role Selectors를 포함한 자세한 ACK 권한 구성은 ACK 권한 구성을 참고하세요.

Argo CD

기본적으로 필요한 IAM 권한이 없어요. 다음 항목에 대해 선택적 권한이 필요할 수 있어요.

AWS Secrets Manager: Git 리포지토리 자격 증명을 저장하는 데 Secrets Manager를 사용하는 경우
AWS CodeConnections: Git 리포지토리 인증에 CodeConnections를 사용하는 경우

Secrets Manager와 CodeConnections용 정책 예시:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "secretsmanager:GetSecretValue",
        "secretsmanager:DescribeSecret"
      ],
      "Resource": "arn:aws:secretsmanager:region:account-id:secret:argocd/*"
    },
    {
      "Effect": "Allow",
      "Action": [
        "codeconnections:UseConnection",
        "codeconnections:GetConnection"
      ],
      "Resource": "arn:aws:codeconnections:region:account-id:connection/*"
    }
  ]
}

자세한 Argo CD 권한 요구 사항은 Argo CD 고려 사항을 참고하세요.

기존 capability 역할 확인하기

계정에 사용 사례에 적합한 capability IAM 역할이 이미 있는지 확인하려면 다음 절차를 사용할 수 있어요.

https://console.aws.amazon.com/iam/ 에서 IAM 콘솔을 엽니다.
왼쪽 탐색 창에서 Roles를 선택합니다.
역할 목록에서 capability 역할 이름(예: ACKCapabilityRole 또는 ArgoCDCapabilityRole)을 검색합니다.
역할이 있으면 그 역할을 선택해 연결된 정책과 신뢰 관계를 봅니다.
Trust relationships를 선택한 다음 Edit trust policy를 선택합니다.
신뢰 관계가 capability 신뢰 정책과 일치하는지 확인합니다. 일치하지 않으면 신뢰 정책을 업데이트합니다.
Permissions를 선택하고 역할이 capability 유형과 사용 사례에 적합한 권한을 가지고 있는지 확인합니다.

Capability IAM 역할 생성

capability 역할은 AWS Management Console이나 AWS CLI로 만들 수 있어요.

AWS Management Console

https://console.aws.amazon.com/iam/ 에서 IAM 콘솔을 엽니다.
Roles를 선택한 다음 Create role을 선택합니다.
Trusted entity type에서 Custom trust policy를 선택합니다.
trust policy 편집기에 capability 신뢰 정책을 복사해 붙여넣습니다.
Next를 선택합니다.
Add permissions 탭에서 capability 유형에 적합한 정책을 선택하거나 만듭니다(capability 유형별 권한 참고). kro의 경우 이 단계를 건너뛸 수 있어요.
Next를 선택합니다.
Role name에 ACKCapabilityRole, ArgoCDCapabilityRole, kroCapabilityRole 같은 역할의 고유한 이름을 입력합니다.
Description에 Amazon EKS - ACK capability role 같은 설명 텍스트를 입력합니다.
Create role을 선택합니다.

AWS CLI

capability 신뢰 정책을 capability-trust-policy.json 파일에 복사합니다.
역할을 만듭니다. ACKCapabilityRole을 원하는 역할 이름으로 바꾸세요.

aws iam create-role \
  --role-name ACKCapabilityRole \
  --assume-role-policy-document file://capability-trust-policy.json

필요한 IAM 정책을 역할에 연결합니다. ACK의 경우 관리하려는 AWS 서비스에 대한 정책을 연결합니다. Argo CD의 경우 필요할 때 Secrets Manager 또는 CodeConnections 정책을 연결합니다. kro의 경우 이 단계를 건너뛸 수 있어요.

S3 권한이 있는 ACK 예시:

aws iam put-role-policy \
  --role-name ACKCapabilityRole \
  --policy-name S3Management \
  --policy-document file://s3-policy.json

Capability 역할 문제 해결

capability 생성이 "Invalid IAM role"로 실패하는 경우

다음을 확인하세요.

역할이 클러스터와 같은 계정에 있는지
신뢰 정책이 capability 신뢰 정책과 일치하는지
역할에 대한 iam:PassRole 권한이 있는지

capability에 권한 오류가 표시되는 경우

다음을 확인하세요.

역할이 capability 유형에 필요한 IAM 권한을 가지고 있는지
역할에 대한 access entry가 클러스터에 존재하는지
필요하면 추가 Kubernetes 권한이 구성되었는지(추가 Kubernetes 권한 참고)

ACK 리소스가 "permission denied" 오류로 실패하는 경우

다음을 확인하세요.

역할이 사용 사례에 필요한 IAM 권한을 가지고 있는지
시크릿을 참조하는 ACK 컨트롤러의 경우 적절한 네임스페이스 범위로 AmazonEKSSecretReaderPolicy access entry 정책을 연결했는지

자세한 문제 해결 지침은 EKS Capabilities 보안 고려 사항을 참고하세요.

더 알아보기 (Learn more)

공식 문서