Google은 AI 기술을 사용하여 콘텐츠를 사용자의 기본 언어로 번역합니다. AI 번역에는 오류가 있을 수 있습니다.

Kubernetes (GKE 또는 자체 클러스터 사용)에서 AlloyDB Omni 배포 및 관리

1. 소개

이 Codelab에서는 Google Kubernetes Engine (GKE) Autopilot 클러스터 또는 자체 Kubernetes 클러스터에 AlloyDB Omni Kubernetes 연산자 (컨테이너 조정자)를 설치하고 엔드 투 엔드 데이터베이스 수명 주기 워크플로와 핵심 사용자 여정 (CUJ)을 관리하는 방법을 알아봅니다.

AlloyDB Omni는 온프레미스 환경부터 Google Cloud 또는 에지 컴퓨팅에 이르기까지 어디서나 실행되도록 설계된 다운로드 가능한 버전의 AlloyDB입니다. 컨테이너 조정자를 사용하면 AlloyDB Omni가 고가용성, 자동 장애 조치, 자가 복구, 최소 다운타임으로 순차적 유지보수, 연결 풀링, 자동 백업, PITR(point-in-time recovery)을 자동화합니다.

PostgreSQL용 AlloyDB와 AlloyDB Omni 비교: PostgreSQL용 AlloyDB는 Google Cloud의 완전 관리형 데이터베이스 서비스입니다. AlloyDB Omni는 동일한 AlloyDB 데이터베이스 엔진을 다운로드 가능한 컨테이너로 패키징하여 온프레미스, 다른 퍼블릭 클라우드 (예: Amazon EKS 또는 Azure AKS), OpenShift 또는 개발자 워크스테이션에서 직접 실행하고 운영할 수 있도록 지원합니다. 이를 통해 데이터 레지던시, 하이브리드 클라우드 또는 로컬 개발 요구사항을 충족할 수 있습니다. 실제 배포에서는 일반적으로 자체 Kubernetes 클러스터에서 AlloyDB Omni Kubernetes 연산자를 실행합니다 (경로 2). 경로 1은 아직 클러스터가 없는 경우 GKE Autopilot을 편리한 로컬 설정이 필요 없는 Kubernetes 샌드박스로만 사용합니다.

환경 경로 선택

다음 두 가지 경로 중 하나를 사용하여 이 Codelab을 완료할 수 있습니다.

경로 1: Google Cloud 계정 보유 (GKE Autopilot) — Google Cloud Shell 또는 Google Cloud 콘솔을 사용하여 완전 관리형 GKE Autopilot 클러스터를 프로비저닝합니다.
경로 2: Google Cloud 계정이 없음 (자체 Kubernetes 클러스터 사용) — 워크스테이션에 kubectl 및 helm가 구성된 기존 Kubernetes 클러스터 (v1.21 이상)를 사용합니다. Google Cloud 계정이나 gcloud CLI는 필요하지 않습니다.

기본 요건

Kubernetes 개념 (kubectl, Helm, 커스텀 리소스 정의)에 대한 기본적인 이해
경로 1 (Google Cloud / GKE Autopilot):
- 결제가 사용 설정된 Google Cloud 프로젝트.
- gcloud, kubectl, helm로 구성된 Google Cloud Shell 또는 워크스테이션에 대한 액세스 권한
경로 2 (자체 Kubernetes 클러스터 사용):
- 동적 PersistentVolume 프로비저닝을 위한 기본 StorageClass가 있는 버전 1.21 이상을 실행하는 Kubernetes 클러스터
- cgroup v2가 사용 설정된 Linux 커널 4.18 이상 (x86-64/AMD64)을 실행하고 클러스터 전체에 최소 8개의 vCPU와 24GiB의 할당 가능한 RAM이 있는 워커 노드
- kubectl 및 helm로 구성된 워크스테이션이 클러스터에 연결되어 있습니다.

학습할 내용

GKE Autopilot 클러스터를 프로비저닝하는 방법 (경로 1) 또는 기존 Kubernetes 클러스터를 검증하는 방법 (경로 2)
Helm을 통해 cert-manager 및 AlloyDB Omni Kubernetes 연산자를 설치하는 방법
단일 인스턴스 AlloyDB Omni DBCluster를 배포하는 방법
동기식 대기 인스턴스를 사용하여 고가용성 (HA)으로 확장하고 읽기 전용 대기 기능을 사용 설정하는 방법
로컬 저장소 스토리지 (및 선택적으로 경로 1의 Google Cloud Storage)에 대한 예약된 자동 백업을 구성하는 방법
주문형 백업을 수행하고 데이터 복원을 이전 상태로 확인하는 방법
새로 클론된 데이터베이스 클러스터에 PITR (point-in-time recovery)을 수행하는 방법
클라이언트 연결 확장을 위해 PgBouncer 연결 풀링을 배포하는 방법
pgAdmin4를 배포하여 데이터베이스를 시각적으로 관리하고 쿼리하는 방법
CPU 및 메모리 리소스 확장을 위해 짧은 다운타임 유지보수 (LDTM)를 실행하는 방법

