Документация spg99

1.1. Что такое spg99

spg99 — это PostgreSQL‑платформа как сервис с отделённым storage и «serverless»‑подходом к compute в российском облаке.

Базовая идея:

• •данные и WAL живут в S3‑совместимом хранилище в РФ через связку Pageserver/Safekeeper;
• •compute‑узлы PostgreSQL — одноразовые VM в облаке (сейчас — Яндекс.Облако), которые можно поднимать и останавливать сколько угодно раз;
• •на compute используется чистый PostgreSQL без форков и внутренних патчей; мы не меняем его поведение, опираемся на стандартные механизмы хранения и репликации;
• •всё это управляется единым Control Plane, который:
  • ·хранит каталог tenants/БД/timeline/state/scale;
  • ·выдаёт DSN и токены;
  • ·оркестрирует запуск/остановку compute;
  • ·предоставляет CLI spgctl и REST API v2.

Для приложения spg99 выглядит как обычный PostgreSQL:

• •стандартный DSN вида postgres://<pg_user>:<pg_password>@provisioner.spg99.ru:5432/<db-name>?sslmode=require — pg_user/pg_password выдаются при создании tenant, <db-name> — имя вашей БД.
• •стандартный PostgreSQL‑протокол по TLS;
• •нет привязки к конкретной VM или IP — есть один Gateway‑endpoint.

1.2. Какие задачи решает spg99

spg99 решает типичные инфраструктурные задачи вокруг PostgreSQL, которые в классической модели ложатся на команду разработки/DevOps/DBA:

1.3. Чем spg99 отличается от классического PostgreSQL на VM

Классическая модель «PostgreSQL на VM в облаке» требует самостоятельного управления инфраструктурой и оплаты простаивающих ресурсов. spg99 переводит это в платформенную модель.

1. Разделение storage и compute

   В классике: данные и WAL на дисках VM; потеря VM/диска = риск потери данных, если бэкапы не настроены.

   В spg99: данные и WAL в S3 через Safekeeper/Pageserver; compute можно выключить или пересоздать, storage остаётся; восстановление — поднять новый compute и подключить его к существующему timeline.

2. Control Plane вместо «зоопарка» ручных настроек

   В классике: набор VM/дисков/сетей/скриптов, нет единого источника истины по tenants, БД, timelines и состояниям.

   В spg99: Control Plane хранит каталог tenants → БД → timeline → state → scale; CP — точка входа через CLI или REST; от CP получают DSN, состояния, операции create/drop/scale/describe.

3. Auto start/stop compute вместо «вечных» инстансов

   В классике: Postgres на VM работает 24/7, даже при отсутствии трафика вы платите за compute.

   В spg99: первое подключение к DSN попадает в Gateway, он через CP поднимает compute если его нет; при idle CP останавливает compute (через ~5 минут простоя) — БД остаётся в STOPPED, данные в S3 и compute перестаёт потреблять ресурсы.

4. Единый Gateway‑endpoint вместо прямых подключений к VM

   В классике: приложение подключается к конкретному host:port; при смене VM надо менять конфиги.

   В spg99: все подключения идут на один Gateway‑адрес (например, provisioner.spg99.ru:5432); маршрутизация, выбор compute и холодный старт скрыты внутри; приложение работает со стабильным DSN и tenant/db без знаний о VM и S3.

5. Платформа vs. одиночный инстанс

   spg99 предполагает многотенантность, унифицированное API и развитие в сторону шаблонов окружений, политик масштабирования, интеграций и SDK. Обычный Postgres на VM — просто инстанс, вокруг которого всё нужно строить самостоятельно.

1.4. Ключевые концепции архитектуры spg99 (в обзоре)

Следующие разделы документации детализируют эти концепции: описывают модель данных (tenants, db, timeline, state, scale), компонентную архитектуру (CP, Provisioner, Agent, Safekeeper, Pageserver, Gateway, S3) и конкретные сценарии использования и API.

Переменные окружения (один раз)

