KMS Agent是一個HTTP代理服務，負責向KMS服務擷取憑據值並緩衝在記憶體中，應用通過HTTP請求向KMS Agent擷取憑據值。通過部署KMS Agent，可以簡化應用訪問KMS的身份認證與緩衝管理流程，適用於大規模應用訪問KMS的情境。同時，KMS Agent能夠降低應用改造成本，確保統一的整合標準。本文介紹如何部署KMS Agent。
KMS Agent擷取憑據流程
KMS Agent使用記憶體緩衝憑據值，根據您設定的TTL時間定期重新整理緩衝的憑據值。當業務應用通過HTTP請求向KMS Agent請求憑據值時，KMS Agent通過SSRF Token檔案驗證請求的合法性，若緩衝中存在有效憑據值則直接返回，否則向KMS服務轉寄請求，KMS服務驗證KMS Agent身份通過後，從KMS解密憑據並返回，KMS Agent更新緩衝後通過HTTP訊息將憑據值返回給業務應用。流程如下圖所示：
命中緩衝的流程。
未命中緩衝的流程。
KMS Agent需要和業務應用部署在一起，支援多環境部署，包括本地物理機、虛擬機器（如ECS）、容器（如K8s Pod）。您可以訪問alibabacloud-kms-agent，瞭解更多KMS Agent代碼資訊。
適用範圍
KMS Agent僅適用於KMS 3.0執行個體，若目前的版本過低，請先升級或購買3.0執行個體，具體操作請參見購買和啟用KMS執行個體。
功能模組
KMS Agent代理由HTTP Server模組、Cache模組、KMS配置模組、Log模組這四個模組組成。
您可以通過在設定檔中設定相應參數來配置各功能模組。設定檔如下：
# 全部配置項
[Server]
# 可選, 預設值為 2025， Agent預設監聽地址127.0.0.1:2025
HttpPort = 2025
# 可選, 預設值為 ["X-KMS-Token", "X-Vault-Token"]。
# 訪問Agent必須攜帶SSRF Header, 否則禁止訪問。
SSRFHeaders = ["X-KMS-Token"]
# 可選，預設值為 ["KMS_TOKEN", "KMS_SESSION_TOKEN", "KMS_CONTAINER_AUTHORIZATION_TOKEN"]，變數值可以是具體值，或者檔案路徑如 file:///var/run/awssmatoken.
# Agent從Env擷取SSRF Token，與應用訪問Header攜帶的 Token比較，一致才允許訪問。
SSRFEnvVariables = ["KMS_TOKEN"]
# 可選, 預設值為 "/v1/".
# 基於路徑訪問時請求的URI首碼
PathPrefix = "/v1/"
# 可選, 預設值為 800
# 同時能夠並發請求的最大值
MaxConn = 800
# 可選, 預設值為 0
# 0: 憑據內容按照KMS GetSecretvalue API Response 格式返回； 1： 憑據內容按照 AWS SeceretManager GetSecretvalue API Response 格式返回; 2: 以 HashiCorp KV 結構返回。
ResponseType = 0
# 可選, 預設值 true
# IgnoreTransientErrors為 true，當緩衝失效後， 而訪問遠端KMS遇到失敗，Response會返回已經在記憶體裡失效的緩衝憑證。
IgnoreTransientErrors = true
[Kms]
# 可選,預設值為 cn-hangzhou
# KMS所在的地區
Region = "cn-hangzhou"
# 可選, 預設值為 kms.cn-hangzhou.aliyuncs.com
# Endpoint可以是共用網關Endpoint，也可以是專屬網關Endpoint
Endpoint = "kms.cn-hangzhou.aliyuncs.com"
[Cache]
# 可選,預設為 InMemory，當前僅支援記憶體緩衝
CacheType = "InMemory"
# 可選, 預設緩衝大小 1000 個憑據，當 CacheSize=0 時，不使用緩衝，每次請求都訪問遠端KMS。
CacheSize = 1000
# 可選, 緩衝時效性，預設值是 300s.
TtlSeconds = 300
# 可選, 緩衝淘汰策略，不填預設為 false.
# 當緩衝憑據到了CacheSize上限，取值false表示按照緩衝時間刪除最早存入緩衝憑據，取值true表示按照使用頻率淘汰最近一次使用時間最長的憑據。
EnableLRU = false
[Log]
# 可選, 預設記錄層級 Debug
LogLevel = "Debug"
# 可選, 預設日誌儲存應用啟動目錄的 ./logs/
LogPath = "./logs/"
# 可選, 預設單個日誌大小 100M
MaxSize = 100
# 可選, 預設保留2個記錄檔數量
MaxBackups = 2HTTP Server模組。
用於響應應用程式檢索憑據的請求。KMS Agent返回的憑據值預設與GetSecretValue的響應格式相同，也可以通過在設定檔中設定ResponseType參數返回其他格式。
Cache模組。
KMS Agent內建記憶體緩衝機制，將憑據緩衝在記憶體中，憑據值在緩衝中未加密，業務應用直接讀取本機快取，減少對KMS服務的頻繁請求。使用者可以設定緩衝時間、緩衝大小、淘汰策略，避免憑據到期導致業務中斷。
重要建議您通過設定記憶體保護機制、設定合理的KMS Agent進程存取權限以及部署記憶體流失偵查工具等措施，增強緩衝中的憑據值的儲存安全性。
KMS配置模組。
支援設定地區、網關地址（Endpoint），網關地址支援共用網關Endpoint和專屬網關Endpoint。
說明使用專屬網關Endpoint時，KMS Agent已經內建了全地區專屬網關的CA認證，使用者無需配置CA認證。
Log模組。
基於流行的Zap日誌架構， 提供JSON格式的日誌，支援使用者配置單個記錄檔的大小限制和最多保留的記錄檔數量。
安全性
身份認證與授權
KMS Agent訪問KMS。
KMS Agent訪問KMS使用預設憑證鏈，自動按優先順序檢測環境變數、ECS執行個體RAM角色、設定檔等認證方式，不允許使用者在配置裡直接使用明文AccessKey。詳細介紹，請參見預設憑據鏈。Linux環境部署推薦使用ECS執行個體RAM角色，K8s Sidecar容器部署推薦使用RRSA， 其他環境推薦使用環境變數。
訪問KMS服務時通過RAM權限原則限制對憑據的訪問時，KMS Agent需要具有擷取憑據值的許可權，由於憑據值是加密儲存的，還需要具有解密密鑰的許可權，請在設定Agent的許可權時遵循許可權最小化原則。
業務應用訪問KMS Agent。
KMS Agent啟動時產生SSRF Token檔案（如
/var/run/kmstoken），應用程式在向KMS Agent發起HTTP請求時，必須在要求標頭中攜帶該SSRF Token，Agent會對其進行校正，只有校正通過請求才會被處理，否則返回失敗響應。Linux環境部署情境。
SSRF Token檔案預設只允許KMS Agent與應用程式所屬的系統使用者讀取，其他進程禁止訪問SSRF Token檔案。
Sidecar容器部署。
採用Sidecar模式與業務應用程式容器同Pod部署，SSRF Token檔案預設僅在Pod內部可見，其他Pod或外部服務無法直接存取。
通訊安全
KMS Agent與KMS服務之間的通訊使用TLS協議來確保資料轉送過程的安全，以防止被攻擊或竊聽。相比使用共用網關Endpoint，建議您使用專屬網關Endpoint訪問KMS服務，該方式業務請求僅在VPC網路內傳輸，可以避免請求暴露到公網，從而提供更高的安全性。
KMS Agent只監聽127.0.0.1，即只有在同一台機器上啟動並執行應用程式或進程能夠與KMS Agent進行通訊，外部網路中的任何裝置都無法串連到KMS Agent。
支援日誌
所有通過KMS Agent擷取憑據的操作，均以日誌形式儲存在您設定的日誌路徑中，便於您審計操作記錄。
穩定性
KMS Agent通過自檢、重試機制等，確保在複雜網路環境和突發故障情境下的服務連續性。
啟動自檢機制。
KMS Agent啟動時會驗證KMS的連通性，驗證失敗則終止啟動。
錯誤重試機制。
KMS Agent依賴阿里雲SDK（V2）與KMS服務進行通訊，遇到網路異常時，會利用阿里雲SDK（V2）內建的錯誤重試邏輯自動嘗試重新發起請求。當遇到服務端限流（HTTP 429）或伺服器內部錯誤（HTTP 500）時，會採用間隔時間指數退避方法重試3次。
故障時使用到期緩衝。
在KMS Agent設定檔中設定IgnoreTransientErrors參數， 當遇到網路或服務端故障時，KMS Agent會檢查並返回舊的快取資料，確保應用程式不會由於短時間故障而無法擷取憑據。IgnoreTransientErrors參數預設開啟。
基於systemd或Sidecar容器的高可用性保障。
Linux環境部署：KMS Agent被systemd託管，進程中斷後會自動重啟。
Sidecar容器部署：把Sidecar配置為Init容器，確保KMS Agent在業務容器啟動之前完成初始化。
KMS Agent優勢
效能和可靠性。
KMS Agent在記憶體中緩衝憑據值，高頻訪問情境可以減少對KMS服務的頻繁請求，避免高頻訪問可能引起的限流，從而提高效能和業務可用性。
相容性。
KMS Agent基於標準化HTTP介面提供服務，支援任意程式設計語言的業務應用直接調用。當業務的多個應用屬於不同語言時，使用KMS Agent可以降低整合難度。
簡化整合。
通過KMS Agent，可以解耦應用與KMS，KMS Agent可以減少應用程式與KMS服務互動所需的複雜性，應用程式只需與KMS Agent進行通訊，無需直接處理訪問KMS服務時的身分識別驗證、API調用等。
集中化管理及可擴充性。
對於企業級多應用情境，使用KMS Agent可以統一管理和控制存取權限，減少在每個用戶端上配置許可權，從而保證各應用整合過程中的統一性。當業務需要擴充時，使用KMS Agent便於新應用整合，減少使用SDK可能導致的許可權配置及代碼改造。
KMS Agent與憑據用戶端對比
KMS Agent作為中介層，應用通過Agent間接訪問KMS服務，使用憑據用戶端需要應用通過SDK直接調用KMS服務的API。兩者之間的差異請參見下表。
對比維度 | KMS Agent | 憑據用戶端 |
部署位置 | 作為獨立進程部署（如Sidecar容器），與應用解耦。 | 與應用代碼整合，作為依賴庫。 |
存取控制 | KMS Agent作為唯一訪問入口，可集中實施權限原則管控。 | 需在每個應用中配置訪問身份及權限原則，策略分散。 |
語言支援 | Agent提供通用HTTP介面，支援任意語言的應用。 | 提供Java（Java 8及以上版本）、Python、Go語言。 |
業務效能 | KMS Agent在記憶體緩衝憑據值，針對高頻擷取憑據值的情境，可以減少訪問延遲且降低限流風險。 | 每次請求均需訪問遠端KMS服務，高頻訪問時可能會限流。 |
憑據輪轉情境處理 | 通過在KMS Agent中設定TTL時間，當超過TTL時間長度時會向KMS服務擷取憑據值，減少憑據輪轉可能導致的憑據失效問題。 | 通過配置憑據緩衝機制及錯誤重試機制，當憑據失效時會自動從KMS服務重新擷取憑據。 |
整合複雜度 | 應用無需整合SDK，僅需調用KMS Agent提供的HTTP介面，應用程式無需處理KMS的互動邏輯，整合方式更簡單。 當業務涉及多語言應用時，使用KMS Agent還可保證整合品質的統一性。 | 需在代碼中調用API，處理重試、錯誤、緩衝機制，當業務涉及多個應用時整合複雜度較高。 |
維護成本 | 多個應用的情境下，當權限原則等出現變更時，可以統一維護KMS Agent配置，應用無感知。 | 多個應用的情境下，當權限原則等出現變更時，每個應用需單獨修改配置。 |
針對多應用、多語言的企業級使用者，如果您需要保證權限原則的集中控制，降低應用整合的複雜度，保證整合品質的統一性時可優先使用KMS Agent。針對小型或單一應用，無需複雜存取控制策略時，可優先使用憑據用戶端。