MENU

AKSでAzure Key Vault provider for Secrets Store CSI Driverを使う方法と確認ポイント

Azure

Azure Kubernetes Service（AKS）でシークレットを安全に扱うなら、今回確認すべきポイントは明確です。Azure Key Vault provider for Secrets Store CSI DriverをAKSアドオンとして有効化し、Key Vaultをシークレットの保管元にしたうえで、PodにはCSIボリューム経由で必要な値だけを渡します。あわせて、マネージドID、Azure RBAC、SecretProviderClass、ネットワーク制限、ローテーション設定を確認しないと、デプロイ後に「Podが起動しない」「値が更新されない」「Key Vaultにアクセスできない」といった問題が起きやすくなります。

2026年5月更新の公式情報で重要なのは、単なる機能紹介ではなく、AKSでKey Vault連携を本番運用するための確認手順が整理されている点です。新規クラスタだけでなく既存AKSクラスタ、Terraform管理、オープンソース版Secrets Store CSI Driverからの移行、Workload IDやユーザー割り当てマネージドIDを使った認証設計まで見直す必要があります。Microsoft Learn上では対象ページの最終更新が2026年5月5日と表示されています。日本時間で2026年5月6日前後に確認する公式更新として、管理者・開発者が押さえるべき実務ポイントを整理します。(Microsoft Learn)

ITtripTOOLS
その「面倒」、無料で解決。 ITtripがつくる、6つの道具。 無料ツール一覧へ すべて無料・追加課金なし
先頭0を守るCSV編集こわさないCSV PDFに直接書き込みかけるPDF 写真＋説明をPDFに写レポ スマホ⇄PCで共有コピペ便 · 文章・写真 みんなの日程を調整日程Fit 匿名質問・投票を集めるKOEQ
目次

AKSのAzure Key Vault provider for Secrets Store CSI Driverとは

Azure Key Vault provider for Secrets Store CSI Driverは、Azure Key VaultをAKSのシークレットストアとして使い、Podにシークレット、キー、証明書をCSIボリュームとしてマウントするための仕組みです。公式ドキュメントでは、CSI inline volume、複数オブジェクトの単一ボリュームへのマウント、SecretProviderClass CRD、Windowsコンテナ、Kubernetes Secretとの同期、自動ローテーションをサポートする機能として説明されています。(Microsoft Learn)

従来のようにKubernetes Secretへ値を直接登録してアプリケーションに渡す構成では、シークレットの作成・更新・削除の運用がクラスタ側に寄りがちです。Key Vault providerを使うと、シークレットの保管元をAzure Key Vaultに寄せ、AKS側では「どのKey Vaultから、どのIDで、どのオブジェクトを、どのPodに渡すか」を定義します。

実務では、次のようなケースで特に効果があります。

利用シーンKey Vault providerが有効な理由
DB接続文字列やAPIキーを複数アプリで使う保管元をKey Vaultに集約し、アプリごとの参照設定を分けられる
TLS証明書や秘密鍵をPodへ渡すKey Vault上の証明書・キーをCSIボリュームとして扱える
シークレットローテーションを運用に組み込みたい自動ローテーションやKubernetes Secret同期を構成できる
AKSとKey Vaultのアクセス権を分離したいAzure RBACやマネージドIDで最小権限を設計できる
既存のKubernetes Secret運用を段階的に見直したいsecretObjectsを使ってKubernetes Secretとの同期も選べる

重要なのは、Key Vault providerは「Kubernetes Secretを完全に不要にする機能」ではないという点です。アプリケーションの実装や既存マニフェストによっては、CSIボリュームとして直接読む構成と、Key Vaultの内容をKubernetes Secretに同期する構成を使い分けます。

何が変わるのか：AKSのシークレット管理をKey Vault中心に再設計する必要がある

今回の公式情報は、AKSのシークレット管理について「Key Vault連携をどう有効化し、どう検証し、どこで失敗しやすいか」を整理した内容です。大きなポイントは、AKSアドオンとしてazure-keyvault-secrets-providerを有効化し、Key VaultへのアクセスにはマネージドIDやWorkload IDを使う点です。新規クラスタではaz aks createに--enable-addons azure-keyvault-secrets-providerを指定し、既存クラスタではaz aks enable-addonsで有効化します。(Microsoft Learn)

