全部产品
Search
文档中心

云服务器 ECS:实例RAM角色

更新时间:Mar 31, 2025

实例RAM角色是指为ECS实例授予的RAM角色,该RAM角色是一个信任主体为云服务器的普通服务角色。使用实例RAM角色可以实现在ECS实例内部无需配置AccessKey即可获取临时访问凭证(STS Token),从而调用其他云产品的API。由于临时身份凭证仅可在实例内部获取,并且无需配置AccessKey,这不仅确保了云账号AccessKey的安全性,还能够通过访问控制RAM实现精细化的控制与权限管理。

功能优势

  • 安全便捷的实例内API调用方案:当您的项目部署在阿里云ECS上时,无需在代码中配置AccessKey,即可利用ECS提供的能力获取临时身份凭证(STS Token)以调用API,从而降低AccessKey泄漏的风险。

  • 简化RAM身份切换流程:如果您使用的是传统的AccessKey方案,当需要更换调用服务的RAM身份时,需对配置或者代码进行修改并重启服务。而采用实例RAM角色后,仅需调整授予ECS实例的RAM角色即可实现身份切换,无需进行其他任何更改。

  • 精细化管理权限:可以为不同的ECS实例分配具有特定授权策略的RAM角色,从而实现根据业务需求进行精细化的访问控制。

使用限制

为ECS实例授予RAM角色时存在以下限制:

  • ECS实例的网络类型必须是专有网络VPC。

  • 一台ECS实例只能被授予一个RAM角色。

实现流程

如您使用阿里云账号(主账号)操作,可忽略以下授权内容,若您使用RAM用户或RAM角色执行后续操作,请为对应的用户身份授予以下权限。

权限示例

该权限主要包含以下权限内容:

  • 管理RAM角色:需要创建RAM角色并授权。

  • 授予/回收RAM角色:需要进入实例详情页对实例做授予/回收RAM角色的操作。

  • 允许传递角色给云产品:给云服务授予角色需要配合ram:PassRole权限。

{ "Version": "1", "Statement": [ { "Effect": "Allow", "Action": [ "ecs:Describe*", "ecs:List*", "ecs:AttachInstanceRamRole", "ecs:DetachInstanceRAMRole" ], "Resource": "*" }, { "Effect": "Allow", "Action": [ "ram:Describe*", "ram:List*", "ram:Get*", "ram:CreateRole", "ram:CreatePolicy", "ram:AttachPolicyToRole" ], "Resource": "*" }, { "Effect": "Allow", "Action": "ram:PassRole", "Resource": "*" } ] }

创建RAM角色并授予给ECS实例

通过控制台创建和授予

  1. 登录RAM控制台,创建RAM角色并授权。

    1. 创建可信实体为阿里云服务的RAM角色。

      选择身份管理 > 角色,单击创建角色,按照界面提示完成角色创建。注意以下参数(其他参数按需填写,可参见创建普通服务角色):

      • 信任主体类型:选择云服务

      • 信任主体名称:选择云服务器image

    2. 为已创建的RAM角色授权。

      将系统策略或已创建的自定义权限策略授权给RAM角色,使其拥有相关的资源访问或操作权限。例如,给RAM角色授予系统策略(AliyunOSSReadOnlyAccess)。

      说明

      若系统策略无法满足您的需求,您可以通过创建自定义策略为RAM角色授权。具体操作,请参见创建自定义权限策略

  2. 为ECS实例授予RAM角色。

    1. 登录ECS管理控制台

    2. 在左侧导航栏,选择实例与镜像 > 实例

    3. 在页面左侧顶部,选择目标资源所在的资源组和地域。地域

    4. 找到要操作的ECS实例,选择图标 > 实例设置 > 授予/收回RAM角色

    5. 在对话框中,选择创建好的实例RAM角色,单击确定

通过API创建和授予

  1. 创建RAM角色并授权。

    1. 调用CreateRole接口创建RAM角色。

      信任策略参数(AssumeRolePolicyDocument):

      { "Statement": [ { "Action": "sts:AssumeRole", "Effect": "Allow", "Principal": { "Service": [ "ecs.aliyuncs.com" ] } } ], "Version": "1" }
    2. (可选)调用CreatePolicy接口新建权限策略。

      如果您已有可用权限策略,可跳过该步骤。

      PolicyDocument(权限策略)需按如下设置:

      { "Statement": [ { "Action": [ "oss:Get*", "oss:List*" ], "Effect": "Allow", "Resource": "*" } ], "Version": "1" }
    3. 调用AttachPolicyToRole接口为实例RAM角色授权。

  2. 调用AttachInstanceRamRole接口将RAM角色授予ECS实例。

