すべてのプロダクト
Search
ドキュメントセンター

Key Management Service:ACK からのクイックアクセス

最終更新日:Aug 08, 2026

Container Service for Kubernetes (ACK) 上でコンテナ化されたワークロードを実行する際、アプリケーションコード内に AccessKey をハードコードするとセキュリティリスクが生じ、認証情報のローテーションも困難になります。KMS クラウドネイティブアクセス機能は、Pod に KMS エージェントサイドカーを注入することでこのリスクを解消し、アプリケーションがローカル HTTP リクエストを通じて KMS で管理されている認証情報を安全に取得できるようにします。

仕組み

Key Management Service (KMS) のクラウドネイティブアクセス機能は、コンポーネントのインストールおよび構成をガイド付きワークフローで提供します。ご利用の Container Service for Kubernetes (ACK) クラスター内の Pod が HTTP リクエストを送信すると、Helm コンポーネント ack-kms-agent-webhook-injector によって自動的に Pod に注入された KMS エージェントがそのリクエストを受信し、OpenID Connect (OIDC) JWT または Resource Access Management (RAM) ロールを使用して認証を行います。KMS が権限を検証した後、認証情報をエージェント経由で返却します。エージェントは認証情報をローカルにキャッシュすることで、繰り返しのリクエストを削減し、認証情報取得のレイテンシを低減します。

範囲

KMS エージェントのインストール

クラスター作成時の有効化

ACK マネージドクラスターまたは ACK Edge クラスターを作成する際は、クラスター構成ステップで詳細オプション(任意)を展開し、RRSA OIDCの横にある有効化をクリックします。

image

既存クラスターへの有効化

  1. ACK コンソールにログインします。左側のナビゲーションウィンドウでクラスターをクリックします。

  2. ご利用のクラスター名をクリックします。左側のナビゲーションウィンドウでクラスター情報をクリックします。

  3. 基本情報タブで、セキュリティと監査セクションまでスクロールし、RRSA OIDCの横にある有効化をクリックします。

    image

  4. RRSA の有効化ダイアログボックスで確認をクリックします。クラスターのステータスが更新中から実行中に変化するまで待ちます。これで RRSA が有効化されます。

手順 1:名前空間およびサービスアカウントの作成(任意)

名前空間は、開発・テスト・本番などの異なる環境向けに ACK クラスターを論理的に分離された仮想スペースに分割します。デフォルトでは、異なる名前空間内のアプリケーションは互いのリソースにアクセスできません。すでにビジネスアプリケーション用の名前空間およびサービスアカウントがある場合は、この手順をスキップしてください。

  1. 名前空間を作成します。

    1. YAML ファイルを使用して名前空間を作成します。以下の例では、app1-namespace.yaml を使用して app1-dev という名前の名前空間を作成します。

      apiVersion: v1
      kind: Namespace
      metadata:
        name: app1-dev
    2. 次のコマンドを実行して名前空間を作成します。

      kubectl apply -f app1-namespace.yaml
    3. 名前空間が作成されたことを確認します。出力に app1-dev が含まれている場合、名前空間は正常に作成されています。

      kubectl get namespaces
  2. サービスアカウントを作成します。

    1. YAML ファイルを使用してサービスアカウントを作成します。以下の例では、前の手順で作成した app1-dev 名前空間内に app1-service という名前のサービスアカウントを app1-serviceaccount.yaml を使用して作成します。

      apiVersion: v1
      kind: ServiceAccount
      metadata:
        name: app1-service
        namespace: app1-dev
    2. 次のコマンドを実行してサービスアカウントを作成します。

      kubectl apply -f app1-serviceaccount.yaml
    3. サービスアカウントが作成されたことを確認します。出力に app1-service が含まれている場合、サービスアカウントは正常に作成されています。

      kubectl get serviceaccount -n app1-dev

手順 2:権限の構成

KMS クラウドネイティブアクセスは、以下の 2 つの認証方式をサポートしています。

説明

ほとんどのシナリオでは、構成がシンプルな OpenID Connect (OIDC) を推奨します。既存の RAM ロールポリシーを再利用したい場合やクロスアカウントアクセスが必要な場合は、RAM ロールを使用してください。

認証方式

特徴

OIDC (ACK)

ACK クラスターは OpenID Connect (OIDC) 標準 JWT を使用して認証します。エージェントは自動的にサービスアカウントトークンを取得し、Pod の ID を KMS に証明します。RAM ロールは不要で、構成が最もシンプルです。

