Vault Agent の概要: 認証とシークレット取得の自動化

Vault Agent はクライアント側デーモンとして、アプリの代わりに認証・トークン更新・シークレット取得・テンプレート出力を自動化します。

Kubernetes サイドカーや VM 常駐プロセスとして動作し、ファイル出力またはローカル HTTP リスナー経由でアプリに安全にシークレットを渡せます。

Vault Agent とは

Vault Agent は Vault サーバとは別の軽量デーモンで、クライアント側に常駐して認証処理（Auto-Auth）、トークンの自動更新、シークレットの取得、テンプレート生成（ファイル出力）を担います。アプリケーションは Vault の認証や API 詳細を直接扱わず、Agent が用意するローカルの成果物（ファイルまたはローカル HTTP）を読むだけで済みます。

Agent は二つの典型的な使い方があります。1) テンプレート機能でシークレットをファイルとして出力し、アプリはファイルを読む。2) ローカル HTTP リスナーを有効化し、Agent をキャッシュ付きプロキシとして経由して Vault にアクセスする。いずれもトークン管理は Agent が担い、TTL に従って更新または再取得します。

• アプリに Vault SDK/CLI を組み込みたくない場合に有効
• 既存ソフトがファイルでのみシークレットを受け取れる場合に有効
• 高頻度アクセスで Vault に直接負荷をかけたくない場合はキャッシュを活用
• クライアントが自前で安全にトークン更新できるなら、Agent は必須ではない

アーキテクチャとデプロイパターン

もっとも一般的なのは Kubernetes のサイドカーパターンです。アプリコンテナと同じ Pod に Agent を同居させ、ServiceAccount を用いた Kubernetes 認証でトークンを取得・更新します。テンプレートでファイルを出力し、emptyDir などで共有するか、ローカルリスナーを localhost で公開します。

VM/ベアメタルでは systemd 常駐として起動し、AppRole などの認証方式でトークンを取得します。複数プロセスで共有する場合は、ファイル出力（パーミッション厳格化）または 127.0.0.1 上のリスナー経由で配布します。

• サイドカー: Pod 内通信のみ（127.0.0.1/ファイル共有）で閉じ、ネットワーク露出を抑制
• ノード常駐: ノード内アプリ複数から利用する場合は権限分離とファイル権限に注意
• いずれの場合も、Agent から Vault までは mTLS と最小権限ポリシーを徹底

サイドカー構成の全体像

Auto-Auth の仕組みとトークン管理

Auto-Auth は、指定した認証メソッド（例: Kubernetes、AppRole、AWS IAM など）で Vault に自動ログインし、クライアントトークンを取得・更新する機能です。Agent はトークンの有効期限を監視し、期限前に自動更新を試みます。更新できない場合は再認証します。

トークンは用途に応じて 1) ファイルに書き出す（sink）か、2) ローカル HTTP リスナーで内部的に保持してプロキシ要求に付与する、のいずれかで活用できます。キャッシュ型プロキシを使う場合、クライアントはトークンを意識せずに Agent のローカルリスナーへリクエストを送り、Agent が Auto-Auth トークンを用いて上流の Vault へ転送します。

• 認証方式は実行環境の信頼根拠に合わせて選定（Kubernetes SA、ロール/シークレット ID、クラウド署名など）
• トークン TTL/Max TTL を越えないようにポリシーとロール設定を調整
• 429 や一時的な接続失敗に対してはバックオフと再試行を有効化

テンプレートとファイル出力でのシークレット配布

テンプレート機能は、Vault のシークレットを定期的に取得し、所定の形式でファイルに出力します。テンプレート言語は Consul Template に準拠しており、KV v2 の場合は Data.data 以下にキーが格納されます。ファイルは権限を絞り、アプリが読み込み専用で参照するのが基本です。

アプリがリロード対応しているなら、ファイル更新後にコマンドを実行して HUP 送信などを行えます。これによりシークレットのローテーションを無停止で適用できます。

