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

1. Термины проектирования

В этой архитектуре используются такие уровни:

• Проект - большой домен, объединяющий несколько микросервисов. Пример: platform-core, auth-platform.
• Микросервис - bounded context со своей БД и своими контрактами. Микросервисы не ходят в одну общую БД.
• Модуль микросервиса - отдельный runtime/process/pod внутри микросервиса, который разделяет БД и доменную модель этого микросервиса. Пример: api, worker, scheduler, runner.

Пример из текущего стиля проекта:

1
2
3
4

auth-platform/
  identity-service/
    api
    worker

Для нового platform-core это означает: мы не пытаемся превратить все в один микросервис, но и не выносим сильно связанные части в отдельные сервисы, если это приведет к постоянным синхронным запросам и дублированию данных.

2. Главный принцип разбиения

Микросервисная граница оправдана, если:

• сервис владеет отдельной моделью данных;
• другой сервис не должен читать его данные на каждом шаге обычного сценария;
• данные можно синхронизировать событиями или projections;
• workload, scaling, risk profile или security boundary существенно отличаются.

Микросервисная граница вредна, если:

• два компонента постоянно участвуют в одном transaction-like use case;
• один компонент без другого почти не может отвечать на свои основные запросы;
• приходится хранить почти полную копию данных соседнего сервиса;
• большинство запросов превращаются в цепочку синхронных вызовов.

На этом основании scenario-registry не выносится в отдельный микросервис: он слишком тесно связан с control-plane-service.

3. Итоговая структура проекта

1
2
3
4

platform-core/
  resource-catalog-service/
  control-plane-service/
  execution-plane-service/

Подробная документация по каждому core-сервису находится в services/index.ru.md.

Опциональные внешние/соседние домены:

1
2
3

ai-ops-agent-service/
iam-platform/
audit-service/

ai-ops-agent-service не является владельцем операций. Он анализирует, предлагает patches и reviews. iam-platform принимает решения о доступе и ролях. audit-service хранит независимый audit trail.

4. Общая схема компонентов

5. resource-catalog-service

Смысл: что у нас есть.

resource-catalog-service владеет каноническим каталогом ресурсов и их provided capabilities.

Владеет данными

• Organizations / tenant context для platform resources.
• Topology: regions, datacenters, layers, segments.
• Compute nodes.
• Clusters.
• Internal/external services.
• Deployments.
• Managed resources: postgres, redis, tempo, minio, vault, kafka и другие.
• Resource relationships.
• Resource desired state и observed state.
• Resource health summary.
• Capability definitions.
• Provided capabilities.

Модули

1
2
3
4
5

resource-catalog-service/
  api
  worker
  observer
  projector

БД

Одна PostgreSQL БД сервиса.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

resource_catalog_db
  resources
  resource_types
  resource_relationships
  resource_desired_state
  resource_observed_state
  capability_definitions
  provided_capabilities
  topology
  read_models

Важная граница

resource-catalog-service не исполняет долгие операции. Он может принять команду уровня "зарегистрировать ресурс" или "обновить metadata", но создание реального Kubernetes-кластера, установка Tempo или ремонт ноды идут через control-plane-service.

6. control-plane-service

Смысл: что хотим сделать, какой план построен и как идет операция.

control-plane-service владеет намерениями, сценариями, планами, операциями, gates, patches и timeline.

Владеет данными

• Intent.
• ScenarioPack.
• Scenario.
• PlanTemplate.
• JobTemplate / JobContract.
• CapabilityRequirement.
• ResourceBinding.
• Plan.
• PlanNode.
• Operation.
• OperationNodeRun.
• Gate.
• Intervention.
• PlanPatch.
• Artifact metadata.
• Evidence metadata.
• Operation timeline.
• Local catalog/capability projections.

Модули

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

control-plane-service/
  api
  scenario-registry
  planner
  capability-resolver
  operation-manager
  workflow-worker
  policy-adapter
  ai-adapter
  event-worker

Почему scenario-registry здесь

scenario-registry не выносится в отдельный микросервис, потому что:

• planner постоянно читает scenario templates;
• resolver читает capability requirements сценариев;
• plan preview требует scenario, job contracts и policy metadata;
• operation validation зависит от версии scenario;
• PlanPatch может ссылаться на templates/jobs из registry.

Если вынести registry отдельно, control-plane-service будет либо постоянно дергать его синхронно, либо держать почти полную копию. Поэтому это модуль внутри control-plane-service, но с четкой внутренней границей, чтобы позже его можно было вынести только при реальной необходимости.

БД

Одна PostgreSQL БД сервиса.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21

