Формат job v1

Актуально для v0.53.0 (pre-GA single-agent). Поля spec.schedules, runtime_hooks, backup.encryption и др. зависят от feature gates агента (docs/reference/feature-gates.md, docs/reference/experimental-features.md). Матрица зрелости провайдеров и подсистем: docs/reference/feature-status-matrix.md. Этот документ не описывает production restore/orchestration и не задаёт контракт центрального control plane.

Поддерживаемая схема

api_version: iobackup.io/v1
kind: BackupJob

В v1 исполняется только BackupJob.

Зарезервированные kind для будущих версий

• RestoreJob
• MigrateJob
• Policy
• StorageProfile
• SourceProfile
• SecretProfile

Структура

Корневые блоки:

• api_version — строка API; для v1 только iobackup.io/v1.
• kind — строка; для исполнимого задания — BackupJob.
• metadata — идентификация и подпись job для людей (job_id, name, описание и метки).
• spec — всё, что нужно оркестратору: операция, задачи, политики, уведомления, значения по умолчанию.

Внутри spec:

• enabled
• operation
• logging
• data
• execution
• artifact
• policies
• defaults
• notifications
• tasks

Детально по каждому полю, с уровнями вложенности и перекрёстными ссылками — в разделе «Справочник полей YAML».

Карта источников (source.type)

Примеры и поля конфигурации описаны ниже по типам и в тематических страницах сайта:

Для postgres и mysql также см. общий паттерн Docker/runner для утилит.

Карта назначений (destination.type)

Конфиг всегда в destination.config:

Политики, уведомления, поток данных

• Retention: retention, verify после run: verify, поле spec.policies.verify — ниже.
• Webhooks: webhooks и spec.notifications / task.notifications в справочнике.
• Модель потока и staging: streaming.
• Список имён провайдеров и stub-ы: providers.

Справочник полей YAML

Ниже — «человеческое» описание дерева задания. Необязательные поля помечены как опциональные; часть значений подставляется по умолчанию (см. важные defaults). Точное соответствие структуре — пакет internal/job/model.go.

Корень документа

metadata