export CP_URL=https://provisioner.spg99.ru
export ACME_TOKEN=<ASK_SPG99_TO_ACCESS>

Создать tenant

spgctl tenant create --name t1
spgctl tenant get --name t1

# REST-эквивалент
curl -sS -X POST "$CP_URL/v2/tenants" \
  -H "Authorization: Bearer $ACME_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"t1"}' | jq .

В ответе придут pg_user, pg_password и dsn_template — сохраните их.

Создать БД без немедленного старта compute

# CLI (start_immediately=false, initial_scale=0)
spgctl db create \
  --tenant t1 \
  --name d1 \
  --size dev-small \
  --start-immediately=false \
  --initial-scale 0

# REST
curl -sS -X POST "$CP_URL/v2/tenants/t1/dbs" \
  -H "Authorization: Bearer $ACME_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"d1","size":"dev-small","start_immediately":false,"initial_scale":0}' | jq .

Запустить compute и проверить состояние

spgctl db start --tenant t1 --db d1 --scale 1
spgctl db describe --tenant t1 --db d1

# REST start + describe
curl -sS -X POST "$CP_URL/v2/tenants/t1/dbs/d1/start" \
  -H "Authorization: Bearer $ACME_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"scale":1}' | jq .

curl -sS -X GET "$CP_URL/v2/tenants/t1/dbs/d1" \
  -H "Authorization: Bearer $ACME_TOKEN" | jq .

Ждите state=ready — это значит, что compute поднят и готов к подключениям.

Остановить или удалить БД

spgctl db stop --tenant t1 --db d1
spgctl db delete --tenant t1 --db d1 --force

# REST
curl -sS -X POST "$CP_URL/v2/tenants/t1/dbs/d1/stop" \
  -H "Authorization: Bearer $ACME_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}' | jq .

curl -sS -X DELETE "$CP_URL/v2/tenants/t1/dbs/d1" \
  -H "Authorization: Bearer $ACME_TOKEN" | jq .

Полезное

• ·spgctl db list --tenant t1 и spgctl db get --id <uuid> отображают те же поля, что и GET /v2/tenants/:t/dbs.
• ·spgctl ping проверяет health CP; --json выводит сырой ответ API.
• ·При сетевом таймауте spgctl db create автоматически делает describe, чтобы показать итоговое состояние.

Tenant

Логическая граница изоляции: свой каталог в Control Plane, свой pg_user/pg_password и DSN-шаблон вида postgres://<pg_user>:<pg_password>@provisioner.spg99.ru:5432/<db-name>?sslmode=require. Внутри tenant — любое количество БД. В CP tenant также мапится на ps_tenant, по которому Pageserver/Safekeeper хранят timeline.

DB

Запись в каталоге CP (v2) с полями id, timeline_id, size, compute_profile, state, target_scale. Создание записи мгновенное: CP подготавливает timeline и креды, а compute запускается только по start/scale или по автозапуску из Gateway.

Timeline

UUID‑идентификатор истории БД. CP создаёт timeline на Pageserver (ensure_timeline_ps) и Safekeeper (ensure_timeline_sk) до запуска compute. Таймлайн хранится как «канонический» в db_store; даже если compute/VM потерялась, новый старт подключается к тому же timeline и видит данные в S3.

Scale и compute-профили

target_scale определяет желаемое количество compute (в демо — 0 или 1). current_scale отражает фактический запуск. Команды start/stop/scale меняют target_scale; Gateway по первому подключению может автозапустить БД до target_scale=1.

Профиль compute задаёт размеры ВМ (cores, RAM, диск, core_fraction). В демо используется профиль yc-dev: 2 vCPU, 4 ГБ RAM, 20 ГБ SSD, core_fraction 100%. Можно выбирать профиль через поле compute_profile при создании БД.

Базовая настройка окружения

export CP_URL=https://provisioner.spg99.ru
export ACME_TOKEN=<ASK_SPG99_TO_ACCESS>
export DSN=<GENERATED_BY_TOKEN>

