快速入门:15 分钟创建您的第一个 PostgreSQL 集群

本教程将引导您从全新安装 Alauda Data Services Relational Database E3 operator 开始,直至运行一个包含 3 个实例且已配置备份的 PostgreSQL 集群。每个部分只需几分钟;如果集群响应正常,整个流程大约需要 15 分钟。

先决条件(5 分钟)

您需要:

  1. 一个运行 Kubernetes 1.30+ 的 ACP 托管集群,并且:
    • 一个默认的块模式 StorageClass(通常是 topolvm 类;使用 kubectl get sc 验证)。
    • 已安装 cert-manager(Barman Cloud 备份插件的 TLS 先决条件)。使用 kubectl api-resources --api-group=cert-manager.io 验证。如果尚未安装,请先通过 Marketplace 安装,再继续操作。
  2. 集群管理员或平台管理员访问权限,用于执行安装步骤。 第 2 天运维(创建集群、备份)只需拥有目标命名空间的管理员权限。
  3. 为目标集群配置好 kubectl(最简单的方式是使用 ACP Web 控制台中的 Download kubeconfig 操作)。
  4. 一个兼容 S3 的对象存储,用于存放备份(MinIO、Ceph RGW 或集群可访问的任何 S3 端点),并准备好访问密钥以及可写入的存储桶。

如果尚未安装 operator,请先阅读安装,待 CSV 处于 Succeeded 状态后再返回此处。

步骤 1 — 安装 operator(3 分钟)

如果您已按照安装中的说明操作,请跳过此步骤。

# install.yaml
apiVersion: v1
kind: Namespace
metadata:
  name: cnpg-system
---
apiVersion: operators.coreos.com/v1
kind: OperatorGroup
metadata:
  name: cnpg-system-og
  namespace: cnpg-system
spec: {}
---
apiVersion: operators.coreos.com/v1alpha1
kind: Subscription
metadata:
  name: cloudnative-pg
  namespace: cnpg-system
spec:
  channel: stable
  installPlanApproval: Automatic
  name: cloudnative-pg
  source: platform
  sourceNamespace: cpaas-system

应用配置并等待 CSV 达到 Succeeded 状态:

kubectl apply -f install.yaml
kubectl wait --for=jsonpath='{.status.phase}'=Succeeded \
  -n cnpg-system csv -l operators.coreos.com/cloudnative-pg.cnpg-system='' \
  --timeout=5m

operator Pod(cnpg-controller-manager-*,位于 cnpg-system 中)应在 Succeeded 后约 60 秒内显示为 Running 1/1。

步骤 2 — 创建您的第一个 PostgreSQL 集群(4 分钟)

创建一个工作负载命名空间并应用一个包含 3 个实例的 Cluster。如果未指定镜像,operator 将使用此产品版本随附的 PostgreSQL 版本,这是最简单且受支持的默认配置:

# my-cluster.yaml
apiVersion: v1
kind: Namespace
metadata:
  name: pg-demo
---
apiVersion: postgresql.cnpg.io/v1
kind: Cluster
metadata:
  name: my-postgres
  namespace: pg-demo
spec:
  instances: 3
  storage:
    size: 2Gi
    # storageClass: <name>   # omit to use the default StorageClass
  bootstrap:
    initdb:
      database: app
      owner: app
TIP

operator 会为 app owner 生成一个随机密码,并将其存储在 my-postgres-app Secret 中(其中包含现成的 uri / jdbc-uri 键)。如需使用自定义密码,或为 postgres 超级用户设置密码,请创建一个 kubernetes.io/basic-auth Secret,并在 spec.bootstrap.initdb.secret 中引用它;请参阅用户和数据库。

TIP

若要选择特定的 PostgreSQL 主版本,请将 spec.imageName 设置为平台 registry 中的 PostgreSQL operand 镜像,或者创建一个 ClusterImageCatalog 并通过 spec.imageCatalogRef 引用它;请参阅配置(镜像部分)。默认情况下不会安装 ClusterImageCatalog。

