Skip to content

PROJECT_OVERVIEW.md

Latest commit

 

History

History
287 lines (239 loc) · 14.5 KB

PROJECT_OVERVIEW.md

File metadata and controls

287 lines (239 loc) · 14.5 KB
Raw

postgres-operator 프로젝트 개요

operator 버전: v0.4.0-beta.8 | Helm chart: 0.4.0-beta.9 | 라이선스: MIT | 언어: Go 1.26 | 프레임워크: Kubebuilder / controller-runtime

🔖 진행 중 작업을 이어받거나 재검증하려면 먼저 WORK_HANDOFF.ko.md를 보라 — 브랜치 chore/ha-pitr-e2e-consolidation의 커밋 구성·검증 결과·남은 라이브 E2E·재현 방법 정리.

1. 프로젝트 목적

postgres-operator는 Kubernetes 위에서 vanilla PostgreSQL 18+을 선언적으로 운영하기 위한 Kubernetes Operator다. 외부 fork 없이 upstream PostgreSQL 바이너리를 그대로 사용하기 때문에 기존 libpq/JDBC/asyncpg 드라이버와 완전히 호환된다.

단기 목표는 단일 클러스터 PostgreSQL(Primary + Replica) 운영 자동화이며, 장기 목표는 수평 샤딩 + 분산 SQL 레이어를 vanilla PostgreSQL 위에 구축하는 것이다.

[현재 beta]
  단일 클러스터: Primary + Replica, HA Failover, 백업, 커넥션 풀, 선언적 DB/역할

[현재 beta + 후속 로드맵]
  ShardRange CRD → pg-router 쿼리 라우터 → ShardSplitJob 구현
  후속: 범용 크로스 샤드 분산 트랜잭션

2. 기술 스택

항목 선택 이유
언어 Go 1.26 Kubernetes 생태계 표준
프레임워크 Kubebuilder + controller-runtime CRD 스캐폴딩 + reconcile 루프
PostgreSQL 17 / 18 (upstream 바이너리) fork 없음 = 완전 호환
백업 pgBackRest (기본), WAL-G, Barman (플러그인) 플러그인 교체 가능
커넥션 풀 PgBouncer 1.19+ CNPG 호환 surface
인증서 cert-manager (선택) TLS 자동 발급/갱신
모니터링 Prometheus Operator + Grafana ServiceMonitor / PrometheusRule
이미지 배포 ghcr.io/keiailab/postgres-operator GitHub Container Registry

3. 아키텍처 전체 구조

┌────────────────────────────────────────────────────────────┐
│  Kubernetes Cluster                                        │
│                                                            │
│  ┌──────────────────────────────────┐                      │
│  │  postgres-operator (manager Pod) │                      │
│  │                                  │                      │
│  │  ┌──────────────┐  ┌──────────┐ │                      │
│  │  │ Reconcilers  │  │ Webhooks │ │                      │
│  │  │ PostgresCluster│  │ Admission│ │                      │
│  │  │ BackupJob    │  │ Validate │ │                      │
│  │  │ Pooler       │  └──────────┘ │                      │
│  │  │ PostgresDB   │               │                      │
│  │  │ PostgresUser │  ┌──────────┐ │                      │
│  │  │ ScheduledBkp │  │ Plugin   │ │                      │
│  │  │ ShardSplitJob│  │ Registry │ │                      │
│  │  └──────────────┘  └──────────┘ │                      │
│  │                                  │                      │
│  │  ┌────────────────────────────┐  │                      │
│  │  │  HA Failover Lease         │  │                      │
│  │  │  (별도 leader election)    │  │                      │
│  │  └────────────────────────────┘  │                      │
│  └──────────────────────────────────┘                      │
│                                                            │
│  ┌────────────────────────────────────────────────────┐    │
│  │  PostgresCluster "my-cluster"                      │    │
│  │                                                    │    │
│  │  StatefulSet (shard-0)    StatefulSet (shard-N)    │    │
│  │  ┌──────────┐             ┌──────────┐             │    │
│  │  │ primary  │             │ primary  │             │    │
│  │  │ replica0 │   ...       │ replica0 │             │    │
│  │  └──────────┘             └──────────┘             │    │
│  │                                                    │    │
│  │  Pooler (PgBouncer)  ────→ rw endpoint             │    │
│  └────────────────────────────────────────────────────┘    │
└────────────────────────────────────────────────────────────┘

4. CRD 목록 (10종)

