Средний

6 мин

7K

Вступление

Архитектура CNPG (как он работает изнутри)

Тут нам важно понять ключевое архитектурное решение CNPG: он не использует StatefulSets.

Вместо этого оператор реализует собственный кастомный Pod-контроллер и напрямую управляет Persistent Volume Claims (PVCs). Это даёт несколько преимуществ:

• Ресайзинг PVC прямо из манифеста - StatefulSet этого не поддерживает

• Разный порядок обновлений для primary и replica в зависимости от типа операции (например, понижение max_connections требует сначала обновить primary, а не реплики)

• Согласованное управление несколькими PVC на instance (PGDATA + отдельный WAL volume)

Компоненты

Operator - это Kubernetes-контроллер, который непрерывно сверяет фактическое состояние кластера с желаемым, определённым в манифесте, и автоматически обрабатывает failover, масштабирование и управление конфигурацией. Т.е. он в бесконечном цикле сверяет "как есть" и "как должно быть" и приводит одно к другому

Instance Manager - строенный процесс внутри каждого PostgreSQL Pod. Он управляет жизненным циклом инстанса и коммуницирует с Operator через Kubernetes API. Важно: это не sidecar-контейнер в классическом смысле, процесс встроен в сам Pod с PostgreSQL и именно он принимает решение о промоции реплики в primary при failover.

CRDs, которые CNPG добавляет в Kubernetes

Важно про FailoverQuorum: Этот ресурс создаётся и управляется оператором автоматически, поэтому не изменяйте его вручную. В версии 1.28 quorum-based failover был переведён из экспериментального в стабильный API и теперь конфигурируется через поле spec.postgresql.synchronous.failoverQuorum.

На основе модели Operator Capability Levels, CNPG реализует подмножество возможностей уровня "Level V - Auto Pilot". На практике это означает: оператор берёт на себя весь операционный цикл - от первичного деплоя до самовосстановления.

Схема того что мы будем разворачивать:

Предварительные требования:

• Кластер Kubernetes 1.23+ (для локальных тестов подойдут minikube или kind)

• kubectl

Шаг 1: Установка CNPG Operator (1.28.x)

Способ 1: деплой через манифест

kubectl apply --server-side -f \
  https://raw.githubusercontent.com/cloudnative-pg/cloudnative-pg/release-1.28/releases/cnpg-1.28.1.yaml

Проверяем деплой:

kubectl rollout status deployment -n cnpg-system cnpg-controller-manager

Способ 2: через Helm Chart

Если у Вас не установлен Helm Chart, то переходим в доку и ставим.

# Добавить репозиторий CNPG
helm repo add cnpg https://cloudnative-pg.io/charts/

# Установить оператор
helm install cnpg-operator cnpg/cloudnative-pg --version 0.27.1

Шаг 2: Создание кластера PostgreSQL (CNPG)

Разворачиваем кластер через CRD Cluster, который идёт в комплекте с оператором. Это декларативный способ описать желаемое состояние PostgreSQL-кластера.

# cluster.yaml
apiVersion: postgresql.cnpg.io/v1
kind: Cluster
metadata:
  name: my-cluster
spec:
  instances: 3

  storage:
    size: 1Gi

Этот манифест создаёт кластер с дефолтным storage class: 1 primary + 2 hot standby реплики. Primary инстанс стримит Write-Ahead Logs (WAL) на standby через нативную потоковую репликацию PostgreSQL.

Режимы репликации

CNPG поддерживает два режима:

1. Асинхронный (по умолчанию) - не ждёт подтверждения от реплик о получении WAL. Минимальная latency записи, минимальный риск потери данных при failover (только транзакции, не успевшие улететь на реплику).
2. Синхронный (настраиваемый) - ждёт кворума реплик с подтверждением получения WAL перед тем, как вернуть COMMIT клиенту. Никакой потери данных при failover, ценой небольшого роста latency.

Если потеря даже одной транзакции недопустима, то нужна синхронная репликация:

# cluster-synchronous.yaml
apiVersion: postgresql.cnpg.io/v1
kind: Cluster
metadata:
  name: my-synchronous-cluster
spec:
  instances: 3

  storage:
    size: 1Gi

  postgresql:
    synchronous:
      method: any   # any = кворум, first = приоритет (required)
      number: 1     # кол-во standbys, обязанных подтвердить WAL (required)

