ECS 快速接入

步骤 1 ：权限配置

1. 登录密钥管理服务控制台，在左侧导航栏，选择 应用接入 > 云原生接入。

2. 在弹性计算区域的 ECS 列表中，在目标 ECS 实例的操作列中，单击更多图标，选择配置ECS接入。

3. 在弹出的配置面板中，选择以下其中一种认证方式完成权限配置。

   实例身份(ECS)（默认推荐）

   ECS 实例身份认证，无需额外凭据配置， Agent 直接从元数据服务获取身份证明。认证流程为： ECS → Identity Doc → KMS → 短期凭证。

   参数	说明
   作用域	选择访问 KMS 的方式。可选值： 指定的 KMS 实例：通过 KMS 实例 Endpoint 访问指定实例中的密钥和凭据。 KMS共享网关：通过 KMS 服务 Endpoint 访问凭据。
   应用接入点名称	自定义应用接入点（访问凭证）的名称，便于后续识别和管理。
   权限策略名称	自定义 RAM 权限策略名称，在此步骤中即可创建权限策略，无需预先在 RAM 控制台创建。
   RBAC权限	选择基于角色的访问控制（ RBAC ）权限级别，决定应用程序对凭据的操作权限。 作用域选择指定的 KMS 实例： CryptoServiceKeyUser：允许使用 KMS 实例中的密钥，用于凭据加密。支持实例API中的密码运算接口，具体请参见密钥接口。 CryptoServiceSecretUser：允许使用 KMS 实例中的凭据。支持实例 API 中的凭据接口，具体参见凭据接口。 作用域选择KMS共享网关：仅支持选择SecretUser，允许使用当前账号下的所有凭据。
   允许访问的资源	勾选应用需要访问的凭据和密钥（用于凭据加解密）。 重要 勾选多个凭据时，如果凭据名称总长度超限会报"参数非法"错误，此时使用通配符配置允许访问的凭据。例如，配置为secret/rds-ibm*，表示允许访问前缀为 rds-ibm 的凭据。
   描述信息	选填。对该应用接入点的详细说明，最大支持 8192 字符。

   RAMRole

   ECS 实例中的应用使用 KMS Agent 访问敏感凭证，需要为该 ECS 实例绑定 RAM 角色。确认该 RAM 角色的权限策略已授予访问 KMS 凭据的权限。

   1. 配置对应的RAM角色。

      • 新建 RAM 角色：

        1. 单击创建RAM角色，跳转至 RAM 控制台的角色页面，单击创建角色。

        2. 在创建页面，配置如下信息后，单击确定。

           • 信任主体类型：选择云服务器。

           • 信任主体名称：选择云服务器 ECS。

        3. 新建或修改权限策略：

           • 新建：在权限策略页签，单击新建权限策略，选择脚本编辑。

           • 修改：进入已有策略详情页，并在策略内容页签，单击编辑权限策略。

           参考示例如下：

           {
               "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. 在策略列表页，选择上一步新建或修改的策略。单击其操作列的新增授权，绑定新建的 RAM 角色。

      • 选择已有的 RAM 角色：若已有相关的角色，可在下拉列表中直接选择。

        重要

        若角色未绑定权限策略，参照上文新建 RAM 角色的说明，为其绑定相关策略。

   2. 登录ECS 管理控制台，将 RAM 角色授予 ECS 实例。

4. 填写完成后，单击确定，进入下一步。

步骤 2 ：安装 Agent

1. 进入安装 Agent 页签后，根据步骤 1 中选择认证方式，选择对应的页签实例身份(ECS)或RAMRole。

2. 配置基础参数：

   参数	说明
   AapArn	仅实例身份(ECS)需要配置，选择步骤 1 中创建的应用接入点。
   本地主机HTTP端口号	默认值为 2025 。 KMS Agent 的 HTTP 服务默认监听地址为 127.0.0.1:2025 。 重要 在 ECS 的安全组中放行该端口，具体操作参见安全组配置。
   最大并发数	应用访问 Agent 时， Agent 能处理的最大并发请求数。默认值为 800 ，最大 1000 。
   KMS地域	KMS 实例所在地域，例如 cn-hangzhou 。可以和 ECS 同地域，可不同地域。 不同地域时：确保 ECS 和 KMS 实例网络互通，具体参考通过高速通道实现本地 IDC 与专有网络互通、通过 VPN 网关实现本地 IDC 与专有网络互通或通过云企业网实现本地 IDC 与专有网络互通。 同地域时：若 ECS 和 KMS 实例属于不同 VPC ，将 ECS 所属 VPC 绑定到 KMS 实例以实现网络互通，具体操作参见绑定 VPC 到 KMS 实例。
   访问KMS服务域名	KMS 服务的访问地址。 作用域选择KMS共享网关： VPC 网络访问：填写 VPC 访问地址，例如kms-vpc.cn-hangzhou.aliyuncs.com。 公网访问：填写公网访问地址，例如kms.cn-hangzhou.aliyuncs.com。 作用域选择指定的 KMS 实例：填写 KMS 私有网络地址，格式为<YOUR_KMS_INSTANCE_ID>.cryptoservice.kms.aliyuncs.com。
   内存限制	KMS Agent 可以缓存的凭据数，默认值 1000 ，最大值 1000 。
   缓存时间TTL（秒）	Agent 的缓存时间 TTL ，建议根据凭据的轮转间隔设置，默认为 300 秒。

3. 高级设置（可选）：展开高级设置后显示以下配置项，一般使用默认值即可。

   参数	说明
   SSRF请求头	应用访问 Agent 时携带的 SSRF 请求头，默认为["X-KMS-Token","X-Vault-Token"]。
   SSRF令牌环境变量	Agent 使用该环境变量中的文件验证 SSRF 请求，默认为["KMS_TOKEN","KMS_SESSION_TOKEN","KMS_CONTAINER_AUTHORIZATION_TOKEN"]。
   日志级别	日志记录的级别，默认为 debug 。支持设置为 debug 、 info 、 warn 、 error ，建议使用默认取值 debug 以便调试。
   日志路径	日志文件存储路径，默认为./logs/。
   日志文件大小（MB）	单个日志文件的最大限制，默认取值 100 MiB 。
   日志备份文件数	保留的日志文件数量，默认取值 2 。

4. 配置完成后，单击确定， KMS 将通过云助手自动向目标 ECS 实例远程安装 Agent ，无需手动登录服务器操作。

步骤 3 ：安装验证

安装验证页是配置向导的最后一个页签，在此页面可查看安装状态并获取应用程序集成代码示例。

1. 单击刷新按钮，在KMS最近操作结果列查看安装状态。状态为运行中表示 Agent 安装成功。

2. 关闭配置面板后，可在 ECS 快速接入列表页查看 Agent 状态。

3. 可登录 ECS 实例，执行以下 curl 命令验证 Agent 是否正常工作：

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

   返回 HTTP 200 表示 Agent 工作正常。如果返回其他状态码，参考"故障排查"部分排查问题。

curl 示例

从本地 Agent 获取凭据，可以通过文件读取 Token 或直接写入 Token ：

# 从文件读取 token
curl -v -H "X-KMS-Token:$(</var/run/kmstoken)" 'http://localhost:2025/secretsmanager/get?secretId=agent-test'

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

Go 示例

package main

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

func main() {
    // 支持指定 versionStage 或 versionId 以获取特定凭据值。
    // 以获取指定 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))
}