• •CP_URL — адрес Control Plane. В демо — http://provisioner.spg99.ru.
• •ACME_TOKEN — сервисный токен tenant (запросите у команды spg99). Им подписываются все запросы в заголовке Authorization.
• •DSN — строка подключения PostgreSQL для приложений. Её можно взять из описания БД (см.GET /v2/tenants/:tenant/dbs/:db) или из выдачи токена.

Управление tenants

curl -sS -X POST "$CP_URL/v2/tenants" \
  -H "Authorization: Bearer $ACME_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"t1"}' | jq .

curl -sS -X GET "$CP_URL/v2/tenants" \
  -H "Authorization: Bearer $ACME_TOKEN" | jq .

curl -sS -X DELETE "$CP_URL/v2/tenants/t1" \
  -H "Authorization: Bearer $ACME_TOKEN" | jq .

Жизненный цикл БД внутри tenant

{
  "tenant": "t1",
  "created_at": "2025-12-10T06:57:50Z",
  "db_count": 0,
  "pg_user": "tnt_xxxxxx",
  "pg_password": "<secret>",
  "dsn_template": "postgres://tnt_xxxxxx:<secret>@provisioner.spg99.ru:5432/<db-name>?sslmode=require"
}

{
  "id": "73cd73e2-0d12-4f63-9389-c202ab345b28",
  "tenant": "t1",
  "name": "d1",
  "size": "dev-small",
  "state": "stopped",
  "current_scale": 0,
  "target_scale": 0,
  "active_connections": 0,
  "created_at": "2025-12-10T07:10:01Z",
  "updated_at": "2025-12-10T07:10:01Z"
}

{
  "id": "73cd73e2-0d12-4f63-9389-c202ab345b28",
  "tenant": "t1",
  "name": "d1",
  "size": "dev-small",
  "state": "creating",
  "current_scale": 0,
  "target_scale": 1,
  "active_connections": 0,
  "created_at": "2025-12-10T07:10:01Z",
  "updated_at": "2025-12-10T07:11:07Z"
}

curl -sS -X POST "$CP_URL/v2/tenants/t1/dbs" \
  -H "Authorization: Bearer $ACME_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "d1",
    "size": "dev-small",
    "start_immediately": false
  }' | jq .

curl -sS -X POST "$CP_URL/v2/tenants/t1/dbs/d1/start" \
  -H "Authorization: Bearer $ACME_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"scale":1}' | jq .

curl -sS -X GET "$CP_URL/v2/tenants/t1/dbs/d1" \
  -H "Authorization: Bearer $ACME_TOKEN" | jq .

curl -sS -X POST "$CP_URL/v2/tenants/t1/dbs/d1/stop" \
  -H "Authorization: Bearer $ACME_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}' | jq .

curl -sS -X DELETE "$CP_URL/v2/tenants/t1/dbs/d1" \
  -H "Authorization: Bearer $ACME_TOKEN" | jq .

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

Приложение использует постоянный DSN с Gateway — compute можно запускать/останавливать без смены строки подключения. Шаблон DSN приходит в ответе создания tenant: подставьте имя БД вместо <db-name> и используйте выданные pg_user/pg_password.

postgres://<pg_user>:<pg_password>@provisioner.spg99.ru:5432/<db-name>?sslmode=require

Быстрая проверка подключения и холодного/горячего отклика: time psql "$DSN" -c "select 1". В горячем режиме (state=READY) CP даёт ответ < 0.5 сек, дальше влияет сеть.

Если compute ушёл в stopped из-за простоя, первое подключение через Gateway автоматически запустит ВМ; старт занимает до ~2 минут, после чего запрос получит ответ от БД.

Gateway держит TLS и маршрутизацию, Control Plane поднимает compute по первому подключению и останавливает при простое — для клиента это выглядит как обычный PostgreSQL.

Control Plane

Единый каталог tenants/БД/timeline/state/scale, API v2 и оркестрация жизненного цикла. Хранит записи в catalog_v2 (SQLite), выдаёт DSN/pg_user/pg_password, генерирует register_token для compute, подписывает TLS‑серты для gateway/воркеров, управляет auto start/stop и выдает lease Gateway (чтобы один gateway держал compute). Операции start/stop проходят через Provisioner; CP следит за state, target_scale и idle‑таймерами.

