Статус: Draft Дата: 2026-04-29 Область: предметная модель control plane, без выбора БД, брокера, workflow engine или API transport.

1. Цель модели

Этот документ уточняет, какие сущности должны стать first-class объектами control plane. Он отвечает на вопросы:

• что пользователь создает, когда хочет получить инфраструктурный результат;
• как marketplace-сценарии превращаются в конкретный план;
• как capabilities связывают ресурсы, сценарии и jobs;
• чем отличается resource state от operation state;
• какие инварианты нельзя нарушать при будущей реализации.

Базовая формула остается прежней:

1
2
3
4
5

Intent + Capability Requirements + Policies
        -> Resolved Capability Graph
        -> Editable DAG Plan
        -> Operation Run
        -> Resource State + Artifacts + Evidence

2. Высокоуровневая карта домена

3. Агрегаты и ownership

Это логический ownership. Он не означает, что каждая строка должна жить в отдельном сервисе.

4. Основные сущности

4.1 Resource

Resource - управляемая сущность инфраструктуры или платформы.

Примеры:

• cluster/prod-k8s;
• node/worker-3;
• postgres/main;
• tempo/prod-tracing;
• service/api-gateway;
• deployment/api-gateway-prod.

Минимальная модель:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16

resource:
  id: resource-id
  type: kubernetes.cluster
  name: prod-k8s
  organization_id: org-id
  environment: prod
  desired_state: {}
  observed_state: {}
  lifecycle_status: provisioning
  health_status: unknown
  provided_capabilities:
    - kubernetes.cluster
    - workload.runtime
  relationships:
    - type: runs_on
      target: node/worker-1

Resource не должен хранить всю историю изменения. История живет в operations.

4.2 ResourceType

ResourceType описывает класс ресурса и его допустимые действия.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

resource_type:
  key: kubernetes.cluster
  display_name: Kubernetes Cluster
  allowed_actions:
    - create
    - upgrade
    - add_node
    - remove_node
    - repair
    - delete
  default_capabilities:
    - kubernetes.cluster
    - workload.runtime

4.3 CapabilityDefinition

CapabilityDefinition описывает семантику capability.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

capability_definition:
  key: object_storage.s3
  category: storage
  description: S3-compatible object storage endpoint.
  constraint_schema:
    environment: string
    region: string
    encryption: required|optional
    min_capacity_gb: integer
    access_mode: dedicated|shared

Capability key должен быть стабильным контрактом. Constraints уточняют, какой именно provider подходит.

4.4 ProvidedCapability

ProvidedCapability говорит, что конкретный resource предоставляет capability.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

provided_capability:
  resource: minio/prod-storage
  capability: object_storage.s3
  scope:
    environment: prod
    region: eu-central
  attributes:
    encryption: required
    access_mode: shared
    endpoint_ref: secret:minio-endpoint

4.5 CapabilityRequirement

CapabilityRequirement говорит, что scenario, plan node или job требует capability.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

capability_requirement:
  capability: object_storage.s3
  scope: workload
  constraints:
    environment: prod
    region: same-as-workload
    encryption: required
    access_mode: dedicated
  resolution:
    strategy: existing-or-create

Requirement не должен ссылаться на конкретный provider до resolution.

4.6 ResourceBinding

ResourceBinding связывает requirement с concrete resource или sub-operation, которая создаст provider.

1
2
3
4
5
6
7

resource_binding:
  requirement: req-object-storage
  status: resolved
  selected_provider:
    resource: minio/prod-tempo-storage
    capability: object_storage.s3
  resolution_reason: No existing prod provider matched; dedicated MinIO selected by policy.

Если provider еще не существует:

1
2
3
4
5
6

resource_binding:
  requirement: req-object-storage
  status: pending_sub_operation
  sub_operation:
    scenario: minio.install
    expected_capability: object_storage.s3

4.7 Intent

Intent - пользовательское намерение получить результат.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

