Key Management Service:KMS Agent overview

How it works

The agent caches secret values in memory and refreshes them periodically based on the Time To Live (TTL) you configure. When an application requests a secret:

1. The agent validates the request using a Server-Side Request Forgery (SSRF) token file.

2. If a valid cached value exists and has not expired, the agent returns it immediately (cache hit).

3. If no valid cache entry exists, the agent forwards the request to KMS. KMS verifies the agent's identity, decrypts the secret, and returns it. The agent updates the cache and returns the value to the application (cache miss).

The following diagrams show both flows:

• Cache hit process

• Cache miss (no cache or expired cache) process

Deploy the agent alongside your applications on physical servers, virtual machines such as Elastic Compute Service (ECS), or containers such as Kubernetes pods. For the source code and deployment guides, see alibabacloud-kms-agent.

Architecture

The agent comprises four components: HTTP server, cache, KMS client, and log.

Configure all four components in a single configuration file. The file below shows all available options and their defaults:

# All configuration items
[Server]
# Optional, default value is 2025. Agent listens on 127.0.0.1:2025.
HttpPort = 2025
# Optional, default value is ["X-KMS-Token", "X-Vault-Token"].
# Requests to the agent must include an SSRF header; requests without one are rejected.
SSRFHeaders = ["X-KMS-Token"]
# Optional, default value is ["KMS_TOKEN", "KMS_SESSION_TOKEN", "KMS_CONTAINER_AUTHORIZATION_TOKEN"].
# The value can be a literal string or a file path, such as file:///var/run/awssmatoken.
# The agent reads the SSRF token from the specified environment variable and compares it
# against the token in the application's request header. Access is granted only on a match.
SSRFEnvVariables = ["KMS_TOKEN"]
# Optional, default value is "/v1/". URI prefix for path-based requests.
PathPrefix = "/v1/"
# Optional, default value is 800. Maximum number of concurrent requests.
MaxConn = 800
# Optional, default value is 0.
# 0: KMS GetSecretValue response format
# 1: AWS Secrets Manager GetSecretValue response format
# 2: HashiCorp Vault KV structure
ResponseType = 0
# Optional, default value is true.
# When true, the agent returns expired cached values if KMS is temporarily unreachable.
IgnoreTransientErrors = true

[Kms]
# Optional, default value is cn-hangzhou.
Region = "cn-hangzhou"
# Optional, default value is kms.cn-hangzhou.aliyuncs.com.
# Accepts both shared and dedicated gateway endpoints.
Endpoint = "kms.cn-hangzhou.aliyuncs.com"

[Cache]
# Optional, default value is InMemory. Only in-memory caching is currently supported.
CacheType = "InMemory"
# Optional, default value is 1000. When set to 0, caching is disabled and every
# request goes directly to KMS.
CacheSize = 1000
# Optional, default value is 300s.
TtlSeconds = 300
# Optional, default value is false.
# false: evicts the oldest cached secret when the cache is full.
# true: evicts the least recently used secret (LRU) based on access frequency.
EnableLRU = false

[Log]
# Optional, default value is Debug.
LogLevel = "Debug"
# Optional, default value is ./logs/ relative to the application startup directory.
LogPath = "./logs/"
# Optional, default value is 100 (MB). Maximum size per log file.
MaxSize = 100
# Optional, default value is 2. Number of log files to retain.
MaxBackups = 2

curl -s \
  -H "X-KMS-Token: $(cat /var/run/kmstoken)" \
  "http://127.0.0.1:2025/v1/<secret-name>"

with open("/var/run/kmstoken") as f:
    token = f.read().strip()

headers = {"X-KMS-Token": token}
response = requests.get("http://127.0.0.1:2025/v1/<secret-name>", headers=headers)
print(response.json())

Security

Stability

The agent is designed to remain available during network disruptions and transient failures.

Startup self-check: On startup, the agent verifies connectivity to KMS. If verification fails, the agent exits rather than starting in a degraded state.

Automatic retry: The agent uses the Alibaba Cloud SDK (V2) built-in retry logic. For HTTP 429 (throttling) and HTTP 500 (internal server error) responses, it will retry 3 times using an exponential backoff method for interval times.

Stale cache fallback: When IgnoreTransientErrors is enabled (the default), the agent returns the most recent cached value if KMS is temporarily unreachable. This prevents application failures during short-lived network or server issues.

High availability:

• Linux (systemd): systemd monitors the agent process and restarts it automatically if it crashes.

• Kubernetes (sidecar container): Deployed as an init container, the agent failing will trigger a container restart, guaranteeing application stability.

KMS Agent vs. Secret Client

KMS Agent acts as a middle layer — applications access secrets through the agent rather than calling KMS directly. Secret Client integrates the KMS SDK into each application. Choose based on your deployment scale and access control requirements.