Skip to content

docs: Control Plane アーキテクチャ設計（Terraform + Keycloak） #32

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
susumutomita merged 1 commit into from
Nov 11, 2025
Merged

docs: Control Plane アーキテクチャ設計（Terraform + Keycloak） #32

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
155 changes: 155 additions & 0 deletions Plan.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -107,6 +107,161 @@ PR を作成した後、CI の状態確認を忘れて push がタイムアウ

---

### Control Plane 基盤構築 (Terraform + Keycloak) - 2025-11-10

**目的 (Objective)**:
- TenkaCloud のコントロールプレーン（管理基盤）を **マルチクラウド対応** で構築する
- reference/eks の SaaS Factory EKS Reference Architecture のコンセプトを参考にしつつ、**ベンダーロックインを回避**
- マルチテナント SaaS の基盤となる認証・認可、テナント管理、イベント管理機能を実装する

**背景 (Background)**:
- TenkaCloud はマルチクラウド対応が必須要件（AWS/GCP/Azure/OCI/LocalStack）
- reference/eks は AWS 固有の実装だが、アーキテクチャパターンは参考にする
- コントロールプレーンの責務：
- テナント管理（登録、プロビジョニング、削除）
- 認証・認可（Keycloak ベース）
- イベント管理（クラウドネイティブイベントバス）
- システム管理者機能

**技術スタック（クラウドアグノスティック）**:
- **IaC**: Terraform（マルチクラウド対応）
- **認証**: Keycloak（OSS、OIDC/SAML 対応）
- **コンテナオーケストレーション**: Kubernetes (EKS/GKE/AKS)
- **イベントバス**: NATS / Apache Kafka（クラウドネイティブ）
- **データベース**: PostgreSQL（Keycloak 用）+ DynamoDB/Firestore/CosmosDB（テナントデータ）
- **サービスメッシュ**: Istio / Linkerd（テナント分離）

**制約 (Guardrails)**:
- CLAUDE.md の開発プレイブックに従う
- テスト駆動開発（TDD）- カバレッジ 100%
- TypeScript strict mode
- セキュリティベストプラクティスの遵守（OWASP Top 10）

**タスク (TODOs)**:
- [x] reference/eks の Control Plane アーキテクチャ調査
- [x] マルチクラウド対応の技術スタック選定（Terraform + Keycloak）
- [ ] プロジェクト構造の作成（infrastructure/terraform/control-plane/）
- [ ] Terraform モジュール構成の設計
- [ ] Keycloak デプロイメント（Kubernetes）
- [ ] Keycloak Helm Chart の設定
- [ ] PostgreSQL データベースのプロビジョニング
- [ ] Realm/Client/Role の初期設定
- [ ] OIDC プロバイダー設定
- [ ] Kubernetes リソースの定義
- [ ] Namespace 作成（control-plane）
- [ ] ServiceAccount と RBAC 設定
- [ ] Ingress 設定（Keycloak 管理コンソール）
- [ ] イベントバス（NATS/Kafka）のデプロイ
- [ ] テナント管理サービスの実装（TypeScript/Go）
- [ ] テナント CRUD API
- [ ] Keycloak Realm 自動作成
- [ ] イベントパブリッシュ
- [ ] Terraform モジュールのテスト（Terratest）
- [ ] ドキュメント作成