• method: any - кворум-based (рекомендуется для большинства HA-сценариев)

• method: first - priority-based (по порядку в списке реплик)

• number - минимальное количество реплик, которые должны ответить до COMMIT

В версии 1.28 к этому добавился стабильный
spec.postgresql.synchronous.failoverQuorum: true — включает data-driven failover, который не допускает промоции реплики без подтверждения кворума.

Шаг 3: Настройка базы данных

По умолчанию CNPG инициализирует кластер с двумя базами:

• app - рабочая база приложения. Принадлежит непривилегированному пользователю app, credentials хранятся в Kubernetes Secret.

• postgres - системная административная база во всех PostgreSQL-инсталляциях, используется оператором для reconciliation. Не удаляйте её, т.к. это сломает оператор

Если стандартное имя app не устраивает, то переопределяется через bootstrap.initdb:

# initdb-secret.yaml
apiVersion: v1
kind: Secret
metadata:
  name: initdb-secret
type: kubernetes.io/basic-auth
data:
  username: YWRtaW5fbXl1c2Vy   # base64
  password: YWRtaW5fcGFzc3dvcmQ=   # base64

# initdb-cluster.yaml
apiVersion: postgresql.cnpg.io/v1
kind: Cluster
metadata:
  name: initdb-cluster
spec:
  instances: 3

  bootstrap:
    initdb:
      database: custom    # app (по умолчанию)
      owner: myuser       # app (по умолчанию)
      secret:
        name: initdb-secret

  storage:
    size: 1Gi

Чтобы добавить дополнительную базу в уже существующий кластер через CRD Database:

# my-db.yaml
apiVersion: postgresql.cnpg.io/v1
kind: Database
metadata:
  name: my-db           # (обязательно)
spec:
  name: my-db           # (обязательно)
  owner: app            # или ваш кастомный пользователь (обязательно)
  cluster:
    name: my-cluster    # должно совпадать с именем Cluster (обязательно)

Шаг 4: Подключение к кластеру

После того как кластер поднялся, оператор создаёт в namespace набор ресурсов. Разберём главные.

Секреты

kubectl get secrets

NAME                     TYPE                       DATA   AGE
my-cluster-app           kubernetes.io/basic-auth   11     1d4h
my-cluster-ca            Opaque                     2      1d4h
my-cluster-replication   kubernetes.io/tls          2      1d4h
my-cluster-server        kubernetes.io/tls          2      1d4h

Все данные для подключения хранятся в секрете my-cluster-app. Достать их в читаемом виде можно следующим образом:

kubectl get secret my-cluster-app -o json \
  | jq -r '.data | to_entries[] | "\(.key): \(.value | @base64d)"'

Три сервиса (три точки входа)

kubectl get services

NAME            TYPE        CLUSTER-IP      EXTERNAL-IP   PORT(S)    AGE
my-cluster-r    ClusterIP   10.105.200.51   <none>        5432/TCP   1d4h
my-cluster-ro   ClusterIP   10.97.105.14   <none>        5432/TCP   1d4h
my-cluster-rw   ClusterIP   10.99.140.210   <none>        5432/TCP   1d4h

Важно то, что оператор создаёт три сервиса для каждого кластера, у каждого сервиса своя семантика, и правильный выбор напрямую влияет на поведение приложения при failover:

Операции записи всегда идут через -rw. В этом фишка автоматического failover: сервис меняет endpoint незаметно для приложения, я бы сказал бесшовно.

Заходим в кластер

Через плагин kubectl cnpg (дока по установке):

kubectl cnpg psql -n default my-cluster

Через стандартный psql

psql -h <host> -p <port> -U <username> -d <dbname>

Креды подставляем из секрета my-cluster-app

Итог

За несколько манифестов мы получили то, на настройку чего раньше уходили дни: высокодоступный PostgreSQL-кластер в Kubernetes с потоковой репликацией, автоматическим failover и полностью декларативным управлением.

Что отличает CNPG от "просто PostgreSQL в StatefulSet":

• Прямое управление PVC без ограничений StatefulSet (включая ресайзинг на лету)

• Автоматический failover с промоцией самой актуальной реплики

• Три семантически разных сервиса для грамотной маршрутизации нагрузки

• Декларативное управление базами, пользователями и расписаниями бэкапов

• Высокий уровень автоматизации