Kubernetes 認証 実践ガイド: Service Account連携とSidecarで安全にVaultを使う

KubernetesのPodからVaultへ安全に認証する王道は、Service Accountトークンを用いたKubernetes Auth Methodです。本稿では、RBACとロール設計の勘所、Sidecar（Vault Agent Injector）による秘密情報配布の実装ポイントを、試験観点と運用観点の両方から解説します。

Associate試験では、auth/kubernetesの構成要素、Service AccountとVaultロールの対応付け、Agent Injectorの注釈と動作、トークン更新やTTLの考え方が頻出です。設定例と比較表、ASCII図でイメージを固定しましょう。

全体像: Kubernetes Auth + Service Account + Sidecarの流れ

Kubernetes Auth Methodは、Podに自動マウントされるService Account（SA）JWTを用い、Vault側でその正当性をKubernetes API経由で検証し、Vaultトークンを払い出す仕組みです。Sidecarパターンでは、Vault AgentがPod内で自動認証・シークレット取得・テンプレート展開を行い、アプリはファイル経由で秘密情報を参照します。

実務では、アプリをVaultに直接接続させるよりも、Sidecar（またはInit）経由のファイル配布が管理しやすく、ローテーションや再読み込みの制御も行いやすい傾向があります。以下の図で、認証からシークレット注入までの流れを確認します。

• 入力: PodのService Account JWT（短期のProjected Token推奨）
• 検証: VaultがKubernetes APIに問い合わせてトークンを検証
• 出力: Vaultトークン（ポリシーに基づき限定権限）とシークレットをSidecarが取得・更新

Kubernetes Auth + Sidecarの典型フロー

最小構成の概念（抜粋）

# Pod内のService Accountトークンを使い、VaultのKubernetes Authでlogin。
# SidecarのVault Agentがテンプレートでシークレットをファイル出力し、
# アプリはread-onlyでマウントされたボリュームから読み取る。

ステップバイステップ: VaultのKubernetes Authを設定する

Vaultサーバー側では、Kubernetes Auth Methodを有効化し、Kubernetes APIへのTokenReviewが可能なService Accountを用意して、auth/kubernetes/configに必要情報を登録します。これにより、VaultはPodのJWTを正規のKubernetes発行トークンとして検証できます。

RBACは最小権限で十分です。TokenReviewと、該当するNamespaceのService Accountトークン検証に必要な権限のみを付与します。

• 前提: VaultはKubernetes APIに到達可能（ネットワーク/証明書）
• 推奨: Projected Service Account Token（短命・audience指定）
• セキュリティ: kubernetes_ca_certの取り扱いとTLS検証を明示

設定コンポーネントの関係

Kubernetes Authの有効化とRBAC（例）

# 1) Vault側: Kubernetes Authを有効化
vault auth enable kubernetes

# 2) Reviewer用のService Account/RBAC（kube側）
---
apiVersion: v1
kind: ServiceAccount
metadata:
  name: vault-token-reviewer
  namespace: vault
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: system:token-reviewer
rules:
- apiGroups: ["authentication.k8s.io"]
  resources: ["tokenreviews"]
  verbs: ["create"]
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  name: vault-token-reviewer-binding
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: ClusterRole
  name: system:token-reviewer
subjects:
- kind: ServiceAccount
  name: vault-token-reviewer
  namespace: vault

# 3) VaultにK8sクラスタ情報を登録
# 環境に合わせて$K8S_HOST, $REVIEWER_JWT, $CA_CERTを用意
vault write auth/kubernetes/config \
  kubernetes_host="$K8S_HOST" \
  token_reviewer_jwt="$REVIEWER_JWT" \
  kubernetes_ca_cert=@/var/run/secrets/kubernetes.io/serviceaccount/ca.crt

Service AccountとVaultロールの設計

VaultのKubernetesロールは、特定のService Account名とNamespaceの組み合わせに対してVaultポリシーを関連付け、許可されたPodからのloginにトークンを発行します。bound_service_account_names、bound_service_account_namespaces、必要に応じてbound_audiencesでJWTのaudienceを絞り込みます。

TTLやトークンタイプ（service, batch）もロールで制御可能です。アプリの更新間隔や再起動コストを踏まえ、短すぎないTTLと自動更新可否を決めます。

• SAとNamespaceの両方でバインドして誤適用を防止
• audienceをVault向けに限定しリプレイリスクを低減
• 必要十分なポリシーに限定（list権限の付与範囲に注意）

ロールとポリシーのひも付けイメージ

ロール作成とポリシー例

