Vault Namespacesで実現するマルチテナント設計

NamespacesはVault Enterpriseの機能で、単一クラスタ内に強固な論理的隔離をつくり、チーム・環境・顧客単位のマルチテナントを安全に運用できます。各名前空間は認証方式、シークレットエンジン、ポリシー、エンティティ/グループ、トークンを独立管理します。

実務では“どの分離手段を選ぶか”と“運用の一貫性”が鍵です。試験ではX-Vault-Namespaceヘッダ、トークン/ポリシーのスコープ、レプリケーションやスナップショットの挙動が頻出です。本稿では安定した公式仕様に基づき、設計判断の軸と運用手順を具体化します。

Vault Namespacesの基礎と選定比較

NamespacesはVault Enterpriseにおける論理的テナント境界です。各名前空間は独立したポリシー評価・トークン発行・認証方式・シークレットエンジンを持ち、同一パス名でも名前空間が異なれば衝突しません。APIではX-Vault-Namespaceヘッダ、CLIでは-namespaceフラグまたはVAULT_NAMESPACE環境変数で対象を切り替えます。

運用・試験の落とし穴は“意図した名前空間に対して操作しているか”です。ヘッダや環境変数の指定漏れは、誤った名前空間へのマウントやポリシー適用を招きます。root権限のトークンも、発行された名前空間にスコープされる点を忘れないでください。

• Enterprise機能。OSS版にはNamespacesはありません。
• X-Vault-Namespace未指定時は“現在の名前空間”が対象。CLIはVAULT_NAMESPACEで明示するのが安全。
• トークンは発行された名前空間にスコープ。別名前空間には権限が及ばない。

単一クラスタ内のNamespaceによる隔離

APIとCLIでの名前空間指定（作成・一覧）

# 1) root 名前空間で team-a を作成（API）
curl -sS \
  -H "X-Vault-Token: $VAULT_TOKEN" \
  -H "X-Vault-Namespace: root" \
  -X POST $VAULT_ADDR/v1/sys/namespaces/team-a

# 2) 一覧（LISTメソッド）。ヘッダの指定が必須
curl -sS -X LIST \
  -H "X-Vault-Token: $VAULT_TOKEN" \
  -H "X-Vault-Namespace: root" \
  $VAULT_ADDR/v1/sys/namespaces | jq .

# 3) CLIはVAULT_NAMESPACEで明示
export VAULT_NAMESPACE=team-a
auth_method=$(vault auth list -detailed -format=json | jq 'keys')

階層設計と命名規約

設計の基本は“誰が何を独立運用したいか”を起点にします。よくあるパターンは、組織・顧客単位で第1階層、環境（dev/stg/prod）を第2階層に置く方式です。過度な深さは運用と可視性を損なうため、2〜3階層を目安にします。

命名は一貫したスキーム（英小文字・ハイフン・環境接尾辞）を採用し、短く衝突しない形にします。短命な検証用はsandboxなどに集約し、定期的に棚卸しします。

• 推奨: org/tenant → env（例: team-a/prod）
• 命名規約をレポジトリ化し、CIで逸脱を検出
• 棚卸しジョブで空の名前空間・未使用マウントを可視化

名前空間の一覧取得と存在確認（API）

# root配下の第1階層を列挙
curl -sS -X LIST \
  -H "X-Vault-Token: $VAULT_TOKEN" \
  -H "X-Vault-Namespace: root" \
  $VAULT_ADDR/v1/sys/namespaces | jq '.data.keys'

# team-a配下の環境を列挙
curl -sS -X LIST \
  -H "X-Vault-Token: $VAULT_TOKEN" \
  -H "X-Vault-Namespace: team-a" \
  $VAULT_ADDR/v1/sys/namespaces | jq '.data.keys'

ポリシーとトークンの境界設計

ACLポリシーは“評価対象の名前空間”内のパスに対して作用します。トークンも名前空間にスコープされるため、team-aで発行したトークンはteam-bのシークレットにアクセスできません。root権限であってもスコープ外へは越境できません。

運用では名前空間管理用の管理者ロール（例: ns-admin）を各テナントに用意し、ポリシー登録・マウント・エンティティ管理を委任します。発行や失効の自動化はテナントごとに行い、監査容易性を高めます。

• デフォルトポリシーは名前空間ごとに存在。誤ってroot配下に書かないこと。
• トークン失効は“発行元の名前空間”で行うのが確実。
• OIDC等の認証マッピングも名前空間ごとに独立。