control_plane_db
  intents
  scenario_packs
  scenarios
  plan_templates
  job_templates
  capability_requirements
  resource_bindings
  plans
  plan_nodes
  operations
  operation_node_runs
  gates
  interventions
  plan_patches
  artifact_metadata
  evidence_metadata
  operation_timeline
  catalog_resource_projection
  catalog_capability_projection
  catalog_topology_projection

Projections вместо постоянных вызовов

control-plane-service держит локальные projections каталога:

• resources;
• topology;
• provided capabilities;
• capability definitions;
• active/last operation references при необходимости.

Это нужно, чтобы plan preview и capability resolution не ходили в resource-catalog-service на каждый read.

Синхронные вызовы в catalog нужны только на command boundary:

• перед стартом operation;
• перед destructive action;
• перед финальным bind/update resource;
• если projection устарела и нужна сильная проверка.

Product API и история операций

control-plane-service обязан иметь собственный API для интерфейса. UI не должен зависеть от Temporal UI, Argo UI или UI другого workflow engine. Workflow engine может быть внутренним runtime, но продуктовый опыт строится поверх нашей доменной модели.

Интерфейс должен уметь показывать operation history примерно как GitLab pipelines:

• список операций по ресурсу, пользователю, организации, сценарию и статусу;
• текущую active operation для ресурса;
• историю completed/failed/cancelled operations;
• DAG плана;
• stages и jobs;
• статусы каждого узла;
• attempts, retries, duration, started/finished timestamps;
• logs и raw outputs;
• artifacts;
• evidence;
• gates и approvals;
• manual interventions;
• AI diagnosis и PlanPatch history.

Пример продуктовых API:

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

GET  /v1/operations
GET  /v1/operations/{operation_id}
GET  /v1/operations/{operation_id}/graph
GET  /v1/operations/{operation_id}/timeline
GET  /v1/operations/{operation_id}/nodes
GET  /v1/operations/{operation_id}/nodes/{node_id}
GET  /v1/operations/{operation_id}/nodes/{node_id}/logs
GET  /v1/operations/{operation_id}/artifacts
GET  /v1/operations/{operation_id}/evidence
GET  /v1/resources/{resource_id}/operations
POST /v1/operations/{operation_id}/pause
POST /v1/operations/{operation_id}/resume
POST /v1/operations/{operation_id}/cancel
POST /v1/operations/{operation_id}/nodes/{node_id}/retry
POST /v1/operations/{operation_id}/gates/{gate_id}/approve
POST /v1/operations/{operation_id}/interventions
POST /v1/operations/{operation_id}/patches/{patch_id}/approve

Для этого нужны read models внутри control-plane-service:

1
2
3
4
5
6
7
8

operation_summary_view
operation_graph_view
operation_timeline_view
operation_node_run_summary
operation_job_log_index
operation_artifact_index
operation_evidence_index
resource_operation_index

Правило: operation history должна быть audit-friendly и immutable на уровне фактов. Если plan меняется во время выполнения, история не переписывается; добавляется PlanPatch, approval и новая версия effective plan.

7. execution-plane-service

Смысл: как реально выполнить job.

execution-plane-service не владеет business operation model. Он владеет execution attempts, runners, raw logs, leases и technical execution records.

Владеет данными

• ExecutionAttempt.
• RunnerLease.
• RunnerStatus.
• Raw execution logs metadata.
• Runner output metadata.
• Temporary job state.

Модули

1
2
3
4
5
6
7
8
9

execution-plane-service/
  dispatcher
  ansible-runner
  kubernetes-runner
  helm-runner
  opentofu-runner
  ssh-runner
  verification-runner
  artifact-worker

БД

Одна PostgreSQL БД сервиса.

1
2
3
4
5
6

execution_plane_db
  execution_attempts
  runner_leases
  runner_statuses
  raw_log_refs
  runner_output_refs

Важная граница

Source of truth по operation остается в control-plane-service. execution-plane-service возвращает execution result, artifacts и evidence, но не решает, завершена ли business operation.

8. AI agent boundary

AI не должен быть execution-plane.

AI-слой может жить как отдельный домен:

1
2
3
4

ai-ops-agent-service/
  analyzer
  planner
  reviewer

Роли:

• Analyzer - анализ failed operation, logs, artifacts, evidence.
• Planner - предлагает PlanPatch.
• Reviewer - проверяет plan до запуска, объясняет risk и blast radius.

AI возвращает structured output:

1
2
3
4

Diagnosis
PlanPatch
RiskReview
Recommendation

control-plane-service применяет результат только через policy, gates и approvals.

9. Инфраструктурные технологии

Temporal не является доменной моделью. Доменная модель живет в PostgreSQL control-plane-service. Temporal отвечает за durability: retries, timers, signals, pause/resume, human gates и long-running workflows.

