This topic describes how to create an instance RAM role, attach a policy to the RAM role, and then attach the RAM role to an Elastic Compute Service (ECS) instance by calling API operations.

Prerequisites

The Resource Access Management (RAM) service is activated. For more information, see Activate RAM.

Background information

The following limits apply:
  • Instance RAM roles can be attached only to ECS instances in virtual private clouds (VPCs).
  • Only one instance RAM role can be attached to a single ECS instance at a time.
  • If you have attached an instance RAM role to an ECS instance and want to access the APIs of other Alibaba Cloud services from applications deployed on the instance, you must obtain a temporary authorization token for the instance RAM role by using the instance metadata. For more information, see Obtain a temporary authorization token.
  • If you want to use an instance RAM role as a RAM user, you must use the Alibaba Cloud account to authorize the RAM user to use the instance RAM role. For more information, see Authorize a RAM user to use an instance RAM role.

Procedure

Step 1: Create an instance RAM role

Call the CreateRole operation to create an instance RAM role.

Set the RoleName parameter. In this example, set this parameter to EcsRamRoleDocumentTesting.

Set the AssumeRolePolicyDocument parameter based on the following policy: 
{
     "Statement": [
     {
         "Action": "sts:AssumeRole",
         "Effect": "Allow",
         "Principal": {
         "Service": [
         "ecs.aliyuncs.com"
         ]
         }
     }
     ],
     "Version": "1"
 }

Step 2: Attach a policy to the instance RAM role

  1. Call the CreatePolicy operation to create an authorization policy.
    • Set the RoleName parameter. In this example, set this parameter to EcsRamRoleDocumentTestingPolicy.
    • Set the PolicyDocument parameter based on the following policy: 
      {
     "Statement": [
         {
         "Action": [
             "oss:Get*",
             "oss:List*"
         ],
         "Effect": "Allow",
         "Resource": "*"
         }
     ],
     "Version": "1"
 }
  2. Call the AttachPolicyToRole operation to attach the policy to the role.
    • Set the PolicyType parameter to Custom.
    • Set the PolicyName parameter. In this example, set this parameter to EcsRamRoleDocumentTestingPolicy.
    • Set the RoleName parameter. In this example, set this parameter to EcsRamRoleDocumentTesting.

Step 3: Attach the instance RAM role to an instance

Call the AttachInstanceRamRole operation to attach the instance RAM role to an instance.

  • Set the RegionId and InstanceIds parameters to specify an ECS instance.
  • Set the RamRoleName parameter. In this example, set this parameter to EcsRamRoleDocumentTesting.

Step 4: (Optional) Detach the instance RAM role from the instance

Call the DettachInstanceRamRole operation to detach the instance RAM role from the instance.

  • Set the RegionId and InstanceIds parameters to specify the ECS instance.
  • Set the RamRoleName parameter. In this example, set this parameter to EcsRamRoleDocumentTesting.

Step 5: (Optional) Obtain a temporary authorization token

You can obtain a temporary access token from the instance RAM role. The token is automatically updated on a regular basis and allows you to exercise the permissions and use the resources of the instance RAM role. You can perform the following operations:

Query the temporary authorization token of the instance RAM role named EcsRamRoleDocumentTesting.
  • Linux ECS instance: Run the curl http://100.100.100.200/latest/meta-data/Ram/security-credentials/EcsRamRoleDocumentTesting command.
  • Windows ECS instance: For more information, see Overview of ECS instance metadata.
Obtain the temporary authorization token. A command output similar to the following one is returned. 
{
"AccessKeyId" : "XXXXXXXXX",
"AccessKeySecret" : "XXXXXXXXX",
"Expiration" : "2017-11-01T05:20:01Z",
"SecurityToken" : "XXXXXXXXX",
"LastUpdated" : "2017-10-31T23:20:01Z",
"Code" : "Success"
}

Step 6: (Optional) Authorize a RAM user to use the instance RAM role

Note When you authorize a RAM user to use an instance RAM role, you must grant the RAM user the PassRole permission on the instance RAM role. If the RAM user does not have the PassRole permission, the RAM user cannot exercise the permissions specified in role policies.
  1. Log on to the RAM console.
  2. Authorize a RAM user to use the instance RAM role. For more information, see Grant permissions to a RAM user. 
    {
        "Version": "2016-10-17",
        "Statement": [
            {
            "Effect": "Allow",
            "Action": [
                "ecs: [ECS RAM Action]",
                "ecs: CreateInstance",
                "ecs: AttachInstanceRamRole",
                "ecs: DetachInstanceRAMRole"
            ],
            "Resource": "*"
            },
            {
        "Effect": "Allow",
        "Action": "ram:PassRole",
        "Resource": "*"
            }
        ]
}

    [ECS RAM Action] indicates permissions that can be granted to the RAM user. For more information, see Authentication rules.