The Alibaba Cloud CLI automatically obtains temporary credentials by using an ECS instance RAM role (EcsRamRole) without requiring an AccessKey. This method applies to ECS and ECI instances and is the recommended authentication approach for cloud environments. - Alibaba Cloud CLI

When you run the Alibaba Cloud CLI on an ECS instance or an ECI instance, you can use the EcsRamRole credential type. The CLI automatically retrieves temporary security credentials (an STS token) for the RAM role attached to the instance through the Instance Metadata Service (IMDS). This method eliminates the need to configure an AccessKey. It is the recommended authentication approach for cloud environments. This topic describes the prerequisites and the configuration process for EcsRamRole credentials.

Prerequisites

Alibaba Cloud CLI version 3.3.0 or later. Run aliyun version to check your current version. If your version is earlier, see Install or update the Alibaba Cloud CLI to upgrade.
The Alibaba Cloud CLI must be installed on an ECS instance or an ECI instance. This credential type is not supported in local development environments.
The instance must have a RAM role attached with the necessary permissions to access your cloud resources. To grant a RAM role to an instance, 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 to start the configuration. Replace <ProfileName> with a custom name for your profile, such as EcsProfile.
```
aliyun configure --mode EcsRamRole --profile <ProfileName>
```
Follow the prompts to enter configuration information, such as the ECS instance RAM role name, default region, and language.
```
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 a list of available regions, see Regions and availability zones. Some cloud products do not support cross-region access. We recommend setting the default region to where your resources are located.
The configuration is successful when the terminal displays Configure Done and a welcome message.

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

Parameters

Parameter	Description	Required	Example
`--mode`	Specifies the credential type. Set this to `EcsRamRole`.	Yes	`EcsRamRole`
`--profile`	The name of the profile. If you omit this parameter, the CLI uses the active profile. The default name for the first configuration is `default`. We recommend using a descriptive name to distinguish between multiple credential sets.	No	`EcsProfile`
`--ram-role-name`	The name of the RAM role attached to the ECS instance. If you omit this parameter, the CLI automatically queries the IMDS for the role name.	No	`ECSAdmin`
`--region`	The default region ID.	Yes	`cn-hangzhou`

Note

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

Verify credentials

After configuration, run the following command to verify that the credentials are working:

aliyun sts get-caller-identity

The command returns output similar to the following. The Arn field includes the name of the ECS instance RAM role:

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

Refresh credentials

EcsRamRole credentials are essentially temporary security credentials obtained through the IMDS. The IMDS automatically manages the credential refresh process. This process is seamless and requires no manual intervention.

Delete credentials

To delete an EcsRamRole credential profile from your local CLI configuration, run the following command:

aliyun configure delete --profile <ProfileName>

Note

This command only removes the corresponding profile entry from the ~/.aliyun/config.json file. It does not detach the RAM role from the instance. To completely revoke permissions, you must detach the RAM role in the ECS console.

FAQ

Confirm RAM role attachment

Run the following command on the instance to query the IMDS. If the command returns role information, a RAM role is attached.

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

If the output is empty or a 404 error is returned, no RAM role is attached to the instance.

Handle credential fetch failure

By default, the Alibaba Cloud CLI uses enhanced mode (IMDSv2) to retrieve credentials from the Instance Metadata Service. If an error occurs during this process, you can control the fallback behavior by using the ALIBABA_CLOUD_IMDSV1_DISABLED environment variable.

If set to false (default): The CLI falls back to common mode (IMDSv1) to fetch the credentials.
If set to true: Only enhanced mode is allowed. If the process fails, the CLI throws an exception directly without falling back.