Управляемый сервис PostgreSQL

PostgreSQL в настоящее время является лидирующим выбором среди реляционных баз данных и известен своей надёжной функциональностью и производительностью. Управляемый сервис PostgreSQL использует реализацию на стороне платформы для предоставления самовосстанавливающегося реплицируемого кластера. Этот кластер эффективно управляется с помощью широко признанного оператора CloudNativePG, получившего популярность в сообществе.

Детали развёртывания

Этот управляемый сервис контролируется оператором CloudNativePG, обеспечивающим эффективное управление и бесперебойную работу.

• Документация: https://cloudnative-pg.io/docs/
• Github: https://github.com/cloudnative-pg/cloudnative-pg

Операции

Резервное копирование PostgreSQL имеет два уровня, и в рекомендуемой конфигурации используются оба уровня вместе, а не один из них:

Канонический вариант настройки зависит от того, поставляется ли в кластере платформенный BackupClass cozy-default.

Platform-managed flow (recommended for new clusters) — opt in via backup.useSystemBucket: true and reference cozy-default from BackupJob/Plan/RestoreJob. The chart leaves S3 coordinates blank; the CNPG driver SSA-applies a barman-cloud ObjectStore and patches spec.plugins from the platform-managed bucket coordinates at first BackupJob time.

spec:
  backup:
    enabled: true
    useSystemBucket: true        # platform projects cozy-backups-creds + driver SSA-applies ObjectStore + patches spec.plugins

Legacy chart-managed flow — for clusters that pre-date the platform BackupClass or use a tuned non-default bucket. Provide all S3 coordinates inline (or via s3CredentialsSecret.name); spec.plugins and the barman-cloud ObjectStore render from helm-install onwards.

spec:
  backup:
    enabled: true                # архивировать WAL в объектное хранилище
    destinationPath: s3://my-bucket/pg-src/
    endpointURL: https://seaweedfs-s3.tenant-foo:8333
    s3CredentialsSecret:
      name: pg-src-cnpg-backup-creds
    endpointCA:
      name: pg-src-cnpg-backup-ca
    # backup.schedule намеренно оставлен пустым — BackupClass / Plan
    # ниже управляют повторяющимся резервным копированием; никакой
    # формируемый чартом ScheduledBackup не должен конкурировать с этим расписанием.

paired with a strategy.backups.cozystack.io/CNPG + BackupClass + Plan in the same tenant. The end-to-end e2e fixture under examples/backups/postgres/ is the canonical reference (05-postgres-src.yaml shows the chart side, 10-cnpg-strategy.yaml and 15-backupclass.yaml show the orchestration side, 25-backupjob-adhoc.yaml and 40-restorejob-to-copy.yaml show ad-hoc backup and restore).

Why both layers and not one? WAL archiving is handled by the barman-cloud plugin’s WAL-archiver sidecar - CNPG can attach or detach the plugin at runtime, but any WAL that closed before the plugin began archiving is gone for good. A backup taken from such a cluster is missing the WAL its begin_wal points at, and recovery later fails with WAL not found. Letting the chart wire the plugin from helm-install removes the race.

How to enable backups (preferred: BackupClass + Plan)

End-to-end manifests live under examples/backups/postgres/. Briefly, the moving parts are:

1. A strategy.backups.cozystack.io/CNPG describing the destination bucket and templating the barman-cloud ObjectStore (including a Secret reference to S3 credentials - the credentials never appear on the Postgres CR .spec; see Security note below).
2. A backups.cozystack.io/BackupClass that names the strategy and is selected by an applicationRef matching the Postgres app’s Kind/Name.
3. A backups.cozystack.io/Plan (recurring) or BackupJob (ad-hoc) that references the BackupClass. The controller materialises a Backup artifact when the cnpg.io Backup completes; restores then reference that Backup via RestoreJob.

Both in-place restores (overwrite the source app’s data) and to-copy restores (restore into a separate target Postgres app in the same namespace) are supported via the RestoreJob.spec.targetApplicationRef field.

Security: With the BackupClass path, S3 credentials live in a tenant-readable Secret referenced from the strategy template. The CNPG driver forwards that Secret reference into the Postgres app’s spec.backup.s3CredentialsSecret on restore, so access keys never land in the Postgres CR .spec, etcd object store, or kubectl get -o yaml output. Prefer this over the chart-managed path whenever possible.