필요한 항목

경로 1: gcloud, kubectl, helm 유틸리티가 사전 설치된 Google Cloud Shell
경로 2: Kubernetes 클러스터에 연결된 kubectl 및 helm가 있는 터미널
참고 문서는 공식 AlloyDB Omni 배포 가이드를 참조하세요.

2. 설정 및 요구사항

Google Cloud 계정을 사용하여 GKE Autopilot 클러스터를 만드는 경우 경로 1을 선택하고, Google Cloud 계정 없이 자체 Kubernetes 클러스터를 사용하는 경우 경로 2를 선택합니다.

경로 1: Google Cloud 프로젝트 설정 (GKE Autopilot)

Google Cloud 콘솔에서 Google Cloud 프로젝트를 선택하거나 만듭니다.
프로젝트에 결제가 사용 설정되어 있는지 확인합니다. 결제 상태를 확인하는 방법을 알아보세요.
Google Cloud 콘솔의 오른쪽 상단에 있는 Cloud Shell 활성화 아이콘을 클릭하거나 shell.cloud.google.com으로 이동하여 Google Cloud Shell을 엽니다. Cloud Shell은 gcloud, kubectl, helm가 로드된 컴퓨팅 환경을 프로비저닝합니다.
프로젝트 ID를 환경 변수로 설정하고 gcloud를 구성합니다.

export PROJECT_ID="<YOUR_PROJECT_ID>"
export REGION="us-central1"
export CLUSTER_NAME="omni-autopilot-cluster"

gcloud config set project ${PROJECT_ID}
gcloud config set compute/region ${REGION}

GKE 및 Cloud Storage에 필요한 Google Cloud API를 사용 설정합니다.

gcloud services enable container.googleapis.com \
    storage.googleapis.com \
    cloudresourcemanager.googleapis.com

경로 2: 자체 클러스터 설정 (Google Cloud 계정 없음)

Google Cloud 계정이 없고 자체 Kubernetes 클러스터를 사용하는 경우 계속하기 전에 터미널에서 다음 기본 요건을 확인하세요.

kubectl 및 helm가 클러스터에 연결할 수 있고 노드가 Ready인지 확인합니다.

kubectl get nodes
helm version

클러스터에 (default)로 표시된 기본 StorageClass가 있는지 확인합니다. DBCluster 및 BackupPlan 매니페스트는 클러스터의 기본 StorageClass를 사용하여 PersistentVolumeClaim을 동적으로 프로비저닝합니다.

kubectl get storageclass

(default)로 표시된 StorageClass가 없으면 계속하기 전에 하나를 기본값으로 지정합니다.

kubectl patch storageclass <YOUR_STORAGE_CLASS_NAME> \
  -p '{"metadata": {"annotations":{"storageclass.kubernetes.io/is-default-class":"true"}}}'

워커 노드가 연산자의 하드웨어 및 OS 요구사항을 충족하는지 확인합니다.
- OS 및 커널: x86-64/AMD64 노드에서 cgroup v2가 사용 설정된 Linux 커널 4.18 이상
- 클러스터 용량: HA 데이터베이스 인스턴스 (12단계에서 각각 vCPU 2개 및 8GiB로 확장됨), PITR 클론 인스턴스, PgBouncer, pgAdmin4를 동시에 실행하려면 워커 노드에 최소 vCPU 8개 및 할당 가능한 메모리 24GiB가 있어야 합니다.
- 네트워크 액세스: gcr.io/alloydb-omni, quay.io/jetstack, docker.io에서 컨테이너 이미지를 가져오기 위한 아웃바운드 인터넷 액세스

3. Kubernetes 클러스터 프로비저닝 또는 연결

경로 1 (Google Cloud 계정)을 따르는 경우 GKE Autopilot은 Google에서 클러스터 인프라, 노드 프로비저닝, 자동 확장을 관리하는 완전 관리형 Kubernetes 모드를 제공합니다. Google Cloud CLI 또는 Google Cloud 콘솔을 사용하여 GKE Autopilot 클러스터를 만들 수 있습니다.

옵션 A: CLI를 통해 GKE Autopilot 클러스터 만들기 (경로 1)

Cloud Shell에서 다음 gcloud 명령어를 실행합니다.

gcloud container clusters create-auto ${CLUSTER_NAME} \
    --region=${REGION} \
    --project=${PROJECT_ID}

옵션 B: 콘솔을 통해 GKE Autopilot 클러스터 만들기 (경로 1)

Google Cloud 콘솔에서 Kubernetes Engine을 엽니다.
왼쪽 탐색창에서 클러스터를 클릭합니다.
만들기를 클릭합니다.
GKE Autopilot 섹션에서 구성을 클릭합니다.
클러스터 이름을 지정하고 (예: omni-autopilot-cluster) 원하는 리전 (us-central1)을 선택합니다.
만들기를 클릭합니다.

클러스터 연결 확인 (경로 1 및 경로 2)

경로 1에서 GKE Autopilot 클러스터를 만든 경우 kubectl 사용자 인증 정보를 구성합니다.

