在 Kubernetes (GKE 或自備叢集) 部署及管理 AlloyDB Omni

1. 簡介

在本程式碼實驗室中，您將瞭解如何在 Google Kubernetes Engine (GKE) Autopilot 叢集或自己的 Kubernetes 叢集上，安裝 AlloyDB Omni Kubernetes 運算子 (容器自動調度管理工具)，並管理完整的端對端資料庫生命週期工作流程和關鍵使用者歷程 (CUJ)。

AlloyDB Omni 是 AlloyDB 的可下載版本，可在任何位置執行，包括地端部署環境、Google Cloud 或邊緣運算。AlloyDB Omni 搭配容器自動調度管理工具，可自動執行高可用性、自動容錯移轉、自我修復、滾動式維護 (停機時間極短)、連線集區、自動備份和時間點復原。

AlloyDB for PostgreSQL 與 AlloyDB Omni：AlloyDB for PostgreSQL 是 Google Cloud 的全代管資料庫服務。AlloyDB Omni 將相同的 AlloyDB 資料庫引擎封裝成可下載的容器，讓您自行在地端部署、其他公有雲 (例如 Amazon EKS 或 Azure AKS)、OpenShift 或開發人員工作站上執行及操作，滿足資料落地、混合雲或本機開發需求。在實際部署作業中，您通常會在自己的 Kubernetes 叢集上執行 AlloyDB Omni Kubernetes 運算子 (路徑 2)。路徑 1：如果您還沒有叢集，可以將 GKE Autopilot 當做便利、不需在本機設定的 Kubernetes 沙箱。

選擇環境路徑

您可以透過下列任一方式完成本程式碼實驗室：

1. 路徑 1：擁有 Google Cloud 帳戶 (GKE Autopilot) - 使用 Google Cloud Shell 或 Google Cloud 控制台，佈建全代管 GKE Autopilot 叢集。
2. 路徑 2：沒有 Google Cloud 帳戶 (自備 Kubernetes 叢集)：使用現有的 Kubernetes 叢集 (1.21 以上版本)，並在工作站上設定 kubectl 和 helm。無須 Google Cloud 帳戶或 gcloud CLI。

必要條件

• 對 Kubernetes 概念有基本瞭解 (kubectl、Helm、自訂資源定義)。
• 路徑 1 (Google Cloud / GKE Autopilot)：
  • 已啟用計費功能的 Google Cloud 專案。
  • 可存取 Google Cloud Shell 或已設定 gcloud、kubectl 和 helm 的工作站。
• 路徑 2 (自備 Kubernetes 叢集)：
  • 執行 1.21 以上版本的 Kubernetes 叢集，並具備預設 StorageClass，可動態佈建 PersistentVolume。
  • worker 節點執行 Linux 核心 4.18 以上版本，並啟用 cgroup v2 (x86-64/AMD64)，且整個叢集至少有 8 個 vCPU 和 24 GiB 的可分配 RAM。
  • 已設定 kubectl 和 helm 的工作站，並已連線至叢集。

課程內容

• 如何佈建 GKE Autopilot 叢集 (路徑 1) 或驗證現有的 Kubernetes 叢集 (路徑 2)。
• 如何透過 Helm 安裝 cert-manager 和 AlloyDB Omni Kubernetes 運算子。
• 如何部署單一執行個體 AlloyDB Omni DBCluster。
• 如何透過同步待命功能擴充至高可用性 (HA)，並啟用唯讀待命功能。
• 如何設定排定的自動備份，將資料備份至本機存放區 (以及路徑 1 的 Google Cloud Storage，此為選用)。
• 如何執行隨選備份，並驗證資料是否還原至先前的狀態。
• 如何對新的複製資料庫叢集執行時間點復原 (PITR)。
• 如何部署 PgBouncer 連線集區，以便調度用戶端連線資源。
• 如何部署 pgAdmin4，以視覺化方式管理及查詢資料庫。
• 如何執行低停機時間維護 (LDTM)，調整 CPU 和記憶體資源。

軟硬體需求