How to enable chart-managed scheduled backups (legacy)

The chart can also emit a cnpg.io/ScheduledBackup directly, without a BackupClass. Superseded by the BackupClass + Plan path above and kept around for clusters that did not migrate. It does not run by default - backup.schedule defaults to an empty string, which gates the chart’s ScheduledBackup template off. To turn it on, fill in a CNPG 6-field cron expression:

## @param backup.enabled Enable plugin WAL archiving + render the chart-managed ScheduledBackup
## @param backup.schedule Cron schedule (CNPG 6-field). Empty means no chart-managed ScheduledBackup
## @param backup.retentionPolicy Retention policy
## @param backup.destinationPath Path to store the backup (i.e. s3://bucket/path/to/folder)
## @param backup.endpointURL S3 Endpoint used to upload data to the cloud
## @param backup.s3AccessKey Access key for S3, used for authentication
## @param backup.s3SecretKey Secret key for S3, used for authentication
backup:
  enabled: true
  retentionPolicy: 30d
  destinationPath: s3://bucket/path/to/folder/
  endpointURL: http://minio-gateway-service:9000
  schedule: "0 2 * * * *"  # включение — пусто (по умолчанию) означает отсутствие управляемого чартом расписания
  s3AccessKey: oobaiRus9pah8PhohL1ThaeTa4UVa7gu
  s3SecretKey: ju3eum4dekeich9ahM1te8waeGai0oog

Как восстановить из резервной копии (предпочтительно: RestoreJob)

Для резервных копий, управляемых через BackupClass, создайте backups.cozystack.io/RestoreJob, ссылающийся на нужный Backup. См. examples/backups/postgres/35-restorejob-in-place.yaml и examples/backups/postgres/40-restorejob-to-copy.yaml. On a to-copy restore the controller replaces the target app’s spec.databases and spec.users with the source-spec snapshot persisted in Backup.status.underlyingResources, so the chart’s post-install init-job does not drop the recovered roles or databases.

e2e coverage: the same-namespace to-copy restore (Steps 0-7) leaves the source running and is the deterministic end-to-end signal; it stays a manual / dev-cluster reference flow, not part of the automated e2e suite. The cross-tenant variant (target Postgres in a different tenant from the source’s seaweedfs) stays a manual / dev-cluster exercise — reachability is blocked by the per-tenant Cilium egress policy. The in-place restore code path is shipped and is covered at the unit level by TestClusterHasRecoveryBootstrap_TerminatingCluster, TestCNPGBackupWALArchived, TestCNPGPurgeNeeded, and the rest of the internal/backupcontroller/cnpgstrategy_controller_test.go suite.

How to recover a backup (chart-managed bootstrap)

CloudNativePG supports point-in-time-recovery. Recovering a backup is done by creating a new database instance and restoring the data in it.

Create a new PostgreSQL application with a different name, but identical configuration. Set bootstrap.enabled to true and fill in the name of the database instance to recover from and the recovery time:

## @param bootstrap.enabled Восстановить кластер базы данных из резервной копии
## @param bootstrap.recoveryTime Метка времени (PITR), до которой будет выполнено восстановление, в формате RFC 3339. Если оставить пустым, будет восстановлена последняя
## @param bootstrap.oldName Имя кластера базы данных до удаления
##
bootstrap:
  enabled: false
  recoveryTime: ""  # оставьте пустым для последней или укажите точную метку времени; пример: 2020-11-26 15:22:00.00000+00
  oldName: "<previous-postgres-instance>"

Как переключить первичную/вторичную реплику

См.:

• https://cloudnative-pg.io/documentation/1.15/rolling_update/#manual-updates-supervised

storageClass помечен как неизменяемый (immutable) в схеме чарта — см. docs/storage-immutability.md, где описан этот контракт и какие потребители его обеспечивают.

TLS для серверных подключений

CNPG управляет цепочкой сертификатов сквозным образом. Оператор автоматически генерирует самоподписанный CA, подписывает им конечные (leaf) сертификаты сервера, клиента и репликации и ротирует их по мере необходимости. Чарт не формирует никаких объектов Issuer/Certificate cert-manager — этот путь взаимоисключающий с управляемой оператором цепочкой на admission webhook CNPG.

