在 Kubernetes（GKE 或自带集群）上部署和管理 AlloyDB Omni

1. 简介

在此 Codelab 中，您将学习如何在 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 沙盒（如果您还没有集群）。

选择环境路径

您可以通过以下两种路径之一完成此 Codelab：

1. 路径 1：拥有 Google Cloud 账号 (GKE Autopilot) - 使用 Google Cloud Shell 或 Google Cloud 控制台预配全托管式 GKE Autopilot 集群。
2. 路径 2：没有 Google Cloud 账号（自带 Kubernetes 集群）- 使用现有 Kubernetes 集群（v1.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 集群，具有用于动态 PersistentVolume 预配的默认 StorageClass。
  • 运行 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：使用预安装了 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)

1. 在 Google Cloud 控制台中，选择或创建 Google Cloud 项目。
2. 确认您的项目已启用结算功能。了解如何验证结算状态。
3. 点击 Google Cloud 控制台右上角的激活 Cloud Shell 图标，或访问 shell.cloud.google.com，打开 Google Cloud Shell。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. 确认您的工作器节点满足操作器的硬件和操作系统要求：
   • 操作系统和内核：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. 在左侧导航窗格中，点击集群。
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 来管理准入网络钩子 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 操作器

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

验证 Operator 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。初始预配可能需要几分钟时间：Operator 必须创建永久性卷并拉取数据库映像，而在 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。

检查 Operator 从单个 DBCluster 清单中协调的资源：数据库 Pod、DataDisk PersistentVolumeClaim 和 al-adbo-rw-ilb Service：

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. 配置自动 BackupPlan（本地和 GCS）

AlloyDB Omni 通过 BackupPlan 自定义资源提供物理备份和 WAL 归档。您可以配置备份保留、自动 Cron 时间表和备份目标（本地永久性卷或 Google Cloud Storage）。

1. 创建本地 BackupPlan

创建一个 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 - 可选）

在没有 Google Cloud 账号的情况下使用自己的 Kubernetes 集群（路径 2）？跳过2. 创建 GCS BackupPlan，然后直接执行下一步。此 Codelab 中所有剩余的备份和时间点恢复练习都使用上一部分中的 backupplan-local。

如需将备份存储在外部 Google Cloud Storage 存储桶中，请创建一个 GCS 存储桶，配置服务账号密钥 Secret，然后应用云 BackupPlan。

1. 创建 Cloud Storage 存储桶，请运行以下命令：

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

2. 创建一个具有 Storage Object Admin 管理员权限的服务账号，并为其创建密钥：

注意：AlloyDB Omni 操作器会从您存储在 Kubernetes Secret 中的服务账号密钥中读取 Cloud Storage 凭据。该 Operator 的文档未涵盖其他身份验证方式，例如 Workload Identity Federation for 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"

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，以 postgres 用户身份通过其读写服务 al-adbo-rw-ilb 连接到数据库：

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 编码的密码。

注意：此 Codelab 中的其余 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. 更改数据（添加新记录）

在备份后插入其他记录：

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 流日志将数据库恢复到恢复窗口内的任意秒，并将恢复的数据预配到新的克隆数据库集群中。

由于该 Operator 会持续归档预写式日志 (WAL)，因此 PITR 可让您从意外的人为错误或应用错误（例如，下午 2:15:00 意外执行了 DELETE 或 DROP TABLE）中恢复，方法是将数据库克隆到错误发生前的确切秒数（下午 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. 执行时间点恢复

注意：Operator 会在与源集群 omni-demo 相同的命名空间中创建克隆的 DBCluster。不支持克隆到其他命名空间。如需了解详情，请参阅从某个时间点克隆集群。

应用配置 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

通过克隆数据库 adbo-cloned 的读写 Service al-adbo-cloned-rw-ilb 查询该数据库：

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 会为每个客户端连接派生一个单独的操作系统进程，因此来自 Web 服务、微服务或 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 状态

观察 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，以提供基于 Web 的管理控制台，用于查询、管理和检查 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"

此图表将其 Kubernetes 资源命名为 pgadmin4（Deployment、Service、PersistentVolumeClaim），并使用 app=pgadmin4 为其 Pod 添加标签，而不管 Helm 版本名称 (my-pgadmin) 是什么。

验证 pgAdmin4 pod 是否正在运行：

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

2. 转发端口并访问 Web 界面

将 pgAdmin4 通过端口转发到您的本地环境或 Cloud Shell：

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

只要您使用 pgAdmin4 Web 界面，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 中，右键点击服务器 > 注册 > 服务器…。
2. 在常规标签页下：
   • 名称：AlloyDB Omni Primary
3. 在连接标签页下：
   • 主机名/地址：al-adbo-rw-ilb.omni-demo.svc.cluster.local（或 al-omni-pgbouncer-pgb-svc.omni-demo.svc.cluster.local，适用于 PgBouncer）
   • 端口：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 账号产生不必要的费用，请清理在此 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）

将两个集群都标记为已删除，以通过准入 webhook 检查，等待 Operator 移除 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)。
• 部署了 PgBouncer 连接池程序，以实现可扩缩的客户端连接。
• 已部署并连接 pgAdmin4 以进行数据库管理。
• 执行了低停机时间维护 (LDTM)，以动态扩缩计算和内存资源。

后续步骤

• 探索多集群环境中的 AlloyDB Omni 灾难恢复 (DR)。
• 详细了解 AlloyDB Omni AI 和 pgvector 功能。

15. 调查问卷

您打算如何使用本教程？

仅通读 阅读并完成练习