快速开始：15 分钟内创建你的第一个 PostgreSQL 集群
本教程将引导你从全新安装的 Alauda CloudNativePG operator 开始，逐步创建一个正在运行的 3 实例 PostgreSQL 集群，并完成 backup 配置。每个部分都只需几分钟；如果你的集群响应正常，总耗时大约 15 分钟。
先决条件（5 分钟）
你需要：
- 一个 ACP 托管集群，运行 Kubernetes 1.30+，并满足以下条件：
- 默认的块存储模式 StorageClass（通常是
topolvm 类；可通过 kubectl get sc 验证）。
- 已安装 cert-manager（Barman Cloud backup plugin 的 TLS 前置条件需要它）。可通过
kubectl api-resources --api-group=cert-manager.io 验证。如果尚未安装，请先通过 marketplace 安装，然后继续。
- 集群管理员或平台管理员权限，用于执行安装步骤。
Day-2 操作（创建集群、backup）只需要目标 namespace 的 namespace admin 权限。
- 已为目标集群配置好
kubectl（ACP Web 控制台中的 Download kubeconfig 操作是最简单的方式）。
- 用于 backup 的 S3 兼容对象存储（MinIO、Ceph RGW，或集群可访问的任意 S3 endpoint），并准备好访问密钥和一个可写入的 bucket。
如果你还没有安装 operator，请先阅读
Installation，然后在 CSV 状态变为 Succeeded 后再返回此处。
步骤 1 — 安装 operator（3 分钟）
如果你已经按照
Installation 完成安装，可跳过此步骤。
# 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-system 中的 cnpg-controller-manager-*）应在 Succeeded 后约 60 秒内显示为 Running 1/1。
步骤 2 — 创建你的第一个 PostgreSQL 集群（4 分钟）
创建一个 workload namespace，并应用一个 3 实例 Cluster。在未指定 image 的情况下，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
如果要选择特定的 PostgreSQL major version，请将 spec.imageName 设置为平台 registry 中的 PostgreSQL operand image，或者创建一个 ClusterImageCatalog 并通过 spec.imageCatalogRef 引用它——请参见 Configuration（Images 部分）。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 实例集群通常会在 2 到 5 分钟内达到 Cluster in healthy state（首次使用时，拉取 image 的时间通常占主要部分）。第一个实例是 primary；另外两个实例会从它进行流复制。
使用可写的 -rw service 进行一次 SQL 冒烟测试，并使用集群运行时相同的 operand image：
# 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 — 配置到对象存储的 backup（3 分钟）
backup 通过 Barman Cloud plugin 进行，该插件包含在 Alauda CNPG 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 resource，用于描述 backup 的存放位置，并将 Barman Cloud plugin 关联到 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
附加 plugin 会触发实例的 rolling restart（plugin sidecar 会被注入到每个 pod 中）。在触发 backup 之前，请等待集群恢复到 Cluster in healthy state —— 在 rollout 过程中创建的 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
立即触发一次 backup：
# 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
小型集群的首次 backup 通常会在 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 replication 和基于 S3 的 point-in-time recovery。
下一步
故障排查
有关配置层面的其他问题，请参见
troubleshooting quick reference。
