cnpg-database

CNPG データベース管理

アーキテクチャの概要

すべてのクラスターは database 名前空間にあります。共有プラットフォームクラスター（platform-0/1/2）では、アプリごとに spec.managed.roles と Database CRD を使用し、PgBouncer プーラーは platform-pooler-rw.database.svc にあります。専用クラスター（Immich など）では、initdb を使って独自のデータベースとオーナーを初期化します。どちらの場合も、kubernetes-replicator を介して認証情報が利用アプリの名前空間に複製されます。

判断基準：共有クラスターと専用クラスター

標準的なワークロードで、特殊な拡張機能が不要 → 共有クラスター（platform-pooler-rw.database.svc） カスタム拡張機能（vector、PostGIS）または分離が必要 → カスタムの imageName を使った専用クラスター 判断がつかない → まず共有クラスターを使い、必要に応じて移行

---

主要ファイル（共有クラスター）

場所：kubernetes/platform/config/database/

ファイル	目的
cluster.yaml	spec.managed.roles を含む CNPG Cluster CR
databases.yaml	Database CRD（アプリのデータベースごとに 1 つ）
role-secrets.yaml	ロールごとのパスワードシークレット（secret-generator + replicator）
pooler.yaml	PgBouncer Pooler（platform-pooler-rw）
superuser-secret.yaml	自動生成されたスーパーユーザーのパスワード（database 名前空間のみ）
prometheus-rules.yaml	CNPG 固有の PrometheusRules

マニフェストの例については、references/cluster-reference.md を参照してください。

---

ワークフロー：新しいアプリ用のデータベースを追加する（共有クラスター）

手順 1～3 では kubernetes/platform/config/database/ のファイルを編集します。手順 4～5 はアプリのクラスター設定で行います。

手順 1：管理対象ロールを追加する：cluster.yaml の spec.managed.roles に追加します。テンプレートについては、references/cluster-reference.md を参照してください。

手順 2：ロールのパスワードシークレットを作成する：role-secrets.yaml に作成します。テンプレートについては、references/credentials.md を参照してください。

手順 3：Database CRD を作成する：databases.yaml に作成します。テンプレートについては、references/cluster-reference.md を参照してください。

注：複数のデータベース（sonarr-main、sonarr-log）を持つアプリでは、1 つのロールを共有します。同じ owner を指定して、個別の Database CR を作成してください。

手順 4：認証情報のレプリカを作成する：kubernetes/clusters/<cluster>/config/<app>/ に作成します。テンプレートについては、references/credentials.md を参照してください。

手順 5：ネットワークポリシーのアクセスラベルを追加する：kubernetes/platform/namespaces.yaml の名前空間エントリーに、access.network-policy.homelab/postgres: "true" を追加します。

手順 6：登録する：認証情報のレプリカを、アプリの kustomization.yaml に登録します。

認証情報チェーンの図については、references/credentials.md を参照してください。

---

ワークフロー：専用の CNPG クラスターを作成する

アプリでカスタム PostgreSQL 拡張機能やパフォーマンス／データの分離が必要な場合に使用します。

ステップ 1：クラスターを定義します。kubernetes/clusters/<cluster>/config/<app>/<app>-cluster.yaml に定義します。自動生成されたアプリシークレットを複製できるよう、inheritedMetadata を設定します。マニフェスト全体の例については、references/cluster-reference.md を参照してください。

共有クラスターとの主な違い：

機能	共有	専用
場所	kubernetes/platform/config/database/	kubernetes/clusters/<cluster>/config/<app>/
イメージ	標準の PostgreSQL	拡張機能を含むカスタムイメージ
ロール管理	spec.managed.roles + Database CRD	bootstrap.initdb で DB と所有者を作成
認証情報のソース	<app>-role-password（secret-generator）	<app>-database-app（CNPG が自動生成）
inheritedMetadata	不要	シークレットの複製に必須

ステップ 2：アプリの認証情報を コンシューマーの名前空間に複製します。CNPG は database 内に <cluster-name>-app を自動生成します。inheritedMetadata のアノテーションで複製を有効にします。テンプレートについては、references/credentials.md を参照してください。

実例：kubernetes/clusters/live/config/immich/database-secret-replication.yaml

ステップ 3： アプリの名前空間に access.network-policy.homelab/postgres: "true" ラベルを追加し、すべてのファイルを kustomization.yaml に登録します。

---

モニタリング

Cluster と Pooler の両方で monitoring.enablePodMonitor: true を設定します。Prometheus が自動的に検出するため、手動で ServiceMonitor を設定する必要はありません。

CNPG のアラートは kubernetes/platform/config/database/prometheus-rules.yaml にあります。

アラート	条件	重大度
CNPGClusterNotHealthy	cnpg_pg_replication_streaming == 0	重大
CNPGClusterHighConnections	接続使用率が max_connections の 80% を超過	警告
CNPGInstanceNotReady	レプリカの WAL レシーバーが停止	重大

主なメトリクス：cnpg_pg_replication_streaming、cnpg_pg_stat_activity_count、cnpg_pg_settings_setting{name="max_connections"}、cnpg_pg_replication_is_wal_receiver_up。

---

デバッグ

構造化されたヘルスチェックには、scripts/check-connection.sh <cluster> <app-namespace> [app-name] を使用します。

よくある問題：

症状	原因	対処法
Pod が Pending	使用可能な PV がない	StorageClass fast が存在し、Longhorn が正常であることを確認します
CrashLoopBackOff	OOM または不正な設定	kubectl logs を確認し、メモリー制限を引き上げます
アプリが接続できない	ネットワークポリシーがない	access.network-policy.homelab/postgres: "true" を追加します
アプリが接続できない	シークレットが複製されていない	ソースシークレットの複製アノテーションを確認します
複製後のシークレットが空	ソースの名前空間が間違っている	replicate-from が正しい <ns>/<name> を指していることを確認します
拡張機能が見つからない	イメージが間違っている	imageName に拡張機能が含まれていることを確認します
データベースが作成されない	Database CRD がない	databases.yaml に Database CR を追加します
ロールが作成されない	managed.roles にない	cluster.yaml にロールエントリーを追加します
ロールのパスワードが一致しない	シークレットが再生成されていない	role-password シークレットを削除します。secret-generator が再作成します

手動での接続テスト：kubectl run -n <app-ns> pg-test --rm -it --image=postgres:17 -- psql "postgresql://user:[email protected]:5432/dbname"

---

相互参照

ドキュメント	関連性
references/cluster-reference.md	Cluster CRD のフィールドと完全なマニフェストの例
references/credentials.md	認証情報チェーンの図とシークレットのテンプレート
scripts/check-connection.sh	構造化されたヘルスチェックコマンド
secrets skill	secret-generator、ExternalSecret、レプリケーションのパターン
deploy-app skill	データベースのセットアップを含むエンドツーエンドのデプロイ
kubernetes/platform/config/CLAUDE.md	Config サブシステムと CRD の依存関係パターン