Key Vault

# Key Vault 統合

## 概要

Knowledge Yard V2 では、本番環境のシークレット管理に Azure Key Vault を使用します。
ローカル開発環境では従来通り `.env` ファイルを使用できます。

---

## アーキテクチャ

┌─────────────────────────────────────────────────────────────────┐ │ Azure Functions │ │ │ │ ┌─────────────────────────────────────────────────────────┐ │ │ │ Managed Identity │ │ │ │ (システム割り当てマネージド ID) │ │ │ └─────────────────────────────────────────────────────────┘ │ │ │ │ │ ▼ │ │ ┌─────────────────────────────────────────────────────────┐ │ │ │ services/keyvault.py │ │ │ │ │ │ │ │ get_secret() → Key Vault からシークレット取得 │ │ │ │ load_all_secrets() → 全シークレットを環境変数に展開 │ │ │ └─────────────────────────────────────────────────────────┘ │ └─────────────────────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────────┐ │ Azure Key Vault │ │ (kv-kitanihon-rag) │ │ │ │ AZURE-OPENAI-ENDPOINT │ │ AZURE-OPENAI-API-KEY │ │ AZURE-SEARCH-ENDPOINT │ │ AZURE-SEARCH-API-KEY │ │ AZURE-STORAGE-CONNECTION-STRING │ │ JWT-SECRET │ │ ... │ └─────────────────────────────────────────────────────────────────┘


---

## セットアップ

### 前提条件

1. Azure CLI がインストールされていること
2. Azure サブスクリプションへのアクセス権限があること
3. 以下の Azure リソースが作成済みであること：
   - リソースグループ: `rg-kitanihon-rag`
   - Key Vault: `kv-kitanihon-rag`
   - Function App: `func-kitanihon-rag`

### 自動セットアップ

```bash
./scripts/setup_keyvault.sh

このスクリプトは以下を行います： 1. Key Vault の存在確認（なければ作成） 2. Function App のマネージド ID を有効化 3. Key Vault へのアクセスポリシーを設定 4. シークレットの作成（対話形式） 5. Function App のアプリ設定に Key Vault 参照を設定

手動セットアップ¶

1. マネージド ID の有効化¶

az functionapp identity assign \
    --name func-kitanihon-rag \
    --resource-group rg-kitanihon-rag

2. Key Vault アクセスポリシーの設定¶

# マネージド ID の Principal ID を取得
PRINCIPAL_ID=$(az functionapp identity show \
    --name func-kitanihon-rag \
    --resource-group rg-kitanihon-rag \
    --query principalId \
    --output tsv)

# Key Vault アクセスポリシーを設定
az keyvault set-policy \
    --name kv-kitanihon-rag \
    --object-id $PRINCIPAL_ID \
    --secret-permissions get list

3. シークレットの作成¶

az keyvault secret set \
    --vault-name kv-kitanihon-rag \
    --name AZURE-OPENAI-API-KEY \
    --value "your-api-key-here"

4. Function App のアプリ設定¶

# KEY_VAULT_URL を設定
az functionapp config appsettings set \
    --name func-kitanihon-rag \
    --resource-group rg-kitanihon-rag \
    --settings "KEY_VAULT_URL=https://kv-kitanihon-rag.vault.azure.net/"

# Key Vault 参照を使用した設定
az functionapp config appsettings set \
    --name func-kitanihon-rag \
    --resource-group rg-kitanihon-rag \
    --settings "AZURE_OPENAI_API_KEY=@Microsoft.KeyVault(SecretUri=https://kv-kitanihon-rag.vault.azure.net/secrets/AZURE-OPENAI-API-KEY/)"

シークレット一覧¶

Key Vault シークレット名	環境変数名	説明
`AZURE-OPENAI-ENDPOINT`	`AZURE_OPENAI_ENDPOINT`	Azure OpenAI エンドポイント
`AZURE-OPENAI-API-KEY`	`AZURE_OPENAI_API_KEY`	Azure OpenAI API キー
`AZURE-OPENAI-GPT4O-DEPLOYMENT-NAME`	`AZURE_OPENAI_GPT4O_DEPLOYMENT_NAME`	GPT-4o デプロイメント名
`AZURE-OPENAI-EMBEDDING-DEPLOYMENT-NAME`	`AZURE_OPENAI_EMBEDDING_DEPLOYMENT_NAME`	Embedding モデル名
`AZURE-OPENAI-API-VERSION`	`AZURE_OPENAI_API_VERSION`	API バージョン
`AZURE-SEARCH-ENDPOINT`	`AZURE_SEARCH_ENDPOINT`	AI Search エンドポイント
`AZURE-SEARCH-API-KEY`	`AZURE_SEARCH_API_KEY`	AI Search API キー
`AZURE-SEARCH-INDEX-NAME`	`AZURE_SEARCH_INDEX_NAME`	インデックス名
`AZURE-STORAGE-CONNECTION-STRING`	`AZURE_STORAGE_CONNECTION_STRING`	Storage 接続文字列
`JWT-SECRET`	`JWT_SECRET`	JWT 署名シークレット

ローカル開発¶

ローカル開発では Key Vault は使用せず、.env ファイルから環境変数を読み込みます。

# .env ファイルの例
AZURE_OPENAI_ENDPOINT=https://your-openai.openai.azure.com/
AZURE_OPENAI_API_KEY=your-api-key
# ...

services/keyvault.py は以下の動作をします： - 本番環境: WEBSITE_SITE_NAME 環境変数の存在で判定、Key Vault からシークレット取得 - ローカル: 環境変数（.env から読み込み済み）を直接使用

セキュリティベストプラクティス¶

最小権限の原則: Function App には get と list 権限のみ付与
シークレットのローテーション: 定期的に API キーを更新
監査ログ: Key Vault の診断設定でアクセスログを有効化
ソフト削除: 本番環境では soft-delete を有効化
ネットワーク制限: 必要に応じてプライベートエンドポイントを使用

監査ログの有効化¶

az monitor diagnostic-settings create \
    --name kv-diagnostics \
    --resource /subscriptions/{subscription-id}/resourceGroups/rg-kitanihon-rag/providers/Microsoft.KeyVault/vaults/kv-kitanihon-rag \
    --logs '[{"category": "AuditEvent", "enabled": true}]' \
    --workspace /subscriptions/{subscription-id}/resourceGroups/rg-kitanihon-rag/providers/Microsoft.OperationalInsights/workspaces/{workspace-name}

トラブルシューティング¶

シークレットが取得できない¶

マネージド ID が有効か確認 bash az functionapp identity show --name func-kitanihon-rag --resource-group rg-kitanihon-rag
Key Vault アクセスポリシーを確認 bash az keyvault show --name kv-kitanihon-rag --query properties.accessPolicies
シークレットが存在するか確認 bash az keyvault secret list --vault-name kv-kitanihon-rag --query "[].name"

ローカルでの Key Vault テスト¶

ローカルから Key Vault に接続してテストする場合：

# Azure CLI でログイン
az login

# 環境変数を設定
export KEY_VAULT_URL=https://kv-kitanihon-rag.vault.azure.net/
export AZURE_FUNCTIONS_ENVIRONMENT=Production

# テスト実行
python -c "from services.keyvault import get_secret; print(get_secret('AZURE-OPENAI-ENDPOINT'))"