All Products
Search

This Product

    Alibaba Cloud CLI:Configure profiles

    Document Center

    Alibaba Cloud CLI:Configure profiles

    Last Updated:Dec 18, 2024

    Before you use Alibaba Cloud CLI, you must configure the information that is required to call Alibaba Cloud resources. The information includes the credential, region, and language. When Alibaba Cloud CLI is used for the first time, it automatically creates a profile named default to store the required information. You can also configure and use your custom profiles.

    Profile configuration modes

    Alibaba Cloud CLI provides two configuration modes: interactive mode and non-interactive mode. You can select a configuration mode based on your business requirements.

    • The interactive mode guides you through the configuration process. This way, you can configure a profile in Alibaba Cloud CLI at a low learning cost. We recommend that you use this mode if you are a beginner, are unfamiliar with CLI operations, or occasionally configure a profile.

    • The non-interactive mode allows you to directly specify configuration items by using parameters in commands or environment variables. This mode offers high flexibility and efficiency. We recommend that you use this mode if you want to manage and use Alibaba Cloud CLI by using scripts, automated deployment tools, or configuration management tools.

    Interactive mode

    General syntax

    You can run the aliyun configure command to configure a profile in interactive mode. Syntax:

    aliyun configure --mode <AuthenticateMode> --profile <profileName>

    • Parameters in the command:

      • --mode: the credential type. Default value: AK. For more information about the credential types supported by Alibaba Cloud CLI, see the Credential types section of this topic.

      • --profile: the profile name. If you do not specify this parameter, the default profile is used. If the specified profile exists, it is modified. If the specified profile does not exist, a profile with the specified name is created.

    • Usage notes

      • Make sure that you specify valid credential information. Invalid credential information may cause accidental operations or failures to run commands.

      • After you configure a profile in interactive mode, the following information is displayed if the credential information is valid:

        Complete response

        Configure Done!!!
..............888888888888888888888 ........=8888888888888888888D=..............
...........88888888888888888888888 ..........D8888888888888888888888I...........
.........,8888888888888ZI: ...........................=Z88D8888888888D..........
.........+88888888 ..........................................88888888D..........
.........+88888888 .......Welcome to use Alibaba Cloud.......O8888888D..........
.........+88888888 ............. ************* ..............O8888888D..........
.........+88888888 .... Command Line Interface(Reloaded) ....O8888888D..........
.........+88888888...........................................88888888D..........
..........D888888888888DO+. ..........................?ND888888888888D..........
...........O8888888888888888888888...........D8888888888888888888888=...........
............ .:D8888888888888888888.........78888888888888888888O ..............

    Non-interactive mode

    General syntax

    You can run the aliyun configure set command to configure a profile in non-interactive mode. Syntax:

    aliyun configure set [--settingName <settingValue>]... --mode <AuthenticateMode> --profile <profileName>
    Note

    When you configure a profile in non-interactive mode, you must specify profile parameters. You need to specify only the parameters required for the credential type of the profile that you configure.

    • The following list describes the common parameters, which apply to all credential types:

      • --profile: required. The profile name. If the specified profile exists, it is modified. If the specified profile does not exist, a profile with the specified name is created.

      • --region: required. The ID of the default region. For more information about the IDs of regions supported by Alibaba Cloud, see Regions and zones.

      • --language: the language of Alibaba Cloud CLI. Default value: en.

      • --mode: the credential type. Default value: AK. For more information about the credential types supported by Alibaba Cloud CLI, see the Credential types section of this topic.

    • Usage notes

      • Make sure that you specify valid credential information. Invalid credential information may cause accidental operations or failures to run commands.

      • After you configure a profile in non-interactive mode, you can run the aliyun configure list or aliyun configure get command to check whether the profile is configured as expected. For more information, see Profile-related commands.

    Credential types

    AK

    Description

    Important

    To ensure the security of your Alibaba Cloud account, we recommend that you create a Resource Access Management (RAM) user for calling API operations and create an AccessKey pair for the RAM user. For more information about how to use an AccessKey pair in a secure manner, see Credential security solutions.

    • In Alibaba Cloud CLI, AK is the default credential type, which uses an AccessKey pair as the credential. Therefore, you can omit the --mode parameter when you configure a profile of the AK credential type.

    • Required parameters:

      • AccessKey Id: the AccessKey ID. For more information, see the "Create an AccessKey pair for a RAM user" section of the Create an AccessKey pair topic.

      • AccessKey Secret: the AccessKey secret. For more information, see the Create an AccessKey pair for a RAM user section of the "Create an AccessKey pair" topic.

      • Region Id: the ID of the default region. For more information about the IDs of regions supported by Alibaba Cloud, see Regions and zones.

    Configuration examples

    The following examples show how to configure a profile named AkProfile of the AK credential type.

    • Interactive mode

      Run the following command:

      aliyun configure --profile AkProfile

      The following sample response shows the interaction process:

      Sample response

      Configuring profile 'AkProfile' in 'AK' authenticate mode...
