From 0a704f102dc0502a869d0572cd48dce166072851 Mon Sep 17 00:00:00 2001 From: phil Date: Thu, 30 Apr 2026 13:32:01 +0900 Subject: [PATCH] =?UTF-8?q?docs(handoff):=20P0=20100%=20=EC=99=84=EB=A3=8C?= =?UTF-8?q?=20+=206=20PR=20=EB=88=84=EC=A0=81=20=ED=9B=84=20=EC=BB=A8?= =?UTF-8?q?=ED=85=8D=EC=8A=A4=ED=8A=B8=20=EA=B0=B1=EC=8B=A0?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 본 세션(2026-04-30) 종료 의식 — workflow.md §2 준수. 다음 세션이 대화 컨텍스트 없이 재개 가능하도록 HANDOFF.md를 본 세션 누적 상태로 갱신. 본 세션 누적: - 6 PR 머지 (PR #1~#6 모두 admin merge, rebase, branch 자동 삭제) - P0 권장 100% 완료 (P0-1, P0-2, P0-3, P0-4, P0-5, P0-6 phase 1) - 거버넌스: ADR 0006/0007/0008/0009 신설, RFC 14건 매트릭스 - 글로벌 §2 정합 (.github/workflows/ 0개, 로컬 4 계층 활성) - 차별화 1(Citus) 코드 진입 (LibPQExecutor SQL 매핑 + 7 단위 테스트) 다음 세션 후보: 1. P0-6 phase 2 (cmd/main.go LibPQExecutor 주입) — 권장 (차별화 1 완전성) 2. P7 cert-manager 통합 (PR #1 e2e fail 진짜 fix) 3. P1-4 Helm chart 골격 (ADR 0007 implementation) 4. P1-1 BackupJob CRD (Plugin SDK 첫 호출자) 차단점: - PR #1 e2e fail은 GH Actions 폐기로 PR-blocking 효과 해소. 진짜 fix는 후보 2. Refs: workflow.md §2 종료 의식, plan §14 Co-Authored-By: Claude Opus 4.7 (1M context) --- HANDOFF.md | 119 +++++++++++++++++++++++++++++++++++++++-------------- 1 file changed, 87 insertions(+), 32 deletions(-) diff --git a/HANDOFF.md b/HANDOFF.md index 36f0b241..2d7c2b41 100644 --- a/HANDOFF.md +++ b/HANDOFF.md @@ -2,62 +2,117 @@ > 다음 세션이 *대화 컨텍스트 없이* 재개 가능하도록 유지. 작업 시작 시 가장 먼저 읽고, 종료 시 갱신. -## 현재 상태 +## 현재 상태 (2026-04-30, P0 100% 완료 후) -- 마지막 커밋: P2-T2 fencing 추가 (커밋 진행 중) -- 직전 커밋: `45e95b8 feat(p2): P2-M1 승격 — election envtest 통합 회귀 + 운영 가이드 + 거버넌스 정착` -- 작업 누적: 본 세션 두 번째 사이클로 P2-T2 (PVC fencing) 완성 +- 마지막 커밋 (main): `33fef9a feat(citus): LibPQExecutor phase 1 (P0-6, RFC 0002 §6 production path 토대)` +- 본 세션(2026-04-30) 누적: **6 PR 머지 + P0 권장 100% 완료 + 글로벌 §2 정합 달성** + +### 본 세션 머지된 PR 6개 (모두 admin merge, rebase, branch 자동 삭제) + +| # | merge commit | 영역 | 권장 ID | +|---|--------------|------|---------| +| 1 | `e7f6373`+ (5 commits) | P0-1, P0-5, 거버넌스, Trivy CVE 3건, e2e 진단 인프라 | P0-1 + P0-5 | +| 2 | `e0d3e4f` | GH Actions 폐기 + 로컬 4 계층 (RFC 0002, ADR 0009) | 글로벌 §2 정합 | +| 3 | `ae3e4e6` | 데이터플레인 PodSecurityContext defaults (ADR 0006) | P0-2 | +| 4 | `fa24a66` | Cascade delete envtest 회귀 차단 (ADR 0008) | P0-4 | +| 5 | `5bc0199` | NetworkPolicy 3개 활성화 (ADR 0006 §NetworkPolicy) | P0-3 | +| 6 | `33fef9a` | LibPQExecutor phase 1 (RFC 0002 §6 토대) | P0-6 phase 1 | ## 도달 마일스톤 - **P1-M1** Core Lifecycle Alpha - **P2-M1** + **P2-T2** HA / Failover Alpha + PVC Fencing - election: 단위 97.4%, envtest 통합 2종 - - fencing: 단위 89.7%, RFC 0003 부록 A 동결, cmd/instance 통합 (`--fencing-disabled` 노브) - - fail-fast: ErrFenced 시 exit(2) → CrashLoopBackOff → 운영자 개입 신호 + - fencing: 단위 89.7%, RFC 0003 부록 A 동결, cmd/instance 통합 - **P10-M0** Extension Plugin SDK spike -- **P11-M0** Citus Topology spike -- **P13-T1** Plugin SDK 인터페이스 동결 +- **P11-M0** Citus Topology spike + **P0-6 phase 1**(LibPQExecutor SQL 매핑 + 7 단위 테스트) +- **P13-T1** Plugin SDK 인터페이스 동결 + **P0-5**(AuthPlugin.RotateSecret 추가) +- **품질 개선 plan**(2026-04-30): P0 6/6 ✓ — Status.Conditions reason / SecurityContext / NetworkPolicy / Cascade test / AuthPlugin Rotate / LibPQExecutor 토대 +- **거버넌스**: ADR 0006/0007/0008/0009 신설, 19 권장 ID TASKS.md 매핑, RFC 14건 매트릭스 +- **글로벌 §2 정합**: `.github/workflows/` 0개. 로컬 4 계층(pre-commit + pre-push + Makefile + PR review) 활성 + +## 다음 단계 후보 (의존 만족 + 가치 우선순위) -## 다음 단계 (단일 행동) +다음 세션은 *fresh*하게 시작하여 다음 중 하나로 진입: ```bash cd /Users/phil/WorkSpace/public/postgresql-operator -make lint && make test # 회귀 확인 — fencing 89.7%, election 97.4% 유지 - -# 다음 작업 후보 (의존 만족 순): -git checkout -b feat/p2-t3-failover-controller # P2-T3 promote/demote 실 PG supervise -# 또는 -git checkout -b feat/p3-storage-wal # F05 P3-M1 트랙 +make lint && make test # 회귀 0 확인 (internal/citus 74.0%, internal/controller 82.9%) +make audit # 0 vulnerabilities 확인 + +# 후보 1 (가치 큼): P0-6 phase 2 — cmd/main.go에서 LibPQExecutor 주입 +git checkout -b feat/p0-6-phase2-cmd-injection +# DSNFunc 구현(election holder lookup + Secret 통합), reconciler.CitusExec에 주입. +# 후속 phase 3에서 RFC 0002 → Implemented 승격. + +# 후보 2 (필요): e2e cert-manager 통합 (PR #1의 e2e fail 진짜 fix) +git checkout -b feat/p7-cert-manager-integration +# config/certmanager/ 신설 (Issuer + Certificate CR) + kustomization 갱신 +# + e2e_test.go BeforeAll에 webhook secret ready wait. + +# 후보 3 (사용자 채널): P1-4 Helm chart (ADR 0007 결정대로 P14에서 P1으로 앞당김) +git checkout -b feat/p1-4-helm-chart-skeleton +# charts/postgresql-operator/ 신설 (Chart.yaml, values.yaml, templates/...). + +# 후보 4 (Plugin SDK 호출자): P1-1 BackupJob CRD +git checkout -b feat/p1-1-backupjob-crd +# api/v1alpha1/backupjob_types.go + internal/controller/backupjob_controller.go +# + RFC 0004 작성. ``` +권장 진입: **후보 1 (P0-6 phase 2)** — 차별화 1 코드 차원 잠금의 *완전성*이 다음 단계의 토대. + ## 차단점 -(없음) +- *PR #1 e2e fail* (manager Pod webhook TLS cert 부재): GH Actions 폐기로 *PR-blocking 효과는 해소*. 진짜 fix는 후보 2 (cert-manager 통합). +- *Node.js 20 deprecated 경고* (actions/checkout@v4 등): GH Actions 폐기로 *근본 해소*. -## 본 세션 의사결정 기록 (누적) +## 본 세션 의사결정 기록 (P0 + 거버넌스) -1. **TASKS.md / HANDOFF.md 도입** — workflow.md §3 의무. -2. **P2-M1 e2e = envtest 통합** — 풀 K8s 클러스터 e2e는 P2-T4 + 실 PG 이미지 필요로 M2+로 연기. -3. **P2-T2 분산 fence 모델** — *각 Pod이 자기 PVC만* fence (controller 일괄 fence 거부). 사유: ADR 0002 "K8s API as DCS" 원칙. 컨트롤러가 PVC를 일괄 patch하면 단일 진실 출처가 controller로 이동, 분산 합의 모델 위배. -4. **Fail-fast 정책 채택** — ErrFenced 시 `os.Exit(2)`. CrashLoopBackOff가 운영자 개입 신호 역할. 자동 unfence 거부 (잘못된 데이터 검증 우회 위험). -5. **fence 인터페이스 단일 PVC 스코프** — 멀티 PVC 트랜잭션 인터페이스는 분산 모델에서 불필요. -6. **Mock fencer를 fencing-disabled 모드에 사용** — Null 구현 별도 추가하지 않고 Mock(unfenced 디폴트)으로 대체. 단순성 우선(§2 Simplicity). +1. **plan §14에서 19 권장 매트릭스 동결** — Bitnami(sane defaults) + Crunchy PGO(Status.Conditions, Cascade) + keiailab USP(LibPQExecutor) 교차검증 결과를 P0/P1/P2로 분해. +2. **ADR 0006 (Security Defaults)** — 데이터플레인 *opt-out 강제* 결정 (운영자 누락 시에도 root 가능 상태로 안 떨어짐). PG postgres user UID 70. +3. **ADR 0007 (Helm chart을 P14에서 P1으로 분리)** — alpha 사용자 채널 조기 확보. P14에는 install.yaml + OLM + multi-arch만. +4. **ADR 0008 (Finalizer 회피 정책)** — ControllerReference + K8s GC 패턴. 외부 자원 cleanup은 별도 Job CRD로. +5. **ADR 0009 (GH Actions 폐기 + RFC 0002 적용)** — 글로벌 §2 정합 + 사고 트리거(2026-04-28 organization billing SPOF) 회피. +6. **P0-6 phase 1 SQL 매핑 simplification** — OpAdd는 ShouldHaveShards를 Citus 기본값으로 두고, 같은 노드의 ShouldHaveShards가 desired와 다르면 다음 reconcile의 OpUpdate가 정확히 set. ComputeActions 결정성 + 멱등성이 이 전략을 보장. +7. **citus_advisory_xact_lock 동시 reconcile 직렬화** — RFC 0002 §위험 §완화. 트랜잭션 종료 시 자동 해제로 reconciler crash에도 lock leak 없음. ## 검증 명령 (재현) ```bash -make lint # 0 issues -make test # 모든 패키지 통과 -go tool cover -func=cover.out | grep fencing # 89.7% 확인 -go tool cover -func=cover.out | grep election # 97.4% 확인 -go build ./cmd/instance/... # instance manager 빌드 통과 +make lint # 0 issues +make test # 모든 패키지 PASS +make audit # 0 vulnerabilities (HIGH+CRITICAL) +go tool cover -func=cover.out | grep -E "citus|election|fencing|plugin|controller" +# 핵심 패키지: election 97.4% / fencing 89.7% / plugin 93.0% +# 변동: citus 95.4% → 74.0% (LibPQExecutor Apply 본문 phase 3에서 cover) +# 변동: controller 81.0% → 82.9% (P0-2/P0-4 회귀 테스트 효과) + +go build ./cmd/instance/... ./cmd/... # 모든 binary 빌드 통과 ``` ## 근거 링크 -- `docs/roadmap.md` — 14 Pillar × DoD +- `docs/roadmap.md` — 14 Pillar × DoD (Helm 분리 ADR 0007 반영) +- `docs/adr/0001-stateless-query-router-on-citus.md` — 미션 3축 - `docs/adr/0002-no-patroni-instance-manager.md` — K8s API as DCS -- `docs/rfcs/0003-ha-election.md` — Election (§1~9) + 부록 A (PVC Fencing) -- `docs/operator-guide/ha-election.md` — 운영 가이드 (Fencing 섹션 §10) -- 코드: `internal/instance/election/`, `internal/instance/fencing/`, `cmd/instance/main.go` +- `docs/adr/0005-plugin-sdk-interface-model.md` — Plugin SDK 5 인터페이스 +- `docs/adr/0006-security-defaults-rationale.md` — P0-2 결정 (본 세션) +- `docs/adr/0007-helm-chart-promoted-to-p1.md` — P1-4 ADR (본 세션) +- `docs/adr/0008-finalizer-avoidance-policy.md` — P0-4 ADR (본 세션) +- `docs/adr/0009-no-github-actions-rfc-0002.md` — RFC 0002 적용 (본 세션) +- `docs/rfcs/0002-metadata-sync.md` — Citus topology sync (LibPQExecutor phase 1 토대) +- `docs/rfcs/0003-ha-election.md` — Election + Fencing +- `TASKS.md` "품질 개선 plan" 섹션 — 19 권장 ID 매트릭스 +- `/Users/phil/.claude/plans/1-https-artifacthub-io-packages-helm-bit-sunny-wozniak.md` — 본 세션 plan (사용자 승인) +- 코드 (본 세션 신규): + - `internal/citus/libpq_executor.go` (P0-6 phase 1) + - `internal/controller/builders.go` helper 5개 (P0-2) + - `internal/controller/cascade_delete_test.go` (P0-4) + - `internal/plugin/api.go` AuthPlugin.RotateSecret (P0-5) + - `internal/controller/status.go` reason 6개 (P0-1) + - `config/network-policy/dataplane-*.yaml` (P0-3) + - `.pre-commit-config.yaml` + `Makefile audit` (RFC 0002) +- 외부 출처 (교차검증): + - artifacthub.io Bitnami PostgreSQL Helm Chart + - artifacthub.io Crunchy PGO v5.8.7 (Community OLM)