# Amazon ECS 托管实例实例配置文件
<a name="managed-instances-instance-profile"></a>

实例配置文件是一个 IAM 容器，它只包含一个 IAM 角色，并允许 Amazon ECS 托管实例安全地代入该角色。实例配置文件包含 ECS 代理代入的实例角色，用于向集群注册实例并与 ECS 服务进行通信。

**重要**  
如果您将 Amazon ECS 托管实例与 `AmazonECSInfrastructureRolePolicyForManagedInstances` 托管策略一起使用，则实例角色名称必须以 `ecsInstanceRole` 开头。该策略将 `iam:PassRole` 的作用范围限定为 `arn:aws:iam::*:role/ecsInstanceRole*`，因此名称不匹配会导致任务启动时出现授权错误。省略 `RoleName` 时，CloudFormation 经常出现这种情况，因为 CloudFormation 会自动生成类似于 `MyStack-InstanceRole-ABC123` 的名称。  
如果您改用自定义基础设施角色策略，则只要您的策略包含针对实例角色 ARN 的 `iam:PassRole` 授权，则实例角色可以具有任何名称。

## 使用信任策略创建角色
<a name="create-instance-role"></a>

将所有{{用户输入}}替换为您自己的信息。

1. 创建一个名为 `ecsInstanceRole-trust-policy.json` 的文件，其中包含要用于 IAM 角色的信任策略。该文件应包含以下内容：

------
#### [ 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 控制台中堆栈的**资源**选项卡下查看自动生成的名称。如果名称不匹配，可以：
+ 将 `RoleName: ecsInstanceRole` 添加到您的 `AWS::IAM::Role` 资源。
+ 将明确的 `iam:PassRole` 内联策略添加到您的基础设施角色。有关更多信息，请参阅 [选项 2：使用自定义角色名称](#create-instance-profile-cfn-custom)。