feat: HA/PITR 안정화 + 분산 SQL 라우터 + 온라인 resharding

.devcontainer/devcontainer-lock.json

@@ -0,0 +1,19 @@
+{
+  "features": {
+    "ghcr.io/devcontainers/features/common-utils:2": {
+      "version": "2.5.9",
+      "resolved": "ghcr.io/devcontainers/features/common-utils@sha256:cb0c4d3c276f157eed17935747e364178d75fee17f55c4e129966f64633deb3a",
+      "integrity": "sha256:cb0c4d3c276f157eed17935747e364178d75fee17f55c4e129966f64633deb3a"
+    },
+    "ghcr.io/devcontainers/features/docker-in-docker:2": {
+      "version": "2.17.0",
+      "resolved": "ghcr.io/devcontainers/features/docker-in-docker@sha256:25b9f05705ffba7dbe503230ac76081419306f8c8bc88e0ce78c4ecd99a0c78c",
+      "integrity": "sha256:25b9f05705ffba7dbe503230ac76081419306f8c8bc88e0ce78c4ecd99a0c78c"
+    },
+    "ghcr.io/devcontainers/features/git:1": {
+      "version": "1.3.5",
+      "resolved": "ghcr.io/devcontainers/features/git@sha256:27905dc196c01f77d6ba8709cb82eeaf330b3b108772e2f02d1cd0d826de1251",
+      "integrity": "sha256:27905dc196c01f77d6ba8709cb82eeaf330b3b108772e2f02d1cd0d826de1251"
+    }
+  }
+}

.devcontainer/devcontainer.json

