Index

Документация по установке и использованию PostgreSQL через Crunchy PGO (PostgreSQL Operator).

Описание

Crunchy PGO (PostgreSQL Operator) - оператор Kubernetes для управления PostgreSQL кластерами с автоматическим failover, backup и restore.

Возможности

✅ Автоматический failover
✅ Connection pooling (PgBouncer)
✅ Backup и restore (pgBackRest)
✅ Репликация (read replicas)
✅ Мониторинг и логирование
✅ Интеграция с Prometheus

Текущая конфигурация

Operator namespace: tech-postgres-operator
Databases namespace: tech-postgres-databases
Storage: Longhorn (60Gi per instance, StorageClass: longhorn-postgres)
Placement: Operator на masters, PostgreSQL на workers

Быстрый старт

1. Подготовка нод

Подготовка нод выполняется автоматически через Ansible playbook:

cd ../.. && make k8s-prepare-nodes

Это добавит: - На master нодах: label node-role.kubernetes.io/control-plane=true и taint node-role.kubernetes.io/control-plane:NoSchedule - На worker нодах: label node-role.kubernetes.io/worker=true

Или вручную (замените <masterX> и <workerX> на реальные имена нод):

# Master ноды
kubectl taint nodes <master-node-name> node-role.kubernetes.io/control-plane=:NoSchedule --overwrite
kubectl label node <master-node-name> node-role.kubernetes.io/control-plane=true --overwrite
# Повторите для всех master нод

# Worker ноды
kubectl label node <worker1> node-role.kubernetes.io/worker=true --overwrite
# Повторите для всех worker нод

2. Установка Operator

1	`make postgres-install-operator`

3. Создание кластера

1	`make postgres-create-cluster`

4. Проверка статуса

1	`make postgres-status`

Архитектура

Компоненты

Компонент	Namespace	Расположение	Описание
PGO Operator	`tech-postgres-operator`	Control-plane ноды	Управляет кластерами
PostgreSQL Pods	`tech-postgres-databases`	Worker ноды	Основные инстансы БД
PgBouncer	`tech-postgres-databases`	Worker ноды	Connection pooler
pgBackRest	`tech-postgres-databases`	Worker ноды	Backup и restore

Кластер pg-public

┌─────────────────────────────────────┐
│  tech-postgres-databases           │
├─────────────────────────────────────┤
│  pg-public-instance1-xxxxx (Primary)│
│  ├── PostgreSQL 17                 │
│  └── Volume: 60Gi (Longhorn)       │
│                                     │
│  pg-public-instance1-xxxxx (Replica)│
│  ├── PostgreSQL 17                 │
│  └── Volume: 60Gi (Longhorn)       │
│                                     │
│  pg-public-pgbouncer-xxxxx         │
│  └── PgBouncer                     │
│                                     │
│  pg-public-backup-xxxxx            │
│  └── pgBackRest                    │
└─────────────────────────────────────┘

Команды

Управление

make postgres-prepare-nodes        # Подготовка нод (labels, taints)
make postgres-install-operator     # Установка оператора
make postgres-create-cluster       # Создание кластера pg-public
make postgres-status               # Статус оператора и кластеров
make postgres-connect              # Инструкции по подключению
make postgres-uninstall            # Удаление (УДАЛЯЕТ ДАННЫЕ!)

Сервисные БД

make postgres-init-service-db SERVICE=name           # Инициализация БД для сервиса
make postgres-init-service-db SERVICE=name ROTATE=true  # Ротация пароля
make postgres-get-migration-vars SERVICE=name        # Генерация GitLab CI/CD переменных (опционально)

Мониторинг

make postgres-monitoring-status   # Статус встроенного экспортера метрик

Примечание: Мониторинг встроен в PostgresCluster через monitoring.pgmonitor.exporter. ServiceMonitor и PrometheusRule должны быть настроены отдельно в namespace tech-monitoring.

Справка

make postgres-help  # Справка по PostgreSQL командам

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

Кластер pg-public

Конфигурация в manifests/cluster/pg-public.yaml:

Instances: 2 (1 primary + 1 replica)
Version: PostgreSQL 17
Storage: 60Gi per instance (Longhorn, StorageClass: longhorn-postgres)
Resources: 200m-1 CPU, 512Mi-1Gi RAM
Connection poolers: PgBouncer (2 replicas, transaction mode)
Node placement: Только worker ноды
Pod anti-affinity: Разные worker ноды
Backup: pgBackRest (20Gi storage)

Подключение

Connection Strings

# Primary (write)
pg-public.tech-postgres-databases.svc.cluster.local:5432

