You can store credentials for your ECS instances, such as passwords or SSH key pairs, in KMS as ECS secrets. Your applications and Alibaba Cloud services can dynamically retrieve these credentials from KMS by integrating the Alibaba Cloud SDK, a KMS instance SDK, or a secrets SDK. You can also configure secret rotation to reduce the risk of leaks. This topic describes how to manage and use ECS secrets.
ECS secret rotation
When an ECS secret is rotated, either through scheduled or immediate rotation, Secrets Manager sends a rotation command to Cloud Assistant. Cloud Assistant then invokes a plugin on the ECS instance to complete the rotation. After a successful rotation, you can use the new secret to log on to the ECS instance.
After an ECS secret is successfully rotated, the password or SSH key pair of the associated ECS instance is also updated. To prevent rotation failures, do not delete the ECS instance that is associated with the secret.
Usage notes
To use ECS secrets, you must grant KMS the necessary permissions to manage the passwords and SSH key pairs of your ECS instances. When you need to log on to an ECS instance, you can retrieve the corresponding secret from KMS.
After you store passwords or SSH key pairs for an ECS account in KMS, do not modify or delete them in Elastic Compute Service (ECS) to prevent service failures.
Do not store a single password or SSH key pair from an ECS instance in multiple ECS secrets. Secret rotation updates the password or SSH key pair. If one secret is rotated, the values in the other secrets become outdated, preventing you from logging in to the instance with them.
Limitations
On Linux systems, you can rotate both passwords and SSH key pairs. On Windows systems, you can rotate only passwords.
Before you begin
A KMS instance is purchased and enabled. For more information, see Purchase and enable a KMS instance.
A symmetric key is created in the KMS instance for encrypting secrets. For more information, see Create a key.
You have created an ECS instance. For more information, see Create an ECS instance.
If you use a RAM user or RAM role to manage ECS secrets, make sure your Alibaba Cloud account has attached the
AliyunKMSSecretAdminAccesssystem policy to the RAM user or RAM role. For more information, see Manage RAM user permissions or Manage permissions for a RAM role.
Step 1: Create an ECS secret
You can configure automatic periodic rotation when creating a credential to reduce the security risk of credential leaks.
Log on to the Key Management Service console. In the top navigation bar, select a region. In the left-side navigation pane, choose .
Click the ECS Secrets tab. Select an Instance ID, and then click Create ECS Secret. Configure the parameters and click OK.
Parameter
Description
Secret Name
A custom credential name. Must be unique within the current region.
Managed Instance
Select an ECS instance under your Alibaba Cloud account.
Managed User
Enter the username of an existing user on the ECS instance, such as
root(Linux) orAdministrator(Windows).Initial Secret Value
The credential value must be up to 30,720 bytes (30 KB) in length.
-
Password: The logon password of the user on the ECS instance.
-
Key pair: The SSH key pair used to log on to the ECS instance.
NoteThe credential value must be correctly configured. If the credential value is incorrect, the password or key pair retrieved from KMS cannot be used to log on to the ECS instance until the credential is first rotated.
CMK
Select the symmetric key used to encrypt the credential value. The key and the credential must belong to the same KMS instance.
ImportantThe key and the credential must belong to the same KMS instance, and the key must be a symmetric key. For more information about the symmetric keys supported by KMS, see Key types and specifications.
If a RAM user or RAM role is used, it must have permissions to perform the GenerateDataKey operation using the encryption master key.
Automatic Rotation
Select whether to enable automatic rotation. When enabled, KMS periodically updates the credential value to reduce the risk of credential leaks.
Rotation Period
Set this parameter only when automatic rotation is enabled. Valid values: 1 hour to 365 days.
Specifies the rotation interval. KMS periodically updates the credential value based on this setting.
Description
An optional description of the credential for identification and management.
Set the access policy for the credential to control which RAM users or roles can read or modify it.
You can select the default policy first and modify it later as needed.
NoteWhen you create a secret, the system automatically creates the AliyunServiceRoleForKMSSecretsManagerForECS service-linked role and attaches the AliyunServiceRolePolicyForKMSSecretsManagerForECS permission policy to the role. Secrets Manager assumes this role to manage your ECS secrets and perform rotation tasks for ECS passwords and SSH key pairs.You can log on to the RAM console to view the details of service-linked roles and permission policies. For more information, see View a RAM role and View permission policy details.
-
Step 2: Integrate the ECS secret
KMS provides the Alibaba Cloud SDK, KMS instance SDKs, and the Secrets Manager client for you to retrieve secret values and integrate ECS secrets into your applications. We recommend that you use the Secrets Manager client. It encapsulates secret caching, best practices, and design patterns to simplify integration. For more information, see Secrets Manager client. For detailed information about each SDK, see SDK reference.
If you use an SDK to perform management operations, such as creating an ECS secret or modifying tags, you can use only the Alibaba Cloud SDK.
More operations
Rotate an ECS secret
Configuring periodic automatic credential rotation effectively reduces the risk of leakage caused by long-term lack of updates. Additionally, the console supports immediate manual rotation, enabling rapid response to security incidents and timely mitigation of potential threats.
Log on to the Key Management Service console. In the top navigation bar, select a region. In the left-side navigation pane, choose .
Click the ECS Secrets tab. Select an Instance ID, find the secret that you want to rotate, and click Details in the Actions column.
On the secret details page, configure a rotation policy.
Automatic rotation: In the upper-right corner of the page, click Configure Rotation, enable or disable periodic automatic rotation, and then click OK.
Immediate rotation: In the upper-right corner of the page, click Rotate Now. In the Configure Rotation dialog box, specify whether to Use Custom Secrets and then click OK.
If you enable this option, you must specify a new secret value.
If you disable this option, KMS automatically creates a 32-character random password or an RSA-2048 SSH key pair.
Delete an ECS secret
You can delete secrets that are no longer needed, either by scheduling their deletion or by deleting them immediately.
Before you delete a secret, make sure that it is no longer in use. Otherwise, your services may be disrupted.
Log on to the Key Management Service console. In the top navigation bar, select a region. In the left-side navigation pane, choose .
Click the ECS Secrets tab. Select an Instance ID, find the secret that you want to delete, and click Schedule Deletion in the Actions column.
In the Schedule Deletion dialog box, select a deletion method for the secret and click OK.
Schedule Deletion: Specify a recovery period of 7 to 30 days. The system deletes the secret after the recovery period ends.
Delete Immediately: The system immediately deletes the secret.
During the recovery period, you can find the secret and click Restore Secret in the Actions column to cancel the deletion.
Configure credential tags
You can assign tags to credentials to organize and manage them. Each tag consists of a key-value pair (Key : Value), including a tag key (Key) and a tag value (Value).
Tag usage notes
A tag key or tag value can contain up to 128 characters, including letters, digits, forward slashes (/), backslashes (\), underscores (_), hyphens (-), periods (.), plus signs (+), equal signs (=), colons (:), at signs (@), and spaces.
A tag key cannot start with aliyun or acs:. This restriction does not apply to tag values.
Each credential can have up to 20 tags.
Procedures
Tag a single credential
Log on to the Key Management Service console. In the top navigation bar, select a region. In the left-side navigation pane, choose .
Click the tab for the corresponding credential type, select a Instance ID, and locate the target credential.
Open the tag editor using one of the following methods:
Method 1: In the credential list, click the
icon in the Tags column for the target credential.Method 2: Click Actions > Details to go to the credential details page, then click the
icon next to Tag.
Tag multiple credentials in bulk
Log on to the Key Management Service console. In the top navigation bar, select a region. In the left-side navigation pane, choose .
Click the tab for the corresponding credential type, select a Instance ID, and select the credentials to operate on from the credential list.
Add tags: At the bottom of the credential list, click Add Tag, enter the Tag Key and Tag Value, and click OK.
Delete tags: At the bottom of the credential list, click Remove Tag, select the tags to unbind in the Batch Remove dialog box, click Cancel, and then click Close in the confirmation dialog box.