ACK 快速接入 - Key Management Service

KMS 雲原生接入是一種面向 ACK 叢集的憑據分發方案，通過在 Pod 中注入 KMS Agent Sidecar，使應用通過本地 HTTP 要求即可安全擷取託管在 KMS 中的憑據，無需在代碼中管理 AccessKey。

工作原理

KMS 雲原生接入功能提供嚮導式的組件安裝與配置流程。ACK 叢集中的 Pod 發起 HTTP 要求後，KMS Agent（通過 Helm 組件 ack-kms-agent-webhook-injector 自動注入到 Pod 中）接收請求並通過 OIDC JWT 或 RAM 角色完成認證。KMS 驗證許可權後返回憑據，最終由 Agent 將憑據返回給應用程式。Agent 在本機快取憑據，減少重複請求，降低憑據擷取延遲。

適用範圍

ACK叢集類型限制：支援ACK託管與專有叢集、ACK Serverless叢集。
說明
ACK專有叢集、ACK註冊叢集接入，請參見ACK容器環境中部署KMS Agent擷取憑據。
地區限制：ACK叢集與KMS執行個體需要在同一地區。
效能限制：由於每個Pod獨立運行KMS Agent Sidercar容器，若業務部署大量Pod，在身分識別驗證過程中如果STS Token請求每分鐘超過500次則會觸發限流，進而對KMS Agent的正常工作產生影響。

配置接入

建立叢集時開啟

建立ACK託管叢集和ACK Edge叢集時，您可以在叢集配置的進階選項（選填）地區，選中開啟RRSA功能。

在叢集資訊頁面開啟

登入Container Service管理主控台，在左側導覽列選擇叢集列表。
在叢集列表頁面，單擊目的地組群名稱，然後在左側導覽列，選擇叢集資訊。
在基本資料頁簽的安全與審計地區，單擊RRSA OIDC右側的開啟。
在彈出的啟用 RRSA對話方塊，單擊確定。

在基本資料地區，當叢集狀態由更新中變為運行中後，表明該叢集的RRSA特性已變更完成。

步驟 1 ：建立 Namespace 和 ServiceAccount（可選）

Namespace 將 ACK 叢集劃分為邏輯隔離的虛擬空間，用於區分開發、測試、生產等環境。不同 Namespace 中的應用預設無法互訪資源。若業務應用已建立過對應的空間和帳號，可跳過此步驟。

建立 Namespace 。
1. 通過 YAML（以 app1-namespace.yaml 為例）檔案建立 Namespace（以 app1-dev 為例）：
```
apiVersion: v1
kind: Namespace
metadata:
  name: app1-dev
```
2. 執行以下命令建立 Namespace ：
```
kubectl apply -f app1-namespace.yaml
```
3. 驗證 Namespace 是否建立成功：若輸出中包含 app1-dev，即代表建立成功。
```
kubectl get namespaces
```
建立 ServiceAccount 。
1. 通過 YAML（以 app1-serviceaccount.yaml 為例）檔案建立 ServiceAccount（以 app1-service 為例），其中 namespace 為上一步建立的命名空間 app1-dev。
```
apiVersion: v1
kind: ServiceAccount
metadata:
  name: app1-service
  namespace: app1-dev
```
2. 執行以下命令建立 ServiceAccount ：
```
kubectl apply -f app1-serviceaccount.yaml
```
3. 驗證 ServiceAccount 是否建立成功：若輸出中包含 app1-service，即代表建立成功。
```
kubectl get serviceaccount -n app1-dev
```

步驟 2 ：許可權配置

KMS 雲原生接入提供以下兩種認證方式。

認證方式	特點
OIDC(ACK)	ACK 叢集通過 OIDC 標準 JWT 認證，Agent 自動擷取 ServiceAccount Token，向 KMS 證明 Pod 身份。無需建立 RAM 角色，配置最簡單。
RAMRole	通過 RAM 角色的 STS 臨時憑證訪問 KMS，適用於需要複用已有 RAM 角色體系的情境。

OIDC(ACK)

登入Key Management Service控制台，在左側導覽列，選擇应用接入 > 云原生接入，在弹性计算地區的 ACK 列表中，單擊目標 ACK 執行個體操作列的配置 ACK 接入。
在彈出的配置面板中，選擇认证方式為OIDC(ACK)。

配置以下參數：