RAM ロール

RAM ロールの STS 一時認証情報を使用して KMS にアクセスします。この方式は、既存の RAM ロール設定を再利用したいシナリオに適しています。

OIDC (ACK)

  1. KMS コンソールにログインします。左側のナビゲーションウィンドウでアプリケーションアクセス > クラウドネイティブ統合を選択します。コンテナセクションで、ご利用の ACK クラスターを見つけ、操作をクリックします。

  2. 表示される構成パネルで、Authentication MethodOIDC (ACK)に設定します。

  3. 以下のパラメーターを構成します。

    パラメーター

    説明

    名前空間

    Pod が存在する名前空間の名前(例:app1-dev)。

    ServiceAccount

    Pod が使用するサービスアカウント(例:app1-service)。

    PodNamePrefix

    Pod 名のプレフィックス。このパラメーターを構成すると、プレフィックスに一致する名前の Pod のみが検証を通過できます。このパラメーターを構成しない場合、名前空間とサービスアカウントのみが検証されます。

    スコープ

    KMS へのアクセス方法。有効な値:

    • 指定された KMS インスタンス:インスタンスエンドポイントを使用して特定の KMS インスタンス内のキーおよび認証情報にアクセスします。

    • Shared KMS Gateway:KMS サービスエンドポイントを使用して認証情報にアクセスします。

    Application Access Point Name

    識別および管理用のアプリケーションアクセスポイント(アクセス認証情報)のカスタム名。

    Policy Name

    RAM ポリシーのカスタム名。このステップで直接ポリシーを作成でき、RAM コンソールで事前に作成する必要はありません。

    RBAC の権限

    RBAC(ロールベースアクセス制御)の権限レベル。アプリケーションの認証情報操作権限を決定します。

    • 指定された KMS インスタンスが範囲に選択されている場合:

      • CryptoServiceKeyUser:KMS インスタンス内のキーを使用して認証情報を暗号化できます。

      • CryptoServiceSecretUser:KMS インスタンス内の認証情報の使用を許可し、インスタンス向けの認証情報 API をサポートします。

    • Shared KMS Gatewayが範囲に選択されている場合:SecretUser のみがサポートされ、現在のアカウント配下のすべての認証情報の使用が許可されます。

    アクセス可能のリソース

    アプリケーションがアクセスする必要のある認証情報およびキー(認証情報の暗号化・復号に使用)を選択します。

    重要

    複数の認証情報を選択し、認証情報名の合計文字数が制限を超える場合、「パラメーターが無効です」というエラーが返されます。その場合はワイルドカードを使用して許可する認証情報を指定してください(例:secret/rds-ibm*)。これにより、rds-ibm で始まる認証情報へのアクセスが許可されます。

    Description

    任意。アプリケーションアクセスポイントの詳細な説明。最大長:8,192 文字。

  4. OK をクリックして次に進みます。

RAM ロール

  1. ID プロバイダー情報を取得します。

    1. ACK コンソールにログインします。左側のナビゲーションウィンドウでクラスターリストをクリックします。

    2. 対象クラスターの名前をクリックして詳細ページに移動します。

    3. 基本情報タブで、セキュリティと監査セクション内の RRSA (RAM Roles for Service Accounts) OIDC の横にある「有効」ラベルにポインターを合わせると、プロバイダー URL および ARN 情報が表示されます。プロバイダー URL は https://oidc-ack-<region>.oss-<region>.aliyuncs.com/<cluster_id> 形式、プロバイダー ARN は acs:ram::<account_id>:oidc-provider/ack-rrsa-<cluster_id> 形式です。

  2. RAM ロールを作成します。

    1. RAM コンソールにログインします。左側のナビゲーションウィンドウでアイデンティティ > ロールを選択し、ロールの作成をクリックします。

    2. 信頼できるエンティティタイプとしてIdPを選択し、エディターに切り替えをクリックします。

    3. ビジュアルエディターセクションで、以下の項目を構成します。

      • 基本構成

        パラメーター

        説明

        Effect

        Allow を選択します。

        Action

        デフォルト値 sts:AssumeRole のままにします。

        Condition

        キーが oidc:sub、演算子が StringEquals、値が system:serviceaccount:<namespace>:<ServiceAccountName> の条件を追加します。ここで、namespace および ServiceAccountName は、ワークロードを実行している Pod の名前空間およびサービスアカウントに対応します。

      • プリンシパルを以下のように構成します。

        1. プリンシパルとしてID プロバイダーを選択し、下の編集をクリックします。

        2. ID プロバイダー構成ページで、以下のパラメーターを構成し、OK をクリックします。

          パラメーター

          説明

          IdP タイプ

          OIDC を選択します。

          ID プロバイダー

          RRSA 有効化後に ACK クラスターが自動作成した ID プロバイダーを選択します:ack-rrsa-<cluster_id>

    4. 構成が完了したら、OK をクリックしてロール名(例:app1-rrsa)を設定し、確認 をクリックします。

  3. ポリシーを作成し、RAM ロールにアタッチします。詳細については、「カスタムポリシーの作成」および「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. ポリシーリストに戻り、対象のポリシーを見つけ、操作列のID にアタッチをクリックします。

    4. プリンシパルセクションで、作成した RAM ロールを選択し、確認をクリックします。

