Запуск задач: `curl` и `iobackupctl`

Этот документ показывает два равноправных способа запуска backup-задач:

через HTTP API (curl);
через CLI (iobackupctl).

Оба варианта обращаются к одному и тому же iobackup-agent.

1) Что должно быть запущено заранее

Агент доступен по http://127.0.0.1:8735.
Способ доставки секретов в задачу совпадает с полями YAML: переменные окружения процесса агента (*_env), файлы на узле (*_path), либо KV v2 refs (*_vault) через настроенный на агенте Vault (IOBACKUP_VAULT_ADDR и токен). Опционально: локальный overlay IOBACKUP_JOB_SECRETS_FILE / -job-secrets-file сливается с job до валидации.
Установлены нужные утилиты (pg_dump, mysqldump, aws CLI) для runner.mode: local, либо доступен docker для runner.mode: docker.
Если включен --auth-enabled, задан IOBACKUP_API_TOKEN.

OpenAPI

Runtime: агент отдаёт спецификацию на GET /api/openapi.json (тот же маршрут, что и у встроенного embed).
Репозиторий: исходник генерируется скриптом python3 scripts/gen-openapi.py → internal/api/openapi.json (коммитится в git). Повторный запуск должен быть идемпотентен, если router не менялся.
После правок API сначала прогоните генератор, затем пересоберите агент, чтобы embed и файл не расходились.

Проверка health:

curl -sS http://127.0.0.1:8735/api/v1/health

Проверка metadata DB health (0.17-fix.60):

curl -sS http://127.0.0.1:8735/api/v1/metadata/health

Пример ответа health (укорочено; с 0.17-fix.70 — live, ready, checks, degraded_reasons):

{
  "status": "ok",
  "live": true,
  "ready": true,
  "agent": {
    "id": "agent_01J...",
    "name": "Local Agent",
    "instance_id": "inst_01J...",
    "hostname": "host1",
    "mode": "standalone",
    "labels": {
      "env": "dev"
    }
  },
  "version": {
    "version": "0.17-fix.70",
    "commit": "abc1234",
    "build_date": "2026-05-11T12:00:00Z"
  },
  "time": "2026-05-11T12:00:00Z",
  "checks": {
    "db": { "status": "ok" },
    "metadata": { "status": "ok" }
  },
  "degraded_reasons": []
}

Минимальные пробы:

curl -sS http://127.0.0.1:8735/api/v1/live
curl -sS http://127.0.0.1:8735/api/v1/ready

Инвентарь агента (read-only, без deep network probe):

curl -sS http://127.0.0.1:8735/api/v1/capabilities
curl -sS http://127.0.0.1:8735/api/v1/agent/facts
curl -sS http://127.0.0.1:8735/api/v1/providers/health

То же через CLI (с вашими --server, --token-env и т.д.):

iobackupctl --server http://127.0.0.1:8735 health
iobackupctl --server http://127.0.0.1:8735 agent capabilities
iobackupctl --server http://127.0.0.1:8735 agent facts
iobackupctl --server http://127.0.0.1:8735 providers list --kind source

Полное описание полей: docs/reference/capabilities.md.

Зарезервированные сценарии (ожидаемо падают на job validate): см. examples/future/README.md.

Проверка идентичности агента (полезно для инвентаризации и дебага):

curl -sS http://127.0.0.1:8735/api/v1/agent

Пример ответа (структура укорочена):

{
  "agent": {
    "id": "agent_01J...",
    "name": "Local Agent",
    "instance_id": "inst_01J...",
    "hostname": "host1",
    "mode": "standalone",
    "labels": {
      "env": "dev",
      "role": "demo"
    }
  },
  "version": {
    "version": "0.17-fix.70",
    "commit": "abc1234",
    "build_date": "2026-05-11T12:00:00Z"
  },
  "time": "2026-05-11T12:00:00Z",
  "management": {
    "mode": "local",
    "managed_by": "local",
    "origin": "local-agent",
    "server_id": null
  },
  "sync": {
    "version": 1,
    "dirty": true,
    "last_synced_at": null,
    "sync_cursor": null
  }
}

Важно:

id (в JSON поле id) — стабильный (persisted) идентификатор агента; если он не задан явно, он создаётся и сохраняется в каталоге IOBACKUP_IDENTITY_DIR.
instance_id — идентификатор конкретного запуска процесса (меняется при каждом рестарте).
labels — передаются только после безопасной нормализации (подозрительные ключи отфильтровываются).

Проверка версии (вместе с agent):

curl -sS http://127.0.0.1:8735/api/v1/version

Пример ответа version (укорочено; agent присутствует и здесь):