Tenant / namespace / project / environment (0.17-fix.80): отдельных полей metadata.namespace в Go-модели пока нет — используйте соглашение по labels (например tenant, project, environment или префикс iobackup.io/*), пока в 0.18+ не появятся first-class поля.

System-managed identity and revisions (0.17-fix.20)

Начиная с 0.17-fix.20 агент хранит отдельную immutable историю версий job (revisions) и использует system-managed identity.

В обычном YAML (job submit/apply, без специальных флагов импорта) нельзя задавать system-managed поля — агент выставляет их сам. Валидация (job.Validate) отклоняет submit, если задано любое из:

• metadata.job_uid
• metadata.revision (не ноль)
• metadata.previous_job_ids (непустой список)
• metadata.created_at, metadata.updated_at, metadata.renamed_at (любое ненулевое время)

Код ошибки: JOB_UID_NOT_ALLOWED_IN_NORMAL_SUBMIT (сообщение агрегирует эти поля).

Не используйте в ручном YAML (агент перезапишет или это приведёт к рассинхрону с API): metadata.latest_job_revision_id, metadata.submitted_hash, metadata.resolved_hash, metadata.matched_previous_job_id, metadata.deleted_at, metadata.delete_reason — они появляются в ответах API и в JSON в bolt.

metadata.job_id — стабильный пользовательский slug (primary key «по id» в API); при rename меняется, цепочка прежних id — в previous_job_ids на стороне агента.

metadata.job_uid — неизменяемый идентификатор цепочки job; сохраняется при rename.

Для просмотра истории версий используйте API/CLI:

• GET /api/v1/jobs/{id}/revisions
• GET /api/v1/job-revisions/{job_revision_id}

Каждый Run сохраняет executed_job_snapshot (sanitized) и executed_job_hash для воспроизводимости.

spec

spec.operation

spec.repository (опционально, 0.17-fix.40)

Логический блок репозитория (type, engine, repository_id, snapshot_id, parent_snapshot_id, external_ref, chunking). Исполняется связка по умолчанию type: single_artifact + engine: iobackup. Значения вроде external_engine / content_addressed зарезервированы: при попытке исполнить неподдерживаемую комбинацию валидация вернёт стабильный код (см. Go job.Validate / preflight).

spec.requires (reserved)

Поле spec.requires в YAML может встречаться в черновиках спецификации; в текущей Go-модели (internal/job/model.go) нет соответствующего поля — ключ игнорируется при decode или остаётся только в сыром YAML вне runtime. Semantics появятся в будущих версиях.

spec.logging (опционально, 0.17-fix.50)

spec:
  logging:
    include_source_paths: false
    path_redaction: basename # full | basename | hash | none

Defaults: include_source_paths=false, path_redaction=basename.

spec.data (опционально, 0.17-fix.50)

spec:
  data:
    classification: internal # public | internal | confidential | restricted
    contains_pii: false
    residency:
    log_sensitivity: normal # normal | high

Это signal-поля для будущего enforcement (export/support bundle / encryption / approvals).

Agent ExportPolicy.IncludePaths и HTTP API артефактов (не поля BackupJob YAML)

Поле ExportPolicy.IncludePaths относится к конфигурации процесса iobackup-agent, а не к документу BackupJob. В коде это agent.Config.ExportPolicy (internal/agent/config.go, значения по умолчанию — internal/agent.DefaultConfig). Отдельного поля в YAML job для этого нет.

Семантика для публичных ответов HTTP, которые сериализуют storage.BackupManifest в JSON:

Не затрагивается этим переключателем: запись манифеста в metadata DB, POST …/verify, GET …/download, DELETE … — там по-прежнему используются полные пути из хранилища, иначе невозможно прочитать объект у destination.

Отдельно: iobackupctl metadata export задаёт политику путей своими флагами (--include-paths и т.д.); это не то же самое, что ExportPolicy.IncludePaths, хотя смысл «показывать пути или нет» схож.

См. также docs/internal/roadmap/status-matrix.md (раздел Known gaps / Deferred) и docs/internal/roadmap/roadmap.md (блок про hardening 40/50/60).

spec.execution (опционально)

spec.concurrency (опционально, 0.17-fix.30)

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

Поддержка:

• policy=allow|forbid — accepted.
• policy=queue — возвращает machine-readable CONCURRENCY_QUEUE_UNSUPPORTED до появления scheduler.
• max_parallel_tasks>1 — возвращает MAX_PARALLEL_TASKS_UNSUPPORTED до реализации parallel task execution.

spec.artifact (опционально)

spec.policies (опционально)

spec.defaults (опционально)

Если в task не указаны backup, destination или policies, агент может подставить значения отсюда:

spec.notifications (опционально)

spec.notifications.webhooks[].payload (0.17-fix.50)

Итоговый HTTP body собирается агентом как DTO + опциональные включения из policy, затем redact.RedactAny.

spec.notifications.webhooks[].policy (0.17-fix.50)

policy:
  include_job_snapshot: false
  include_manifest: false
  include_labels: true
  include_paths: false

Payload всегда проходит redaction layer; включение paths управляет только тем, допускаются ли они в payload (и в каком виде).

Элемент spec.tasks[]

Каждая задача описывает один проход «источник → упаковка/чексы → назначение» (и опционально свои политики и уведомления).

task.backup (опционально)

depends_on (reserved)

Поле depends_on для DAG задач в текущей модели не реализовано — не полагайтесь на порядок, отличный от порядка элементов в tasks[] и spec.execution.mode.

source и destination (endpoint)

Оба устроены одинаково:

type: <строка из registry>
config: { ... }   # произвольная структура под выбранный type
# только task.destination (опционально):
write_policy:
  on_conflict: fail   # fail | overwrite | create_new (дефолт: fail)

Для destination блок write_policy задаёт поведение при конфликте ключа/пути для объектов, которыми владеет iobackup: fail (по умолчанию), overwrite, create_new. В манифесте рядом с артефактом может дублироваться семантика в destination.write_policy как JSON-объект (см. docs/reference/manifest-schema.md).

Конкретные ключи config — в разделах по типам и на страницах источников / назначений.

Зарезервировано / не исполняется в v1 (0.17-fix.80)

Важные defaults

• spec.artifact.mode = auto
• spec.artifact.staging.enabled = false

Итог: по умолчанию система пытается работать строго потоково, без полного временного локального artifact-файла.

Рекомендации по секретам

Учётные данные не храните в открытом виде в job, который кладёте в Git или передаёте через незащищённые каналы. Используйте один из механизмов из раздела «Учётные данные»:

• ..._env — переменная окружения процесса iobackup-agent на узле;
• ..._path — файл только на узле агента (см. права POSIX);
• ..._vault — ссылка на поле в Vault KV v2 (клиент Vault настраивается на агенте);
• локальный overlay — отдельный YAML на диске агента, сливаемый с job до валидации.

Детали, список полей по провайдерам и примеры — ниже в том же разделе.

S3-compatible: endpoint и region

Для destination.type: s3 endpoint и region задаются по тем же правилам, что и ключи: ровно один источник на каждую семантику — литерал (endpoint / region) или endpoint_env | endpoint_path | endpoint_vault или region_env | region_path | region_vault. См. Учётные данные и s3-destination.

Пример только с env:

destination:
  type: s3
  config:
    endpoint_env: S3_ENDPOINT
    region_env: S3_REGION
    bucket: iobackup
    access_key_env: S3_ACCESS_KEY
    secret_key_env: S3_SECRET_KEY

Полный обзор S3: s3-destination.

Docker fallback для tool-based provider-ов

Для postgres/mysql source и s3 destination можно явно задать runner в docker-контейнере (runner.mode: docker). Автоматического fallback с хоста в контейнер нет: при runner.mode: local используется бинарник с PATH, при ошибке нужно либо установить утилиту, либо переключить YAML на docker.

Пример (PostgreSQL):

tasks:
  - source:
      type: postgres
      config:
        dump:
          tool: pg_dump
          runner:
            mode: docker
            docker:
              image: postgres:16-alpine
              network: host
              extra_args: []
    destination:
      type: s3
      config:
        upload:
          runner:
            mode: docker
            docker:
              image: amazon/aws-cli:latest
              # или оставьте пустым, тогда используется default: amazon/aws-cli:latest
              extra_args: []

Аналогично для MySQL (mysqldump в образе клиента):

tasks:
  - source:
      type: mysql
      config:
        host: 127.0.0.1
        username: backup
        password_env: MYSQL_BACKUP_PASSWORD
        databases:
          - app
        dump:
          tool: mysqldump
          runner:
            mode: docker
            docker:
              image: mysql:8.0
              network: host
              extra_args: []
    destination:
      type: s3
      config:
        upload:
          runner:
            mode: docker
            docker:
              image: amazon/aws-cli:latest

Режим runner.mode: docker явно задаёт выполнение через контейнер (автоматического переключения с local на docker при отсутствии бинарника нет). В режиме local используется утилита с хоста; если её нет в PATH, run завершится ошибкой — тогда задайте docker или установите клиент на хост.

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

• runner.mode: local (по умолчанию)
• runner.mode: docker

Filesystem source (каталоги на хосте агента)

source.type: filesystem упаковывает один или несколько путей в один поток filesystem_backup.tar.gz (gzip+tar):

source:
  type: filesystem
  config:
    paths:
      - /var/lib/app
    include_hidden: false
    exclude:
      - "*.tmp"

Полная спецификация полей, exclude/скрытые файлы/symlinks и pre-flight: filesystem-source.

Учётные данные (*_env, *_path, *_vault)

Общие правила

Для каждого логического параметра (один пароль, один ключ API, один токен и т.д.) в YAML допускается ровно один способ доставить значение:

Взаимоисключение: нельзя задать одновременно, например, password_env и password_vault или password_path и password_env для одной и той же роли пароля — валидация / резолвер вернут ошибку (use exactly one of *_env, *_path, or *_vault).

Plaintext в job: технически некоторые поля можно указать литералами (endpoint, region, иногда пароль в типах, где модель это допускает) — это по-прежнему плохая практика для секретов; preflight там, где включено, может предупреждать об открытых ключах. Для ключей и паролей предпочтительны триада или overlay.

Vault на агенте (для всех полей *_vault)

Клиент KV v2 создаётся в процессе агента. Задаётся один набор параметров подключения (адрес обязателен, если вы используете любой *_vault):

• Адрес API: -vault-addr или IOBACKUP_VAULT_ADDR.
• Токен клиента Vault: по приоритету — -vault-token / IOBACKUP_VAULT_TOKEN, иначе -vault-token-file / IOBACKUP_VAULT_TOKEN_FILE, иначе переменная из -vault-token-env / IOBACKUP_VAULT_TOKEN_ENV (по умолчанию имеет смысл VAULT_TOKEN). Это не YAML-поля job, а конфиг узла агента.
• TLS: -vault-ca-cert / IOBACKUP_VAULT_CA_CERT; при необходимости только для разработки — -vault-tls-skip-verify / IOBACKUP_VAULT_TLS_SKIP_VERIFY.
• Таймаут HTTP: -vault-timeout / IOBACKUP_VAULT_TIMEOUT.

Ссылка в job — объект VaultKVRef (в YAML под ключом password_vault, secret_key_vault и т.д.):

password_vault:
  mount: secret       # необязательно; по умолчанию KV mount `secret`
  path: myapp/pg      # logical path внутри движка (без префикса `data/` в YAML)
  field: password     # ключ в данных секрета после чтения KV v2 (строка или нестроковое значение будет приведено к строке)

Разбор значения из Vault: выполняется KVv2(mount).Get(ctx, path); из ответа берётся поле field. Пустая строка в поле — ошибка; если поля нет в данных — ошибка.

Важно — два разных Vault в продукте:

1. «Vault как клиент учётных данных» — адрес/token из конфига iobackup-agent. Все password_vault, access_key_vault, token_vault при обычном использовании читаются с этого кластера/адреса.
2. source.type: vault — поле config.address задаёт Vault, из которого делается бэкап KV. Токен к этому адресу — всё так же один из token_env | token_path | token_vault; при token_vault значение токена подтягивается через клиент Vault агента (п. 1 выше). То есть KV ref для пароля Postgres и KV ref для токена в vault-source используют одну и ту же точку конфигурации клиента на агенте, если вы не запускаете отдельные агенты с разными -vault-addr.

Локальный overlay (-job-secrets-file, IOBACKUP_JOB_SECRETS_FILE)

Путь задаётся только на агенте (флаг или env). При submit и при validate агент:

1. Декодирует тело запроса (YAML/JSON) в BackupJob.
2. Если файл overlay задан и прочитан — сливает его в уже разобранный job до Validate / ValidateStrict / записи в store (submit).

Поведение merge (упрощённо):

• В корне документа ключи из overlay накладываются на ключи базового job: для карт действует рекурсивное слияние (значения из patch дописывают/перекрывают вложенные map); скаляр в patch заменяет значение в base.
• Ветка spec обрабатывается отдельно: массив spec.tasks сопоставляется по task_id. Для задачи с тем же task_id объект задачи в overlay поверхностно копируется с базовой задачей, затем ключи из overlay задачи мержатся тем же правилом (вложенные config сливаются, а не затираются целиком). Задачи из overlay, которых не было в base, добавляются в конец списка.

Типичный шаблон: в репозитории — job без секретов; на сервере — файл /etc/iobackup/job-secrets.local.yaml только с нужными фрагментами spec.tasks[].source.config.password_path или password_vault и т.д.

Карта полей по провайдерам

Ниже — поля с суффиксами _env / _path / _vault (семантика везде «ровно один из трёх» там, где строка помечена как обязательная в спецификации провайдера).

Подробнее по S3 см. s3-destination; по vault source — vault-source; webhook auth — webhooks.

Source: PostgreSQL (postgres)

Логический дамп через pg_dump (на хосте или в Docker по dump.runner).

Обязательные поля config: host, username, ровно один из (password_env | password_path | password_vault), непустой список databases.

Пример: postgres.local.yaml · YAML. Перекрёстно: Docker/runner, local destination, s3 destination.

Source: MySQL (mysql)

Логический дамп через mysqldump (на хосте или в Docker).

Обязательные поля config: host, username, один из (password_env | password_path | password_vault), непустой список databases.

Пример: mysql.local.yaml · YAML. Перекрёстно: Docker/runner, назначения — local, s3.

Vault source (KV export)

source.type: vault поддерживает выгрузку секретов из Vault KV (v1/v2):

source:
  type: vault
  config:
    address: http://127.0.0.1:18200
    token_env: VAULT_TOKEN
    mount: iobackup
    kv_version: 2
    include_paths:
      - ""
    timeout: 30s

Минимально обязательные поля:

• address
• ровно один из token_env, token_path, token_vault

Подробнее: vault-source.

OpenLDAP source (directory snapshot)

source.type: openldap поддерживает snapshot LDAP directory в JSON:

source:
  type: openldap
  config:
    host: 127.0.0.1
    port: 18389
    bind_dn: cn=admin,dc=example,dc=org
    password_env: OPENLDAP_ADMIN_PASSWORD
    base_dn: dc=example,dc=org
    scope: sub
    filter: (objectClass=*)

Минимально обязательные поля:

• host
• base_dn

Подробнее: openldap-source.

ClickHouse source (HTTP snapshot)

source.type: clickhouse поддерживает snapshot таблиц в JSONL:

source:
  type: clickhouse
  config:
    host: 127.0.0.1
    port: 18123
    username: default
    databases:
      - iobackup

Минимально обязательные поля:

• host
• databases

Подробнее: clickhouse-source.

Docker Compose source (project snapshot)

source.type: docker_compose поддерживает snapshot compose-проекта:

source:
  type: docker_compose
  config:
    project_dir: /path/to/compose-project
    compose_files:
      - docker-compose.yml
    include_paths:
      - .env
    snapshot_volumes: true

Минимально обязательные поля:

• project_dir

Подробнее: docker-compose-source.

Auto verify после run

Можно включить автоматический verify после каждого успешного backup-run:

spec:
  policies:
    verify:
      after_run: true
      # опционально, сколько последних successful-артефактов
      # проверять по каждой task (по умолчанию 1)
      limit_per_task: 1

Поддерживаемые уровни:

• spec.policies.verify (рекомендуется, job-level);
• spec.defaults.policies.verify (fallback);
• task.policies.verify (fallback, если не задано на уровне spec).

Детали: verify.