본문 바로가기
WIKI 기술 지식 베이스

퀵스타트

원문 보기 위키 갱신

퀵스타트 (Quickstart)

로컬 머신에서 CloudNativePG를 배포해 PostgreSQL 클러스터를 테스트하는 방법을 알려 드릴게요. Kind나 Minikube를 이용해 로컬 Kubernetes 환경을 만들고, 오퍼레이터를 설치하고, PostgreSQL 클러스터를 배포하고, Prometheus와 Grafana로 모니터링하는 전체 과정을 함께 따라가 볼게요.

출처: 문서

본문

이 섹션은 Kind나 Minikube를 사용해 로컬 Kubernetes 클러스터에 CloudNativePG를 배포함으로써 로컬 머신에서 PostgreSQL 클러스터를 테스트하는 방법을 안내해요.

:::warning 이 섹션에 포함된 지침은 데모, 테스트, 연습 목적만을 위한 것으로 프로덕션에서는 사용하면 안 돼요. :::

다른 Kubernetes 애플리케이션과 마찬가지로 CloudNativePG는 YAML로 작성된 일반 매니페스트를 사용해 배포돼요.

이 페이지의 지침을 따르면 로컬 Kubernetes 설치에서 PostgreSQL 클러스터를 시작하고 실험해볼 수 있을 거예요.

:::info[Important] Kubernetes 클러스터에 연결하려면 머신에 kubectl이 설치되어 있어야 해요. Kubernetes 문서의 kubectl 설치 방법을 참고해 주세요. :::

1부: 로컬 Kubernetes 플레이그라운드 설정 (Setup the local Kubernetes playground)

첫 번째 부분은 Minikube나 Kind를 설치하는 것이에요. 두 시스템에 대해 읽어보고 어느 것으로 진행할지 시간을 들여 결정해 주세요. 하나를 설정한 후에는 2부로 진행해 주세요.

로컬 테스트/평가를 위한 Prometheus와 Grafana 모니터링 설정 지침도 4부에서 제공해요.

Minikube

Minikube는 Kubernetes를 로컬에서 쉽게 실행할 수 있게 해주는 도구예요. Minikube는 Kubernetes를 시도해 보거나 일상적으로 개발하려는 사용자를 위해 노트북의 가상 머신(VM) 안에서 단일 노드 Kubernetes 클러스터를 실행해요. 보통 VirtualBox와 함께 사용돼요.

공식 Kubernetes 문서에서 Minikube 설치 방법을 참고해 로컬 개인 환경에 설치할 수 있어요. 설치했으면 다음 명령을 실행해 minikube 클러스터를 만드세요:

minikube start

이렇게 하면 Kubernetes 클러스터가 생성되고 바로 사용할 수 있게 돼요. 다음 명령으로 정상 동작을 확인해 보세요:

kubectl get nodes

minikube라는 이름의 노드 하나가 보일 거예요.

Kind

가상 머신 하이퍼바이저를 사용하고 싶지 않다면, Kind는 Docker 컨테이너 "노드"를 사용해 로컬 Kubernetes 클러스터를 실행하는 도구예요 (Kind는 실제로 "Kubernetes IN Docker"를 의미해요).

퀵스타트의 지침에 따라 환경에 kind를 설치한 다음, 다음으로 Kubernetes 클러스터를 만드세요:

kind create cluster --name pg

2부: CloudNativePG 설치 (Install CloudNativePG)

이제 노트북에 Kubernetes 설치가 실행 중이므로 CloudNativePG 설치를 진행할 수 있어요.

"Installation(설치)" 섹션을 참고한 다음 PostgreSQL 클러스터 배포를 진행해 주세요.

3부: PostgreSQL 클러스터 배포 (Deploy a PostgreSQL cluster)

Kubernetes의 다른 배포와 마찬가지로 PostgreSQL 클러스터를 배포하려면 원하는 Cluster를 정의하는 구성 파일을 적용해야 해요.

cluster-example.yaml 샘플 파일은 기본 스토리지 클래스를 사용해 디스크 공간을 할당하는 간단한 Cluster를 정의해요:

apiVersion: postgresql.cnpg.io/v1
kind: Cluster
metadata:
  name: cluster-example
spec:
  instances: 3

  postgresql:
    synchronous:
      method: any
      number: 1

  storage:
    size: 1Gi