手順 3:ack-kms-agent-webhook-injector のインストール

  1. ACK コンソールにログインします。左側のナビゲーションウィンドウでクラスターリストをクリックします。

  2. クラスターページで、対象クラスターの名前をクリックして詳細ページに移動します。

  3. 詳細ページの左側ナビゲーションウィンドウでアプリケーション > Helmを選択します。

  4. Helm ページでデプロイをクリックします。基本情報セクションを構成し、をクリックします。

    パラメーター

    説明

    アプリケーション名

    デフォルトのアプリケーション名 ack-kms-agent-webhook-injector を使用します。

    名前空間

    チャートのデフォルト名前空間 kube-system を使用します。ACK クラスターごとに 1 つの名前空間にインストールすればよく、複数回インストールする必要はありません。

    発生元

    デフォルト:Marketplace。このパラメーターは変更できません。

    Chart

    ack-kms-agent-webhook-injector を検索して選択します。

  5. 確認ダイアログが表示されたら、情報を確認してをクリックします。

  6. パラメーターページで、手順 2 で選択した認証方式に基づいてパラメーターを構成します。

    • OIDC (ACK):デフォルト構成のままにします。

    • RAM ロール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
  7. 構成が完了したら、OK をクリックします。アプリケーション詳細ページにリダイレクトされます。

手順 4:エージェントサイドカーの注入

  1. Pod アノテーションの追加:アノテーションキーを kms-agent-webhook-injector/inject、値を true に設定します。

    1. クラスター詳細ページの左側ナビゲーションウィンドウでワークロード > デプロイメントを選択します。

    2. ワークロードが実行されている名前空間に切り替え、Deployment に Pod アノテーションを追加します。

      重要

      RAM ロール認証方式の場合、Deployment YAML 構成を変更し、ServiceAccountName パラメーターをワークロードを実行している Pod のサービスアカウント名(例:app1-service)に設定します。OIDC (ACK) 認証方式の場合は、変更は不要です。

      • 新しい Deployment の作成

        イメージによる作成

        1. Deployment リストの上部でイメージによる作成をクリックし、パラメーターを構成します。

        2. [上級] を構成する場合は、[Labels and Annotations] セクションに移動し、Pod アノテーションを追加します。名前 列に kms-agent-webhook-injector/inject を、 列に true を入力します。

        3. 作成するをクリックして完了します。

        YAML のリソースの作成

        1. Deployment リストの上部でYAML のリソースの作成をクリックします。

        2. YAML ファイルを編集し、spec.template.metadata.annotations 配下に kms-agent-webhook-injector/inject: "true" を追加します(該当セクションが存在しない場合は新たに作成します)。

        3. 作成するをクリックして完了します。

      • 既存の Deployment の変更

        1. 対象ワークロードを見つけ、アクション > 詳細をクリックします。

        2. 詳細ページの右上隅でYAML の編集をクリックします。

        3. spec.template.metadata.annotations 配下に kms-agent-webhook-injector/inject: "true" を追加します(該当セクションが存在しない場合は新たに作成します)。

        4. 更新をクリックし、ワークロードが準備完了になるまで待ちます。

  2. 注入の確認

    1. ワークロード > デプロイメントに戻り、対象 Deployment の名前をクリックして詳細ページに移動します。

    2. ポッドタブで、イメージ列を確認します。KMS エージェントがサイドカーとして Pod に注入されていることが確認できます。

      説明

      Pod に KMS エージェントが 2 回注入されているように見える場合があります。これは初期化用の init コンテナが使用されているためです。init コンテナは初期化完了後に終了(Terminated)し、アプリケーションに悪影響を及ぼしたり、計算リソースを継続的に消費したりすることはありません。

