+ English | + 한국어 | + 日本語 | + 中文 +
+ +# ARCHITECTURE — postgres-operator (日本語) + +> 単一ページのアーキテクチャ説明。CRD サーフェス / Gate / reconcile パターンが変わった際に更新する。 + +> 英語原文: [ARCHITECTURE.md](ARCHITECTURE.md) — canonical / 正本 + +## 概要 + +- **目的**: Apache-2.0 PostgreSQL Kubernetes Operator — *自前実装* (PGO / Citus の fork / wrapper ではない) で PGO クラスの運用品質 + Citus クラスの分散を狙う。 +- **範囲**: K8s 上の vanilla PostgreSQL 18+、single-shard HA → sharding → online resharding → distributed SQL → GA。 +- **安定性ティア**: v0.3.0-alpha.16 (G0 100% / G1 81% / G2 72% / G3 37% / G4-G5 0% / G6 12%) +- **License**: Apache-2.0 (依存: BSD/Apache/MIT/PG-License のみ — SaaS 公開時 copyleft 義務ゼロ) +- **Module path**: `github.com/keiailab/postgres-operator` + +## CRD サーフェス (8 CRD) + +| CRD | apiVersion | Scope | 説明 | +|---|---|---|---| +| `PostgresCluster` | `postgres.keiailab.com/v1alpha1` | Namespaced | Primary HA controller — StatefulSet + WAL + failover | +| `BackupJob` | `postgres.keiailab.com/v1alpha1` | Namespaced | pgBackRest backup / restore / PITR | +| `ScheduledBackup` | `postgres.keiailab.com/v1alpha1` | Namespaced | Cron ベース BackupJob トリガー | +| `PostgresDatabase` | `postgres.keiailab.com/v1alpha1` | Namespaced | 宣言的 database + schema + privilege | +| `PostgresUser` | `postgres.keiailab.com/v1alpha1` | Namespaced | 宣言的 role + password rotation | +| `Pooler` | `postgres.keiailab.com/v1alpha1` | Namespaced | PgBouncer 接続プール | +| `ImageCatalog` / `ClusterImageCatalog` | `postgres.keiailab.com/v1alpha1` | Namespaced / Cluster | 宣言的アップグレード用 image catalog | +| (G3+ 予定) `ShardRange` / `ShardSplitJob` | — | — | Sharding メタデータ + 7-step online resharding | + +## 自前実装の distributed SQL アーキテクチャ + +``` +Application (libpq / JDBC / asyncpg) + │ PostgreSQL wire protocol v3 +pg-router (stateless, HPA-scaled) + │ - vindex 評価 (hash / range / consistent-hash / lookup) + │ - single-shard fast path / multi-shard scatter-gather + │ - distributed transaction coordinator (2PC + saga) + ├──────┬──────┬──────┬────── + Shard A Shard B Shard C Shard D (shard ごと: 1 primary + N replica) + │ instance manager (election + fencing + postgres 監督) + │ +operator manager + - PostgresCluster reconciler + - ShardRange reconciler (source of truth — G3+) + - ShardSplitJob reconciler (7-step workflow — G4+) + - Rebalancer / Backup / Autoscaler glue +``` + +ADR-0001 (`docs/kb/adr/0001-self-built-distributed-sql.md`) が keystone — *PGO / Citus を埋め込まない*。 + +## RBAC スコープ + +- ClusterRole: CRD watch + cert-manager Certificate + ImageCatalog cluster-scope +- Role (ns 単位): StatefulSet / Service / Secret / ConfigMap / PVC / PDB / NetworkPolicy / Job / PgBouncer +- ServiceAccount: `postgres-operator` + +## operator-commons import サーフェス + +採用: **5/8 (63%)**。 + +| パッケージ | 状態 | 用途 | +|---|---|---| +| `pkg/security` | ✅ | restricted PSA (it8) | +| `pkg/version` | ⏳ | ローカルの `version.Combo` が commons.MustList より豊富 — delegation 保留 | +| `pkg/labels` | ✅ | 推奨 labels (it28) | +| `pkg/monitoring` | ⏳ | ServiceMonitor ローカル実装 — commons delegation 保留 | +| `pkg/networkpolicy` | ⏳ | NetworkPolicy ローカル実装 — commons delegation 保留 | +| `pkg/webhook` | ✅ | Validation ヘルパー (it34) | +| `pkg/finalizer` | ✅ | `Add` / `Remove` / `Has` | +| `pkg/status` | ✅ | Condition reason | + +## Gate plan (G0 → G6) + +| Gate | 目標 | 状態 | +|---|---|---| +| G0 | Day-0 deployment | **100%** (7/7) | +| G1 | Single-shard HA (failover + sync repl + PVC fence + lease) | 81% (HA election Lease 保留) | +| G2 | 運用品質 (TLS auto / PrometheusRule / Grafana / Pooler / RBAC / ImageCatalog / Hibernation) | 72% (live drill 保留) | +| G3 | Sharding foundation (`ShardRange` CRD + pg-router PoC + メタデータ) | 37% | +| G4 | Online resharding (`ShardSplitJob` 7-step) | 0% | +| G5 | Distributed SQL (scatter-gather + 2PC/saga + isolation + benchmark) | 0% | +| G6 | 1.0.0 GA (soak ≥7d + chaos + SBOM + cosign + 6 runbook) | 12% | + +100% までのプラン (G6): `~/.claude/plans/2026-05-14-4-operators-100pct/P-D.md` (59 sub-task)。 + +## テストレイヤー + +| レイヤー | 場所 | カバレッジ | +|---|---|---| +| Unit | `internal/**/_test.go`, `api/**/_test.go` | `make test-unit` | +| Integration (envtest) | `test/integration/` | `make test-integration` | +| E2E (kind) | `test/e2e/{*,pg,failover,sharding}/` | `make test-e2e*` | +| Bench | `test/bench/` (G5) | sysbench / pgbench | +| Scorecard | `bundle/tests/scorecard/` | OLM v1alpha3 | + +## ビルド / デプロイ + +- コンテナイメージ: `ghcr.io/keiailab/postgres-operator:v0.3.0-alpha.16` +- Helm chart: `charts/postgres-operator/` (`keiailab.github.io/postgres-operator`) +- OLM bundle: `bundle/` +- ArtifactHub: `keiailab-postgres-operator` +- pg-router: 別バイナリ `cmd/pg-router/` (G3+) + +## セキュリティサプライチェーン + +- OpenSSF Scorecard 有効 +- License audit allowlist (BSD/Apache/MIT/PG-License のみ) +- ADR-0009 が legacy GitHub Actions を禁止強制 (RFC-0002) +- Lefthook DCO + Conventional Commits + lint gate + +## ADR cross-link (24 ADR) + +Notable: +- ADR-0001: 自前実装の distributed SQL (keystone) +- ADR-0006: GitOps deploy overlay 導入 (3-repo 整合) +- ADR-0007: Hook tooling — lefthook ではなく pre-commit +- ADR-0009: webhook validate — accumulate-errors +- ADR-0013: OperatorHub.io bundle scaffold cross-cut +- ADR-0014: community-operators upstream sync 自動化 +- ADR-0019: GitHub Actions 維持 (operator family v2.0 dual-track) +- ADR-0022: GHA narrow exception — 3 workflow (helm-publish + release + scorecard) +- ADR-0023: v3.x-stable baseline の承認 +- ADR-0024: lefthook pre-push incremental lint + envtest +- ADR-0025: Repmgr / PgBouncer / Barman 統合 (bitnami parity) +- ADR-0026: OperatorHub.io 自動 sync + +全リスト: `docs/kb/adr/INDEX.md`。 + +## Non-goals + +- ❌ PostgreSQL < 18 (`pkg/version` 決定により v18 最小) +- ❌ PGO fork または PGO runtime embedding (Apache-2.0 境界) +- ❌ Citus extension 出荷 (問題領域を *再実装*) +- ❌ Patroni / Stolon runtime 依存 (自前 instance manager) +- ❌ Copyleft 依存 (license-clean Apache-2.0 のみ) +- ❌ Plugin SDK (v0.x archive にて retired — 明示 CRD で置換) + +## 参考 + +- `README.md` — アイデンティティ + アーキテクチャ要約 + 機能 +- `ROADMAP.md` + `docs/roadmap.md` — 104 + 91 checkbox (Gate matrix) +- `CHANGELOG.md` +- `ADOPTERS.md` +- `CONTRIBUTING.md` + `MAINTAINERS.md` +- `GOVERNANCE.md` +- `SUPPORT.md` +- `AGENTS.md` +- `docs/kb/adr/INDEX.md` — 24 ADR + +--- + +
+ keiailab operator family
+ postgres-operator ·
+ mongodb-operator ·
+ valkey-operator ·
+ operator-commons ·
+ forgewise
+
+ © 2026 keiailab · Apache-2.0 · keiailab.com +
diff --git a/ARCHITECTURE.ko.md b/ARCHITECTURE.ko.md new file mode 100644 index 00000000..c08b2cb9 --- /dev/null +++ b/ARCHITECTURE.ko.md @@ -0,0 +1,169 @@ ++ English | + 한국어 | + 日本語 | + 中文 +
+ +# ARCHITECTURE — postgres-operator (한국어) + +> 단일 페이지 아키텍처 설명. CRD 표면 / Gate / reconcile 패턴이 바뀔 때 갱신. + +> English 원본: [ARCHITECTURE.md](ARCHITECTURE.md) — canonical / 정본 + +## 개요 + +- **목적**: Apache-2.0 PostgreSQL Kubernetes Operator — *자체 구축* 코드 (PGO/Citus fork 또는 wrapper 아님) 로 PGO 급 운영 품질 + Citus 급 분산을 목표. +- **범위**: K8s 위의 vanilla PostgreSQL 18+, single-shard HA → sharding → online resharding → distributed SQL → GA. +- **안정성 단계**: v0.3.0-alpha.16 (G0 100% / G1 81% / G2 72% / G3 37% / G4-G5 0% / G6 12%) +- **License**: Apache-2.0 (의존성: BSD/Apache/MIT/PG-License 만 — SaaS 노출 시 copyleft 의무 0) +- **Module path**: `github.com/keiailab/postgres-operator` + +## CRD 표면 (8 CRD) + +| CRD | apiVersion | Scope | 설명 | +|---|---|---|---| +| `PostgresCluster` | `postgres.keiailab.com/v1alpha1` | Namespaced | Primary HA controller — StatefulSet + WAL + failover | +| `BackupJob` | `postgres.keiailab.com/v1alpha1` | Namespaced | pgBackRest backup / restore / PITR | +| `ScheduledBackup` | `postgres.keiailab.com/v1alpha1` | Namespaced | Cron 기반 BackupJob 트리거 | +| `PostgresDatabase` | `postgres.keiailab.com/v1alpha1` | Namespaced | 선언적 database + schema + privilege | +| `PostgresUser` | `postgres.keiailab.com/v1alpha1` | Namespaced | 선언적 role + password rotation | +| `Pooler` | `postgres.keiailab.com/v1alpha1` | Namespaced | PgBouncer 연결 풀 | +| `ImageCatalog` / `ClusterImageCatalog` | `postgres.keiailab.com/v1alpha1` | Namespaced / Cluster | 선언적 업그레이드용 이미지 catalog | +| (G3+ 계획) `ShardRange` / `ShardSplitJob` | — | — | Sharding 메타데이터 + 7-step online resharding | + +## 자체 구축 distributed SQL 아키텍처 + +``` +Application (libpq / JDBC / asyncpg) + │ PostgreSQL wire protocol v3 +pg-router (stateless, HPA-scaled) + │ - vindex 평가 (hash / range / consistent-hash / lookup) + │ - single-shard fast path / multi-shard scatter-gather + │ - distributed transaction coordinator (2PC + saga) + ├──────┬──────┬──────┬────── + Shard A Shard B Shard C Shard D (shard 별: 1 primary + N replica) + │ instance manager (election + fencing + postgres 감독) + │ +operator manager + - PostgresCluster reconciler + - ShardRange reconciler (source of truth — G3+) + - ShardSplitJob reconciler (7-step workflow — G4+) + - Rebalancer / Backup / Autoscaler glue +``` + +ADR-0001 (`docs/kb/adr/0001-self-built-distributed-sql.md`) 이 keystone — *PGO/Citus embedding 없음*. + +## RBAC 범위 + +- ClusterRole: CRD watch + cert-manager Certificate + ImageCatalog cluster-scope +- Role (ns 별): StatefulSet / Service / Secret / ConfigMap / PVC / PDB / NetworkPolicy / Job / PgBouncer +- ServiceAccount: `postgres-operator` + +## operator-commons import 표면 + +채택: **5/8 (63%)**. + +| 패키지 | 상태 | 사용 | +|---|---|---| +| `pkg/security` | ✅ | restricted PSA (it8) | +| `pkg/version` | ⏳ | 로컬 `version.Combo` 가 commons.MustList 보다 풍부 — delegation 보류 | +| `pkg/labels` | ✅ | 권장 labels (it28) | +| `pkg/monitoring` | ⏳ | ServiceMonitor 로컬 구현 — commons delegation 보류 | +| `pkg/networkpolicy` | ⏳ | NetworkPolicy 로컬 구현 — commons delegation 보류 | +| `pkg/webhook` | ✅ | Validation 헬퍼 (it34) | +| `pkg/finalizer` | ✅ | `Add` / `Remove` / `Has` | +| `pkg/status` | ✅ | Condition reason | + +## Gate plan (G0 → G6) + +| Gate | 목표 | 상태 | +|---|---|---| +| G0 | Day-0 deployment | **100%** (7/7) | +| G1 | Single-shard HA (failover + sync repl + PVC fence + lease) | 81% (HA election Lease 보류) | +| G2 | 운영 품질 (TLS auto / PrometheusRule / Grafana / Pooler / RBAC / ImageCatalog / Hibernation) | 72% (live drill 보류) | +| G3 | Sharding foundation (`ShardRange` CRD + pg-router PoC + 메타데이터) | 37% | +| G4 | Online resharding (`ShardSplitJob` 7-step) | 0% | +| G5 | Distributed SQL (scatter-gather + 2PC/saga + isolation + benchmark) | 0% | +| G6 | 1.0.0 GA (soak ≥7d + chaos + SBOM + cosign + 6 runbook) | 12% | + +100% 까지의 계획 (G6): `~/.claude/plans/2026-05-14-4-operators-100pct/P-D.md` (59 sub-task). + +## 테스트 레이어 + +| 레이어 | 위치 | 커버리지 | +|---|---|---| +| Unit | `internal/**/_test.go`, `api/**/_test.go` | `make test-unit` | +| Integration (envtest) | `test/integration/` | `make test-integration` | +| E2E (kind) | `test/e2e/{*,pg,failover,sharding}/` | `make test-e2e*` | +| Bench | `test/bench/` (G5) | sysbench / pgbench | +| Scorecard | `bundle/tests/scorecard/` | OLM v1alpha3 | + +## 빌드 / 배포 + +- 컨테이너 이미지: `ghcr.io/keiailab/postgres-operator:v0.3.0-alpha.16` +- Helm chart: `charts/postgres-operator/` (`keiailab.github.io/postgres-operator`) +- OLM bundle: `bundle/` +- ArtifactHub: `keiailab-postgres-operator` +- pg-router: 별 binary `cmd/pg-router/` (G3+) + +## 보안 공급망 + +- OpenSSF Scorecard 활성 +- License audit allowlist (BSD/Apache/MIT/PG-License 만) +- ADR-0009 가 legacy GitHub Actions 금지 강제 (RFC-0002) +- Lefthook DCO + Conventional Commits + lint gate + +## ADR cross-link (24 ADR) + +Notable: +- ADR-0001: 자체 구축 distributed SQL (keystone) +- ADR-0006: GitOps deploy overlay 도입 (3-repo 정합) +- ADR-0007: Hook tooling — lefthook 대신 pre-commit +- ADR-0009: webhook validate — accumulate-errors +- ADR-0013: OperatorHub.io bundle scaffold cross-cut +- ADR-0014: community-operators upstream sync 자동화 +- ADR-0019: GitHub Actions 유지 (operator family v2.0 dual-track) +- ADR-0022: GHA narrow exception — 3 workflow (helm-publish + release + scorecard) +- ADR-0023: v3.x-stable baseline 인정 +- ADR-0024: lefthook pre-push incremental lint + envtest +- ADR-0025: Repmgr / PgBouncer / Barman 통합 (bitnami parity) +- ADR-0026: OperatorHub.io 자동 sync + +전체 목록: `docs/kb/adr/INDEX.md`. + +## Non-goals + +- ❌ PostgreSQL < 18 (`pkg/version` 결정상 v18 최소) +- ❌ PGO fork 또는 PGO runtime embedding (Apache-2.0 경계) +- ❌ Citus extension 출하 (문제 공간을 *재구현*) +- ❌ Patroni / Stolon runtime 의존 (자체 instance manager) +- ❌ Copyleft 의존성 (license-clean Apache-2.0 만) +- ❌ Plugin SDK (v0.x archive 에서 retired — 명시 CRD 로 대체) + +## 참조 + +- `README.md` — 정체성 + 아키텍처 요약 + 기능 +- `ROADMAP.md` + `docs/roadmap.md` — 104 + 91 checkbox (Gate matrix) +- `CHANGELOG.md` +- `ADOPTERS.md` +- `CONTRIBUTING.md` + `MAINTAINERS.md` +- `GOVERNANCE.md` +- `SUPPORT.md` +- `AGENTS.md` +- `docs/kb/adr/INDEX.md` — 24 ADR + +--- + +
+ keiailab operator family
+ postgres-operator ·
+ mongodb-operator ·
+ valkey-operator ·
+ operator-commons ·
+ forgewise
+
+ © 2026 keiailab · Apache-2.0 · keiailab.com +
diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md index 6c011741..3f0621d9 100644 --- a/ARCHITECTURE.md +++ b/ARCHITECTURE.md @@ -112,15 +112,21 @@ Plan to 100% (G6): `~/.claude/plans/2026-05-14-4-operators-100pct/P-D.md` (59 su - ADR-0009 enforces no legacy GitHub Actions (RFC-0002) - Lefthook DCO + Conventional Commits + lint gate -## ADR cross-link (17 ADRs) +## ADR cross-link (24 ADRs) Notable: - ADR-0001: self-built distributed SQL (keystone) -- ADR-0006: Repmgr / PgBouncer / Barman integration plan (bitnami parity) -- ADR-0007: OperatorHub.io 자동 sync -- ADR-0009: no legacy GitHub Actions (RFC-0002 정합) -- ADR-0013: scorecard OLM test parity standard (cross-repo with mongodb) +- ADR-0006: introduce the GitOps deploy overlay (3-repo alignment) +- ADR-0007: hook tooling — pre-commit instead of lefthook +- ADR-0009: webhook validate — accumulate-errors +- ADR-0013: OperatorHub.io bundle scaffold cross-cut - ADR-0014: community-operators upstream sync automation +- ADR-0019: GitHub Actions retention (operator family v2.0 dual-track) +- ADR-0022: GHA narrow exception — 3 workflow (helm-publish + release + scorecard) +- ADR-0023: v3.x-stable baseline 인정 +- ADR-0024: lefthook pre-push incremental lint + envtest +- ADR-0025: Repmgr / PgBouncer / Barman integration plan (bitnami parity) +- ADR-0026: OperatorHub.io 자동 sync Full list: `docs/kb/adr/INDEX.md`. diff --git a/ARCHITECTURE.zh.md b/ARCHITECTURE.zh.md new file mode 100644 index 00000000..4f6dabc0 --- /dev/null +++ b/ARCHITECTURE.zh.md @@ -0,0 +1,169 @@ ++ English | + 한국어 | + 日本語 | + 中文 +
+ +# ARCHITECTURE — postgres-operator (中文) + +> 单页架构说明。在 CRD 表面 / Gate / reconcile 模式发生变化时更新。 + +> 英文原文: [ARCHITECTURE.md](ARCHITECTURE.md) — canonical / 正本 + +## 概述 + +- **目的**: Apache-2.0 PostgreSQL Kubernetes Operator — 以 *自建* 代码 (非 PGO / Citus 的 fork 或 wrapper) 实现 PGO 级运营质量 + Citus 级分布式。 +- **范围**: K8s 上的 vanilla PostgreSQL 18+,single-shard HA → sharding → online resharding → distributed SQL → GA。 +- **稳定性等级**: v0.3.0-alpha.16 (G0 100% / G1 81% / G2 72% / G3 37% / G4-G5 0% / G6 12%) +- **License**: Apache-2.0 (依赖: 仅 BSD/Apache/MIT/PG-License — SaaS 暴露时 copyleft 义务为 0) +- **Module path**: `github.com/keiailab/postgres-operator` + +## CRD 表面 (8 CRD) + +| CRD | apiVersion | Scope | 描述 | +|---|---|---|---| +| `PostgresCluster` | `postgres.keiailab.com/v1alpha1` | Namespaced | Primary HA controller — StatefulSet + WAL + failover | +| `BackupJob` | `postgres.keiailab.com/v1alpha1` | Namespaced | pgBackRest backup / restore / PITR | +| `ScheduledBackup` | `postgres.keiailab.com/v1alpha1` | Namespaced | 基于 Cron 的 BackupJob 触发器 | +| `PostgresDatabase` | `postgres.keiailab.com/v1alpha1` | Namespaced | 声明式 database + schema + privilege | +| `PostgresUser` | `postgres.keiailab.com/v1alpha1` | Namespaced | 声明式 role + password rotation | +| `Pooler` | `postgres.keiailab.com/v1alpha1` | Namespaced | PgBouncer 连接池 | +| `ImageCatalog` / `ClusterImageCatalog` | `postgres.keiailab.com/v1alpha1` | Namespaced / Cluster | 声明式升级用 image catalog | +| (G3+ 计划) `ShardRange` / `ShardSplitJob` | — | — | Sharding 元数据 + 7-step online resharding | + +## 自建 distributed SQL 架构 + +``` +Application (libpq / JDBC / asyncpg) + │ PostgreSQL wire protocol v3 +pg-router (stateless, HPA-scaled) + │ - vindex 评估 (hash / range / consistent-hash / lookup) + │ - single-shard fast path / multi-shard scatter-gather + │ - distributed transaction coordinator (2PC + saga) + ├──────┬──────┬──────┬────── + Shard A Shard B Shard C Shard D (每 shard: 1 primary + N replica) + │ instance manager (election + fencing + postgres 监督) + │ +operator manager + - PostgresCluster reconciler + - ShardRange reconciler (source of truth — G3+) + - ShardSplitJob reconciler (7-step workflow — G4+) + - Rebalancer / Backup / Autoscaler glue +``` + +ADR-0001 (`docs/kb/adr/0001-self-built-distributed-sql.md`) 是 keystone — *不内嵌 PGO / Citus*。 + +## RBAC 范围 + +- ClusterRole: CRD watch + cert-manager Certificate + ImageCatalog cluster-scope +- Role (按 ns): StatefulSet / Service / Secret / ConfigMap / PVC / PDB / NetworkPolicy / Job / PgBouncer +- ServiceAccount: `postgres-operator` + +## operator-commons import 表面 + +采用: **5/8 (63%)**。 + +| 包 | 状态 | 用途 | +|---|---|---| +| `pkg/security` | ✅ | restricted PSA (it8) | +| `pkg/version` | ⏳ | 本地 `version.Combo` 比 commons.MustList 更丰富 — delegation 暂缓 | +| `pkg/labels` | ✅ | 推荐 labels (it28) | +| `pkg/monitoring` | ⏳ | ServiceMonitor 本地实现 — commons delegation 暂缓 | +| `pkg/networkpolicy` | ⏳ | NetworkPolicy 本地实现 — commons delegation 暂缓 | +| `pkg/webhook` | ✅ | Validation 帮助函数 (it34) | +| `pkg/finalizer` | ✅ | `Add` / `Remove` / `Has` | +| `pkg/status` | ✅ | Condition reason | + +## Gate plan (G0 → G6) + +| Gate | 目标 | 状态 | +|---|---|---| +| G0 | Day-0 deployment | **100%** (7/7) | +| G1 | Single-shard HA (failover + sync repl + PVC fence + lease) | 81% (HA election Lease 暂缓) | +| G2 | 运营质量 (TLS auto / PrometheusRule / Grafana / Pooler / RBAC / ImageCatalog / Hibernation) | 72% (live drill 暂缓) | +| G3 | Sharding foundation (`ShardRange` CRD + pg-router PoC + 元数据) | 37% | +| G4 | Online resharding (`ShardSplitJob` 7-step) | 0% | +| G5 | Distributed SQL (scatter-gather + 2PC/saga + isolation + benchmark) | 0% | +| G6 | 1.0.0 GA (soak ≥7d + chaos + SBOM + cosign + 6 runbook) | 12% | + +到 100% 的计划 (G6): `~/.claude/plans/2026-05-14-4-operators-100pct/P-D.md` (59 sub-task)。 + +## 测试层次 + +| 层次 | 位置 | 覆盖率 | +|---|---|---| +| Unit | `internal/**/_test.go`, `api/**/_test.go` | `make test-unit` | +| Integration (envtest) | `test/integration/` | `make test-integration` | +| E2E (kind) | `test/e2e/{*,pg,failover,sharding}/` | `make test-e2e*` | +| Bench | `test/bench/` (G5) | sysbench / pgbench | +| Scorecard | `bundle/tests/scorecard/` | OLM v1alpha3 | + +## 构建 / 部署 + +- 容器镜像: `ghcr.io/keiailab/postgres-operator:v0.3.0-alpha.16` +- Helm chart: `charts/postgres-operator/` (`keiailab.github.io/postgres-operator`) +- OLM bundle: `bundle/` +- ArtifactHub: `keiailab-postgres-operator` +- pg-router: 独立 binary `cmd/pg-router/` (G3+) + +## 安全供应链 + +- OpenSSF Scorecard 启用 +- License audit allowlist (仅 BSD/Apache/MIT/PG-License) +- ADR-0009 强制禁止 legacy GitHub Actions (RFC-0002) +- Lefthook DCO + Conventional Commits + lint gate + +## ADR cross-link (24 ADR) + +Notable: +- ADR-0001: 自建 distributed SQL (keystone) +- ADR-0006: 引入 GitOps deploy overlay (3-repo 一致) +- ADR-0007: Hook tooling — 用 pre-commit 而非 lefthook +- ADR-0009: webhook validate — accumulate-errors +- ADR-0013: OperatorHub.io bundle scaffold cross-cut +- ADR-0014: community-operators upstream sync 自动化 +- ADR-0019: 保留 GitHub Actions (operator family v2.0 dual-track) +- ADR-0022: GHA narrow exception — 3 workflow (helm-publish + release + scorecard) +- ADR-0023: 承认 v3.x-stable baseline +- ADR-0024: lefthook pre-push incremental lint + envtest +- ADR-0025: Repmgr / PgBouncer / Barman 集成 (bitnami parity) +- ADR-0026: OperatorHub.io 自动 sync + +完整列表: `docs/kb/adr/INDEX.md`。 + +## Non-goals + +- ❌ PostgreSQL < 18 (`pkg/version` 决定 v18 最低) +- ❌ PGO fork 或 PGO runtime embedding (Apache-2.0 边界) +- ❌ Citus extension 出货 (将问题领域 *重新实现*) +- ❌ Patroni / Stolon runtime 依赖 (自建 instance manager) +- ❌ Copyleft 依赖 (license-clean Apache-2.0 only) +- ❌ Plugin SDK (在 v0.x archive 已 retired — 用显式 CRD 替代) + +## 参考 + +- `README.md` — 身份 + 架构摘要 + 功能 +- `ROADMAP.md` + `docs/roadmap.md` — 104 + 91 checkbox (Gate matrix) +- `CHANGELOG.md` +- `ADOPTERS.md` +- `CONTRIBUTING.md` + `MAINTAINERS.md` +- `GOVERNANCE.md` +- `SUPPORT.md` +- `AGENTS.md` +- `docs/kb/adr/INDEX.md` — 24 ADR + +--- + +
+ keiailab operator family
+ postgres-operator ·
+ mongodb-operator ·
+ valkey-operator ·
+ operator-commons ·
+ forgewise
+
+ © 2026 keiailab · Apache-2.0 · keiailab.com +
diff --git a/docs/kb/adr/0006-repmgr-pgbouncer-barman-integration.md b/docs/kb/adr/0025-repmgr-pgbouncer-barman-integration.md similarity index 97% rename from docs/kb/adr/0006-repmgr-pgbouncer-barman-integration.md rename to docs/kb/adr/0025-repmgr-pgbouncer-barman-integration.md index 7408477c..2552962e 100644 --- a/docs/kb/adr/0006-repmgr-pgbouncer-barman-integration.md +++ b/docs/kb/adr/0025-repmgr-pgbouncer-barman-integration.md @@ -1,4 +1,4 @@ -# ADR-0006: Repmgr/PgBouncer/Barman 통합 — bitnami parity +# ADR-0025: Repmgr/PgBouncer/Barman 통합 — bitnami parity - **Date**: 2026-05-14 - **Status**: Proposed diff --git a/docs/kb/adr/0007-operatorhub-io-version-sync.md b/docs/kb/adr/0026-operatorhub-io-version-sync.md similarity index 98% rename from docs/kb/adr/0007-operatorhub-io-version-sync.md rename to docs/kb/adr/0026-operatorhub-io-version-sync.md index 75e4f853..83d0370b 100644 --- a/docs/kb/adr/0007-operatorhub-io-version-sync.md +++ b/docs/kb/adr/0026-operatorhub-io-version-sync.md @@ -1,4 +1,4 @@ -# ADR-0007: OperatorHub.io 최신 버전 자동 sync +# ADR-0026: OperatorHub.io 최신 버전 자동 sync - **Date**: 2026-05-14 - **Status**: Proposed diff --git a/docs/kb/adr/INDEX.md b/docs/kb/adr/INDEX.md index f63cec52..d7b8834e 100644 --- a/docs/kb/adr/INDEX.md +++ b/docs/kb/adr/INDEX.md @@ -35,6 +35,8 @@ Standard path: `