iobackup: подробный человеческий гайд

Этот документ — «человеческое» описание iobackup: что система делает, как она работает в реальной жизни, где ее сильные стороны и как безопасно использовать ее в production.

Если README.md — это технический вход и быстрые команды, то этот гайд — про смысл, сценарии и практику эксплуатации.

1) Что такое iobackup простыми словами

iobackup — это локальный агент резервного копирования с API и CLI.

Вы описываете задачу backup в YAML (job), отправляете ее в агент и запускаете вручную. Агент:

1. читает данные из источника (source);
2. потоково передает их в хранилище (destination);
3. считает checksum;
4. сохраняет manifest;
5. применяет retention-политику;
6. отправляет уведомления и пишет историю выполнения.

Главная идея: streaming-first. Данные идут потоком, без лишних временных файлов, где это возможно.

2) Из каких частей состоит система

• iobackup-agent — основной процесс (daemon + HTTP API), который реально выполняет backup.
• iobackupctl — CLI-клиент для оператора, работает поверх API.
• bbolt (agent.db) — встроенная база метаданных:
  • jobs,
  • runs/tasks,
  • manifests,
  • webhook events,
  • retention audit,
  • verify results / verify runs.

Важно: iobackup хранит в bbolt состояние и историю, а сами backup-артефакты — в destination (local, S3, SSH и т.д.).

3) Foundation-модели: зачем в iobackup столько ID, manifest и snapshots

В iobackup есть не только “запустить backup и получить файл”. Внутри продукт хранит несколько базовых сущностей — foundation-моделей. Они нужны не ради сложности, а чтобы backup-ы можно было потом проверять, восстанавливать, переносить, шифровать, запускать по расписанию и управлять ими с центрального сервера.

Проще говоря: foundation-модели — это скелет продукта.

Agent identity: какой агент сделал backup

Каждый агент имеет стабильную identity:

• agent_id — постоянный ID агента;
• hostname — имя сервера;
• instance_id — ID конкретного запуска процесса агента;
• labels — метки вроде env=prod, role=mysql.

Это нужно, чтобы понимать:

• какой сервер сделал backup;
• какой агент отправил webhook;
• какому агенту в будущем central server назначит задачу.

agent_id живёт долго, а instance_id меняется после restart агента.

job_id и job_uid: имя для человека и ID для системы

В YAML оператор пишет человекочитаемый job_id:

metadata:
  job_id: mysql-prod

Система внутри создаёт неизменяемый job_uid:

job_uid: job_01J...

Разница важна:

• job_id можно переименовать;
• job_uid остаётся прежним и связывает всю историю job-а.

Если job переименовали из mysql-prod в mysql-production, старые backup-ы всё равно относятся к тому же job_uid.

JobRevision: какая версия YAML реально использовалась

Каждое изменение job создаёт новую revision. Run хранит, по какой именно revision он был запущен: YAML может измениться уже после выполнения backup-а, а история должна оставаться точной.

submitted / resolved / executed snapshot

У job есть три состояния:

• submitted — что прислал пользователь;
• resolved — что получилось после defaults, overlay секретов, validation и нормализации;
• executed — что реально использовал конкретный run.

Run хранит executed_job_snapshot. Поэтому даже если job потом изменили, старый run остаётся воспроизводимым и понятным.

Run и TaskRun

Run — это один запуск job-а. TaskRun — выполнение одной task внутри run.

Если job содержит несколько tasks, возможен статус partial_success: например основной backup успешен, а optional task (с required: false) упала.

request_id и correlation_id

Для диагностики у запуска есть:

• request_id — конкретный API/CLI-запрос;
• correlation_id — вся цепочка действий: request → run → task → manifest → webhook.

Это помогает искать связанные логи, webhooks и ошибки.

Idempotency-Key: защита от двойного запуска

Если клиент не понял, дошёл ли запрос на запуск backup-а, он может повторить запрос с тем же Idempotency-Key. Для того же job_uid система вернёт тот же run_id, а не запустит второй backup. Тот же ключ для другого job_uid вернёт IDEMPOTENCY_KEY_CONFLICT.

Concurrency locks: защита от параллельных запусков

Некоторые backup нельзя запускать одновременно (например два тяжёлых dump одной базы). Для этого есть:

spec:
  concurrency:
    policy: forbid
    lock_key: mysql-prod

Если run уже идёт, второй запуск получит CONCURRENCY_LOCKED.

interrupted: если агент умер во время backup

