11. StackGres 리소스 프로파일 및 PostgreSQL 설정 관리

소개

• StackGres는 설정을 SGInstanceProfile과 SGPostgresConfig로 나누어 관리한다.
• 이 문서는 db-test 네임스페이스의 pgsql 클러스터를 기준으로 작성했다. PostgreSQL 버전은 예시로 16을 사용하며, 실제 클러스터 버전에 맞게 변경한다.

1. 각 리소스의 역할

SGInstanceProfile은 PostgreSQL 실행에 필요한 리소스를 정의하고, SGPostgresConfig는 postgresql.conf에 해당하는 내부 설정을 정의한다.

1.1. SGInstanceProfile

주요 필드는 다음과 같다.

1.2. SGPostgresConfig

PostgreSQL 메이저 버전과 서버 파라미터를 정의한다.

별도 설정을 지정하지 않으면 StackGres가 기본 PostgreSQL 설정을 생성한다. 사용자 정의 설정은 여러 클러스터에서 재사용할 수 있다.

2. 리소스 생성

2.1. SGInstanceProfile 생성

sginstanceprofile.yaml 파일을 작성한다.

apiVersion: stackgres.io/v1
kind: SGInstanceProfile
metadata:
  name: size-small
  namespace: db-test
spec:
  cpu: "2"
  memory: "4Gi"

위 설정은 patroni 컨테이너에 CPU 2코어와 메모리 4Gi limits를 지정한다. 명시하지 않은 컨테이너별 리소스는 Operator가 기본값으로 채운다.

kubectl apply -f sginstanceprofile.yaml

생성 결과를 확인한다.

kubectl get sginstanceprofiles -n db-test
kubectl get sginstanceprofile size-small -n db-test -o yaml

2.2. SGPostgresConfig 생성

먼저 기존 클러스터의 PostgreSQL 버전을 확인한다.

kubectl get sgcluster pgsql -n db-test \
  -o jsonpath='{.spec.postgres.version}{"\n"}'

sgpostgresconfig.yaml 파일을 작성한다.

아래 예시는 PostgreSQL 16용이다. 실제 버전이 17.x라면 postgresVersion을 "17"로 변경한다. 같은 메이저 버전의 설정은 해당 버전의 마이너 버전에서도 사용할 수 있다.

apiVersion: stackgres.io/v1
kind: SGPostgresConfig
metadata:
  name: pgsql-config
  namespace: db-test
spec:
  postgresVersion: "16"
  postgresql.conf:
    log_min_duration_statement: "1000"
    log_checkpoints: "on"

이 예시는 로그 설정만 명시한다. StackGres 기본값에도 포함된 항목이므로, 현재 설정에 따라 실제 동작 차이가 없을 수 있다.

kubectl apply -f sgpostgresconfig.yaml

생성 결과를 확인한다.

kubectl get sgpgconfigs -n db-test
kubectl get sgpgconfig pgsql-config -n db-test -o yaml

3. 생성한 리소스 적용

리소스를 생성하는 것만으로 기존 클러스터에 연결되지는 않는다. SGCluster에서 생성한 리소스 이름을 참조해야 한다.

3.1. 클러스터 생성 YAML에 지정

클러스터 생성 YAML에 다음 필드를 추가한다.

아래는 관련 설정만 발췌한 내용이다. 이 YAML만으로 클러스터를 생성하지 않고, 전체 SGCluster YAML에 병합해서 사용한다.

apiVersion: stackgres.io/v1
kind: SGCluster
metadata:
  name: pgsql
  namespace: db-test
spec:
  sgInstanceProfile: size-small

  configurations:
    sgPostgresConfig: pgsql-config

  # instances, postgres, pods 등 나머지 설정 유지

프로파일과 PostgreSQL 설정을 먼저 생성한 뒤 클러스터를 생성한다.

kubectl apply -f sginstanceprofile.yaml
kubectl apply -f sgpostgresconfig.yaml
kubectl apply -f sgcluster.yaml

3.2. 기존 pgsql 클러스터에 적용

기존 클러스터의 나머지 설정은 유지하고, 두 참조 필드만 변경한다.

kubectl patch sgcluster pgsql -n db-test \
  --type merge \
  -p '{
    "spec": {
      "sgInstanceProfile": "size-small",
      "configurations": {
        "sgPostgresConfig": "pgsql-config"
      }
    }
  }'

선언형 YAML로 관리하는 환경에서는 원본 SGCluster YAML도 동일하게 수정한다.

3.3. 참조 설정 확인

kubectl get sgcluster pgsql -n db-test \
  -o jsonpath='{.spec.sgInstanceProfile}{"\n"}{.spec.configurations.sgPostgresConfig}{"\n"}'

예상 출력:

size-small
pgsql-config

3.4. 실제 Pod 리소스 확인

kubectl get pod pgsql-0 -n db-test \
  -o jsonpath='{range .spec.containers[*]}{.name}{"\n"}{.resources}{"\n\n"}{end}'

patroni 컨테이너의 limits와 다른 컨테이너의 resources를 확인한다.

3.5. PostgreSQL 설정 확인

PostgreSQL에 접속해 실제 적용값을 조회한다.

SHOW log_min_duration_statement;
SHOW log_checkpoints;

설정값과 재시작 대기 여부를 함께 확인하려면 다음 SQL을 실행한다.

SELECT
    name,
    setting,
    unit,
    context,
    pending_restart
FROM pg_settings
WHERE name IN (
    'log_min_duration_statement',
    'log_checkpoints'
)
ORDER BY name;

4. 변경이 제한된 설정

4.1. SGPostgresConfig의 변경 금지 파라미터

StackGres는 정상 동작에 필요한 일부 파라미터를 직접 관리한다. 다음 항목을 SGPostgresConfig.spec.postgresql.conf에 지정하면 오류가 발생한다.

위 목록은 StackGres latest 문서 기준이다. 실제 운영에서는 설치한 StackGres 버전의 CRD 문서를 확인한다.

4.2. SGInstanceProfile과 서버 튜닝 구분

SGInstanceProfile은 CPU·메모리 리소스를 정의하는 리소스다. shared_buffers, work_mem 등 PostgreSQL 파라미터는 SGPostgresConfig에서 설정한다.

# SGInstanceProfile
spec:
  cpu: "2"
  memory: "4Gi"

# SGPostgresConfig
spec:
  postgresVersion: "16"
  postgresql.conf:
    shared_buffers: "1GB"

두 설정은 별도 리소스이므로, 메모리 프로파일과 PostgreSQL 메모리 설정을 함께 검토한다.

4.3. 공유 설정 변경 시 주의

하나의 SGPostgresConfig를 여러 클러스터에서 참조할 수 있다. 공유 설정을 수정하기 전에는 영향을 받는 클러스터를 확인한다.

kubectl get sgclusters -n db-test \
  -o custom-columns='NAME:.metadata.name,PROFILE:.spec.sgInstanceProfile,POSTGRES_CONFIG:.spec.configurations.sgPostgresConfig'