アドオンを有効化すると、AKSはazurekeyvaultsecretsprovider-xxxxというユーザー割り当てマネージドIDをノードリソースグループに作成し、Virtual Machine Scale Setへ自動的に割り当てます。公式ドキュメントでは、このIDの作成を防ぐことはサポートされていないと明記されています。つまり、既存のID管理ポリシーや命名ルールがある組織では、アドオン有効化前にノードリソースグループ内の自動作成リソースを棚卸し対象に含める必要があります。(Microsoft Learn)

また、Key Vault側はAzure RBACを前提に確認する流れが強調されています。新規Key VaultではAzure RBACが既定で有効になり、既存Key VaultでAzure RBACが無効な場合はaz keyvault update --enable-rbac-authorizationで有効化できます。Key Vaultのアクセスモデルを変更すると既存アプリの権限にも影響するため、本番環境では事前にロール割り当てと既存アクセスポリシーの棚卸しが必要です。(Microsoft Learn)

対象者と影響範囲

この更新で確認すべき対象は、AKSクラスタ管理者だけではありません。シークレットの参照方法はアプリケーションの起動、環境変数、証明書読み込み、ローテーション時の挙動に直結するため、開発者、SRE、セキュリティ担当、IaC担当が同じ前提で設計する必要があります。

対象者主な影響最初に確認すべきこと
AKS管理者アドオン有効化、ノードリソースグループ、VMSSへのID割り当てaddonProfiles.azureKeyvaultSecretsProviderとkube-system内Podの状態
アプリ開発者シークレットの読み込み方法、再読み込み、Pod再起動要否ファイルマウントで読むか、Kubernetes Secret経由か、環境変数か
セキュリティ担当Key VaultのRBAC、IDごとの最小権限、証明書・キーの扱いsecret、key、certごとの必要ロール
SRE/運用担当ローテーション、監視、障害時の切り分け自動ローテーション設定、メトリクス、イベントログ
Terraform/IaC担当クラスタとKey Vault設定のコード化key_vault_secrets_provider、RBAC、SecretProviderClassの管理範囲
移行担当オープンソース版CSI DriverからAKS管理アドオンへの移行既存HelmリリースやYAMLデプロイの削除手順

特に注意したいのは、アプリケーションがシークレットを環境変数として読んでいる場合です。ファイルマウントされた値やKubernetes Secretのボリュームは更新を検知できる余地がありますが、環境変数はPod起動時に値が固定されます。公式情報でも、環境変数としてKubernetes Secretを使う場合は、最新値を反映するためにPodの再起動やローリングアップグレードが必要とされています。(Microsoft Learn)

管理者が最初に確認すべき設定

AKSでAzure Key Vault provider for Secrets Store CSI Driverを使う前に、まずクラスタ、Key Vault、ID、ネットワーク、アプリケーションの5点を確認します。いきなり本番Podへ適用するのではなく、検証用namespaceとテスト用Key Vaultで動作確認してから段階的に展開するのが安全です。

確認項目確認内容見落とした場合のリスク
Azure CLI公式手順ではAzure CLI 2.30.0以降が前提コマンドやパラメータが使えない
AKSアドオンazure-keyvault-secrets-providerが有効かSecretProviderClassを作ってもPodがマウントできない
マネージドIDアドオン作成IDまたは独自IDのclientId、objectIdKey Vaultアクセスで認証エラーになる
Key Vault RBACsecret、key、certに必要なロール権限不足でPod起動時にマウント失敗する
ネットワークPrivate Endpoint、UDR、Firewall、必要ポートKey Vaultへ到達できない、メトリクス取得不可
SecretProviderClassKey Vault名、tenantId、objectName、objectType参照先違い、ファイル名違い、同期失敗
ローテーション自動ローテーション有無、ポーリング間隔値を更新してもアプリに反映されない

