CloudNativePG部署实战：从零开始搭建高可用PostgreSQL集群-优快云博客

CloudNativePG部署实战：从零开始搭建高可用PostgreSQL集群

【免费下载链接】cloudnative-pg CloudNativePG is a Kubernetes operator that covers the full lifecycle of a PostgreSQL database cluster with a primary/standby architecture, using native streaming replication 项目地址: https://gitcode.com/GitHub_Trending/cl/cloudnative-pg

本文详细介绍了从环境准备到完整部署CloudNativePG高可用PostgreSQL集群的全过程。内容包括Kubernetes集群配置要求、系统环境准备、存储类配置、网络策略设置，以及CloudNativePG Operator的多种安装方式。通过完整的部署示例和配置详解，指导读者如何快速搭建生产就绪的PostgreSQL高可用集群，并提供了监控体系和故障排查的完整解决方案。

环境准备与Kubernetes集群配置

在开始部署CloudNativePG之前，必须确保具备正确的环境配置和Kubernetes集群设置。本节将详细介绍环境准备的关键步骤、Kubernetes集群配置要求以及最佳实践，为后续的PostgreSQL集群部署奠定坚实基础。

系统环境要求

CloudNativePG作为Kubernetes原生操作符，对运行环境有特定的要求。以下是部署前必须满足的基础条件：

必备工具清单：

Kubernetes集群（v1.21+）
kubectl命令行工具
容器运行时（Docker或containerd）
网络插件（Calico、Flannel等）
存储类配置

资源需求估算： | 组件 | CPU需求 | 内存需求 | 存储需求 | |------|---------|----------|----------| | CloudNativePG Operator | 100m-500m | 128Mi-512Mi | 无持久化存储 | | PostgreSQL实例（每个） | 500m-2 | 1Gi-8Gi | 10Gi-100Gi+ | | 监控组件（可选） | 200m-1 | 256Mi-2Gi | 5Gi-20Gi |

Kubernetes集群配置

1. 集群类型选择

根据使用场景选择合适的Kubernetes集群类型：

开发测试环境：

# 使用Minikube创建单节点集群
minikube start --memory=4096 --cpus=4 --disk-size=20g

# 或使用Kind创建多节点集群
kind create cluster --name cnpg-cluster --config kind-config.yaml

生产环境要求：

至少3个worker节点确保高可用性
节点间网络延迟低于5ms
存储后端支持ReadWriteOnce和ReadWriteMany
启用RBAC和网络策略

2. 存储类配置

存储是数据库集群的核心，必须仔细配置：

# 高性能存储类示例
apiVersion: storage.k8s.io/v1
kind: StorageClass
metadata:
  name: postgres-ssd
provisioner: kubernetes.io/gce-pd
parameters:
  type: pd-ssd
  replication-type: none
allowVolumeExpansion: true
reclaimPolicy: Retain
volumeBindingMode: WaitForFirstConsumer

存储类关键参数说明：

allowVolumeExpansion: true - 支持在线卷扩容
reclaimPolicy: Retain - 防止意外数据删除
volumeBindingMode: WaitForFirstConsumer - 延迟绑定优化调度

3. 资源配额与限制

为命名空间设置合理的资源配额：

apiVersion: v1
kind: ResourceQuota
metadata:
  name: postgres-quota
  namespace: postgres-production
spec:
  hard:
    requests.cpu: "8"
    requests.memory: 32Gi
    limits.cpu: "16"
    limits.memory: 64Gi
    requests.storage: 1Ti
    persistentvolumeclaims: "10"
    pods: "20"

网络配置要求

PostgreSQL集群对网络有特定要求，特别是流复制和故障转移场景：

网络策略示例：

apiVersion: networking.k8s.io/v1
kind: NetworkPolicy
metadata:
  name: postgres-network-policy
  namespace: postgres-production
