fix(router): deploy pg-router image + PGROUTER_* env + dedicated RBAC (B-01)

Dockerfile.bench

@@ -0,0 +1,21 @@
+# Build the router-bench binary — 라우터 처리량/오버헤드 측정 도구(Suite F / F-4·F-5).
+# In-cluster Job 으로 실행: router ClusterIP + shard DNS 를 env 로 받아 벤치.
+FROM golang:1.26.4@sha256:68cb6d68bed024785b69195b89af7ac7a444f27791435f98647edff595aa0479 AS builder
+ARG TARGETOS
+ARG TARGETARCH
+
+WORKDIR /workspace
+COPY go.mod go.mod
+COPY go.sum go.sum
+RUN go mod download
+
+COPY . .
+
+RUN CGO_ENABLED=0 GOOS=${TARGETOS:-linux} GOARCH=${TARGETARCH} go build -a -o router-bench ./cmd/router-bench
+
+FROM gcr.io/distroless/static:nonroot@sha256:e3f945647ffb95b5839c07038d64f9811adf17308b9121d8a2b87b6a22a80a39
+WORKDIR /
+COPY --from=builder /workspace/router-bench .
+USER 65532:65532
+
+ENTRYPOINT ["/router-bench"]

README.md

@@ -33,10 +33,12 @@ The operator runs **unmodified upstream PostgreSQL** — no forked engine, no em
 - **Connection pooling** — `Pooler` runs a PgBouncer layer in front of a cluster, with transaction/session pool modes and optional cert-manager TLS.
 - **Declarative databases & roles** — `PostgresDatabase` and `PostgresUser` manage databases, schemas, extensions, FDWs, roles, memberships, and passwords against the ready primary.
 - **Image catalogs** — `ImageCatalog` / `ClusterImageCatalog` pin the PostgreSQL runtime image per major version, namespace- or cluster-scoped.
+- **Native sharding** — `ShardRange` is the routing topology source of truth, while the reconciled `pg-router` deployment provides point routing, scatter-gather reads, and failover-aware backends.
+- **Online and offline resharding** — `ShardSplitJob` provisions target shards, copies data, optionally catches up with logical replication, switches routing, and cleans up through a guarded state machine.
 - **Observability** — the Helm chart ships a Prometheus `ServiceMonitor`, a `PrometheusRule` with built-in alerts, and Grafana dashboards.
 - **Secure by default** — restricted Pod Security Context, deny-by-default `NetworkPolicy`, and TLS via cert-manager.
 
-The chart installs **8 CRDs**:
+The chart installs **10 CRDs**:
 
 | CRD | Purpose |
 |---|---|
@@ -48,10 +50,12 @@ The chart installs **8 CRDs**:
 | `PostgresUser` | Declarative role / membership / password |
 | `ImageCatalog` | Namespace-scoped PostgreSQL image catalog |
 | `ClusterImageCatalog` | Cluster-wide PostgreSQL image catalog |
+| `ShardRange` | Shard-key ranges and their current routing targets |
+| `ShardSplitJob` | Guarded online or offline shard split workflow |
 
 ## Status
 
