**이 페이지 개선에 도움 주기** 

이 사용자 가이드에 기여하려면 모든 페이지의 오른쪽 창에 있는 **GitHub에서 이 페이지 편집** 링크를 선택합니다.

# Amazon EKS 기능 IAM 역할
<a name="capability-role"></a>

EKS 기능을 사용하려면 기능 IAM 역할 또는 기능 역할을 구성해야 합니다. 기능은 이 역할을 사용하여 AWS 서비스에서 작업을 수행하고 자동으로 생성된 액세스 항목을 통해 클러스터의 Kubernetes 리소스에 액세스합니다.

기능 생성 중에 기능 역할을 지정하려면 먼저 기능 유형에 대한 적절한 신뢰 정책 및 권한을 사용하여 IAM 역할을 생성해야 합니다. 이 IAM 역할이 생성되면 원하는 수의 기능 리소스에 대해 재사용할 수 있습니다.

## 기능 역할 요구 사항
<a name="_capability_role_requirements"></a>

기능 역할은 다음 요구 사항을 충족해야 합니다.
+ 역할은 클러스터 및 기능 리소스와 동일한 AWS 계정에 있어야 함
+ 역할에는 EKS 기능 서비스가 역할을 수임하도록 허용하는 신뢰 정책이 있어야 함
+ 역할에는 기능 유형 및 사용 사례 요구 사항에 적절한 권한이 있어야 함([기능 유형별 권한](#capability-permissions) 참조)

## 기능 역할에 대한 신뢰 정책
<a name="capability-trust-policy"></a>

모든 기능 역할에는 다음 신뢰 정책이 포함되어야 합니다.

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

이 신뢰 정책을 통해 EKS는 다음을 수행할 수 있습니다.
+ AWS API 작업을 수행하도록 역할 수임
+ 감사 및 추적을 위해 세션에 태그 지정

## 기능 유형별 권한
<a name="capability-permissions"></a>

필요한 IAM 권한은 사용 중인 기능 및 배포 모델에 따라 다릅니다.

**참고**  
ACK와 함께 IAM 역할 선택기를 사용하는 프로덕션 배포의 경우 또는 AWS 서비스 통합 없이 kro 또는 Argo CD를 사용하는 경우 기능 역할에는 신뢰 정책 이외의 IAM 권한이 필요하지 않을 수 있습니다.

 **Kube Resource Orchestrator(kro)**   
IAM 권한이 필요하지 않습니다. 연결된 정책 없이 기능 역할을 생성할 수 있습니다. kro는 Kubernetes 리소스를 생성 및 관리하는 데 Kubernetes RBAC 권한만 필요합니다.

 **AWS Controllers for Kubernetes(ACK)**   
ACK는 다음과 같이 두 가지 권한 모델을 지원합니다.  
+  **단순 설정(개발/테스트)**: 기능 역할에 직접 AWS 서비스 권한을 추가합니다. 시작하기, 단일 계정 배포 또는 모든 사용자에게 동일한 권한이 필요한 경우에 적합합니다.
+  **프로덕션 모범 사례**: IAM 역할 선택기를 사용하여 최소 권한 액세스를 구현합니다. 이 접근 방식을 사용하면 기능 역할에는 서비스 특정 역할을 수임할 `sts:AssumeRole` 권한만 있으면 됩니다. 기능 역할 자체에 AWS 서비스 권한(예: S3 또는 RDS)을 추가하지 않아도 됩니다. 이러한 권한은 특정 네임스페이스에 매핑되는 개별 IAM 역할에 부여됩니다.

  IAM 역할 선택기는 다음을 활성화합니다.
  + 네임스페이스 수준의 권한 격리
  + 교차 계정 리소스 관리
  + 팀 특정 IAM 역할
  + 최소 권한 보안 모델

    IAM 역할 선택기 접근 방식에 대한 기능 역할 정책 예제:

    ```
    {
      "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 역할 선택기를 포함한 자세한 ACK 권한 구성은 [ACK 권한 구성](ack-permissions.md) 섹션을 참조하세요.

 **Argo CD**   
기본적으로 IAM 권한은 필요하지 않습니다. 다음과 같은 경우에 선택적 권한이 필요할 수 있습니다.  
+  **AWS Secrets Manager**: Secrets Manager를 사용하여 Git 리포지토리 자격 증명을 저장하는 경우
+  **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 고려 사항](argocd-considerations.md) 섹션을 참조하세요.

## 기존 기능 역할 확인
<a name="check-capability-role"></a>

다음 절차를 사용하여 사용 사례에 적합한 기능 IAM 역할이 이미 계정에 있는지 확인할 수 있습니다.

1. IAM 콘솔(https://console.aws.amazon.com/iam/)을 엽니다.

1. 왼쪽 탐색 창에서 **역할**을 선택합니다.

1. 역할 목록에서 기능 역할 이름(예: `ACKCapabilityRole` 또는 `ArgoCDCapabilityRole`)을 검색하세요.

1. 역할이 있는 경우 역할을 선택하여 연결된 정책 및 신뢰 관계를 확인하세요.

1. **신뢰 관계**를 선택한 후 **신뢰 정책 편집**을 선택합니다.

1. 신뢰 관계가 [기능 신뢰 정책](#capability-trust-policy)과 일치하는지 확인하세요. 일치하지 않는 경우 신뢰 정책을 업데이트하세요.

1. **권한**을 선택하고 역할에 기능 유형 및 사용 사례에 적합한 권한이 있는지 확인하세요.

## 기능 IAM 역할 생성
<a name="create-capability-role"></a>

기능 역할을 생성하기 위해 AWS Management Console 또는 AWS CLI를 사용할 수 있습니다.

 ** AWS Management Console **   

1. IAM 콘솔(https://console.aws.amazon.com/iam/)을 엽니다.

1. **역할**을 선택한 다음 **역할 생성**을 선택합니다.

1. **신뢰할 수 있는 엔터티 유형**에서 **사용자 지정 신뢰 정책**을 선택하세요.

1. [기능 신뢰 정책](#capability-trust-policy) 복사하여 신뢰 정책 편집기에 붙여 넣으세요.

1. **다음**을 선택합니다.

1. **권한 추가** 탭에서 기능 유형에 적합한 정책을 선택하거나 생성하세요([기능 유형별 권한](#capability-permissions) 참조). kro의 경우 이 단계를 건너뛸 수 있습니다.

1. **다음**을 선택합니다.

1. **역할 이름**에 역할의 고유한 이름(예: `ACKCapabilityRole`, `ArgoCDCapabilityRole` 또는 `kroCapabilityRole`)을 입력하세요.

1. **설명**에서 `Amazon EKS - ACK capability role`과 같은 설명 텍스트를 입력합니다.

1. **역할 생성**을 선택합니다.

 **AWS CLI**   

1. [기능 신뢰 정책](#capability-trust-policy)을 `capability-trust-policy.json` 파일에 복사하세요.

1. 역할을 생성합니다. `ACKCapabilityRole`을 원하는 역할 이름으로 바꾸세요.

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

1. 필요한 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
   ```

## 기능 역할 문제 해결
<a name="troubleshooting-capability-role"></a>

 **'유효하지 않은 IAM 역할'로 기능 생성 실패**   
다음을 확인합니다.  
+ 역할이 클러스터와 동일한 계정에 존재함
+ 신뢰 정책이 [기능 신뢰 정책](#capability-trust-policy)과 일치함 
+ 역할에 대한 `iam:PassRole` 권한이 있음

 **기능에서 권한 오류 표시**   
다음을 확인합니다.  
+ 기능 역할에 필요한 권한이 해당 역할에 있음
+ 액세스 항목이 역할의 클러스터에 있음
+ 필요한 경우 추가 Kubernetes 권한이 구성됨([추가 Kubernetes 권한](capabilities-security.md#additional-kubernetes-permissions) 참조)

 **'권한 거부' 오류로 ACK 리소스 실패**   
다음을 확인합니다.  
+ 역할에는 사용 사례에 필요한 권한이 있습니다.
+ 보안 암호를 참조하는 ACK 컨트롤러의 경우 적절한 네임스페이스로 범위가 지정된 `AmazonEKSSecretReaderPolicy` 액세스 항목 정책을 연결했는지 확인합니다.

문제 해결 지침은 [EKS 기능에 대한 보안 고려 사항](capabilities-security.md) 섹션을 참조하세요.