ネットワーク分離されたAKSクラスタでは、Key VaultへPrivate Endpointでアクセスする構成が推奨されています。また、userDefinedRoutingとFirewallを使う環境では、必要な送信ルールやFQDNの許可を確認する必要があります。Ingressを制限している場合は、公式情報でポート9808と8095の開放確認も求められています。(Microsoft Learn)

新規AKSクラスタで有効化する基本手順

新規クラスタでは、AKS作成時にazure-keyvault-secrets-providerアドオンを有効化します。公式手順では、az aks createに--enable-addons azure-keyvault-secrets-providerを指定します。Workload IDを使いたい場合は、クラスタ作成時に--enable-oidc-issuerと--enable-workload-identityも含める必要があります。(Microsoft Learn)

az aks create \
  --name <cluster-name> \
  --resource-group <resource-group> \
  --enable-addons azure-keyvault-secrets-provider \
  --generate-ssh-keys

Microsoft Entra Workload IDを前提にする場合は、次のようにOIDC issuerとWorkload Identityも有効化します。

az aks create \
  --name <cluster-name> \
  --resource-group <resource-group> \
  --enable-addons azure-keyvault-secrets-provider \
  --enable-oidc-issuer \
  --enable-workload-identity \
  --generate-ssh-keys

本番向けには、クラスタ作成コマンドだけで完了と考えないことが重要です。アドオンを有効化しても、Key Vaultへのアクセス権、SecretProviderClass、Podのボリューム設定、アプリ側の読み込み処理がそろって初めてシークレットを使えるようになります。

既存AKSクラスタで有効化する手順

既存クラスタでは、az aks enable-addonsでアドオンを追加します。アドオン有効化後、AKSはKey Vaultアクセスに使えるユーザー割り当てマネージドIDを作成します。(Microsoft Learn)

az aks enable-addons \
  --addons azure-keyvault-secrets-provider \
  --name <cluster-name> \
  --resource-group <resource-group>

有効化後は、次のコマンドでアドオンプロファイルを確認します。

az aks show \
  --name <cluster-name> \
  --resource-group <resource-group> \
  --query addonProfiles

確認すべきポイントは、azureKeyvaultSecretsProvider.enabledがtrueになっていること、identity.clientIdとidentity.objectIdが取得できること、resourceIdがノードリソースグループ内のazurekeyvaultsecretsprovider-...を指していることです。

さらに、kube-system namespaceでCSI DriverとAzure providerのPodが稼働しているか確認します。公式手順では、secrets-store-csi-driverとsecrets-store-provider-azureラベルを指定してPodを確認します。(Microsoft Learn)

kubectl get pods -n kube-system \
  -l 'app in (secrets-store-csi-driver,secrets-store-provider-azure)' \
  -o wide

すべてのノードでPodがRunningになっていない場合、ノードプール、OS種別、DaemonSet、ネットワーク制限、イメージ取得可否を確認します。特定ノードだけ失敗する場合は、そのノードのtaint、nodeSelector、セキュリティ設定、ネットワーク到達性も疑うべきです。

Terraform管理ではkey_vault_secrets_providerを明示する

TerraformでAKSを管理している場合、ポータルやAzure CLIでアドオンを有効化すると、Terraformの状態との差分が発生します。公式情報では、azurerm_kubernetes_clusterにkey_vault_secrets_providerブロックを設定する例が示されています。新規・既存どちらの場合も、IaCで管理しているクラスタはTerraform側に設定を反映してから展開するのが基本です。(Microsoft Learn)

resource "azurerm_kubernetes_cluster" "aks" {
  name                = "<cluster-name>"
  resource_group_name = "<resource-group>"

  key_vault_secrets_provider {
    secret_rotation_enabled = false
  }
}

ここで注意したいのは、secret_rotation_enabled = falseのままでは自動ローテーションが有効にならないことです。シークレットをKey Vaultで更新したときにPod側へ反映したい場合は、ローテーション設計もあわせて決める必要があります。