Access Key Id []: ****
Access Key Secret []: ****
Default Region Id []: ****
Default Output Format [json]: json (Only support json))
Default Language [zh|en] en: en
Saving profile[akProfile] ...Done.

    • Non-interactive mode

      Run the aliyun configure set command to configure a profile in non-interactive mode.

      aliyun configure set \
  --profile AkProfile \ 
  --mode AK \
  --access-key-id **** \
  --access-key-secret **** \
  --region ****

    RamRoleArn

    Description

    • Credentials of the RamRoleArn type are temporary STS tokens for RAM users. For more information about this credential type, see AssumeRole.

    • To configure a profile of this credential type, you must set the --mode parameter to RamRoleArn.

    • Required parameters:

      • AccessKey Id: the AccessKey ID. For more information, see Create an AccessKey pair.

      • AccessKey Secret: the AccessKey secret. For more information, see Create an AccessKey pair.

      • Region Id: the ID of the default region. For more information about the IDs of regions supported by Alibaba Cloud, see Regions and zones.

      • RamRoleArn: the Alibaba Cloud Resource Name (ARN) of the RAM role. You can view the ARN of a RAM role in the RAM console or by calling an API operation.

        • For more information about how to view the ARN of a RAM role in the RAM console, see the "How do I view the ARN of a RAM role?" section of the FAQ about RAM roles and STS tokens topic.

        • For more information about how to view the ARN of a RAM role by calling an API operation, see ListRoles or GetRole.

      • RoleSessionName: the session name of the RAM role. The parameter value is user-defined and is usually set to the identity of the user who calls the API operation, such as the username.

    Configuration examples

    The following examples show how to configure a profile named RamRoleArnProfile of the RamRoleArn credential type.

    • Interactive mode

      Run the following command:

      aliyun configure --profile RamRoleArnProfile --mode RamRoleArn

      The following sample response shows the interaction process:

      Sample response

      Configuring profile 'RamRoleArnProfile' in 'RamRoleArn' authenticate mode...
Access Key Id []: ****
Access Key Secret []: ****
Ram Role Arn []: ****
Role Session Name []: ****
Default Region Id []: ****
Default Output Format [json]: json (Only support json))
Default Language [zh|en] en: en
Saving profile[ramRoleArnProfile] ...Done.

    • Non-interactive mode

      Run the aliyun configure set command to configure a profile in non-interactive mode.

      aliyun configure set \
  --profile RamRoleArnProfile \
  --mode RamRoleArn \
  --access-key-id **** \
  --access-key-secret **** \
  --ram-role-arn **** \
  --role-session-name ****\
  --region ****

    EcsRamRole

    Description

    • Credentials of the EcsRamRole type allow you to obtain an STS token by accessing the metadata service within an ECS instance. This frees you from configuring an AccessKey pair and reduces the risk of AccessKey pair leakage.

    • You can configure and use credentials of the EcsRamRole type only within ECS instances that are assigned instance RAM roles.

    • To configure a profile of this credential type, you must set the --mode parameter to EcsRamRole.

    • Required parameters:

    Configuration examples

    The following examples show how to configure a profile named EcsRamRoleProfile of the EcsRamRole credential type.

    • Interactive mode

      Run the following command:

      aliyun configure --profile EcsRamRoleProfile --mode EcsRamRole

      The following sample response shows the interaction process:

      Sample response

      Configuring profile 'EcsRamRoleProfile' in 'EcsRamRole' authenticate mode...