**ディレクトリ構造**:
```
infrastructure/
└── terraform/
├── modules/
│ ├── keycloak/ # Keycloak モジュール
│ │ ├── main.tf
│ │ ├── variables.tf
│ │ ├── outputs.tf
│ │ └── helm-values.yaml # Keycloak Helm values
│ ├── event-bus/ # NATS/Kafka モジュール
│ │ ├── main.tf
│ │ └── variables.tf
│ ├── database/ # PostgreSQL モジュール
│ │ ├── main.tf
│ │ └── variables.tf
│ └── kubernetes-base/ # Kubernetes 基盤
│ ├── main.tf
│ └── namespaces.tf
├── environments/
│ ├── dev/
│ │ ├── main.tf
│ │ ├── variables.tf
│ │ └── terraform.tfvars
│ ├── staging/
│ └── prod/
└── control-plane/ # Control Plane メインディレクトリ
├── main.tf
├── variables.tf
├── outputs.tf
├── providers.tf # マルチクラウドプロバイダー
└── backend.tf

backend/
└── services/
└── control-plane/
└── tenant-management/ # テナント管理サービス
├── src/
│ ├── api/ # REST API
│ ├── keycloak/ # Keycloak クライアント
│ ├── events/ # イベントパブリッシュ
│ └── database/ # DB アクセス
├── test/
├── Dockerfile
└── package.json
```
Comment on lines +163 to +207

@coderabbitai coderabbitai Bot Nov 11, 2025

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor

Add language identifier to code block to resolve markdown linting issue.

The fenced code block lacks a language specifier. According to markdownlint (MD040), all code blocks should declare their language for proper rendering and syntax highlighting.

-```
+```tree
 infrastructure/

Alternatively, use text` or bash` if the intent is to emphasize portability across different environments:

-```
+```text
 infrastructure/
🧰 Tools
🪛 markdownlint-cli2 (0.18.1)

163-163: Fenced code blocks should have a language specified

(MD040, fenced-code-language)

🤖 Prompt for AI Agents 
In Plan.md around lines 163 to 207, the fenced code block showing the project
tree lacks a language identifier which triggers markdownlint MD040; fix it by
adding a language tag after the opening triple backticks (for example "tree",
"text", or "bash") so the block becomes ```tree (or ```text/```bash) and leave
the contents unchanged to satisfy the linter and enable proper syntax
highlighting.


**検証手順 (Validation)**:
1. Terraform の構文チェックが成功すること
```bash
cd infrastructure/terraform/control-plane
terraform fmt -check
terraform validate
```

2. Terraform モジュールのテスト（Terratest）が通過すること
```bash
cd infrastructure/terraform/modules/keycloak
go test -v
```

3. Keycloak が正常にデプロイされること（kind/LocalStack）
```bash
# kind クラスターで検証
terraform plan
terraform apply
kubectl get pods -n control-plane
```

4. テナント管理サービスのテストが通過すること（カバレッジ 100%）
```bash
cd backend/services/control-plane/tenant-management
bun run test
bun run test:coverage
```

5. Keycloak との統合テストが成功すること
```bash
# Keycloak 起動後、OIDC トークン取得テスト
bun run test:integration
```

**未解決の質問 (Open Questions)**:
- [ ] ローカル開発環境: kind vs minikube vs k3s
- [ ] イベントバス: NATS vs Apache Kafka（どちらを選択するか）
- [ ] テナント tier の定義（Free, Pro, Enterprise など）
- [ ] Keycloak の Realm 設計（マスター Realm + テナント別 Realm？）
- [ ] データベース選択: PostgreSQL のマネージドサービス vs セルフホスト
- [ ] マルチクラウドのデータストア抽象化レイヤー設計
- [ ] ドメイン名の決定（*.tenkacloud.io など）

**進捗ログ (Progress Log)**:
- [2025-11-10 23:30] reference/eks/lib/control-plane-stack.ts を確認
- [2025-11-10 23:35] reference/eks/GUIDE.md を確認
- [2025-11-10 23:40] Plan.md に AWS CDK ベースの実行計画を追加
- [2025-11-10 23:50] ユーザーフィードバックでマルチクラウド対応に方針変更
- [2025-11-10 23:55] Terraform + Keycloak ベースのアーキテクチャに設計変更完了

**振り返り (Retrospective)**:
*（実装後に記入）*

---

## 次の実行計画テンプレート

以下のテンプレートを使用して、新しい機能開発の実行計画を作成してください：
Expand Down
Loading