參數	說明
Namespace	Pod 所在的空間名稱，如 `app1-dev`。
ServiceAccount	Pod 使用的帳號，如 `app1-service`。
PodNamePrefix	Pod 名稱首碼。配置後，僅允許名稱匹配首碼的 Pod 通過校正，未配置時，僅校正 Namespace 和 ServiceAccount 。
作用域	選擇訪問 KMS 的方式。可選值：指定的 KMS 執行個體：通過 KMS 執行個體 Endpoint 訪問指定執行個體中的密鑰和憑據。 KMS共享网关：通過 KMS 服務 Endpoint 訪問憑據。
应用接入点名称	自訂應用存取點（訪問憑證）的名稱，便於後續識別和管理。
权限策略名称	自訂 RAM 權限原則名稱。在此步驟中可直接建立權限原則，無需預先在 RAM 控制台建立。
RBAC权限	選擇 RBAC 權限等級，決定應用程式對憑據的操作許可權。範圍選擇指定的 KMS 執行個體： CryptoServiceKeyUser：允許使用 KMS 執行個體中的密鑰，用於憑據加密。 CryptoServiceSecretUser：允許使用 KMS 執行個體中的憑據，支援執行個體 API 中的憑據介面。範圍選擇KMS共享网关：僅支援選擇SecretUser，允許使用當前帳號下的所有憑據。
允许访问的资源	勾選應用需要訪問的憑據和密鑰（用於憑據加解密）。重要勾選多個憑據時，如果憑據名稱總長度超限會報"參數非法"錯誤。此時請使用萬用字元配置允許訪問的憑據，例如配置為 `secret/rds-ibm*`，表示允許訪問首碼為 rds-ibm 的憑據。
描述信息	選填。對該應用存取點的詳細說明，最大支援 8192 字元。

單擊確認，進入下一步。

RAMRole

擷取供應商資訊
1. 登入Container Service管理主控台，在左側導覽列選擇叢集列表。
2. 單擊目的地組群名稱，進入詳情頁。
3. 在基本資料頁簽的安全與審計地區，將滑鼠懸浮至 RRSA OIDC 右側已開啟上面，查看供應商的 URL 連結和 ARN 資訊。

建立 RAM 角色。

登入RAM 控制台，在左側導覽列選擇身份管理 > 角色，單擊创建角色。
選擇可信實體類型為身份提供商，單擊切換編輯器。

在可視化編輯地區，完成如下配置：

基礎配置

配置項	描述
效果	選擇允許。
操作	保持預設值 `sts:AssumeRole`。
條件	新增 `oidc:sub` 條件，運算子 `StringEquals`，值為 `system:serviceaccount:<namespace>:<ServiceAccountName>`（`namespace`、`ServiceAccountName` 為業務運行 Pod 對應的空間和帳號名稱）。

主體配置：
1. 選擇主體為身份供應商後，單擊下方的編輯。
2. 在身份供應商配置頁面，配置相關參數後，單擊確定。
  配置項
  描述
  身份供應商類型
  選擇 OIDC 。
  身份供應商
  選擇上一步中開啟 RRSA 後 ACK 叢集自動建立的身份供應商 ack-rrsa-<cluster_id>。

配置完成後，單擊確定設定角色名稱（如 app1-rrsa），單擊確認。

建立權限原則並授權：具體操作，請參見建立自訂權限原則和管理RAM角色的許可權。
1. 在左側導覽列選擇权限管理 > 权限策略。
2. 單擊创建权限策略，選擇指令碼編輯，參見如下樣本完成配置。
  說明
  本文以權限原則名稱 dev-role-for-rrsa-kms-policy 為例，策略內容以僅允許訪問帶有 env:app1 標籤的憑據為例。
```
{
    "Version": "1",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "kms:Decrypt",
                "kms:GetSecretValue"
            ],
            "Resource": "*",
            "Condition": {
                "StringEqualsIgnoreCase": {
                    "kms:tag/secret": [
                        "app1"
                    ]
                }
            }
        }
    ]
}
```
3. 返回策略列表，單擊目標策略操作列的新增授權。
4. 在授權主體地區勾選上一步建立的 RAM 角色後，單擊確認新增授權。

步驟 3 ：安裝 ack-kms-agent-webhook-injector

登入Container Service管理主控台，在左側導覽列選擇叢集列表。
在叢集列表頁面，單擊目的地組群名稱，進入叢集詳情頁。
在詳情頁左側導覽列，選擇應用 > Helm。

在 Helm 頁面，單擊建立，配置基本資料，然後單擊下一步。