TerraformでKey Vaultも管理する場合は、enable_rbac_authorization = trueを設定し、必要なロール割り当てもコード化します。手動でロールを付与すると、環境差分や監査漏れが起きやすくなります。

Key Vault側で必要なRBACを確認する

Key Vault providerを有効化しても、Key Vault側にアクセス権がなければPodはシークレットを取得できません。公式情報では、Key VaultにAzure RBACが有効な場合、secretタイプにはKey Vault Secrets User、keyまたはcertificateタイプにはKey Vault Certificate Userが必要とされています。(Microsoft Learn)

Key Vault上のオブジェクトSecretProviderClassのobjectType主な用途必要なロールの考え方
シークレットsecretAPIキー、接続文字列、パスワードKey Vault Secrets User
キーkey暗号化キー、署名キーKey Vault Certificate Userが必要なケースを確認
証明書certTLS証明書などKey Vault Certificate User
証明書の秘密鍵込みデータsecretとして取得する場合がある証明書チェーンや秘密鍵を含むPEM取得する型に応じて権限を確認

ロール割り当てでは、アプリケーションが使うIDだけに必要最小限の権限を付与します。すべてのワークロードで同じマネージドIDを使うと、あるnamespaceのPodが別アプリ用のシークレットを参照できる設計になりやすくなります。新規設計では、アプリ、namespace、環境ごとにIDとKey Vaultスコープを分けることを検討してください。

RBACの反映には数分かかることがあります。公式手順でも、ロール割り当て後に反映まで時間がかかる可能性があると説明されています。デプロイ直後にPodが失敗した場合、設定ミスだけでなくRBAC反映待ちも切り分け対象に入れます。(Microsoft Learn)

SecretProviderClassで定義する内容

SecretProviderClassは、AKSのPodがKey Vaultから何を取得するかを定義するCRDです。ここでKey Vault名、テナントID、認証方式、取得するオブジェクト名、オブジェクトタイプを指定します。公式サンプルでは、Workload IDの場合はclientID、ユーザー割り当てマネージドIDの場合はuseVMManagedIdentityとuserAssignedIdentityIDを使う例が示されています。(Microsoft Learn)

ユーザー割り当てマネージドIDを使う場合のイメージは次のとおりです。

apiVersion: secrets-store.csi.x-k8s.io/v1
kind: SecretProviderClass
metadata:
  name: azure-kvname-user-msi
spec:
  provider: azure
  parameters:
    usePodIdentity: "false"
    useVMManagedIdentity: "true"
    userAssignedIdentityID: "<client-id>"
    keyvaultName: "<key-vault-name>"
    cloudName: ""
    objects: |
      array:
        - |
          objectName: db-password
          objectType: secret
          objectVersion: ""
        - |
          objectName: tls-cert
          objectType: cert
          objectVersion: ""
    tenantId: "<tenant-id>"

Workload IDを使う場合は、ServiceAccountにazure.workload.identity/client-idアノテーションを付け、Pod側にazure.workload.identity/use: "true"ラベルを設定する流れになります。公式情報では、AKSクラスタがトークン発行者となり、Microsoft Entra IDがOIDCを使ってServiceAccountトークンを検証し、Microsoft Entraトークンへ交換する仕組みとして説明されています。(Microsoft Learn)

設計上の注意点は次のとおりです。

設定注意点
metadata.namenamespace内で一意にする
objectNameKey Vault上の実際のオブジェクト名と一致させる
objectAlias使う場合は同期先のobjectName指定にも影響する
objectTypesecret、key、certを取り違えない
objectVersion空なら通常は最新バージョンを参照する。固定したい場合のみ指定する
tenantIdKey VaultのテナントIDを指定する
userAssignedIdentityIDobjectIdではなくclientIdを指定する例が示されている

よくある失敗は、objectNameとアプリが読むファイル名の認識違いです。objectAliasを使う場合、マウントされるファイル名が変わるため、アプリケーション設定やKubernetes Secret同期のobjectNameもあわせて確認します。公式情報でも、objectAliasを使う場合はYAML側の更新が必要だと注意されています。(Microsoft Learn)