# Replica (read)
pg-public-replica.tech-postgres-databases.svc.cluster.local:5432

# Pooler (primary)
pg-public-pgbouncer.tech-postgres-databases.svc.cluster.local:5432

Пользователи

postgres - суперпользователь (по умолчанию)
pgpublic_app - приложение (SUPERUSER, CREATEDB)
pgpublic_readonly - только чтение (NOLOGIN, для внутренних целей)
pgpublic_monitoring - мониторинг (LOGIN, CREATEDB)

Подключение через kubectl

# Primary
kubectl -n tech-postgres-databases exec -it \
  $(kubectl -n tech-postgres-databases get pod -l postgres-operator.crunchydata.com/cluster=pg-public,postgres-operator.crunchydata.com/role=master -o jsonpath='{.items[0].metadata.name}') \
  -- psql -U postgres

# Replica (if available)
kubectl -n tech-postgres-databases exec -it \
  $(kubectl -n tech-postgres-databases get pod -l postgres-operator.crunchydata.com/cluster=pg-public,postgres-operator.crunchydata.com/role=replica -o jsonpath='{.items[0].metadata.name}') \
  -- psql -U postgres

Подключение из приложения

apiVersion: v1
kind: Secret
metadata:
  name: postgres-credentials
  namespace: my-app
type: Opaque
stringData:
  host: pg-public.tech-postgres-databases.svc.cluster.local
  port: "5432"
  database: pg_public
  username: pgpublic_app
  password: <password>

Для получения пароля:

kubectl -n tech-postgres-databases get secret pg-public-pguser-pgpublic-app -o jsonpath='{.data.password}' | base64 -d

Инициализация сервисных БД

Для каждого сервиса, использующего PostgreSQL, необходимо создать отдельную базу данных, пользователя и K8s секрет с credentials.

Создание БД для сервиса

make postgres-init-service-db SERVICE=my-service

Команда: 1. Создаёт базу данных my-service и пользователя my-service в PostgreSQL 2. Генерирует безопасный пароль (или использует существующий, если секрет уже создан) 3. Создаёт Kubernetes секреты в namespace tech-postgres-databases: - pg-user-my-service-stage - pg-user-my-service-pre - pg-user-my-service-prod

Каждый секрет содержит: - host - хост PostgreSQL (pg-public-primary или pg-public-pgbouncer) - port - порт (5432) - database - имя базы данных - user - имя пользователя - password - пароль - uri - полная connection string

Ротация паролей

Для ротации пароля используйте флаг ROTATE=true:

make postgres-init-service-db SERVICE=my-service ROTATE=true

Генерация переменных для GitLab CI/CD (опционально)

Если вы хотите использовать старый способ с GitLab CI/CD Variables (не рекомендуется), можно сгенерировать переменные:

make postgres-get-migration-vars SERVICE=my-service

Команда выведет переменные в трёх форматах: - Base64 (для Masked Variable в GitLab) - File content (для File Variable в GitLab) - Plain string (для обычной переменной)

Автоматическое использование в CI/CD

После инициализации базы данных сервиса, GitLab CI/CD автоматически использует созданные credentials для миграций.

Новое поведение (рекомендуется)

Не нужно добавлять MIGRATION_ENV_VARS_* в GitLab CI/CD Variables!

Credentials автоматически читаются из K8s секретов при выполнении миграций.

Как это работает:

В CI/CD pipeline job migrate-database-{env} проверяет наличие переменной MIGRATION_ENV_VARS_{ENV}
Если переменная не указана, система автоматически:
Определяет окружение из CI_ENVIRONMENT_NAME (stage/pre/production)
Читает секрет pg-user-{SERVICE}-{env} из namespace tech-postgres-databases через kubectl
Извлекает credentials и создаёт .env.migration для docker

Требования:

Секрет должен существовать: make postgres-init-service-db SERVICE=your-service
RBAC должен быть применён: cd ../gitlab-runner && make gitlab-runner-apply-rbac
KUBECONFIG настроен в CI jobs (уже есть через KUBECONFIG_STAGE/PRE/PROD)

Подробнее см. GitLab Runner RBAC.

Старое поведение (deprecated, но работает)

Можно вручную добавить переменные через make postgres-get-migration-vars SERVICE=name и прописать их в GitLab CI/CD Variables:

{SERVICE}_MIGRATION_ENV_STAGE
{SERVICE}_MIGRATION_ENV_PRE
{SERVICE}_MIGRATION_ENV_PROD

Это полезно для: - Специальных случаев (кастомные настройки подключения) - Override стандартных настроек - Отладки проблем с миграциями

Пример: Инициализация для нового сервиса