Provisioner

Сервис, который создаёт и останавливает VM под compute (в демо — адаптер к Yandex Cloud). Подбирает профиль ВМ по compute_profile, ставит образ, сеть, SG, прокидывает bootstrap‑параметры (register_token, timeline, addresses Pageserver/Safekeeper, CP). Возвращает worker_id, который CP использует для lease и маршрутизации.

Safekeeper

Принимает WAL от PostgreSQL compute, буферизует и выгружает сегменты в S3. Обеспечивает durable WAL для последующего воспроизведения и репликации; CP гарантирует, что timeline создан на Safekeeper до запуска compute.

Pageserver

Подписывается на WAL из Safekeeper, применяет его и строит page‑слои в S3 для каждого timeline. Отдаёт страницы compute‑ноде при старте и в работе, так что восстановление после остановки — это подключение compute к готовому timeline.

Gateway

Единственный внешней endpoint PostgreSQL/TLS. При первом подключении запрашивает lease у CP; если compute отсутствует или в STOPPED — триггерит start через CP и Provisioner, ждёт готовности и проксирует протокол до backend. Держит TLS, SNI и ограничивает одновременный доступ к ВМ одним gateway.

Agent + PostgreSQL

Агент живёт внутри compute‑ВМ. После bootstrap от CP тянет TLS‑сертификат, кладёт креды БД, стартует системный PostgreSQL (17) и следит за его состоянием: снимает stale postmaster.pid, прогревает конфиг, мониторит лог, перестраивает pg_hba. Через workers/hello регистрируется в CP по register_token и получает bootstrap‑spec (timeline, адреса Pageserver/Safekeeper, backend creds). Экспонирует метрики, умеет корректно останавливать postgres по сигналу stop_db от CP.

S3‑хранилище

Каноничное место хранения WAL и page‑слоёв (тенант/БД/timeline/…). Compute‑ВМ одноразовая: потеря/перезапуск не трогает данные, потому что state БД определяется timeline в S3 + WAL из Safekeeper.

Создание БД

1. Запрос create — CP создаёт запись каталога, генерирует timeline_id, размещает его в Pageserver/Safekeeper, выдаёт register_token, сохраняет target_scale.
2. start_immediately? false → state=stopped, storage готов, compute не поднимается. true → CP помечает state=creating и запускает compute.
3. Bootstrap — если требуется старт, CP зовёт Provisioner; Provisioner создаёт ВМ и передаёт агенту register_token/timeline/адреса. Agent делает workers/hello, получает bootstrap‑spec, стартует PostgreSQL 17 и подключается к Pageserver/Safekeeper.
4. Готовность — CP обновляет state=ready после успешного bootstrap. DSN из describe уже можно отдавать приложению.

Scale 0 ↔ 1 (start/stop)

• ·Start: POST /v2/tenants/:t/dbs/:d/start или spgctl db start. CP ставит state=starting/creating, target_scale=1, запускает Provisioner. Agent проходит bootstrap; при READY state=ready, current_scale=1. Если БД была в STOPPED по idle, то первый клиентский коннект через Gateway также инициирует start (до ~2 минут).
• ·Stop: POST /v2/tenants/:t/dbs/:d/stop или spgctl db stop. CP ставит state=stopping, target_scale=0, отправляет команду агенту остановить PostgreSQL, затем гасит ВМ через Provisioner. Финальное state=stopped, данные в S3.
• ·Проверка: описанием GET /v2/tenants/:t/dbs/:d или spgctl db describe — ждите state=ready для старта и state=stopped для остановки.

Удаление

1. Остановите compute (state=stopped) или вызовите delete с force через spgctl.
2. DELETE /v2/tenants/:t/dbs/:d — CP помечает state=deleting, удаляет запись в каталоге, db_store и инициирует очистку ресурсов в фоне.
3. При каскадном удалении tenant CP обходит все его БД и удаляет их перед удалением tenant.

