阿里云CLI通过ECS实例RAM角色（EcsRamRole）自动获取临时凭证，无需配置AccessKey，适用于ECS、ECI实例，是云上环境的推荐认证方式。-阿里云CLI(CLI)-阿里云帮助中心

在 ECS 实例或 ECI 实例上运行阿里云 CLI 时，可使用 EcsRamRole 凭证类型。CLI 通过实例元数据服务（IMDS）自动获取与实例绑定的 RAM 角色的临时安全凭证（STS Token），无需配置 AccessKey，是云上环境的推荐认证方式。本文介绍 EcsRamRole 凭证的前置准备及配置流程。

前提条件

阿里云 CLI 版本 ≥ 3.3.0。运行 aliyun version 查看当前版本，低于此版本时，请参考安装/更新 CLI升级。
CLI 需要安装在 ECS 实例或 ECI 实例上。本地开发环境不支持此凭证类型。
实例已绑定 RAM 角色，且该角色拥有所需资源的访问权限。为ECS和ECI实例授予RAM角色，具体操作请参见创建并为ECS实例授予RAM角色和为ECI实例授予实例RAM角色。

配置凭证

交互式配置

运行以下命令开始配置。将 <ProfileName> 替换为自定义的配置名称（如 EcsProfile）：
```
aliyun configure --mode EcsRamRole --profile <ProfileName>
```

按提示依次输入ECS实例RAM角色名称、默认地域及语言等配置信息：

Configuring profile 'EcsProfile' in 'EcsRamRole' authenticate mode...
Ecs Ram Role []: ecs-role-name
Default Region Id []: cn-shanghai
Default Output Format [json]: json (Only support json)
Default Language [zh|en] en: en
Saving profile[EcsProfile] ...Done.

具体地域请参见地域和可用区。部分云产品不支持跨地域访问，建议您优先将默认地域设置为已购资源所在地域。

终端显示 Configure Done 及欢迎信息，表示配置成功。

非交互式配置

Bash

aliyun configure set \
  --profile EcsProfile \
  --mode EcsRamRole \
  --ram-role-name ECSAdmin \
  --region cn-hangzhou

PowerShell

aliyun configure set `
  --profile EcsProfile `
  --mode EcsRamRole `
  --ram-role-name ECSAdmin `
  --region cn-hangzhou

完整配置参数

参数名称	说明	必填	示例值
`--mode`	固定值 `EcsRamRole`，指定凭证类型。	是	`EcsRamRole`
`--profile`	配置名称。未指定时默认使用当前激活的配置；首次配置默认名称为 `default`。建议使用有意义的名称以便区分多套凭证。	否	`EcsProfile`
`--ram-role-name`	ECS 实例绑定的 RAM 角色名。省略时 CLI 通过 IMDS 自动查询。	否	`ECSAdmin`
`--region`	默认 Region ID。	是	`cn-hangzhou`

说明

配置成功后，该配置自动成为当前激活的配置。如需切换到其他配置，运行 aliyun configure switch --profile <ProfileName> 命令。

验证凭证配置

配置完成后，运行以下命令验证凭证是否生效：

aliyun sts get-caller-identity

输出类似如下，在Arn字段中会包含ECS实例RAM角色名称：

{
  "AccountId": "191317683912****",
  "Arn": "acs:ram::191317683912****:assumed-role/<ecs-role-name>/<role-session-name>",
  "IdentityType": "AssumedRoleUser",
  "PrincipalId": "30004467717606****:<role-session-name>",
  "RequestId": "0FFADC33-EA49-5E2A-977F-0BA820D6****",
  "RoleId": "30004467717606****"
}

凭证的刷新

EcsRamRole 凭证本质是通过 IMDS 服务获取的 STS 临时凭证。凭证的刷新由IMDS服务自动控制，整个过程对用户透明，无需手动干预。

删除凭证

删除 CLI 本地配置中的 EcsRamRole 凭证：

aliyun configure delete --profile <ProfileName>

说明

此命令仅删除 ~/.aliyun/config.json 中的对应配置条目，不会解除实例上的 RAM 角色绑定。如需完全撤销权限，请在 ECS 控制台解绑 RAM 角色。

常见问题

如何确认实例已绑定 RAM 角色？

在实例内运行以下命令查询 IMDS，返回角色信息表示已绑定：

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

若返回为空或 404，说明实例未绑定 RAM 角色。

使用 EcsRamRole 凭证时获取凭证异常怎么办？

阿里云 CLI 默认使用加固模式（IMDSv2）从实例元数据服务获取访问凭据。若获取凭证时发生异常，可通过环境变量 ALIBABA_CLOUD_IMDSV1_DISABLED 控制回退行为：

值为 false（默认）：回退到普通模式（IMDSv1）继续获取凭据。
值为 true：仅允许加固模式，回退失败时直接抛出异常。