アプリケーション統合

Deployment に KMS エージェントが注入された後、アプリケーションコンテナは KMS エージェントへの HTTP リクエストを通じて KMS から認証情報を取得できます。コード内に AccessKey を構成する必要はありません。以下の例は認証情報の取得方法を示しています。<SecretId> は実際の認証情報名に置き換えてください。

重要
  • KMS エージェントは 127.0.0.1 のみでリッスンしており、同じマシン上のアプリケーションまたはプロセスのみが通信できます。外部ネットワークデバイスからの接続はできません。アクセスアドレスは localhost または 127.0.0.1 のみをサポートし、アプリケーションのローカル IP はサポートしません。以下の例では localhost を使用しています。

  • KMS エージェントアクセス方式に加え、KMS は SDK 経由でのアクセスもサポートしています。詳細な操作については、「Secrets Manager クライアント」をご参照ください。

OIDC (ACK)

curl を使用

  • 次のコマンドを実行して認証情報を取得します。

    # トークンをファイルから読み取り、AapArn を指定
    curl -v -H "X-KMS-Token:$(</var/run/kmstoken/token)"
    -H "AapArn:<AapArn>" 'http://localhost:2025/secretsmanager/get?secretId=<SecretId>'
  • $(<file) 構文は bash や zsh などのシェルでのみサポートされます。Pod ベースイメージが Alpine(デフォルトシェルは BusyBox ash)またはこの構文をサポートしない他のシェルを使用している場合は、代わりに以下のコマンドを使用してください。

    # トークンをファイルから読み取り、AapArn を指定(Alpine/BusyBox 互換)
    curl -v -H "X-KMS-Token:$(cat /var/run/kmstoken/token)"
    -H "AapArn:<AapArn>" 'http://localhost:2025/secretsmanager/get?secretId=<SecretId>'

wget を使用

  • 次のコマンドを実行して認証情報を取得します。

    # トークンをファイルから読み取り、AapArn を指定
    wget -q -O - --header "X-KMS-Token:$(</var/run/kmstoken/token)" --header "AapArn:<AapArn>" 'http://localhost:2025/secretsmanager/get?secretId=<SecretId>'
  • $(<file) 構文は bash や zsh などのシェルでのみサポートされます。Pod ベースイメージが Alpine(デフォルトシェルは ash)またはこの構文をサポートしない他のシェルを使用している場合は、代わりに以下のコマンドを使用してください。

    # トークンをファイルから読み取り、AapArn を指定(Alpine 互換)
    wget -q -O - --header "X-KMS-Token:$(cat /var/run/kmstoken/token)" --header "AapArn:<AapArn>" 'http://localhost:2025/secretsmanager/get?secretId=<SecretId>'

Go コード例

以下の例は 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("トークンファイルの読み取りエラー: %v\n", err)
    }

    req, err := http.NewRequest("GET", url, nil)
    if err != nil {
        fmt.Printf("リクエスト作成エラー: %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("リクエスト送信エラー: %v \n", err)
    }
    defer resp.Body.Close()

    body, _ := ioutil.ReadAll(resp.Body)
    fmt.Printf("ステータスコード %d - %s \n", resp.StatusCode, string(body))
}

RAM ロール

curl を使用

  • 次のコマンドを実行して認証情報を取得します。

    # トークンをファイルから読み取り
    curl -v -H "X-KMS-Token:$(</var/run/kmstoken/token)" 'http://localhost:2025/secretsmanager/get?secretId=<SecretId>'
    
    # またはトークンを直接記述
    curl -v -H "X-KMS-Token:<token>" 'http://localhost:2025/secretsmanager/get?secretId=<SecretId>'
  • $(<file) 構文は bash や zsh などのシェルでのみサポートされます。Pod ベースイメージが Alpine(デフォルトシェルは BusyBox ash)またはこの構文をサポートしない他のシェルを使用している場合は、代わりに以下のコマンドを使用してください。

    # トークンをファイルから読み取り(Alpine/BusyBox 互換)
    curl -v -H "X-KMS-Token:$(cat /var/run/kmstoken/token)" 'http://localhost:2025/secretsmanager/get?secretId=<SecretId>'