Восстановление после сбоя compute

1. Если ВМ потерялась/упала, CP при следующем start или первом подключении через Gateway создаёт новую ВМ через Provisioner.
2. Agent снова делает hello, получает bootstrap‑spec с тем же timeline и подключается к Pageserver/Safekeeper.
3. PostgreSQL поднимается на свежей ВМ, подтягивая данные из S3/page‑слоёв; state переходит в ready. Приложения используют тот же DSN.
4. Если предыдущий start завис, CP переведёт state в error; повторный start перезапускает цепочку bootstrap с новым register_token.

Токены и учётные данные

• •API key (Bearer) — непрозрачный токен CP вида spg99_api_key_…, хранится захешированным в catalog_v2 (token_prefix + sha256). Имеет scope (global/account/tenant) и флаги can_create_db/can_scale/can_delete. Передаётся только в заголовке Authorization: Bearer.
• •pg_user / pg_password — креды PostgreSQL для клиента, выдаются в ответе создания tenant и в DSN. Они отделены от API key: один токен для CP, другие — для БД. Практика подтверждённая: API‑ключ не должен попадать в DSN.
• •client_token — опциональный токен БД; если не передать, CP использует SPG99_DEFAULT_DB_TOKEN (по умолчанию yc-demo). Попадает в ответ describe DB и может входить в DSN.
• •register_token — одноразовый токен для compute‑агента; CP выдаёт его при создании/старте БД. Агент использует workers/hello для bootstrap (timeline, адреса PS/SK). Не нужен клиентам.

TLS и разделение секретов

• •Gateway принимает только TLS PostgreSQL, сертификат подписан CP; агент получает сертификат по CSR, CP выдаёт отдельный cert per worker.
• •Креды БД (pg_user/pg_password) шифруются в каталоге CP (pg_secret_key) и передаются клиенту только в ответе создания tenant/describe DB.
• •API key не смешивается с DSN: приложения используют только DSN (pg_user/pg_password), операционные вызовы CP — только Bearer токен.

Ротация и ограничения

• •API key поддерживает expires_at; пользователям выдаются tenant-scoped ключи для изоляции и минимальных прав.
• •client_token можно переопределить при создании БД (поле token), либо использовать дефолтный.
• •register_token короткоживущий и генерируется на каждый новый старт/compute.

Эндпоинты /metrics

• •Control Plane — Prometheus /metrics с метриками: cp_autostart_total, cp_idle_autostop_total, cp_provisioner_http_requests_total{op,code}, cp_describe_latency_seconds, cp_catalog_entries, PKI метрики (cp_pki_sign_total, cp_pki_active_workers), bootstrap/tokens (cp_bootstrap_push_total, cp_tokens_invalid_total).
• •Gateway — /metrics с TLS‑ручками к backend: gw_backend_tls_ok_total, gw_backend_tls_handshake_errors_total. Можно добавить счётчики подключений/lease в будущем.

Что смотреть

• •Latency cold start: время от start / первого подключения до state=ready. Триггерить alert > 120s.
• •Idle auto-stop: рост cp_idle_autostop_total подтверждает экономию; отсутствие — проверка idle‑таймеров.
• •Provisioner ошибки: лейблы cp_provisioner_http_requests_total{op,code}; аномальный рост 5xx — сигнал к проверке YC/ресурсов.
• •PKI/hello: cp_pki_sign_fail_total и cp_tokens_invalid_total — ошибки выдачи сертификатов и регистр‑токенов для агентов.

Примеры алертов/дашбордов

• •Alert: cold start > 120s или доля start→ready > 2 мин > 5% за 15 мин.
• •Alert: ошибки TLS к backend на Gateway (рост gw_backend_tls_handshake_errors_total).
• •Dashboard: cp_autostart_total/id le_autostop_total + describe_latency_seconds для оценки реакции CP и частоты cold start/stop.
• •Dashboard: provisioner_http_requests_total с кодами, чтобы видеть 5xx/4xx.