Если агент перезапустился во время run, старые running / pending run помечаются как interrupted. Это значит: run не завершился корректно, artifacts нужно проверять вручную (или через verify), а stale locks будут очищены startup recovery.

BackupManifest: паспорт backup-а

Manifest — это JSON-паспорт backup-а. Он отвечает на вопросы: какой агент и какой job/revision сделали backup, какой run/task создали artifact, где лежит artifact, какой checksum, какая lineage/repository, и как этот backup проверить.

Manifest пишется рядом с data artifact как sidecar. Если agent.db потерян, sidecar manifest помогает понять, что лежит в хранилище.

backup_id, artifact_id и manifest_id

• backup_id — логический результат backup и ключ API;
• manifest_id — идентификатор документа manifest;
• artifact_id — идентификатор конкретного data/manifest artifact внутри artifacts[].

Repository и lineage: подготовка к incremental backup

Сейчас обычный backup — это single_artifact. Future incremental backup должен работать через repository, snapshots, chunks и indexes. Поэтому manifest уже содержит repository и lineage как подготовку к будущим сценариям.

checksums и checks

checksums[] — фактические хэши, а checks — статусы проверок (artifact verify, decrypt/format verify, restore smoke). Часть проверок пока reserved/placeholder, потому что encryption/restore smoke ещё не реализованы.

Redaction и export policy

Секреты не должны попадать в API, webhook, manifest, metadata export или snapshots. Поэтому sensitive fields маскируются, а полные пути/object keys по умолчанию не раскрываются наружу.

Metadata maintenance

Агент хранит историю в agent.db. Для обслуживания есть:

iobackupctl metadata check
iobackupctl metadata backup
iobackupctl metadata export

Перед upgrade и будущими migrations metadata DB нужно бэкапить отдельно. Также важно сохранять identity/agent.identity, чтобы не потерять continuity agent_id.

Capabilities и facts

Агент может рассказать, что он умеет: какие feature gates включены, какие provider-ы доступны, какие tools найдены на хосте, и какой health/readiness. Для этого есть GET /api/v1/capabilities и GET /api/v1/agent/facts.

Что это даёт

Foundation-модели нужны, чтобы текущий локальный backup-agent мог вырасти в полноценную backup-платформу. Важно: не все эти функции уже реализованы, но foundation-модель нужна заранее, чтобы потом не переписывать job YAML, manifest, metadata DB и API.

Подробнее:

• модель данных: data-model.md;
• manifest: manifest-schema.md;
• storage layout: bbolt-storage-layout.md;
• capabilities/facts: capabilities.md;
• metadata maintenance: metadata.md;
• security/redaction: security.md;
• maturity/status: status-matrix.md.

4) Что уже умеет текущая версия

Рабочие provider-ы:

• Source: filesystem, postgres, mysql, clickhouse, openldap, vault (KV export), docker_compose
• Destination: local, s3, ssh
• Policy: retention
• Notification: webhook

Сводная «зрелость» возможностей: status-matrix.md. Модель сущностей в БД: data-model.md.

• Можно делать backup файлов (source: filesystem; подробнее docs/providers/sources/filesystem-source.md);
• Можно делать logical dump PostgreSQL и MySQL;
• Можно складывать артефакты локально, в S3-compatible storage или через SSH;
• Можно чистить старые backup по retention;
• Можно отправлять события во внешний API;
• Можно проверять восстановляемость (verify) вручную и автоматически.

5) Как проходит один backup-run

Упрощенный жизненный цикл:

1. Job submit — YAML проходит валидацию и сохраняется; агент определяет job_uid и создаёт/обновляет JobRevision.
2. Job run — создается run со статусом running, сохраняются request_id/correlation_id и executed_job_snapshot.
3. для каждой task:
   • source создает поток данных;
   • destination принимает поток;
   • checksum считается на лету;
   • создается manifest (и sidecar рядом с data artifact);
   • запускается retention;
4. run получает финальный статус (success, partial_success, failed);
5. отправляются webhook-события;
6. (опционально) запускается auto verify-after-run.

Дополнительно:

• если передан Idempotency-Key, повторный запрос для того же job_uid вернёт существующий run_id;
• если spec.concurrency.policy=forbid, агент берёт lock по lock_key;
• non-critical сбои (например webhook delivery или retention partial failure) фиксируются как warnings (warnings_count / last_warning_code);
• если агент перезапустился во время run, startup recovery пометит незавершённый run как interrupted.

Статусы и история можно смотреть через API/CLI в любой момент.

6) Почему streaming-first — это важно