Pod側ではCSIボリュームとしてマウントする

Podでは、secrets-store.csi.k8s.ioドライバーを指定してCSIボリュームを定義し、volumeAttributes.secretProviderClassで作成済みのSecretProviderClassを参照します。

kind: Pod
apiVersion: v1
metadata:
  name: app-using-keyvault
spec:
  containers:
    - name: app
      image: <your-image>
      volumeMounts:
        - name: secrets-store
          mountPath: "/mnt/secrets-store"
          readOnly: true
  volumes:
    - name: secrets-store
      csi:
        driver: secrets-store.csi.k8s.io
        readOnly: true
        volumeAttributes:
          secretProviderClass: "azure-kvname-user-msi"

アプリケーション側では、/mnt/secrets-store/db-passwordのようなファイルとして値を読みます。ここで重要なのは、シークレットをログに出さないことです。公式サンプルでは検証のためにkubectl execでシークレット内容を表示する例がありますが、本番運用では値そのものを標準出力やログに出すべきではありません。検証時も、存在確認はls、権限確認はイベントやメトリクス、アプリの起動状態で確認するのが安全です。(Microsoft Learn)

Kubernetes Secretへ同期する場合の注意点

既存アプリがKubernetes Secretを前提にしている場合、SecretProviderClassのsecretObjectsを使って、マウントした内容をKubernetes Secretに同期できます。公式情報では、secretObjectsフィールドで同期先のKubernetes Secret名、キー、タイプを定義する例が示されています。(Microsoft Learn)

apiVersion: secrets-store.csi.x-k8s.io/v1
kind: SecretProviderClass
metadata:
  name: azure-sync
spec:
  provider: azure
  secretObjects:
    - secretName: app-secret
      type: Opaque
      data:
        - objectName: db-password
          key: DB_PASSWORD
  parameters:
    # Key Vault名、ID、objectsなどを定義

ただし、Kubernetes Secret同期には運用上の落とし穴があります。公式情報では、同期されたKubernetes Secretは、シークレットをマウントするPodが起動した後に作成され、そのシークレットを消費するPodを削除するとKubernetes Secretも削除されると説明されています。つまり、Secretだけを先に作っておいて別Podから参照するような運用とは前提が異なります。(Microsoft Learn)

また、secretObjects.data.objectNameは、マウントされたファイル名と一致させる必要があります。objectAliasを使っている場合は、Key Vault上の名前ではなく、エイリアス側に合わせる必要があります。ここを間違えると、Key Vaultから値は取得できているのにKubernetes Secretが期待どおり作られない、という切り分けしにくい障害になります。(Microsoft Learn)

自動ローテーションの挙動を正しく理解する

Azure Key Vault provider for Secrets Store CSI Driverでは、自動ローテーションを有効化すると、定義したポーリング間隔に基づいてPodマウントとSecretProviderClassのsecretObjectsで定義したKubernetes Secretを更新します。公式情報では、既定のローテーションポーリング間隔は2分とされています。(Microsoft Learn)

新規クラスタで自動ローテーションを有効化するには、アドオン有効化に加えて--enable-secret-rotationを指定します。

az aks create \
  --name <cluster-name> \
  --resource-group <resource-group> \
  --enable-addons azure-keyvault-secrets-provider \
  --enable-secret-rotation \
  --generate-ssh-keys

既存クラスタでは、次のようにアドオン設定を更新します。

az aks addon update \
  --resource-group <resource-group> \
  --name <cluster-name> \
  --addon azure-keyvault-secrets-provider \
  --enable-secret-rotation

ポーリング間隔を変更する場合は、--rotation-poll-intervalを指定します。

az aks addon update \
  --resource-group <resource-group> \
  --name <cluster-name> \
  --addon azure-keyvault-secrets-provider \
  --enable-secret-rotation \
  --rotation-poll-interval 5m