spec:
  podSelector:
    matchLabels:
      app.kubernetes.io/name: postgresql
  policyTypes:
  - Ingress
  - Egress
  ingress:
  - ports:
    - protocol: TCP
      port: 5432
    from:
    - podSelector:
        matchLabels:
          app: application-service
  egress:
  - ports:
    - protocol: TCP
      port: 5432
    to:
    - podSelector:
        matchLabels:
          app.kubernetes.io/name: postgresql

节点亲和性与反亲和性

为确保高可用性，需要合理配置Pod调度策略：

# 在Cluster配置中设置反亲和性
apiVersion: postgresql.cnpg.io/v1
kind: Cluster
metadata:
  name: ha-postgres-cluster
spec:
  instances: 3
  affinity:
    podAntiAffinity:
      requiredDuringSchedulingIgnoredDuringExecution:
      - labelSelector:
          matchExpressions:
          - key: app.kubernetes.io/name
            operator: In
            values:
            - postgresql
        topologyKey: kubernetes.io/hostname

监控与日志配置

预先配置监控基础设施：

# Prometheus PodMonitor配置
apiVersion: monitoring.coreos.com/v1
kind: PodMonitor
metadata:
  name: cnpg-monitor
  namespace: postgres-production
spec:
  selector:
    matchLabels:
      app.kubernetes.io/name: postgresql
  podMetricsEndpoints:
  - port: metrics
    interval: 30s
    path: /metrics

环境验证脚本

部署前运行验证脚本确保环境就绪：

#!/bin/bash
# 环境验证脚本
echo "验证Kubernetes集群状态..."
kubectl cluster-info
kubectl get nodes -o wide

echo "验证存储类配置..."
kubectl get storageclass
kubectl describe storageclass postgres-ssd

echo "验证资源配额..."
kubectl get resourcequota -n postgres-production

echo "验证网络策略..."
kubectl get networkpolicy -n postgres-production

echo "环境验证完成！"

配置流程图

以下是环境准备与配置的整体流程：

mermaid

通过以上系统化的环境准备和Kubernetes集群配置，您将拥有一个稳定、高性能的基础设施平台，为后续CloudNativePG operator和PostgreSQL集群的部署提供可靠保障。每个配置步骤都经过精心设计，确保生产环境的稳定性、安全性和可扩展性。

CloudNativePG Operator安装指南

CloudNativePG Operator是管理Kubernetes中PostgreSQL集群的核心组件，它提供了完整的数据库生命周期管理能力。本文将详细介绍多种安装方式，帮助您选择最适合生产环境的部署方案。

前置环境要求

在开始安装之前，请确保您的Kubernetes集群满足以下要求：

组件	最低版本	推荐版本
Kubernetes	1.23	1.26+
kubectl	1.23	1.26+
Helm (可选)	3.8	3.12+
OLM (可选)	0.22	0.26+

安装方法概览

CloudNativePG Operator支持多种安装方式，每种方式都有其适用场景：

mermaid

方法一：直接使用YAML清单安装

这是最简单直接的安装方式，适用于大多数生产环境：

# 安装最新稳定版本（1.27.0）
kubectl apply --server-side -f \
  https://raw.githubusercontent.com/cloudnative-pg/cloudnative-pg/release-1.27/releases/cnpg-1.27.0.yaml

安装完成后验证Operator状态：

# 检查Operator部署状态
kubectl rollout status deployment \
  -n cnpg-system cnpg-controller-manager

# 查看Operator Pod运行状态
kubectl get pods -n cnpg-system

预期输出示例：

deployment "cnpg-controller-manager" successfully rolled out
NAME                                   READY   STATUS    RESTARTS   AGE
cnpg-controller-manager-5f8d7b6c8-abc   1/1     Running   0          2m

方法二：使用kubectl cnpg插件定制安装

kubectl cnpg插件提供了更灵活的安装选项，允许生成定制化的安装清单：

# 生成仅监视特定命名空间的安装清单
kubectl cnpg install generate \
  --watch-namespace "postgres-production" \
  > cnpg-custom.yaml

# 应用定制化的安装清单
kubectl apply --server-side -f cnpg-custom.yaml

插件支持的主要定制选项：

