Quick access from ECS

Step 1: Configure permissions

1. Log on to the KMS console. In the left-side navigation pane, choose Application Access > Cloud-native Access.

2. In the ECS list within the Elastic Computing section, find the target ECS instance and click the More icon in the Actions column. Then select Configure ECS Access.

3. In the configuration panel that appears, select one of the following Authentication Method to complete the permission configuration.

   Instance Identity (ECS) (recommended)

   Uses ECS instance identity for authentication without requiring additional credential configuration. The Agent retrieves instance identity directly from the metadata service. Authentication flow: ECS → Identity Doc → KMS → Short-term credentials.

   Parameter	Description
   Scope	Select how you want to access KMS. Valid values: Specified KMS instance: Access keys and credentials in a specified KMS instance through the KMS instance endpoint. Shared KMS Gateway: Access credentials through the KMS service endpoint.
   Application Access Point Name	A custom name for the application access point (access credential) to help you identify and manage it later.
   Policy Name	A custom name for the RAM permission policy. You can create the permission policy in this step — no need to pre-create it in the RAM console.
   RBAC Permissions	Select the role-based access control (RBAC) permission level, which determines what operations your application can perform on credentials. When scope is set to Specified KMS instance: CryptoServiceKeyUser: Allows the use of keys in the KMS instance for credential encryption. Supports cryptographic operation APIs in the instance API. For more information, see Key API reference. CryptoServiceSecretUser: Allows the use of credentials in the KMS instance. Supports credential APIs in the instance API. For more information, see Credential API reference. When scope is set to Shared KMS Gateway: You can select only SecretUser, which allows the use of all credentials under the current account.
   Accessible Resources	Select the credentials and keys (used for credential encryption and decryption) that the application needs to access. Important If you select multiple credentials and the total length of credential names exceeds the limit, an "Invalid parameter" error is returned. In this case, use a wildcard to configure which credentials are allowed. For example, setting secret/rds-ibm* allows access to all credentials with the prefix rds-ibm.
   Description	Optional. A detailed description of the application access point. Maximum length: 8,192 characters.

   RAMRole

   When an application on an ECS instance uses the KMS Agent to access sensitive credentials, you must bind a RAM role to the ECS instance. Make sure the RAM role's permission policy grants access to KMS credentials.

   1. Configure the corresponding RAM Role.

      • Create a new RAM role:

        1. Click Create RAM Role to go to the Roles page in the RAM console. Then click Create Role.

        2. On the creation page, configure the following parameters and click OK.

           • Trusted entity type: Select Elastic Compute Service.

           • Trusted entity name: Select ECS.

        3. Create or modify a permission policy:

           • Create: On the Policies tab, click Create Policy and select Script Edit.

           • Modify: Go to the details page of the existing policy. On the Policy Document tab, click Modify Policy.

           Refer to the following example:

           {
               "Version": "1",
               "Statement": [
                   {
                       "Effect": "Allow",
                       "Action": "kms:GetSecretValue",
                       "Resource": "acs:kms:${region}:${account}:secret/example-secret"
                   },
                   {
                       "Effect": "Allow",
                       "Action": "kms:Decrypt",
                       "Resource": "acs:kms:${region}:${account}:key/keyId-example"
                   }
               ]
           }
                         

        4. On the policy list page, select the policy you created or modified in the previous step. Click Grant Permission in the Actions column to attach the policy to the newly created RAM role.

      • Select an existing RAM role: If a suitable role already exists, select it from the drop-down list.

        Important

        If the role is not attached to any permission policy, attach the relevant policies by following the instructions for creating a RAM role above.

   2. Log on to the ECS console and attach the RAM role to an ECS instance.

   3. Bind the RAM role to the target ECS instance. For detailed steps, see the linked topic above.

4. After completing the configuration, click OK to proceed to the next step.

Step 2: Install the Agent

1. On the Agent installation tab, based on the Authentication Method selected in Step 1, select the corresponding tab: Instance Identity (ECS) or RAMRole.