gcloud container clusters get-credentials ${CLUSTER_NAME} --region=${REGION} --project=${PROJECT_ID}

경로 1과 경로 2 모두에서 Kubernetes 클러스터에 대한 연결을 확인합니다.

kubectl get nodes

4. 연산자 기본 요건 및 연산자 설치

AlloyDB Omni Kubernetes 연산자는 허용 웹훅 TLS 인증서를 관리하기 위해 cert-manager가 필요합니다.

1. cert-manager 설치

공식 Helm 차트를 사용하여 cert-manager를 설치합니다.

helm install \
  cert-manager oci://quay.io/jetstack/charts/cert-manager \
  --version v1.21.2 \
  --namespace cert-manager \
  --create-namespace \
  --set crds.enabled=true \
  --set global.leaderElection.namespace=cert-manager

cert-manager 포드가 실행 중인지 확인합니다.

kubectl wait --namespace cert-manager \
  --for=condition=ready pod \
  --selector=app.kubernetes.io/instance=cert-manager \
  --timeout=120s

2. AlloyDB Omni 연산자 설치

Helm을 사용하여 AlloyDB Omni Kubernetes 연산자를 alloydb-omni-system 네임스페이스에 배포합니다.

helm install alloydbomni-operator oci://gcr.io/alloydb-omni/alloydbomni-operator \
  --version 1.8.2 \
  --create-namespace \
  --namespace alloydb-omni-system \
  $(helm install --help | grep -q -- '--rollback-on-failure' && echo '--rollback-on-failure' || echo '--atomic') \
  --timeout 5m

연산자 포드가 정상이고 실행 중인지 확인합니다.

kubectl get pods -n alloydb-omni-system

5. 단일 인스턴스 데이터베이스 클러스터 만들기

이 단계에서는 전용 애플리케이션 네임스페이스를 만들고 단일 인스턴스 AlloyDB Omni DBCluster를 배포합니다.

1. 네임스페이스 및 관리자 사용자 인증 정보 보안 비밀 만들기

데이터베이스 워크로드의 네임스페이스 omni-demo를 만듭니다.

kubectl create namespace omni-demo

기본 postgres 데이터베이스 관리자 사용자의 비밀번호를 저장하는 Kubernetes 보안 비밀을 만듭니다.

kubectl apply -n omni-demo -f - <<EOF
apiVersion: v1
kind: Secret
metadata:
  name: db-pw-adbo
type: Opaque
data:
  adbo: "Q2hhbmdlTWUxMjM=" # Base64 for "ChangeMe123"
EOF

2. 단일 인스턴스 DBCluster 배포

단일 인스턴스 DBCluster 매니페스트를 만듭니다.

kubectl apply -n omni-demo -f - <<EOF
apiVersion: alloydbomni.dbadmin.goog/v1
kind: DBCluster
metadata:
  name: adbo
spec:
  databaseVersion: "18.3.0"
  primarySpec:
    adminUser:
      passwordRef:
        name: db-pw-adbo
    resources:
      cpu: 1
      memory: 4Gi
      disks:
      - name: DataDisk
        size: 10Gi
EOF

3. 클러스터 준비 상태 확인

DBCLUSTERPHASE가 DBClusterReady에 도달할 때까지 클러스터 상태를 모니터링합니다. 초기 프로비저닝에는 몇 분 정도 걸릴 수 있습니다. 연산자가 영구 볼륨을 만들고 데이터베이스 이미지를 가져와야 하며 GKE Autopilot에서 새 노드를 먼저 프로비저닝해야 할 수 있습니다.

kubectl get dbcluster -n omni-demo -w

DBCLUSTERPHASE가 DBClusterReady에 도달하면 Ctrl+C를 눌러 감시 모드를 종료합니다.

샘플 출력:

NAME   PRIMARYENDPOINT   PRIMARYPHASE   DBCLUSTERPHASE   HAREADYSTATUS   HAREADYREASON
adbo   10.128.0.45       Ready          DBClusterReady

읽기-쓰기 Kubernetes 서비스 al-adbo-rw-ilb의 ClusterIP인 PRIMARYENDPOINT IP 주소를 기록해 둡니다. AlloyDB Omni는 기본 PostgreSQL 포트 5432에서 수신 대기합니다.

연산자가 단일 DBCluster 매니페스트에서 조정한 리소스(데이터베이스 포드, DataDisk PersistentVolumeClaim, al-adbo-rw-ilb 서비스)를 검사합니다.

kubectl get pods,svc,pvc -n omni-demo

6. 고가용성 (HA)으로 업그레이드 및 읽기 전용 대기 사용 설정

AlloyDB Omni는 스트리밍 복제, 자동 상태 모니터링, 자동 장애 조치, 읽기 복제본 서빙을 통해 기본 제공되는 고가용성 (HA)을 제공합니다.

1. HA 및 읽기 복제본 기능 사용 설정

DBCluster 사양을 업데이트하여 대기 인스턴스 1개를 구성하고 읽기 전용 대기 라우팅을 사용 설정합니다.