ローテーションで最も重要なのは、Key Vaultの値が更新されても、アプリケーションが必ず即時に新しい値を使うとは限らないという点です。公式情報では、アプリケーションがCSIマウント上のファイルを読む場合はファイル変更を監視する必要があり、Kubernetes Secretを環境変数として使う場合はPod再起動が必要とされています。(Microsoft Learn)

アプリの読み方更新時の挙動実務上の対応
CSIボリューム上のファイルを読むマウント内容はローテーションで更新されるアプリがファイル変更を検知して再読み込みする
Kubernetes Secretをボリュームとして読むSecret同期後、ボリューム内容が更新されるアプリがファイル変更を検知する
Kubernetes Secretを環境変数として読む起動時の値が使われ続けるPod再起動やローリング更新を組み込む
subPathでSecretやConfigMapをマウントする自動更新を受け取れないsubPathを避けるか、Pod再起動を前提にする

公式情報では、ConfigMapまたはSecretをsubPathボリュームマウントとして使うコンテナは、シークレットローテーション時に自動更新を受け取れないというKubernetes側の制限も説明されています。変更を反映するには、ファイルシステム変更の監視による再読み込み、またはPod再起動が必要です。(Microsoft Learn)

Workload IDとマネージドIDはどちらを選ぶべきか

公式情報では、Key Vaultへのアクセス方法として、Service Connector with managed identity、Workload ID、ユーザー割り当てマネージドIDが示されています。(Microsoft Learn)

新規に本番設計するなら、まずWorkload IDを候補にします。Workload IDはKubernetes ServiceAccountとMicrosoft Entra ID側のフェデレーションを組み合わせ、Pod単位・ワークロード単位でIDを分けやすいためです。特定アプリだけにKey Vaultの特定シークレットを読ませたい場合、namespaceやServiceAccount単位で権限設計しやすくなります。

一方、アドオンが自動作成するユーザー割り当てマネージドIDを使う構成は、設定が比較的シンプルです。検証環境や小規模な構成では扱いやすいものの、複数アプリが同じIDを共有すると権限が広がりやすくなります。

認証方式向いているケース注意点
Workload IDアプリ単位で権限を分けたい本番環境OIDC issuer、ServiceAccount、フェデレーション設定が必要
アドオン作成のマネージドID検証、小規模環境、シンプルな構成ID共有による権限過多に注意
独自のユーザー割り当てマネージドID既存のID管理ルールに合わせたい環境VMSSまたは対象リソースへの割り当て確認が必要
Service ConnectorポータルやCLIで接続構成を簡略化したい場合自動構成される範囲を理解してIaCとの差分に注意

なお、Microsoft Entra pod-managed identityはプレビューとして提供されていた方式で、公式情報ではWorkload IDがその認証方式を置き換えるものと説明されています。既存環境で古いpod-managed identity前提の設計が残っている場合は、Workload IDまたはマネージドID方式への移行計画を立てるべきです。(Microsoft Learn)

ネットワーク制限環境で失敗しやすいポイント

AKSとKey Vaultを連携する構成では、権限が正しくてもネットワークで失敗することがあります。特にPrivate Cluster、ネットワーク分離、Firewall、UDR、Private Endpointを使っている環境では、Key Vaultへの到達性を必ず検証します。

症状よくある原因確認方法
Podが起動時にマウント失敗するKey Vaultへ到達できないPodイベント、CSI Driverログ、Firewallログ
特定ノードだけ失敗するノードプールごとのネットワーク差分kubectl get pods -o wideでノードを確認
ローテーションされないprovider/driverがKey Vaultへ再取得できないローテーションメトリクス、Key Vaultログ
メトリクスが取れないポートやport-forwardの制限8095、8898への接続確認
既存クラスタで突然失敗するFirewallルールやPrivate DNS変更DNS解決、FQDN許可、Private Endpoint状態

公式情報では、ネットワーク分離クラスタではKey VaultへのPrivate Endpoint設定が推奨され、UDRとFirewallを使う場合は必要な送信ネットワークルールやFQDNを許可する必要があるとされています。Ingress制限がある場合は、9808と8095の確認も必要です。(Microsoft Learn)

