Key Management Service:Quickly install KMS Agent on ECS (Linux) to retrieve secrets

Step 1: Install the agent on the ECS instance

1. Log on to the KMS console. In the top navigation bar, select a region. In the navigation pane on the left, click Application Access > Quick Agent Installation.

2. Find the target ECS instance and click Actions in the Install Agent column.

3. In the Install Agent panel, complete the configuration and click OK. By default, the agent is installed in the /usr/local/alibabacloudkmsagent/ directory.

   Parameter	Description
   Compatible Instances	The instance ID of the ECS instance. It cannot be modified.
   Local HTTP Port	The port on which the agent listens for HTTP requests. Defaults to 2025 (127.0.0.1:2025). Important You must allow this port in the security group of the ECS instance. For instructions, see Manage security groups.
   Max Concurrent Connections	The maximum number of simultaneous connections that the agent can handle. Default value: 800. Maximum value: 1000.
   KMS Region, KMS Endpoint	KMS Region: The region ID of the KMS instance, such as ap-southeast-1. It can be the same as or different from the region of the ECS instance. For more information, see Regions. KMS Endpoint: The access point that serves as a destination for service requests in a network architecture. It varies depending on the gateway type: Shared gateway: Access through both public network and Virtual Private Cloud (VPC) network. Dedicated gateway: Access through KMS private network. Shared gateway The KMS Endpoint supports public endpoint (format: kms.<REGION_ID>.aliyuncs.com) and VPC endpoint (format: kms-vpc.<REGION_ID>.aliyuncs.com). Same region: Set KMS Endpoint to either public or VPC endpoint. Network connectivity between ECS and KMS is enabled by default without additional configuration. Different regions: ECS access KMS over the Internet: Set KMS Endpoint to public endpoint. ECS access KMS over the VPC network: Set KMS Endpoint to VPC endpoint, and ensure that the ECS instance and KMS instance can communicate with each other. For more information about network interconnection options, see VPC peering, Connect to the Internet, or Connect to an on-premises IDC. Dedicated gateway The KMS Endpoint supports Instance VPC Endpoint (KMS private network address). Format: <KMS_INSTANCE_ID>.cryptoservice.kms.aliyuncs.com. Same region: Same VPC: Set KMS Endpoint to KMS Instance VPC Endpoint. Network connectivity between ECS and KMS is enabled by default without additional configuration. Different VPCs: Set KMS Endpoint to Instance VPC Endpoint, and associate the VPC of the ECS instance with the KMS instance. For instructions, see Configure Multi-VPC access to KMS instances within the same region. Different regions: Set KMS Endpoint to Instance VPC Endpoint, and ensure that the ECS instance and KMS instance can communicate with each other. For more information about network interconnection options, see VPC peering, Connect to the Internet, or Connect to an on-premises IDC.
   Memory Limit	The number of secrets that the agent can cache. Default and maximum value: 1000.
   TTL (Seconds)	The Time To Live (TTL) for each cache entry used by the agent. Set it based on the rotation interval of secrets. Default value: 300.
   Advanced Settings	In most cases, use the default values for parameters in Advanced Settings. SSRF Request Headers: The Server-Side Request Forgery (SSRF) request header that applications carry when they access the agent. Default value: ["X-KMS-Token","X-Vault-Token"]. SSRF Token Environment Variable: The agent uses the file in this environment variable to verify SSRF. Default value: ["KMS_TOKEN" ,"KMS_SESSION_TOKEN","KMS_CONTAINER_AUTHORIZATION_TOKEN"]. Log Level: The level of logs to record. Default value: debug. Valid values: debug, info, warn, and error. Use the default value debug for troubleshooting. Log Path: The storage path of log files. Default value: ./logs/. Log File Size (MB): The maximum size of a single log file. Default value: 100. Log Backup Files: The number of log files to retain. Default value: 2.

Step 2: Create an ECS instance RAM role

An ECS instance Resource Access Management (RAM) role is a service role attached to an ECS instance. The principal is ECS. Using this role lets the ECS instance obtain STS tokens for temporary access, eliminating the need for AccessKey pairs when calling KMS OpenAPI operations.

1. Log on to the RAM console, and create an instance RAM role whose Principal Type is an Alibaba Cloud service.

   • Principal Type: Select Cloud Service.

   • Principal Name: Select Elastic Compute Service / ECS.

2. Grant the RAM role permissions to retrieve secrets.

   The permissions that the agent requires:

   • Retrieve secret values from KMS.

   • Decrypt the encrypted secrets using the decryption keys.

   Choose a method to complete the grant:

   • Method 1: Configure identity-based policies.

     For instructions, see Create a custom policy and Grant permissions to a RAM role.

     Example policy

     Replace the following parameters with the actual ones:

     • ${region}: The region ID to which the resource belongs.

     • ${account}: The Alibaba Cloud account to which the resource belongs.

     • example-secret: The secret name.

     • keyId-example: The decryption key ID.

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

   • Method 2: Configure resource-based policies.

     This method allows you to configure access permissions for individual keys and secrets to control which Alibaba Cloud accounts, RAM users, and RAM roles have permissions to manage or use KMS keys and secrets. For more information, see Key policies and Secret policies.

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

Step 3: Retrieve secrets

This topic uses the default value 2025 for Local HTTP Port as an example. If you set it to another value, replace 2025 in the examples with the actual one.

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

 # Read token from file
 curl -v -H "X-KMS-Token:$(</var/run/kmstoken)" 'http://localhost:2025/secretsmanager/get?secretId=<SecretId>&versionId=0a7513ee719da740807b15b77500****'
 
 # Write token directly
 curl -v -H "X-KMS-Token:<token>" 'http://localhost:2025/secretsmanager/get?secretId=<SecretId>&versionId=0a7513ee719da740807b15b77500****'

package main

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

func main() {
	
	//You can specify versionStage or versionId to retrieve a specific secret value.
	//For example, to retrieve a secret value with a specific versionId, url := fmt.Sprintf("http://localhost:2025/secretsmanager/get?secretId=%s&versionId=%s", "agent-test", "version-id").
	url := fmt.Sprintf("http://localhost:2025/secretsmanager/get?secretId=%s", "agent-test")

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

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

	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)
	}
	defer resp.Body.Close()

	body, _ := ioutil.ReadAll(resp.Body)
	fmt.Printf("status code %d - %s \n", resp.StatusCode, string(body))
}