{
  "time": "2026-05-11T12:00:00Z",
  "agent": {
    "id": "agent_01J...",
    "name": "Local Agent",
    "instance_id": "inst_01J...",
    "hostname": "host1",
    "mode": "standalone",
    "labels": {
      "env": "dev"
    }
  },
  "version": {
    "version": "0.17-fix.70",
    "commit": "abc1234",
    "build_date": "2026-05-11T12:00:00Z"
  },
  "management": {
    "mode": "local",
    "managed_by": "local",
    "origin": "local-agent",
    "server_id": null
  },
  "sync": {
    "version": 1,
    "dirty": true,
    "last_synced_at": null,
    "sync_cursor": null
  }
}

2) Сценарий через `curl` (API)

2.0 Проверить job без сохранения (pre-flight)

Статическая проверка и опционально сетевые probe (доступность БД, S3, SSH и т.д.):

curl -sS -X POST "http://127.0.0.1:8735/api/v1/jobs/validate?deep=1" \
  -H "Authorization: Bearer $IOBACKUP_API_TOKEN" \
  -H "Content-Type: application/x-yaml" \
  --data-binary @path/to/job.yaml

Без probe (только схема + Validate провайдеров): опустите query-параметр deep или задайте deep=0.

2.1 Отправить job

curl -sS -X POST "http://127.0.0.1:8735/api/v1/jobs" \
  -H "Authorization: Bearer $IOBACKUP_API_TOKEN" \
  -H "Content-Type: application/x-yaml" \
  --data-binary @- <<'EOF'
api_version: iobackup.io/v1
kind: BackupJob
metadata:
  job_id: curl-fs-s3-demo
  name: Curl demo filesystem to s3
spec:
  enabled: true
  operation:
    type: backup
    strategy: full
  repository:
    type: single_artifact
    engine: iobackup
  artifact:
    mode: stream
    staging:
      enabled: false
  tasks:
    - task_id: fs-demo
      source:
        type: filesystem
        config:
          paths:
            - /add/tmp/max-docker
          include_hidden: true
          follow_symlinks: false
      backup:
        format: tar.gz
        compression: gzip
        checksum: sha256
      destination:
        type: s3
        config:
          endpoint: https://s3.twcstorage.ru
          region: ru-1
          bucket: iobackup
          prefix: iobackup-tests/curl-demo
          access_key_env: S3_ACCESS_KEY
          secret_key_env: S3_SECRET_KEY
          force_path_style: true
        write_policy:
          on_conflict: fail
EOF

2.2 Запустить job

curl -sS -X POST "http://127.0.0.1:8735/api/v1/jobs/curl-fs-s3-demo/run" \
  -H "Authorization: Bearer $IOBACKUP_API_TOKEN"

Ответ вернет run_id.

2.3 Проверить выполнение

curl -sS -H "Authorization: Bearer $IOBACKUP_API_TOKEN" "http://127.0.0.1:8735/api/v1/runs/<run_id>"
curl -sS -H "Authorization: Bearer $IOBACKUP_API_TOKEN" "http://127.0.0.1:8735/api/v1/runs/<run_id>/tasks"
curl -sS -H "Authorization: Bearer $IOBACKUP_API_TOKEN" "http://127.0.0.1:8735/api/v1/runs/<run_id>/tasks/<task_id>/logs"
curl -sS -H "Authorization: Bearer $IOBACKUP_API_TOKEN" "http://127.0.0.1:8735/api/v1/artifacts"
curl -sS -X POST -H "Authorization: Bearer $IOBACKUP_API_TOKEN" "http://127.0.0.1:8735/api/v1/jobs/curl-fs-s3-demo/verify?limit_per_task=1"
curl -sS -X POST -H "Authorization: Bearer $IOBACKUP_API_TOKEN" "http://127.0.0.1:8735/api/v1/artifacts/<backup_id>/verify"
curl -sS -H "Authorization: Bearer $IOBACKUP_API_TOKEN" "http://127.0.0.1:8735/api/v1/verifications"
curl -sS -H "Authorization: Bearer $IOBACKUP_API_TOKEN" "http://127.0.0.1:8735/api/v1/job-verifications"

3) Сценарий через `iobackupctl` (CLI)

3.0 Проверить job (pre-flight)

go run ./cmd/iobackupctl --server http://127.0.0.1:8735 --token-env IOBACKUP_API_TOKEN job validate ./examples/filesystem.s3.streaming.yaml
go run ./cmd/iobackupctl --server http://127.0.0.1:8735 --token-env IOBACKUP_API_TOKEN job validate --file ./examples/filesystem.s3.streaming.yaml --deep

Путь к YAML можно передать позиционным аргументом или флагом --file / -f (job validate, job submit, job apply, job import).