# 1. Создать БД и секреты
cd infra/k8s
make postgres-init-service-db SERVICE=my-new-service

# 2. Настроить RBAC для GitLab Runner (если ещё не настроено)
make gitlab-runner-apply-rbac

# 3. Запустить pipeline с миграциями
# Миграции автоматически используют credentials из K8s секретов

В логах CI/CD вы увидите:

MIGRATION_ENV_VARS not set, auto-fetching from Kubernetes secrets...
Fetching credentials from K8s secret: pg-user-my-new-service-stage (namespace: tech-postgres-databases)
Successfully fetched credentials from Kubernetes (secret: pg-user-my-new-service-stage)

Troubleshooting

Operator не запускается

# Проверить логи
kubectl -n tech-postgres-operator logs deployment/postgres-operator

# Проверить nodeSelector
kubectl -n tech-postgres-operator get deployment postgres-operator -o yaml | grep -A 5 nodeSelector

PostgreSQL pods не создаются

# Проверить статус кластера
kubectl -n tech-postgres-databases get postgrescluster pg-public -o yaml

# Проверить события
kubectl -n tech-postgres-databases get events --sort-by='.lastTimestamp'

# Проверить PVC
kubectl -n tech-postgres-databases get pvc

Pods не распределяются по нодам

# Проверить labels на нодах
kubectl get nodes --show-labels | grep worker

# Проверить pod anti-affinity
kubectl -n tech-postgres-databases get pods -l postgres-operator.crunchydata.com/cluster=pg-public -o wide

Проблемы с подключением

# Проверить services
kubectl -n tech-postgres-databases get svc -l postgres-operator.crunchydata.com/cluster=pg-public

# Проверить endpoints
kubectl -n tech-postgres-databases get endpoints pg-public

# Тест подключения
kubectl -n tech-postgres-databases run psql-test --rm -it --image=postgres:17 -- psql -h pg-public.tech-postgres-databases.svc.cluster.local -U postgres

Ошибка "permission denied for schema public"

В PostgreSQL 15+ схема public по умолчанию не имеет прав для обычных пользователей. Если приложение получает ошибку [42501] ERROR: permission denied for schema public, нужно выдать права вручную.

Выдача прав для всех пользователей приложений:

POD=$(kubectl -n tech-postgres-databases get pod -l postgres-operator.crunchydata.com/cluster=pg-public,postgres-operator.crunchydata.com/role=master -o jsonpath='{.items[0].metadata.name}')

# Для authentik
kubectl -n tech-postgres-databases exec $POD -- psql -U postgres -d authentik -c "
GRANT USAGE, CREATE ON SCHEMA public TO authentik;
GRANT ALL PRIVILEGES ON ALL TABLES IN SCHEMA public TO authentik;
GRANT ALL PRIVILEGES ON ALL SEQUENCES IN SCHEMA public TO authentik;
ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT ALL ON TABLES TO authentik;
ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT ALL ON SEQUENCES TO authentik;
ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT ALL ON FUNCTIONS TO authentik;
"

# Для sonarqube
kubectl -n tech-postgres-databases exec $POD -- psql -U postgres -d sonarqube -c "
GRANT USAGE, CREATE ON SCHEMA public TO sonarqube;
GRANT ALL PRIVILEGES ON ALL TABLES IN SCHEMA public TO sonarqube;
GRANT ALL PRIVILEGES ON ALL SEQUENCES IN SCHEMA public TO sonarqube;
ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT ALL ON TABLES TO sonarqube;
ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT ALL ON SEQUENCES TO sonarqube;
ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT ALL ON FUNCTIONS TO sonarqube;
"

# Для glitchtip
kubectl -n tech-postgres-databases exec $POD -- psql -U postgres -d glitchtip -c "
GRANT USAGE, CREATE ON SCHEMA public TO glitchtip;
GRANT ALL PRIVILEGES ON ALL TABLES IN SCHEMA public TO glitchtip;
GRANT ALL PRIVILEGES ON ALL SEQUENCES IN SCHEMA public TO glitchtip;
ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT ALL ON TABLES TO glitchtip;
ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT ALL ON SEQUENCES TO glitchtip;
ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT ALL ON FUNCTIONS TO glitchtip;
"

Проверка прав:

POD=$(kubectl -n tech-postgres-databases get pod -l postgres-operator.crunchydata.com/cluster=pg-public,postgres-operator.crunchydata.com/role=master -o jsonpath='{.items[0].metadata.name}')

kubectl -n tech-postgres-databases exec $POD -- psql -U postgres -d authentik -c "
SELECT
    has_schema_privilege('authentik', 'public', 'USAGE') as has_usage,
    has_schema_privilege('authentik', 'public', 'CREATE') as has_create;