选项	描述	默认值
`--watch-namespace`	指定监视的命名空间	所有命名空间
`--operator-image`	自定义Operator镜像	官方镜像
`--service-account`	自定义服务账户	cnpg-controller-manager
`--namespace`	安装到的命名空间	cnpg-system

方法三：使用Helm Chart安装

对于已经使用Helm进行应用管理的环境，CloudNativePG提供了官方的Helm Chart：

# 添加Helm仓库
helm repo add cnpg https://cloudnative-pg.github.io/charts
helm repo update

# 安装CloudNativePG Operator
helm install cnpg cnpg/cloudnative-pg \
  --namespace cnpg-system \
  --create-namespace \
  --version 1.27.0

Helm安装的优势在于支持Values文件配置：

# values-custom.yaml
fullnameOverride: "my-cnpg-operator"
watchNamespaces:
  - "app-database"
  - "backup-storage"
resources:
  requests:
    memory: "256Mi"
    cpu: "250m"
  limits:
    memory: "512Mi"
    cpu: "500m"

helm install cnpg cnpg/cloudnative-pg \
  -f values-custom.yaml \
  --namespace cnpg-system

方法四：通过Operator Lifecycle Manager安装

对于OpenShift或已部署OLM的环境，可以通过OperatorHub安装：

# 创建OperatorGroup
cat <<EOF | kubectl apply -f -
apiVersion: operators.coreos.com/v1
kind: OperatorGroup
metadata:
  name: cnpg-operator-group
  namespace: cnpg-system
spec:
  targetNamespaces:
  - cnpg-system
EOF

# 创建Subscription
cat <<EOF | kubectl apply -f -
apiVersion: operators.coreos.com/v1alpha1
kind: Subscription
metadata:
  name: cloudnative-pg
  namespace: cnpg-system
spec:
  channel: stable
  name: cloudnative-pg
  source: operatorhubio-catalog
  sourceNamespace: olm
  installPlanApproval: Automatic
EOF

安装验证和健康检查

无论采用哪种安装方式，都需要进行完整的健康检查：

# 检查CRD是否已安装
kubectl get crd | grep postgresql.cnpg.io

# 检查Operator Pod日志
kubectl logs -n cnpg-system deployment/cnpg-controller-manager

# 验证webhook服务
kubectl get validatingwebhookconfigurations,mutatingwebhookconfigurations | grep cnpg

预期应该看到以下CRD资源：

clusters.postgresql.cnpg.io
backups.postgresql.cnpg.io
scheduledbackups.postgresql.cnpg.io

生产环境最佳实践

对于生产环境部署，建议遵循以下最佳实践：

高可用Operator部署：

# 在Deployment中配置多副本
spec:
  replicas: 3
  strategy:
    type: RollingUpdate

资源限制和请求：

resources:
  requests:
    cpu: "250m"
    memory: "256Mi"
  limits:
    cpu: "1000m"
    memory: "1Gi"

节点亲和性和反亲和性：

affinity:
  podAntiAffinity:
    preferredDuringSchedulingIgnoredDuringExecution:
    - weight: 100
      podAffinityTerm:
        labelSelector:
          matchExpressions:
          - key: app.kubernetes.io/name
            operator: In
            values: ["cloudnative-pg"]
        topologyKey: kubernetes.io/hostname

网络策略：

# 限制Operator的网络访问
apiVersion: networking.k8s.io/v1
kind: NetworkPolicy
metadata:
  name: cnpg-operator-policy
  namespace: cnpg-system
spec:
  podSelector:
    matchLabels:
      app.kubernetes.io/name: cloudnative-pg
  policyTypes:
  - Ingress
  - Egress
  ingress:
  - from:
    - namespaceSelector:
        matchLabels:
          kubernetes.io/metadata.name: cnpg-system
  egress:
  - to:
    - namespaceSelector: {}

故障排除常见问题

GKE环境Webhook问题：

# 如果遇到webhook连接问题，修改targetPort
kubectl patch service cnpg-webhook-service -n cnpg-system \
  --type='json' \
  -p='[{"op": "replace", "path": "/spec/ports/0/targetPort", "value": 9443}]'

