04. Web UI로 PostgreSQL 클러스터 생성

1. 생성할 구성

Web UI에서 단일 인스턴스를 생성하고 SQL 실행을 확인합니다.

항목	설정값
Namespace	postgres
클러스터 이름	demo-db
PostgreSQL 버전	UI 지원 목록에서 선택
인스턴스 수	1
CPU·메모리	테스트용 프로파일
StorageClass	실제 환경값
인스턴스별 디스크	5Gi — 예시
DB Service	ClusterIP
추가 Extension·SQL Script	제외
백업·모니터링 외부 연동	제외

클러스터 생성은 PostgreSQL 인스턴스 배포입니다. 애플리케이션용 Database·Role은 접속 문서에서 생성합니다.

2. Namespace 준비

Context와 변수를 설정합니다.

export K8S_CONTEXT="$(kubectl config current-context)"
export DB_NAMESPACE="postgres"
export DB_CLUSTER="demo-db"

Namespace를 확인하고 없으면 생성합니다.

kubectl --context "$K8S_CONTEXT" get namespace "$DB_NAMESPACE"

kubectl --context "$K8S_CONTEXT" create namespace "$DB_NAMESPACE"

이미 존재하면 생성 명령은 실행하지 않습니다.

StorageClass를 확인합니다.

kubectl --context "$K8S_CONTEXT" get storageclass

Operator의 관리 Namespace를 제한했다면 postgres를 포함해야 합니다.

3. Web UI에서 생성

3.1. 생성 화면 열기

03번 문서의 /admin/ 주소로 로그인하고 클러스터 생성 화면을 엽니다.

메뉴 이름·배치는 버전에 따라 다를 수 있습니다.

3.2. 기본 정보 입력

항목	입력값
Namespace	postgres
클러스터 이름	demo-db
PostgreSQL 버전	지원 목록에서 선택
인스턴스 수	1

선택한 PostgreSQL 버전을 기록합니다.

3.3. CPU·메모리 설정

인스턴스 프로파일을 선택하거나 준비합니다. SGInstanceProfile은 인스턴스의 CPU·메모리 설정을 정의합니다.

프로파일 목록·설정을 확인합니다.

kubectl --context "$K8S_CONTEXT" get sginstanceprofiles \
  --namespace "$DB_NAMESPACE"

kubectl --context "$K8S_CONTEXT" get sginstanceprofile <PROFILE_NAME> \
  --namespace "$DB_NAMESPACE" \
  -o yaml

참조할 프로파일이 같은 Namespace에 있는지 확인합니다. 생성 방식은 UI 버전에 맞춰 진행합니다.

3.4. 스토리지 설정

항목	입력값
StorageClass	실제 선택한 이름
인스턴스별 용량	5Gi — 예시

의도하지 않은 기본 스토리지 사용을 피하도록 StorageClass를 지정합니다.

3.5. 추가 기능 확인

추가 Extension·사용자 SQL Script·외부 모니터링 연동은 제외합니다.

PgBouncer 등 기본 구성 요소는 유지합니다. 기본 커넥션 풀러는 Sidecar로 배포됩니다.

DB Service는 ClusterIP로 시작합니다. 외부 접속은 접속 문서에서 구성합니다.

3.6. 생성 실행

다음 설정을 검토하고 생성합니다.

Namespace·클러스터 이름
PostgreSQL 버전
인스턴스 수
리소스 프로파일
StorageClass·용량

생성 후 UI와 Kubernetes 리소스를 함께 확인합니다.

4. 생성 상태 확인

4.1. SGCluster와 Pod

kubectl --context "$K8S_CONTEXT" get sgcluster "$DB_CLUSTER" \
  --namespace "$DB_NAMESPACE"

kubectl --context "$K8S_CONTEXT" get pods \
  --namespace "$DB_NAMESPACE" \
  -o wide

SGCluster는 클러스터 구성을 정의하는 Custom Resource입니다. 생성된 설정을 확인합니다.

kubectl --context "$K8S_CONTEXT" get sgcluster "$DB_CLUSTER" \
  --namespace "$DB_NAMESPACE" \
  -o yaml

4.2. PVC와 Service

kubectl --context "$K8S_CONTEXT" get pvc \
  --namespace "$DB_NAMESPACE"

kubectl --context "$K8S_CONTEXT" get svc \
  --namespace "$DB_NAMESPACE"

대상	확인 항목
SGCluster	입력한 설정 반영
Pod	Running·전체 컨테이너 Ready
PVC	Bound
Service	DB 접속 서비스 생성

Running이어도 Ready가 아니면 초기화 상태·로그를 확인합니다.

4.3. Pod 준비 대기

기본 Pod 이름을 사용하는 단일 인스턴스 예제입니다.

kubectl --context "$K8S_CONTEXT" wait \
  --namespace "$DB_NAMESPACE" \
  --for=condition=Ready \
  pod/"${DB_CLUSTER}-0" \
  --timeout=600s

Pod 이름이 다르면 실제 이름으로 바꿉니다. 600s는 대기 제한입니다.

5. SQL 실행 확인

5.1. 관리 컨테이너에서 접속

postgres-util 컨테이너의 psql로 접속합니다.

kubectl --context "$K8S_CONTEXT" exec -it \
  --namespace "$DB_NAMESPACE" \
  "${DB_CLUSTER}-0" \
  --container postgres-util \
  -- psql -U postgres -d postgres

컨테이너 이름이 다르면 실제 Pod 구성을 확인합니다.

5.2. 버전과 역할 확인

psql에서 실행합니다.

SELECT version();

SELECT current_database(), current_user;

SELECT pg_is_in_recovery();

단일 Primary에서는 pg_is_in_recovery()가 false인지 확인합니다.

5.3. 쓰기·읽기 확인

세션 종료 시 삭제되는 임시 테이블로 검증합니다.

CREATE TEMP TABLE stackgres_check (
    id integer PRIMARY KEY,
    message text
);

INSERT INTO stackgres_check
VALUES (1, 'StackGres connection OK');

SELECT * FROM stackgres_check;

예상 결과입니다.

 id |         message
----+-------------------------
  1 | StackGres connection OK

psql을 종료합니다.

\q

이 단계는 Pod 내부 SQL 검증입니다. Service 경유·외부 접속은 접속 문서에서 확인합니다.

6. 생성 지연과 오류 확인

kubectl --context "$K8S_CONTEXT" describe pod "${DB_CLUSTER}-0" \
  --namespace "$DB_NAMESPACE"

kubectl --context "$K8S_CONTEXT" get events \
  --namespace "$DB_NAMESPACE" \
  --sort-by=.metadata.creationTimestamp

증상	확인 항목
PVC Pending	StorageClass·프로비저닝·배치 조건
Pod Pending	노드 리소스·Taint·볼륨
ImagePullBackOff	이미지 주소·다운로드 오류
Init Container 지연	초기화 컨테이너 로그
Running이지만 Ready 미충족	컨테이너 로그·Readiness
UI만 느림	REST API·브라우저 요청

컨테이너 목록을 확인합니다.

kubectl --context "$K8S_CONTEXT" get pod "${DB_CLUSTER}-0" \
  --namespace "$DB_NAMESPACE" \
  -o jsonpath='{.spec.initContainers[*].name}{"\n"}{.spec.containers[*].name}{"\n"}'

문제 컨테이너의 로그를 조회합니다.

kubectl --context "$K8S_CONTEXT" logs "${DB_CLUSTER}-0" \
  --namespace "$DB_NAMESPACE" \
  --container <CONTAINER_NAME> \
  --tail=100