kubectl patch dbcluster adbo -n omni-demo --type=merge -p '{
  "spec": {
    "availability": {
      "numberOfStandbys": 1,
      "enableStandbyAsReadReplica": true
    }
  }
}'

2. HA 안정화 확인

대기 인스턴스가 프로비저닝되고 정상적인 스트리밍 복제에 도달할 때까지 기다린 후 (HAREADYSTATUS가 True에 도달하고 HAREADYREASON가 Ready에 도달) Ctrl+C를 눌러 감시 모드를 종료합니다.

kubectl get dbcluster adbo -n omni-demo -w

HAReady 상태 조건을 확인합니다.

kubectl get dbcluster.alloydbomni.dbadmin.goog adbo -n omni-demo -o jsonpath='{.status.conditions[?(@.type == "HAReady")]}'

읽기-쓰기 및 읽기 전용 엔드포인트가 모두 게시되었는지 확인합니다.

kubectl describe dbcluster adbo -n omni-demo | grep -A 8 "Endpoints:"

샘플 출력:

Endpoints:
  Name: Read-Write
  Value: 10.128.0.45:5432
  Name: Read-Only
  Value: 10.128.0.46:5432

읽기-쓰기 엔드포인트 (al-adbo-rw-ilb 서비스)는 기본 데이터베이스로 라우팅하고 읽기 전용 엔드포인트 (al-adbo-ro-ilb 서비스)는 대기 인스턴스 간에 읽기 쿼리를 분산합니다.

7. 자동 BackupPlan 구성 (로컬 및 GCS)

AlloyDB Omni는 BackupPlan 커스텀 리소스를 통해 물리적 백업 및 WAL 보관처리를 제공합니다. 백업 보관 기간, 자동화된 크론 일정, 백업 대상 (로컬 영구 볼륨 또는 Google Cloud Storage)을 구성할 수 있습니다.

1. 로컬 BackupPlan 만들기

데이터베이스 인스턴스에 연결된 로컬 Kubernetes 스토리지에 백업을 작성하는 BackupPlan를 만듭니다.

kubectl apply -n omni-demo -f - <<EOF
apiVersion: alloydbomni.dbadmin.goog/v1
kind: BackupPlan
metadata:
  name: backupplan-local
spec:
  dbclusterRef: adbo
  backupSchedules:
    full: "0 2 * * *" # Daily at 02:00 UTC
    incremental: "0 */4 * * *" # Every 4 hours
  backupRetainDays: 7
EOF

로컬 BackupPlan이 준비되었는지 확인합니다.

kubectl get backupplan backupplan-local -n omni-demo

PHASE가 Ready를 보고하고 NEXTBACKUPTIME가 예약될 때까지 기다립니다.

2. GCS BackupPlan 만들기 (경로 1: Google Cloud만 해당 — 선택사항)

백업을 Google Cloud Storage 버킷에 외부로 저장하려면 GCS 버킷을 만들고, 서비스 계정 키 보안 비밀을 구성하고, 클라우드 BackupPlan를 적용합니다.

Cloud Storage 버킷을 만듭니다.

export BUCKET_NAME="${PROJECT_ID}-omni-backups"
gcloud storage buckets create gs://${BUCKET_NAME} --location=${REGION}

스토리지 객체 관리자 권한이 있는 서비스 계정을 만들고 키를 만듭니다.

주의: AlloyDB Omni 연산자는 Kubernetes 보안 비밀에 저장하는 서비스 계정 키에서 Cloud Storage 사용자 인증 정보를 읽습니다. 운영자 문서에는 GKE용 워크로드 아이덴티티 제휴와 같은 다른 인증 방법이 설명되어 있지 않습니다. 조직에서 iam.disableServiceAccountKeyCreation 조직 정책을 시행하는 경우 keys create 명령어가 실패합니다. 이 경우 GCS BackupPlan 만들기의 나머지 부분을 건너뜁니다. 이 Codelab의 나머지 단계에서는 로컬 백업 계획을 사용합니다.

서비스 계정 키는 장기 사용자 인증 정보입니다. 다음 단계에서는 로컬 사본을 삭제하고 정리 단계에서는 서비스 계정과 해당 키를 삭제합니다. 자세한 내용은 Cloud Storage에 백업을 저장하는 계획 만들기를 참조하세요.

export SA_NAME="omni-backup-sa"
gcloud iam service-accounts create ${SA_NAME} --display-name="AlloyDB Omni Backup SA"

gcloud projects add-iam-policy-binding ${PROJECT_ID} \
  --member="serviceAccount:${SA_NAME}@${PROJECT_ID}.iam.gserviceaccount.com" \
  --role="roles/storage.objectAdmin"

gcloud iam service-accounts keys create /tmp/gcs-key.json \
  --iam-account="${SA_NAME}@${PROJECT_ID}.iam.gserviceaccount.com"

Kubernetes 네임스페이스에 보안 비밀을 만듭니다.

kubectl create secret generic gcs-backup-secret \
  --from-file=key.json=/tmp/gcs-key.json \
  -n omni-demo