配置項	說明
應用程式名稱	建議使用預設應用程式名稱 `ack-kms-agent-webhook-injector`。
命名空間	建議使用 Chart 預設的Runspace `kube-system`。一個 ACK 叢集中安裝到一個命名空間即可，無需重複安裝。
來源	預設為應用市場，不支援修改。
Chart	搜尋並選中 `ack-kms-agent-webhook-injector`。

彈出提醒對話方塊時，確認資訊無誤後，單擊是。
在參數配置頁面，根據步驟 2 選擇的認證方式進行配置。
- OIDC(ACK)：保持預設配置即可。
- RAMRole：agent.auth.roleArn 留空，agent.auth.roleArnMapping 需配置為 <Namespace>:<ServiceAccountName>: <RAM Role ARN>。以下以步驟 2 建立的資料為例：
  說明
  Namespace、ServiceAccountName 為業務運行 Pod 對應的空間和帳號名稱，RAM Role ARN 可在 RAM 角色詳情頁查看。
```
agent:
  auth:
    roleArn:
    roleArnMapping:
      app1-dev:app1-service: acs:ram::190325303126****:role/app1-rrsa
```
配置完成後，單擊確定，跳轉至應用詳情頁。

步驟 4 ：注入 Agent Sidecar

添加 Pod 註解：註解名稱為 kms-agent-webhook-injector/inject，值為 true。
1. 在目的地組群詳情頁左側導覽列，選擇工作負載 > 無狀態。
2. 切換至業務實際啟動並執行命名空間，為工作負載（Deployment）添加 Pod 註解。
  重要
  若為 RAMRole 認證方式，請修改工作負載的 YAML 設定檔，將 ServiceAccountName 參數改為業務運行 Pod 對應的服務賬戶名稱（本文為 app1-service）。若為 OIDC(ACK) 認證方式，則無需修改。
  - 新增 Deployment
    使用鏡像建立
    單擊 Deployment 列表上方的使用鏡像建立，完成各項配置。
    填寫高級配置時，在標籤和註解地區添加 Pod 註解：名稱填入 kms-agent-webhook-injector/inject，值填入 true。
    完成後單擊建立。
    使用YAML建立資源
    單擊 Deployment 列表上方的使用YAML建立資源。
    編輯 YAML 中 spec.template.metadata.annotations（若不存在，需手動建立），添加 kms-agent-webhook-injector/inject: "true"。
    完成後單擊建立。
  - 已有 Deployment
    1. 定位到目標工作負載，單擊操作列的詳情。
    2. 在詳情頁單擊右上方的YAML 編輯。
    3. 向 spec.template.metadata.annotations（若不存在，需手動建立）中添加 kms-agent-webhook-injector/inject: "true"。
    4. 單擊更新，等待工作負載重新就緒。
注入驗證
1. 返回工作負載 > 無狀態，單擊目標業務 Deployment 名稱，進入詳情頁。
2. 在工作負載容器組頁簽的鏡像列，可以看到 KMS Agent 已經作為 Sidecar 注入到 Pod 中。
  說明
  Pod 可能被注入兩次 KMS Agent 鏡像，這是因為使用了初始化容器（initContainer）進行初始化。初始化容器在初始化完成後會終止（Terminated），不會對應用產生負面影響，也不會持續佔用計算資源。

應用程式整合

當 Deployment 注入了 KMS Agent 後，在應用程式容器中可通過 HTTP 協議向 KMS Agent 發起請求，擷取儲存在 KMS 中的憑據，無需在代碼中配置 AccessKey。以下樣本展示如何調用，使用時請將樣本中的 <SecretId> 替換為實際的憑據名稱。

重要

KMS Agent 只監聽 127.0.0.1，即僅允許同一機器上的應用或進程與其通訊，外部網路裝置無法串連。訪問地址僅支援 localhost 或 127.0.0.1，不支援應用的本地 IP。以下樣本以 localhost 為例。
除 KMS Agent 接入方式外，KMS 還支援通過 SDK 接入。具體操作，請參見憑據用戶端。

OIDC(ACK)

使用 curl

# 從檔案讀取 token，指定 AapArn
curl -v -H "X-KMS-Token:$(</var/run/kmstoken/token)"
-H "AapArn:<AapArn>" 'http://localhost:2025/secretsmanager/get?secretId=<SecretId>'

Go 程式碼範例

package main

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