• 路徑 1：Google Cloud Shell，預先安裝 gcloud、kubectl 和 helm 公用程式。
• 路徑 2：已安裝 kubectl 和 helm，並連線至 Kubernetes 叢集的終端機。
• 如需參考文件，請參閱官方 AlloyDB Omni 部署指南。

2. 設定和需求

如果您使用 Google Cloud 帳戶建立 GKE Autopilot 叢集，請選擇路徑 1；如果您使用自己的 Kubernetes 叢集，但沒有 Google Cloud 帳戶，請選擇路徑 2。

路徑 1：設定 Google Cloud 雲端專案 (GKE Autopilot)

1. 在 Google Cloud 控制台中，選取或建立 Google Cloud 專案。
2. 確認專案已啟用計費功能。瞭解如何驗證帳單狀態。
3. 如要開啟 Google Cloud Shell，請按一下 Google Cloud 控制台右上角的「啟用 Cloud Shell」圖示，或前往 shell.cloud.google.com。Cloud Shell 會佈建已載入 gcloud、kubectl 和 helm 的運算環境。
4. 將專案 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}

5. 啟用 GKE 和 Cloud Storage 必要的 Google Cloud API：

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

路徑 2：自備叢集設定 (沒有 Google Cloud 帳戶)

如果您沒有 Google Cloud 帳戶，且使用自己的 Kubernetes 叢集，請先在終端機中確認下列必要條件，再繼續操作：

1. 確認 kubectl 和 helm 可以連上叢集，且節點為 Ready：

kubectl get nodes
helm version

2. 確認叢集有標示為 (default) 的預設StorageClass。DBCluster 和 BackupPlan 資訊清單會使用叢集的預設 StorageClass 動態佈建 PersistentVolumeClaim：

kubectl get storageclass

如果沒有任何 StorageClass 標示為 (default)，請先指定一個預設值，再繼續操作：

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

3. 確認 worker 節點符合運算子的硬體和 OS 需求：
   • OS 和核心：Linux 核心 4.18 以上版本，且在 x86-64/AMD64 節點上啟用 cgroup v2。
   • 叢集容量：工作站節點至少要有 8 個 vCPU 和 24 GiB 的可分配記憶體，才能同時執行高可用性資料庫執行個體 (在步驟 12 調整為 2 個 vCPU 和 8 GiB)、PITR 複製執行個體、PgBouncer 和 pgAdmin4。
   • 網路存取權：可連上網際網路，從 gcr.io/alloydb-omni、quay.io/jetstack 和 docker.io 提取容器映像檔。

3. 佈建或連線至 Kubernetes 叢集

使用自己的 Kubernetes 叢集 (路徑 2)？略過下方的選項 A 和選項 B，在「驗證叢集連線能力」下方確認叢集節點為 Ready，然後直接前往下一個步驟。

如果您選擇路徑 1 (Google Cloud 帳戶)，GKE Autopilot 會提供全代管的 Kubernetes 模式，由 Google 管理叢集基礎架構、節點佈建和自動調度資源，您不需手動操作。您可以使用 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)

1. 在 Google Cloud 控制台中開啟「Kubernetes Engine」。
2. 按一下左側導覽窗格中的「Clusters」(叢集)。
3. 點選「建立」。
4. 在「GKE Autopilot」部分，按一下「設定」。
5. 指定叢集名稱 (例如 omni-autopilot-cluster)，並選取偏好的區域 (us-central1)。
6. 點選「建立」。