-Current release: **v0.4.0-beta.1**. The operator manages single-cluster PostgreSQL (primary + replicas) with HA, backups, pooling, and monitoring. It is **beta** — verify your own backup/restore procedure before trusting it with production data. See [Roadmap](#roadmap) for what is not yet built.
+Current operator release: **v0.4.0-beta.8**. The bundled Helm chart is **0.4.0-beta.9** and packages that operator version. The operator manages PostgreSQL clusters with HA, backups, pooling, monitoring, native shard routing, and guarded online/offline shard splits. It is **beta** — verify backup/restore and reshard rollback procedures against your own workload before production use. See [Roadmap](#roadmap) for the remaining distributed-SQL work.
 
 ## Installation
 
@@ -136,22 +140,21 @@ Helm keeps CRDs on uninstall by design; remove them manually with `kubectl delet
 
 ## Roadmap
 
-Beyond single-cluster operations, the long-term goal is a horizontally sharded, distributed-SQL layer on top of vanilla PostgreSQL. The `ShardRange` and `ShardSplitJob` CRD types are defined, but **no controllers exist for them yet** — sharding and the `pg-router` query layer are design-only at this stage.
+Beyond single-cluster operations, the project is building a horizontally sharded, distributed-SQL layer on top of vanilla PostgreSQL. `ShardRange`, the reconciled `pg-router`, AutoSplit evaluation, and the single-source `ShardSplitJob` split state machine are implemented. The current branch also guards offline initial copy, online logical-replication catch-up, routing cutover, source cleanup, and target promotion. These paths remain beta and require workload-specific validation. `direction=merge` and multiple sources are rejected before side effects; `cutoverWindow` enforcement and automatic rollback are not implemented. A split source must currently use the ordinal `shard-N` form; a promoted named shard such as `shard-1a` cannot yet be selected as a later split source. Router SQL coverage is also bounded rather than a general distributed SQL engine, and cross-shard transactions and general distributed JOINs are not complete.
 
 Planned, roughly in order:
 
 - HA hardening — PITR drill, chaos failover testing
-- `ShardRange` CRD controller + `pg-router` (manual multi-shard routing)
-- Scatter-gather queries + read-replica autoscaling
-- `ShardSplitJob` — online shard splitting
-- Automatic split/rebalance triggered by load
+- Harden `pg-router` and resharding with broader failure-injection and scale tests
+- Expand scatter-gather SQL coverage and read-replica autoscaling
+- Validate automatic split/rebalance policies on production-shaped workloads
 - Cross-shard distributed transactions and JOINs
 
 Detailed phase plan, sub-tasks, and SLOs: [`docs/ROADMAP.md`](docs/ROADMAP.md). Architecture and design decisions: [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md), [`docs/sharding/SHARDING.md`](docs/sharding/SHARDING.md), and the [ADR index](docs/kb/adr/INDEX.md).
 
 ## Contributing
 
-The canonical repository is on [GitLab](https://keiailab.synology.me/gitlab/keiailab/oss/postgres-operator), mirrored to [GitHub](https://github.com/keiailab/postgres-operator).
+The canonical development and release repository is [GitHub](https://github.com/keiailab/postgres-operator). Any GitLab copy is an archive mirror, not the development source of truth.
 
 ```bash
 make lint test validate   # lint + unit tests + manifest validation

api/v1alpha1/postgrescluster_types.go

@@ -111,13 +111,30 @@ type RouterAutoscaleSpec struct {
 	// +optional
 	TargetCPU int32 `json:"targetCPU,omitempty"`
 
-	// TargetActiveConnections is the HPA active-connection target.
+	// TargetActiveConnections is the HPA active-connection target (average value per Pod).
+	// Only used when ScaleOnActiveConnections=true.
 	// +kubebuilder:validation:Minimum=1
 	// +kubebuilder:default=1000
 	// +optional
 	TargetActiveConnections int32 `json:"targetActiveConnections,omitempty"`
+
+	// ScaleOnActiveConnections enables an additional Pods metric on the router HPA that
+	// scales on the average active client-connection count per router Pod (metric
+	// RouterActiveConnectionsMetric, exposed by pg-router's /metrics endpoint). Default
+	// false keeps the HPA CPU-only. Requires a custom-metrics adapter (e.g.
+	// prometheus-adapter) in the cluster that maps the scraped gauge into the
+	// custom.metrics.k8s.io API; without it the Pods metric reports unavailable and the
+	// HPA falls back to CPU.
+	// +kubebuilder:default=false
+	// +optional
+	ScaleOnActiveConnections bool `json:"scaleOnActiveConnections,omitempty"`
 }
 
+// RouterActiveConnectionsMetric is the Prometheus/custom-metrics name that pg-router
+// exposes for its active client-connection gauge and that the router HPA's Pods metric
+// targets when ScaleOnActiveConnections is enabled.
+const RouterActiveConnectionsMetric = "pgrouter_active_connections"
+
 // RouterSpec is the stateless QueryRouter Deployment configuration (RFC 0001 §3.1, RFC 0004).
 //
 // This struct intentionally omits a Storage field — the router's statelessness is enforced
@@ -161,6 +178,15 @@ type AutoSplitTriggers struct {
 	// +optional
 	CPUPercent int32 `json:"cpuPercent,omitempty"`
 
+	// PVCUtilizationPercent is the per-shard data-PVC utilization threshold (%,
+	// dbSize/pvcCapacity). 0 disables. Unlike SizeThresholdGB (absolute GB), this expresses
+	// "split when the shard fills X% of its PVC" directly, so no manual GB conversion is needed
+	// and it self-adjusts on PVC resize (K-5 gap closure).
+	// +kubebuilder:validation:Minimum=0
+	// +kubebuilder:validation:Maximum=100
+	// +optional
+	PVCUtilizationPercent int32 `json:"pvcUtilizationPercent,omitempty"`
+
 	// DurationMinutes is how long the thresholds above must be sustained (minutes). 0 means immediate.
 	// +kubebuilder:validation:Minimum=0
 	// +optional

api/v1alpha1/shardsplitjob_types.go

@@ -14,16 +14,16 @@ import (
 //
 // 7-step workflow (RFC-0002 §online-resharding 정합):
 //
-//  1. Snapshot + WAL capture — source shard 의 시점 일관 base snapshot 확보
+//  1. SnapshotWAL — 현재는 호환성을 위해 유지하는 no-op 전이 단계
 //  2. Bootstrap target shard — 신규 shard StatefulSet 생성 + PG init
-//  3. Initial copy — base snapshot 적용 (logical 또는 pg_basebackup)
-//  4. CDC catch-up — source 의 변경분을 logical replication 으로 따라잡기
+//  3. Initial copy — offline 모드의 bulk/range copy Job (online 모드는 no-op)
+//  4. CDC catch-up — online 모드에서 copy_data=true logical replication으로 초기복사와 변경분을 따라잡기
 //  5. Cutover — write 차단 최소화 윈도우 + router 라우팅 갱신
 //  6. Routing update — ShardRange CRD 의 ranges 갱신 + metadata store sync
 //  7. Source cleanup — old shard 의 split-out 키 범위 데이터 회수
 //
-// 본 CRD 는 *state machine 만 정의* — 실 step 구현은 internal/controller/
-// shardsplit/ + internal/router/ 에 위임 (P-D §D.9.* 후속).
+// 본 CRD 는 state machine API를 정의하고, 현재 부수효과는
+// internal/controller/shardsplitjob_*.go와 internal/router/에 구현되어 있다.
 
 // ShardSplitJobPhase 는 resharding state machine 의 현재 phase 이다.
 // +kubebuilder:validation:Enum=Pending;SnapshotWAL;Bootstrap;InitialCopy;CDCCatchup;Cutover;RoutingUpdate;Cleanup;Promote;Completed;Failed;Aborted
@@ -55,9 +55,10 @@ const (
 	ShardSplitDirectionMerge ShardSplitDirection = "merge"
 )
 
-// ShardSplitJobSpec 는 사용자 의도된 shard split/merge 작업이다.
-// +kubebuilder:validation:XValidation:rule="size(self.sources) > 0",message="sources must not be empty"
+// ShardSplitJobSpec 는 사용자 의도된 shard split 작업이다. merge 값은 향후 API
+// 호환성을 위해 예약되어 있지만 현재 controller가 모든 부수효과 전에 거부한다.
 // +kubebuilder:validation:XValidation:rule="size(self.targets) > 0",message="targets must not be empty"
+// +kubebuilder:validation:XValidation:rule="self == oldSelf",message="spec is immutable after creation"
 type ShardSplitJobSpec struct {
 	// Cluster 는 본 작업이 속한 PostgresCluster 의 이름 (동일 namespace).
 	// +kubebuilder:validation:Required
@@ -69,24 +70,27 @@ type ShardSplitJobSpec struct {
 	// +kubebuilder:validation:Pattern=`^[a-z][a-z0-9_]{0,62}$`
 	Keyspace string `json:"keyspace"`
 
-	// Direction 은 split 또는 merge 방향. 기본 split.
+	// Direction 은 향후 split 또는 merge 방향을 표현한다. 현재는 split만 구현되어
+	// controller가 merge를 부수효과 전에 거부한다. 기본 split.
 	// +kubebuilder:default=split
 	// +optional
 	Direction ShardSplitDirection `json:"direction,omitempty"`
 
-	// Sources 는 source shard ID 목록 (split: 1, merge: N).
+	// Sources 는 source shard ID 목록이다. 현재 split은 정확히 1개만 허용하며
+	// merge용 다중 source는 예약 상태다.
 	// +kubebuilder:validation:Required
 	// +kubebuilder:validation:MinItems=1
 	Sources []string `json:"sources"`
 
-	// Targets 는 target shard 정의 목록 (split: N, merge: 1).
+	// Targets 는 target shard 정의 목록이다. 현재 split은 1개 이상을 허용하며
+	// merge용 단일 target 의미는 예약 상태다.
 	// 각 target 은 자체 키 범위와 placement hint 를 갖는다.
 	// +kubebuilder:validation:Required
 	// +kubebuilder:validation:MinItems=1
 	Targets []ShardSplitTarget `json:"targets"`
 
-	// CutoverWindow 는 cutover phase 의 최대 write-block 시간이다 (예: "30s").
-	// 초과 시 자동 abort + rollback. 기본 60s.
+	// CutoverWindow 는 향후 최대 write-block 시간 enforcement를 위한 예약 필드이다.
+	// 현재 controller는 이 값을 측정하거나 자동 abort/rollback에 사용하지 않는다. 기본 60s.
 	// +kubebuilder:default="60s"
 	// +optional
 	CutoverWindow metav1.Duration `json:"cutoverWindow,omitempty"`
@@ -97,8 +101,9 @@ type ShardSplitJobSpec struct {
 	// +optional
 	CDCMaxLag int64 `json:"cdcMaxLag,omitempty"`
 
-	// AllowForwardOnly 는 true 면 cutover 이후 rollback 불가 (D.9.10).
-	// 기본 false — rollback 가능 (역방향 logical replication 유지).
+	// AllowForwardOnly 는 향후 forward-only cutover 의도를 위한 필드이다.
+	// 현재 controller는 true를 routing 전에 거부한다. false는 진행을 허용하지만
+	// 역방향 logical replication이나 자동 rollback을 보장하지 않는다.
 	// +kubebuilder:default=false
 	// +optional
 	AllowForwardOnly bool `json:"allowForwardOnly,omitempty"`
@@ -112,7 +117,7 @@ type ShardSplitJobSpec struct {
 	Online bool `json:"online,omitempty"`
 }
 
-// ShardSplitTarget 는 split/merge 의 target shard 1건 정의.
+// ShardSplitTarget 는 split target shard 1건을 정의한다.
 type ShardSplitTarget struct {
 	// ShardID 는 target shard 의 식별자 (ShardRange.spec.ranges[].shard 와 동일).
 	//
@@ -172,7 +177,8 @@ type ShardSplitJobStatus struct {
 	// +optional
 	CutoverStartedAt *metav1.Time `json:"cutoverStartedAt,omitempty"`
 
-	// SnapshotLSN 은 SnapshotWAL phase 에서 확정된 source 시점 LSN.
+	// SnapshotLSN 은 향후 snapshot 기준점 기록을 위한 예약 필드이다.
+	// 현재 SnapshotWAL 은 no-op 이므로 컨트롤러가 이 값을 채우지 않는다.
 	// +optional
 	SnapshotLSN string `json:"snapshotLSN,omitempty"`
 

charts/postgres-operator/Chart.yaml

@@ -101,6 +101,16 @@ annotations:
       name: postgresusers.postgres.keiailab.io
       displayName: PostgresUser
       description: ready primary Pod 의 psql 로 PostgreSQL role flags, membership, password, validUntil 을 적용한다
+    - kind: ShardRange
+      version: v1alpha1
+      name: shardranges.postgres.keiailab.io
+      displayName: ShardRange
+      description: keyspace 의 vindex 와 shard range routing topology 를 선언한다
+    - kind: ShardSplitJob
+      version: v1alpha1
+      name: shardsplitjobs.postgres.keiailab.io
+      displayName: ShardSplitJob
+      description: guarded online 또는 offline shard split workflow 를 선언한다
   artifacthub.io/crdsExamples: |
     - apiVersion: postgres.keiailab.io/v1alpha1
       kind: ImageCatalog
@@ -249,7 +259,7 @@ annotations:
       image: ghcr.io/keiailab/postgres-operator:0.4.0-beta.8
   artifacthub.io/changes: |
     - kind: changed
-      description: "Add opt-in ExternalSecret rendering for PostgresUser, Pooler, and external replica-source credentials while keeping operator appVersion/image at 0.4.0-beta.1."
+      description: "Package operator appVersion/image 0.4.0-beta.8 and publish all 10 CRDs, including ShardRange and ShardSplitJob."
 
 dependencies:
   - name: keiailab-commons

charts/postgres-operator/crds/postgres.keiailab.io_shardsplitjobs.yaml

@@ -63,13 +63,16 @@ spec:
           metadata:
             type: object
           spec:
-            description: ShardSplitJobSpec 는 사용자 의도된 shard split/merge 작업이다.
+            description: |-
+              ShardSplitJobSpec 는 사용자 의도된 shard split 작업이다. merge 값은 향후 API
+              호환성을 위해 예약되어 있지만 현재 controller가 모든 부수효과 전에 거부한다.
             properties:
               allowForwardOnly:
                 default: false
                 description: |-
-                  AllowForwardOnly 는 true 면 cutover 이후 rollback 불가 (D.9.10).
-                  기본 false — rollback 가능 (역방향 logical replication 유지).
+                  AllowForwardOnly 는 향후 forward-only cutover 의도를 위한 필드이다.
+                  현재 controller는 true를 routing 전에 거부한다. false는 진행을 허용하지만
+                  역방향 logical replication이나 자동 rollback을 보장하지 않는다.
                 type: boolean
               cdcMaxLag:
                 default: 16777216
@@ -85,12 +88,14 @@ spec:
               cutoverWindow:
                 default: 60s
                 description: |-
-                  CutoverWindow 는 cutover phase 의 최대 write-block 시간이다 (예: "30s").
-                  초과 시 자동 abort + rollback. 기본 60s.
+                  CutoverWindow 는 향후 최대 write-block 시간 enforcement를 위한 예약 필드이다.
+                  현재 controller는 이 값을 측정하거나 자동 abort/rollback에 사용하지 않는다. 기본 60s.
                 type: string
               direction:
                 default: split
-                description: Direction 은 split 또는 merge 방향. 기본 split.
+                description: |-
+                  Direction 은 향후 split 또는 merge 방향을 표현한다. 현재는 split만 구현되어
+                  controller가 merge를 부수효과 전에 거부한다. 기본 split.
                 enum:
                 - split
                 - merge
@@ -108,17 +113,20 @@ spec:
                   범위복사 + cutover write-block) — 동시 쓰기 없는 유지보수 창에 단순·빠름.
                 type: boolean
               sources:
-                description: 'Sources 는 source shard ID 목록 (split: 1, merge: N).'
+                description: |-
+                  Sources 는 source shard ID 목록이다. 현재 split은 정확히 1개만 허용하며
+                  merge용 다중 source는 예약 상태다.
                 items:
                   type: string
                 minItems: 1
                 type: array
               targets:
                 description: |-
-                  Targets 는 target shard 정의 목록 (split: N, merge: 1).
+                  Targets 는 target shard 정의 목록이다. 현재 split은 1개 이상을 허용하며
+                  merge용 단일 target 의미는 예약 상태다.
                   각 target 은 자체 키 범위와 placement hint 를 갖는다.
                 items:
-                  description: ShardSplitTarget 는 split/merge 의 target shard 1건 정의.
+                  description: ShardSplitTarget 는 split target shard 1건을 정의한다.
                   properties:
                     placement:
                       description: Placement 는 target shard 의 nodeAffinity / topology
@@ -181,10 +189,10 @@ spec:
             - targets
             type: object
             x-kubernetes-validations:
-            - message: sources must not be empty
-              rule: size(self.sources) > 0
             - message: targets must not be empty
               rule: size(self.targets) > 0
+            - message: spec is immutable after creation
+              rule: self == oldSelf
           status:
             description: ShardSplitJobStatus 는 reconciler 가 관찰한 7-step state machine
               상태.
@@ -286,7 +294,7 @@ spec:
                 - Aborted
                 type: string
               snapshotLSN:
-                description: SnapshotLSN 은 SnapshotWAL phase 에서 확정된 source 시점 LSN.
+                description: SnapshotLSN 은 향후 snapshot 기준점 기록을 위한 예약 필드이다. 현재 SnapshotWAL 은 no-op 이므로 컨트롤러가 이 값을 채우지 않는다.
                 type: string
               startedAt:
                 description: StartedAt 은 본 작업이 Pending → SnapshotWAL 으로 진입한 시각.