:::note[There's more] 사용 가능한 옵션에 대한 더 자세한 내용은 "API Reference" 섹션을 참고해 주세요. :::

3노드 PostgreSQL 클러스터를 생성하려면 다음 명령을 실행해야 해요:

kubectl apply -f cluster-example.yaml

get pods 명령으로 파드가 생성되고 있는지 확인할 수 있어요:

kubectl get pods

이 명령은 기본 네임스페이스에서 파드를 찾아요. 클러스터를 Kubernetes 설치의 다른 워크로드와 분리하려면 클러스터를 배포할 새 네임스페이스를 만들 수도 있어요. 대안으로 라벨을 사용할 수도 있어요. 오퍼레이터는 특정 클러스터와 관련된 모든 객체에 cnpg.io/cluster 라벨을 적용해요. 예를 들어:

kubectl get pods -l cnpg.io/cluster=<CLUSTER>

:::info[Important] 여기서는 cnpg.io/cluster를 라벨로 사용하고 있다는 점에 유의하세요. 과거에는 postgresql을 보거나 사용했을 수도 있어요. 이 라벨은 deprecated되고 있으며 향후 제거될 예정이에요. cnpg.io/cluster를 사용해 주세요. :::

기본적으로 오퍼레이터는 오퍼레이터가 출시된 시점의 최신 메이저 버전 PostgreSQL 중 가장 최신 마이너 버전을 설치해요. Cluster 정의의 spec 섹션에서 imageName 키를 설정해 이를 재정의할 수 있어요. 예를 들어 PostgreSQL 13.6을 설치하려면:

apiVersion: postgresql.cnpg.io/v1
kind: Cluster
metadata:
   # [...]
spec:
   # [...]
   imageName: ghcr.io/cloudnative-pg/postgresql:13.6
   #[...]

:::info[Important] 불변 인프라(immutable infrastructure) 패러다임에서는 항상 컨테이너 이미지의 특정 버전을 가리켜야 해요. 프로덕션 환경에서 latest나 13 같은 태그는 절대 사용하지 마세요. 업데이트 정책과 클러스터의 버전 일관성 측면에서 예측할 수 없는 시나리오를 만들 수 있기 때문이에요. 엄격하게 결정적이고 반복 가능한 배포를 위해서는 <image>:<tag>@sha256:<digestValue> 형식으로 이미지 이름에 다이제스트를 추가할 수 있어요. :::

:::note[There's more] 오퍼레이터와 함께 번들로 제공되는 몇 가지 예제 클러스터 구성이 있어요. "Examples(예시)" 섹션을 참고해 주세요. :::

4부: Prometheus와 Grafana로 클러스터 모니터링 (Monitor clusters with Prometheus and Grafana)

:::info[Important] Prometheus와 Grafana 설치는 이 프로젝트의 범위 밖이에요. 이 섹션의 지침은 실험과 설명 목적으로만 제공돼요. :::

이 섹션에서는 관측성을 위해 Prometheus와 Grafana를 배포하는 방법, CloudNativePG 클러스터를 모니터링하는 Grafana 대시보드를 만드는 방법, 그리고 알림 조건을 정의하는 Prometheus 규칙 세트를 만드는 방법을 보여줘요.

우리는 Prometheus Community가 유지 관리하는 Kube-Prometheus stack Helm 차트를 활용해요. 추가 문서와 배경은 프로젝트 웹사이트를 참고해 주세요.

Kube-Prometheus-stack Helm 차트는 Prometheus Operator를 설치하며, Alert Manager와 Grafana 배포를 포함해요.

CloudNativePG 클러스터의 관측성에 유용한 초기 설정을 제공하는 이 Helm 차트 배포용 구성 파일을 포함해요.

설치 (Installation)

아직 Helm이 설치되지 않았다면 지침에 따라 시스템에 설치해 주세요.

prometheus-community Helm 차트 리포지토리를 추가한 다음, 샘플 구성 kube-stack-config.yaml으로 Kube Prometheus stack을 설치해야 해요.

다음 명령으로 이를 수행할 수 있어요:

helm repo add prometheus-community \
  https://prometheus-community.github.io/helm-charts

helm upgrade --install \
  -f https://raw.githubusercontent.com/cloudnative-pg/cloudnative-pg/main/docs/src/samples/monitoring/kube-stack-config.yaml \
  prometheus-community \
  prometheus-community/kube-prometheus-stack

완료 후에는 kube-stack-config.yaml 파일로 구성된 Prometheus, Grafana, Alert Manager를 가지게 돼요:

  • Prometheus 설치에서 Prometheus Operator가 모든 PodMonitor를 감시하고 있어요 (자세한 내용은 monitoring(모니터링) 참고).
  • Alert Manager와 Grafana가 모두 활성화돼 있어요.

:::note[Seealso] 위 Helm 명령에 대한 자세한 내용은 helm install 문서를 참고해 주세요. :::

몇 가지 커스텀 리소스가 생성된 것을 볼 수 있어요:

% kubectl get crds
NAME                                        CREATED AT
…
alertmanagers.monitoring.coreos.com         <timestamp>
…
prometheuses.monitoring.coreos.com          <timestamp>
prometheusrules.monitoring.coreos.com       <timestamp>
…

그리고 일련의 서비스들도요:

% kubectl get svc     
NAME                                      TYPE        PORT(S)
…                                         …           …
prometheus-community-grafana              ClusterIP   80/TCP
prometheus-community-kube-alertmanager    ClusterIP   9093/TCP
prometheus-community-kube-operator        ClusterIP   443/TCP
prometheus-community-kube-prometheus      ClusterIP   9090/TCP

Prometheus로 보기 (Viewing with Prometheus)

이 시점에서 모니터링이 활성화된 상태로 배포된 CloudNativePG 클러스터는 Prometheus를 통해 관찰할 수 있어요.

예를 들어 PodMonitor가 활성화된 간단한 클러스터를 배포할 수 있어요:

kubectl apply -f - <<EOF
---
apiVersion: postgresql.cnpg.io/v1
kind: Cluster
metadata:
  name: cluster-with-metrics
spec:
  instances: 3

  storage:
    size: 1Gi
---
apiVersion: monitoring.coreos.com/v1
kind: PodMonitor
metadata:
  name: cluster-with-metrics
spec:
  selector:
    matchLabels:
      cnpg.io/cluster: cluster-with-metrics
  podMetricsEndpoints:
  - port: metrics
EOF

Prometheus에 접근하려면 Prometheus 서비스를 포트 포워딩하세요:

kubectl port-forward svc/prometheus-community-kube-prometheus 9090

그런 다음 로컬에서 Prometheus 콘솔에 접근하세요: http://localhost:9090/

CloudNativePG 클러스터와 관련된 일련의 메트릭을 찾을 수 있을 거예요. 자세한 내용은 monitoring(모니터링) 섹션을 참고해 주세요.

local prometheus

CloudNativePG 오퍼레이터를 대상으로 하는 PodMonitor를 만들어 오퍼레이터도 모니터링할 수 있어요. 자세한 내용은 monitoring 페이지의 관련 섹션을 참고해 주세요.

prometheusRule을 만들어 몇 가지 알림을 정의할 수 있어요:

kubectl apply -f \
  https://raw.githubusercontent.com/cloudnative-pg/cloudnative-pg/main/docs/src/samples/monitoring/prometheusrule.yaml

이제 기본 알림이 보일 거예요:

% kubectl get prometheusrules                      
NAME                                                       AGE
cnpg-default-alerts                                        3m27s

Prometheus 콘솔에서 Alerts 메뉴를 클릭해 방금 설치한 알림을 볼 수 있어요.

Grafana 대시보드 (Grafana Dashboard)

지금까지 설치에서 Grafana는 사전 정의된 대시보드 없이 배포돼요.

Grafana를 열려면 grafana 서비스를 포트 포워딩할 수 있어요:

kubectl port-forward svc/prometheus-community-grafana 3000:80

그리고 로컬에서 Grafana에 접근하세요 http://localhost:3000/. 사용자 이름은 admin, 비밀번호는 prom-operator를 입력하면 돼요 (kube-stack-config.yaml에서 정의됨).

CloudNativePG는 전용 grafana-dashboards 리포지토리에 기본 Grafana 대시보드를 제공해요. grafana-dashboard.json 파일을 다운로드해 GUI를 통해 직접 가져올 수 있어요 (메뉴: Dashboards > New > Import).

방금 만든 CloudNativePG 대시보드를 클릭할 수 있어요:

local grafana

:::warning 이전 대시보드의 일부 그래프는 이 대시보드가 만들어질 당시 알파 단계였던 메트릭(예: kubelet_volume_stats_available_bytes, kubelet_volume_stats_capacity_bytes)을 사용해 일부 그래프가 No data로 표시될 수 있어요. :::

참고로 로컬 설정에서 Prometheus와 Grafana는 모니터링 기능이 활성화된 상태로 배포된 CloudNativePG 클러스터를 자동으로 발견하고 모니터링하도록 구성돼 있어요.