API

Previous Next

API сервиса является internal API для control-plane-service, runners и operational tooling. UI не ходит в execution-plane-service напрямую: product view строится через control-plane-service, который связывает operation/node history с attempts, logs, artifacts и evidence.

Принципы

  • Все write calls idempotent по idempotency_key или lease token.
  • Secret values не принимаются, только secret_refs.
  • JobSpec является входным execution contract.
  • ExecutionResult является выходным contract.
  • Для пользователя attempts видны как часть operation history, а не как отдельная бизнес-сущность.

Execute Job

Создает execution attempt.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
request:
  idempotency_key: operation:op-123:node:install-runtime:run:2
  operation_id: op-123
  plan_id: plan-123
  plan_node_id: install-runtime
  node_run_id: node-run-456
  job_spec:
    api_version: controlplane.aiops.dev/v1
    kind: JobSpec
    job_type: ansible.playbook.run
    runner_requirements:
      runner_kind: ansible
      isolation: default
      network_access: private
    inputs:
      package_ref: marketplace://kubernetes/bootstrap@1.4.0
      playbook_path: playbooks/install-runtime.yml
      inventory_ref: artifact://inventory-789
      variables:
        container_runtime: containerd
    secrets:
      - name: ssh_private_key
        ref: vault://kv/projects/p1/nodes/node-1/ssh_key
    artifacts:
      input_refs:
        - artifact://inventory-789
    timeout_seconds: 1800
    evidence_requirements:
      - name: containerd-active
        type: service_status
        target: systemd:containerd
response:
  attempt_id: exec-attempt-123
  status: queued
  created_at: "2026-04-29T10:00:00Z"

Правила:

  • При повторе с тем же idempotency_key возвращается существующий attempt.
  • Validation failure возвращается синхронно без создания runnable attempt.
  • Если runner unavailable, attempt может быть создан в queued или отклонен по policy.

Get Attempt

Возвращает execution state и refs.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
response:
  attempt_id: exec-attempt-123
  status: running
  runner_kind: ansible
  runner_instance_id: ansible-runner-7
  started_at: "2026-04-29T10:01:00Z"
  last_heartbeat_at: "2026-04-29T10:05:00Z"
  log_refs:
    - artifact://logs/exec-attempt-123/stdout
  output_refs: []

Cancel Attempt

Best-effort cancellation.

1
2
3
4
5
6
7
request:
  attempt_id: exec-attempt-123
  reason: user_cancelled_operation
  requested_by: control-plane-service
response:
  attempt_id: exec-attempt-123
  status: cancellation_requested

Правила:

  • Terminal attempt не отменяется повторно.
  • Runner обязан прекратить работу, сохранить partial artifacts и вернуть final status cancelled.
  • Если runner потерян, dispatcher переводит attempt в lost или cancelled по cancellation policy.

Runner Lease Pull

Runner получает работу через pull или dispatcher assignment.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
request:
  runner_instance_id: ansible-runner-7
  runner_kind: ansible
  capacity_available: 2
  capabilities:
    - ansible.playbook.run
response:
  lease:
    lease_id: lease-123
    attempt_id: exec-attempt-123
    lease_token: opaque-token
    expires_at: "2026-04-29T10:10:00Z"
  job_spec_ref:
    attempt_id: exec-attempt-123

Lease token используется только runner-ом и не передается в UI.

Heartbeat

Runner сообщает progress.

1
2
3
4
5
6
7
8
9
request:
  attempt_id: exec-attempt-123
  lease_token: opaque-token
  phase: executing
  progress_percent: 42
  message: installing container runtime
response:
  accepted: true
  cancellation_requested: false

Если cancellation_requested=true, runner должен перейти к graceful stop.

Complete Attempt

Runner завершает attempt.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
request:
  attempt_id: exec-attempt-123
  lease_token: opaque-token
  status: succeeded
  exit_code: 0
  output_refs:
    - name: ansible-recap
      ref: artifact://outputs/exec-attempt-123/recap.json
      schema_ref: schemas://ansible/recap.v1
  artifact_refs:
    - artifact://logs/exec-attempt-123/bundle.tar.zst
  evidence_refs:
    - evidence://exec-attempt-123/containerd-active
  finished_at: "2026-04-29T10:20:00Z"
response:
  accepted: true

Dispatcher строит ExecutionResult и доставляет его в control-plane-service.

ExecutionResult Callback

Callback в control-plane-service.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
execution_result:
  api_version: controlplane.aiops.dev/v1
  kind: ExecutionResult
  attempt_id: exec-attempt-123
  operation_id: op-123
  plan_node_id: install-runtime
  node_run_id: node-run-456
  status: succeeded
  failure_category: null
  started_at: "2026-04-29T10:01:00Z"
  finished_at: "2026-04-29T10:20:00Z"
  output_refs:
    - name: ansible-recap
      artifact_ref: artifact://outputs/exec-attempt-123/recap.json
      schema_ref: schemas://ansible/recap.v1
  artifact_refs:
    - artifact://logs/exec-attempt-123/bundle.tar.zst
  evidence_refs:
    - evidence://exec-attempt-123/containerd-active

Error Categories

API использует стабильные categories:

  • validation;
  • runner_unavailable;
  • target_unreachable;
  • permission_denied;
  • secret_resolution_failed;
  • artifact_upload_failed;
  • command_failed;
  • timeout;
  • cancelled;
  • heartbeat_lost;
  • internal.

Эти categories помогают control-plane-service предложить retry, manual intervention, PlanPatch или AI remediation.

Совместимость

  • Контракты версионируются через api_version.
  • Добавление optional fields не ломает совместимость.
  • Удаление или изменение semantics existing fields требует новой версии contract.
  • Runner должен явно объявлять поддерживаемые job_type и contract versions.
Обзор Модель данных