镜像拉取失败：

# 检查镜像拉取密钥
kubectl create secret docker-registry cnpg-pull-secret \
  --docker-server=ghcr.io \
  --docker-username=USERNAME \
  --docker-password=TOKEN \
  --namespace cnpg-system

通过以上详细的安装指南，您可以根据具体环境需求选择最适合的CloudNativePG Operator安装方式，为后续的PostgreSQL集群部署奠定坚实基础。

基础PostgreSQL集群部署示例

在CloudNativePG中部署一个基础的PostgreSQL集群非常简单直观，通过声明式的YAML配置即可完成。下面我们将详细介绍一个完整的基础集群部署示例，包含所有必要的配置项和最佳实践。

最小化集群配置

最基本的PostgreSQL集群配置只需要指定实例数量和存储大小：

apiVersion: postgresql.cnpg.io/v1
kind: Cluster
metadata:
  name: basic-postgres-cluster
spec:
  instances: 3
  storage:
    size: 10Gi

这个配置会创建一个3节点的PostgreSQL集群，每个节点分配10GB的存储空间。CloudNativePG会自动处理主从复制、故障转移和高可用性。

完整的基础集群配置示例

下面是一个更加完整的生产级基础配置示例：

apiVersion: postgresql.cnpg.io/v1
kind: Cluster
metadata:
  name: production-postgres-cluster
  labels:
    environment: production
    app: postgresql
spec:
  description: "生产环境PostgreSQL集群"
  instances: 3
  
  # 使用特定版本的PostgreSQL镜像
  imageName: ghcr.io/cloudnative-pg/postgresql:15.3
  
  # 存储配置
  storage:
    storageClass: fast-ssd
    size: 50Gi
  walStorage:
    storageClass: fast-ssd  
    size: 10Gi

  # 资源限制
  resources:
    requests:
      memory: "4Gi"
      cpu: "2"
    limits:
      memory: "8Gi"
      cpu: "4"

  # PostgreSQL参数配置
  postgresql:
    parameters:
      max_connections: "200"
      shared_buffers: "1GB"
      work_mem: "16MB"
      maintenance_work_mem: "256MB"
      effective_cache_size: "6GB"

  # 连接认证配置
  postgresql:
    pg_hba:
      - host all all 10.0.0.0/8 md5
      - host all all 172.16.0.0/12 md5
      - host all all 192.168.0.0/16 md5

  # 初始化配置
  bootstrap:
    initdb:
      database: appdb
      owner: appuser
      encoding: UTF8
      locale: en_US.UTF-8

  # 更新策略
  primaryUpdateStrategy: unsupervised

  # 亲和性配置
  affinity:
    enablePodAntiAffinity: true
    topologyKey: kubernetes.io/hostname

配置详解

实例数量配置

instances: 3

这表示部署一个3节点的集群，包含1个主节点和2个备用节点。CloudNativePG会自动维护主从复制关系。

存储配置

storage:
  storageClass: fast-ssd
  size: 50Gi
walStorage:
  storageClass: fast-ssd
  size: 10Gi

storage: 主数据存储配置
walStorage: WAL日志存储配置（可选但推荐）
建议为WAL日志使用高性能存储

资源限制

resources:
  requests:
    memory: "4Gi"
    cpu: "2"
  limits:
    memory: "8Gi" 
    cpu: "4"

合理的资源限制可以确保集群稳定运行，避免资源竞争。

PostgreSQL参数优化

postgresql:
  parameters:
    max_connections: "200"
    shared_buffers: "1GB"
    work_mem: "16MB"

这些参数可以根据实际负载情况进行调整，优化数据库性能。

部署流程

部署集群的完整流程如下：

mermaid

验证部署状态

部署完成后，可以通过以下命令验证集群状态：

# 查看集群状态
kubectl get clusters.postgresql.cnpg.io

# 查看Pod状态
kubectl get pods -l cnpg.io/cluster=production-postgres-cluster

# 查看详细集群信息
kubectl describe cluster production-postgres-cluster

