Operations Guide

Этот документ описывает эксплуатационные процедуры для iobackup в проде.

1) Базовые принципы

• Агент работает локально на узле, где расположен источник данных.
• Секреты никогда не хранятся в job файлах и в metadata store.
• Все чувствительные значения передаются через env переменные.
• Перед релизом изменений выполняется smoke-run на тестовом job.
• API должен быть закрыт Bearer auth (минимум) и, по возможности, network ACL/mTLS.
• Для публичных/общих контуров включайте rate limit middleware.

Для разработки/ревизии документации (перед релизом) используйте:

• make site-docs — пересобрать site/docs/*.html из docs/*.md (требуется pandoc).
• make docs-check — локальные проверки ссылок/версий/таблиц и идемпотентности генерации (см. scripts/docs_check.py).

2) Управление секретами

Рекомендуемый минимальный набор:

• POSTGRES_BACKUP_PASSWORD
• MYSQL_BACKUP_PASSWORD
• S3_ACCESS_KEY
• S3_SECRET_KEY
• IOBACKUP_API_TOKEN (если включен --auth-enabled)
• IOBACKUP_WEBHOOK_TOKEN (если используются webhooks)

Рекомендации:

• храните секреты в systemd environment file / secret manager;
• ограничивайте права доступа к файлам с env;
• не выводите значения секретов в логи и shell history.

3) Ротация ключей S3

Процедура:

1. Создать новый ключ в S3.
2. Обновить env у агента (S3_ACCESS_KEY, S3_SECRET_KEY).
3. Перезапустить агент.
4. Прогнать тестовый backup в отдельный prefix.
5. Убедиться, что upload успешен.
6. Отключить старый ключ.

Проверка после ротации:

iobackupctl --server http://127.0.0.1:8735 --token-env IOBACKUP_API_TOKEN job run filesystem-s3-streaming
iobackupctl --server http://127.0.0.1:8735 --token-env IOBACKUP_API_TOKEN run list

4) Очистка старых данных в S3

Основной механизм — retention policy по manifest metadata.

Дополнительная ручная очистка prefix (если нужно):

aws s3 rm s3://<bucket>/<prefix>/ --recursive --endpoint-url <s3-endpoint> --region <region>

Делайте manual delete только после проверки, что объекты не нужны для restore/аудита.

5) Плановые проверки (ежедневно/еженедельно)

Ежедневно:

• есть ли успешные run за последние 24 часа;
• есть ли failed task;
• есть ли проблемы доставки webhook.

Еженедельно:

• проверка целостности цепочки backup -> manifest -> metadata;
• тест восстановления (минимум выборочно);
• проверка корректности retention.

5.1) Ротация run-логов и метаданных

Для ограничения роста локального хранилища задайте:

• IOBACKUP_RUN_LOGS_RETENTION_DAYS — сколько дней хранить task run-логи в runs-log-dir;
• IOBACKUP_DB_RETENTION_DAYS — сколько дней хранить историю в metadata DB;
• IOBACKUP_RETENTION_CLEANUP_INTERVAL — интервал фоновой очистки (например 6h).

CLI-флаги эквиваленты:

• --run-logs-retention-days
• --db-retention-days
• --retention-cleanup-interval

Значение <=0 для *_RETENTION_DAYS отключает соответствующую очистку.

5.1.1) Per-type metadata retention (0.17-fix.60 foundation)

IOBACKUP_DB_RETENTION_DAYS остаётся как legacy/fallback, но целевая модель — per-type retention:

• metadata_retention.runs_days
• metadata_retention.task_logs_days
• metadata_retention.events_days (reserved)
• metadata_retention.audit_days (reserved)
• metadata_retention.verification_days
• metadata_retention.hook_results_days (reserved)
• metadata_retention.retention_events_days
• metadata_retention.job_revisions_days / metadata_retention.manifests_days: 0 = keep forever (until explicit delete)

См. docs/architecture/metadata.md.

5.1.2) Metadata DB maintenance (0.17-fix.60)

Команды iobackupctl metadata работают только с metadata DB (не скачивают artifacts):

iobackupctl metadata check --db /var/lib/iobackup/agent.db
iobackupctl metadata backup --db /var/lib/iobackup/agent.db --output /var/lib/iobackup/metadata-backups/
iobackupctl metadata export --db /var/lib/iobackup/agent.db --output /var/lib/iobackup/exports/metadata.json

Важно:

• metadata export всегда применяет redaction и учитывает export policy (см. docs/architecture/metadata.md и docs/operator/support-bundle.md).
• metadata compact — offline-only (в 0.17-fix.60 возвращает METADATA_COMPACT_REQUIRES_OFFLINE).

5.2) Лог агента и дублирование task-логов в metadata DB

• IOBACKUP_LOG_LEVEL — уровень лога агента: debug, info, warning, error.
• IOBACKUP_LOG_OUTPUT — куда писать лог агента: stderr (удобно с journalctl), file, both.
• IOBACKUP_TASK_LOG_DUP_DB — дублировать строки per-task логов в bbolt; тогда HTTP-выдача логов задачи может собрать текст из БД, если файла нет или он пуст.

Подробности и значения по умолчанию — в examples/iobackup-agent.env.example и флагах iobackup-agent --help.

6) Мониторинг

Агент экспортирует метрики по endpoint:

curl -sS http://127.0.0.1:8735/metrics

Ключевые метрики:

• iobackup_api_requests_total, iobackup_api_request_duration_seconds
• iobackup_runs_started_total, iobackup_runs_finished_total, iobackup_run_duration_seconds
• iobackup_tasks_started_total, iobackup_tasks_finished_total, iobackup_task_duration_seconds
• iobackup_backup_bytes_total, iobackup_artifacts_created_total
• iobackup_provider_operations_total, iobackup_provider_operation_duration_seconds
• iobackup_notifications_total, iobackup_notification_attempts
• iobackup_artifact_downloads_total, iobackup_artifact_deletes_total

Рекомендуемые алерты:

• рост runs_finished_total{status="failed"} выше базовой нормы;
• рост tasks_finished_total{status="failed"} по конкретному source/destination;
• увеличение latency по api_request_duration_seconds;
• рост notifications_total{status="failed"}.

7) Аварийный регламент

Если backup начал падать:

1. Проверить health API агента (GET /api/v1/health, при необходимости GET /api/v1/ready — 503 если не готов; краткая сводка checks/degraded — см. docs/reference/capabilities.md). Для инвентаря: GET /api/v1/agent/facts (tool discovery) и GET /api/v1/capabilities (feature gates и зарегистрированные провайдеры).
2. Проверить наличие утилит (pg_dump, mysqldump, aws).
3. Проверить env секреты.
4. Проверить доступность destination (S3 endpoint/права на bucket).
5. Проверить последние task errors через CLI/API.

Если падают webhooks:

• backup должен оставаться success/partial_success по фактическому результату задачи;
• анализировать только notification_events, не блокируя backup pipeline.

8) Обновление агента

Рекомендуемый порядок:

1. Сборка новой версии.
2. Тест на staging job.
3. Переключение прод-агента на новую версию.
4. Контрольный run.
5. Проверка artifacts/manifests/notifications.

Рекомендуемый pre-release regression smoke:

bash ./examples/tests/run-full-matrix.sh

Этот прогон проверяет local/ssh/s3 для mysql, postgres, vault, openldap, clickhouse, filesystem.

Зарезервированные сценарии (не для прогона как готовые jobs): каталог examples/future/ — см. examples/future/README.md.

9) Runtime troubleshooting (0.17-fix.80)

9.1 Interrupted recovery

Если агент перезапущен во время run:

• «Зависшие» running / pending run/task переводятся в терминальный interrupted при восстановлении;
• advisory locks в bolt для stale run снимаются;
• уже записанные артефакты могут потребовать ручной проверки (verify / retention);
• статус interrupted терминальный — повторное исполнение оформляется новым run.

9.2 Concurrency locks (CONCURRENCY_LOCKED)

• Проверьте owner_run_id и lock_key в теле ошибки / логах.
• После рестарта агента устаревший lock должен освободиться; если нет — metadata check и инспекция bucket locks (см. docs/architecture/bbolt-storage-layout.md).

9.3 Idempotency replay

Повторный POST …/runs с тем же HTTP Idempotency-Key и тем же job_uid возвращает тот же run_id. Тот же ключ для другого job_uid даёт конфликт IDEMPOTENCY_KEY_CONFLICT.

9.4 Disk pressure

Поведение зависит от политики агента: режим reject_new_runs может вернуть DISK_PRESSURE_LOW_SPACE и не стартовать новые run; режим warn позволяет старт с предупреждением. См. конфиг и docs/reference/error-codes.md.

9.5 Расписание backup metadata DB

Делайте iobackupctl metadata backup (или файловый snapshot) перед обновлением агента, перед storage-миграциями 0.18+, периодически в каталог metadata-backups/. Включайте в резерв и identity/ (agent.identity / docs/architecture/agent-identity.md).

9.6 Потерян sidecar manifest

Если в destination остался только data-файл без sidecar, опирайтесь на запись BackupManifest в bolt и на операционные бэкапы БД; полное восстановление только из object storage может быть невозможно (см. docs/features/retention/retention.md, docs/reference/manifest-schema.md).

9.7 Диагностика через capabilities / facts

• GET /api/v1/capabilities — feature gates, зарегистрированные провайдеры, maturity, кэш provider health.
• GET /api/v1/agent/facts — ОС, timezone, redacted пути, обнаруженные CLI.

Не путать с jobs/validate?deep=1 — там допускаются дорогие проверки подготовки job.