Configure access credentials for clients such as Docker and containerd - Container Registry

Before you push or pull Container Registry (ACR) images by using Docker, containerd, or other clients, you must configure access credentials for authentication. Credentials include permanent passwords and temporary passwords. After you pass authentication, you can push and pull container images or Helm charts.

Credential description

After authentication, the system authorizes operations based on the RAM access control policy and controls the scope of operations that you can perform.

Access credentials are independent of your Alibaba Cloud account and its password. The ACR permanent password is not the console logon password of your account (Alibaba Cloud account or Resource Access Management (RAM) user). It is a dedicated Registry password that you set on the Access Credential page in the ACR console. There are two types of credentials:

Permanent password: This password does not expire. If it is leaked, it remains valid until you actively reset it. For higher security, we recommend that you use a temporary password. If you lose the password, you can reset it on the access credentials page.
Temporary password: This password is valid for 1 hour. If you request the password by using Security Token Service (STS), the password is valid for the same period as the Security Token Service token of the request.

The access credentials of an Alibaba Cloud account and those of a RAM user are independent of each other. A RAM user cannot use the permanent password that is set by the Alibaba Cloud account. Each RAM user must log on to the ACR console with their own Alibaba Cloud account and set a dedicated permanent password.

When you log on to ACR by using Docker or other clients, the value of the --username parameter varies based on the account type:

Alibaba Cloud account: The username is the logon name of the Alibaba Cloud account. You can view the complete docker login command and the corresponding username on the Access Credentials page in the ACR console. This username is different from the Alibaba Cloud account ID, which is a numeric string. If you use the account ID as the username, authentication fails.
RAM user: The username is the RAM user login name, in the format <RAM-user-login-name>@<default-domain-of-alibaba-cloud-account>, for example username@China-1234567890.onaliyun.com.

Before running docker login, verify the correct username format on the Access Credentials page in the ACR console to avoid the unauthorized: authentication required error caused by an incorrect username.

Use a permanent password

Note

Container Registry (ACR) does not support role-based logon. Log on by using Use a temporary password.

RAM user: To set a permanent password as a RAM user in the ACR console, the Alibaba Cloud account must enable the Console Login permission for the RAM user in advance. A RAM user without console access enabled cannot log on to the ACR console or configure access credentials.

The Alibaba Cloud account cannot set or manage the permanent password on behalf of a RAM user. The RAM user must log on to the ACR console with their own account and configure access credentials by themselves.

Log on to the Container Registry console.
In the top navigation bar, select a region.
In the left-side navigation pane, click Instances.
On the Instances page, click the Enterprise Edition instance that you want to manage.
In the left-side navigation pane of the Enterprise instance management page, choose Instances > Access Credentials.
On the Access Credentials page, click Set Password.
In the Set Password dialog box, enter the Password and Confirm Password. Then, click Confirm.
The password must be 8 to 32 characters in length and contain at least two of the following character types: letters, symbols, and digits. Do not use a publicly known weak password such as P@ssw0rd. The $ symbol is not supported.
- Confirm button grayed out with no error message: If the Confirm button becomes grayed out after you click it and no error message appears, the password likely does not meet the security requirements (for example, the password contains prohibited characters such as $ or uses a common weak password). Check and adjust the password, then try again.
- Docker login failed due to special characters: If the password contains special characters such as @, running docker login in the terminal may fail due to shell escaping, resulting in an unauthorized: authentication required error. In this case, reset the password on the Access Credentials page and use a password without special characters.
- Historical passwords cannot be retrieved: After a permanent password is set, its history cannot be viewed. If you lose the password, reset it on the Access Credentials page.

What to do next

Log on to the Enterprise instance.

Configure access control for a VPC or the Internet. For more information, see Configure internet access control or Configure VPC access control.
In your terminal, enter the access credential to log on to the Enterprise instance. The following sample command is for your reference:
```
docker login <Enterprise-Edition-instance-name>-registry.<region-of-the-Enterprise-Edition-instance>.cr.aliyuncs.com
```

Use a temporary password

You have installed Alibaba Cloud CLI and Configure and manage credentials.
You have installed the jq command.
You have Create a RAM user.

You can run the GetAuthorizationToken operation directly in OpenAPI Explorer to obtain the temporary logon username and password of the target instance.

Use an existing AccessKey pair, or see Create an AccessKey to create a new one. Record the AccessKey ID and AccessKey secret.

Use the following content to Using the script editor and Manage RAM user permissions.

{
    "Version": "1",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "cr:GetAuthorizationToken",
                "cr:PullRepository",
                "cr:PushRepository"
            ],
            "Resource": "*"
        }
    ]
}

Run the following commands to obtain the temporary password.

ACR_ENDPOINT="<acr service endpoint>" where <acr service endpoint> is the Endpoints of the region where the ACR instance resides.

export ALIYUN_AK="<aliyun access key>"               # The AccessKey ID from Step 1.
export ALIYUN_SK="<aliyun access key secret>"       # The AccessKey Secret from Step 1.
export ACR_INSTANCE_ID="<id of acr instance>"       # The target ACR instance ID.
export ACR_ENDPOINT="<acr service endpoint>"

aliyun cr GetAuthorizationToken --endpoint $ACR_ENDPOINT --InstanceId $ACR_INSTANCE_ID --access-key-id $ALIYUN_AK --access-key-secret $ALIYUN_SK | jq -r '.AuthorizationToken'

Container Registry:Configure access credentials

Credential description

Use a permanent password

What to do next

Use a temporary password

References