kubectl apply -f my-cluster.yaml
kubectl wait --for=jsonpath='{.status.phase}'='Cluster in healthy state' \
  -n pg-demo cluster.postgresql.cnpg.io/my-postgres --timeout=5m
WARNING

在 kubectl 命令中,始终使用 cluster.postgresql.cnpg.io 指定 CNPG 集群。在 ACP 集群上,直接使用 cluster 短名称会解析为另一种资源(来自 Cluster API 的 clusters.cluster.x-k8s.io),因此 kubectl wait cluster/my-postgres 等命令会因 NotFound 而失败。

包含 3 个实例的集群通常会在两到五分钟内达到 Cluster in healthy state(首次使用时,耗时主要取决于镜像拉取时间)。第一个实例是主实例;另外两个实例从它接收流复制。

通过可写的 -rw 服务执行 SQL 冒烟测试查询,并使用集群运行的同一 operand 镜像进行验证:

# Pull the auto-generated app-user password
PGPASSWORD=$(kubectl get secret my-postgres-app -n pg-demo \
  -o jsonpath='{.data.password}' | base64 -d)

# The image the cluster is running (use it for the client too)
IMG=$(kubectl get cluster.postgresql.cnpg.io my-postgres -n pg-demo \
  -o jsonpath='{.status.image}')

# Connect through the cluster's writable service (-rw routes to the primary)
kubectl run psql-client --rm -it --restart=Never \
  --image="$IMG" --env=PGPASSWORD="$PGPASSWORD" -n pg-demo \
  -- psql -h my-postgres-rw -U app -d app \
  -c "CREATE TABLE hello (msg text);" \
  -c "INSERT INTO hello VALUES ('first row');" \
  -c "SELECT * FROM hello;" \
  -c "SELECT version();"

预期输出中应包含您插入的行以及 PostgreSQL 18.x ... 版本信息行。

步骤 3 — 配置备份到对象存储(3 分钟)

备份通过 Barman Cloud 插件完成。该插件包含在 Alauda Data Services Relational Database E3 bundle 中,并由 operator 在启动时自动引导(前提是已安装 cert-manager)。

首先,创建一个包含 S3 凭据的 Kubernetes Secret。避免在命令行中传递 Secret——使用 --from-file 配合短期临时文件:

TMP=$(mktemp -d) && umask 077
printf '%s' '<your-access-key>'  > "$TMP/ACCESS_KEY_ID"
printf '%s' '<your-secret-key>'  > "$TMP/ACCESS_SECRET_KEY"
kubectl -n pg-demo create secret generic s3-creds \
  --from-file=ACCESS_KEY_ID="$TMP/ACCESS_KEY_ID" \
  --from-file=ACCESS_SECRET_KEY="$TMP/ACCESS_SECRET_KEY"
rm -rf "$TMP"

然后创建一个 ObjectStore 资源,描述备份的存储位置,并将 Barman Cloud 插件附加到 Cluster:

# backup.yaml
apiVersion: barmancloud.cnpg.io/v1
kind: ObjectStore
metadata:
  name: my-backup-store
  namespace: pg-demo
spec:
  configuration:
    destinationPath: s3://<bucket>/quickstart/my-postgres/
    endpointURL: http://<your-s3-endpoint>
    s3Credentials:
      accessKeyId:     { name: s3-creds, key: ACCESS_KEY_ID }
      secretAccessKey: { name: s3-creds, key: ACCESS_SECRET_KEY }
    wal:  { compression: gzip, maxParallel: 4 }
    data: { compression: gzip }
  retentionPolicy: "30d"
---
# Patch the Cluster to use the plugin for backups + WAL archiving
apiVersion: postgresql.cnpg.io/v1
kind: Cluster
metadata:
  name: my-postgres
  namespace: pg-demo
