快速入门:15 分钟创建您的第一个 PostgreSQL 集群
本教程将引导您从全新安装 Alauda Data Services Relational Database E3
operator 开始,直至运行一个包含 3 个实例且已配置备份的 PostgreSQL 集群。每个部分只需几分钟;如果集群响应正常,整个流程大约需要 15 分钟。
先决条件(5 分钟)
您需要:
- 一个运行 Kubernetes 1.30+ 的 ACP 托管集群,并且:
- 一个默认的块模式 StorageClass(通常是
topolvm 类;使用 kubectl get sc 验证)。
- 已安装 cert-manager(Barman Cloud 备份插件的 TLS 先决条件)。使用
kubectl api-resources --api-group=cert-manager.io 验证。如果尚未安装,请先通过 Marketplace 安装,再继续操作。
- 集群管理员或平台管理员访问权限,用于执行安装步骤。
第 2 天运维(创建集群、备份)只需拥有目标命名空间的管理员权限。
- 为目标集群配置好
kubectl(最简单的方式是使用 ACP Web 控制台中的 Download kubeconfig 操作)。
- 一个兼容 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。
- 架构 — 了解主节点选举、复制和插件的工作方式。
故障排除
有关配置级问题,请参阅
故障排除快速参考。
商标声明
CloudNativePG™ 是 The Linux Foundation 的商标。
PostgreSQL® 是 PostgreSQL Community Association of Canada 的注册商标。
Alauda 是一家独立供应商。本产品与 The Linux Foundation、PostgreSQL Community Association of Canada 均无关联,亦未获得其认可或赞助。所有商标均为其各自所有者的财产,在此仅用于标识。