rm /tmp/gcs-key.json

GCS BackupPlan 매니페스트를 적용합니다. key 필드는 연산자가 백업을 작성하는 버킷의 폴더입니다. /로 시작해야 합니다.

kubectl apply -n omni-demo -f - <<EOF
apiVersion: alloydbomni.dbadmin.goog/v1
kind: BackupPlan
metadata:
  name: backupplan-gcs
spec:
  dbclusterRef: adbo
  backupSchedules:
    full: "0 1 * * *"
    incremental: "0 */6 * * *"
  backupRetainDays: 14
  backupLocation:
    type: GCS
    gcsOptions:
      bucket: ${BUCKET_NAME}
      key: /omni-backups/adbo
      secretRef:
        name: gcs-backup-secret
        namespace: omni-demo
EOF

GCS BackupPlan 상태를 확인합니다.

kubectl get backupplan backupplan-gcs -n omni-demo

PHASE가 Ready를 보고하고 NEXTBACKUPTIME가 예약될 때까지 기다립니다.

8. 데이터 삽입, 백업 트리거, 복원 테스트

이 단계에서는 기본 데이터베이스에 초기 데이터를 채우고, 주문형 수동 백업을 트리거하고, 후속 데이터를 추가하고, 백업에서 복원하여 데이터 롤백을 증명합니다.

1. 초기 데이터 채우기

임시 PostgreSQL 클라이언트 포드를 실행하여 읽기-쓰기 서비스 al-adbo-rw-ilb를 통해 postgres 사용자로 데이터베이스에 연결합니다.

kubectl run pg-client --rm -i --tty --image=postgres:16 --restart=Never -n omni-demo -- \
  psql -h al-adbo-rw-ilb -U postgres -d postgres -c "
    CREATE TABLE customers (id SERIAL PRIMARY KEY, name TEXT, created_at TIMESTAMPTZ DEFAULT pg_catalog.now());
    INSERT INTO customers (name) VALUES ('Alpha Co'), ('Beta LLC');
    SELECT * FROM customers;
  "

비밀번호를 묻는 메시지가 표시되면 ChangeMe123를 입력합니다. 5단계에서 db-pw-adbo 보안 비밀에 base64로 인코딩한 비밀번호입니다.

2. 주문형 백업 트리거

로컬 BackupPlan를 참조하는 수동 Backup 커스텀 리소스를 만듭니다.

kubectl apply -n omni-demo -f - <<EOF
apiVersion: alloydbomni.dbadmin.goog/v1
kind: Backup
metadata:
  name: initial-customer-backup
spec:
  dbclusterRef: adbo
  backupPlanRef: backupplan-local
  manual: true
EOF

백업 진행 상황을 모니터링합니다.

kubectl get backup initial-customer-backup -n omni-demo -w

PHASE가 Succeeded로 전환될 때까지 기다립니다.

3. 데이터 변형 (새 레코드 추가)

백업 후 추가 레코드를 삽입합니다.

kubectl run pg-client --rm -i --tty --image=postgres:16 --restart=Never -n omni-demo \
  --env="PGPASSWORD=ChangeMe123" -- \
  psql -h al-adbo-rw-ilb -U postgres -d postgres -c "
    INSERT INTO customers (name) VALUES ('Gamma Inc'), ('Delta Corp');
    SELECT * FROM customers;
  "

이제 데이터베이스에 4개의 행이 포함됩니다.

4. 백업에서 복원

initial-customer-backup에서 캡처된 상태로 복원을 트리거합니다.

kubectl apply -n omni-demo -f - <<EOF
apiVersion: alloydbomni.dbadmin.goog/v1
kind: Restore
metadata:
  name: restore-to-initial
spec:
  sourceDBCluster: adbo
  backup: initial-customer-backup
EOF

복원 작업을 모니터링합니다.

kubectl get restore restore-to-initial -n omni-demo -w

PHASE가 ProvisionSucceeded에 도달할 때까지 기다린 후 DBCluster가 DBClusterReady로 돌아가는지 확인합니다.

kubectl get dbcluster adbo -n omni-demo -w

5. 복원된 데이터 상태 확인

customers 테이블을 쿼리하여 백업 전 레코드만 있는지 확인합니다.

kubectl run pg-client --rm -i --tty --image=postgres:16 --restart=Never -n omni-demo \
  --env="PGPASSWORD=ChangeMe123" -- \
  psql -h al-adbo-rw-ilb -U postgres -d postgres -c "
    SELECT * FROM customers;
  "

출력에 2개 행 (Alpha Co 및 Beta LLC)만 표시되어 데이터베이스가 정확한 백업 상태로 복원되었음을 확인할 수 있습니다.

9. 복제된 데이터베이스로 PITR (point-in-time recovery)

PITR (Point-In-Time Recovery)을 사용하면 기본 백업과 WAL 스트림 로그를 사용하여 복구 기간 내의 임의의 초로 데이터베이스를 복원하고 복원된 데이터를 새로 클론된 데이터베이스 클러스터에 프로비저닝할 수 있습니다.

