infra(keycloak)+docs: Phase 1 Sprint 1 — Keycloak Realm initial import 手順(S1Infra-8)

[win2cot]

Phase 1 Sprint 1 Infra-8: Keycloak Realm initial import 手順

概要

keycloak/realm-export/(Setup 1 #214 で構築済)を dev 環境の Keycloak Custom Image 起動時に 初回 import する手順を確立する。冪等性 + 上書き挙動 + Local Docker Compose との手順統一を含む。

詳細仕様: docs/architecture/infrastructure-plan.md v5 §5.3 / Setup 1 #214(Realm 設計 + JSON export)。

背景

• Setup 1 infra(compose): Keycloak Realm 設計 + JSON export 配置(keycloak/realm-export/) #214 で Realm JSON export 配置済(local 用)
• dev 環境では初回 ECS Service 起動時に同 JSON を import する必要あり
• Keycloak の import 手段は kc.sh import or 環境変数 KC_IMPORT or REST API
• 二度目以降の起動で重複 / 上書き / skip の挙動を確定する

やること

• import 手段の選定(kc.sh import 推奨、もしくは init container / one-shot ECS Task)
• 冪等性ポリシー確定: OVERRIDE / IGNORE_EXISTING / OFFLINE_IMPORT 等の挙動を文書化
• dev 環境用 Realm 設定の差分管理(local と dev で異なる issuer URI / redirect URI 等を env vars / parameter store で吸収)
• 実行手順を docs/dev/ or infra/docs/ に記載
• dev で初回起動 → Realm 反映を確認
• 後続変更時の re-import 手順も同 docs に記録

受入条件

• import 手順が docs に明示
• dev 環境の Keycloak で Realm 設定が反映済
• 二度目以降の起動で想定通りの挙動(skip / override 等)

関連

• 親 tracker Issue: [Phase 1 Infra] Setup 0-2 + Sprint 0-5 Infra ストリーム横断 tracker #206
• Milestone: Phase 1
• Iteration: Phase 1 Sprint 1
• 依存: S1Infra-5 (Keycloak ECS Service)、Setup 1 infra(compose): Keycloak Realm 設計 + JSON export 配置(keycloak/realm-export/) #214 (Realm export 配置済)
• 隣接: Sprint 3 Infra S3Infra-1(dev E2E 動作確認)

備考

• task-type: task-type:impl
• 優先度: priority/p1(Keycloak Service 起動だけなら S1Infra-5 でも可、本 Issue は import 手順の安定化)
• area: area/keycloak + area/infra + area/docs
• claude-automation 推奨: 適用

[claude-automation-impl]

着手宣言・実装方針

選定したアプローチ: --import-realm フラグ + Docker Image への Realm JSON ベイク

根拠:

• ローカル環境 (start-dev --import-realm + volume mount) との一貫性
• ECS Fargate はファイルシステムマウントが使えないため、Image への組み込みが最もシンプル
• Keycloak 26 の --import-realm はデフォルトで IGNORE_EXISTING 戦略 → 冪等性を自動保証

変更ファイル

ファイル	種別	内容
keycloak/Dockerfile	変更	Stage 3 で realm JSON を /opt/keycloak/data/import/ にコピー・CMD に --import-realm を追加
infra/shared/modules/keycloak/main.tf	変更	ECS タスク定義に command フィールドを明示追加(start --optimized --import-realm)
docs/dev/keycloak-realm-import.md	新規	import 手順・冪等性ポリシー・local/dev 差分・re-import 手順

冪等性ポリシー

起動回数	挙動	理由
初回	Realm を DB に作成	DB に realm が存在しない
2 回目以降	スキップ (IGNORE_EXISTING)	DB に realm が既存
設定変更を反映したい場合	Admin Console で realm 削除 → ECS service 再デプロイ、または kc.sh import --override true (one-shot ECS task)	手動 re-import 手順として docs に記載

[claude-automation-impl]

対応完了レポート

PR: #463

変更サマリ

ファイル	種別	内容
keycloak/Dockerfile	変更	Stage 3 で realm-export/ を /opt/keycloak/data/import/ にコピー・CMD に --import-realm を追加
infra/shared/modules/keycloak/main.tf	変更	ECS タスク定義に command を明示追加 (start --optimized --import-realm)
docs/dev/keycloak-realm-import.md	新規	import 手順・冪等性ポリシー (IGNORE_EXISTING)・local/dev 差分・re-import 手順 (方法 A: Realm 削除 / 方法 B: kc.sh import --override true)

受入条件の対応状況

• import 手順が docs に明示 → docs/dev/keycloak-realm-import.md に記載
• 二度目以降の起動で想定通りの挙動 (IGNORE_EXISTING) → Dockerfile CMD + ECS command フィールドで実装済み
• dev 環境の Keycloak で Realm 設定が反映済 → ECR image push (infra(terraform): Phase 1 Sprint 1 — ECR(tasks-webapi + keycloak-custom)(S1Infra-7) #324) + ECS デプロイ後に確認 (本 PR スコープ外)

_{signal: claude-impl-done}