"

Ожидаемый результат: has_usage = true и has_create = true.

Примечание: Для новых баз данных права можно настроить автоматически через databaseInitSQL в конфигурации PostgresCluster (см. manifests/cluster/pg-public.yaml).

Мониторинг

PostgreSQL кластер мониторится через встроенный postgres-exporter, который настраивается в PostgresCluster CR через секцию monitoring.pgmonitor.exporter.

Компоненты мониторинга

Встроенный экспортер - автоматически создается Crunchy PGO для каждого инстанса PostgreSQL
ServiceMonitor - конфигурация для Prometheus (должен быть настроен в namespace tech-monitoring)
PrometheusRule - алерты для PostgreSQL (должен быть настроен в namespace tech-monitoring)

Важно: Экспортер встроен в кластер и автоматически собирает метрики с primary и replica инстансов.

Конфигурация мониторинга

Мониторинг настраивается в манифесте кластера (manifests/cluster/pg-public.yaml):

monitoring:
  pgmonitor:
    exporter:
      image: quay.io/prometheuscommunity/postgres-exporter:v0.18.1
      resources:
        requests:
          cpu: "50m"
          memory: "64Mi"
        limits:
          cpu: "200m"
          memory: "128Mi"

Настройка ServiceMonitor и PrometheusRule

ServiceMonitor и PrometheusRule должны быть настроены отдельно в namespace tech-monitoring для сбора метрик из встроенного экспортера.

Проверка статуса

# Статус встроенного экспортера
make postgres-monitoring-status

# Проверка метрик напрямую (через service кластера)
kubectl -n tech-postgres-databases port-forward svc/pg-public 9187:9187
curl http://localhost:9187/metrics

Метрики

Встроенный экспортер собирает следующие метрики:

pg_up - доступность PostgreSQL (1 = доступен, 0 = недоступен)
pg_stat_database_* - статистика по базам данных
pg_stat_activity_* - активные подключения и запросы
pg_replication_* - метрики репликации
pg_stat_statements_* - статистика выполнения запросов
pg_settings_* - настройки PostgreSQL

Алерты

Настроены следующие алерты:

Доступность: - PostgresDown - PostgreSQL недоступен (5 min) - PostgresExporterDown - экспортер не может подключиться (5 min)

Подключения: - PostgresTooManyConnections - используется >80% подключений (5 min) - PostgresMaxConnectionsReached - используется >95% подключений (2 min)

Репликация: - PostgresReplicationLag - отставание репликации >30s (5 min) - PostgresReplicationLagCritical - отставание репликации >300s (5 min) - PostgresReplicationNotRunning - репликация не работает (10 min)

Производительность: - PostgresSlowQueries - медленные запросы (avg >1s, 10 min) - PostgresHighCPUUsage - высокое использование CPU (10 min) - PostgresHighMemoryUsage - высокое использование памяти (10 min)

Хранилище: - PostgresDatabaseSize - размер БД >50GB (5 min) - PostgresDatabaseSizeCritical - размер БД >55GB (5 min)

Backups (pgBackRest): - NoRecentBackup - нет бэкапа за 24 часа (15 min) - PostgresBackupRecoveryWindowLow - recovery window <1 часа (5 min) - PostgresWALArchiveStale - WAL архив устарел >1 часа (5 min)

Мониторинг PgBouncer

Текущая реализация:

Мониторинг PgBouncer реализован через sidecar exporter в каждом PgBouncer pod. Это обеспечивает: - Автоматическое масштабирование: каждый PgBouncer pod имеет свой exporter - Устойчивость к рестартам: Service выбирает pods по лейблам, а не по именам - Простоту управления: exporter управляется PGO вместе с PgBouncer

Архитектура:

Feature Gate: PGBouncerSidecars=true включен в операторе
Sidecar контейнер: pgbouncer-exporter добавлен в каждый PgBouncer pod через spec.proxy.pgBouncer.containers
Service: pg-public-pgbouncer-metrics селектит все PgBouncer pods по лейблам
ServiceMonitor: Prometheus скрейпит все endpoints сервиса

Установка pgbouncer_exporter

# Установить PgBouncer exporter (sidecar)
make postgres-install-pgbouncer-exporter

Эта команда: - Создает Service pg-public-pgbouncer-metrics для метрик - Создает ServiceMonitor для Prometheus - Ожидает перезапуска PgBouncer pods с sidecar exporter'ом

Важно: Sidecar exporter добавляется автоматически при применении PostgresCluster с секцией containers. Убедитесь, что feature gate PGBouncerSidecars=true включен в операторе.

