# Amazon ECS 관리형 인스턴스의 인스턴스 프로파일
<a name="managed-instances-instance-profile"></a>

인스턴스 프로파일은 정확히 하나의 IAM 역할을 보유하며 Amazon ECS 관리형 인스턴스가 해당 역할을 안전하게 수임할 수 있도록 하는 IAM 컨테이너입니다. 인스턴스 프로파일에는 ECS 에이전트가 클러스터에 인스턴스를 등록하고 ECS 서비스와 통신하기 위해 수임하는 인스턴스 역할이 포함되어 있습니다.

**중요**  
`AmazonECSInfrastructureRolePolicyForManagedInstances` 관리형 정책과 함께 Amazon ECS 관리형 인스턴스를 사용하는 경우 인스턴스 역할 이름은 `ecsInstanceRole`로 시작해야 합니다. 정책은 `iam:PassRole`을 `arn:aws:iam::*:role/ecsInstanceRole*`로 제한하므로 이름이 일치하지 않으면 태스크 시작 시 권한 부여 오류가 발생합니다. CloudFormation에서 `MyStack-InstanceRole-ABC123`와 같은 이름을 자동으로 생성하기에 CloudFormation에서는 `RoleName`을 생략하는 것이 일반적입니다.  
대신 사용자 지정 인프라 역할 정책을 사용하는 경우 정책에 인스턴스 역할 ARN을 대상으로 하는 `iam:PassRole` 권한이 포함되어 있는 한 인스턴스 역할에는 임의의 이름이 있을 수 있습니다.

## 신뢰 정책으로 역할 생성
<a name="create-instance-role"></a>

모든 {{사용자 입력}}을 사용자 정보로 바꿉니다.

1. IAM 역할에 사용할 신뢰 정책이 포함된 `ecsInstanceRole-trust-policy.json`이라는 이름의 파일을 생성합니다. 파일에 다음을 포함해야 합니다.

------
#### [ JSON ]

****  

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

------

1. 다음 AWS CLI 명령을 사용하여 이전 단계에서 생성한 신뢰 정책을 사용해 `ecsInstanceRole`이라는 이름의 역할을 생성합니다.

   ```
   aws iam create-role \
         --role-name ecsInstanceRole \
         --assume-role-policy-document file://{{ecsInstanceRole-trust-policy.json}}
   ```

1. AWS 관리형 `AmazonECSInstanceRolePolicyForManagedInstances` 정책을 `ecsInstanceRole` 역할에 연결합니다.

   ```
   aws iam attach-role-policy \
         --role-name ecsInstanceRole \
         --policy-arn arn:aws:iam::aws:policy/AmazonECSInstanceRolePolicyForManagedInstances
   ```
**참고**  
대신 최소 권한을 적용하고 자체 권한을 지정하도록 선택한 경우 Amazon ECS 관리형 인스턴스의 태스크 관련 문제를 해결하는 데 도움이 되는 다음 권한을 추가할 수 있습니다.  
`ecs:StartTelemetrySession`
`ecs:PutSystemLogEvents`

IAM 콘솔의 **사용자 지정 신뢰 정책** 워크플로를 사용하여 역할을 생성할 수도 있습니다. 지침은 IAM 사용자 설명서의 [사용자 지정 신뢰 정책을 사용하여 역할 생성(콘솔)](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create_for-custom.html)을 참조하세요.**

파일을 생성한 후 Amazon ECS로 역할을 전달할 수 있는 권한을 사용자에게 부여해야 합니다.

## AWS CLI를 사용하여 인스턴스 프로파일 생성
<a name="create-instance-profile"></a>

역할을 생성한 후 AWS CLI를 사용하여 인스턴스 프로파일을 생성합니다.

```
aws iam create-instance-profile --instance-profile-name ecsInstanceRole 
```

인스턴스 프로파일에 역할을 추가합니다.

```
aws iam add-role-to-instance-profile \
   --instance-profile-name ecsInstanceRole \
   --role-name ecsInstanceRole
```

프로파일이 생성되었는지 확인합니다.

```
aws iam get-instance-profile --instance-profile-name ecsInstanceRole 
```

## CloudFormation을 사용하여 인스턴스 프로파일 생성
<a name="create-instance-profile-cfn"></a>

