All Products
Search
Document Center

Use an instance RAM role by calling API operations

Last Updated: Nov 26, 2021

You can bind an instance Resource Access Management (RAM) role to an elastic container instance. Then, applications on the elastic container instance can access APIs of other cloud services by using a temporary security token service (STS) token. This topic describes how to create an instance RAM role, attach a policy to the role, and then assign the role to an elastic container instance by calling API operations.

Scenarios

Applications on elastic container instances can use an AccessKey pair of an Alibaba Cloud account or a RAM user to access the APIs of other Alibaba Cloud services such as Object Storage Service (OSS), Virtual Private Cloud (VPC), and ApsaraDB RDS. To call API operations in an efficient manner, some users specify AccessKey pairs in an elastic container instance. For example, the users write AccessKey pairs in the configuration file of the elastic container instance. However, this method may cause issues such as information leakage and complex maintenance. This method may also cause unnecessary permissions to be granted. You can use instance RAM roles to prevent similar issues.

A RAM role is a virtual user that has specific permissions. When an elastic container instance assumes a RAM role, the instance has the permissions of the RAM role. You do not need to save the AccessKey pair of the RAM role in the elastic container instance. If you want to modify the permissions of an elastic container instance, you need only to modify the permissions of the RAM role. This way, operations are simplified and issues such as information leakage are prevented. For more information about RAM roles, see RAM role overview.

Procedure

To use an instance RAM role, perform the following operations:

  1. Create an instance RAM role

    You can call the CreateRole operation to create an instance RAM role. In the configuration file, you must set the trusted service to ECS to allow an elastic container instance to assume the RAM role.

  2. Attach a policy to the RAM role

    You can call the CreatePolicy operation to create a policy, and then call the AttachPolicyToRole operation to attach the policy to the instance RAM role.

  3. (Optional) Authorize a RAM user to use the instance RAM role

    Before you use a RAM user to create an elastic container instance and assign an instance RAM role to the instance, you must authorize the RAM user to use the instance RAM role.

  4. Assign the instance RAM role to an elastic container instance

    When you call the CreateContainerGroup operation to create an elastic container instance, you can use the RamRoleName parameter to assign the instance RAM role to the elastic container instance. This way, the instance obtains the permissions of the RAM user. An elastic container instance can assume only one instance RAM role.

  5. (Optional) Obtain a temporary access token

    After you assign an instance RAM role to an elastic container instance, you must obtain a temporary access token if you want to access the APIs of other Alibaba Cloud services from applications on the elastic container instance. The temporary access token is granted by the instance RAM role and is displayed in the instance metadata.

Create an instance RAM role

You can call the CreateRole operation to create an instance RAM role. For information about the parameters, see CreateRole.

You can use the RoleName parameter to specify a role name. The ECIRamRoleTest name is used in the example. Then, configure AssumeRolePolicyDocument based on the following code.

{
"Statement": [
{
  "Action": "sts:AssumeRole",
  "Effect": "Allow",
  "Principal": {
    "Service": [
      "ecs.aliyuncs.com"
    ]
  }
}
],
"Version": "1"
}

Attach a policy to the RAM role

  1. Call the CreatePolicy operation to create a custom policy.

    Configure the following parameters in the request:

    • PolicyName: the name of the policy. The ECIRamRoleTestPolicy name is used in the example.

    • PolicyDocument: the details about the policy.

      {
           "Statement": [
               {
               "Action": [
                   "oss:Get*",
                   "oss:List*"
               ],
               "Effect": "Allow",
               "Resource": "*"
               }
           ],
           "Version": "1"
       }

    For more information, see CreatePolicy.

  2. Call the AttachPolicyToRole operation to attach the policy to the RAM role.

    Configure the following parameters in the request:

    • PolicyName: the name of the policy. The ECIRamRoleTestPolicy name is used in the example.

    • PolicyType: the type of the policy. Set this parameter to Custom.

    • RoleName: the name of the RAM role. The ECIRamRoleTest name is used in the example.

    For more information, see AttachPolicyToRole.

Authorize a RAM user to use the instance RAM role

If you want a RAM user to use an instance RAM role, you must grant the ram:PassRole permission of the instance RAM role to the RAM user. If the RAM user does not have the ram:PassRole permission, the RAM user cannot exercise the permissions that are specified in role policies.

  1. Log on to the RAM console by using a RAM user that has administrator permissions or by using an Alibaba Cloud account.

  2. Authorize the RAM user to use the instance RAM role.

    To authorize the RAM user to use the instance RAM role, create the following custom policy and attach the policy to the RAM user. ECIRamRoleTest is the name of the RAM role. The ram:PassRole permission of the RAM role is to be granted to the RAM user. For more information, see Grant permissions to a RAM user.

    {
       "Statement": [
        {
          "Effect": "Allow",
          "Action": "ram:PassRole",
          "Resource": "acs:ram:*:*:role/ECIRamRoleTest" 
        }
      ],
      "Version": "1"
    }                

Assign the instance RAM role to an elastic container instance

When you call the CreateContainerGroup operation to create an elastic container instance, you can use the RamRoleName parameter to specify the RAM role.

Note

An elastic container instance can assume only one instance RAM role. If an instance RAM role is assigned to an instance, an error message appears when you attempt to assign another instance RAM role to the instance.

Obtain a temporary access 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.

Run the following command to query the temporary access token of the ECIRamRoleTest RAM role:

curl http://100.100.100.200/latest/meta-data/ram/security-credentials/ECIRamRoleTest

The command output contains the temporary access token. The following code provides an example of the command output.

{
"AccessKeyId" : "STS.J8XXXXXXXXXX4",
"AccessKeySecret" : "9PjfXXXXXXXXXBf2XAW",
"Expiration" : "2021-06-09T09:17:19Z",
"SecurityToken" : "CAIXXXXXXXXXXXwmBkleCTkyI+",
"LastUpdated" : "2021-06-09T03:17:18Z",
"Code" : "Success"
}