운영자가 미리 쓰기 로그(WAL)를 지속적으로 보관처리하므로 PITR을 사용하면 실수(예: 오후 2시 15분 00초에 의도하지 않은 DELETE 또는 DROP TABLE)가 발생하기 정확히 1초 전(오후 2시 14분 59초)으로 데이터베이스를 클론하여 원래 클러스터를 건드리지 않고도 실수로 인한 사용자 또는 애플리케이션 오류를 복구할 수 있습니다.

1. 현재 타임스탬프 기록 및 데이터 변형

현재 UTC 타임스탬프를 가져옵니다.

export PITR_TIMESTAMP=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
echo "PITR Target Timestamp: ${PITR_TIMESTAMP}"

이 타임스탬프 이후에 원치 않는 수정을 나타내는 테스트 레코드를 삽입합니다.

kubectl run pg-client --rm -i --tty --image=postgres:16 --restart=Never -n omni-demo \
  --env="PGPASSWORD=ChangeMe123" -- \
  psql -h al-adbo-rw-ilb -U postgres -d postgres -c "
    INSERT INTO customers (name) VALUES ('Unwanted Record Post-Timestamp');
    SELECT * FROM customers;
  "

2. 특정 시점 복원 수행

pointInTime 및 clonedDBClusterConfig를 구성하는 Restore 커스텀 리소스를 적용합니다.

kubectl apply -n omni-demo -f - <<EOF
apiVersion: alloydbomni.dbadmin.goog/v1
kind: Restore
metadata:
  name: restore-pitr-clone
spec:
  sourceDBCluster: adbo
  pointInTime: "${PITR_TIMESTAMP}"
  clonedDBClusterConfig:
    dbclusterName: adbo-cloned
EOF

PHASE가 ProvisionSucceeded에 도달할 때까지 복원 작업을 모니터링합니다.

kubectl get restore restore-pitr-clone -n omni-demo -w

3. 클론된 데이터베이스 확인

복원이 완료되면 새로 클론된 DBCluster가 DBClusterReady에 도달할 때까지 기다립니다 (Ctrl+C를 눌러 감시 모드 종료).

kubectl get dbcluster adbo-cloned -n omni-demo -w

읽기-쓰기 서비스 al-adbo-cloned-rw-ilb를 통해 클론된 데이터베이스 adbo-cloned를 쿼리합니다.

kubectl run pg-client --rm -i --tty --image=postgres:16 --restart=Never -n omni-demo \
  --env="PGPASSWORD=ChangeMe123" -- \
  psql -h al-adbo-cloned-rw-ilb -U postgres -d postgres -c "
    SELECT * FROM customers;
  "

복제된 클러스터에 Unwanted Record Post-Timestamp가 없으므로 정확한 대상 시점으로 정확하게 복구되었음을 알 수 있습니다.

10. PgBouncer 연결 풀러 배포

연결 풀링은 데이터베이스 메모리 오버헤드와 연결 지연 시간을 줄여줍니다. 이 연산자는 PgBouncer 커스텀 리소스를 통해 PgBouncer 인스턴스를 기본적으로 관리합니다.

PostgreSQL은 모든 클라이언트 연결에 대해 별도의 운영체제 프로세스를 포크하므로 웹 서비스, 마이크로서비스 또는 AI 에이전트의 수백 개의 동시 연결로 인해 데이터베이스 메모리가 소진될 수 있습니다. PgBouncer는 데이터베이스 앞에 위치하며, 수명이 짧은 많은 클라이언트 연결 (최대 max_client_conn개)을 수명이 긴 PostgreSQL 서버 연결의 작은 풀 (사용자/데이터베이스 쌍당 default_pool_size개, max_db_connections개로 제한)로 멀티플렉싱합니다.

1. PgBouncer 배포

클러스터 adbo에 연결된 복제본 2개 PgBouncer 풀러를 배포합니다.

kubectl apply -n omni-demo -f - <<EOF
apiVersion: alloydbomni.dbadmin.goog/v1
kind: PgBouncer
metadata:
  name: omni-pgbouncer
spec:
  dbclusterRef: adbo
  allowSuperUserAccess: true
  replicaCount: 2
  parameters:
    pool_mode: transaction
    default_pool_size: "20"
    max_client_conn: "500"
    max_db_connections: "100"
  podSpec:
    resources:
      cpu: 1
      memory: 1Gi
    image: "gcr.io/alloydb-omni/operator/g-pgbouncer:1.4.0"
  serviceOptions:
    type: ClusterIP
EOF

2. PgBouncer 상태 확인

PHASE가 Ready가 될 때까지 PgBouncer 상태를 확인합니다.

kubectl get pgbouncer omni-pgbouncer -n omni-demo -w

실행 중인 PgBouncer 포드 및 서비스를 확인합니다.

kubectl get pods -n omni-demo
kubectl get svc al-omni-pgbouncer-pgb-svc -n omni-demo

3. PgBouncer를 통해 연결