Что добавляет чарт: когда TLS включён и external: true, чарт устанавливает spec.certificates.serverAltDNSNames в ресурсе CNPG Cluster CR, чтобы внедрить внешнее имя хоста <release>.<_namespace.host> в список SAN автоматически сгенерированного серверного сертификата. Стандартное покрытие SAN в CNPG уже включает три встроенных сервиса ClusterIP (-rw, -r, -ro) во всех четырёх формах DNS (<svc>, <svc>.<ns>, <svc>.<ns>.svc, <svc>.<ns>.svc.<cluster-domain>); требуется добавить только внешнее имя хоста.

Трёхпозиционный параметр tls.enabled определяет, внедряет ли чарт serverAltDNSNames:

• tls.enabled: null (по умолчанию) — режим TLS наследуется от external. При external: true чарт внедряет внешнее имя хоста в управляемый оператором сертификат.
• tls.enabled: true при external: true — эффект тот же, что и по умолчанию.
• tls.enabled: true при external: false — внедрение serverAltDNSNames не требуется (внешнего имени хоста для добавления нет); автоматически сгенерированный сертификат CNPG покрывает внутренние сервисы.
• tls.enabled: false — чарт пропускает внедрение serverAltDNSNames. Примечание: CNPG сохраняет встроенный TLS на уровне соединения независимо от этого флага; данный переключатель управляет лишь тем, добавляется ли внешнее имя хоста в сертификат. Чтобы полностью отключить TLS в PostgreSQL, потребовалось бы установить postgresql.parameters.ssl = "off" на уровне CNPG, что выходит за рамки этого флага.

Получение CA-бандла для проверки на стороне клиента:

CNPG включает сертификат CA в каждый создаваемый им Secret с учётными данными пользователя под ключом ca.crt. Получите его из Secret <release>-credentials, который уже доступен тенантам через RBAC дашборда:

kubectl --context <ctx> --namespace <tenant> \
  get secret <release>-credentials \
  --output jsonpath='{.data.ca\.crt}' | base64 --decode

Подключение с полной проверкой (пример psql):

psql "host=<host> port=5432 dbname=app user=app \
  sslmode=verify-full sslrootcert=ca.crt"

Чтобы sslmode=verify-full работал, полученный выше CA-бандл должен быть сохранён в ca.crt. Без него используйте sslmode=require (шифрует, но не проверяет серверный сертификат).

Параметры

Общие параметры

Конфигурация TLS

Параметры, специфичные для приложения

Синхронная репликация на основе кворума

Конфигурация пользователей

Конфигурация баз данных

Параметры резервного копирования

Параметры начальной загрузки (восстановления)

Примеры и справочник по параметрам

resources и resourcesPreset

resources задаёт явные конфигурации CPU и памяти для каждой реплики. Если оставить пустым, применяется пресет, указанный в resourcesPreset.

resources:
  cpu: 4000m
  memory: 4Gi

resourcesPreset задаёт именованные конфигурации CPU и памяти для каждой реплики. Эта настройка игнорируется, если задано соответствующее значение resources.

Пресеты следуют облачной схеме именования <серия>.<размер>. Пять серий покрывают весь диапазон соотношений CPU к памяти (t1 1:0.5, c1 1:1, s1 1:2, u1 1:4, m1 1:8), и каждая серия поставляется с восемью размерами (от nano до 4xlarge). Устаревшие плоские имена (nano, micro, small, medium, large, xlarge, 2xlarge) по-прежнему принимаются как устаревшие псевдонимы соответствующих типов инстансов с соотношением 1:1.

См. docs/operations/resource-presets.md, где приведены полная матрица размеров и сопоставление устаревших имён с типами инстансов.

users

users:
  user1:
    password: strongpassword
  user2:
    password: hackme
  airflow:
    password: qwerty123
  debezium:
    replication: true

databases

databases:
  myapp:
    roles:
      admin:
      - user1
      - debezium
      readonly:
      - user2
  airflow:
    roles:
      admin:
      - airflow
    extensions:
    - hstore