spec:
  instances: 3
  storage:
    size: 2Gi
  bootstrap:
    initdb:
      database: app
      owner: app
  plugins:
  - name: barman-cloud.cloudnative-pg.io
    isWALArchiver: true
    parameters:
      barmanObjectName: my-backup-store
kubectl apply -f backup.yaml
WARNING

附加插件会触发实例的滚动重启(插件 sidecar 会注入每个 pod)。在触发备份之前,请等待集群恢复到 Cluster in healthy state——在滚动更新期间创建的 Backup 会失败,并显示 requested plugin is not available: barman-cloud.cloudnative-pg.io。

kubectl wait --for=jsonpath='{.status.phase}'='Cluster in healthy state' \
  -n pg-demo cluster.postgresql.cnpg.io/my-postgres --timeout=5m

立即触发一次备份:

# trigger-backup.yaml
apiVersion: postgresql.cnpg.io/v1
kind: Backup
metadata:
  name: my-postgres-first-backup
  namespace: pg-demo
spec:
  cluster: { name: my-postgres }
  method: plugin
  pluginConfiguration:
    name: barman-cloud.cloudnative-pg.io
kubectl apply -f trigger-backup.yaml
kubectl wait --for=jsonpath='{.status.phase}'=completed \
  -n pg-demo backup/my-postgres-first-backup --timeout=3m

小型集群的首次备份通常会在 10–30 秒内完成。使用 mc(或任意 S3 客户端)验证 S3 中的文件:

mc alias set my-store http://<your-s3-endpoint> \
  '<your-access-key>' '<your-secret-key>'
mc ls --recursive my-store/<bucket>/quickstart/my-postgres/
# Expect:  base/<timestamp>/{backup.info,data.tar.gz}
#          wals/0000000100000000/*.gz

现在,你已拥有一个自管理的 PostgreSQL 集群,具备 HA 复制和基于 S3 的时间点恢复能力。

接下来

  • 配置 — 参数、用户和数据库、同步复制、存储、镜像。
  • 操作指南:运维手册 — 第 2 天运维,包括故障转移、扩缩容、升级和恢复。
  • 操作指南:Grafana 仪表板 — 将内置指标接入平台 Prometheus,并导入 Curated 仪表板。
  • 从 Zalando 迁移 — 将现有的 Zalando postgres-operator 集群迁移到 CloudNativePG。
  • 架构 — 了解主节点选举、复制和插件的工作方式。

故障排除

症状原因解决方法
kubectl wait 在 CSV Succeeded 上超时OLM 仍在解析 channel;或尚未安装 cert-manager在 cnpg-system 中执行 kubectl describe csv 并检查安装条件
集群存在时,kubectl wait cluster/my-postgres 执行 NotFound 失败裸 cluster 会解析为 Cluster API 的资源使用 cluster.postgresql.cnpg.io/my-postgres(参见步骤 2 中的警告)
集群卡在 Setting up primary,并显示 ImagePullBackOff此集群节点无法访问默认 operand 镜像将 spec.imageName 设置为平台仓库中的 PostgreSQL operand 镜像(参见配置)
PVC 卡在 Pending没有默认 StorageClass执行 kubectl get sc 确认默认 StorageClass 是否存在,或将 storageClass: 添加到 spec.storage
Backup 处于 phase: failed 状态,并显示 requested plugin is not available在插件附加的滚动更新完成前触发了备份等待 Cluster in healthy state,然后重新创建 Backup
Backup 处于 phase: failed 状态,并显示 no such host集群节点无法访问 ObjectStore 端点为 endpointURL 使用集群内部地址

有关配置级问题,请参阅 故障排除快速参考。

商标声明

CloudNativePG™ 是 The Linux Foundation 的商标。

PostgreSQL® 是 PostgreSQL Community Association of Canada 的注册商标。

Alauda 是一家独立供应商。本产品与 The Linux Foundation、PostgreSQL Community Association of Canada 均无关联,亦未获得其认可或赞助。所有商标均为其各自所有者的财产,在此仅用于标识。