cnpg: kubectl-плагин для CloudNativePG — подробный разбор всех команд

cnpg — официальный плагин для kubectl, который ставится через krew и сильно облегчает повседневную работу с PostgreSQL-кластерами под управлением CloudNativePG . Без него почти каждая операция превращается в длинную цепочку kubectl get/patch/exec с YAML-патчами и ручным base64 -d.

В статье — установка и подробный разбор всех практически полезных команд плагина, с примерами и краткими комментариями, когда что использовать.

Если вы только знакомитесь с CloudNativePG — посмотрите серию переводов рецептов Gabriele Bartolini. А Рецепт 14 даёт обзор связки cnpg + view-secret + view-cert + stern, которая закрывает 90% повседневной операционки.

Установка

Через krew (рекомендуется)

Если уже установлен krew:

kubectl krew install cnpg

Обновление:

kubectl krew update
kubectl krew upgrade cnpg

Альтернативные способы

Установочный скрипт от мейнтейнеров:

curl -sSfL \
  https://github.com/cloudnative-pg/cloudnative-pg/raw/main/hack/install-cnpg-plugin.sh | \
  sudo sh -s -- -b /usr/local/bin

Homebrew (управляется community):

brew install kubectl-cnpg

Готовые пакеты (.deb, .rpm) под Linux лежат в Releases — удобно для air-gapped окружений и CI-агентов.

Поддерживаемые архитектуры

Linux (amd64, arm 5/6/7, arm64, s390x, ppc64le), macOS (amd64, arm64), Windows (386, amd64, arm 5/6/7, arm64).

Автодополнение

# bash
echo "source <(kubectl cnpg completion bash)" >> ~/.bashrc

# zsh
kubectl cnpg completion zsh > "${fpath[1]}/_kubectl-cnpg"

В Homebrew autocomplete уже подключается автоматически.

Краткая шпаргалка

Дальше — детально по каждой.

Диагностика

status — обзор состояния кластера

Самая ходовая команда. Показывает: имя и system ID кластера, образ PostgreSQL, имя primary и uptime, число инстансов и ready-инстансов, размер БД, текущую WAL-позицию, статус continuous backup, статус streaming replication (LSN, лаги, sync state) и список инстансов с их ролями.

kubectl cnpg status sandbox

Пример вывода:

Cluster Summary
Name:                default/sandbox
System ID:           7423474350493388827
PostgreSQL Image:    ghcr.io/cloudnative-pg/postgresql:16.4
Primary instance:    sandbox-1
Primary start time:  2024-10-08 18:31:57 +0000 UTC (uptime 1m14s)
Status:              Cluster in healthy state
Instances:           3
Ready instances:     3
Size:                126M
Current Write LSN:   0/604DE38 (Timeline: 1 - WAL File: 000000010000000000000006)

Streaming Replication status
Name       Sent LSN   Write LSN  Flush LSN  Replay LSN  ...  State      Sync State
sandbox-2  0/604DE38  0/604DE38  0/604DE38  0/604DE38   ...  streaming  async
sandbox-3  0/604DE38  0/604DE38  0/604DE38  0/604DE38   ...  streaming  async

Instances status
Name       Current LSN  Replication role  Status  QoS         Manager  Node
sandbox-1  0/604DE38    Primary           OK      BestEffort  1.29.0   k8s-eu-worker
sandbox-2  0/604DE38    Standby (async)   OK      BestEffort  1.29.0   k8s-eu-worker2
sandbox-3  0/604DE38    Standby (async)   OK      BestEffort  1.29.0   k8s-eu-worker

Полезные флаги:

• --verbose (-v) — больше деталей: PDB, managed roles, tablespaces, физические бэкапы. Можно повторить (-v -v) — добавятся PostgreSQL-конфиг, HBA-правила и сертификаты.
• -o yaml / -o json — машинно-читаемый вывод.
• --timeout 45s — для больших БД (>1 TB) дефолтные 10 секунд могут не хватать (status зовёт du/cat по подам).

report operator и report cluster — диагностический ZIP

Когда что-то сломалось и нужно отдать данные мейнтейнерам / коллегам.

По оператору:

kubectl cnpg report operator -n cnpg-system

Соберёт в ZIP: deployment оператора, ConfigMaps, события, логи подов оператора, секреты (по запросу), webhook configs, OLM-ресурсы (если есть).

По кластеру:

kubectl cnpg report cluster sandbox

В архив попадут: манифест Cluster, список подов, их логи, события, jobs, PVC-ы. Полезные флаги:

• --logs — включает логи (выключен по умолчанию из-за объёма);
• --include-default-secrets — добавить дефолтные секреты (CA, server-cert и т. п.).

logs cluster и logs pretty — централизованные логи

# Скачать логи всех инстансов кластера в файлы
kubectl cnpg logs cluster sandbox --output ./sandbox-logs

# Стримить логи всех инстансов
kubectl cnpg logs cluster sandbox -f

logs pretty форматирует JSON-логи оператора в человеко-читаемый вид:

kubectl logs deployment/cnpg-controller-manager -n cnpg-system | \
  kubectl cnpg logs pretty