# ポリシー: kv v2の特定パスのみ許可
tee kv-app.hcl <<'EOF'
path "kv/data/app/*" {
  capabilities = ["read"]
}
EOF
vault policy write kv-app kv-app.hcl

# ロール: app Namespaceのweb SAにバインド
aud="vault"
vault write auth/kubernetes/role/app-web \
  bound_service_account_names=web \
  bound_service_account_namespaces=app \
  bound_audiences="$aud" \
  policies=kv-app \
  ttl=1h \
  token_type=default

Sidecarで配布: Vault Agent Injectorの実装

Vault Agent Injectorは、Podに注釈を付与するだけでSidecarと共有ボリュームを自動注入し、Kubernetes Authで認証・テンプレートを評価してファイルを生成します。アプリは環境変数ファイルや設定ファイルとして読み取るだけで済みます。

ローテーションが必要な証明書や短命トークンは、Agentの自動更新とSIGHUPリロード等を組み合わせると安定します。

• Deployment/StatefulSetのPodテンプレートに注釈を追加
• vault.hashicorp.com/role でVaultロール名を指定
• テンプレートでJSON/YAML/ENV形式など柔軟に出力

InjectorのPod内レイアウト

Deployment注釈の最小例（kv v2からconfig.json生成）

apiVersion: apps/v1
kind: Deployment
metadata:
  name: web
  namespace: app
spec:
  replicas: 1
  selector:
    matchLabels: { app: web }
  template:
    metadata:
      labels: { app: web }
      annotations:
        vault.hashicorp.com/agent-inject: "true"
        vault.hashicorp.com/role: "app-web"
        # 出力ファイル名は注釈の末尾と一致
        vault.hashicorp.com/agent-inject-secret-config: "kv/data/app/config"
        vault.hashicorp.com/agent-inject-template-config: |
          {{- with secret "kv/data/app/config" -}}{{ .Data.data | toJSON }}{{- end -}}
    spec:
      serviceAccountName: web
      containers:
      - name: app
        image: ghcr.io/example/web:1.0
        volumeMounts:
        - name: vault-secrets
          mountPath: /vault/secrets
          readOnly: true
      volumes:
      - name: vault-secrets
        emptyDir:
          medium: Memory

セキュリティと運用: トークン更新、TTL、障害時のふるまい

Kubernetes Authで払い出されたVaultトークンは、ロールのttlおよびmax_ttlの範囲で自動更新可能です。SidecarのAgentは期限前に更新し、失敗時には再試行します。更新不可が続く場合、テンプレートの再評価が止まり、アプリは最後に出力されたファイルを参照し続けます。

安定運用には、監視（トークン残存TTL、テンプレート更新時刻）、Pod再起動戦略、SIGHUP等での設定再読み込みを組み合わせ、万一の認証断でも影響範囲を限定します。

• Projected SA Tokenの有効期限は短めに保つ（数分〜数十分）
• Vaultトークンのttlはアプリのリロード特性とバランスを取る
• ネットワーク断やAPI断続時のリトライ・バックオフを前提にする

更新ループの簡略図

テンプレート例（環境変数ファイル）と再読込

# テンプレート例: .env 形式
{{- with secret "kv/data/app/db" -}}
DB_USER={{ .Data.data.username }}
DB_PASS={{ .Data.data.password }}
{{- end -}}

# アプリ側: ファイル変更検知でSIGHUP
# inotifywait等で /vault/secrets/.env の更新を監視し、プロセスにSIGHUP送出

試験対策と落とし穴: 押さえる要点チェック

Associate試験では、用語と流れが問われます。Reviewerトークンの役割、ロールのバインド条件、Injector注釈の意味、kv v2のパス指定など基本を確実に。

また、audienceやNamespace/SA名の不一致によるログイン失敗、kv v2での/dataと/metadataの混同は頻出の落とし穴です。

• Reviewer用SAのトークンはVaultがK8s APIへTokenReviewするためのもの（アプリ用ではない）
• auth/kubernetes/roleのbound_service_account_namesとnamespacesはANDで評価
• kv v2では読み取りはsecret/data/...、メタはsecret/metadata/...

用語対応のミニ図

CLIでの手動login確認（トラブルシュート）

# Pod内での手動テスト例（デバッグ用途）
SA_JWT=$(cat /var/run/secrets/kubernetes.io/serviceaccount/token)
vault write auth/kubernetes/login role=app-web jwt="$SA_JWT"
# auth成功後に VAULT_TOKEN を使って読み取り
echo $VAULT_TOKEN | vault kv get -format=json kv/app/config

問題で確認

よくある質問