Vault Agent Templating 実践ガイド: ファイル出力とプロセス連携

Vault Agent の template 機能は、Vault 上のシークレットをポーリングや更新イベントに応じてファイルとして安全に出力し、アプリのリロード等を自動化できます。

本稿では、運用でつまずきやすいファイル原子書き込み、権限設定、リロードのトリガー設計を、試験対策と実務の両面から整理します。

基礎: Vault Agent とテンプレートの役割

Vault Agent は Vault への認証を自動化し、取得したトークンを用いてシークレットをキャッシュ・更新し続ける常駐プロセスです。template スタンザを用いると、取得したデータを Go テンプレート構文（consul-template 互換の関数群）で整形し、ファイルに出力できます。

Auto-auth（例: AppRole, Kubernetes など）で得たトークンは自動的にローテーションされ、対象シークレットの更新・期限切れに合わせてテンプレート出力も再実行されます。結果として、アプリケーションはファイルを読むだけで最新のクレデンシャルを受け取れます。

• template は destination パスに原子的に書き込み
• perms と create_dest_dirs で最低限のファイル権限・作成制御
• command でレンダリング直後に任意コマンド（例: プロセスのリロード）を実行可能
• auto_auth と cache を併用し、Vault への負荷とレイテンシを低減

ファイル出力の仕組みと原子性

Vault Agent のテンプレート出力は、一時ファイルに書いた後にリネームする原子的な手順で行われます。これにより、読み手（アプリケーション）が中途半端な内容を読むことを防げます。

また、perms（例: 0640）で最小権限を明示し、create_dest_dirs=true でディレクトリが未作成でも安全に配置できるようにします。アプリは destination のファイルを読むだけにし、書き込みは Agent のみに限定するのが基本方針です。

• 原子書き込みにより読み手の整合性を担保
• perms はアプリの実行ユーザが読み取れる最小限に設定
• テンプレートは定期ポーリングとイベントで再レンダリング
• 大きなファイルはリロード時間と I/O 量に注意

全体フロー（ファイル出力とプロセス連携）

プロセス連携パターン（リロードとローテーション）

テンプレート出力後にアプリへ変更を伝える方法は、service manager 経由の reload、SIGHUP 送信、ソケット通知などが代表的です。Vault Agent の template スタンザに command を設定すると、再レンダリング直後にそのコマンドが呼ばれます。

証明書やクレデンシャルをローテーションする場合、アプリ側がホットリロード対応かを事前に確認し、非対応なら短いダウンタイムでの再起動戦略を設計します。

• systemctl reload <service>（ユニットが Reload= を実装している場合）
• kill -HUP <pid>（多くのサーバが設定再読込を実装）
• 再起動が必要な場合は並行稼働やヘルスチェックで影響を緩和
• 更新頻度が高い動的シークレットはレート制御とバッチングを検討

実用サンプル: DB 認証ファイルの自動更新とサービスのリロード

以下は、データベース動的クレデンシャル（database/creds/readonly）をファイルに出力し、アプリサービスをリロードする例です。ポイントは、with secret ブロックで単一リクエストにまとめ、ユーザ名とパスワードの不整合を防ぐこと、そして perms の最小化と原子的な出力です。

サービス側は db.env を環境ファイルとして読み込み、reload で再読込する前提です。

• with secret ブロックで一貫したペアの取得
• perms=0640 と create_dest_dirs=true
• command でリロードの自動化
• auto_auth のトークンは sink にも出力可能（必要に応じて）

agent.hcl（抜粋: auto_auth と template）

cache {
  use_auto_auth_token = true
}

auto_auth {
  method "approle" {
    mount_path = "auth/approle"
    config = {
      role_id_file_path   = "/etc/vault/role_id"
      secret_id_file_path = "/etc/vault/secret_id"
    }
  }
  sink "file" {
    config = {
      path = "/run/vault/agent.token"
    }
  }
}

template {
  destination       = "/etc/myapp/db.env"
  perms             = 0640
  create_dest_dirs  = true
  contents = <<EOH
{{- with secret "database/creds/readonly" -}}
DB_USER={{ .Data.username }}
DB_PASS={{ .Data.password }}
DB_HOST=db.internal.example
DB_NAME=app
{{- end -}}
EOH
  command = ["/bin/systemctl", "reload", "myapp.service"]
}

運用の落とし穴とベストプラクティス

リロードの多重起動を防ぐため、テンプレート更新頻度（ポーリング間隔や TTL）とアプリのリロード時間を見積もり、必要に応じてコマンド側でデバウンスやロックを入れます。大規模環境では、更新嵐が起きないようロール毎に TTL を分散させるのが有効です。

権限面では、テンプレート出力先ディレクトリの所有権と perms を厳格にし、バックアップや一時ファイルが残置しないかを監視します。ログレベルは平時は info、トラブル時のみ debug を推奨します。

• テンプレート一つにつき一貫したシークレット参照（重複取得を避ける）
• アプリが読み込み時に部分読みをしない設計（原子性前提）
• リーク防止: コマンドで env 展開せず、ファイル参照に統一
• 監視: レンダリング失敗、コマンド失敗、シークレット期限切れを可視化

試験対策チェックポイント（Associate / Ops）

Vault Agent の template は原子的ファイル書き込みであること、command で外部プロセスを連携できること、auto_auth によりトークンの自動取得・ローテーションが行われることを押さえてください。

KV v2 ではデータパスとメタデータパスの違い、動的シークレットは TTL に基づいて更新・再レンダリングされる点も頻出です。

• template スタンザの主要オプション: destination, contents/source, perms, create_dest_dirs, command
• with secret ブロックで一回の読み出しに集約
• リロードはサービス側の仕様に合わせて設計（SIGHUP か reload か）
• 運用では最小権限とログ監視が基本

問題で確認

よくある質問