Authenticate Alibaba Cloud CLI on ECS or ECI instances by using the EcsRamRole credential type. The CLI retrieves temporary credentials from IMDS automatically, with no AccessKey pair required. - Alibaba Cloud CLI

When you run Alibaba Cloud CLI on an ECS instance or an ECI instance, you can authenticate by using the EcsRamRole credential type. The CLI automatically retrieves temporary security credentials (STS tokens) from the Instance Metadata Service (IMDS) for the RAM role attached to your instance. No AccessKey pair is required. This is the recommended authentication method for workloads running on Alibaba Cloud instances. This topic describes the prerequisites and configuration procedure for EcsRamRole credentials.

Prerequisites

Alibaba Cloud CLI version 3.3.0 or later. Run aliyun version to check your version. To upgrade, see Install or update the Alibaba Cloud CLI.
The CLI must be installed on an ECS instance or an ECI instance. Local development environments do not support this credential type.
A RAM role with the required permissions is attached to the instance. For instructions, see Create a RAM role and grant it to an ECS instance and Grant an instance RAM role to an ECI instance.

Configure credentials

Interactive configuration

Run the following command. Replace <ProfileName> with a name for the profile, such as EcsProfile.
```
aliyun configure --mode EcsRamRole --profile <ProfileName>
```

Enter the requested information at each prompt:

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.

For available region IDs, see Regions and availability zones. If a cloud service does not support cross-region access, set the default region to the region where your resources are deployed.

When the terminal displays Configure Done and a welcome message, the configuration is complete.

Non-interactive configuration

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

Full parameters

Parameter	Description	Required	Example
`--mode`	The credential type. Set this to `EcsRamRole`.	Yes	`EcsRamRole`
`--profile`	A name for the credential profile. If omitted, the CLI uses the active profile. The first profile defaults to `default`. Use a descriptive name to distinguish between multiple profiles.	No	`EcsProfile`
`--ram-role-name`	The RAM role attached to the instance. If omitted, the CLI queries the IMDS for the role name automatically.	No	`ECSAdmin`
`--region`	The default region ID.	Yes	`cn-hangzhou`

Note

After you configure a profile, it automatically becomes the active profile. To switch to a different profile, run the aliyun configure switch --profile <ProfileName> command.

Verify credentials

Run the following command to verify that the credentials work:

aliyun sts get-caller-identity

If the credentials are configured correctly, the output includes the RAM role name in the Arn field:

{
  "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****"
}

Credential refresh

EcsRamRole credentials are STS temporary credentials obtained through the IMDS. The IMDS handles credential refresh automatically, and the entire process is transparent to you. No manual intervention is required.

Delete credentials

To remove an EcsRamRole profile from the local CLI configuration, run:

aliyun configure delete --profile <ProfileName>

Note

This command only removes the profile from ~/.aliyun/config.json. It does not detach the RAM role from the instance. To fully revoke access, detach the RAM role in the ECS console.

FAQs

How do I check whether a RAM role is attached to my instance?

Run the following command on the instance to query the IMDS:

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

If the command returns role information, a RAM role is attached. An empty response or a 404 error means no RAM role is attached.

What do I do if credential retrieval fails when using EcsRamRole credentials?

Alibaba Cloud CLI uses the hardened mode (IMDSv2) by default to retrieve credentials from the Instance Metadata Service. If credential retrieval fails, you can control the fallback behavior with the ALIBABA_CLOUD_IMDSV1_DISABLED environment variable:

false (default): The CLI falls back to the normal mode (IMDSv1) to retrieve credentials.
true: The CLI uses the hardened mode only. If the hardened mode fails, the CLI raises an error instead of falling back.