Ecs Ram Role []: ****
Default Region Id []: ****
Default Output Format [json]: json (Only support json))
Default Language [zh|en] en: en
Saving profile[ecsRamRamRoleArnProfile] ...Done.

    • Non-interactive mode

      Run the aliyun configure set command to configure a profile in non-interactive mode.

      aliyun configure set \
  --profile EcsRamRoleProfile \
  --mode EcsRamRole \
  --ram-role-name **** \
  --region ****

    External

    Description

    • Alibaba Cloud CLI can obtain an external credential by running a command of an external program.

    • To configure a profile of this credential type, you must set the --mode parameter to External.

    • Alibaba Cloud CLI allows you to use an external credential to log on to CloudSSO. For more information, see Use Alibaba Cloud CLI to access CloudSSO and Alibaba Cloud resources.

    • Required parameters:

      • Process Command: the command of the external program. External programs can return two types of static credentials: AK and StsToken. The following code shows the structures of the two types of credentials:

        AK

        {
  "mode": "AK",
  "access_key_id": "accessKeyId",
  "access_key_secret": "accessKeySecret"
}

        StsToken

        {
  "mode": "StsToken",
  "access_key_id": "accessKeyId",
  "access_key_secret": "accessKeySecret",
  "sts_token": "stsToken"
}

      • Region Id: the ID of the default region. For more information about the IDs of regions supported by Alibaba Cloud, see Regions and zones.

    Configuration examples

    The following examples show how to configure a profile named ExternalProfile of the External credential type.

    • Interactive mode

      Run the following command:

      aliyun configure --profile ExternalProfile --mode External

      The following sample response shows the interaction process:

      Sample response

      Configuring profile 'ExternalProfile' in 'External' authenticate mode...
Process Command []: ****
Default Region Id []: ****
Default Output Format [json]: json (Only support json)
Default Language [zh|en] en: en
Saving profile[externalTest] ...Done.

    • Non-interactive mode

      Run the aliyun configure set command to configure a profile in non-interactive mode.

      aliyun configure set \
  --profile ExternalProfile \
  --mode External \
  --process-command **** \
  --region ****

    ChainableRamRoleArn

    Description

    • The ChainableRamRoleArn credential type allows you to use chainable role assumption to obtain credentials. To use a credential of this type, Alibaba Cloud CLI obtains an intermediate credential from the source profile, assumes a role by using the intermediate credential, and then obtains the final credential.

    • To configure a profile of this credential type, you must set the --mode parameter to ChainableRamRoleArn.

    • Required parameters:

      • Source Profile: the name of the source profile. The source profile can be of any credential type. Before you configure a profile of the ChainableRamRoleArn credential type, you must configure a source profile. For more information, see the following configuration example.

      • Region Id: the ID of the default region. For more information about the IDs of regions supported by Alibaba Cloud, see Regions and zones.

      • RamRoleArn: the ARN of the RAM role. You can view the ARN of a RAM role in the RAM console or by calling an API operation.

        • For more information about how to view the ARN of a RAM role in the RAM console, see the "How do I view the ARN of a RAM role?" section of the FAQ about RAM roles and STS tokens topic.

        • For more information about how to view the ARN of a RAM role by calling an API operation, see ListRoles or GetRole.

      • RoleSessionName: the session name of the RAM role. The parameter value is user-defined and is usually set to the identity of the user who calls the API operation, such as the username.

    Configuration example

    Note

    Before you configure a profile of the ChainableRamRoleArn credential type, you must attach the AliyunSTSAssumeRoleAcces system policy to the RAM identity associated with the source profile.

    The following example shows how to configure a profile named ChainableProfile of the ChainableRamRoleArn credential type. In this example, the source profile is named RamRoleArnProfile and of the RamRoleArn credential type.

    • Interactive mode

      1. Configure the source profile RamRoleArnProfile. For more information, see the configuration examples in the RamRoleArn section of this topic.

      2. Run the following command to configure the ChainableProfile profile of the ChainableRamRoleArn credential type. 

        aliyun configure --profile ChainableProfile --mode ChainableRamRoleArn

        The following sample response shows the interaction process. Specify the source profile by setting the Source Profile parameter to RamRoleArnProfile.

        Sample response

        Configuring profile 'ChainableProfile' in 'ChainableRamRoleArn' authenticate mode...
Source Profile []: RamRoleArnProfile
Sts Region []: ****
Ram Role Arn []: ****
Role Session Name []: ****
Expired Seconds [900]: ****
Default Region Id []: ****
Default Output Format [json]: json (Only support json)
Default Language [zh|en] en: en
Saving profile[p1] ...Done.

    • You cannot configure a profile of the ChainableRamRoleArn credential type in non-interactive mode.

    CredentialsURI

    Description

    • Credentials of the CredentialsURI type are obtained by accessing local or remote Uniform Resource Identifiers (URIs).

    • To configure a profile of this credential type, you must set the --mode parameter to CredentialsURI.

    • Required parameters:

      • CredentialsURI: the local or remote URI. If the URI is inaccessible or the structure of the returned credential is incorrect, Alibaba Cloud CLI returns an error. The following code shows the standard structure:

        Standard structure

        {
  "Code": "Success",
  "AccessKeyId": "<ak id>",
  "AccessKeySecret": "<ak secret>",
  "SecurityToken": "<security token>",
  "Expiration": "2006-01-02T15:04:05Z"
}

      • Region Id: the ID of the default region. For more information about the IDs of regions supported by Alibaba Cloud, see Regions and zones.

    Configuration examples

    The following examples show how to configure a profile named URIProfile of the CredentialsURI credential type.

    • Interactive mode

      Run the following command:

      aliyun configure --profile URIProfile --mode CredentialsURI

      The following sample response shows the interaction process:

      Sample response

      Configuring profile 'URIProfile' in 'CredentialsURI' authenticate mode...