Жизненный цикл кластера

restart — рестарт кластера или одного инстанса

# Rolling-restart всего кластера (полезно после изменения ConfigMap)
kubectl cnpg restart sandbox

# Рестарт конкретного инстанса
kubectl cnpg restart sandbox sandbox-2

Поведение зависит от роли:

• Primary → in-place restart, либо switchover (если изменения требуют его).
• Replica → удаление и пересоздание пода.

Если хочется, чтобы изменения в ConfigMap/Secret применялись автоматически, повесьте на них лейбл cnpg.io/reload.

reload — мягкий reconcile

kubectl cnpg reload sandbox

Просит оператор прокрутить reconcile-цикл. Применить новые ConfigMap‘ы с custom-метриками — без рестарта подов.

promote — повысить standby до primary

# По имени пода
kubectl cnpg promote sandbox sandbox-2

# Или по серийному номеру
kubectl cnpg promote sandbox 2

Используется для контролируемого switchover’а (например, перед обслуживанием конкретной ноды).

destroy — снести инстанс и его PVC

# Удалить под и все его PVC
kubectl cnpg destroy cluster-example 2

# Сохранить PVC (для последующего ручного использования)
kubectl cnpg destroy cluster-example 2 --keep-pvc

С --keep-pvc оператор уберёт ownerReferences и поменяет лейбл cnpg.io/pvcStatus с ready на detached. Повторный запуск без флага — окончательно удалит «отвязанные» PVC.

hibernate — гибернация кластера

Полезно, когда временно нужно остановить кластер, не удаляя данные. Под капотом — аннотация cnpg.io/hibernation.

# Усыпить (поды убираются, PVC живут)
kubectl cnpg hibernate on sandbox

# Разбудить
kubectl cnpg hibernate off sandbox

# Проверка
kubectl cnpg status sandbox

maintenance — окно обслуживания нод

Массовое выставление .spec.nodeMaintenanceWindow.inProgress:

# Выставить флаг maintenance во всех namespace'ах
kubectl cnpg maintenance set --all-namespaces

# Снять
kubectl cnpg maintenance unset --all-namespaces

С флагом --reusePVC оператор будет реюзать PVC при пересоздании подов.

Перед применением плагин показывает список затрагиваемых кластеров и просит подтверждение:

Namespace  Cluster Name     Maintenance  reusePVC
---------  ------------     -----------  --------
default    cluster-example  true         false
default    pg-backup        true         false
test       cluster-example  true         false
Do you want to proceed? [y/n]: y

fencing — заморозка инстансов

Заморозка отключает оператор от управления конкретным инстансом или всем кластером — полезно для ручного дебага PostgreSQL изнутри.

# Заморозить весь кластер
kubectl cnpg fencing on sandbox

# Заморозить конкретный под
kubectl cnpg fencing on sandbox sandbox-2

# Снять заморозку
kubectl cnpg fencing off sandbox

Бэкап

backup — запросить новый физический бэкап

Создаёт ресурс Backup:

# Обычный backup (Barman Cloud, например)
kubectl cnpg backup sandbox

# Volume snapshot
kubectl cnpg backup sandbox -m volumeSnapshot

# Online (hot) volume snapshot
kubectl cnpg backup sandbox -m volumeSnapshot --online

# Указать целевой инстанс политики
kubectl cnpg backup sandbox --backup-target prefer-standby

Имя бэкапа генерируется по времени запроса:

$ kubectl cnpg backup cluster-example
backup/cluster-example-20230121002300 created

Дополнительные тонкие флаги для volume snapshot’ов: --immediate-checkpoint, --wait-for-archive.

Сертификаты

certificate — выпустить TLS-сертификат для пользователя

Оператор уже поднял CA для каждого кластера (см. Рецепт 2). Этой командой выпускается клиентский сертификат для конкретного PostgreSQL-пользователя.

kubectl cnpg certificate cluster-cert \
  --cnpg-cluster sandbox \
  --cnpg-user app

Извлечь содержимое:

kubectl get secret cluster-cert -o json | \
  jq -r '.data | map(@base64d) | .[]'

Бенчмарки

pgbench — нагрузочный тест PostgreSQL

# 30 секунд, 1 клиент, 1 поток
kubectl cnpg pgbench sandbox -- --time 30 --client 1 --jobs 1

Всё, что после --, передаётся встроенному pgbench. Поднимает временный Job рядом с кластером, который и гоняет нагрузку.

fio — бенчмарк storage

kubectl cnpg fio my-fio-job -n default

Создаёт PVC + ConfigMap + Deployment с fio для измерения IOPS/throughput на storage-классе CloudNativePG. Очень полезно при выборе storage-класса под Postgres (Рецепт 6).

Доступ к БД

psql — psql внутри пода

# Подключение к primary (под пользователем postgres, к БД postgres)
kubectl cnpg psql sandbox

# К реплике
kubectl cnpg psql --replica sandbox

# К конкретной БД
kubectl cnpg psql sandbox -- app

# Сразу выполнить запрос
kubectl cnpg psql sandbox -- -c "SELECT pg_is_in_recovery();"

