02. StackGres Operator 설치

1. 설치 구성

Helm으로 Operator와 Web UI를 설치하는 절차를 작성했습니다.

항목	설정
Release	stackgres-operator
Namespace	stackgres
Chart 버전	조회 후 고정
Operator·REST API·Web UI	활성화
Web UI Service	ClusterIP
Web UI HTTP 포트	비활성화
Grafana 자동 연동	비활성화

주요 리소스는 Operator·REST API Deployment, CRD, Webhook, 인증 리소스입니다. 실제 구성과 설정 키는 선택한 Chart에서 확인합니다.

2. 작업 환경 준비

설치 대상 Context를 확인하고 변수를 설정합니다.

kubectl config current-context

export K8S_CONTEXT="$(kubectl config current-context)"
export SG_NAMESPACE="stackgres"
export SG_RELEASE="stackgres-operator"
export SG_CHART="stackgres-charts/stackgres-operator"

작업 디렉터리를 생성합니다.

mkdir -p stackgres-install
cd stackgres-install

3. Helm 저장소와 버전 준비

3.1. 저장소 등록

저장소를 등록하고 Chart 버전을 조회합니다.

helm repo add stackgres-charts \
  [https://stackgres.io/downloads/stackgres-k8s/stackgres/helm/](https://stackgres.io/downloads/stackgres-k8s/stackgres/helm/)

helm repo update stackgres-charts
helm repo list

helm search repo "$SG_CHART" --versions

CHART VERSION과 APP VERSION을 구분해 기록합니다.

3.2. 버전 고정

조회한 Chart 버전을 지정합니다.

export SG_CHART_VERSION="<선택한-Chart-버전>"

재현 가능한 설치를 위해 --version으로 고정합니다.

3.3. Chart 정보 저장

helm show chart "$SG_CHART" \
  --version "$SG_CHART_VERSION" \
  > chart-metadata.yaml

helm show values "$SG_CHART" \
  --version "$SG_CHART_VERSION" \
  > chart-default-values.yaml

cat chart-metadata.yaml
less chart-default-values.yaml

예제의 설정 키가 있는지 확인하고, 차이가 있으면 해당 버전에 맞춰 수정합니다.

4. values.yaml 작성

4.1. 기본 설정

cat > values.yaml <<'EOF'
deploy:
  operator: true
  restapi: true

adminui:
  service:
    type: ClusterIP
    exposeHTTP: false

grafana:
  autoEmbed: false
EOF

Operator·REST API를 활성화하고, UI 외부 노출·HTTP 포트·Grafana 자동 연동은 제외합니다. 나머지는 Chart 기본값을 사용합니다.

Grafana 자동 연동을 꺼도 모든 메트릭 구성 요소가 비활성화되는 것은 아닙니다.

4.2. 인증과 권한

Chart에서 다음 설정을 확인합니다.

authentication.type
authentication.createAdminSecret
authentication.user
authentication.password
rbac.create
allowedNamespaces

rbac.create의 관리자 cluster-admin 권한 할당 여부를 확인합니다. 기본 설치를 운영용 최소 권한 구성으로 간주하지 않습니다.

관리자 비밀번호는 values.yaml에 직접 기록하지 않습니다. 인증 정보·UI 접속은 04번 문서에서 확인합니다.

기존 Prometheus·Grafana가 필요한 자동 연동 예제는 제외합니다.

5. 설치 리소스 사전 확인

helm template "$SG_RELEASE" "$SG_CHART" \
  --namespace "$SG_NAMESPACE" \
  --version "$SG_CHART_VERSION" \
  --values values.yaml \
  --include-crds \
  > rendered.yaml

less rendered.yaml

다음 항목을 확인합니다.

리소스 이름·Namespace
이미지 경로·태그
Service 유형·포트
CRD·Webhook
RBAC·ServiceAccount·설치 Job
Secret·인증 설정

렌더링 성공이 설치 성공을 보장하지는 않습니다. 권한·배치·이미지 다운로드·Webhook 통신은 설치 후 확인합니다.

6. Operator 설치

6.1. 기존 Release 확인

helm list \
  --namespace "$SG_NAMESPACE" \
  --kube-context "$K8S_CONTEXT" \
  --all

같은 Release가 있으면 신규 설치 대신 현재 상태·설정을 확인합니다.

6.2. 신규 설치

helm install "$SG_RELEASE" "$SG_CHART" \
  --kube-context "$K8S_CONTEXT" \
  --namespace "$SG_NAMESPACE" \
  --create-namespace \
  --version "$SG_CHART_VERSION" \
  --values values.yaml \
  --wait \
  --timeout 10m

10m은 대기 제한입니다. 실패 원인 조사를 위해 --atomic은 사용하지 않습니다.

6.3. Release 상태

helm status "$SG_RELEASE" \
  --namespace "$SG_NAMESPACE" \
  --kube-context "$K8S_CONTEXT"

Helm 상태와 Kubernetes 리소스를 함께 확인합니다.

7. Deployment와 Pod 확인

7.1. 준비 상태 대기

라벨로 Deployment 준비 상태를 확인합니다.

kubectl --context "$K8S_CONTEXT" wait deployment \
  --namespace "$SG_NAMESPACE" \
  --selector group=stackgres.io \
  --for=condition=Available \
  --timeout=600s

대상 리소스가 없으면 실제 라벨을 확인합니다.

kubectl --context "$K8S_CONTEXT" get deployments \
  --namespace "$SG_NAMESPACE" \
  --show-labels

7.2. 리소스 상태

kubectl --context "$K8S_CONTEXT" get deployments,pods,services,jobs \
  --namespace "$SG_NAMESPACE" \
  -o wide

대상	확인 항목
Deployment	원하는 인스턴스 수·준비 상태
Pod	Running·Ready
Service	유형·포트
Job	완료·실패 여부

설치 Job은 완료 후 삭제될 수 있습니다. Pod 이름·컨테이너 수는 실제 결과로 기록합니다.

7.3. 로그

kubectl --context "$K8S_CONTEXT" logs \
  --namespace "$SG_NAMESPACE" \
  deployment/stackgres-operator \
  --all-containers=true \
  --tail=100

kubectl --context "$K8S_CONTEXT" logs \
  --namespace "$SG_NAMESPACE" \
  deployment/stackgres-restapi \
  --all-containers=true \
  --tail=100

Deployment 이름이 다르면 실제 이름으로 바꿉니다.

8. CRD와 Webhook 확인

8.1. CRD

kubectl --context "$K8S_CONTEXT" get crd \
  -o name | grep 'stackgres.io'

kubectl --context "$K8S_CONTEXT" wait \
  --for=condition=Established \
  --timeout=120s \
  crd/sgclusters.stackgres.io

kubectl --context "$K8S_CONTEXT" api-resources \
  --api-group=stackgres.io

SGCluster 스키마를 확인합니다.

kubectl --context "$K8S_CONTEXT" explain sgcluster
kubectl --context "$K8S_CONTEXT" explain sgcluster.spec

8.2. Webhook

kubectl --context "$K8S_CONTEXT" get \
  mutatingwebhookconfigurations,validatingwebhookconfigurations \
  -o name | grep -i stackgres

이름으로 구분되지 않으면 렌더링 결과와 비교합니다.

오류가 있으면 실제 설정을 확인합니다.

kubectl --context "$K8S_CONTEXT" get \
  validatingwebhookconfiguration <WEBHOOK_NAME> \
  -o yaml

서비스 참조·통신·인증서를 확인합니다. Custom Resource 생성은 05·06번 문서에서 검증합니다.

9. 설치 설정과 이력 관리

9.1. 설정·이력 저장

helm get values "$SG_RELEASE" \
  --namespace "$SG_NAMESPACE" \
  --kube-context "$K8S_CONTEXT" \
  --output yaml \
  > release-user-values.yaml

helm history "$SG_RELEASE" \
  --namespace "$SG_NAMESPACE" \
  --kube-context "$K8S_CONTEXT" \
  > release-history.txt

전체 계산 설정은 --all로 조회합니다.

helm get values "$SG_RELEASE" \
  --namespace "$SG_NAMESPACE" \
  --kube-context "$K8S_CONTEXT" \
  --all

인증 정보가 포함될 수 있으므로 출력 전체를 공개하지 않습니다.

9.2. 실제 이미지 확인

kubectl --context "$K8S_CONTEXT" get pods \
  --namespace "$SG_NAMESPACE" \
  -o jsonpath='{range .items[*]}{.metadata.name}{"\n"}{range .spec.initContainers[*]}{"  init: "}{.name}{" -> "}{.image}{"\n"}{end}{range .spec.containers[*]}{"  container: "}{.name}{" -> "}{.image}{"\n"}{end}{end}'

9.3. 설정 변경

values.yaml을 수정하고 같은 Chart 버전으로 반영합니다.

helm upgrade "$SG_RELEASE" "$SG_CHART" \
  --kube-context "$K8S_CONTEXT" \
  --namespace "$SG_NAMESPACE" \
  --version "$SG_CHART_VERSION" \
  --values values.yaml \
  --wait \
  --timeout 10m

설정은 values.yaml으로 관리합니다. Chart 버전 업그레이드는 별도 절차를 확인합니다.

10. 설치 실패 시 확인

10.1. Event와 로그

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

kubectl --context "$K8S_CONTEXT" describe pod <POD_NAME> \
  --namespace "$SG_NAMESPACE"

kubectl --context "$K8S_CONTEXT" logs <POD_NAME> \
  --namespace "$SG_NAMESPACE" \
  --all-containers=true \
  --tail=200

재시작 전 로그는 컨테이너를 지정해 조회합니다.

kubectl --context "$K8S_CONTEXT" logs <POD_NAME> \
  --namespace "$SG_NAMESPACE" \
  --container <CONTAINER_NAME> \
  --previous \
  --tail=200

10.2. 증상별 확인

증상	확인 항목
Helm 오류	권한·리소스 충돌·오류 원문
Pod Pending	리소스·Taint·배치 조건
ImagePullBackOff	이미지 주소·다운로드 오류
Job 실패	Job Pod 로그
반복 재시작	종료 원인·컨테이너 로그
준비 상태 실패	Readiness·Event
Webhook 오류	서비스·인증서·Operator 상태