03. Web UI 접속 구성

1. 접속 방식

StackGres Web UI는 클러스터 조회·설정 변경을 제공합니다. 기본 Service는 stackgres-restapi, 접속 경로는 /admin/입니다.

방식	용도
port-forward	로컬 접속 확인
NodePort	외부 PC에서 노드 주소로 접속
Ingress	도메인 기반 접속

관리 화면과 DB 접속 주소는 다릅니다.

관리 접속: 브라우저 → Web UI
DB 접속:   애플리케이션 → PostgreSQL Service

2. 변수와 서비스 확인

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

설치한 Chart 버전을 지정합니다.

export SG_CHART_VERSION="<설치한-Chart-버전>"

관리 Service·Pod·포트를 확인합니다.

kubectl --context "$K8S_CONTEXT" get svc stackgres-restapi \
  --namespace "$SG_NAMESPACE" \
  -o wide

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

kubectl --context "$K8S_CONTEXT" get svc stackgres-restapi \
  --namespace "$SG_NAMESPACE" \
  -o yaml

이후 예제는 HTTPS Service 포트 443 기준입니다. 실제 포트가 다르면 수정합니다.

3. 관리자 인증 정보 확인

기본 관리자 Secret에서 사용자 이름·비밀번호를 조회합니다.

kubectl --context "$K8S_CONTEXT" get secret stackgres-restapi-admin \
  --namespace "$SG_NAMESPACE" \
  --template='{{ printf "username = %s\n" (.data.k8sUsername | base64decode) }}'

Secret이 없으면 설치 시 인증 설정·Secret 생성 여부를 확인합니다.

4. port-forward로 접속

관리 PC에서 실행합니다.

kubectl --context "$K8S_CONTEXT" port-forward \
  --namespace "$SG_NAMESPACE" \
  service/stackgres-restapi \
  8443:443 \
  --address 127.0.0.1

같은 PC의 브라우저에서 접속하고 관리자 계정으로 로그인합니다.

[https://localhost:8443/admin/](https://localhost:8443/admin/)

자체 서명 인증서는 브라우저 경고가 표시될 수 있습니다.

다른 PC에서는 접속할 수 없습니다. 외부 접속은 NodePort 또는 Ingress를 사용합니다.

5. NodePort로 외부 접속

5.1. values.yaml 변경

02번 문서의 values.yaml을 수정합니다.

deploy:
  operator: true
  restapi: true

adminui:
  service:
    type: NodePort
    exposeHTTP: false

grafana:
  autoEmbed: false

기존 추가 설정은 유지하고 adminui.service.type만 변경합니다.

5.2. Helm 반영

values.yaml이 있는 디렉터리에서 실행합니다.

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

5.3. 할당 포트 확인

kubectl --context "$K8S_CONTEXT" get svc stackgres-restapi \
  --namespace "$SG_NAMESPACE"

출력 예시입니다.

NAME                TYPE       CLUSTER-IP    EXTERNAL-IP   PORT(S)
stackgres-restapi   NodePort   10.96.10.20   <none>        443:31133/TCP

예제의 NodePort는 31133입니다. 실제 할당 포트로 접속합니다.

https://<접근 가능한 노드 IP>:<NodePort>/admin/

노드 주소를 확인합니다.

kubectl --context "$K8S_CONTEXT" get nodes -o wide

관리 PC에서 노드 IP·NodePort에 접근할 수 있어야 합니다.

6. Ingress로 도메인 접속

6.1. TLS 종료 위치

브라우저와 백엔드의 프로토콜을 구분합니다.

구성	연결 경로
백엔드 HTTPS	브라우저 HTTPS → Ingress → Service HTTPS
백엔드 HTTP	브라우저 HTTPS → Ingress → Service HTTP

HTTPS 백엔드 설정은 Ingress Controller별로 확인합니다.

아래 예제는 Ingress에서 TLS를 종료하고 백엔드에는 HTTP로 연결합니다.

6.2. HTTP 포트 활성화

values.yaml을 수정합니다.

deploy:
  operator: true
  restapi: true

adminui:
  service:
    type: ClusterIP
    exposeHTTP: true

grafana:
  autoEmbed: false

exposeHTTP로 관리 Service의 HTTP 포트를 활성화합니다.

5.2절의 Helm 명령으로 반영하고 포트를 확인합니다.

kubectl --context "$K8S_CONTEXT" get svc stackgres-restapi \
  --namespace "$SG_NAMESPACE" \
  -o yaml

다음 예제는 HTTP Service 포트 80 기준입니다. 실제 포트가 다르면 수정합니다.

6.3. Ingress 작성

예제 값을 환경에 맞게 변경합니다.

예제 값	변경 대상
`<INGRESS_CLASS>`	설치된 IngressClass
stackgres.example.com	관리 도메인
stackgres-ui-tls	도메인의 TLS Secret

TLS Secret은 Ingress와 같은 stackgres Namespace에 준비합니다.

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: stackgres-admin
  namespace: stackgres
spec:
  ingressClassName: <INGRESS_CLASS>
  tls:
    - hosts:
        - stackgres.example.com
      secretName: stackgres-ui-tls
  rules:
    - host: stackgres.example.com
      http:
        paths:
          - path: /
            pathType: Prefix
            backend:
              service:
                name: stackgres-restapi
                port:
                  number: 80

ingress.yaml로 저장하고 적용합니다.

kubectl --context "$K8S_CONTEXT" apply -f ingress.yaml

kubectl --context "$K8S_CONTEXT" get ingress \
  --namespace "$SG_NAMESPACE"

DNS가 Ingress 접속 주소를 가리키도록 설정하고 /admin/으로 접속합니다.

[https://stackgres.example.com/admin/](https://stackgres.example.com/admin/)

7. 접속 오류 확인

증상	확인 항목
루트 경로 오류	`/admin/` 접속 여부
연결 실패	노드 IP·포트·방화벽
인증 실패	관리자 Secret·인증 설정
인증서 경고	인증서 신뢰·접속 도메인
HTTP 요청이 HTTPS 포트로 전달됨	백엔드 프로토콜·Service 포트
502·503	Service 연결 대상·Pod Ready
반복 타임아웃	브라우저 API 요청·REST API 로그·프록시

REST API 로그·Event를 확인합니다.

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

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