team-a にポリシーを作成しトークンを発行

# 対象の名前空間を明示
export VAULT_NAMESPACE=team-a

# 最小権限ポリシーを登録
echo '
path "kv/data/app/*" { capabilities = ["read"] }
' > read-app.hcl
vault policy write app-read read-app.hcl

# ポリシーを付与したトークン発行
vault token create -policy=app-read -period=24h -orphan

認証方式とシークレットエンジンの分離

各名前空間で認証方式（例: userpass、OIDC、Kubernetes、GitHub）を個別に有効化できます。同様に、kv、pki、databaseなどのシークレットエンジンもテナント単位でマウントします。パス名の重複は名前空間で吸収されるため、各テナントは同じパス規約を採用しても干渉しません。

TTLやローテーション、ロール定義は名前空間ローカルに完結します。標準運用タスク（ロール作成、エンジン有効化、チューニング）は、常に対象の名前空間を明示して実施します。

• 同名パスでも名前空間が異なれば衝突しない。
• マウント・認証の有効化/無効化はテナントごとに委任できる。
• 設定ドリフト対策として“ベース設定のHCLテンプレート”を用意。

名前空間ごとの認証/シークレットエンジンの有効化

# team-a で GitHub 認証を有効化
export VAULT_NAMESPACE=team-a
vault auth enable github
vault write auth/github/config organization=my-org

# 同名パスで kv-v2 を有効化（team-a と team-b は独立）
vault secrets enable -path=kv -version=2 kv

export VAULT_NAMESPACE=team-b
vault secrets enable -path=kv -version=2 kv

運用: レプリケーションとバックアップ

EnterpriseのDR/Performanceレプリケーションは、名前空間を含む状態を複製します。フェイルオーバー後もテナント境界は維持されるため、切替計画では“どの名前空間がどのエンドポイントに乗るか”を明示しておきます。

Integrated Storage（RAFT）利用時のスナップショットはクラスタ全体を対象とし、名前空間を含めて取得/復元できます。計画停止時に取得し、復元手順は非本番で定期検証します。

• レプリケーション切替時もX-Vault-Namespaceの指定は必要。
• RAFTスナップショットはクラスタ全体。部分復元は設計段階で回避策を用意。
• 復元後は各名前空間のマウント/ポリシーの健全性チェックを自動化。

スナップショット運用（Integrated Storage）

# 取得（権限: 適切な管理トークン、通常はroot名前空間で実施）
vault operator raft snapshot save /backups/vault_$(date +%Y%m%d%H%M).snap

# 復元（事前にクラスタ停止/隔離した検証環境で）
vault operator raft snapshot restore /backups/vault_YYYYMMDDHHMM.snap

自動化とクォータ適用

TerraformのVaultプロバイダで名前空間やマウント、ポリシーをコード化すると、テナント増加に伴う設定ドリフトを抑制できます。プロバイダのnamespace引数で操作対象を固定し、テナントごとにワークスペースを分けると安全です。

Enterpriseのクォータ（レートリミット等）は名前空間単位で適用できます。SLAに応じてテナントごとに制限値を定義し、負荷偏りを防ぎます。

• provider.vault の namespace で明示スコープ。
• 計画外の越境を防ぐため、CIでX-Vault-Namespace/VAULT_NAMESPACEの未設定を失敗にする。
• クォータは段階適用し、メトリクスで監視してから引き上げる。

Terraformで名前空間作成 + レートリミット設定例

# Terraform (vault >= 3.x)
provider "vault" {
  address   = var.vault_addr
  token     = var.vault_token
  namespace = "root"
}

resource "vault_namespace" "team_a" {
  path = "team-a"
}

# team-a 内で kv をマウント（別プロバイダでスコープ）
provider "vault" {
  alias     = "team_a"
  address   = var.vault_addr
  token     = var.vault_token
  namespace = "team-a"
}

resource "vault_mount" "kv" {
  provider = vault.team_a
  path     = "kv"
  type     = "kv-v2"
}

# クォータ（API例）：team-a に毎秒100リクエスト
curl -sS -X POST \
  -H "X-Vault-Token: $VAULT_TOKEN" \
  -H "X-Vault-Namespace: root" \
  -H "Content-Type: application/json" \
  $VAULT_ADDR/v1/sys/quotas/rate-limit/team-a-rl \
  -d '{
        "rate": 100,
        "interval": "1s",
        "namespace": "team-a"
      }'

問題で確認

よくある質問