実務では、アプリケーションPodの失敗だけを見るのではなく、kube-system内のsecrets-store-csi-driverとsecrets-store-provider-azureのログを確認します。権限エラー、DNSエラー、Key Vault応答遅延、証明書関連エラーは、アプリのログだけでは判断できないことがあります。

監視ではメトリクスを必ず見る

Azure Key Vault providerとSecrets Store CSI Driverは、それぞれメトリクスを提供します。公式情報では、Azure Key Vault provider側はkeyvault_requestやgrpc_request、Secrets Store CSI Driver側はtotal_node_publish_error、total_sync_k8s_secret、total_rotation_reconcile_errorなどのメトリクスが示されています。(Microsoft Learn)

Provider側メトリクスはポート8898、Secrets Store CSI Driver側メトリクスはポート8095で提供されます。ただし、これらのポートは既定ではPod外部へ公開されていません。公式手順では、kubectl port-forwardでローカルから確認する例が示されています。(Microsoft Learn)

kubectl port-forward -n kube-system ds/aks-secrets-store-provider-azure 8898:8898
curl localhost:8898/metrics
kubectl port-forward -n kube-system ds/aks-secrets-store-csi-driver 8095:8095
curl localhost:8095/metrics

本番運用では、少なくとも次の観点で監視を設計します。

監視対象見るべき理由
Key Vault取得時間Key Vaultやネットワークの遅延でPod起動が遅くなる可能性がある
volume mountエラーPod起動失敗の直接原因になりやすい
Kubernetes Secret同期数同期設定が期待どおり動いているか確認できる
ローテーションエラー値更新後にアプリへ反映されない問題を早期検知できる
gRPCエラーproviderとdriver間の通信問題を切り分けやすい

シークレット管理は「一度動けば終わり」ではありません。Key Vaultの値更新、証明書更新、RBAC変更、Firewall変更、ノードプール追加のたびに影響を受けるため、メトリクスとログをセットで確認できる状態にしておく必要があります。

オープンソース版からAKS管理アドオンへ移行する場合

既にオープンソース版のSecrets Store CSI DriverやAzure providerをHelmやYAMLで導入している場合、AKS管理アドオンへ移行する前に既存コンポーネントを整理します。公式情報では、オープンソース版のSecrets Store CSI Driverをhelm deleteで削除し、その後az aks enable-addons --addons azure-keyvault-secrets-providerでAKSアドオンを有効化する手順が示されています。YAMLで導入している場合は、Linuxノード用・Windowsノード用のproviderマニフェストを削除する例も示されています。(Microsoft Learn)

移行で注意すべき点は、単にDriverを入れ替えるだけではないことです。既存のSecretProviderClass、Podマニフェスト、RBAC、ServiceAccount、Key Vault権限、ローテーション設定を確認し、移行後も同じファイル名・同じマウントパス・同じ参照方式でアプリが動くかを検証します。

移行前には、次の順番で確認すると失敗を減らせます。

手順確認内容
既存構成の棚卸しHelmリリース、DaemonSet、SecretProviderClass、Pod参照を一覧化
アプリ影響の確認どのPodがどのシークレットをどのパスで読んでいるか確認
検証環境でAKSアドオンを有効化同じKey VaultとSecretProviderClassで再現テスト
ローテーション確認Key Vault更新後にファイル・Secret・アプリがどう動くか確認
本番移行メンテナンス時間、ロールバック方法、監視を準備して実施

特に、同じクラスタ内にオープンソース版とAKS管理アドオンのコンポーネントが混在すると、トラブル時の切り分けが難しくなります。移行作業では、どのDriverとproviderが実際にPodへマウントしているかを明確にしてください。

アドオンを無効化するときの注意点

検証後にアドオンを無効化する場合や、構成変更のために一時的に停止する場合にも注意が必要です。公式情報では、SecretProviderClassが使用中の場合、アドオンを無効化しようとするとエラーになると説明されています。また、アドオンを無効化しても既存ワークロードはすぐには問題が出ない場合がありますが、Pod再起動やスケールアウトで新しいPodが作られると、Driverが動作していないため起動に失敗します。(Microsoft Learn)

