infrastructure-design
Kubernetes、Kong API Gateway、ScalarDB Cluster v3.17を使用したインフラストラクチャ設計を行います。マニフェストファイルと設定ファイルを生成します。
Codex または Claude でインストール この Prompt をコピーして Codex、Claude、または他のアシスタントに貼り付けると、Skill ページを確認してインストールできます。
メニュー
Kubernetes、Kong API Gateway、ScalarDB Cluster v3.17を使用したインフラストラクチャ設計を行います。マニフェストファイルと設定ファイルを生成します。
Codex または Claude でインストール この Prompt をコピーして Codex、Claude、または他のアシスタントに貼り付けると、Skill ページを確認してインストールできます。
SOC 職業分類に基づく
RESTful API の設計を行います。エンドポイント定義、リクエスト/レスポンス仕様、エラーハンドリング、ScalarDBトランザクション例外のマッピングを含みます。
ScalarDBを前提としたデータベース設計を行います。スキーマ設計、トランザクション設計、マルチストレージ構成を対話形式で決定し、スキーマファイルと設計書を生成します。
DDDに基づいたドメインモデルを設計します。戦略的設計(境界コンテキスト、ユビキタス言語)と戦術的設計(エンティティ、値オブジェクト、集約、ドメインサービス、ドメインイベント)を定義し、ヘキサゴナルアーキテクチャとの統合を行います。ScalarDBのトランザクション境界や管理テーブル分類の考慮事項を含みます。中間状態はresearch/に記録されます。
設計ドキュメントに基づいて実装計画を生成します。ScalarDB特有のスキーマ定義、トランザクション実装、統合テストを含む実装可能なタスク指示書を作成し、フェーズ別の実装ロードマップを提供します。
ScalarDBの制約を考慮したデータモデル設計を行います。Partition Key・Clustering Key・Secondary Index の設計、ホットスポット評価、メタデータオーバーヘッド見積もり、バックエンドDB選定を含みます。ワークフローStep 04(データモデル設計)で使用します。
ScalarDBのトランザクション設計を行います。トランザクション境界定義、パターン選定(単一集約内/2PC/Saga/ハイブリッド)、OCC競合率評価、バッチ処理設計、v3.17最適化適用計画を含みます。ワークフローStep 05(トランザクション設計)で使用します。
| name | infrastructure-design |
| description | Kubernetes、Kong API Gateway、ScalarDB Cluster v3.17を使用したインフラストラクチャ設計を行います。マニフェストファイルと設定ファイルを生成します。 |
Kubernetes、Kong、ScalarDB Cluster v3.17を使用したインフラストラクチャを設計し、以下を生成します:
flowchart TB
subgraph K8s["Kubernetes Cluster"]
subgraph Ingress["Ingress Layer"]
KONG[Kong API Gateway]
KONG_DB[(Kong DB)]
end
subgraph App["Application Layer"]
SVC1[Service Pod]
SVC2[Service Pod]
SVC3[Service Pod]
end
subgraph Data["Data Layer"]
SCALAR[ScalarDB Cluster v3.17]
ANALYTICS[ScalarDB Analytics]
end
subgraph Infra["Infrastructure"]
CM[ConfigMaps]
SEC[Secrets]
PV[PersistentVolumes]
PDB[PodDisruptionBudget]
end
end
subgraph External["External Storage"]
PG[(PostgreSQL)]
CASS[(Cassandra)]
end
KONG --> SVC1
KONG --> SVC2
KONG --> SVC3
SVC1 --> SCALAR
SVC2 --> SCALAR
SVC3 --> SCALAR
SCALAR --> PG
SCALAR --> CASS
ANALYTICS --> SCALAR
設計にあたっては、以下の調査資料とワークフローを参照してください:
| 資料 | パス | 参照内容 |
|---|---|---|
| インフラ前提条件 | research/06_infrastructure_prerequisites.md | K8s要件、リソース制約、ネットワーク設定 |
| セキュリティ要件 | research/10_security.md | 認証・認可、暗号化、Secret管理 |
| 監視設計 | research/11_observability.md | メトリクス、ログ、分散トレーシング |
| DR設計 | research/12_disaster_recovery.md | バックアップ、リストア、フェイルオーバー |
| ScalarDB v3.17詳細 | research/13_scalardb_317_deep_dive.md | v3.17固有機能、制約事項、移行パス |
| 実施手順 | workflow/07_infrastructure_design.md | ステップバイステップ手順 |
| 資料 | パス | 参照内容 |
|---|---|---|
| マルチテナントSaaS | assets/multi-tenant-saas-architecture.md | テナント分離戦略、マルチテナントK8s設計 |
| API設計 | assets/api-architecture.md | API Gateway設計、認証・認可パターン |
research/06_infrastructure_prerequisites.md の K8sリソース要件research/10_security.md の API Gateway セキュリティresearch/13_scalardb_317_deep_dive.md の全セクション(必須)research/06_infrastructure_prerequisites.md のストレージ設定research/11_observability.md の全セクションresearch/12_disaster_recovery.md の全セクション| パラメータ | 必須 | 説明 | デフォルト |
|---|---|---|---|
| projectName | Yes | プロジェクト名 | - |
| namespace | No | K8s namespace | {projectName} |
| services | Yes | サービス一覧 | - |
| scalardbStorage | No | ストレージ構成 | postgresql + cassandra |
| kongPlugins | No | Kongプラグイン | jwt, rate-limiting |
| enablePiggybackBegin | No | Piggyback Begin有効化 | true (v3.17推奨) |
| enableWriteBuffering | No | Write Buffering有効化 | false (慎重に検討) |
以下のファイルを読み込み、設計要件を抽出:
research/06_infrastructure_prerequisites.md - リソース制約、前提条件research/10_security.md - セキュリティ要件research/11_observability.md - 監視要件research/12_disaster_recovery.md - DR要件research/13_scalardb_317_deep_dive.md - ScalarDB v3.17固有要件# k8s/namespace.yaml
apiVersion: v1
kind: Namespace
metadata:
name: {projectName}
labels:
app: {projectName}
env: production
scalardb-version: "3.17"
各サービスに対して以下を生成:
Deployment:
# k8s/{service-name}/deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
name: {service-name}
namespace: {projectName}
spec:
replicas: 3
selector:
matchLabels:
app: {service-name}
template:
metadata:
labels:
app: {service-name}
spec:
containers:
- name: {service-name}
image: {registry}/{projectName}/{service-name}:latest
ports:
- containerPort: 8080
env:
- name: SPRING_PROFILES_ACTIVE
value: "production"
- name: SCALARDB_CONFIG
valueFrom:
configMapKeyRef:
name: scalardb-config
key: database.properties
resources:
requests:
memory: "512Mi"
cpu: "250m"
limits:
memory: "1Gi"
cpu: "500m"
livenessProbe:
httpGet:
path: /actuator/health/liveness
port: 8080
initialDelaySeconds: 30
periodSeconds: 10
readinessProbe:
httpGet:
path: /actuator/health/readiness
port: 8080
initialDelaySeconds: 10
periodSeconds: 5
Service:
# k8s/{service-name}/service.yaml
apiVersion: v1
kind: Service
metadata:
name: {service-name}
namespace: {projectName}
spec:
selector:
app: {service-name}
ports:
- port: 80
targetPort: 8080
type: ClusterIP
HorizontalPodAutoscaler:
# k8s/{service-name}/hpa.yaml
apiVersion: autoscaling/v2
kind: HorizontalPodAutoscaler
metadata:
name: {service-name}-hpa
namespace: {projectName}
spec:
scaleTargetRef:
apiVersion: apps/v1
kind: Deployment
name: {service-name}
minReplicas: 3
maxReplicas: 10
metrics:
- type: Resource
resource:
name: cpu
target:
type: Utilization
averageUtilization: 70
PodDisruptionBudget (ScalarDB v3.17推奨):
# k8s/{service-name}/pdb.yaml
apiVersion: policy/v1
kind: PodDisruptionBudget
metadata:
name: {service-name}-pdb
namespace: {projectName}
spec:
minAvailable: 2 # 最低2つのPodを常に稼働
selector:
matchLabels:
app: {service-name}
# kong/kong-deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
name: kong
namespace: {projectName}-kong
spec:
replicas: 3
selector:
matchLabels:
app: kong
template:
metadata:
labels:
app: kong
spec:
containers:
- name: kong
image: kong:3.4
ports:
- containerPort: 8000 # Proxy
- containerPort: 8001 # Admin API
- containerPort: 8443 # Proxy SSL
env:
- name: KONG_DATABASE
value: "postgres"
- name: KONG_PG_HOST
value: "kong-postgres"
- name: KONG_PROXY_ACCESS_LOG
value: "/dev/stdout"
- name: KONG_ADMIN_ACCESS_LOG
value: "/dev/stdout"
- name: KONG_PROXY_ERROR_LOG
value: "/dev/stderr"
- name: KONG_ADMIN_ERROR_LOG
value: "/dev/stderr"
# kong/services/{service-name}.yaml
apiVersion: configuration.konghq.com/v1
kind: KongIngress
metadata:
name: {service-name}-ingress
namespace: {projectName}
spec:
route:
strip_path: true
preserve_host: true
---
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: {service-name}-ingress
namespace: {projectName}
annotations:
kubernetes.io/ingress.class: kong
konghq.com/strip-path: "true"
spec:
rules:
- host: api.{domain}
http:
paths:
- path: /{service-path}
pathType: Prefix
backend:
service:
name: {service-name}
port:
number: 80
JWT認証:
# kong/plugins/jwt.yaml
apiVersion: configuration.konghq.com/v1
kind: KongPlugin
metadata:
name: jwt-auth
namespace: {projectName}
plugin: jwt
config:
secret_is_base64: false
claims_to_verify:
- exp
レート制限:
# kong/plugins/rate-limiting.yaml
apiVersion: configuration.konghq.com/v1
kind: KongPlugin
metadata:
name: rate-limiting
namespace: {projectName}
plugin: rate-limiting
config:
minute: 100
hour: 1000
policy: local
CORS:
# kong/plugins/cors.yaml
apiVersion: configuration.konghq.com/v1
kind: KongPlugin
metadata:
name: cors
namespace: {projectName}
plugin: cors
config:
origins:
- "*"
methods:
- GET
- POST
- PUT
- DELETE
- OPTIONS
headers:
- Accept
- Authorization
- Content-Type
exposed_headers:
- X-Auth-Token
max_age: 3600
# scalardb/scalardb.properties
# ===== Coordinator設定 =====
scalar.db.contact_points=postgresql-coordinator
scalar.db.username=${DB_USER}
scalar.db.password=${DB_PASSWORD}
scalar.db.storage=jdbc
scalar.db.transaction_manager=consensus-commit
# ===== v3.17新機能: Piggyback Begin =====
# Piggyback Beginを有効化(推奨: 性能向上)
scalar.db.consensus_commit.piggyback_begin.enabled=true
# ===== v3.17新機能: Write Buffering =====
# Write Bufferingを有効化(注意: 要件に応じて慎重に検討)
# 有効化する場合のみコメント解除
# scalar.db.consensus_commit.write_buffering.enabled=true
# scalar.db.consensus_commit.write_buffering.buffer_size=1000
# ===== Coordinator Table Protection =====
# Coordinator tableの保護設定(v3.17で推奨)
scalar.db.consensus_commit.coordinator.namespace=coordinator
scalar.db.consensus_commit.coordinator.table_metadata.connection_pool_size=10
# ===== PostgreSQLストレージ設定 =====
scalar.db.multi_storage.storages=postgresql,cassandra
scalar.db.multi_storage.storages.postgresql.storage=jdbc
scalar.db.multi_storage.storages.postgresql.contact_points=postgresql-host
scalar.db.multi_storage.storages.postgresql.username=${POSTGRESQL_USER}
scalar.db.multi_storage.storages.postgresql.password=${POSTGRESQL_PASSWORD}
scalar.db.multi_storage.storages.postgresql.jdbc.connection_pool.min_idle=10
scalar.db.multi_storage.storages.postgresql.jdbc.connection_pool.max_idle=50
scalar.db.multi_storage.storages.postgresql.jdbc.connection_pool.max_total=100
# ===== Cassandraストレージ設定 =====
scalar.db.multi_storage.storages.cassandra.storage=cassandra
scalar.db.multi_storage.storages.cassandra.contact_points=cassandra-host
scalar.db.multi_storage.storages.cassandra.username=${CASSANDRA_USER}
scalar.db.multi_storage.storages.cassandra.password=${CASSANDRA_PASSWORD}
scalar.db.multi_storage.storages.cassandra.replication_strategy=NetworkTopologyStrategy
scalar.db.multi_storage.storages.cassandra.replication_factor=3
# ===== ネームスペースマッピング =====
scalar.db.multi_storage.namespace_mapping={namespace}_postgresql:postgresql,{namespace}_cassandra:cassandra
scalar.db.multi_storage.default_storage=postgresql
# ===== パフォーマンスチューニング =====
scalar.db.consensus_commit.serializable_strategy=EXTRA_READ
scalar.db.consensus_commit.isolation_level=SERIALIZABLE
# k8s/scalardb-cluster/deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
name: scalardb-cluster
namespace: {projectName}
spec:
replicas: 3
selector:
matchLabels:
app: scalardb-cluster
template:
metadata:
labels:
app: scalardb-cluster
version: "3.17"
spec:
containers:
- name: scalardb-cluster
image: ghcr.io/scalar-labs/scalardb-cluster-node-byol-standard:3.17.0
ports:
- containerPort: 60051
name: grpc
- containerPort: 8080
name: metrics
env:
- name: SCALAR_DB_CONFIG_FILE
value: "/config/scalardb.properties"
- name: SCALAR_DB_CLUSTER_NODE_PORT
value: "60051"
- name: JAVA_OPTS
value: "-Xms2g -Xmx4g -XX:+UseG1GC"
volumeMounts:
- name: config
mountPath: /config
resources:
requests:
memory: "4Gi"
cpu: "1000m"
limits:
memory: "8Gi"
cpu: "2000m"
livenessProbe:
grpc:
port: 60051
initialDelaySeconds: 60
periodSeconds: 10
readinessProbe:
grpc:
port: 60051
initialDelaySeconds: 30
periodSeconds: 5
volumes:
- name: config
configMap:
name: scalardb-config
# k8s/scalardb-cluster/pdb.yaml
apiVersion: policy/v1
kind: PodDisruptionBudget
metadata:
name: scalardb-cluster-pdb
namespace: {projectName}
spec:
minAvailable: 2 # 最低2ノードは常に稼働
selector:
matchLabels:
app: scalardb-cluster
# k8s/scalardb-config.yaml
apiVersion: v1
kind: ConfigMap
metadata:
name: scalardb-config
namespace: {projectName}
data:
scalardb.properties: |
# Coordinator設定
scalar.db.contact_points=postgresql-coordinator
scalar.db.storage=jdbc
scalar.db.transaction_manager=consensus-commit
# v3.17機能
scalar.db.consensus_commit.piggyback_begin.enabled=true
# Coordinator table保護
scalar.db.consensus_commit.coordinator.namespace=coordinator
# Multi-storage設定
scalar.db.multi_storage.storages=postgresql,cassandra
# ... 詳細設定
# scalardb/scalardb-analytics.properties
# Analytics用設定
scalar.db.sql.enabled=true
scalar.db.sql.connection_mode=direct
scalar.db.sql.default_namespace_name={projectName}
# Spark連携設定(必要な場合)
scalar.db.analytics.spark.master=local[*]
// scalardb/schema.json
{
"{projectName}": {
"{table_name}": {
"transaction": true,
"partition-key": ["{partition_key}"],
"clustering-key": ["{clustering_key}"],
"columns": {
"{column_name}": "{type}"
}
}
}
}
# k8s/monitoring/servicemonitor.yaml
apiVersion: monitoring.coreos.com/v1
kind: ServiceMonitor
metadata:
name: scalardb-cluster
namespace: {projectName}
spec:
selector:
matchLabels:
app: scalardb-cluster
endpoints:
- port: metrics
interval: 30s
# k8s/secrets.yaml
apiVersion: v1
kind: Secret
metadata:
name: scalardb-credentials
namespace: {projectName}
type: Opaque
stringData:
DB_USER: "${DB_USER}"
DB_PASSWORD: "${DB_PASSWORD}"
POSTGRESQL_USER: "${POSTGRESQL_USER}"
POSTGRESQL_PASSWORD: "${POSTGRESQL_PASSWORD}"
CASSANDRA_USER: "${CASSANDRA_USER}"
CASSANDRA_PASSWORD: "${CASSANDRA_PASSWORD}"
# k8s/backup/cronjob.yaml
apiVersion: batch/v1
kind: CronJob
metadata:
name: scalardb-backup
namespace: {projectName}
spec:
schedule: "0 2 * * *" # 毎日2時
jobTemplate:
spec:
template:
spec:
containers:
- name: backup
image: {backup-image}
env:
- name: BACKUP_TARGET
value: "scalardb"
restartPolicy: OnFailure
output/phase3/
└── 07_infrastructure_design.md
├── k8s/
│ ├── namespace.yaml
│ ├── {service-name}/
│ │ ├── deployment.yaml
│ │ ├── service.yaml
│ │ ├── hpa.yaml
│ │ └── pdb.yaml
│ ├── scalardb-cluster/
│ │ ├── deployment.yaml
│ │ ├── service.yaml
│ │ └── pdb.yaml
│ ├── scalardb-config.yaml
│ ├── secrets.yaml
│ ├── monitoring/
│ │ └── servicemonitor.yaml
│ └── backup/
│ └── cronjob.yaml
├── kong/
│ ├── kong-deployment.yaml
│ ├── services/
│ │ └── {service-name}.yaml
│ └── plugins/
│ ├── jwt.yaml
│ ├── rate-limiting.yaml
│ └── cors.yaml
└── scalardb/
├── scalardb.properties
├── scalardb-analytics.properties
└── schema.json
output/phase3/07_infrastructure_design.md:
# インフラストラクチャ設計書
## 1. 概要
### 技術スタック
| コンポーネント | 技術 | バージョン |
|---------------|------|-----------|
| コンテナ基盤 | Kubernetes | 1.28+ |
| API Gateway | Kong | 3.x |
| データ層 | ScalarDB Cluster | 3.17.x |
| 分析 | ScalarDB Analytics | 3.x |
### ScalarDB v3.17新機能の適用
| 機能 | 適用状況 | 理由 |
|------|---------|------|
| Piggyback Begin | 有効 | トランザクション性能向上 |
| Write Buffering | {有効/無効} | {理由} |
| Coordinator Table保護 | 有効 | 本番環境推奨設定 |
## 2. Kubernetes構成
### 2.1 Namespace
- **{projectName}**: アプリケーションサービス
- **{projectName}-kong**: Kong API Gateway
- **{projectName}-data**: データ層
### 2.2 リソース割り当て
| サービス | CPU Request | CPU Limit | Memory Request | Memory Limit | Replicas |
|---------|-------------|-----------|----------------|--------------|----------|
| ScalarDB Cluster | 1000m | 2000m | 4Gi | 8Gi | 3 |
| {service} | 250m | 500m | 512Mi | 1Gi | 3 |
### 2.3 高可用性設定
- **PodDisruptionBudget**: 全サービスに適用(最低2Pod稼働)
- **HorizontalPodAutoscaler**: CPU使用率70%でスケール
- **Liveness/Readiness Probe**: 全Podに設定
## 3. Kong API Gateway
### 3.1 ルーティング
| パス | サービス | 認証 | レート制限 |
|-----|---------|------|-----------|
| /{path} | {service} | JWT | 100/min |
### 3.2 プラグイン
{plugin_list}
### 3.3 セキュリティ設定
参照: `research/10_security.md`
- JWT認証の実装
- レート制限の設定
- CORS設定
## 4. ScalarDB Cluster v3.17構成
### 4.1 ストレージマッピング
| ネームスペース | ストレージ | 用途 |
|---------------|-----------|------|
| {ns}_postgresql | PostgreSQL | トランザクションデータ |
| {ns}_cassandra | Cassandra | スケーラブルデータ |
### 4.2 v3.17固有設定
#### Piggyback Begin
```properties
scalar.db.consensus_commit.piggyback_begin.enabled=true
# 要件に応じて検討
scalar.db.consensus_commit.write_buffering.enabled={true/false}
scalar.db.consensus_commit.coordinator.namespace=coordinator
詳細は scalardb/schema.json 参照
{schema_summary}
参照: research/11_observability.md
参照: research/10_security.md
参照: research/12_disaster_recovery.md
詳細は research/12_disaster_recovery.md 参照
参照: workflow/07_infrastructure_design.md
参照: research/06_infrastructure_prerequisites.md
監視メトリクスとログを活用した問題切り分け
---
## ScalarDB v3.17 固有の注意事項
### Piggyback Begin
**推奨設定**: 有効化(`scalar.db.consensus_commit.piggyback_begin.enabled=true`)
- トランザクション開始時のネットワークラウンドトリップを削減
- 性能向上が期待できる
- 既存の動作に影響なし
### Write Buffering
**慎重な検討が必要**: 要件に応じて判断
有効化する場合:
```properties
scalar.db.consensus_commit.write_buffering.enabled=true
scalar.db.consensus_commit.write_buffering.buffer_size=1000
検討ポイント:
推奨設定: 専用namespace使用
scalar.db.consensus_commit.coordinator.namespace=coordinator
推奨設定: 全クリティカルサービスに適用
spec:
minAvailable: 2 # 最低2Podは常に稼働
詳細は research/13_scalardb_317_deep_dive.md を参照してください。
Skill: infrastructure-design
- プロジェクト名: pce-backend
- サービス:
- tenant-service
- provider-service
- validation-service
- enablePiggybackBegin: true
- enableWriteBuffering: false
Skill: infrastructure-design
- プロジェクト名: pce-backend
- namespace: pce-prod
- scalardbStorage: postgresql only
- kongPlugins:
- jwt
- rate-limiting
- cors
- request-transformer
- enablePiggybackBegin: true
- enableWriteBuffering: true # 要件に応じて有効化
設計完了前に以下を確認してください:
research/06_infrastructure_prerequisites.md の全要件を満たしているresearch/10_security.md のセキュリティ要件を実装しているresearch/11_observability.md の監視設計を反映しているresearch/12_disaster_recovery.md のDR要件を満たしているresearch/13_scalardb_317_deep_dive.md のv3.17固有設定を適用しているoutput/phase3/07_infrastructure_design.md になっているresearch/10_security.md 参照)research/10_security.md 参照)research/13_scalardb_317_deep_dive.md 参照)workflow/07_infrastructure_design.md を参照してください