集群架构说明

CloudNativePG创建的PostgreSQL集群采用标准的流复制架构：

mermaid

连接数据库

集群部署完成后，可以通过以下方式连接：

# 获取连接信息
kubectl get secrets production-postgres-cluster-app -o jsonpath='{.data.uri}' | base64 -d

# 端口转发连接
kubectl port-forward svc/production-postgres-cluster-rw 5432:5432

监控和日志

CloudNativePG提供了丰富的监控指标：

monitoring:
  enablePodMonitor: true

启用监控后，可以通过Prometheus收集以下关键指标：

指标类型	说明	重要性
`cnpg_postgresql_up`	实例状态	高
`cnpg_postgresql_connections`	连接数	高
`cnpg_postgresql_replication_lag`	复制延迟	高
`cnpg_postgresql_wal_files`	WAL文件数	中

故障排除

如果部署遇到问题，可以检查以下内容：

存储类是否存在：确保指定的storageClass在Kubernetes集群中可用
资源配额：检查命名空间的资源配额是否足够
镜像拉取：确保能够访问PostgreSQL镜像仓库
网络策略：检查网络策略是否允许Pod间通信

通过以上配置和说明，您可以快速部署一个生产就绪的PostgreSQL高可用集群。CloudNativePG会自动处理复杂的运维任务，让您专注于业务开发。

集群状态监控与故障排查

在CloudNativePG的高可用PostgreSQL集群部署中，有效的监控和及时的故障排查是确保数据库稳定运行的关键环节。CloudNativePG提供了全面的监控能力和丰富的故障排查工具，帮助运维团队实时掌握集群状态并快速定位问题。

监控体系架构

CloudNativePG的监控体系基于Prometheus标准构建，每个PostgreSQL实例都内置了指标导出器，通过HTTP/HTTPS端口9187提供丰富的监控数据。

mermaid

内置监控指标

CloudNativePG提供了丰富的预定义监控指标，主要分为以下几类：

核心集群状态指标

指标名称	类型	描述
`cnpg_collector_up`	Gauge	PostgreSQL实例是否正常运行（1=正常，0=异常）
`cnpg_collector_nodes_used`	Gauge	集群使用的不同节点数量
`cnpg_collector_fencing_on`	Gauge	实例是否被隔离（1=隔离，0=正常）
`cnpg_collector_manual_switchover_required`	Gauge	是否需要手动切换（1=需要，0=不需要）

WAL日志监控指标

指标名称	类型	描述
`cnpg_collector_pg_wal`	Gauge	WAL段文件数量和总大小
`cnpg_collector_pg_wal_archive_status`	Gauge	归档状态文件数量（ready/done）

复制状态指标

指标名称	类型	描述
`cnpg_collector_sync_replicas`	Gauge	同步副本数量（期望值/实际值）
`cnpg_collector_replica_mode`	Gauge	集群是否处于副本模式

自定义监控查询

除了预定义指标，CloudNativePG支持通过ConfigMap定义自定义监控查询：

apiVersion: v1
kind: ConfigMap
metadata:
  name: custom-monitoring-queries
data:
  queries: |
    database_connections:
      query: |
        SELECT datname, COUNT(*) as connections
        FROM pg_stat_activity 
        GROUP BY datname
      metrics:
        - datname:
            usage: "LABEL"
            description: "Database name"
        - connections:
            usage: "GAUGE"
            description: "Number of active connections"

PodMonitor配置

启用自动PodMonitor创建：

apiVersion: postgresql.cnpg.io/v1
kind: Cluster
metadata:
  name: my-cluster
spec:
  monitoring:
    enablePodMonitor: true
    tls:
      enabled: true

或者手动配置PodMonitor：

apiVersion: monitoring.coreos.com/v1
kind: PodMonitor
metadata:
  name: my-cluster-monitor
spec:
  selector:
    matchLabels:
      cnpg.io/cluster: my-cluster
  podMetricsEndpoints:
  - port: metrics
    interval: 30s
    path: /metrics

故障排查工具集

kubectl cnpg插件

