Обзор (сервисы control plane)

Previous Next

Статус: Draft Дата: 2026-04-29 Область: сервисная архитектура core-сервисов проекта platform-core.

1. Цель раздела

Этот раздел переводит концепцию control plane в реализационную карту сервисов. Документы должны быть достаточно конкретными, чтобы другой инженер или AI-агент мог начать проектирование репозиториев, API, схем БД, событий и модулей без повторного принятия архитектурных решений.

Документируются только 3 core-сервиса:

AI, IAM, Audit, Billing и будущие домены описываются только как integration points. Они не входят в этот сервисный раздел.

2. Жестко зафиксированные решения

1
2
3
4
5
6
7
8
resource-catalog-service = source of truth for resources/capabilities
control-plane-service = source of truth for scenarios/intents/plans/operations
execution-plane-service = source of truth for execution attempts/runners
Temporal = primary durable runtime, not domain source of truth
Kafka = events/projections, not workflow engine
PostgreSQL per service
Vault for secrets
S3/MinIO for artifacts/log bundles

Каждый микросервис владеет своей БД. Модули внутри сервиса могут иметь отдельные pods/processes, но используют общую БД и общую доменную модель сервиса.

3. Карта сервисов

flowchart TB UI[Web App / API Clients] subgraph Core[platform-core] RC[resource-catalog-service] CP[control-plane-service] EP[execution-plane-service] end TEMP[(Temporal)] KAFKA[(Kafka)] VAULT[(Vault)] S3[(S3 / MinIO)] UI --> RC UI --> CP CP -->|command-time validation
final resource updates| RC CP -->|JobSpec / cancel / result channel| EP CP --> TEMP EP --> VAULT EP --> S3 RC --> KAFKA CP --> KAFKA EP --> KAFKA

4. Source-of-truth matrix

Данные Владелец
Resource metadata resource-catalog-service
Resource type taxonomy resource-catalog-service
Topology resource-catalog-service
Resource relationships resource-catalog-service
Desired/observed state resource-catalog-service
Health summary resource-catalog-service
Capability definitions resource-catalog-service
Provided capabilities resource-catalog-service
Scenario packs/templates control-plane-service
Capability requirements control-plane-service
Resource bindings control-plane-service
Plans and plan nodes control-plane-service
Operations and node runs control-plane-service
Gates/interventions/PlanPatches control-plane-service
Artifact/evidence metadata control-plane-service
Execution attempts and runner leases execution-plane-service
Raw execution output refs execution-plane-service
Secret values and credentials Vault
Artifact/log bundle blobs S3/MinIO

5. Communication rules

  1. UI читает ресурсы из resource-catalog-service и операции из control-plane-service.
  2. control-plane-service держит локальные projections ресурсов/capabilities, чтобы не дергать catalog на каждый plan preview.
  3. Синхронный вызов control-plane-service -> resource-catalog-service разрешен на command boundary: start operation, destructive action, final resource update.
  4. execution-plane-service не вызывает resource-catalog-service напрямую для business decisions.
  5. Kafka используется для facts/projections/audit, но не как workflow engine.
  6. Temporal используется только за adapter внутри control-plane-service; UI и domain model не зависят от Temporal history/UI.

6. Общие conceptual contracts

Контракты ниже не являются protobuf/OpenAPI. Это стабильная conceptual shape для будущей реализации.

6.1 JobSpec

Что control-plane-service передает в execution-plane-service.

 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
job_spec:
  operation_id: uuid
  plan_node_id: string
  attempt_id: uuid
  job_type: ansible | kubernetes | helm | opentofu | ssh | verification
  runner:
    name: ansible-runner
    isolation: container
  target:
    resources:
      - resource_id: node/worker-3
        resource_type: compute.node
    environment: prod
  inputs:
    parameters: {}
    capabilities:
      - container.runtime.containerd
    artifacts:
      - artifact_ref: artifact://operation/node-inventory
    secrets:
      - secret_ref: vault://ssh/prod-worker
  output_contract:
    capabilities:
      - kubernetes.worker_node.joined
    artifacts:
      - kubeadm_join_report
    evidence:
      - node_ready
  controls:
    timeout_seconds: 1800
    retry_policy_ref: retry/default
    allowed_commands_ref: policy/approved-commands

6.2 ExecutionResult

Что execution-plane-service возвращает в control-plane-service.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
execution_result:
  operation_id: uuid
  plan_node_id: string
  attempt_id: uuid
  status: succeeded | failed | cancelled | timed_out
  started_at: timestamp
  finished_at: timestamp
  exit_summary:
    code: 0
    category: success | validation_error | infrastructure_error | policy_error | unknown
    message: short human-readable summary
  artifacts:
    - artifact_ref
  evidence:
    - evidence_ref
  raw_logs:
    - log_ref

6.3 ArtifactRef

1
2
3
4
5
6
7
8
9
artifact_ref:
  id: uuid
  type: kubeconfig.admin | rendered_manifest | diagnostics_bundle | install_report
  storage: s3 | vault | inline_metadata
  uri: s3://aiops-artifacts/operations/op-id/file
  sensitivity: public | internal | secret
  produced_by:
    operation_id: uuid
    plan_node_id: string

6.4 EvidenceRef

1
2
3
4
5
6
7
evidence_ref:
  id: uuid
  type: command_check | api_check | metric_check | log_check | human_verification
  capability: kubernetes.cluster.ready
  result: passed | failed | inconclusive
  source_ref: artifact-or-log-ref
  observed_at: timestamp

6.5 ResourceUpdateCommand

Финальный command из control-plane-service в resource-catalog-service.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
resource_update_command:
  command_id: uuid
  operation_id: uuid
  resource_id: cluster/prod-k8s
  expected_version: integer
  changes:
    lifecycle_status: running
    health_status: healthy
    observed_state_patch: {}
    provided_capabilities:
      add:
        - kubernetes.cluster
        - workload.runtime
  evidence:
    - evidence_ref

6.6 CatalogProjectionEvent

События resource-catalog-service, из которых control-plane-service строит локальные projections.

1
2
3
4
5
6
7
8
9
catalog_projection_event:
  event_id: uuid
  event_type: resource.updated | capability.provided | resource.health_changed
  resource_id: string
  resource_type: string
  organization_id: uuid
  version: integer
  payload: {}
  occurred_at: timestamp

7. Документы сервисов

resource-catalog-service

control-plane-service

execution-plane-service

Примеры (control plane) Обзор