Credentials URI []: ****
Default Region Id []: ****
Default Output Format [json]: json (Only support json)
Default Language [zh|en] en: en
Saving profile[cup] ...Done.

    • You cannot configure a profile of the CredentialsURI credential type in non-interactive mode.

    OIDC

    Description

    • Credentials of the OIDC type are used for role-based single sign-on (SSO) based on OpenID Connect (OIDC). For more information about this credential type, see AssumeRoleWithOIDC.

    • To configure a profile of this credential type, you must set the --mode parameter to OIDC.

    • Required parameters:

      • OIDCProviderARN: the ARN of the OIDC identity provider (IdP). You can view the ARN of an OIDC IdP in the RAM console or by calling an API operation.

      • OIDCTokenFile: the path of the OIDC token file. An OIDC token is issued by an external IdP.

      • Region Id: the ID of the default region. For more information about the IDs of regions supported by Alibaba Cloud, see Regions and zones.

      • RamRoleArn: the ARN of the RAM role. You can view the ARN of a RAM role in the RAM console or by calling an API operation.

        • For more information about how to view the ARN of a RAM role in the RAM console, see the "How do I view the ARN of a RAM role?" section of the FAQ about RAM roles and STS tokens topic.

        • For more information about how to view the ARN of a RAM role by calling an API operation, see ListRoles or GetRole.

      • RoleSessionName: the session name of the RAM role. The parameter value is user-defined and is usually set to the identity of the user who calls the API operation, such as the username.

    Configuration examples

    The following examples show how to configure a profile named OIDCProfile of the OIDC credential type.

    • Interactive mode

      Run the following command:

      aliyun configure --profile OIDCProfile --mode OIDC

      The following sample response shows the interaction process:

      Sample response

      Configuring profile 'OIDCProfile' in 'OIDC' authenticate mode...
OIDC Provider ARN []: ****
OIDC Token File []: ****
RAM Role ARN []: ****
Role Session Name []: ****
Default Region Id []: ****
Default Output Format [json]: json (Only support json)
Default Language [zh|en] en: en
Saving profile[oidc_p] ...Done.

    • Non-interactive mode

      Run the aliyun configure set command to configure a profile in non-interactive mode.

      aliyun configure set \
  --profile OIDCProfile \
  --mode OIDC \
  --oidc-provider-arn **** \
  --oidc-token-file **** \
  --ram-role-arn **** \
  --role-session-name ****\
  --region ****

    Use a profile

    • If you do not specify a profile when you run a command, the default profile is used.

    • You can also use one of the following methods to specify a profile for running a command.

      Use the -profile parameter

      Add the --profile parameter to your command to use the specified profile.

      Example: Call the DescribeInstances operation of Elastic Compute Service by using the profile named exampleProfile to query the information about Elastic Compute Service instances. 

      aliyun ecs DescribeInstances --profile exampleProfile

      Specify the default profile

      After the default profile is specified, you do not need to specify a profile every time you run a command in Alibaba Cloud CLI. You can still use the --profile parameter to specify the profile that you want to use after the default profile is specified.

      You can use one of the following methods to specify the default profile:

      • Run the aliyun configure switch command to explicitly specify a profile as the default profile. For more information, see the Specify the default profile section of the "Profile-related commands" topic.

      • Run the aliyun configure set command to modify a profile. After the profile is modified, Alibaba Cloud CLI automatically sets the profile as the default profile. For more information, see the Method 2: Modify a specific profile section of the "Profile-related commands" topic.

      • Manually modify the current parameter in the config.json file to specify the default profile.

    Profile storage location

    A profile specifies a set of configuration items and has a custom name. All profiles are stored in the config.json file in the JSON format. This file is located in the .aliyun folder in your personal user directory. The path of the folder varies with the operating system.

    • Windows: C:\Users\<USERNAME>\.aliyun

    • Linux or macOS: ~/.aliyun