获取实例RAM角色的临时身份凭证

您可以在ECS实例内部通过访问元数据服务(Meta Data Service)获取到临时访问凭证,同时会确保临时访问凭证的有效性。更多关于元数据的介绍,请参见实例元数据

方式一:在程序中通过Credentials工具获取

Credentials工具封装了调用ECS的元数据服务(Meta Data Service)获取临时访问凭证STS Token的逻辑,且支持周期性更新。

Python
  1. 安装Credentials工具。

    说明

    若使用加固模式获取临时身份凭证,alibabacloud_credentials的版本应不低于0.3.6。

    pip install alibabacloud_credentials
  2. 配置ECS的RAM角色作为访问凭证。

    from alibabacloud_credentials.client import Client as CredClient from alibabacloud_credentials.models import Config as CredConfig credentialsConfig = CredConfig(	type='ecs_ram_role',	# 选填,该ECS角色的角色名称,不填会自动获取,但是建议加上以减少请求次数,可以通过环境变量ALIBABA_CLOUD_ECS_METADATA设置role_name	role_name='<role_name>',	# 选填,默认值:False。True:表示强制使用加固模式。False:系统将首先尝试在加固模式下获取凭据。如果失败,则会切换到普通模式进行尝试(IMDSv1)。	enable_imds_v1=True, ) credentialsClient = CredClient(credentialsConfig) 

    更多详细信息及调用示例,请参见方式五:使用ECS实例RAM角色

Java

  1. 添加credentials依赖。

    说明

    若使用加固模式获取临时身份凭证,credentials-java的版本不低于0.3.10。

    <!-- https://mvnrepository.com/artifact/com.aliyun/credentials-java --> <dependency> <groupId>com.aliyun</groupId> <artifactId>credentials-java</artifactId> <version>0.3.10</version> </dependency>
  2. 配置ECS实例RAM角色作为访问凭证。

    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"); // 选填,该ECS角色的角色名称,不填会自动获取,但是建议加上以减少请求次数,可以通过环境变量ALIBABA_CLOUD_ECS_METADATA设置RoleName credentialConfig.setRoleName("<RoleName>"); // 选填,默认值:false。true:表示强制使用加固模式。false:系统将首先尝试在加固模式下获取凭据。如果失败,则会切换到普通模式进行尝试(IMDSv1)。 credentialConfig.setDisableIMDSv1(true); Client credentialClient = new Client(credentialConfig); } }

    更多详细信息及调用示例,请参见方式五:使用ECS实例RAM角色

Go

  1. 安装Credentials工具。

    说明

    若使用加固模式获取临时身份凭证,credentials-go的版本不低于1.3.10。

    • 使用go get下载安装。

      go get -u github.com/aliyun/credentials-go
    • 如果您使用dep来管理依赖包,您可以使用以下命令。

      dep ensure -add github.com/aliyun/credentials-go
  2. 配置ECS实例RAM角色作为访问凭证。

    package main import (	"fmt"	"github.com/aliyun/credentials-go/credentials" ) func _main(args []*string) {	credentialsConfig := new(credentials.Config).	SetType("ecs_ram_role").	// 选填,该ECS角色的角色名称,不填会自动获取,但是建议加上以减少请求次数,可以通过环境变量ALIBABA_CLOUD_ECS_METADATA设置RoleName	SetRoleName("<RoleName>").	// 选填,默认值:false。true:表示强制使用加固模式。false:系统将首先尝试在加固模式下获取凭据。如果失败,则会切换到普通模式进行尝试(IMDSv1)。	SetDisableIMDSv1(true)	credentialClient, err := credentials.NewCredential(credentialsConfig)	if err != nil {	panic(err)	} }

    更多详细信息及调用示例,请参见方式五:使用ECS实例RAM角色

Node.js

  1. 安装Credentials工具。

    说明

    若使用加固模式获取临时身份凭证,credentials的版本不低于2.3.1。

    npm install @alicloud/credentials
  2. 配置ECS实例RAM角色作为访问凭证。

    const Credential = require('@alicloud/credentials'); const credentialsConfig = new Credential.Config({ type: 'ecs_ram_role', // 选填,该ECS角色的角色名称,不填会自动获取,但是建议加上以减少请求次数,可以通过环境变量ALIBABA_CLOUD_ECS_METADATA设置roleName roleName: '<RoleName>', // 选填,默认值:false。true:表示强制使用加固模式。false:系统将首先尝试在加固模式下获取凭据。如果失败,则会切换到普通模式进行尝试(IMDSv1)。 disableIMDSv1: true, }); const cred = new Credential.default(credentialsConfig); 

    更多详细信息及调用示例,请参见方式五:使用ECS实例RAM角色

.NET

  1. 安装Credentials工具。

    说明

    若使用加固模式获取临时身份凭证,credentials的版本不低于1.4.2。

    dotnet add package Aliyun.Credentials
  2. 配置ECS实例RAM角色作为访问凭证。

    using Aliyun.Credentials.Models; namespace credentials_demo { class Program { static void Main(string[] args) { var config = new Config() { Type = "ecs_ram_role",	// 选填,该ECS角色的角色名称,不填会自动获取,但是建议加上以减少请求次数,可以通过环境变量ALIBABA_CLOUD_ECS_METADATA设置RoleName RoleName = "<RoleName>", // 选填,默认值:false。true:表示强制使用加固模式。false:系统将首先尝试在加固模式下获取凭据。如果失败,则会切换到普通模式进行尝试(IMDSv1)。 DisableIMDSv1 = true } } } }

    更多详细信息及调用示例,请参见方式五:使用ECS实例RAM角色

PHP

  1. 安装Credentials工具。

    说明

    若使用加固模式获取临时身份凭证,credentials的版本不低于1.2.0。

    composer require alibabacloud/credentials
  2. 配置ECS实例RAM角色作为访问凭证。

    <?php use AlibabaCloud\Credentials\Credential; use AlibabaCloud\Credentials\Credential\Config; $credConfig = new Config([ 'type' => 'ecs_ram_role', // 选填,该ECS角色的角色名称,不填会自动获取,但是建议加上以减少请求次数,可以通过环境变量ALIBABA_CLOUD_ECS_METADATA设置role_name 'roleName' => '<RoleName>', // 选填,默认值:false。true:表示强制使用加固模式。false:系统将首先尝试在加固模式下获取凭据。如果失败,则会切换到普通模式进行尝试(IMDSv1)。 'disableIMDSv1' => true, ]);

    更多详细信息及调用示例,请参见方式五:使用ECS实例RAM角色

方式二:通过Shell命令获取

元数据服务提供HTTP访问地址获取临时访问凭据。

加固模式

  • Linux实例

    # 获取元数据服务器的访问凭证用于鉴权 TOKEN=`curl -X PUT "http://100.100.100.200/latest/api/token" -H "X-aliyun-ecs-metadata-token-ttl-seconds:<元数据服务器访问凭证有效期>"` # 获取实例RAM角色的临时授权访问凭证 curl -H "X-aliyun-ecs-metadata-token: $TOKEN" http://100.100.100.200/latest/meta-data/ram/security-credentials/<实例RAM角色名称>
  • Windows实例(Powershell)

    # 获取元数据服务器的访问凭证用于鉴权 $token = Invoke-RestMethod -Headers @{"X-aliyun-ecs-metadata-token-ttl-seconds" = "<元数据服务器的访问凭证有效期>"} -Method PUT -Uri http://100.100.100.200/latest/api/token # 获取实例RAM角色的临时授权访问凭证 Invoke-RestMethod -Headers @{"X-aliyun-ecs-metadata-token" = $token} -Method GET -Uri http://100.100.100.200/latest/meta-data/ram/security-credentials/<实例RAM角色名称>

<元数据服务器的访问凭证有效期>:在获取实例RAM角色的临时授权访问凭证之前,先获取元数据服务器的访问凭证并设置其有效期,以加强数据安全。超过有效期后,需要重新获取凭证,否则无法获取实例RAM角色的临时授权访问凭证。

取值范围为1~21600,单位为秒。详细说明,请参见实例元数据

<实例RAM角色名称>需替换为具体的实例RAM角色名称。例如EcsRamRole

说明

若您是使用云助手执行上述命令时,云助手Agent的最低版本要求如下:

平台

云助手Agent版本号

windows

2.1.3.857

linux

2.2.3.857

linux arm

2.4.3.857

freebsd

2.3.3.857

普通模式

  • Linux实例

    curl http://100.100.100.200/latest/meta-data/ram/security-credentials/<实例RAM角色名称>
  • Windows实例(Powershell)

    Invoke-RestMethod http://100.100.100.200/latest/meta-data/Invoke-RestMethod http://100.100.100.200/latest/meta-data/ram/security-credentials/<实例RAM角色名称>

    <实例RAM角色名称>需替换为具体的实例RAM角色名称。例如EcsRamRoleDocumentTesting。

返回示例如下,其中:

  • AccessKeyIdAccessKeySecretSecurityToken共同构成了临时访问令牌。

  • Expiration:临时授权访问凭证的有效期。

    { "AccessKeyId" : "STS.*******6YSE", "AccessKeySecret" : "aj******jDU", "Expiration" : "2017-11-01T05:20:01Z", "SecurityToken" : "CAISng********", "LastUpdated" : "2023-07-18T14:17:28Z", "Code" : "Success" }

方式三:通过阿里云CLI获取

CLI支持通过调用ECS的元数据服务(Meta Data Service)获取临时访问凭证STS Token的逻辑,且支持周期性自动刷新。

说明

若使用加固模式获取临时身份凭证,CLI的版本不低于3.0.248。

  1. 安装CLI。

  2. 配置身份凭据。

    执行如下命令配置凭证信息,其中<ProfileName>为配置的名称:

    aliyun configure --profile <ProfileName> --mode EcsRamRole

    该命令为交互式命令,需要您根据提示输出相应信息。更多信息请参见EcsRamRole

  3. 调用API。

    例如使用CLI查询ECS实例列表。

     aliyun ecs DescribeInstances

    更多关于CLI命令的说明,请参见命令结构

使用实例RAM角色调用API

下文以部署在Linux ECS实例上的Python应用程序调用OSS下载文件接口为例,为您介绍ECS实例RAM角色的使用方法。

pip install oss2 pip install alibabacloud_credentials
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', # 访问凭证类型。固定为ecs_ram_role。 role_name=role_name ) cred = Client(config) credentials_provider = CredentialProviderWarpper(cred) auth = oss2.ProviderAuth(credentials_provider) # 初始化 OSS Bucket 对象 bucket = oss2.Bucket(auth, endpoint, bucket_name) # 下载图片到本地 bucket.get_object_to_file(object_key, local_file) print("Image downloaded successfully") if __name__ == "__main__": # 定义全局变量 role_name = 'role_name' # 需替换为实例RAM角色名称 bucket_name = 'bucket_name' # 需替换为Bucket名称 endpoint = 'oss-cn-beijing.aliyuncs.com' # 需替换为OSS Bucket的外网Endpoint object_key = 'testfolder/example.png' # 需替换为你要下载的图片在OSS中的完整存储路径(不包含Bucket名称) local_file = '/localpath/to/image.png' # 需替换为图片需要在ECS上存储的根路径,并定义图片名称 download_image_using_instance_role(bucket_name, endpoint, object_key, local_file, role_name) 

其他操作

收回/更改ECS的实例RAM角色

通过控制台收回/更改

  1. 登录ECS管理控制台

  2. 在左侧导航栏,选择实例与镜像 > 实例

  3. 在页面左侧顶部,选择目标资源所在的资源组和地域。地域

  4. 找到要操作的ECS实例,选择图标 > 实例设置 > 授予/收回RAM角色

    • 收回实例RAM角色:操作类型选择收回,单击确定

    • 更改实例RAM角色:操作类型选择授予,选择所需的实例RAM角色,单击确定完成更改。

      image.png

通过API收回/更改

相关文档

  • 当您的自建应用部署在阿里云ECS服务器上,且需要访问KMS应用时,可以使用ECS实例RAM角色访问KMS。具体操作,请参见使用ECS实例RAM角色安全访问KMS

  • 当ECS不需要某些资源访问权限时,可以通过移除实例RAM角色的权限来实现。具体操作,请参见为RAM角色移除权限

  • 访问阿里云OpenAPI时,如果在代码中硬编码明文AK,容易因代码仓库权限管理不当造成AK泄露,建议您通过非AccessKey硬编码的方式编程,使用访问凭证访问阿里云OpenAPI,可参见使用访问凭据访问阿里云OpenAPI最佳实践