Протокол v0 (control plane)

Статус: Draft Дата: 2026-04-29 Цель: зафиксировать язык и объектную модель control plane до выбора конкретной реализации.

1. Базовая формула

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

Эта формула должна быть одинаковой для создания Kubernetes-кластера, добавления ноды, установки PostgreSQL, установки Tempo, ремонта failed stage и других сценариев.

2. Объектная модель

flowchart TB Resource["Resource
id, type, name
desired_state, observed_state
health, provided_capabilities"] Intent["Intent
id, target_resource_type
desired_result, parameters, constraints"] Scenario["Scenario
id, version, actions
required_capabilities, provided_capabilities
plan_template"] Plan["Plan
id, scenario_ref, graph
customizations, capability_bindings"] Operation["Operation
id, intent_id, plan_id
status, timeline, actor"] Stage["Stage
id, name, status, jobs"] Job["Job
id, type
input_contract, output_contract
retry_policy"] CapabilityRequirement["CapabilityRequirement
key, constraints, scope"] Artifact["Artifact
id, type, location, sensitivity"] Evidence["Evidence
id, check_type, result, source"] PlanPatch["PlanPatch
id, operation, diff
author, approval"] Intent --> Scenario Scenario --> Plan Plan --> Operation Plan --> Stage Stage --> Job Job --> CapabilityRequirement Job --> Artifact Job --> Evidence Operation --> PlanPatch Resource --> CapabilityRequirement

3. Lifecycle операции

flowchart TB Start([start]) --> DraftIntent DraftIntent --> PlanPreview: build plan PlanPreview --> CapabilityResolution: resolve requirements CapabilityResolution --> WaitingForInput: missing input or provider choice WaitingForInput --> CapabilityResolution: user selects/provides input CapabilityResolution --> WaitingForApproval: gates or risk approval WaitingForApproval --> Running: approved CapabilityResolution --> Running: no approval needed Running --> Paused: manual pause or gate Paused --> Running: resume Running --> Failed: job/stage failed Failed --> Diagnosing: AI or human investigation Diagnosing --> PlanPatchReview: proposed patch PlanPatchReview --> Running: approved and applied Failed --> Running: retry Failed --> Verification: manually fixed Verification --> Running: verified Verification --> Failed: still broken Running --> Completed: outputs verified Completed --> End([end])

4. Resource и Operation

Resource описывает управляемый объект. Operation описывает процесс изменения объекта.

Пример:

Resource:
  type: cluster
  name: prod-k8s
  desired_state: kubernetes cluster with 3 masters and 5 workers
  observed_state: 3 masters ready, 5 workers ready
  health: healthy

Operation:
  action: create_cluster
  status: completed
  plan: kubernetes.create@1.0.0 customized
  artifacts: kubeconfig, inventory snapshot, install reports
  evidence: kubectl get nodes, cni health, api health

Ресурс может быть provisioning, running, degraded или error, но полная причина состояния должна быть видна через связанные operations.

5. Capability

Capability бывает двух типов.

Provided capability:

cluster/prod-k8s provides:
  - kubernetes.cluster
  - workload.runtime
  - ingress.target

Required capability:

tempo requires:
  - kubernetes.cluster
  - object_storage.s3
  - secret.store

Capability должна поддерживать constraints. Без constraints она быстро станет слишком общей.

requires:
  capability: object_storage.s3
  constraints:
    environment: prod
    region: same-as-workload
    encryption: required
    min_capacity_gb: 500
    access_mode: dedicated

6. Capability resolution

Resolution связывает requirement с concrete provider.

flowchart TB req[Requirement: object_storage.s3] --> policy[Provider policy] policy --> candidates[Find candidates] candidates --> match{Matching provider?} match -->|yes| bind[Bind existing resource] match -->|no| create[Create provider through sub-operation] match -->|ambiguous| gate[User/provider selection gate] bind --> graph[Resolved capability graph] create --> graph gate --> graph

Provider policy может зависеть от organization, environment, criticality, cost, compliance и роли пользователя.

Пример:

capability_policy:
  object_storage.s3:
    dev:
      allowed_providers: [shared_minio]
    stage:
      allowed_providers: [shared_minio, dedicated_minio]
      default_provider: shared_minio
    prod:
      allowed_providers: [aws_s3, dedicated_minio]
      require_encryption: true
      require_approval: true

7. DAG Plan

Plan является DAG, а не просто линейным списком. Узлы DAG зависят от конкретных output capabilities и artifacts, а не только от имени предыдущей стадии.

flowchart LR validateInputs[validate inputs] validateNodes[validate nodes] validateCredentials[validate credentials] prepareNetwork[prepare network] installRuntime[install runtime] initControlPlane[init control-plane] installCni[install CNI] joinWorkers[join workers] verify[verify] validateInputs --> validateNodes validateInputs --> validateCredentials validateNodes --> prepareNetwork validateCredentials --> prepareNetwork prepareNetwork --> installRuntime installRuntime --> initControlPlane initControlPlane --> installCni initControlPlane --> joinWorkers installCni --> joinWorkers joinWorkers --> verify

8. Job contract

Каждый job обязан декларировать input/output contract.

job:
  id: install-container-runtime
  title: Install container runtime
  type: automation
  scope:
    resources:
      - compute_node
  inputs:
    parameters:
      runtime: containerd
      version: "1.7.x"
    requires:
      capabilities:
        - key: linux.host
          scope: target_nodes
        - key: ssh.access
          scope: target_nodes
        - key: package.manager.apt
          scope: target_nodes
        - key: network.registry_access
          scope: target_nodes
      artifacts:
        - node_inventory
        - registry_mirror_config
  outputs:
    provides:
      capabilities:
        - key: container.runtime.containerd
          scope: target_nodes
    artifacts:
      - containerd_config_snapshot
      - package_install_report
    evidence:
      - containerd_service_active
      - crictl_works
  controls:
    retry_policy:
      max_attempts: 2
    idempotency:
      key: install-containerd:{node_id}:{version}
    rollback:
      supported: partial
    manual_intervention:
      allowed: true

9. Artifact

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

Примеры:

generated inventory;
kubeconfig;
kubeadm join token;
Helm values;
generated manifest;
secret reference;
package install report;
diagnostics bundle.

Artifact должен иметь sensitivity:

artifact:
  type: kubeconfig.admin
  sensitivity: secret
  storage: secret_ref
  visible_to_roles:
    - sre
    - platform_admin

10. Evidence

Evidence доказывает, что output capability действительно существует.

Пример:

evidence:
  - id: containerd_service_active
    source: systemd
    command: systemctl is-active containerd
    expected: active
  - id: crictl_works
    source: command
    command: crictl info
    expected_exit_code: 0

Правило: job не должен считаться successful только по exit code automation tool. Он successful, если output contract подтвержден evidence.

11. Stage и Job

Stage нужен для human UX. Job нужен для protocol и execution.

Stage: Install runtime
  Jobs:
    - detect package manager
    - configure registry mirror
    - install containerd
    - configure containerd
    - restart containerd
    - verify runtime

Simple mode показывает stage. Advanced mode раскрывает jobs и контракты.

12. Gates

Gate является узлом DAG.

Типы gate:

approval gate;
provider selection gate;
destructive action gate;
policy exception gate;
missing input gate;
cost confirmation gate.

Пример:

gate:
  id: approve-dedicated-minio
  reason: Tempo requires object_storage.s3 and no existing prod provider matches.
  options:
    - create dedicated MinIO
    - bind external S3
    - cancel operation
  required_roles:
    - sre
    - platform_admin

13. Manual intervention

Manual intervention должен быть first-class объектом.

intervention:
  type: manually_fixed
  target_stage: join-workers
  actor: user
  note: Fixed DNS resolver on worker-3 and restarted kubelet.
  requires_verification:
    - kubelet_ready
    - node_registered

После manual fix control plane не должен просто продолжать. Он должен выполнить verification jobs.

14. AI intervention

AI должен производить структурированный результат, а не только текст.

Роли AI:

Analyzer: анализирует failed stage, logs, artifacts и observed state.
Planner: предлагает PlanPatch.
Executor: выполняет только разрешенные policy действия.
Reviewer: проверяет план до запуска.

Пример PlanPatch:

plan_patch:
  author: ai-agent:sre
  reason: kubeadm init failed because images cannot be pulled from registry-1.docker.io.
  changes:
    - insert_after: install-container-runtime
      jobs:
        - id: configure-containerd-registry-mirror
        - id: restart-containerd
        - id: pre-pull-kubernetes-images
    - retry:
        job: init-control-plane
  approval:
    required: true
    roles: [sre]

15. Marketplace scenario pack

Минимальный контракт marketplace-сценария:

scenario_pack:
  id: tempo
  version: 1.0.0
  resource_types:
    - tempo.instance
  actions:
    - install
    - upgrade
    - scale
    - repair
    - uninstall
  requires:
    - capability: kubernetes.cluster
    - capability: object_storage.s3
    - capability: secret.store
  provides:
    - capability: observability.tracing
  plan_templates:
    - id: tempo.install
      entrypoint: install-tempo
  editable:
    advanced_mode: true
  risk:
    default_level: medium

16. Что пока не решаем

Этот документ намеренно не выбирает:

движок workflow;
брокер событий;
формат хранения DAG;
модель исполнения workers;
конкретный API;
схему БД.

Следующий шаг: превратить этот язык в архитектуру компонентов, API contracts и storage model.

Доменная модель v0 Примеры (control plane)

На странице

1. Базовая формула 2. Объектная модель 3. Lifecycle операции 4. Resource и Operation 5. Capability 6. Capability resolution 7. DAG Plan 8. Job contract 9. Artifact 10. Evidence 11. Stage и Job 12. Gates 13. Manual intervention 14. AI intervention 15. Marketplace scenario pack 16. Что пока не решаем