func main() {

    //支援指定versionStage或versionId以擷取特定憑據值。
    //以擷取指定versionId的憑據值為例， url := fmt.Sprintf("http://localhost:2025/secretsmanager/get?secretId=%s&versionId=%s", "agent-test", "version-id")
    aapArn := "acs:kms:cn-hangzhou:19*********224:applicationaccesspoint/****"
    url := fmt.Sprintf("http://localhost:2025/secretsmanager/get?secretId=%s", "agent-test")

    token, err := ioutil.ReadFile("/var/run/kmstoken/token")
    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))
    req.Header.Add("AapArn", aapArn)

    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))
}

RAMRole

使用 curl

# 從檔案讀取 token
curl -v -H "X-KMS-Token:$(</var/run/kmstoken/token)" 'http://localhost:2025/secretsmanager/get?secretId=<SecretId>'

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

Go 程式碼範例

package main

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

func main() {
    
    //支援指定versionStage或versionId以擷取特定憑據值。
    //以擷取指定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/token")
    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))
}

計費說明

KMS 側的費用：
- 計費方式為訂用帳戶：使用KMS Agent前您需要購買KMS執行個體，使用KMS Agent本身不會額外收取您的費用。詳細介紹，請參見訂用帳戶。
- 計費方式為隨用隨付：除您已產生的費用外，使用KMS Agent擷取憑據時，會因API調用請求產生額外的QPS調用費用。詳細介紹，請參見隨用隨付。
ACK 側的費用：
ack-kms-agent-webhook-injector 組件本身完全免費，但使用該組件的過程中可能會產生額外費用。
- 安裝 ack-kms-agent-webhook-injector 組件後，會產生一個 Webhook 服務工作負載，該負載將佔用一定計算資源併產生費用。可在設定檔中限制該負載的 CPU 和記憶體使用量。
- 建立或更新合格工作負載時，ack-kms-agent-webhook-injector 會將 KMS Agent 以 Sidecar 形式注入到容器中，KMS Agent 會使用一定計算資源併產生費用。

Agent 狀態說明

在雲原生接入列表頁，可查看 ACK 叢集中 KMS Agent 的運行狀態。不同狀態對應的說明和支援的操作如下：

狀態	說明
運行中	Agent 已安裝並正常運行。
未安裝	該 ACK 叢集未安裝 KMS Agent 組件。
未運行	Agent 組件已安裝但當前未運行。
未知	無法擷取 Agent 狀態，請檢查叢集網路設定。

故障排查

如果在安裝或使用 KMS Agent 過程中遇到問題，請參見以下常見問題進行排查：

失敗原因	解決方案
Agent 安裝失敗	檢查 ACK 叢集是否處於運行中狀態，確認當前帳號具有 KMS 相關操作許可權。
網路不通或逾時	確認 ACK 叢集與 KMS 服務之間網路互連。如果通過 VPC 訪問 KMS，請確保 ACK 叢集所在 VPC 與 KMS 執行個體網路連通。
許可權不足	檢查以下配置項： OIDC(ACK)：Namespace 和 ServiceAccount 是否正確，是否設定了 PodNamePrefix 過濾。 RAMRole：RAM 角色已正確綁定身份供應商，且權限原則包含 `kms:GetSecretValue` 和 `kms:Decrypt` 許可權。
Agent 注入失敗	檢查 ack-kms-agent-webhook-injector 組件是否正確安裝並正常運行。確認 Pod 註解 `kms-agent-webhook-injector/inject: "true"` 已正確配置。
RRSA 未開啟	OIDC(ACK) 認證方式依賴 RRSA 功能。請在 ACK 控制台的叢集安全與審計模組中開啟 RRSA，具體操作請參見步驟 2 中的 RRSA 開啟步驟。

配置項	描述
身份供應商類型	選擇 OIDC 。
身份供應商	選擇上一步中開啟 RRSA 後 ACK 叢集自動建立的身份供應商 `ack-rrsa-<cluster_id>`。

工作原理

適用範圍

配置接入

建立叢集時開啟

在叢集資訊頁面開啟

步驟 1 ：建立 Namespace 和 ServiceAccount（可選）

步驟 2 ：許可權配置

OIDC(ACK)

RAMRole

步驟 3 ：安裝 ack-kms-agent-webhook-injector

步驟 4 ：注入 Agent Sidecar

使用鏡像建立

使用YAML建立資源

應用程式整合

OIDC(ACK)

使用 curl

Go 程式碼範例

RAMRole

使用 curl

Go 程式碼範例

計費說明

Agent 狀態說明

故障排查