@@ -1,6 +1,6 @@
 {
   "name": "Kubebuilder DevContainer",
-  "image": "golang:1.25",
+  "image": "golang:1.26",
   "features": {
     "ghcr.io/devcontainers/features/docker-in-docker:2": {
       "moby": false,

.gitattributes

@@ -0,0 +1,33 @@
+# 모든 텍스트 파일의 기본 라인 엔딩: LF (Unix)
+* text=auto eol=lf
+
+# 명시적으로 LF 강제 (스크립트 실행 파일)
+*.sh   text eol=lf
+*.bash text eol=lf
+
+# Go 소스 코드
+*.go   text eol=lf
+
+# 설정 / 마크다운 / 기타 텍스트
+*.md        text eol=lf
+*.json      text eol=lf
+*.yaml      text eol=lf
+*.yml       text eol=lf
+Makefile    text eol=lf
+Dockerfile* text eol=lf
+*.toml      text eol=lf
+*.mod       text eol=lf
+*.sum       text eol=lf
+*.txt       text eol=lf
+*.env       text eol=lf
+
+# 바이너리 파일 (라인 엔딩 변환 금지)
+*.png  binary
+*.jpg  binary
+*.jpeg binary
+*.gif  binary
+*.ico  binary
+*.zip  binary
+*.tar  binary
+*.gz   binary
+*.pdf  binary

.gitignore

@@ -9,6 +9,7 @@ Dockerfile.cross
 
 # Test binary, built with `go test -c`
 *.test
+*.test.exe
 
 # Output of the go coverage tool, specifically when used with LiteIDE
 *.out

AGENTS.md

@@ -88,3 +88,14 @@ make bundle VERSION=X.Y.Z  # OLM bundle 재생성
   Apache 헤더 발견 시 보고 후 교체 (pg-router 정리 선례).
 - 의존성 갱신: `renovate.json` (mongodb-operator 와 동일 기준 — k8s.io 그룹 / major 분리).
 - CI (`.gitlab-ci.yml`): golang 이미지 버전은 `go.mod` 의 go directive 와 정합 유지.
+
+### 문서 작성 (`docs/`)
+
+`docs/` 의 한국어 분석/작업 문서는 [`docs/DOCS_MAP.ko.md`](docs/DOCS_MAP.ko.md) 의 지침을 **구속력 있는 규칙**으로 따른다. Claude / Codex / Cursor 등 어떤 에이전트나 작업자라도 `docs/` 를 편집할 때 동일하게 준수한다.
+
+- **주제별 SSOT 준수**: 같은 사실(검증 수치·CRLF 조치·E2E 명령 등)을 여러 문서에 복제하지 않는다. 본문은 DOCS_MAP §3 이 지정한 출처 1곳에만 두고, 나머지는 링크한다.
+- **계층 유지**: 요약은 `PROJECT_OVERVIEW`, 상세 동작은 `FEATURE_DEEP_DIVE`. 개요 문서에 상세를 복붙하지 않는다.
+- **보강 위치**: 새 내용을 어디에 쓸지는 DOCS_MAP §5 를 따른다(기능→OVERVIEW/DEEP_DIVE, 테스트→TEST_ANALYSIS/E2E_REPORT, 작업→WORK_HANDOFF+메모리, 환경→dev-setup).
+- **지도 갱신 의무**: 새 분석/작업 문서를 추가하면 DOCS_MAP §1 표와 §2 관계도에 한 줄 추가한다.
+- 미완 여부·현재 상태는 문서 단정 대신 코드/`git log` 로 확인한다(과거 "미구현" 오진 선례).
+- **용어집 유지**: 각 분석 문서는 **마지막 장에 "용어집" 절**을 둔다. 용어 정의 SSOT 는 [`docs/GLOSSARY.ko.md`](docs/GLOSSARY.ko.md) — 각 문서는 등장 용어만 **그 정의를 그대로 발췌**(어디서 보든 동일) + 전체 링크. 새 용어는 GLOSSARY 에 먼저 추가하고 발췌 측을 맞춘다.

Dockerfile.reshard

@@ -0,0 +1,23 @@
+# Build the reshard-copy-poc binary — the online-resharding InitialCopy data mover
+# (ShardSplitJob InitialCopy phase runs this as a K8s Job; RFC 0003 / ROADMAP G4).
+# Separate image from the operator manager so the copy Job pulls a minimal surface.
+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 . .
+
+# CGO disabled → static distroless binary (lib/pq is pure Go).
+RUN CGO_ENABLED=0 GOOS=${TARGETOS:-linux} GOARCH=${TARGETARCH} go build -a -o reshard-copy ./cmd/reshard-copy-poc
+
+FROM gcr.io/distroless/static:nonroot@sha256:e3f945647ffb95b5839c07038d64f9811adf17308b9121d8a2b87b6a22a80a39
+WORKDIR /
+COPY --from=builder /workspace/reshard-copy .
+USER 65532:65532
+
+ENTRYPOINT ["/reshard-copy"]

Dockerfile.router

@@ -0,0 +1,22 @@
+# Build the pg-router binary (the stateless query router — RFC 0004 / ROADMAP G3).
+# Separate image from the operator manager so the router can scale independently.
+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 . .
+
+# CGO disabled → static distroless binary (zero external runtime, minimal surface).
+RUN CGO_ENABLED=0 GOOS=${TARGETOS:-linux} GOARCH=${TARGETARCH} go build -a -o pg-router ./cmd/pg-router
+
+FROM gcr.io/distroless/static:nonroot@sha256:e3f945647ffb95b5839c07038d64f9811adf17308b9121d8a2b87b6a22a80a39
+WORKDIR /
+COPY --from=builder /workspace/pg-router .
+USER 65532:65532
+
+ENTRYPOINT ["/pg-router"]

Makefile

@@ -124,11 +124,23 @@ setup-test-e2e: ## Set up a Kind cluster for e2e tests if it does not exist
 # 빈 값(디폴트)은 전체 e2e 실행. CI 매트릭스가 본 변수를 채워 Pillar 단위 통과율을
 # 추적한다(.github/workflows/ci.yml의 e2e job).
 PILLAR ?=
+KEEP ?=
+E2E_LABEL_FILTER = $(if $(PILLAR),-ginkgo.label-filter=$(PILLAR),)
+
+define run-e2e-and-cleanup
+	@status=0; \
+	KIND=$(KIND) KIND_CLUSTER=$(KIND_CLUSTER) $(1) || status=$$?; \
+	if [ "$(KEEP)" = "1" ]; then \
+		echo "KEEP=1 set; preserving Kind cluster '$(KIND_CLUSTER)'."; \
+	else \
+		$(MAKE) cleanup-test-e2e || { cleanup_status=$$?; if [ $$status -eq 0 ]; then status=$$cleanup_status; fi; }; \
+	fi; \
+	exit $$status
+endef
 
 .PHONY: test-e2e
 test-e2e: setup-test-e2e manifests generate fmt vet ## Run the e2e tests. Expected an isolated environment using Kind. Use PILLAR=p1 to narrow to one Pillar.
-	KIND=$(KIND) KIND_CLUSTER=$(KIND_CLUSTER) PILLAR=$(PILLAR) go test -tags=e2e ./test/e2e/ -v -ginkgo.v $(if $(PILLAR),-ginkgo.label-filter=$(PILLAR),)
-	$(MAKE) cleanup-test-e2e
+	$(call run-e2e-and-cleanup,PILLAR=$(PILLAR) go test -tags=e2e ./test/e2e/ -v -ginkgo.v $(E2E_LABEL_FILTER))
 
 .PHONY: cleanup-test-e2e
 cleanup-test-e2e: ## Tear down the Kind cluster used for e2e tests
@@ -140,13 +152,13 @@ cleanup-test-e2e: ## Tear down the Kind cluster used for e2e tests
 # KEEP=1 시 cleanup skip (로컬 디버그).
 .PHONY: test-e2e-pg
 test-e2e-pg: setup-test-e2e manifests generate fmt vet ## Run RFC 0006 R1+R2 회귀 e2e (kind 의존, p1 라벨).
-	KIND=$(KIND) KIND_CLUSTER=$(KIND_CLUSTER) go test -tags=e2e ./test/e2e/ -timeout 30m -v -ginkgo.v -ginkgo.label-filter=p1
+	$(call run-e2e-and-cleanup,go test -tags=e2e ./test/e2e/ -timeout 30m -v -ginkgo.v -ginkgo.label-filter=p1)
 
 # RFC 0006 R3 회귀 — primary kill → 새 primary auto-promote (RTO < 30s) → 옛 primary standby rejoin.
 # replicas=1 (Pod 2 개) failover 라이프사이클. KEEP=1 시 cleanup skip.
 .PHONY: test-e2e-failover
 test-e2e-failover: setup-test-e2e manifests generate fmt vet ## RFC 0006 R3 회귀 e2e (kind 의존, p2 라벨, replicas=1 primary kill).
-	KIND=$(KIND) KIND_CLUSTER=$(KIND_CLUSTER) go test -tags=e2e ./test/e2e/ -timeout 30m -v -ginkgo.v -ginkgo.label-filter=p2
+	$(call run-e2e-and-cleanup,go test -tags=e2e ./test/e2e/ -timeout 30m -v -ginkgo.v -ginkgo.label-filter=p2)
 
 .PHONY: lint
 lint: golangci-lint ## Run golangci-lint linter

api/v1alpha1/shardrange_types.go

@@ -100,6 +100,17 @@ type ShardRangeSpec struct {
 	// +kubebuilder:validation:MinItems=1
 	// +kubebuilder:validation:MaxItems=1024
 	Ranges []ShardRangeEntry `json:"ranges"`
+
+	// ReferenceTables은 이 키스페이스에서 *모든 샤드에 복제*되는 reference 테이블 목록이다.
+	// 이 테이블만 참조하는 쿼리는 샤딩 키 없이 임의 샤드로 라우팅된다 (분산 조인 우회).
+	// +optional
+	ReferenceTables []string `json:"referenceTables,omitempty"`
+
+	// WriteBlocked은 true 면 라우터가 이 키스페이스로의 *쓰기*를 일시 거부한다(읽기는 통과).
+	// online resharding 의 Cutover 동안 라우팅 전환 중 쓰기 유실을 막는 write-block 신호로
+	// ShardSplitJob 컨트롤러가 설정/해제한다(Cutover=true, RoutingUpdate 완료 시 false).
+	// +optional
+	WriteBlocked bool `json:"writeBlocked,omitempty"`
 }
 
 // ShardRangeStatus은 reconciler 가 관찰한 ShardRange 상태이다.

api/v1alpha1/shardsplitjob_types.go

@@ -25,8 +25,8 @@ import (
 // 본 CRD 는 *state machine 만 정의* — 실 step 구현은 internal/controller/
 // shardsplit/ + internal/router/ 에 위임 (P-D §D.9.* 후속).
 
-// ShardSplitJobPhase 는 7-step state machine 의 현재 phase 이다.
-// +kubebuilder:validation:Enum=Pending;SnapshotWAL;Bootstrap;InitialCopy;CDCCatchup;Cutover;RoutingUpdate;Cleanup;Completed;Failed;Aborted
+// ShardSplitJobPhase 는 resharding state machine 의 현재 phase 이다.
+// +kubebuilder:validation:Enum=Pending;SnapshotWAL;Bootstrap;InitialCopy;CDCCatchup;Cutover;RoutingUpdate;Cleanup;Promote;Completed;Failed;Aborted
 type ShardSplitJobPhase string
 
 const (
@@ -38,6 +38,7 @@ const (
 	ShardSplitPhaseCutover       ShardSplitJobPhase = "Cutover"
 	ShardSplitPhaseRoutingUpdate ShardSplitJobPhase = "RoutingUpdate"
 	ShardSplitPhaseCleanup       ShardSplitJobPhase = "Cleanup"
+	ShardSplitPhasePromote       ShardSplitJobPhase = "Promote"
 	ShardSplitPhaseCompleted     ShardSplitJobPhase = "Completed"
 	ShardSplitPhaseFailed        ShardSplitJobPhase = "Failed"
 	ShardSplitPhaseAborted       ShardSplitJobPhase = "Aborted"
@@ -101,6 +102,14 @@ type ShardSplitJobSpec struct {
 	// +kubebuilder:default=false
 	// +optional
 	AllowForwardOnly bool `json:"allowForwardOnly,omitempty"`
+
+	// Online 은 true 면 CDC(논리복제) 기반 *무중단* 이동을 쓴다 — InitialCopy 의 정적 bulk
+	// 복사 대신 CDCCatchup phase 가 subscription(copy_data=true)으로 라이브 쓰기를 따라잡고,
+	// write-block 은 최종 drain 구간만 짧게 건다. false(기본)는 offline 모드(InitialCopy
+	// 범위복사 + cutover write-block) — 동시 쓰기 없는 유지보수 창에 단순·빠름.
+	// +kubebuilder:default=false
+	// +optional
+	Online bool `json:"online,omitempty"`
 }
 
 // ShardSplitTarget 는 split/merge 의 target shard 1건 정의.

api/v1alpha1/shardsplitjob_types_test.go

@@ -13,17 +13,17 @@ import (
 )
 
 func TestShardSplitJob(t *testing.T) {
-	t.Run("Phase 전체 11 값 stringify", func(t *testing.T) {
+	t.Run("Phase 전체 12 값 stringify", func(t *testing.T) {
 		phases := []ShardSplitJobPhase{
 			ShardSplitPhasePending, ShardSplitPhaseSnapshotWAL,
 			ShardSplitPhaseBootstrap, ShardSplitPhaseInitialCopy,
 			ShardSplitPhaseCDCCatchup, ShardSplitPhaseCutover,
 			ShardSplitPhaseRoutingUpdate, ShardSplitPhaseCleanup,
-			ShardSplitPhaseCompleted, ShardSplitPhaseFailed,
+			ShardSplitPhasePromote, ShardSplitPhaseCompleted, ShardSplitPhaseFailed,
 			ShardSplitPhaseAborted,
 		}
-		if len(phases) != 11 {
-			t.Fatalf("phase count want=11 got=%d", len(phases))
+		if len(phases) != 12 {
+			t.Fatalf("phase count want=12 got=%d", len(phases))
 		}
 		for _, p := range phases {
 			if string(p) == "" {

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

@@ -99,6 +99,13 @@ spec:
                 maxItems: 1024
                 minItems: 1
                 type: array
+              referenceTables:
+                description: |-
+                  ReferenceTables은 이 키스페이스에서 *모든 샤드에 복제*되는 reference 테이블 목록이다.
+                  이 테이블만 참조하는 쿼리는 샤딩 키 없이 임의 샤드로 라우팅된다 (분산 조인 우회).
+                items:
+                  type: string
+                type: array
               vindex:
                 description: Vindex은 키 → 샤드 매핑 함수 정의이다.
                 properties:
@@ -145,6 +152,12 @@ spec:
                 required:
                 - type
                 type: object
+              writeBlocked:
+                description: |-
+                  WriteBlocked은 true 면 라우터가 이 키스페이스로의 *쓰기*를 일시 거부한다(읽기는 통과).
+                  online resharding 의 Cutover 동안 라우팅 전환 중 쓰기 유실을 막는 write-block 신호로
+                  ShardSplitJob 컨트롤러가 설정/해제한다(Cutover=true, RoutingUpdate 완료 시 false).
+                type: boolean
             required:
             - cluster
             - keyspace

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

@@ -99,6 +99,14 @@ spec:
                 description: Keyspace 는 ShardRange 의 keyspace 식별자.
                 pattern: ^[a-z][a-z0-9_]{0,62}$
                 type: string
+              online:
+                default: false
+                description: |-
+                  Online 은 true 면 CDC(논리복제) 기반 *무중단* 이동을 쓴다 — InitialCopy 의 정적 bulk
+                  복사 대신 CDCCatchup phase 가 subscription(copy_data=true)으로 라이브 쓰기를 따라잡고,
+                  write-block 은 최종 drain 구간만 짧게 건다. false(기본)는 offline 모드(InitialCopy
+                  범위복사 + cutover write-block) — 동시 쓰기 없는 유지보수 창에 단순·빠름.
+                type: boolean
               sources:
                 description: 'Sources 는 source shard ID 목록 (split: 1, merge: N).'
                 items:
@@ -272,6 +280,7 @@ spec:
                 - Cutover
                 - RoutingUpdate
                 - Cleanup
+                - Promote
                 - Completed
                 - Failed
                 - Aborted

cmd/instance/main.go

@@ -157,7 +157,11 @@ func main() {
 	dataDir := envOrDie("POSTGRES_DATA_DIR")
 	binDir := envOrDie("POSTGRES_BIN_DIR")
 	primaryEndpoint := os.Getenv("PRIMARY_ENDPOINT")
-	endpoint := instanceEndpoint(podName, cluster, int32(shardOrdinal), namespace)
+	serviceName := os.Getenv("POSTGRES_SERVICE_NAME")
+	if serviceName == "" {
+		serviceName = fmt.Sprintf("%s-shard-%d-headless", cluster, shardOrdinal)
+	}
+	endpoint := instanceEndpoint(podName, serviceName, namespace)
 	restartedPrimaryAsStandby, err := prepareRestartedPrimaryAsStandby(
 		dataDir, primaryEndpoint, binDir, podName, memberCount, logger,
 	)
@@ -297,7 +301,7 @@ func main() {
 	}()
 	logger.Info("Election started", "identity", elect.Identity(), "lease", leaseName)
 
-	startStatusReporterIfPossible(ctx, clientset, namespace, podName, cluster, int32(shardOrdinal), dataDir, elect, sup, logger)
+	startStatusReporterIfPossible(ctx, clientset, namespace, podName, endpoint, dataDir, elect, sup, logger)
 
 	select {
 	case <-ctx.Done():
@@ -519,9 +523,8 @@ func patchRejoinFailureStatus(
 	return patchPodAnnotation(ctx, clientset, namespace, podName, st)
 }
 
-func instanceEndpoint(podName, cluster string, shardOrdinal int32, namespace string) string {
-	return fmt.Sprintf("%s.%s-shard-%d-headless.%s.svc.cluster.local:5432",
-		podName, cluster, shardOrdinal, namespace)
+func instanceEndpoint(podName, serviceName, namespace string) string {
+	return fmt.Sprintf("%s.%s.%s.svc.cluster.local:5432", podName, serviceName, namespace)
 }
 
 func delayElectionForRestartedPrimary(ctx context.Context, delay time.Duration, podName string, logger *slog.Logger) {
@@ -542,8 +545,7 @@ func delayElectionForRestartedPrimary(ctx context.Context, delay time.Duration,
 func startStatusReporterIfPossible(
 	ctx context.Context,
 	clientset kubernetes.Interface,
-	namespace, podName, cluster string,
-	shardOrdinal int32,
+	namespace, podName, endpoint string,
 	dataDir string,
 	elect election.Election,
 	sup supervise.Supervisor,
@@ -552,7 +554,6 @@ func startStatusReporterIfPossible(
 	if clientset == nil {
 		return
 	}
-	endpoint := instanceEndpoint(podName, cluster, shardOrdinal, namespace)
 	go runStatusReporter(ctx, clientset, namespace, podName, endpoint, dataDir, elect, sup, logger)
 }
 

cmd/instance/main_test.go

@@ -40,6 +40,14 @@ func TestParsePodOrdinalOrDie_StatefulSetName(t *testing.T) {
 	}
 }
 
+func TestInstanceEndpoint_UsesProvidedServiceName(t *testing.T) {
+	got := instanceEndpoint("orders-rsd-t1-0", "orders-rsd-t1-headless", "ns1")
+	want := "orders-rsd-t1-0.orders-rsd-t1-headless.ns1.svc.cluster.local:5432"
+	if got != want {
+		t.Fatalf("endpoint = %q, want %q", got, want)
+	}
+}
+
 func TestPrepareRestartedPrimaryAsStandby_UsesCurrentPrimaryEndpointForAnyOrdinal(t *testing.T) {
 	dir := t.TempDir()
 	marker := filepath.Join(dir, supervise.RestartPrimaryAsStandbyMarker)