3.1 Отправить job

go run ./cmd/iobackupctl --server http://127.0.0.1:8735 --token-env IOBACKUP_API_TOKEN job submit ./examples/filesystem.s3.streaming.yaml

3.1.1 Apply (create/update по `job_id`) и безопасная проверка `job_uid`

job apply — то же, что submit, но с опциональной проверкой: если вы ожидаете, что обновляете тот же job, укажите --expected-job-uid.

go run ./cmd/iobackupctl --server http://127.0.0.1:8735 --token-env IOBACKUP_API_TOKEN \
  job apply ./examples/filesystem.s3.streaming.yaml --expected-job-uid job_01J...

3.1.2 Rename (сохранить историю через `job_uid`)

Обычная смена metadata.job_id в YAML создаёт новый job (и новый job_uid). Чтобы переименовать job_id и сохранить историю, используйте rename:

go run ./cmd/iobackupctl --server http://127.0.0.1:8735 --token-env IOBACKUP_API_TOKEN \
  job rename filesystem-s3-streaming filesystem-s3-streaming-prod

3.1.3 Import (admin/import режим, восстановление metadata)

Импорт нужен для восстановления metadata или переноса истории. В обычном submit/apply job_uid в YAML запрещён, но job import --preserve-uid разрешает его и сохраняет:

go run ./cmd/iobackupctl --server http://127.0.0.1:8735 --token-env IOBACKUP_API_TOKEN \
  job import ./job.yaml --preserve-uid

3.2 Запустить job

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

С idempotency key (пока сохраняется в Run; дедупликация может быть добавлена позже):

go run ./cmd/iobackupctl --server http://127.0.0.1:8735 --token-env IOBACKUP_API_TOKEN \
  job run filesystem-s3-streaming --idempotency-key demo-001

Revisions (история версий job, snapshots/hashes):

go run ./cmd/iobackupctl --server http://127.0.0.1:8735 --token-env IOBACKUP_API_TOKEN job revisions filesystem-s3-streaming
go run ./cmd/iobackupctl --server http://127.0.0.1:8735 --token-env IOBACKUP_API_TOKEN job revision-show jrev_01J...

3.3 Проверить выполнение

go run ./cmd/iobackupctl --server http://127.0.0.1:8735 --token-env IOBACKUP_API_TOKEN run list
go run ./cmd/iobackupctl --server http://127.0.0.1:8735 --token-env IOBACKUP_API_TOKEN task list <run_id>
go run ./cmd/iobackupctl --server http://127.0.0.1:8735 --token-env IOBACKUP_API_TOKEN artifact list
go run ./cmd/iobackupctl --server http://127.0.0.1:8735 --token-env IOBACKUP_API_TOKEN job verify curl-fs-s3-demo --limit-per-task 1
go run ./cmd/iobackupctl --server http://127.0.0.1:8735 --token-env IOBACKUP_API_TOKEN artifact manifest <backup_id>
go run ./cmd/iobackupctl --server http://127.0.0.1:8735 --token-env IOBACKUP_API_TOKEN artifact verify <backup_id>
go run ./cmd/iobackupctl --server http://127.0.0.1:8735 --token-env IOBACKUP_API_TOKEN verification list
go run ./cmd/iobackupctl --server http://127.0.0.1:8735 --token-env IOBACKUP_API_TOKEN verify-run list
go run ./cmd/iobackupctl --server http://127.0.0.1:8735 --token-env IOBACKUP_API_TOKEN notification list

Примечание по task logs:

endpoint /runs/<run_id>/tasks/<task_id>/logs читает файл из runs-log-dir;
если включена ротация (--run-logs-retention-days), для старых run можно получить 404 (лог уже очищен).

4) Что выбрать: API или CLI

curl/API удобно для CI/CD, automation, интеграции с оркестраторами.
iobackupctl удобно для ручной операционной работы и диагностики.

С точки зрения агента результат одинаковый: и API, и CLI вызывают одну и ту же backend-логику.

5) Как проверить, что реально сработало

Минимальный чек:

run.status == success;
task.status == success;
есть artifact в artifact list;
есть manifest для backup_id;
verify (artifact verify или POST /artifacts/<backup_id>/verify) возвращает status=success;
для S3 — объект присутствует в bucket/prefix.

Пример проверки S3:

AWS_ACCESS_KEY_ID="$S3_ACCESS_KEY" AWS_SECRET_ACCESS_KEY="$S3_SECRET_KEY" \
aws s3 ls s3://iobackup/iobackup-tests/curl-demo/ \
  --recursive \
  --endpoint-url https://s3.twcstorage.ru \
  --region ru-1

Запуск задач: curl и iobackupctl