포트 6432에서 PgBouncer 서비스를 통해 클라이언트를 연결합니다.

kubectl run pg-client --rm -i --tty --image=postgres:16 --restart=Never -n omni-demo \
  --env="PGPASSWORD=ChangeMe123" -- \
  psql -h al-omni-pgbouncer-pgb-svc -p 6432 -U postgres -d postgres -c "
    SELECT pg_catalog.version();
    SELECT * FROM customers;
  "

PgBouncer는 쿼리를 기본 AlloyDB Omni 데이터베이스로 원활하게 프록시합니다.

11. pgAdmin4를 배포하여 데이터베이스에 액세스

Kubernetes 클러스터 내에서 직접 pgAdmin4를 실행하여 AlloyDB Omni를 쿼리, 관리, 검사할 수 있는 웹 기반 관리 콘솔을 제공할 수 있습니다.

1. Helm을 통해 pgAdmin4 설치

omni-demo 네임스페이스에 pgadmin4를 설치합니다.

helm install my-pgadmin oci://docker.io/dpage/pgadmin4-helm \
  --namespace omni-demo \
  --set ingress.enabled=false \
  --set image.tag=latest \
  --set auth.email="admin@example.com" \
  --set auth.password="AdminPassword123"

이 차트는 Helm 출시 버전 이름 (my-pgadmin)과 관계없이 Kubernetes 리소스 pgadmin4 (배포, 서비스, PersistentVolumeClaim)의 이름을 지정하고 포드에 app=pgadmin4 라벨을 지정합니다.

pgAdmin4 포드가 실행 중인지 확인합니다.

kubectl wait --namespace omni-demo \
  --for=condition=ready pod \
  --selector=app=pgadmin4 \
  --timeout=300s

2. 포트 전달 및 웹 UI 액세스

pgAdmin4를 로컬 환경 또는 Cloud Shell로 포트 전달합니다.

kubectl port-forward service/pgadmin4 5050:80 -n omni-demo

pgAdmin4 웹 UI를 사용하는 동안 kubectl port-forward가 포그라운드에서 계속 실행됩니다. 다른 명령어를 위해 두 번째 터미널 (또는 새 Cloud Shell 탭)을 열고 다음 단계로 진행할 준비가 되면 이 터미널에서 Ctrl+C를 누릅니다.

pgAdmin4 웹 인터페이스를 엽니다.

경로 1 (Google Cloud Shell): 오른쪽 상단 메뉴에서 웹 미리보기 버튼을 클릭하고 포트 변경을 선택한 후 5050을 입력하고 변경 및 미리보기를 클릭합니다.
경로 2 (로컬 워크스테이션): kubectl port-forward 명령어가 실행되는 동안 브라우저에서 http://localhost:5050를 엽니다.

다음 계정으로 로그인:

이메일: admin@example.com
비밀번호: AdminPassword123

3. pgAdmin4에 AlloyDB Omni 등록

pgAdmin4에서 서버 > 등록 > 서버…를 마우스 오른쪽 버튼으로 클릭합니다.
일반 탭에서 다음을 수행합니다.
- 이름: AlloyDB Omni Primary
<b style="font-weight: bold;">연결 탭에서 다음 단계를 따릅니다.
- 호스트 이름/주소: al-adbo-rw-ilb.omni-demo.svc.cluster.local (또는 PgBouncer의 경우 al-omni-pgbouncer-pgb-svc.omni-demo.svc.cluster.local)
- 포트: 5432 (또는 PgBouncer의 경우 6432)
- 유지보수 데이터베이스: postgres
- 사용자 이름: postgres
- 비밀번호: ChangeMe123
저장을 클릭하고 활성 데이터베이스 세션과 테이블을 확인합니다.

12. 짧은 다운타임 유지보수 (LDTM)로 CPU 및 메모리 확장

프로덕션 데이터베이스에서 컴퓨팅 및 메모리를 수직 확장할 때 기존 업데이트로 인해 데이터베이스가 다시 시작되어 중단이 발생합니다. AlloyDB Omni는 애플리케이션 중단을 최소화하면서 복제본을 통해 업데이트를 적용하는 짧은 다운타임 유지보수 (LDTM)를 제공합니다.

1. LDTM 주석 사용 설정

DBCluster에 주석을 추가하여 업데이트에 LDTM을 사용 설정합니다.

kubectl annotate dbclusters.alloydbomni.dbadmin.goog adbo -n omni-demo dbcluster.dbadmin.goog/enableLDTM=true --overwrite

2. CPU 및 메모리 리소스 확장

기본 리소스를 cpu: 1, memory: 4Gi에서 cpu: 2, memory: 8Gi로 업데이트합니다.

kubectl patch dbcluster adbo -n omni-demo --type=merge -p '{
  "spec": {
    "primarySpec": {
      "resources": {
        "cpu": 2,
        "memory": "8Gi"
      }
    }
  }
}'

3. LDTM 확장 진행 상황 모니터링

순차적 업데이트 및 대기에서 기본으로 전환 조건을 모니터링합니다.