10. Выбор workflow/orchestration engine

Под workflow engine здесь понимается runtime для long-running operations: retries, timers, cancellation, resume, human gates, signals, parallel branches и crash recovery.

Важно: какой бы движок ни был выбран, source of truth для продукта остается в control-plane-service. Движок не должен диктовать доменную модель Intent, Plan, Operation, PlanPatch, Evidence.

Решение для текущей архитектуры: Temporal является primary durable runtime за workflow-engine adapter. Остальные варианты остаются кандидатами для будущих specialized adapters или замены runtime, но не являются базовым выбором.

Критерии выбора

Кандидаты

Решение

Архитектурно нужно ввести внутренний workflow-engine adapter, чтобы не зашить Temporal или любой другой движок в доменную модель:

1
2
3
4
5
6

control-plane-service
  operation-manager
  workflow-engine-adapter
    temporal-adapter
    conductor-adapter
    custom-dag-adapter

Primary runtime фиксируется как Temporal, потому что он лучше всего закрывает durable execution, signals, retries и long-running operations. Но продуктовые API, operation history, plan graph, gates и patches должны жить в control-plane-service.

Если позже выяснится, что dynamic DAG/PlanPatch слишком сильно конфликтует с Temporal model, можно рассмотреть специализированные adapters:

• Conductor/Kestra как более declarative workflow runtime;
• Argo Workflows для Kubernetes-only execution subgraphs;
• собственный DAG engine поверх PostgreSQL для operation runtime;
• гибрид: control-plane own DAG engine + Temporal только для durable activities/timers.

11. Коммуникация

Синхронная коммуникация

Синхронные вызовы должны быть на границах команд, а не на каждом read.

Асинхронная коммуникация

Kafka события:

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

resource.created
resource.updated
resource.deleted
capability.definition.published
capability.provided
intent.created
plan.created
operation.started
operation.node.started
operation.node.succeeded
operation.node.failed
operation.completed
operation.cancelled
gate.waiting
gate.approved
gate.rejected
plan.patch.proposed
plan.patch.approved
artifact.created
evidence.recorded

События используются для projections, audit, read models и loosely-coupled integrations. Они не заменяют source of truth.

12. Source of truth matrix

13. Типовой flow: установка Tempo

14. Почему не один микросервис

Один большой platform-core-service быстро смешает:

• catalog state;
• operation state;
• execution attempts;
• runner security;
• scenario registry;
• observed state.

У этих частей разные риски и разные нагрузки. Особенно execution-plane должен быть изолирован: он работает с SSH, Ansible, Helm, Kubernetes API, secrets и потенциально опасными side effects.

15. Почему не больше микросервисов

Не стоит выносить отдельно:

• organizations внутри platform-core;
• scenario-registry;
• planner;
• capability-resolver;
• operation-manager.

Причина: они постоянно участвуют в одном planning/operation use case и ходят в одни и те же данные. Разделение создаст лишние синхронные вызовы и сложные projections без реального выигрыша.

16. Финальная граница ответственности

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

resource-catalog-service:
  source of truth for resources, topology, relationships, desired/observed state,
  capability definitions, provided capabilities

control-plane-service:
  source of truth for scenarios, intents, plans, operations, gates,
  interventions, PlanPatches, artifact/evidence metadata

execution-plane-service:
  source of truth for execution attempts, runner state, raw execution outputs

ai-ops-agent-service:
  analyzer/planner/reviewer, returns structured results,
  does not own operations and does not execute jobs by default

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

1. Должны ли CapabilityDefinition жить в resource-catalog или control-plane? Текущая рекомендация: resource-catalog, потому что это онтология ресурсов.
2. Какой транспорт выбрать для internal API execution-plane: gRPC, HTTP, Temporal activities wrapper или гибрид?
3. Какой уровень isolation нужен runners: process, container, Kubernetes Job, Firecracker-like sandbox?
4. Какой формат scenario packs выбрать: YAML directory, OCI artifact, Git repository, database records?
5. Как синхронизировать versions scenario packs с уже запущенными operations?
6. Какую policy technology выбрать под adapter: OPA/Rego, Cedar, custom rules или гибрид?
7. Какие ограничения заложить в workflow-engine adapter, чтобы Temporal оставался runtime, а не доменной моделью?
8. Какой минимальный read model нужен для GitLab-like отображения operation history без тяжелых runtime queries?

18. Ссылки по workflow/orchestration engine

• Temporal documentation
• Cadence Workflow
• Conductor OSS
• Argo Workflows documentation
• Camunda 8 Zeebe documentation
• Kestra documentation
• Apache Airflow documentation
• Prefect documentation
• Restate documentation
• DBOS Transact