驗證叢集連線能力 (路徑 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. 安裝 Operator 必要條件和 Operator

AlloyDB Omni Kubernetes 運算子需要 cert-manager，才能管理准入 Webhook TLS 憑證。

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 Pod 正在執行：

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

2. 安裝 AlloyDB Omni Operator

使用 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

確認運算子 Pod 運作正常且正在執行：

kubectl get pods -n alloydb-omni-system

5. 建立單一執行個體資料庫叢集

在這個步驟中，您將建立專屬的應用程式命名空間，並部署單一執行個體 AlloyDB Omni DBCluster。

1. 建立命名空間和管理員憑證 Secret

建立資料庫工作負載的命名空間 omni-demo：

kubectl create namespace omni-demo

建立 Kubernetes Secret，儲存預設 postgres 資料庫管理員使用者的密碼：

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

請記下 PRIMARYENDPOINT IP 位址，這是讀寫 Kubernetes Service al-adbo-rw-ilb 的 ClusterIP。AlloyDB Omni 會監聽預設的 PostgreSQL 通訊埠 5432。

檢查運算子從單一 DBCluster 資訊清單中協調的資源，包括資料庫 Pod、DataDisk PersistentVolumeClaim 和 al-adbo-rw-ilb 服務：

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

6. 升級至高可用性 (HA) 並啟用唯讀待命

AlloyDB Omni 內建高可用性 (HA) 功能，可串流複製、自動監控健康狀態、自動容錯移轉，以及提供唯讀副本。

1. 啟用高可用性和唯讀副本功能

更新 DBCluster 規格，設定 1 個待命執行個體，並啟用唯讀待命轉送功能：

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

2. 驗證高可用性穩定性

等待待命執行個體佈建完成，並達到良好的串流複製狀態 (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. 設定自動備份方案 (本機和 GCS)

AlloyDB Omni 透過 BackupPlan 自訂資源提供實體備份和 WAL 封存功能。您可以設定備份保留、自動化 Cron 排程和備份目標 (本機永久磁碟區或 Google Cloud Storage)。

1. 建立本機備份方案

建立 BackupPlan，將備份寫入附加至資料庫執行個體的本機 Kubernetes 儲存空間：

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 備份計畫 (路徑 1：僅限 Google Cloud - 選用)

使用自己的 Kubernetes 叢集，但沒有 Google Cloud 帳戶 (路徑 2)？略過2. Create GCS BackupPlan，然後直接前往下一個步驟。本程式碼實驗室中所有剩餘的備份和時間點復原練習，都會使用上一節的 backupplan-local。

如要將備份儲存在外部的 Google Cloud Storage bucket，請建立 GCS bucket、設定服務帳戶金鑰密鑰，並套用雲端 BackupPlan。

1. 建立 Cloud Storage bucket：

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

2. 建立具備 Storage 物件管理員權限的服務帳戶，並為其建立金鑰：

注意：AlloyDB Omni operator 會從您儲存在 Kubernetes Secret 的服務帳戶金鑰，讀取 Cloud Storage 憑證。運算子的說明文件並未涵蓋其他驗證方式，例如 Workload Identity Federation for GKE。如果組織強制執行 iam.disableServiceAccountKeyCreation 組織政策，keys create 指令就會失敗。在這種情況下，請略過「建立 GCS BackupPlan」的其餘部分。本程式碼實驗室的其餘步驟會使用本機備份方案。

服務帳戶金鑰是長效憑證。下一個步驟會刪除本機副本，而清除步驟會刪除服務帳戶及其金鑰。詳情請參閱「建立將備份儲存在 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"

3. 在 Kubernetes 命名空間中建立 Secret：

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

4. 套用 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 用戶端 Pod，透過讀寫 Service 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 Secret 進行 Base64 編碼的密碼。

注意：本程式碼實驗室中的其餘 kubectl run pg-client 指令會傳遞 --env="PGPASSWORD=ChangeMe123"，因此 psql 會在沒有互動式提示的情況下進行驗證。這只是為了方便示範，請勿在指令列中輸入正式環境密碼。

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. Mutate Data (Add New Records)

在備份後插入其他記錄：

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) 並複製

時間點復原 (PITR) 功能可使用基礎備份和 WAL 串流記錄，將資料庫還原至復原期間內的任何一秒，並將還原的資料佈建至新的複製資料庫叢集。

由於運算子會持續封存預寫記錄 (WAL)，因此 PITR 可讓您從意外的人為或應用程式錯誤中復原，例如下午 2:15:00 發生非預期的 DELETE 或 DROP TABLE，只要將資料庫複製到錯誤發生前的確切秒數 (下午 2:14:59)，即可復原，而且不會影響原始叢集。

1. 記錄目前的時間戳記並變動資料

擷取目前的世界標準時間戳記：

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. 執行時間點還原

注意：運算子會在與來源叢集 omni-demo 相同的命名空間中，建立複製的 DBCluster。不支援複製到其他命名空間。詳情請參閱「從特定時間點複製叢集」。

套用 Restore 自訂資源，設定 pointInTime 和 clonedDBClusterConfig：

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 連線集區

連線集區可減少資料庫記憶體負擔和連線延遲時間。operator 會透過 PgBouncer 自訂資源，以原生方式管理 PgBouncer 執行個體。

PostgreSQL 會為每個用戶端連線建立獨立的作業系統程序，因此來自網路服務、微服務或 AI 代理的數百個並行連線，可能會耗盡資料庫記憶體。PgBouncer 位於資料庫前端，會將多個短期用戶端連線 (最多 max_client_conn 個) 多工處理至一小組長期 PostgreSQL 伺服器連線 (每個使用者/資料庫組合 default_pool_size 個，上限為 max_db_connections 個)。

1. 部署 PgBouncer

部署 2 個副本的 PgBouncer 集區，並連結至叢集 adbo：

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 狀態

觀察 PgBouncer 狀態，直到 PHASE 變成 Ready：

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

檢查執行中的 PgBouncer Pod 和服務：

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="[e-mail]" \
  --set auth.password="AdminPassword123"

無論 Helm 版本名稱 (my-pgadmin) 為何，這個圖表都會將 Kubernetes 資源命名為 pgadmin4 (Deployment、Service、PersistentVolumeClaim)，並將 Pod 標示為 app=pgadmin4。

確認 pgAdmin4 Pod 正在運作：

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。

登入方式：

• 電子郵件地址：[e-mail]
• 密碼：AdminPassword123

3. 在 pgAdmin4 中註冊 AlloyDB Omni

1. 在 pgAdmin4 中，依序在「Servers」上按一下滑鼠右鍵 >「Register」 >「Server...」。
2. 在「一般」分頁下方：
   • Name (名稱)：AlloyDB Omni Primary
3. 在「連線」分頁下：
   • Host name/address：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
4. 按一下「儲存」，然後驗證使用中的資料庫工作階段和資料表。

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"

觀察 Pod 順利滾動：

kubectl get pods -n omni-demo -w

LDTM 會先準備更新後的待命執行個體、驗證串流複製作業、執行快速切換，並在不中斷服務的情況下更新其餘執行個體。

確認更新後的資源分配：

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

13. 清除資源

為釋出叢集容量，並避免 Google Cloud 帳戶產生不必要的費用，請清除本程式碼實驗室期間佈建的資源。

如果您是在新的終端機工作階段 (路徑 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)

將兩個叢集標示為已刪除，以便通過准入 Webhook 檢查，等待運算子移除 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 operator 和 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 bucket 和 IAM 服務帳戶 (僅限路徑 1)

如果您在路徑 1 建立了 Google Cloud Storage bucket 和服務帳戶：

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」程式碼實驗室。

涵蓋內容

• 佈建 GKE Autopilot 叢集 (路徑 1)，或準備現有的 Kubernetes 叢集 (路徑 2)。
• 已透過 Helm 部署 cert-manager 和 AlloyDB Omni Kubernetes 運算子。
• 部署單一執行個體 AlloyDB Omni DBCluster。
• 將叢集升級為高可用性 (HA) 叢集，並啟用同步待命和唯讀待命轉送功能。
• 為本機永久儲存空間和 Google Cloud Storage (GCS) 建立自動化 BackupPlan 資源。
• 執行隨選備份，並驗證資料庫還原作業。
• 執行時間點復原 (PITR)，將資料還原至新的複製資料庫叢集。
• 部署 PgBouncer 連線集區，以便擴充用戶端連線。
• 部署並連結 pgAdmin4，以便管理資料庫。
• 執行低停機時間維護 (LDTM)，動態調度運算和記憶體資源。

後續步驟

• 探索多叢集環境中的 AlloyDB Omni 災難復原 (DR)。
• 進一步瞭解 AlloyDB Omni AI 和 pgvector 功能。

15. 問卷調查

您會如何使用這個教學課程？

只閱讀內容 閱讀內容並完成練習