kubectl get dbcluster adbo -n omni-demo -o yaml | grep -A 5 -B 2 "LDTMScalingInProgress"

포드가 정상적으로 순환되는지 관찰합니다.

kubectl get pods -n omni-demo -w

LDTM은 업데이트된 대기 인스턴스를 먼저 준비하고, 스트리밍 복제를 확인하고, 빠른 전환을 실행하고, 서비스 중단 없이 나머지 인스턴스를 업데이트합니다.

업데이트된 리소스 할당을 확인합니다.

kubectl get dbcluster adbo -n omni-demo -o jsonpath='{.spec.primarySpec.resources}'

13. 리소스 삭제

클러스터 용량을 확보하고 Google Cloud 계정에 불필요한 요금이 청구되지 않도록 하려면 이 Codelab에서 프로비저닝한 리소스를 삭제하세요.

새 터미널 세션 (경로 1)에서 삭제를 실행하는 경우 이전 단계의 환경 변수가 더 이상 설정되지 않습니다. 이전에 사용한 것과 동일한 값으로 다시 내보냅니다.

export PROJECT_ID="<YOUR_PROJECT_ID>"
export REGION="us-central1"
export CLUSTER_NAME="omni-autopilot-cluster"
export BUCKET_NAME="${PROJECT_ID}-omni-backups"
export SA_NAME="omni-backup-sa"
gcloud config set project ${PROJECT_ID}

1. 데이터베이스 워크로드 삭제 (경로 1 및 경로 2)

허용 웹훅 검사를 통과하도록 두 클러스터를 모두 삭제된 것으로 표시하고, 오퍼레이터가 DBCluster 리소스를 삭제할 때까지 기다린 후 네임스페이스를 삭제합니다.

kubectl patch dbcluster adbo -n omni-demo --type=merge -p '{"spec":{"isDeleted":true}}'
kubectl patch dbcluster adbo-cloned -n omni-demo --type=merge -p '{"spec":{"isDeleted":true}}'
kubectl wait --for=delete dbcluster/adbo dbcluster/adbo-cloned -n omni-demo --timeout=300s
kubectl delete namespace omni-demo

자체 Kubernetes 클러스터 (경로 2)를 사용했고 AlloyDB Omni 연산자와 cert-manager도 삭제하려는 경우:

helm uninstall alloydbomni-operator -n alloydb-omni-system
kubectl delete namespace alloydb-omni-system
helm uninstall cert-manager -n cert-manager
kubectl delete namespace cert-manager

2. GCS 버킷 및 IAM 서비스 계정 삭제 (경로 1만 해당)

경로 1에서 Google Cloud Storage 버킷과 서비스 계정을 만든 경우:

gcloud storage rm --recursive gs://${BUCKET_NAME}
gcloud projects remove-iam-policy-binding ${PROJECT_ID} \
  --member="serviceAccount:${SA_NAME}@${PROJECT_ID}.iam.gserviceaccount.com" \
  --role="roles/storage.objectAdmin"
gcloud iam service-accounts delete ${SA_NAME}@${PROJECT_ID}.iam.gserviceaccount.com --quiet

3. GKE 클러스터 삭제 (경로 1만 해당)

경로 1에서 GKE Autopilot 클러스터를 프로비저닝한 경우:

gcloud container clusters delete ${CLUSTER_NAME} --region=${REGION} --quiet

14. 축하합니다

수고하셨습니다 Kubernetes에서 AlloyDB Omni Codelab을 완료했습니다.

학습한 내용

GKE Autopilot 클러스터를 프로비저닝 (경로 1)하거나 기존 Kubernetes 클러스터를 준비 (경로 2)했습니다.
Helm을 통해 cert-manager 및 AlloyDB Omni Kubernetes 연산자를 배포했습니다.
단일 인스턴스 AlloyDB Omni DBCluster를 배포했습니다.
동기식 대기 모드를 사용하여 클러스터를 고가용성 (HA)으로 업그레이드하고 읽기 전용 대기 라우팅을 사용 설정했습니다.
로컬 영구 스토리지와 Google Cloud Storage (GCS) 모두에 대해 자동화된 BackupPlan 리소스를 만들었습니다.
주문형 백업을 수행하고 데이터베이스 복원을 검증했습니다.
새로 클론된 데이터베이스 클러스터에 PITR (point-in-time recovery)을 실행했습니다.
확장 가능한 클라이언트 연결을 위해 PgBouncer 연결 풀러를 배포했습니다.
데이터베이스 관리를 위해 pgAdmin4를 배포하고 연결했습니다.
짧은 다운타임 유지보수 (LDTM)를 실행하여 컴퓨팅 및 메모리 리소스를 동적으로 확장했습니다.

다음 단계

멀티 클러스터 환경에서 AlloyDB Omni 재해 복구 (DR)를 살펴봅니다.
AlloyDB Omni AI 및 pgvector 기능 자세히 알아보기

15. 설문조사

본 가이드를 어떻게 사용하실 계획인가요?

읽기만 할 계획입니다.

읽은 다음 연습 활동을 완료할 계획입니다.