Amazon ECS Managed Instances 인스턴스 프로파일

Amazon ECS Managed Instances 인스턴스 프로파일

인스턴스 프로파일(instance profile)은 정확히 하나의 IAM 역할을 담고, Amazon ECS Managed Instances가 그 역할을 안전하게 가정할 수 있게 하는 IAM 컨테이너예요. 인스턴스 프로파일에는 ECS 에이전트가 인스턴스를 클러스터에 등록하고 ECS 서비스와 통신하기 위해 가정하는 인스턴스 역할이 포함됩니다.

출처: 문서

본문

중요: AmazonECSInfrastructureRolePolicyForManagedInstances 관리형 정책과 함께 Amazon ECS Managed Instances를 사용한다면, 인스턴스 역할 이름이 ecsInstanceRole로 시작해야 해요. 이 정책은 iam:PassRole을 arn:aws:iam::*:role/ecsInstanceRole*로 범위를 한정하므로, 이름이 일치하지 않으면 태스크 시작 시 권한 부여 오류가 발생합니다. CloudFormation에서 RoleName을 생략하면 MyStack-InstanceRole-ABC123 같은 이름을 자동 생성하기 때문에 이는 CloudFormation에서 흔합니다. 대신 사용자 지정 인프라 역할 정책을 사용한다면, 정책에 인스턴스 역할 ARN을 대상으로 하는 iam:PassRole 권한이 포함되어 있기만 하면 인스턴스 역할 이름은 무엇이든 될 수 있어요.

신뢰 정책으로 역할 만들기

모든 사용자 입력을 자신의 정보로 바꾸세요.

IAM 역할에 사용할 신뢰 정책이 포함된 ecsInstanceRole-trust-policy.json 파일을 만듭니다. 파일에는 다음이 포함되어야 합니다:

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

이전 단계에서 만든 신뢰 정책을 사용해 ecsInstanceRole이라는 이름의 역할을 만들려면 다음 AWS CLI 명령을 사용합니다:

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

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

aws iam attach-role-policy \
      --role-name ecsInstanceRole \
      --policy-arn arn:aws:iam::aws:policy/AmazonECSInstanceRolePolicyForManagedInstances

참고: 최소 권한 권한을 적용하고 자신의 권한을 직접 지정하기로 선택했다면, Amazon ECS Managed Instances 관련 태스크 문제 트러블슈팅에 도움이 되도록 다음 권한을 추가할 수 있어요: ecs:StartTelemetrySession, ecs:PutSystemLogEvents.

IAM 콘솔의 Custom trust policy 워크플로를 사용해 역할을 만들 수도 있어요. 자세한 내용은 IAM 사용자 가이드의 사용자 지정 신뢰 정책으로 역할 만들기(콘솔)(Creating a role using custom trust policies (console))를 참고하세요. 파일을 만든 후에는 사용자에게 역할을 Amazon ECS에 전달(pass)할 권한을 부여해야 합니다.

AWS CLI로 인스턴스 프로파일 만들기

역할을 만든 후 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으로 인스턴스 프로파일 만들기

AWS CloudFormation을 사용해 인스턴스 역할과 인스턴스 프로파일을 만들 수 있어요. AWS 관리형 인프라 정책을 사용하는지 사용자 지정 정책을 사용하는지에 따라 다음 옵션 중 하나를 선택하세요.

옵션 1: ecsInstanceRole 명명 규칙 사용(권장)

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: 사용자 지정 역할 이름 사용

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.*"

트러블슈팅

태스크가 iam:PassRole 권한 부여 오류로 실패

태스크가 iam:PassRole을 언급하는 ResourceInitializationError로 실패하면 인스턴스 역할 이름이 ecsInstanceRole로 시작하는지 확인하세요. CloudFormation 콘솔의 스택 Resources 탭에서 자동 생성된 이름을 확인할 수 있어요. 이름이 일치하지 않으면 다음 중 하나를 수행합니다:

  • AWS::IAM::Role 리소스에 RoleName: ecsInstanceRole을 추가합니다.
  • 인프라 역할에 명시적인 iam:PassRole 인라인 정책을 추가합니다. 자세한 내용은 옵션 2: 사용자 지정 역할 이름 사용을 참고하세요.