01. StackGres 개요와 구성 이해
1. StackGres란?
StackGres는 PostgreSQL, HA, 커넥션 풀링, 메트릭 수집을 통합한 Kubernetes 기반 PostgreSQL 플랫폼입니다.
Web UI 또는 YAML로 구성을 정의하면 Operator가 클러스터를 관리합니다. UI 변경 사항도 Custom Resource에 반영됩니다.
text
운영자 → Web UI / YAML → Custom Resource → Operator → PostgreSQL 클러스터
| 용어 | 의미 |
|---|---|
| Kubernetes 클러스터 | DB가 실행되는 Kubernetes 환경 |
| PostgreSQL 클러스터 | Primary·Replica로 구성된 DB 인스턴스 집합 |
| Database | PostgreSQL 내부의 논리적 데이터베이스 |
| Role | 접속·객체 권한을 관리하는 역할 또는 사용자 |
클러스터 생성과 애플리케이션용 Database·Role 생성은 별도 작업입니다.
2. PostgreSQL 구축 방식 비교
2.1. 기능 비교
| 항목 | PostgreSQL + HAProxy | CloudNativePG(CNPG) | StackGres |
|---|---|---|---|
| 클러스터 생성 | 배포·복제·프록시 직접 구성 | Cluster 리소스 | SGCluster 또는 Web UI |
| 운영 관리 | 설정 파일·스크립트·개별 도구 | YAML·kubectl·cnpg 플러그인 | YAML·kubectl·REST API·Web UI |
| 복제 관리 | 직접 구성 또는 Patroni | Operator | Patroni |
| 자동 장애 전환 | Patroni 등 별도 구성 | Operator 기반 | Patroni 기반 |
| DB 접속 | HAProxy | Kubernetes Service | Kubernetes Service |
| 커넥션 풀링 | PgBouncer 별도 구성 | Pooler로 PgBouncer 배포 | PgBouncer 통합 |
| PostgreSQL 설정 | 설정 파일 | Cluster | SGPostgresConfig |
| 관리 화면 | 별도 구성 | 기본 Operator·CLI 기준 | 내장 Web UI |
| 구성 방식 | 도구 직접 조합 | Kubernetes Operator 중심 | 운영 스택 통합 |
CNPG의 외부 UI 연동은 비교에서 제외합니다.
2.2. PostgreSQL + HAProxy
HAProxy는 DB 연결을 전달하며, 복제와 Replica 승격은 담당하지 않습니다. 자동 장애 전환에는 Patroni 등이 필요합니다.
| 구성 요소 | 역할 |
|---|---|
| PostgreSQL | 데이터 저장·SQL 처리 |
| Patroni | 복제·Primary 역할 관리·장애 전환 |
| HAProxy | DB 역할에 맞춰 연결 전달 |
각 구성 요소와 이중화를 직접 관리하는 방식입니다.
2.3. CloudNativePG
CNPG는 Patroni 없이 Operator가 Primary·Replica와 장애 전환을 관리합니다. 운영은 YAML·CLI 중심이며, 커넥션 풀링은 Pooler로 PgBouncer를 배포합니다.
CNPG와 StackGres는 HA 지원 여부보다 관리 방식과 통합 범위를 비교합니다.
3. StackGres를 선택한 이유
이번 구축은 내장 Web UI와 통합 관리의 편의성을 기준으로 선택했습니다.
| 선택 기준 | 기대 효과 |
|---|---|
| 내장 Web UI | 브라우저에서 클러스터 생성·조회·변경 |
| 통합 관리 | DB·리소스·커넥션 풀 설정 확인 |
| UI·YAML 병행 | UI 확인 후 선언형 관리로 확장 |
| 상태 확인 | 클러스터 상태·설정 시각화 |
UI로 생성한 구성을 확인하고 YAML로 재현합니다.
text
Web UI로 생성 → Custom Resource 확인 → YAML 정리 → 재현 검증
관리 편의성을 기준으로 선택했으며, CNPG보다 성능·안정성이 높다는 의미는 아닙니다. SQL 실행·리소스 사용량·장애 전환은 별도로 검증합니다.
4. 전체 구성
관리 접속과 DB 접속은 경로가 다릅니다.
- 관리 경로 : 운영자 → Web UI / YAML → Kubernetes API → Operator
- DB 접속 경로 : 애플리케이션 / psql / DBeaver → PostgreSQL Service → DB Pod → PVC
| 관리 구성 요소 | 역할 |
|---|---|
| Operator | 선언된 구성에 따라 클러스터 관리 |
| REST API·Web UI | 리소스 조회·설정 변경 |
UI 접속과 DB 준비 상태는 별개입니다. DB 준비 상태는 Kubernetes 리소스와 SQL 실행으로 확인합니다.
5. DB Pod 구성 요소
DB Pod에는 PostgreSQL과 HA·커넥션 풀링용 컨테이너 등이 포함됩니다.
| 구성 요소 | 역할 |
|---|---|
| PostgreSQL | 데이터 저장·SQL 처리 |
| Patroni | Primary·Replica 관리·장애 전환 |
| PgBouncer | 커넥션 풀링 |
| postgres-util | psql 등 관리 도구 |
| PostgreSQL Exporter | 메트릭 제공 |
실제 컨테이너 구성·개수는 버전과 설정에 따라 확인합니다.
6. 주요 Custom Resource
| 리소스 | 역할 |
|---|---|
| SGCluster | PostgreSQL 클러스터 구성 |
| SGInstanceProfile | CPU·메모리 설정 |
| SGPostgresConfig | PostgreSQL 서버 설정 |
| SGPoolingConfig | PgBouncer 설정 |
SGCluster는 설정 리소스를 이름으로 참조합니다. 참조 대상이 같은 Namespace에 있는지 확인합니다.
실행 상태는 다음 Kubernetes 리소스로 확인합니다.
| 리소스 | 확인 항목 |
|---|---|
| Pod | 실행·Ready 상태 |
| Service | DB 접속 경로 |
| PVC / PV | 스토리지 할당 |
| Event | 생성·실행 오류 |
7. 단일 인스턴스와 HA
단일 인스턴스로 기본 동작을 확인한 뒤 HA로 확장합니다.
| 구분 | 단일 인스턴스 | HA 구성 |
|---|---|---|
| 구성 | Primary 1개 | Primary·Replica |
| 목적 | 생성·기본 접속 확인 | 복제·장애 전환 확인 |
| 검증 | 인증·SQL 읽기/쓰기 | 역할 전환·재접속·인스턴스 복귀 |
| 배치 | 실행 노드 확인 | 노드 분산 확인 |
HA는 인스턴스 수뿐 아니라 Primary 장애 후 연결 회복과 기존 인스턴스 복귀까지 검증합니다.