wget を使用

  • 次のコマンドを実行して認証情報を取得します。

    # トークンをファイルから読み取り
    wget -q -O - --header "X-KMS-Token:$(</var/run/kmstoken/token)" 'http://localhost:2025/secretsmanager/get?secretId=<SecretId>'
    
    # またはトークンを直接記述
    wget -q -O - --header "X-KMS-Token:<token>" 'http://localhost:2025/secretsmanager/get?secretId=<SecretId>'
  • $(<file) 構文は bash や zsh などのシェルでのみサポートされます。Pod ベースイメージが Alpine(デフォルトシェルは ash)またはこの構文をサポートしない他のシェルを使用している場合は、代わりに以下のコマンドを使用してください。

    # トークンをファイルから読み取り(Alpine 互換)
    wget -q -O - --header "X-KMS-Token:$(cat /var/run/kmstoken/token)" 'http://localhost:2025/secretsmanager/get?secretId=<SecretId>'

Go コード例

以下の例は 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("トークンファイルの読み取りエラー: %v\n", err)
    }

    req, err := http.NewRequest("GET", url, nil)
    if err != nil {
        fmt.Printf("リクエスト作成エラー: %v\n", err)
    }

    req.Header.Add("X-KMS-Token", string(token))

    client := &http.Client{}
    resp, err := client.Do(req)
    if err != nil {
        fmt.Printf("リクエスト送信エラー: %v \n", err)
    }
    defer resp.Body.Close()

    body, _ := ioutil.ReadAll(resp.Body)
    fmt.Printf("ステータスコード %d - %s \n", resp.StatusCode, string(body))
}

課金

  • KMS 側のコスト:

    • サブスクリプション:KMS エージェントを使用する前に KMS インスタンスを購入します。KMS エージェント自体には追加料金は発生しません。詳細については、「サブスクリプション」をご参照ください。

    • 従量課金:すでに発生している料金に加え、KMS エージェントが API 呼び出しを通じて認証情報を取得する際に追加の QPS 料金が適用されます。詳細については、「従量課金」をご参照ください。

  • ACK 側のコスト:

    ack-kms-agent-webhook-injector コンポーネントは無料です。注入されたサイドカーおよび Webhook ワークロードが消費する計算リソースに対して追加コストが発生する可能性があります。

    • ack-kms-agent-webhook-injector コンポーネントをインストールすると、Webhook サービスワークロードが生成され、計算リソースを消費してコストが発生します。設定ファイルでこのワークロードの CPU およびメモリ使用量を制限してください。

    • 対象となるワークロードを作成または更新すると、ack-kms-agent-webhook-injector が KMS エージェントをサイドカーとしてコンテナに注入します。KMS エージェントは計算リソースを消費してコストが発生します。

トラブルシューティング

KMS エージェントのインストールまたは使用中に問題が発生した場合は、以下の一般的な問題を参考にトラブルシューティングを行ってください。

原因

解決策

エージェントのインストールに失敗

kubectl get nodes を実行してクラスターが実行中の状態であることを確認します。RAM ユーザーの KMS 権限を確認してください。

ネットワークが到達不能またはタイムアウト

ACK クラスターが KMS サービスに到達可能であることを確認します。VPC 経由で KMS にアクセスする場合、ACK クラスターが配置されている VPC が KMS インスタンスとネットワーク接続されていることを確認してください。

権限が不十分

以下の構成を確認してください。

  • OIDC (ACK):名前空間およびサービスアカウントを確認し、PodNamePrefix フィルターが構成されていないか確認してください。

  • RAM ロール:RAM ロールが ID プロバイダーに正しくアタッチされており、ポリシーに kms:GetSecretValue および kms:Decrypt 権限が含まれていることを確認してください。

エージェントの注入に失敗

ack-kms-agent-webhook-injector コンポーネントが正しくインストールされ、正常に実行されていることを確認します。Pod アノテーション kms-agent-webhook-injector/inject: "true" が正しく構成されていることを確認してください。

RRSA が有効化されていない

OIDC (ACK) 認証方式は RRSA (RAM Roles for Service Accounts) 機能に依存しています。ACK コンソールでクラスターのセキュリティおよび監査モジュールに移動し、RRSA を有効化してください。詳細な手順については、手順 2 の RAM ロールタブの ID プロバイダー設定をご参照ください。