つまり、アドオン無効化は「使っていないはずだから消す」ではなく、次の順番で実施します。

順番作業
1SecretProviderClassの一覧を確認する
2参照しているDeployment、StatefulSet、DaemonSet、Jobを確認する
3シークレット参照を別方式へ切り替える
4Pod再起動テストを行う
5アドオンを無効化する
6既存Podの再作成時に失敗しないことを確認する

本番環境では、アドオン無効化は小さな設定変更ではなく、アプリ起動に影響する変更として扱うべきです。

実務で使える展開前チェックリスト

本番展開前には、次の項目を確認してください。

チェック確認内容
クラスタazure-keyvault-secrets-providerアドオンが有効
ID使用するclientId、objectId、ServiceAccountが明確
Key VaultAzure RBACまたはアクセスポリシーの方式が決まっている
権限secret、key、certごとに必要最小限のロールを付与
ネットワークAKSからKey Vaultへ名前解決・通信できる
SecretProviderClassKey Vault名、tenantId、objectName、objectTypeが正しい
PodCSIボリュームがreadOnlyでマウントされる
ローテーション有効化有無、ポーリング間隔、アプリの再読み込み方法が決まっている
Kubernetes Secret同期secretObjectsのファイル名・キー名が一致している
監視8095、8898のメトリクス確認手順がある
移行旧Driver、Helm、YAML、既存Pod参照を棚卸し済み
ロールバックアドオン、RBAC、マニフェスト変更を戻す手順がある

このチェックリストの中で最も後回しにされがちなのが、アプリケーション側の再読み込み設計です。Key VaultやAKSの設定が正しくても、アプリが起動時に一度だけ値を読み込む実装なら、ローテーション後の値は自動では使われません。証明書やDBパスワードの更新を本番で行う前に、実際にKey Vaultの値を更新し、アプリが期待どおり動くか確認してください。

まず何から対応すべきか

最初に行うべきことは、既存AKSクラスタでシークレットがどのように使われているかの棚卸しです。Kubernetes Secret、環境変数、CSIボリューム、証明書ファイル、外部シークレット管理ツールが混在している環境では、いきなり全面移行すると障害が起きやすくなります。

次の順番で進めると、影響を抑えながら導入できます。

優先度対応
高既存のSecretProviderClass、Kubernetes Secret、Key Vault、アプリ参照方法を棚卸しする
高検証用AKSクラスタまたは検証namespaceでアドオンを有効化する
高マネージドIDまたはWorkload IDを選び、Key Vault RBACを最小権限で付与する
中CSIボリュームとして読み込むアプリから先に試す
中Kubernetes Secret同期や環境変数利用アプリは再起動設計を含めて検証する
中ローテーション、監視、アラートを設定する
低オープンソース版DriverからAKS管理アドオンへの移行を段階的に進める

Azure Key Vault provider for Secrets Store CSI Driverは、AKSのシークレット管理をより安全に整理できる強力な仕組みです。ただし、導入の成否は「アドオンを有効化したか」ではなく、ID、RBAC、ネットワーク、SecretProviderClass、アプリの読み込み方式、ローテーション運用まで設計できているかで決まります。

まずは既存シークレットの利用状況を一覧化し、検証環境でKey VaultからPodへ1つのシークレットをマウントするところから始めてください。そのうえで、アプリごとにWorkload IDまたはマネージドIDを選び、ローテーション時の挙動まで確認してから本番展開するのが安全です。

Azure
Kubernetes AKS Azure Key Vault Azure RBAC Secrets Store CSI Driver

この記事を書いた人

佐藤健司のアバター 佐藤健司

実務の現場で詰まりがちなポイントを地図にするITブログ「IT trip」を運営。Windows／Office（Teams・Excel）からSQL、サーバ運用、ガジェットまで、再現性のある手順と“なぜそうなるか”を丁寧に解説します。読んだらすぐ試せること、そして迷った人の次の一歩が見えることを大切にしています。

関連記事

コメント

コメントする

目次