CloudNativePG提供了强大的kubectl插件，是故障排查的首选工具：

# 查看集群状态概览
kubectl cnpg status my-cluster

# 获取详细集群报告（包含日志）
kubectl cnpg report my-cluster --logs

# 查看集群日志
kubectl cnpg logs my-cluster

# 检查备份状态
kubectl cnpg backup status my-cluster

集群状态检查

# 检查集群资源状态
kubectl get cluster my-cluster -o wide

# 查看集群实例详情
kubectl get pods -l cnpg.io/cluster=my-cluster -L role

# 检查实例状态
kubectl describe pod my-cluster-1

日志分析

CloudNativePG使用JSON格式日志，便于机器解析和人工阅读：

# 查看操作器日志
kubectl logs -n cnpg-system deployment/cnpg-controller-manager

# 查看特定实例日志
kubectl logs my-cluster-1 -c postgres | jq .

# 实时日志监控
kubectl logs -f my-cluster-1 -c postgres

常见故障场景排查

实例无法启动

# 检查Pod事件
kubectl describe pod my-cluster-1

# 查看初始化日志
kubectl logs my-cluster-1 -c postgres-init

# 检查持久卷状态
kubectl get pvc -l cnpg.io/cluster=my-cluster

复制延迟问题

# 检查复制状态
kubectl cnpg status my-cluster --verbose

# 查看WAL发送状态
kubectl exec my-cluster-1 -c postgres -- \
  psql -c "SELECT * FROM pg_stat_replication;"

# 检查网络延迟
kubectl exec my-cluster-2 -c postgres -- \
  ping -c 4 my-cluster-1

备份失败排查

# 检查备份作业状态
kubectl get backups -l cnpg.io/cluster=my-cluster

# 查看备份日志
kubectl logs <backup-pod-name>

# 验证存储配置
kubectl describe backup my-cluster-backup

紧急备份与恢复

在紧急情况下，可以执行逻辑备份：

# 紧急逻辑备份
kubectl exec my-cluster-1 -c postgres -- \
  pg_dump -Fc -d app > emergency_backup.dump

# 恢复到新集群
kubectl exec -i new-cluster-1 -c postgres -- \
  pg_restore --no-owner --role=app -d app --verbose < emergency_backup.dump

监控仪表板配置

推荐使用Grafana仪表板来可视化监控数据：

apiVersion: v1
kind: ConfigMap
metadata:
  name: postgres-dashboard
data:
  dashboard.json: |
    {
      "title": "CloudNativePG Monitoring",
      "panels": [
        {
          "title": "Database Connections",
          "targets": [{
            "expr": "cnpg_collector_backends_total",
            "legendFormat": "{{datname}}"
          }]
        }
      ]
    }

告警规则配置

配置关键告警规则：

groups:
- name: cloudnative-pg-alerts
  rules:
  - alert: PostgreSQLDown
    expr: cnpg_collector_up == 0
    for: 5m
    labels:
      severity: critical
    annotations:
      summary: "PostgreSQL instance is down"
      
  - alert: HighReplicationLag
    expr: cnpg_collector_replication_lag_seconds > 30
    for: 2m
    labels:
      severity: warning
    annotations:
      summary: "High replication lag detected"

通过上述监控和故障排查机制，CloudNativePG为用户提供了完整的可观测性解决方案，确保PostgreSQL集群的稳定运行和快速故障恢复能力。

总结

通过本文的全面介绍，我们完成了从零开始搭建高可用PostgreSQL集群的完整流程。从环境准备、Kubernetes集群配置，到CloudNativePG Operator的多种安装方式，再到基础集群的部署和监控体系的建立，每个环节都提供了详细的配置示例和最佳实践。CloudNativePG通过声明式的YAML配置和强大的运维自动化能力，极大地简化了PostgreSQL集群的管理复杂度。内置的监控指标、故障排查工具和告警机制，确保了集群的稳定运行和快速故障恢复。这套解决方案为在生产环境中部署和管理高可用PostgreSQL集群提供了完整的技术栈和运维体系。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考