CRD 단축명 범위 역할
PostgresCluster pgc Namespace Primary + Replica 토폴로지 핵심 리소스
BackupJob bj Namespace 1회성 백업 / PITR 복원
ScheduledBackup — Namespace 크론 스케줄 백업 자동 생성
Pooler pool Namespace PgBouncer 커넥션 풀 레이어
PostgresDatabase pgdb Namespace DB / 스키마 / Extension / FDW 선언적 관리
PostgresUser pguser Namespace PostgreSQL 역할 / 패스워드 선언적 관리
ImageCatalog pgic Namespace 네임스페이스 범위 PostgreSQL 이미지 카탈로그
ClusterImageCatalog pgcic Cluster 클러스터 전체 공유 이미지 카탈로그
ShardRange shr Namespace 키스페이스의 샤드 범위와 라우팅 토폴로지
ShardSplitJob ssj Namespace single-source online/offline shard split 상태 머신

5. 컨트롤러 구조

모든 컨트롤러는 cmd/main.go에서 단일 controller-runtime Manager에 등록된다.

cmd/main.go
├── PostgresClusterReconciler   — 클러스터 라이프사이클 (StatefulSet/Service/ConfigMap 생성)
├── BackupJobReconciler         — 백업/복원 Job 실행
├── PostgresDatabaseReconciler  — SQL DDL 실행 (psql exec via pod)
├── PostgresUserReconciler      — SQL 역할 관리 (psql exec via pod)
├── ScheduledBackupReconciler   — 크론 기반 BackupJob 생성
├── ShardSplitJobReconciler     — 대상 생성·복사·CDC·cutover·cleanup·promotion 상태 머신
├── PoolerReconciler            — PgBouncer Deployment 관리
└── FailoverLease (Runnable)    — HA Failover 전용 Kubernetes Lease

6. Plugin 아키텍처

5종의 Plugin 인터페이스가 internal/plugin/api.go에 동결(freeze) 정의되어 있다.

BackupPlugin       — 백업 도구 추상화 (pgBackRest / WAL-G / Barman)
ExporterPlugin     — Prometheus exporter 사이드카
ExtensionPlugin    — PostgreSQL extension 라이프사이클
RouterPlugin       — QueryRouter 라우팅 정책
AuthPlugin         — 인증 메커니즘 (SCRAM / mTLS / OIDC)

현재 등록된 플러그인:

플러그인 타입 shared_preload 순서
pgaudit Extension 100
pgvector Extension 100
pgcron Extension 200
pgnodemx Extension 300
postgis Extension 300
setuser Extension 300
pgbackrest Backup —

7. 바이너리 구성

바이너리 위치 역할
manager cmd/main.go Operator 컨트롤 플레인 (본 문서 대상)
instance cmd/instance/ PostgreSQL Pod 내부 PID1 데이터플레인
pg-router cmd/pg-router/ PoC 수준 PG wire-protocol 라우터

8. 현재 상태 및 로드맵

현재 (v0.4.0-beta.8)

  • 단일 클러스터 운영: Primary + Replica, HA, 백업, 풀링, 모니터링 — beta 품질
  • PITR restore drill 완료 (2026-06-24 live 7 PASS), 자동 failover reconcile 연결·fencing·promotion 코드 완료
  • ShardRange 토폴로지 watch와 pg-router 배포, point routing·scatter-gather·failover-aware backend 구현
  • ShardSplitJob online/offline 상태 머신과 AutoSplit 관측·승인 게이트 구현; 초기 tablesync, range 보존, target status를 회귀 테스트로 보호

로드맵 (순서대로)

  1. HA 강화 — PITR drill(완료), chaos/node-loss failover live drill 재검증 (ADR-0027 shard-identity)
  2. pg-router와 reshard 경로의 장애 주입·확장성 검증
  3. Scatter-gather SQL 범위와 읽기 레플리카 오토스케일 확장
  4. 부하 기반 자동 분할/리밸런스 운영 정책 검증
  5. 크로스 샤드 분산 트랜잭션 및 JOIN

9. 디렉토리 구조