2. Configure the following basic parameters:

   Parameter	Description
   AapArn	Required only for Instance Identity (ECS). Select the application access point created in Step 1.
   Local HTTP Port	The HTTP service port that the KMS Agent listens on. Default value: 2025. The default listening address is 127.0.0.1:2025. Important Make sure to allow this port in the ECS security group. For more information, see Security group configuration.
   Max Concurrent Connections	The maximum number of concurrent requests that the Agent can process from applications. Default value: 800. Maximum value: 1000.
   KMS Region	The region where the KMS instance is located, for example, cn-hangzhou. This can be the same as or different from the ECS instance region. If the regions are different: Ensure network connectivity between the ECS instance and the KMS instance. For more information, see Connect an on-premises data center to a VPC, Connect an on-premises data center to a VPC by using a VPN gateway, or Connect an on-premises data center to a VPC by using a Cloud Enterprise Network instance. If the regions are the same but the ECS instance and KMS instance belong to different VPCs: Bind the VPC of the ECS instance to the KMS instance to enable network connectivity. For more information, see Bind a VPC to a KMS instance.
   KMS Endpoint	The access URL for the KMS service. If Scope is set to Shared KMS Gateway: VPC access: Enter the VPC access endpoint, for example, kms-vpc.cn-hangzhou.aliyuncs.com. Public network access: Enter the public access endpoint, for example, kms.cn-hangzhou.aliyuncs.com. If Scope is set to Specified KMS instance: Enter the KMS private network address in the format <YOUR_KMS_INSTANCE_ID>.cryptoservice.kms.aliyuncs.com.
   Memory Limit	The maximum number of credentials that the KMS Agent can cache. Default value: 1000. Maximum value: 1000.
   TTL (Seconds)	The time-to-live (TTL) for the Agent cache. We recommend setting this value based on the rotation interval of your credentials. Default value: 300 seconds.

3. Advanced Settings (optional): Expand Advanced Settings to display the following configuration items. In most cases, the default values are sufficient.

   Parameter	Description
   SSRF Request Headers	The SSRF request headers that the application sends to the Agent. Default value: ["X-KMS-Token","X-Vault-Token"].
   SSRF Token Environment Variable	The Agent uses the files in these environment variables to validate SSRF requests. Default value: ["KMS_TOKEN","KMS_SESSION_TOKEN","KMS_CONTAINER_AUTHORIZATION_TOKEN"].
   Log Level	The log level. Default value: debug. Valid values: debug, info, warn, error. We recommend using the default value debug for easier troubleshooting.
   Log Path	The log file storage path. Default value: ./logs/.
   Log File Size (MB)	The maximum size of a single log file. Default value: 100 MiB.
   Log Backup Files	The number of log files to retain. Default value: 2.

4. After the configuration is complete, click OK. KMS uses Cloud Assistant to automatically install the Agent on the target ECS instance — no need to manually log on to the server.

Step 3: Verify the installation

The installation verification page is the final page in the configuration wizard. On this page, you can view the installation status and retrieve application integration code samples.

1. Click the Refresh button, and view the installation status in the Recent Operation Result column. A status of Running indicates that the Agent has been successfully installed.

2. After closing the configuration panel, you can view the Agent status on the Quick access from ECS list page.

3. Log on to the ECS instance and run the following curl command to verify that the Agent is working properly:

   curl -v -H "X-KMS-Token:$(cat /var/run/kmstoken)" 'http://localhost:2025/secretsmanager/get?secretId=test'
   

   An HTTP 200 response indicates that the Agent is working correctly. If you receive a different status code, refer to the Troubleshooting section to resolve the issue.

curl examples

To retrieve credentials from the local Agent, you can either read the token from a file or provide it directly:

# Read token from file
curl -v -H "X-KMS-Token:$(</var/run/kmstoken)" 'http://localhost:2025/secretsmanager/get?secretId=agent-test'

# Provide token directly
curl -v -H "X-KMS-Token:<token>" 'http://localhost:2025/secretsmanager/get?secretId=agent-test'
          

Go example

package main

import (
    "fmt"
    "io"
    "net/http"
    "os"
)

func main() {
    // You can specify either versionStage or versionId to retrieve a specific credential value.
    // The following example retrieves the credential value for a specified versionId.
    url := fmt.Sprintf("http://localhost:2025/secretsmanager/get?secretId=%s", "agent-test")

    token, err := os.ReadFile("/var/run/kmstoken")
    if err != nil {
        fmt.Printf("error reading token file: %v\n", err)
        return
    }

    req, err := http.NewRequest("GET", url, nil)
    if err != nil {
        fmt.Printf("error creating request: %v\n", err)
        return
    }

    req.Header.Add("X-KMS-Token", string(token))

    client := &http.Client{}
    resp, err := client.Do(req)
    if err != nil {
        fmt.Printf("error sending request: %v\n", err)
        return
    }
    defer resp.Body.Close()

    body, err := io.ReadAll(resp.Body)
    if err != nil {
        fmt.Printf("error reading response body: %v\n", err)
        return
    }
    fmt.Printf("status code %d - %s\n", resp.StatusCode, string(body))
}