Примеры (control plane)

Статус: Draft Дата: 2026-04-29

1. Создание Kubernetes-кластера

Intent:

intent:
  action: create
  target_resource_type: kubernetes.cluster
  desired_result:
    name: prod-k8s
    masters: 3
    workers: 5
    cni: calico
    container_runtime: containerd
    storage: longhorn
  constraints:
    environment: prod
    region: eu-central
    require_ha_control_plane: true

Высокоуровневый DAG:

flowchart TB A[Validate inputs] B[Validate nodes] C[Validate credentials] D[Prepare network] E[Install runtime] F[Init control-plane] G[Install CNI] H[Join masters] I[Join workers] J[Install addons] K[Verify cluster] A --> B A --> C B --> D C --> D D --> E E --> F F --> G F --> H G --> I H --> I I --> J J --> K

Stage contracts

Stage	Requires	Produces
Validate inputs	intent, scenario template, organization policy	validated intent, normalized parameters
Validate nodes	compute nodes, SSH metadata, topology	linux.host, node_inventory, node eligibility evidence
Validate credentials	secret references, access policy	ssh.access, registry.access, credential evidence
Prepare network	node_inventory, firewall policy	host.network.ready, wireguard.mesh, network evidence
Install runtime	linux.host, ssh.access, registry.access	container.runtime.containerd, runtime evidence
Init control-plane	runtime, kubeadm config, network ready	kubernetes.api, kubeconfig.admin, join token
Install CNI	kubernetes.api, CNI manifest	kubernetes.network.ready, cni evidence
Join masters	kubernetes.api, join token, runtime	control_plane.nodes.joined
Join workers	kubernetes.api, join token, runtime	worker.nodes.joined
Verify cluster	kubernetes.api, joined nodes, CNI	kubernetes.cluster.ready, health evidence

Пример job: init control-plane

job:
  id: init-control-plane
  inputs:
    requires:
      capabilities:
        - container.runtime.containerd
        - host.network.ready
        - kubernetes.binaries.kubeadm
      artifacts:
        - kubeadm_cluster_config
        - node_inventory
  outputs:
    provides:
      capabilities:
        - kubernetes.api
        - kubernetes.control_plane.initialized
    artifacts:
      - kubeconfig.admin
      - kubeadm.join_token
      - cluster_ca_certificate_ref
    evidence:
      - kube_apiserver_healthy
      - kubeadm_init_completed

2. Добавление worker-ноды

Intent:

intent:
  action: add_node
  target_resource: cluster/prod-k8s
  node: worker-6
  role: worker

DAG:

flowchart LR validateNode[Validate node] prepareNetwork[Update WireGuard mesh] prepareHost[Prepare Kubernetes prerequisites] generateToken[Generate join token] joinNode[Join worker] labelNode[Apply labels and taints] verify[Verify node Ready] validateNode --> prepareNetwork prepareNetwork --> prepareHost prepareHost --> generateToken generateToken --> joinNode joinNode --> labelNode labelNode --> verify

Если kubeadm.join_token отсутствует или истек, control plane не должен падать без объяснения. Он может вставить job generate-join-token, потому что downstream job требует именно artifact kubeadm.join_token.

3. Установка Tempo с S3 dependency

Tempo не должен знать, что обязательно нужен MinIO. Он должен требовать capability object_storage.s3.

scenario: tempo.install
requires:
  - capability: kubernetes.cluster
  - capability: object_storage.s3
  - capability: secret.store
provides:
  - capability: observability.tracing

Resolution:

flowchart TB tempo[Install Tempo] s3[requires object_storage.s3] policy[Apply provider policy] existing{Existing provider?} minio[Sub-operation: Install MinIO] bucket[Create bucket and credentials] deploy[Deploy Tempo] verify[Verify ingestion and query] tempo --> s3 s3 --> policy policy --> existing existing -->|yes| bucket existing -->|no| minio minio --> bucket bucket --> deploy deploy --> verify

Пользователь в simple mode видит:

Installing Tempo
  Storage dependency: creating MinIO
  Tempo deployment: waiting
  Verification: pending

Advanced mode показывает полный capability graph и sub-operation.

4. Failed stage и AI PlanPatch

Сценарий: init-control-plane упал, потому что kubeadm не смог скачать images.

sequenceDiagram participant Run as Operation Run participant Job as init-control-plane participant AI as AI Analyzer participant User as SRE/User participant Plan as Plan Run->>Job: execute Job-->>Run: failed Run->>AI: provide logs, artifacts, evidence AI-->>Run: diagnosis + PlanPatch Run->>User: show patch and risk User-->>Run: approve Run->>Plan: insert registry mirror jobs Run->>Job: retry init-control-plane

PlanPatch:

plan_patch:
  reason: Nodes cannot pull images from registry-1.docker.io.
  changes:
    - insert_after: install-container-runtime
      jobs:
        - configure-containerd-registry-mirror
        - restart-containerd
        - pre-pull-kubernetes-images
    - retry:
        job: init-control-plane
  approval:
    required: true

Важный принцип: AI не должен "просто выполнить команду". Он должен предложить структурированный patch к DAG, который можно проверить, отклонить или применить.

5. Ручное исправление

Сценарий: join-workers упал на worker-3, пользователь зашел по SSH, поправил DNS и перезапустил kubelet.

intervention:
  type: manually_fixed
  target:
    stage: join-workers
    node: worker-3
  note: Fixed resolver config and restarted kubelet.
  verification:
    - kubelet_ready
    - node_registered
    - node_ready

После этого control plane выполняет verification:

flowchart LR manual[Manual fix recorded] kubelet[Verify kubelet] registered[Verify node registered] ready[Verify node Ready] continue[Continue operation] manual --> kubelet kubelet --> registered registered --> ready ready --> continue

6. Редактирование plan в advanced mode

Marketplace template:

kubernetes.create@1.0.0
  validate
  prepare network
  install runtime
  init control-plane
  install CNI
  join workers
  install addons
  verify

Пользовательская версия:

kubernetes.create@1.0.0 forked
  validate
  prepare network
  install runtime
  configure registry mirror
  pre-pull images
  init control-plane
  install CNI
  join workers
  verify

Plan должен хранить отличия:

customizations:
  base_template: kubernetes.create@1.0.0
  changes:
    - inserted: configure-registry-mirror
      after: install-runtime
    - inserted: pre-pull-images
      after: configure-registry-mirror
    - removed: install-addons

7. Как это должно выглядеть пользователю

Simple mode:

Create Kubernetes Cluster
Status: Running
Current phase: Installing container runtime
Progress: 5 of 10 phases
Needs attention: no
Estimated remaining time: 12 minutes

Advanced mode:

Operation #482
Plan: kubernetes.create@1.0.0 customized
Graph:
  prepare-network -> install-runtime -> init-control-plane
Failed jobs: none
Artifacts:
  node_inventory
  containerd_config_snapshot
Evidence:
  ssh_access_verified
  wireguard_mesh_ready
  containerd_service_active

Обе оптики работают над одной operation model.

Протокол v0 (control plane) Обзор (сервисы control plane)

На странице

1. Создание Kubernetes-кластера Stage contracts Пример job: init control-plane 2. Добавление worker-ноды 3. Установка Tempo с S3 dependency 4. Failed stage и AI PlanPatch 5. Ручное исправление 6. Редактирование plan в advanced mode 7. Как это должно выглядеть пользователю