postgres-operator/
├── api/v1alpha1/            # CRD 타입 정의 (Go types)
│   ├── postgrescluster_types.go
│   ├── backupjob_types.go
│   ├── pooler_types.go
│   ├── postgresdatabase_types.go
│   ├── postgresuser_types.go
│   ├── scheduledbackup_types.go
│   ├── imagecatalog_types.go
│   ├── shardrange_types.go      # 라우터가 감시하는 샤드 토폴로지
│   └── shardsplitjob_types.go   # 구현된 split/merge 작업 API
│
├── internal/
│   ├── controller/          # Reconciler 구현체
│   │   ├── postgrescluster_controller.go
│   │   ├── backupjob_controller.go
│   │   ├── pooler_controller.go
│   │   ├── postgresdatabase_controller.go
│   │   ├── postgresuser_controller.go
│   │   ├── scheduledbackup_controller.go
│   │   ├── shardsplitjob_controller.go
│   │   └── failover/        # HA 자동 failover (detection/lease/promotion)
│   ├── instance/            # PostgreSQL Pod PID1 데이터플레인
│   │   ├── election/        # Primary lease election
│   │   ├── fencing/         # PVC fencing
│   │   ├── statusapi/       # HTTP status endpoint
│   │   └── supervise/       # Process supervisor
│   ├── plugin/              # Plugin SDK 인터페이스 + 구현체
│   │   ├── api.go           # 5종 인터페이스 동결 정의
│   │   ├── registry.go      # 플러그인 레지스트리
│   │   ├── backup/          # pgBackRest / WAL-G / Barman
│   │   └── extension/       # pgaudit / pgvector / pgcron / ...
│   ├── postgres/            # SQL DSL (grants 등)
│   ├── router/              # vindex shard 해석
│   └── webhook/v1alpha1/    # Admission webhook
│
├── cmd/
│   ├── main.go              # Manager 진입점
│   ├── instance/            # PID1 instance manager
│   └── pg-router/           # PoC 라우터
│
├── config/
│   ├── crd/bases/           # 자동 생성 CRD YAML (make manifests)
│   └── rbac/                # 자동 생성 RBAC (make manifests)
│
├── charts/postgres-operator/ # Helm 차트 (배포 대상)
├── docs/                    # 각종 문서 (ADR, RFC, runbook 등)
└── Makefile                 # gate = lint + test + audit + validate

10. 설치 및 빠른 시작

# Helm으로 Operator 설치
helm install postgres-operator ./charts/postgres-operator

# 단일 노드 클러스터 생성
kubectl apply -f - <<EOF
apiVersion: postgres.keiailab.io/v1alpha1
kind: PostgresCluster
metadata:
  name: quickstart
  namespace: default
spec:
  postgresVersion: "18"
  shards:
    initialCount: 1
    replicas: 1       # 1 primary + 1 replica
    storage:
      size: 10Gi
EOF

# Ready 대기
kubectl wait postgrescluster/quickstart --for=condition=Ready --timeout=5m

11. 관련 문서

문서 위치 설명
문서 지도 docs/DOCS_MAP.ko.md 분석/작업/환경 문서군의 입구·역할·SSOT·관계 (여기부터)
기능 심층 분석 docs/FEATURE_DEEP_DIVE.md 각 기능 상세 동작 분석
단위·통합 테스트 분석 docs/TEST_ANALYSIS.md 패키지별 커버리지·TC 상세 (테스트 수치 SSOT)
E2E 테스트 보고서 docs/E2E_TEST_REPORT.ko.md E2E 라이브 드릴 RCA 누적 로그
작업 인수인계 docs/WORK_HANDOFF.ko.md 현재 브랜치 커밋 구성·검증·남은 일·재현법
Dev Container 설정 docs/dev-setup-devcontainer.md Windows Dev Container 개발 환경 (권장)
WSL2 설정 docs/dev-setup-wsl.md Windows WSL2 개발 환경 (대안)
아키텍처 docs/ARCHITECTURE.md 설계 결정 및 트레이드오프
로드맵 docs/ROADMAP.md 단계별 개발 계획
ADR 인덱스 docs/kb/adr/INDEX.md Architecture Decision Records
RFC 인덱스 docs/rfcs/INDEX.md Request for Comments
Operator 가이드 docs/operator-guide/ 배포 / HA / 모니터링 가이드
Runbook docs/runbooks/ 백업 / 복구 / HA / 보안 절차
용어집 docs/GLOSSARY.ko.md 용어 정의 SSOT (각 문서 마지막 장 발췌의 원본)

12. 용어집

정의는 GLOSSARY.ko.md에서 발췌해 동일하게 유지한다. 전체 용어는 해당 문서 참고.

용어 정의
Operator Kubernetes 위에서 애플리케이션(여기선 PostgreSQL)의 생성·운영·복구를 CRD + 컨트롤러로 자동화하는 소프트웨어.
CRD (Custom Resource Definition) K8s API를 확장하는 사용자 정의 리소스 타입(PostgresCluster 등).
Reconcile / Reconciler 실제 상태를 원하는 상태(spec)로 수렴시키는 controller-runtime 루프.
StatefulSet (STS) 안정적 식별자·스토리지를 갖는 Pod 집합. PostgreSQL 인스턴스를 띄우는 워크로드.
Hibernation 클러스터를 STS scale-0으로 내려 PVC는 보존한 채 휴면시키는 기능.
ShardRange 샤드 범위를 정의하는 CRD. 분산 메타데이터의 source of truth.
G0~G6 게이트 로드맵 단계 게이트(G1 단일 샤드 HA, G2 운영 품질, G3 샤딩 기반 등).
Helm chart K8s 매니페스트를 패키징·배포하는 단위. operator 배포에 사용.