AWS CloudFormation을 사용하여 인스턴스 역할과 인스턴스 프로파일을 생성할 수 있습니다. AWS 관리형 인프라 정책 또는 사용자 지정 정책을 사용하는지 여부에 따라 다음 옵션 중 하나를 선택합니다.

### 옵션 1: ecsInstanceRole 명명 규칙 사용(권장)
<a name="create-instance-profile-cfn-managed"></a>

AWS 관리형 인프라 정책을 사용하는 경우 명시적으로 `RoleName`을 `ecsInstanceRole`로 시작하는 값으로 설정해야 합니다. `RoleName`을 생략하면 CloudFormation이 관리형 정책의 `iam:PassRole` 조건과 일치하지 않는 이름을 자동으로 생성하며, 태스크는 시작되지 않습니다.

```
Resources:
  EcsInstanceRole:
    Type: AWS::IAM::Role
    Properties:
      RoleName: ecsInstanceRole
      AssumeRolePolicyDocument:
        Version: "2012-10-17"
        Statement:
          - Effect: Allow
            Principal:
              Service: ec2.amazonaws.com
            Action: sts:AssumeRole
      ManagedPolicyArns:
        - arn:aws:iam::aws:policy/AmazonECSInstanceRolePolicyForManagedInstances

  EcsInstanceProfile:
    Type: AWS::IAM::InstanceProfile
    Properties:
      InstanceProfileName: ecsInstanceRole
      Roles:
        - !Ref EcsInstanceRole
```

### 옵션 2: 사용자 지정 역할 이름 사용
<a name="create-instance-profile-cfn-custom"></a>

CloudFormation에서 역할 이름을 생성하도록 하거나 `ecsInstanceRole`로 시작하지 않는 사용자 지정 이름을 사용하는 경우 인스턴스 역할에 `iam:PassRole`을 부여하는 인라인 정책을 인프라 역할에 추가해야 합니다.

```
Resources:
  EcsInstanceRole:
    Type: AWS::IAM::Role
    Properties:
      # No RoleName — CFN auto-generates
      AssumeRolePolicyDocument:
        Version: "2012-10-17"
        Statement:
          - Effect: Allow
            Principal:
              Service: ec2.amazonaws.com
            Action: sts:AssumeRole
      ManagedPolicyArns:
        - arn:aws:iam::aws:policy/AmazonECSInstanceRolePolicyForManagedInstances

  EcsInstanceProfile:
    Type: AWS::IAM::InstanceProfile
    Properties:
      Roles:
        - !Ref EcsInstanceRole

  EcsInfrastructureRole:
    Type: AWS::IAM::Role
    Properties:
      AssumeRolePolicyDocument:
        Version: "2012-10-17"
        Statement:
          - Effect: Allow
            Principal:
              Service: ecs.amazonaws.com
            Action: sts:AssumeRole
      ManagedPolicyArns:
        - arn:aws:iam::aws:policy/AmazonECSInfrastructureRolePolicyForManagedInstances
      Policies:
        - PolicyName: PassInstanceRoleToEC2
          PolicyDocument:
            Version: "2012-10-17"
            Statement:
              - Effect: Allow
                Action: iam:PassRole
                Resource: !GetAtt EcsInstanceRole.Arn
                Condition:
                  StringLike:
                    iam:PassedToService: "ec2.*"
```

## 문제 해결
<a name="managed-instances-instance-profile-troubleshooting"></a>

### iam:PassRole 권한 부여 오류와 함께 태스크 실패
<a name="managed-instances-instance-profile-ts-passrole"></a>

`iam:PassRole`을 언급하는 `ResourceInitializationError`와 함께 태스크가 실패하면 인스턴스 역할 이름이 `ecsInstanceRole`로 시작하는지 확인합니다. CloudFormation 콘솔의 스택 **리소스** 탭에서 자동으로 생성된 이름을 확인할 수 있습니다. 이름이 일치하지 않는 경우:
+ `AWS::IAM::Role` 리소스에 `RoleName: ecsInstanceRole`을 추가합니다.
+ 인프라 역할에 명시적 `iam:PassRole` 인라인 정책을 추가합니다. 자세한 내용은 [옵션 2: 사용자 지정 역할 이름 사용](#create-instance-profile-cfn-custom) 섹션을 참조하세요.