intent:
  id: intent-id
  actor: user-id
  action: install
  target_resource_type: tempo.instance
  desired_result:
    name: prod-tempo
    version: "2.x"
  constraints:
    environment: prod
    cluster: prod-k8s
  mode: simple
  status: draft

Intent не является планом. Он описывает "что нужно", а не "как сделать".

4.8 ScenarioPack

ScenarioPack - marketplace или internal package, который поставляет сценарии.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

scenario_pack:
  id: tempo
  version: 1.0.0
  source: marketplace
  resource_types:
    - tempo.instance
  provides:
    - observability.tracing
  scenarios:
    - tempo.install
    - tempo.upgrade
    - tempo.repair

4.9 Scenario

Scenario - версионируемый шаблон действия.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

scenario:
  id: tempo.install
  version: 1.0.0
  action: install
  target_resource_type: tempo.instance
  requires:
    - kubernetes.cluster
    - object_storage.s3
    - secret.store
  provides:
    - observability.tracing
  plan_template: tempo.install.default
  editable:
    advanced_mode: true

Scenario является template-level объектом. Он не должен содержать runtime state.

4.10 Plan

Plan - конкретный DAG, построенный из scenario под конкретный intent.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

plan:
  id: plan-id
  intent_id: intent-id
  scenario_ref: tempo.install@1.0.0
  status: ready
  graph:
    nodes: []
    edges: []
  bindings:
    - req-kubernetes-cluster -> cluster/prod-k8s
    - req-object-storage -> sub-operation:minio.install
  customizations:
    base_template: tempo.install@1.0.0
    changes: []

Plan можно редактировать до запуска. После запуска изменения идут через PlanPatch.

4.11 PlanNode

PlanNode - узел DAG. Типы узлов:

• stage;
• job;
• gate;
• sub_operation;
• verification;
• manual_intervention;
• ai_analysis.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

plan_node:
  id: install-runtime
  type: stage
  title: Install runtime
  children:
    - detect-package-manager
    - install-containerd
    - verify-containerd
  requires:
    capabilities:
      - linux.host
      - ssh.access
  produces:
    capabilities:
      - container.runtime.containerd

4.12 JobContract

JobContract описывает input/output конкретного executable node.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

job_contract:
  inputs:
    parameters: {}
    capabilities: []
    artifacts: []
  outputs:
    capabilities: []
    artifacts: []
    evidence: []
  controls:
    retry_policy: {}
    rollback_policy: {}
    manual_intervention_allowed: true
    ai_assistance_allowed: true

Job successful только если output contract подтвержден evidence.

4.13 Operation

Operation - фактический запуск plan.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

operation:
  id: op-id
  intent_id: intent-id
  plan_id: plan-id
  action: create_cluster
  status: running
  actor: user-id
  started_at: timestamp
  completed_at: null
  current_node: install-runtime

Operation хранит execution state, но не должна менять template scenario.

4.14 OperationNodeRun

OperationNodeRun - runtime-состояние конкретного PlanNode.

1
2
3
4
5
6
7
8
9

operation_node_run:
  operation_id: op-id
  plan_node_id: install-containerd
  status: running
  attempts: 1
  started_at: timestamp
  outputs:
    artifacts: []
    evidence: []

4.15 Artifact

Artifact - output, который может быть использован другими nodes.

1
2
3
4
5
6
7

artifact:
  id: artifact-id
  operation_id: op-id
  type: kubeconfig.admin
  sensitivity: secret
  storage_ref: vault:path
  produced_by: init-control-plane

Artifact может быть обычным файлом, secret reference, generated config, report или diagnostics bundle.

4.16 Evidence

Evidence - доказательство, что состояние достигнуто.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

evidence:
  id: evidence-id
  operation_id: op-id
  produced_by: verify-containerd
  capability: container.runtime.containerd
  result: passed
  source:
    type: command
    command: systemctl is-active containerd
  observed_at: timestamp

Evidence отличает реальное достижение состояния от простого "команда завершилась".

4.17 Gate

Gate - точка ожидания решения.

1
2
3
4
5
6
7
8

