Key Management Service:KMS Agent の概要

仕組み

エージェントはシークレット値をメモリにキャッシュし、設定した Time To Live (TTL) に基づいて定期的に更新します。アプリケーションがシークレットをリクエストした場合：

1. エージェントは、サーバーサイドリクエストフォージェリ (SSRF) トークンファイルを使用してリクエストを検証します。

2. 有効なキャッシュ値が存在し、有効期限が切れていない場合、エージェントはそれを直ちに返します (キャッシュヒット)。

3. 有効なキャッシュエントリが存在しない場合、エージェントはリクエストを KMS に転送します。KMS はエージェントの ID を検証し、シークレットを復号して返します。エージェントはキャッシュを更新し、値をアプリケーションに返します (キャッシュミス)。

以下の図は、両方のフローを示しています。

• キャッシュヒットのプロセス

• キャッシュミス (キャッシュなし、またはキャッシュ期限切れ) のプロセス

エージェントは、物理サーバー、Elastic Compute Service (ECS) などの仮想マシン、または Kubernetes ポッドなどのコンテナ上のアプリケーションとともにデプロイします。ソースコードとデプロイガイドについては、「alibabacloud-kms-agent」をご参照ください。

アーキテクチャ

エージェントは、HTTP サーバー、キャッシュ、KMS クライアント、ログの 4 つのコンポーネントで構成されます。

4 つのコンポーネントはすべて、単一の設定ファイルで設定します。以下の設定例は、利用可能なすべてのオプションとそのデフォルト値を示しています。

# すべての設定項目
[Server]
# オプション。デフォルト値は 2025 です。エージェントは 127.0.0.1:2025 でリッスンします。
HttpPort = 2025
# オプション。デフォルト値は ["X-KMS-Token", "X-Vault-Token"] です。
# エージェントへのリクエストには SSRF ヘッダーを含める必要があります。ヘッダーがないリクエストは拒否されます。
SSRFHeaders = ["X-KMS-Token"]
# オプション。デフォルト値は ["KMS_TOKEN", "KMS_SESSION_TOKEN", "KMS_CONTAINER_AUTHORIZATION_TOKEN"] です。
# 値はリテラル文字列またはファイルパス (例: file:///var/run/awssmatoken) を指定できます。
# エージェントは指定された環境変数から SSRF トークンを読み取り、
# アプリケーションのリクエストヘッダー内のトークンと比較します。一致した場合にのみアクセスが許可されます。
SSRFEnvVariables = ["KMS_TOKEN"]
# オプション。デフォルト値は "/v1/" です。パスベースのリクエストの URI プレフィックスです。
PathPrefix = "/v1/"
# オプション。デフォルト値は 800 です。同時リクエストの最大数です。
MaxConn = 800
# オプション。デフォルト値は 0 です。
# 0: KMS GetSecretValue レスポンス形式
# 1: AWS Secrets Manager GetSecretValue レスポンス形式
# 2: HashiCorp Vault KV 構造
ResponseType = 0
# オプション。デフォルト値は true です。
# true の場合、KMS が一時的に到達不能な場合、エージェントは期限切れのキャッシュ値を返します。
IgnoreTransientErrors = true

[Kms]
# オプション。デフォルト値は cn-hangzhou です。
Region = "cn-hangzhou"
# オプション。デフォルト値は kms.cn-hangzhou.aliyuncs.com です。
# 共有ゲートウェイエンドポイントと専用ゲートウェイエンドポイントの両方に対応しています。
Endpoint = "kms.cn-hangzhou.aliyuncs.com"

[Cache]
# オプション。デフォルト値は InMemory です。現在、インメモリキャッシングのみがサポートされています。
CacheType = "InMemory"
# オプション。デフォルト値は 1000 です。0 に設定すると、キャッシングが無効になり、すべての
# リクエストが直接 KMS に送信されます。
CacheSize = 1000
# オプション。デフォルト値は 300 s です。
TtlSeconds = 300
# オプション。デフォルト値は false です。
# false: キャッシュが満杯の場合、最も古いキャッシュされたシークレットを削除します。
# true: アクセス頻度に基づいて、Least Recently Used (LRU) のシークレットを削除します。
EnableLRU = false

[Log]
# オプション。デフォルト値は Debug です。
LogLevel = "Debug"
# オプション。デフォルト値は、アプリケーションの起動ディレクトリを基準とした ./logs/ です。
LogPath = "./logs/"
# オプション。デフォルト値は 100 MB です。ログファイルあたりの最大サイズです。
MaxSize = 100
# オプション。デフォルト値は 2 です。保持するログファイルの数です。
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())

セキュリティ

安定性

エージェントは、ネットワークの切断や一時的な障害が発生した場合でも、利用可能な状態を維持するように設計されています。

起動時の自己チェック：起動時に、エージェントは KMS への接続性を検証します。検証に失敗した場合、エージェントは劣化した状態で起動するのではなく、終了します。

自動リトライ：エージェントは、Alibaba Cloud SDK (V2) の組み込みリトライロジックを使用します。HTTP 429 (スロットリング) および HTTP 500 (内部サーバーエラー) のレスポンスに対しては、エクスポネンシャルバックオフ方式を使用して 3 回リトライします。

古いキャッシュへのフォールバック：IgnoreTransientErrors が有効な場合 (デフォルト)、KMS が一時的に到達不能な場合、エージェントは最新のキャッシュ値を返します。これにより、短時間のネットワークやサーバーの問題によるアプリケーションの障害を防ぎます。

高可用性：

• Linux (systemd): systemd はエージェントプロセスを監視し、クラッシュした場合は自動的に再起動します。

• Kubernetes (init コンテナ)：init コンテナとしてデプロイされるため、エージェントに障害が発生するとコンテナが再起動され、アプリケーションの安定性が保証されます。

KMS Agent と Secret Client の比較

KMS Agent は中間層として機能し、アプリケーションは KMS を直接呼び出すのではなく、エージェントを介してシークレットにアクセスします。Secret Client は、各アプリケーションに KMS SDK を統合します。デプロイ規模とアクセス制御の要件に基づいて選択してください。