Проверка работы:

# Проверить, что sidecar exporter запущен в каждом PgBouncer pod
kubectl -n tech-postgres-databases get pods -l postgres-operator.crunchydata.com/role=pgbouncer -o jsonpath='{range .items[*]}{.metadata.name}{"\t"}{.spec.containers[*].name}{"\n"}{end}'

# Проверить метрики через Service
kubectl -n tech-postgres-databases port-forward svc/pg-public-pgbouncer-metrics 9127:9127
# Откройте http://localhost:9127/metrics в браузере

# Проверить метрики
kubectl -n tech-postgres-databases port-forward svc/pg-public-pgbouncer-exporter 9127:9127
# Откройте http://localhost:9127/metrics

Метрики pgbouncer_exporter:

pgbouncer_pools_* - статистика пулов (client_active, server_active, и т.д.)
pgbouncer_stats_* - общая статистика (total_requests, total_received, и т.д.)
pgbouncer_databases_* - статистика по базам данных
pgbouncer_lists_* - списки подключений

Удаление:

1	`make postgres-uninstall-pgbouncer-exporter`

Для включения OpenTelemetryMetrics (альтернатива): - Обновите оператор до версии 5.8.6+ (UBI9) - Включите feature gate: PGO_FEATURE_GATES="OpenTelemetryMetrics=true" - Добавьте instrumentation: {} в PostgresCluster spec - Примените PodMonitor для PgBouncer (см. monitoring/manifests/monitors/pgbouncer-exporter.yaml) - PostgresHighWALUsage - WAL файлы >4GB (10 min)

Deadlocks: - PostgresDeadlocks - обнаружены deadlocks (5 min) - PostgresHighDeadlockRate - высокая частота deadlocks >1/s (5 min)

Grafana Dashboard

Рекомендуется импортировать дашборд для PostgreSQL:

# Импорт через скрипт
bash monitoring/scripts/import-dashboards.sh 9628

# Или вручную через Grafana UI:
# 1. Откройте Grafana: https://grafana.internal.ai-ops.tech
# 2. "+" → "Import"
# 3. Введите ID: 9628
# 4. Выберите datasource: VictoriaMetrics
# 5. Import

Популярные дашборды: - 9628 - PostgreSQL Database (рекомендуется) - 11159 - PostgreSQL Overview - 6742 - PostgreSQL Database & Table Statistics

Troubleshooting мониторинга

Экспортер не запускается:

# Проверить статус кластера
kubectl -n tech-postgres-databases get postgrescluster pg-public -o yaml

# Проверить поды с экспортером
kubectl -n tech-postgres-databases get pods -l postgres-operator.crunchydata.com/cluster=pg-public | grep exporter

# Проверить логи экспортера
kubectl -n tech-postgres-databases logs -l postgres-operator.crunchydata.com/cluster=pg-public | grep exporter

Метрики не собираются:

# Проверить ServiceMonitor (должен быть настроен в tech-monitoring)
kubectl -n tech-monitoring get servicemonitor postgres-exporter -o yaml

# Проверить targets в Prometheus
make monitoring-port-forward-prometheus
# Откройте http://localhost:9090/targets
# Найдите "postgres-exporter" в списке

Алерты не работают:

# Проверить PrometheusRule
kubectl -n tech-monitoring get prometheusrule postgres-alerts -o yaml

# Проверить алерты в Prometheus
# Откройте http://localhost:9090/alerts

Ссылки

← Назад к главной документации

На странице

Оглавление Описание Возможности Текущая конфигурация Быстрый старт 1. Подготовка нод 2. Установка Operator 3. Создание кластера 4. Проверка статуса Архитектура Компоненты Кластер pg-public Команды Управление Сервисные БД Мониторинг Справка Конфигурация Кластер pg-public Подключение Connection Strings Пользователи Подключение через kubectl Подключение из приложения Инициализация сервисных БД Создание БД для сервиса Ротация паролей Генерация переменных для GitLab CI/CD (опционально) Автоматическое использование в CI/CD Новое поведение (рекомендуется) Старое поведение (deprecated, но работает) Пример: Инициализация для нового сервиса Troubleshooting Operator не запускается PostgreSQL pods не создаются Pods не распределяются по нодам Проблемы с подключением Ошибка "permission denied for schema public" Мониторинг Компоненты мониторинга Конфигурация мониторинга Настройка ServiceMonitor и PrometheusRule Проверка статуса Метрики Алерты Мониторинг PgBouncer Grafana Dashboard Troubleshooting мониторинга Ссылки