Потоковый режим дает практические плюсы:

• меньше временного локального диска;
• меньше задержка между чтением и записью;
• меньше риск «заполнили staging и упали»;
• проще масштабировать по размеру данных.

Когда нужны внешние утилиты (pg_dump, mysqldump, aws CLI), их можно запускать либо локально, либо в Docker fallback.

7) Local tools vs Docker fallback

У iobackup есть два режима для tool-based частей:

• runner.mode: local — используем утилиты хоста;
• runner.mode: docker — запускаем утилиты внутри контейнера.

Это особенно полезно когда:

• на сервере нет нужной версии pg_dump/mysqldump/aws;
• нужно стандартизовать окружение через фиксированный image;
• нужен переносимый сценарий между разными хостами.

При этом можно использовать свои образы, а не только дефолтные.

8) Verify: как убедиться, что backup реально читается

run.status=success говорит, что запись прошла успешно, но не гарантирует долгосрочную читаемость.

Для этого есть verify:

• агент читает артефакт из destination;
• пересчитывает checksum и size;
• сравнивает с manifest;
• сохраняет результат проверки.

Есть два режима:

• artifact verify — проверка конкретного backup_id;
• job verify — async-проверка последних успешных backup по job/task.

Также можно включить авто-политику:

spec:
  policies:
    verify:
      after_run: true
      limit_per_task: 1

Тогда после успешного run запускается verify-run автоматически.

9) Retention и hard-delete

Retention в проекте — это не только «убрать запись из metadata», но и удаление физических объектов destination (hard-delete) с audit-событиями.

Практически это значит:

• старые артефакты действительно очищаются из хранилища;
• каждое действие cleanup фиксируется в истории;
• можно расследовать, что удалилось и почему.

10) Безопасность: что включать в production

Минимальный production baseline:

• --auth-enabled (Bearer token);
• TLS (--tls-cert-file, --tls-key-file);
• при необходимости mTLS (--tls-client-ca-file);
• rate limit (--rate-limit-enabled, --rate-limit-rps, --rate-limit-burst);
• secrets: на агенте через *_env, файл *_path или KV ref *_vault (конфиг Vault у iobackup-agent: -vault-addr, токен и т.д.); не кладите значения секретов в Git-friendly YAML основного job — при необходимости локальный overlay -job-secrets-file.

Подробнее и с готовыми профилями: docs/features/encryption/security.md.

11) Наблюдаемость и мониторинг

У агента есть:

• structured logs;
• API для истории runs/tasks/artifacts/notifications/verifications;
• Prometheus /metrics.

Что особенно полезно в эксплуатации:

• run/task статусные метрики;
• bytes/throughput по backup;
• webhook retry/fail;
• verify-метрики;
• retention cleanup метрики.

Для авто-verify есть отдельная метрика:

• iobackup_verify_after_run_total{status}

Подробнее: docs/features/observability/prometheus.md.

12) Типичные сценарии использования

• Операторский backup файлов на локальный диск или S3;
• DB backup PostgreSQL/MySQL с единым API и историей;
• S3-compatible storage (не только AWS) через endpoint/region и env;
• Контроль восстановляемости через регулярный verify;
• Интеграция в DevOps/CI через API + webhook + metrics.

13) Что важно помнить

• В текущей версии нет встроенного scheduler: запуск вручную через API/CLI.
• Источник истины по состоянию — API/metadata store, а не только логи.
• Успешный backup лучше дополнять verify-проверками.
• Для production лучше сразу включать auth + TLS + rate limit.
• job_id можно переименовать, но история связывается через job_uid.
• Manifest sidecar так же важен, как data artifact: он нужен для manual DR и будущего metadata rebuild.
• success не равно “проверено восстановление”: для этого нужен verify, а restore smoke пока future.
• interrupted — terminal status; такой backup нужно проверять вручную.

14) Куда идти дальше по документации

• Быстрый тех-вход: README.md
• Формат job: docs/reference/job-format-v1.md
• Практический запуск: docs/operator/runbook.md
• API/CLI примеры: docs/reference/curl-and-ctl.md
• Verify-пайплайн: docs/features/verification/verify.md
• Метрики/алерты: docs/features/observability/prometheus.md
• Security профили: docs/features/encryption/security.md
• Foundation model: data-model.md
• Manifest schema: manifest-schema.md
• Capabilities/facts: capabilities.md
• Metadata maintenance: metadata.md
• Status matrix: status-matrix.md
• Manual DR: manual-dr.md