• 出力先のパーミッションを 0400/0440 程度に固定
• テンプレート更新時のコマンドで安全にホットリロード
• エラー時の再試行・バックオフを有効化して一時障害に耐性を持たせる

Vault Agent 設定例（Kubernetes 認証 + テンプレート + キャッシュ）

# agent.hcl
vault {
  address = "https://vault.example.local:8200"
}

# ローカル HTTP リスナー（Pod/ホスト内に限定）
listener "tcp" {
  address     = "127.0.0.1:8200"  # 外部公開しない
  tls_disable = true               # Pod/ホスト内ローカル限定時のみ
}

# Vault への認証を自動化
auto_auth {
  method "kubernetes" {
    mount_path = "auth/kubernetes"
    config = {
      role       = "app-role"
      # Pod の SA トークンを既定パスから読む（環境により調整）
      token_path = "/var/run/secrets/kubernetes.io/serviceaccount/token"
    }
  }

  # トークンの書き出しが必要な場合は sink を追加（例: ファイル）
  sink "file" {
    config = {
      path = "/run/secrets/.vault-token"
      mode = "0400"
    }
  }
}

# キャッシュを有効化し、Auto-Auth トークンで上流にアクセス
cache {
  use_auto_auth_token = true
}

# テンプレートで KV v2 のシークレットをファイルへ出力
# Data.data 以下のキーを参照
# アプリに HUP を送ってホットリロード
template {
  destination = "/run/secrets/app-config.env"
  perms       = 0400
  command     = "/usr/bin/pkill -HUP myapp || true"
  contents    = <<EOH
# generated by vault-agent; do not edit
{{ with secret "kv/data/app/config" -}}
API_KEY={{ .Data.data.api_key }}
DB_USER={{ .Data.data.db_user }}
DB_PASS={{ .Data.data.db_pass }}
{{- end }}
EOH
}

キャッシュ型プロキシとパフォーマンス/可用性

キャッシュ型プロキシを有効化すると、Agent はシークレット応答をローカルに保持し、TTL に従って期限切れ前に更新します。これにより Vault サーバへのクエリ回数が減り、スパイク時の安定性が向上します。アプリは Vault のエンドポイントではなく 127.0.0.1 のリスナーへ向けるだけで、トークン付与とキャッシュを自動で享受できます。

可用性の観点では、上流 Vault の一時障害中でも有効 TTL の範囲内でキャッシュがヒットすれば応答可能です。TTL を過ぎたリースは返せないため、重要経路では適切な TTL 設計、リトライ、フォールバック（例えば直近の設定を読み込んだまま継続可能か）を検討します。

• ローカルリスナーは 127.0.0.1/最小権限で露出を限定
• Vault 側は mTLS、必要最小限のポリシーでエンドポイントを許可
• バックオフ/再試行、レート制御で上流保護、ログ/メトリクスでヒット率と更新失敗を監視

Ops ベストプラクティスと試験対策の要点

最小権限の原則を徹底します。テンプレートが参照するパスだけを許可したポリシー、短めの TTL と自動更新、トークンのローテーション/失効戦略を準備します。出力ファイルは所有者限定のパーミッションにし、共有ボリュームを使う場合は他プロセスからの読み取りを防ぎます。

試験対策としては、Agent はサーバ機能ではなくクライアント側の補助であること、Auto-Auth が認証とトークン更新を担うこと、テンプレートがファイル出力を行い、キャッシュ型プロキシが QPS 削減と可用性に寄与する点を押さえてください。Kubernetes ならサイドカー + SA 認証、VM なら AppRole という対応関係を問う設問が出やすいです。

• ルートトークンや広範なポリシーを Agent に渡さない
• init パターンが必要なら exit_after_auth を活用して初回生成のみで終了
• 監査ログ/メトリクスで更新失敗・キャッシュヒット率を可視化し SLO を定義

問題で確認

よくある質問