gate:
  id: approve-prod-storage
  type: approval
  reason: Dedicated object storage will be created in prod.
  required_roles:
    - sre
    - platform_admin
  status: waiting

Gate является узлом DAG и влияет на lifecycle operation.

4.18 Intervention

Intervention - ручное или AI-вмешательство.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

intervention:
  id: intervention-id
  operation_id: op-id
  type: manually_fixed
  actor: user-id
  target_node: join-worker-3
  note: Fixed DNS resolver and restarted kubelet.
  requires_verification:
    - node_registered
    - node_ready

Intervention не должен обходить verification.

4.19 PlanPatch

PlanPatch - структурированное изменение plan.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

plan_patch:
  id: patch-id
  operation_id: op-id
  author: ai-agent:sre
  reason: Registry access failed during kubeadm init.
  changes:
    - insert_after: install-containerd
      node: configure-registry-mirror
    - retry:
      node: init-control-plane
  approval:
    required: true
    status: pending

PlanPatch должен быть auditable и reversible на уровне истории.

5. Связи между сущностями

6. Статусы

6.1 Intent status

6.2 Plan status

6.3 Operation status

6.4 Node run status

6.5 Resource lifecycle status

Resource lifecycle status не заменяет operation status. Он должен ссылаться на active или last operation.

7. Ключевые инварианты

1. Resource и Operation не являются одной сущностью.
2. Scenario template не хранит runtime state.
3. Plan является конкретизацией Scenario под Intent.
4. Запущенный Plan нельзя тихо менять. Изменения только через PlanPatch.
5. Job successful только если output contract подтвержден Evidence.
6. CapabilityRequirement не должен заранее знать concrete provider, если это не явный input пользователя.
7. ResourceBinding должен объяснять, почему выбран конкретный provider.
8. Manual intervention не отменяет verification.
9. AI intervention должен создавать structured output: diagnosis, PlanPatch, recommendation или review.
10. Artifact с secret sensitivity не должен отображаться напрямую пользователю без policy.
11. Operation timeline должен быть auditable.
12. Capability constraints обязательны для production-grade resolution.

8. Границы с текущими сущностями platform-core

Текущие clusters, compute_nodes, internal_services, external_services, marketplace_services можно рассматривать как начальный Resource Catalog.

Control plane добавляет над ними:

• Intent;
• Plan;
• Operation;
• CapabilityRequirement;
• ResourceBinding;
• Artifact;
• Evidence;
• Intervention;
• PlanPatch.

Пример:

1
2
3
4
5
6
7
8

Current:
  cluster row exists with status=provisioning

Control plane:
  operation Create Kubernetes Cluster #482 is running
  current node: install-runtime
  missing capability: network.registry_access on worker-3
  suggested patch: configure registry mirror

9. UX-проекция доменной модели

Simple mode показывает:

• desired result;
• current phase;
• progress;
• needs attention;
• final resource health.

Advanced mode показывает:

• resolved capability graph;
• DAG plan;
• job contracts;
• artifacts;
• evidence;
• gates;
• interventions;
• PlanPatch diff.

Обе проекции используют одну и ту же модель.

10. Открытые вопросы

1. Должен ли Intent сохраняться после завершения operation как отдельный audit object или достаточно Operation?
2. Является ли Stage самостоятельной сущностью или только группирующим PlanNode?
3. Нужна ли отдельная сущность CapabilityProvider, или достаточно Resource + ProvidedCapability?
4. Где проходит граница между Artifact и Evidence, если output является command result?
5. Как версионировать измененный пользователем Plan: fork, overlay или immutable snapshot?
6. Какие resource lifecycle statuses должны быть общими, а какие resource-type-specific?
7. Как отражать drift: через observed_state, отдельную drift operation или evidence failure?

11. Следующий шаг

После этой модели можно проектировать архитектуру компонентов:

• service boundaries;
• API contracts;
• storage ownership;
• event contracts;
• execution runtime;
• AI agent interface;
• marketplace scenario format.