To access resources of other Alibaba Cloud services, Elastic Compute Service (ECS) instances or applications that are deployed on the instances must have the corresponding access credentials. Alibaba Cloud services use the access credentials to authenticate the identities and permissions of the ECS instances or the applications deployed on the instances. You can attach an instance Resource Access Management (RAM) role to an ECS instance. The ECS instance and the applications that are deployed on the instance can automatically obtain and refresh temporary access credentials from within the instance to access the resources of other Alibaba Cloud services without exposing AccessKey pairs. This reduces the risk of AccessKey pair leaks and allows RAM role-based, fine-grained management of access permissions on resources to prevent excessive permissions from being granted. This topic describes how to create an instance RAM role, attach the instance RAM role to an ECS instance, and obtain temporary access credentials based on the instance RAM role.
An instance RAM role is a type of RAM role whose trusted entity is an Alibaba Cloud service. This type of RAM role is used to grant access across Alibaba Cloud services and can be assumed by Alibaba Cloud services. For information about RAM roles, see the What is a RAM role? section of the "RAM role overview" topic.
Benefits
You can obtain the following benefits when you use instance RAM roles to obtain temporary access credentials for authentication and access control:
Enhanced communication security: You can use Security Token Service (STS) tokens instead of AccessKey pairs to access resources, which reduces the risk of AccessKey pair leaks.
Cross-service access and fine-grained permission management: You can attach instance RAM roles that include different policies to grant ECS instances access only to specific resources based on the principle of least privilege.
Simplified permission maintenance: You can modify the policies of instance RAM roles that are attached to ECS instances to modify and manage the access permissions of the instances without the need to manage credentials on the instances.
Limits
Take note of the following limits when you attach instance RAM roles to ECS instances:
You must deploy the ECS instances in virtual private clouds (VPCs).
You can attach only one instance RAM role to an ECS instance.
Procedure
Create an instance RAM role and attach the instance RAM role to an ECS instance
Create an instance RAM role and grant the instance RAM role the required permissions to access specific Alibaba Cloud services. For example, to allow the ECS instance to access Object Storage Service (OSS), you must grant the instance RAM role the permissions to read data from and write data to OSS.
If you use a RAM user to perform the procedure that is described in this topic, make sure that the RAM user is granted the permissions to use and configure instance RAM roles. For more information, see Grant RAM users permissions to use ECS resources.
Use the consoles
Log on to the RAM console to create an instance RAM role and grant permissions to the instance RAM role.
Create a RAM role whose trusted entity is an Alibaba Cloud service.
In the left-side navigation pane, choose Identities > Roles. On the Roles page, click Create Role. On the Create Role page, set the following parameters to specific values and configure other parameters based on your business requirements. For information about the parameter settings, see the Create a regular service role section of the "Create a RAM role for a trusted Alibaba Cloud service" topic.
Select Trusted Entity: Select Alibaba Cloud Service.
Role Type: Select Normal Service Role.
Select Trusted Service: Select Elastic Compute Service.
Grant permissions to the instance RAM role.
Attach system policies or custom policies that you created to the instance RAM role to grant the instance RAM role permissions to access or manage specific resources. For example, you can attach the AliyunOSSReadOnlyAccess policy to grant the instance RAM role the permissions to read data from and write data to OSS.
NoteYou can attach system policies or custom policies to the instance RAM role. If system policies do not meet your business requirements, you can create custom policies. For more information, see Create custom policies.
Attach the instance RAM role to an ECS instance.
Log on to the ECS console.
In the left-side navigation pane, choose .
In the top navigation bar, select the region and resource group to which the resource belongs.
Find the ECS instance to which you want to attach the instance RAM role and choose
in the Actions column.In the Attach/Detach RAM Role dialog box, select the instance RAM role that you created from the RAM Role drop-down list and click Confirm.
Call API operations
Create and configure an instance RAM role.
Call the CreateRole operation to create an instance RAM role.
Set the AssumeRolePolicyDocument parameter to the following policy:
{ "Statement": [ { "Action": "sts:AssumeRole", "Effect": "Allow", "Principal": { "Service": [ "ecs.aliyuncs.com" ] } } ], "Version": "1" }
(Optional) Call the CreatePolicy operation to create a policy.
If you already have a policy that can be attached to the instance RAM role, skip this step.
Set the
PolicyDocument
parameter to the following policy:{ "Statement": [ { "Action": [ "oss:Get*", "oss:List*" ], "Effect": "Allow", "Resource": "*" } ], "Version": "1" }
Call the AttachPolicyToRole operation to attach the policy to the instance RAM role.
Call the AttachInstanceRamRole operation to attach the instance RAM role to an ECS instance.
Use an instance RAM role to get temporary access credentials
After applications deployed on an ECS instance get temporary access credentials to access other Alibaba Cloud services, the applications leverage the temporary access credentials to call API operations in a secure manner to access or manage data across Alibaba Cloud services. The temporary access credentials are automatically updated on a periodic basis.
Method 1: Use the Alibaba Cloud Credentials tool in a SDK
The Alibaba Cloud Credentials tool obtains the instance RAM roles that are attached to ECS instances and then calls the metadata service (metadata server) of ECS to obtain STS tokens as temporary access credentials based on the instance RAM roles. The temporary access credentials are updated on a periodic basis.
The following sample code provides examples on how to use the Alibaba Cloud Credentials tool in SDK for Python and SDK for Java. To view the sample code for SDKs in other programming languages, see the Sample code section of the "Best practices for using an access credential to call API operations" topic.
Python
Install the Alibaba Cloud Credentials tool.
sudo pip install alibabacloud_credentials
Configure the ECS instance to use the instance RAM role to obtain temporary access credentials.
from alibabacloud_credentials.client import Client as CredClient from alibabacloud_credentials.models import Config as CredConfig credentialConfig = CredConfig( type='ecs_ram_role', # Optional. Specify the name of the RAM role of the ECS instance. If you do not specify this parameter, its value is automatically obtained. To reduce the number of requests, we recommend that you specify this parameter. role_name='<RoleName>' ) credentialsClient = CredClient(credentialConfig)
Java
Add the dependencies of credentials.
<!-- https://mvnrepository.com/artifact/com.aliyun/credentials-java --> <dependency> <groupId>com.aliyun</groupId> <artifactId>credentials-java</artifactId> <version>0.3.4</version> </dependency>
Configure the ECS instance to use the instance RAM role to obtain temporary access credentials.
import com.aliyun.credentials.Client; import com.aliyun.credentials.models.Config; public class DemoTest { public static void main(String[] args) throws Exception { Config credentialConfig = new Config(); credentialConfig.setType("ecs_ram_role"); // Optional. Specify the name of the RAM role of the ECS instance. If you do not specify this parameter, the value is automatically obtained. To reduce the number of requests, we recommend that you specify this parameter. credentialConfig.setRoleName("<RoleName>"); Client credentialClient = new Client(credentialConfig); } }
Method 2: Get temporary access credentials within an ECS instance by using metadata
In specific scenarios, if you do not have or cannot use the Alibaba Cloud Credentials tool or you want to obtain temporary access credentials based on instance RAM roles in a script, you can access the metadata server from within ECS instances.
You can access the metadata server to obtain instance metadata from within ECS instances without the need to log on to the ECS console or call API operations. For more information, see Obtain instance metadata.
Security hardening mode
Linux instance
# Obtain the access credentials of the metadata server for authentication. TOKEN=`curl -X PUT "http://100.100.100.200/latest/api/token" -H "X-aliyun-ecs-metadata-token-ttl-seconds:<Validity period of the metadata server access credentials>"` # Obtain temporary access credentials for the instance RAM role. curl -H "X-aliyun-ecs-metadata-token: $TOKEN" http://100.100.100.200/latest/meta-data/ram/security-credentials/<Name of the instance RAM role>
Windows instance (PowerShell)
# Obtain the access credentials of the metadata server for authentication. $token = Invoke-RestMethod -Headers @{"X-aliyun-ecs-metadata-token-ttl-seconds" = "<Validity period of the metadata server access credentials>"} -Method PUT –Uri http://100.100.100.200/latest/api/token # Obtain temporary access credentials for the instance RAM role. Invoke-RestMethod -Headers @{"X-aliyun-ecs-metadata-token" = $token} -Method GET -Uri http://100.100.100.200/latest/meta-data/ram/security-credentials/<Name of the instance RAM role>
<Validity period of the metadata server access credentials>
: Before you can obtain temporary access credentials for the instance RAM role, you must obtain the access credentials of the metadata server and specify a validity period for the credentials to increase data security. After the specified validity period ends, you must re-obtain the access credentials of the metadata server. Otherwise, you cannot obtain temporary access credentials for the instance RAM role.
Valid values: 1 to 21600. Unit: seconds. For more information, see Obtain instance metadata.
<Name of the instance RAM role>
: Replace <Name of the instance RAM role> with an actual value. Example: EcsRamRoleDocumentTesting.
Normal mode
Linux instance
curl http://100.100.100.200/latest/meta-data/ram/security-credentials/<Name of the instance RAM role>
Windows instance (PowerShell)
Invoke-RestMethod http://100.100.100.200/latest/meta-data/Invoke-RestMethod http://100.100.100.200/latest/meta-data/ram/security-credentials/<Name of the instance RAM role>
Replace
<Name of the instance RAM role>
with an actual value. Example: EcsRamRoleDocumentTesting.
The following code snippet shows a sample response.
SecurityToken
: indicates the temporary access credentials of the instance RAM role.Expiration
: indicates the time when the temporary access credentials of the instance RAM role expire.{ "AccessKeyId" : "STS.*******6YSE", "AccessKeySecret" : "aj******jDU", "Expiration" : "2017-11-01T05:20:01Z", "SecurityToken" : "CAISng********", "LastUpdated" : "2023-07-18T14:17:28Z", "Code" : "Success" }
Detach or change an instance RAM role
Use the ECS console
Log on to the ECS console.
In the left-side navigation pane, choose .
In the top navigation bar, select the region and resource group to which the resource belongs.
Find the ECS instance that you want to manage and choose
in the Actions column.To detach the instance RAM role that is attached to the ECS instance, set the Action parameter to Detach and click Confirm.
To change the instance RAM role that is attached to the ECS instance, set the Action parameter to Attach, select a different instance RAM role from the RAM Role drop-down list, and then click Confirm.
Call API operations
To detach an instance RAM role from an ECS instance, call the DettachInstanceRamRole operation.
To change the instance RAM role that is attached to an ECS instance, call the following operations:
Call the DettachInstanceRamRole operation to detach the instance RAM role from the ECS instance.
Call the AttachInstanceRamRole operation to attach a different instance RAM role to the ECS instance.
Example: Use instance RAM roles to access other Alibaba Cloud services
In this example, a Python application that is deployed on a Linux ECS instance uses an instance RAM role to download an image from OSS.
Complete the preparations.
Create an instance RAM role, attach the AliyunOSSReadOnlyAccess policy to the instance RAM role, and then attach the instance RAM role to a Linux ECS instance.
For more information, see the Create an instance RAM role and attach the instance RAM role to an ECS instance section of this topic.
Create an OSS bucket in the region where the ECS instance resides and obtain the name and endpoint of the bucket from the Buckets page. For more information, see Create a bucket.
ImportantIf you want to access OSS over the Internet, make sure that the ECS instance can access the Internet. To allow the ECS instance to access the Internet over IPv4, you can modify the public bandwidth configurations of the ECS instance or associate an elastic IP address (EIP) with the ECS instance. For more information, see Modify the public bandwidth configurations of an instance associated with an auto-assigned public IP address or the Associate one or more EIPs with an instance section of the "Associate or disassociate an EIP" topic.
Upload images to the OSS bucket. For more information, see the Use the OSS console section of the "Simple upload" topic.
Connect to the Linux ECS instance and install OSS SDK for Python and the Alibaba Cloud Credentials tool.
NoteIn this example, an ECS instance that runs an Alibaba Cloud Linux 3 operating system is used. By default, Python 3 is installed on Alibaba Cloud Linux 3. If you use an ECS instance that runs another Linux operating system, change the commands in this section based on the Python version. If you use an ECS instance that runs a Windows operating system, use the procedure described in Installation to install OSS SDK for Python.
Update the pip, setuptools, and wheel tools.
sudo pip3 install --upgrade pip setuptools wheel
Install the Alibaba Cloud Credentials tool.
sudo pip3 install alibabacloud_credentials
Install the python-devel package on which OSS SDK for Python depends.
sudo yum install python3-devel
Install OSS SDK for Python.
sudo pip3 install oss2
Use the temporary access credentials of the instance RAM role to access OSS and download an image.
Compile Python code. Sample Python code (Replace variables with the actual values):
import oss2 from alibabacloud_credentials.client import Client from alibabacloud_credentials.models import Config from oss2 import CredentialsProvider from oss2.credentials import Credentials class CredentialProviderWarpper(CredentialsProvider): def __init__(self, client): self.client = client def get_credentials(self): access_key_id = self.client.get_access_key_id() access_key_secret = self.client.get_access_key_secret() security_token = self.client.get_security_token() return Credentials(access_key_id, access_key_secret, security_token) def download_image_using_instance_role(bucket_name, endpoint, object_key, local_file, role_name): config = Config( type='ecs_ram_role', # Specify the type of access credential. Set this parameter to ecs_ram_role. role_name=role_name ) cred = Client(config) credentials_provider = CredentialProviderWarpper(cred) auth = oss2.ProviderAuth(credentials_provider) # Initialize the OSS bucket. bucket = oss2.Bucket(auth, endpoint, bucket_name) # Download the image. bucket.get_object_to_file(object_key, local_file) print("Image downloaded successfully") if __name__ == "__main__": # Define global variables. role_name = 'role_name' # Specify the name of the instance RAM role. bucket_name = 'bucket_name' # Specify the name of the OSS bucket. endpoint = 'http://oss-cn-beijing-internal.aliyuncs.com' # Specify the endpoint of the OSS bucket. object_key = 'testfolder/example.png' # Specify the path in which the image that you want to download is stored in OSS. The path does not include the bucket name. local_file = '/localpath/to/image.png' # Specify a name for the image and the path in which you want to store the image on the ECS instance. download_image_using_instance_role(bucket_name, endpoint, object_key, local_file, role_name)
References
If your self-managed application is deployed on an ECS instance, you can attach an instance RAM role to the ECS instance and use the instance RAM role to access Key Management Service (KMS) from the instance. For more information, see Use the instance RAM role attached to an ECS instance to securely access KMS.
If an ECS instance no longer requires specific permissions, you can revoke the permissions from the instance RAM role that is attached to the instance. For more information, see Revoke permissions from a RAM role.
If you hard code a plaintext AccessKey pair in the code that you use to call API operations of Alibaba Cloud, the AccessKey pair may be leaked due to improper permission management of the code repository. To call the API operations of Alibaba Cloud, we recommend that you use access credentials instead of a hard-coded AccessKey pair. For more information, see Best practices for using an access credential to call API operations and Credential security solutions.