Модель данных

Previous Next

Модель данных описывает execution lifecycle, а не бизнес-операции. База сервиса отвечает на вопросы: какая попытка была создана, какой runner ее взял, как она завершилась, где лежат логи и какие output/evidence refs были произведены.

Основные Сущности

erDiagram EXECUTION_ATTEMPTS ||--o{ RUNNER_LEASES : has EXECUTION_ATTEMPTS ||--o{ ATTEMPT_HEARTBEATS : records EXECUTION_ATTEMPTS ||--o{ RAW_LOG_REFS : writes EXECUTION_ATTEMPTS ||--o{ RUNNER_OUTPUT_REFS : produces EXECUTION_ATTEMPTS ||--o{ ATTEMPT_EVENTS : emits RUNNER_INSTANCES ||--o{ RUNNER_LEASES : receives RUNNER_INSTANCES ||--o{ RUNNER_STATUSES : reports RUNNER_OUTPUT_REFS ||--o{ EVIDENCE_REFS : contains

execution_attempts

Immutable attempt record for one technical execution.

Conceptual fields:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
execution_attempt:
  id: uuid
  operation_id: uuid
  plan_id: uuid
  plan_node_id: uuid
  node_run_id: uuid
  requested_by_service: control-plane-service
  idempotency_key: string
  job_type: ansible.playbook.run | kubernetes.manifest.apply | helm.install | opentofu.apply | ssh.command.run | verify.*
  job_spec_ref: jsonb
  status: queued | leased | running | succeeded | failed | cancelled | timed_out | lost
  failure_category: validation | runner_unavailable | target_unreachable | permission_denied | command_failed | timeout | cancelled | heartbeat_lost | internal
  runner_kind: ansible | kubernetes | helm | opentofu | ssh | verification
  runner_instance_id: string
  priority: integer
  timeout_seconds: integer
  created_at: timestamp
  leased_at: timestamp
  started_at: timestamp
  finished_at: timestamp

Правила:

  • id не меняется.
  • status движется только вперед по lifecycle.
  • job_spec_ref хранит normalized spec without secret values.
  • idempotency_key защищает от двойного создания attempt при retry API call.

runner_instances

Регистрирует live runner processes/pods.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
runner_instance:
  id: string
  runner_kind: ansible | kubernetes | helm | opentofu | ssh | verification
  version: semver
  capabilities:
    - ansible.playbook.run
    - ansible.check_mode.run
  zone: string
  labels:
    isolation: default
    network: private
  registered_at: timestamp
  last_seen_at: timestamp

Runner instance не является resource catalog resource. Это execution-plane runtime entity.

runner_leases

Lease связывает attempt и runner на ограниченное время.

1
2
3
4
5
6
7
8
9
runner_lease:
  id: uuid
  attempt_id: uuid
  runner_instance_id: string
  lease_token_hash: string
  status: active | released | expired | revoked
  expires_at: timestamp
  created_at: timestamp
  released_at: timestamp

Правила:

  • Только runner с active lease может отправлять heartbeat и complete attempt.
  • Lease token не хранится в открытом виде.
  • Expired lease переводит attempt в lost, если нет безопасного продолжения.

attempt_heartbeats

Append-only heartbeat stream.

1
2
3
4
5
6
7
8
attempt_heartbeat:
  id: uuid
  attempt_id: uuid
  runner_instance_id: string
  phase: pulling_artifacts | resolving_secrets | executing | uploading_artifacts | completing
  progress_percent: integer
  message: string
  created_at: timestamp

Heartbeat messages должны проходить secret masking.

raw_log_refs

Ссылки на raw logs и chunks.

1
2
3
4
5
6
7
8
9
raw_log_ref:
  id: uuid
  attempt_id: uuid
  stream: stdout | stderr | event_stream | system
  artifact_ref_id: uuid
  byte_size: integer
  line_count: integer
  masked: boolean
  created_at: timestamp

Raw logs всегда лежат в S3/MinIO. PostgreSQL хранит только metadata и refs.

runner_output_refs

Нормализованные outputs runner-а.

1
2
3
4
5
6
7
8
9
runner_output_ref:
  id: uuid
  attempt_id: uuid
  name: string
  output_type: json | yaml | text | archive | binary | resource_refs | evidence_bundle
  artifact_ref_id: uuid
  schema_ref: string
  digest: string
  created_at: timestamp

Output refs используются control-plane-service для output contract validation и evidence recording.

evidence_refs

Ссылки на доказательства postcondition или output contract.

1
2
3
4
5
6
7
8
9
evidence_ref:
  id: uuid
  attempt_id: uuid
  output_ref_id: uuid
  evidence_type: assertion | probe | log_excerpt | resource_snapshot | signed_report
  status: passed | failed | inconclusive
  subject_ref: string
  artifact_ref_id: uuid
  recorded_at: timestamp

execution-plane-service может произвести evidence, но финальное решение о node success принимает control-plane-service.

artifact_refs

Единый формат ссылки на артефакт.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
artifact_ref:
  id: uuid
  storage: s3 | minio
  bucket: string
  key: string
  content_type: string
  digest: sha256
  byte_size: integer
  retention_class: short | normal | long | legal_hold
  created_at: timestamp

Artifact body не хранится в БД.

runner_statuses

Текущее состояние runner pool для scheduling.

1
2
3
4
5
6
7
8
runner_status:
  runner_instance_id: string
  runner_kind: string
  status: ready | busy | draining | unhealthy | offline
  capacity_total: integer
  capacity_used: integer
  last_error: string
  updated_at: timestamp

attempt_events

Append-only timeline attempt-а.

1
2
3
4
5
6
attempt_event:
  id: uuid
  attempt_id: uuid
  event_type: created | leased | started | heartbeat | artifact_created | succeeded | failed | cancelled | timed_out | lost
  payload: jsonb
  created_at: timestamp

Эта таблица строит внутреннюю execution history и помогает восстановить callback delivery после сбоя.

Status Lifecycle

flowchart LR queued --> leased leased --> running running --> succeeded running --> failed running --> cancelled running --> timed_out running --> lost leased --> lost queued --> cancelled

Недопустимо вернуть attempt из terminal status обратно в running.

Индексы

Обязательные индексы:

  • execution_attempts(operation_id, plan_node_id, created_at);
  • execution_attempts(status, priority, created_at);
  • execution_attempts(idempotency_key) unique;
  • runner_leases(attempt_id, status);
  • runner_leases(runner_instance_id, status);
  • attempt_heartbeats(attempt_id, created_at);
  • raw_log_refs(attempt_id, stream);
  • runner_output_refs(attempt_id, name);
  • artifact_refs(digest);
  • attempt_events(attempt_id, created_at).

Retention

  • Attempt metadata хранится долго, чтобы UI мог показывать историю операций.
  • Raw logs могут иметь tiered retention.
  • Evidence refs хранятся не меньше operation history.
  • Secret material не хранится никогда.
API События