⚠️ Подключение идёт от пользователя postgres (суперпользователя). На проде использовать только осознанно и авторизованно. Подробнее про политику suprerusers в CloudNativePG — Рецепт 3.

pgadmin4 — pgAdmin рядом с кластером

# Desktop-mode, без аутентификации (для evaluation/обучения)
kubectl cnpg pgadmin4 --mode desktop sandbox

# Server-mode (с аутентификацией pgAdmin)
kubectl cnpg pgadmin4 sandbox

# Просто посмотреть манифесты
kubectl cnpg pgadmin4 --dry-run sandbox

После запуска плагин подсказывает, как сделать port-forward на pgAdmin. Подробнее — Рецепт 4.

Логическая репликация

Самая мощная часть плагина — управление PostgreSQL PUBLICATION / SUBSCRIPTION декларативно через kubectl. Спасает при миграциях ~0 downtime (Рецепт 5).

⚠️ Перед использованием — обязательно изучите ограничения логической репликации PostgreSQL (DDL, sequences, large objects).

publication create — создать публикацию

Структура:

kubectl cnpg publication create \
  --publication PUBLICATION_NAME \
  [--external-cluster EXTERNAL_CLUSTER] \
  LOCAL_CLUSTER [options]

Два сценария:

• С --external-cluster — создать публикацию в внешнем кластере (определённом в externalClusters). SQL уходит в EXTERNAL_CLUSTER, команда запускается из LOCAL_CLUSTER.
• Без --external-cluster — создать публикацию в локальном CloudNativePG-кластере (по умолчанию в БД app).

Способы выбрать таблицы:

• --all-tables → CREATE PUBLICATION ... FOR ALL TABLES
• --table (можно повторять) — конкретные таблицы с выражением.
• --schema (PostgreSQL 15+) — все таблицы в схеме.

--dry-run показывает SQL, который будет выполнен, но не выполняет его.

Пример: публикация на внешнем кластере

kubectl cnpg publication create destination-cluster \
  --external-cluster=source-cluster \
  --all-tables

Пример: публикация в локальном кластере

kubectl cnpg publication create source-cluster \
  --publication=app --all-tables

publication drop — удалить публикацию

kubectl cnpg publication drop \
  --publication PUBLICATION_NAME \
  [--external-cluster EXTERNAL_CLUSTER] \
  LOCAL_CLUSTER

subscription create — создать подписку

kubectl cnpg subscription create \
  --subscription SUBSCRIPTION_NAME \
  --publication PUBLICATION_NAME \
  --external-cluster EXTERNAL_CLUSTER \
  LOCAL_CLUSTER

Подписка живёт в LOCAL_CLUSTER и тянет данные из publication во внешнем кластере.

Пример:

kubectl cnpg subscription create destination-cluster \
  --external-cluster=source-cluster \
  --publication=app \
  --subscription=app

subscription drop — удалить подписку

kubectl cnpg subscription drop \
  --subscription SUBSCRIPTION_NAME \
  LOCAL_CLUSTER

subscription sync-sequences — синхронизация последовательностей

Главное ограничение PostgreSQL logical replication — последовательности (sequences) не реплицируются. При cutover их надо синхронизировать вручную перед переключением приложения. Эта команда подключается к источнику, читает все sequence’ы и обновляет их значения в локальной (целевой) БД:

kubectl cnpg subscription sync-sequences \
  --subscription app \
  destination-cluster

Установочные манифесты

install generate — сгенерировать манифесты оператора

Полезно для GitOps: сохранить манифесты оператора в репозиторий и применять через Argo/Flux.

# Сгенерировать дефолтный набор
kubectl cnpg install generate > cnpg.yaml

# Указать namespace и watch-namespace
kubectl cnpg install generate \
  --namespace cnpg-system \
  --watch-namespaces "default,production" \
  > cnpg.yaml

Применяется как обычно: kubectl apply --server-side -f cnpg.yaml.

Permissions: что нужно RBAC

Не все команды требуют админ-прав. Для CI / on-call ролей можно нарезать узкие RBAC. Минимальная сводка из официальной доки:

Полная таблица — в официальной документации .

💡 Дать роли list на clusters — заработает автодополнение для большинства команд.

Интеграция с k9s

В k9s можно повесить cnpg-команды на горячие клавиши через k9s/plugins.yml . После этого, например, Shift+P на ресурсе Cluster запустит kubectl cnpg promote, Shift+R — restart, Shift+S — status, и т. д.

Что в итоге

cnpg-плагин закрывает практически весь day-to-day управления PostgreSQL в Kubernetes: от рутинной диагностики и backup’ов до сложной логической репликации с миграцией ~0 downtime. Особенно полезен в связке с другими krew-плагинами:

kubectl krew install cnpg view-secret view-cert stern ctx ns neat

Этот набор закрывает 90% операционки и сильно сокращает количество CLI-цепочек, которые надо помнить наизусть.

Полезные ссылки

• Официальная документация плагина
• Репозиторий CloudNativePG
• krew — обзорная статья про менеджер плагинов и подборку must-have
• Серия рецептов CloudNativePG (перевод) — практические сценарии, в которых этот плагин используется