Files
repoctl/docs/research/infrastructure-operations-architecture-options.md

693 lines
41 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
---
documentId: infrastructure-operations-architecture-options
documentVersion: 0.1.0
status: research
normative: false
language: ru
---
# Единый контракт сервисов и инфраструктуры: три варианта архитектуры
**Дата исследования:** 2026-08-19
**Статус:** концепция, изменений в исследованных репозиториях и системах не выполнялось
**Рекомендация:** вариант 1 — федеративный GitOps-контракт с единым протоколом операций; затем, при необходимости, поверх него вариант 3 — MCP-интерфейс.
## 1. Короткий вывод
Здесь уже есть почти все строительные блоки нужной системы, но они реализованы локально и несовместимо:
- сервисные репозитории Antivirus и GuardPlus хорошо отделяют знание о продукте от способа его размещения;
- LXD уже имеет машинную базу знаний с `constraints`, `tooling`, `workflows` и исполняемый handler с `validate`, `audit`, `diff`, `pull`, `push --dry-run`;
- Monitoring уже разделяет read-only audit, проверку дрейфа KDB и безопасный provisioning;
- AD уже использует правильную модель «несколько источников истины, каждый отвечает за свою грань» и отдельную reconciliation-операцию;
- Network уже использует inventory, dry-run, diff и специализированные drivers;
- Docker уже имеет достаточно устойчивые соглашения для стеков, но почти не имеет машинного контракта уровня всего репозитория.
Главный вывод: не следует начинать с общего сервера, которому разрешён произвольный SSH. Сначала нужно стандартизировать **описание сущностей, отношений, требований и операций** в Git. Исполнение должно оставаться в доменных адаптерах LXD, Docker, AD, Network и Monitoring.
Получится «MCP без транспорта»:
1. каждый репозиторий публикует одинаково устроенный контракт;
2. общий `opsctl` умеет найти контракты, построить граф и вызвать объявленную операцию;
3. операции имеют единый жизненный цикл `inspect → validate → plan → apply → verify → reconcile/rollback`;
4. skills лишь объясняют агенту, какую операцию выбрать, и не дублируют изменчивые факты;
5. позже тот же registry операций можно без переделки handlers опубликовать как настоящий MCP server.
## 2. Что было исследовано
### 2.1. Локальные репозитории
Проверены структура, управляющие документы, KDB, скрипты, skills и перекрёстные ссылки в:
- `Infra/Docker`;
- `Infra/LXD`;
- `Infra/AD`;
- `Infra/Network`;
- `Infra/Server-Hardware`;
- `Services/Antivirus`;
- `Services/GuardPlus`;
- `Services/Monitoring`;
- обзорно — остальные прямые подпапки `Infra/` и `Services/`.
В 14 прямых репозиториях/каталогах под `Infra/` и `Services/` соглашения распределены неравномерно: только 3 имеют корневой `AGENTS.md`, 4 — корневую или каталожную KDB, 4 — repo-local skills. Даже имя и положение базы знаний расходятся: `LXD/kdb.yaml`, `Antivirus/kdb/kdb.yaml`, набор отдельных файлов в `AD/kdb/` и `Monitoring/kdb/`.
### 2.2. Read-only SSH-проверка
Проверка выполнялась без копирования файлов, изменения конфигураций, рестартов и других записей.
- `cloud1`: Ubuntu 24.04.4 LTS, оба члена LXD-кластера ONLINE, предупреждений нет, ZFS-пулы healthy;
- LXD live inventory: 35 инстансов и новый проект `drweb`; документация от 2026-08-18 ещё содержит 34 инстанса и 9 проектов;
- `docker-manager0`: 6 Swarm-узлов Ready/Active, live-лидер — `docker-manager1`, 53 сервиса в 17 стеках;
- `dc01`: Debian 10, 26 GPO.
Эти расхождения не являются признаком плохой документации. Они показывают, что live-состояние по природе изменчиво и не должно копироваться в несколько README, skills и снимков без явной provenance и срока актуальности.
### 2.3. Внешние первичные источники
- MCP задаёт JSON-RPC base protocol, capability negotiation и раздельные server features: resources, prompts и tools. Для tools предусмотрены input/output schemas, структурированный результат, ошибки исполнения и подтверждение чувствительных операций клиентом: [MCP specification — Overview](https://modelcontextprotocol.io/specification/2025-11-25/basic), [MCP specification — Tools](https://modelcontextprotocol.io/specification/2025-11-25/server/tools).
- Backstage показывает полезный, но более тяжёлый паттерн: YAML-descriptor хранится рядом с кодом, центральный каталог его агрегирует, а сам каталог не считается первоисточником. Отдельные сущности и relations формируют граф: [Software Catalog](https://backstage.io/docs/features/software-catalog/), [Creating the Catalog Graph](https://backstage.io/docs/features/software-catalog/creating-the-catalog-graph/), [Descriptor Format](https://backstage.io/docs/features/software-catalog/descriptor-format/).
## 3. Наблюдения, которые определяют архитектуру
### 3.1. Граница ответственности уже найдена
GuardPlus формулирует её особенно удачно:
- чтобы **поднять контейнер** — артефакт принадлежит LXD;
- чтобы **понять или наполнить СКУД** — артефакт принадлежит GuardPlus.
Antivirus следует тому же принципу:
- продуктовые факты, проверенные пути, принятие сервиса и rollout — в `Services/Antivirus`;
- LXD profiles — в `Infra/LXD`;
- IP/DNS/firewall — в `Infra/Network`;
- proxy stack — в `Infra/Docker`;
- rollout Windows agent — в `Infra/AD`;
- наблюдаемость должна связываться с `Services/Monitoring`.
Эту границу не надо размывать общим монорепозиторием. Надо сделать её машинно-читаемой.
### 3.2. Единственной «истины обо всём» быть не должно
Для одного объекта существуют разные авторитетные грани:
| Грань | Кто владеет | Пример |
|---|---|---|
| Назначение и продуктовые требования | service repo | Antivirus знает порты DWCP, лицензию и правильный health probe |
| Желаемая инфраструктурная конфигурация | infra repo | LXD владеет profiles, Docker — stack spec, AD — GPO |
| Фактическое состояние | runtime API/CLI | `lxc list`, Docker API, Samba/UDM, Zabbix API |
| Исторический снимок | dated report | `reports/*-YYYY-MM-DD.md`, `instances.yaml` |
| Проверенные особенности продукта | KDB | provenance `VERIFIED/MANUAL/DRAFT/STALE` |
| Связь requirement → implementation | consumer + provider binding | Antivirus требует instance; LXD фиксирует, чем требование выполнено |
Центральный каталог может агрегировать эти грани, но не должен становиться ещё одним местом ручного редактирования тех же фактов.
### 3.3. Повторяющийся протокол операций уже сложился
Реальные handlers используют почти одинаковые понятия:
| Домен | Уже существующие операции |
|---|---|
| LXD | `list`, `pull`, `validate`, `audit`, `diff`, `push --dry-run`, `push` |
| Monitoring | read-only `audit --json`, KDB `validate/stale/drift`, provisioning `check/plan/apply/prune` |
| Network | inventory, discover, `check --diff`, `apply --dry-run`, `apply`, status |
| Docker | compose validation, stack deploy, service/stack inspection |
| AD | backup, apply via управляющий слой, reconciliation AD × audit × Fleet × assets |
Нужно унифицировать **семантику**, но не заменять эти handlers одним универсальным shell runner.
### 3.4. Skills не могут быть источником изменчивых фактов
В LXD одновременно отслеживаются `.agents/skills/lxd-profiles` и `.claude/skills/lxd-profiles`. Они уже различаются:
- старый handler: около 12.6 КБ;
- актуальный handler: около 29.9 КБ;
- актуальная версия добавила `audit`, JSON output, secret placeholders и cloud-init replay guard;
- обе копии отслеживаются Git и имеют разные SHA-256.
Это не косметический drift: агент, выбравший старую копию, получает менее безопасное поведение. Аналогично длинный Docker agent содержит снимочные сведения о topology, а `CLUSTER_STATE.md` уже отстал от live-лидера.
Следствие: skill должен быть тонким UX-слоем, а исполняемый код, constraints и registry операций — иметь ровно одну каноническую копию.
### 3.5. Cross-repo транзакции невозможны, но возможен проверяемый план
Добавление сервиса часто меняет LXD, Network, Docker, AD и Monitoring. Git и эти runtime не поддерживают общую транзакцию. Поэтому правильная единица работы — не «одна атомарная команда», а **неизменяемый план с checkpoints**:
1. зафиксировать revisions входных репозиториев и live snapshots;
2. построить план и dependency order;
3. применить один provider change;
4. выполнить provider verification;
5. выполнить service acceptance;
6. только затем перейти к следующему шагу;
7. хранить run evidence и явно указывать, где rollback невозможен.
## 4. Общая модель, одинаковая для всех трёх вариантов
### 4.1. Минимальный шаблон репозитория
Не нужно немедленно переносить существующие `profiles-source/`, Docker stack folders или `endpoint-management/`. Контракт декларирует их как domain-native paths.
```text
repo/
├── README.md # вход для человека, без дублирования live-снимков
├── AGENTS.md # короткий pointer: прочитать ops/contract + constraints
├── ops/
│ ├── contract.yaml # канонический repo/service/infra contract
│ ├── handlers/ # исполняемая реализация операций
│ ├── schemas/ # repo-specific input/output schemas при необходимости
│ ├── templates/ # scaffolds новых компонентов/ресурсов
│ └── tests/ # contract, safety и handler tests
├── kdb/
│ ├── index.yaml # навигация, provenance и routing вопросов
│ └── *.yaml # проверенные факты и ограничения по подсистемам
├── docs/
│ ├── architecture/ # живые объяснения и ADR
│ ├── runbooks/ # процедуры и rollback
│ └── reports/ # датированные, неизменяемые snapshots/evidence
├── <domain-native paths>/ # profiles-source, stacks, endpoint-management и т. п.
├── .agents/skills/ # тонкие adapters для агента; без handlers и live facts
└── .secrets.example # только схема/имена, без значений
```
Для постепенного внедрения допустимо оставить текущую KDB на месте и указать её через `spec.knowledge.entrypoint`. Стандартизировать путь можно позже; семантика важнее миграции каталогов.
### 4.2. Контракт репозитория
Пример намеренно сокращён. Реальная схема должна валидироваться JSON Schema и иметь versioning.
```yaml
apiVersion: ops.corsus.pro/v1alpha1
kind: RepositoryContract
metadata:
name: antivirus
repo: Services/Antivirus
class: service # service | infrastructure | platform | data
lifecycle: production
owners: [corsus-it]
spec:
authority:
owns:
- product.requirements
- product.knowledge
- service.acceptance
doesNotOwn:
- lxd.profile
- network.ipam
- docker.stack
- ad.gpo
knowledge:
entrypoint: kdb/kdb.yaml
provenance: [VERIFIED, MANUAL, DRAFT, STALE]
requires:
- id: ess-compute
capability: compute.lxd.instance
constraints:
environment: production
placement: cloud1
- id: ess-address
capability: network.static-address
- id: ess-dns
capability: network.dns-record
- id: windows-rollout
capability: identity.software-rollout
- id: service-monitoring
capability: observability.service
provides:
- id: drweb-control-plane
capability: antivirus.endpoint-control
operations:
- id: service.inspect
summary: Read deployed state without trusting the SysV-generated systemd status
effect: read
risk: low
handler: ops/handlers/service.py
args: [inspect]
outputSchema: ops/schemas/service-state.json
- id: service.accept
summary: Verify process, listeners, API and licence after an infrastructure change
effect: read
risk: low
handler: ops/handlers/service.py
args: [accept]
outputSchema: ops/schemas/acceptance-result.json
secrets:
policy: references-only
allowedRefs: [repo-local-env, runtime-secret]
```
Provider repo публикует capabilities и bindings, а не копирует требования сервиса:
```yaml
spec:
provides:
- capability: compute.lxd.instance
bindings:
- id: drweb-ess-lxd
fulfills: repo:Services/Antivirus#requirement/ess-compute
implementation:
project: drweb
instance: drweb-ess
profiles: [default, drweb-base, drweb-server]
desiredStatePaths:
- projects/drweb/
- profiles-source/drweb-base.yaml
- profiles-source/drweb-server.yaml
inspectOperation: lxd.instance.inspect
```
Правило владения связью:
- consumer владеет `requires` и acceptance criteria;
- provider владеет `bindings` и инфраструктурной реализацией;
- агрегатор строит relation только если обе стороны совместимы;
- unresolved requirement и orphan binding являются диагностируемым drift.
### 4.3. Унифицированный жизненный цикл операций
| Фаза | Семантика | Разрешённый эффект |
|---|---|---|
| `describe` | показать контракт, capabilities, constraints, schemas | read |
| `inspect` | получить live state из авторитетного API/CLI | read |
| `snapshot` | записать датированное evidence | local-write |
| `validate` | проверить source, schema, policy и preconditions | read/local temp |
| `diff` | сравнить desired ↔ live ↔ last verified | read |
| `plan` | построить точный change set и verification plan | read/local artifact |
| `apply` | применить ровно сохранённый plan | external-write |
| `verify` | platform checks + service acceptance | read |
| `reconcile` | классифицировать drift и предложить направление исправления | read; apply отдельно |
| `rollback` | восстановить snapshot или выполнить compensating action | external-write/disruptive |
Не каждый домен обязан поддерживать все verbs. Неподдерживаемая операция объявляется явно, как сейчас в LXD объявлены out-of-scope instance lifecycle и project management.
### 4.4. Обязательные поля операции
Каждая исполняемая операция должна объявлять:
- стабильный `id` и краткое назначение;
- input/output JSON Schema;
- `effect`: `read`, `local-write`, `external-write`, `disruptive`, `destructive`;
- `risk`: `low`, `medium`, `high`, `critical`;
- target selector и границы допустимого scope;
- credential references без значений;
- preconditions;
- поддержку `dryRun` и idempotency, если она реальна;
- `mutates`: какие repo paths и runtime objects могут измениться;
- confirmation policy;
- verification operation;
- rollback/compensation или явное `rollback: unavailable`;
- timeout и exit-code semantics;
- redaction policy;
- evidence, которое записывается после запуска.
Нельзя объявлять произвольную shell-строку как публичную операцию. Registry должен ссылаться на allowlisted handler и argv; handler сам ограничивает команды и targets.
### 4.5. Формат plan и run evidence
`plan` должен быть самостоятельным артефактом, например `ops-plan.json`:
```json
{
"apiVersion": "ops.corsus.pro/v1alpha1",
"operation": "lxd.instance.migrate",
"createdAt": "2026-08-19T12:00:00Z",
"inputsHash": "sha256:...",
"repoRevisions": {
"Infra/LXD": "<git-sha>",
"Services/Antivirus": "<git-sha>"
},
"liveSnapshotHash": "sha256:...",
"targets": ["lxd:drweb/drweb-ess"],
"steps": [],
"verification": [],
"rollback": {},
"risk": "high"
}
```
`apply` принимает plan hash и отказывается работать, если revisions, targets или критичные live preconditions изменились. Это защищает от применения старого dry-run к уже изменившейся среде.
### 4.6. Базовый набор skills
Skills должны быть короткими orchestrators, а не вторыми README или копиями Python handlers.
| Skill | Задача |
|---|---|
| `ops-discover` | найти contracts под `~/Git`, построить catalog и relation graph |
| `ops-repo-onboard` | проверить/сгенерировать минимальный contract для существующего repo |
| `ops-change-plan` | разрешить requirements к providers и построить cross-repo plan |
| `ops-drift-audit` | вызвать domain inspect/diff и классифицировать drift |
| `ops-safe-apply` | проверить plan hash, approval и вызвать domain apply |
| `ops-verify` | собрать provider verification и service acceptance |
| `ops-reconcile` | найти unresolved requirements, orphan bindings, stale facts и snapshots |
| `ops-incident-snapshot` | read-only evidence из нескольких providers с redaction |
| `ops-service-integrate` | сценарий «новый компонент сервиса → инфраструктурные bindings» |
| `ops-workload-migrate` | сценарий «инфраструктурное перемещение → service-aware plan» |
Domain skills остаются, но становятся adapters:
- `lxd-ops`;
- `swarm-ops`;
- `ad-ops`;
- `network-ops`;
- `monitoring-ops`;
- `hardware-ops`.
Каждый такой skill обязан сначала читать `ops/contract.yaml` и KDB constraints, затем вызывать канонический handler. Hostnames, current leaders, instance counts и версии в skill не помещаются.
### 4.7. Два ключевых сценария
#### Сервис добавляет компонент
Пример: Antivirus добавляет proxy и rollout endpoints.
1. Service repo добавляет/уточняет requirements и acceptance criteria.
2. `ops-change-plan` находит providers:
- LXD — server instance;
- Docker — proxy на NAS02;
- Network — route/IP/DNS/firewall;
- AD — Windows rollout;
- Monitoring — service checks.
3. Каждый provider возвращает свой `validate/diff/plan`.
4. Общий plan строит dependency order, но не склеивает changes в одну непрозрачную команду.
5. После каждого apply выполняется provider verify.
6. В конце Antivirus выполняет end-to-end acceptance.
7. Providers записывают bindings; service repo не копирует их конфигурацию.
#### Инфраструктура переносит сервисы на новые хосты
1. LXD выбирает candidate instances и публикует proposed placement plan.
2. Catalog находит связанные service contracts и их требования: downtime, backup, affinity, address stability, health/acceptance operations.
3. Capacity/placement validation выполняется инфраструктурой; service impact validation — сервисом.
4. Миграция идёт batch-ами с checkpoints.
5. После platform verification выполняются service acceptance и monitoring verification.
6. Binding обновляется только после успешной проверки; старый host остаётся в evidence, а не в актуальном contract.
```mermaid
flowchart LR
S[Service requires + acceptance] --> C[Catalog / relation graph]
I[Infrastructure capabilities + bindings] --> C
C --> P[Immutable cross-repo plan]
P --> L[LXD adapter]
P --> D[Docker adapter]
P --> N[Network adapter]
P --> A[AD adapter]
P --> M[Monitoring adapter]
L --> V[Provider verification]
D --> V
N --> V
A --> V
M --> V
V --> E[Service end-to-end acceptance]
```
## 5. Вариант 1 — федеративный GitOps-контракт + общий CLI
**Рейтинг: 9.2/10 — рекомендуемый первый этап и основная архитектура.**
### Суть
Каждый repo хранит `ops/contract.yaml`, свои handlers и свои authoritative artifacts. Небольшой общий `opsctl` сканирует `~/Git/Infra` и `~/Git/Services`, валидирует contracts, строит relation graph и вызывает repo-local operations.
Центрального постоянно работающего сервера нет. Catalog — производный локальный JSON/SQLite cache, который всегда можно перестроить из Git.
Пример UX:
```text
opsctl catalog build ~/Git/Infra ~/Git/Services
opsctl entity show service:antivirus
opsctl operations list --entity service:antivirus
opsctl plan service.integrate --service antivirus --component drweb-proxy
opsctl apply --plan .ops/runs/<id>/plan.json --confirm "APPLY <id>"
opsctl verify --run <id>
opsctl reconcile --all
```
### Сильные стороны
- совпадает с текущей границей ответственности repo;
- не требует переносить domain-native конфигурацию;
- минимальная blast radius: handler работает только в своём домене;
- Git остаётся источником desired state и review trail;
- можно внедрять по одному repo;
- работает без отдельной платформы, БД, OAuth и высокой доступности;
- создаёт правильный фундамент для будущего MCP;
- легче всего автоматизировать CI-проверки contracts, duplicate skills и stale facts.
### Слабые стороны
- первый catalog/graph будет CLI, без красивого портала;
- cross-repo plan требует дисциплины versioning и стабильных IDs;
- локальный запуск зависит от доступности нескольких repos и credentials;
- нужно поддержать Windows и Linux execution paths.
### Как устроены skills
- общий набор orchestration skills устанавливается один раз;
- domain skills остаются рядом с repo;
- handlers лежат только в `ops/handlers`, а `.agents/skills` содержит инструкции и ссылки;
- если нужна совместимость `.agents` и `.claude`, wrapper-файлы генерируются из одного template, а CI сравнивает их hash/semantic version.
### Когда выбирать
Сейчас. Это наименьшее изменение, которое решает реальные проблемы ownership, drift, discoverability и безопасного исполнения.
## 6. Вариант 2 — центральный Ops Catalog / Ops Hub
**Рейтинг: 7.4/10 — полезен для обзора, слабее как первичный control plane.**
### Суть
Создаётся отдельный repo, например `Ops/Catalog`, содержащий registry всех entities, operations, templates и связей. В более полном виде рядом разворачивается web UI по модели Backstage-lite.
Есть два подварианта:
1. центральные descriptor files редактируются вручную;
2. рекомендуемый — repo-local contracts остаются первоисточниками, а hub только harvest/cache/UI.
Только второй подвариант приемлем: официальный Backstage также рекомендует считать Git descriptor files первоисточником, а catalog — агрегатором.
### Сильные стороны
- лучший обзор ownership, lifecycle, dependencies и незакрытых требований;
- удобная точка входа для людей;
- templates и onboarding новых repos можно сделать через формы;
- проще строить отчёты: orphan services, stale verification, неподключённый monitoring;
- хорошо масштабируется, если репозиториев станет много.
### Слабые стороны
- отдельный сервис, БД, auth, backup и upgrade lifecycle;
- соблазн начать редактировать runtime facts в каталоге и получить ещё один источник drift;
- центральная команда/схема становится bottleneck;
- custom actions с правом SSH/API резко увеличивают blast radius;
- для текущих 14 прямых repos полноценный Backstage, вероятно, преждевременен.
### Как устроены skills
- skills сначала спрашивают catalog API о relations и operation endpoints;
- исполнение всё равно делегируется domain adapters;
- hub не получает универсального `run_shell`;
- templates создают merge requests в owning repos, а не меняют live напрямую.
### Когда выбирать
После варианта 1, если CLI-каталог перестанет удовлетворять людей или появится необходимость в self-service portal. Как замена repo-local contracts этот вариант не рекомендуется.
## 7. Вариант 3 — полноценный Ops MCP control plane
**Рейтинг сейчас: 6.8/10. Потенциал после варианта 1: 9.0/10.**
### Суть
Registry операций публикуется через настоящий MCP server:
- **resources**: entities, contracts, KDB sections, plans, run evidence, live read-only snapshots;
- **tools**: `catalog.search`, `entity.describe`, `operation.plan`, `operation.apply`, `operation.verify`, `drift.inspect`;
- **prompts**: типовые сценарии onboarding, migration, incident triage;
- tool schemas автоматически выводятся из того же contract schema.
MCP является транспортом и discovery layer, но не заменяет GitOps, domain handlers и safety policy.
### Сильные стороны
- естественный discovery операций для Codex/Claude и других клиентов;
- строгие schemas вместо разбора текстового CLI output;
- единый structured result и actionable tool errors;
- можно централизовать audit events, rate limits и policy checks;
- удобно подключать уже существующие Grafana/Prometheus MCP servers как read-only providers;
- отличный long-term интерфейс поверх стабильного operation registry.
### Слабые стороны
- высокий начальный объём: server, authorization, scopes, audit, secrets broker, availability;
- опасно публиковать write-tools до формализации effects, plan hashes и approvals;
- MCP tool annotations нельзя считать достаточной защитой: сервер обязан валидировать input и access сам;
- один компрометированный control plane может получить доступ сразу к LXD, Docker, AD и Network;
- без варианта 1 MCP server быстро превратится в набор hand-written tools с разными semantics;
- transport/API versioning добавится к contract и handler versioning.
### Рекомендуемые scopes
```text
catalog:read
state:read
plan:create
evidence:write
lxd:apply
docker:apply
network:apply
ad:apply
monitoring:apply
destructive:approve
```
Write scopes должны быть domain-specific. Нельзя выдавать один общий `infra:write`. Credentials downstream-систем не должны передаваться MCP client: server использует отдельные audience-bound credentials для каждого provider.
### Как устроены skills
Skills становятся в основном routing/policy инструкциями:
- какие resources сначала прочитать;
- когда разрешён только `plan`;
- какой confirmation нужен;
- как объединить provider verification с service acceptance.
Вся фактическая schema операции и её execution остаются на server/handler side.
### Когда выбирать
После того как минимум LXD, Docker, Network, AD и один service repo реализовали вариант 1 и показали одинаковые semantics на реальных сценариях. Начинать сразу с write-capable MCP не рекомендуется; допустим ранний read-only MCP для catalog/search/inspect.
## 8. Сравнение вариантов
Вес критериев отражает текущую ситуацию: безопасность и устойчивость к drift важнее UI.
| Критерий | Вес | Вариант 1: federated CLI | Вариант 2: Ops Hub | Вариант 3: MCP сейчас |
|---|---:|---:|---:|---:|
| Соответствие существующим repos и ownership | 25% | 9.5 | 7.5 | 8.0 |
| Безопасность исполнения | 25% | 9.5 | 7.5 | 5.5 |
| Устойчивость к drift | 20% | 9.5 | 6.5 | 7.0 |
| Стоимость запуска | 15% | 8.5 | 6.5 | 4.5 |
| Расширяемость и discoverability | 15% | 8.5 | 9.0 | 10.0 |
| **Итог** | **100%** | **9.2/10** | **7.4/10** | **6.8/10** |
MCP получает 9.0/10 как следующий слой после варианта 1, потому что к тому времени самые сложные части — ownership, schemas, effects, handlers и safety — уже проверены независимо от транспорта.
## 9. Рекомендуемая последовательность внедрения
### Фаза 0 — договориться о semantics
Зафиксировать один schema package:
- `RepositoryContract`;
- `Requirement`;
- `Capability`;
- `Binding`;
- `Operation`;
- `Plan`;
- `RunEvidence`.
Стабильные IDs важнее полноты первой версии. Начать с `v1alpha1`, не обещая обратную совместимость до двух пилотов.
### Фаза 1 — два вертикальных пилота
Пилот A, service-driven:
- `Services/Antivirus` как consumer;
- `Infra/LXD`, `Infra/Network`, `Infra/AD`, `Services/Monitoring` как providers;
- сценарий: описать уже работающий `drweb-ess`, обнаружить fulfilled и unresolved requirements, выполнить read-only acceptance.
Пилот B, infrastructure-driven:
- `Infra/LXD`;
- выбрать тестовый workload;
- построить migration plan с service-owned acceptance;
- apply пока не выполнять — проверить полноту plan, preconditions и rollback.
### Фаза 2 — канонические handlers и thin skills
- перенести LXD handler в единственное каноническое место;
- убрать код и volatile facts из skills;
- добавить одинаковый `--json` envelope и exit codes;
- покрыть safety self-tests;
- добавить CI-проверку, запрещающую drift между compatibility wrappers;
- адаптировать Monitoring audit/provisioning как эталон разделения read/write;
- формализовать Docker repository-level KDB и operations, не копируя stack facts в agent text.
### Фаза 3 — локальный catalog и reconciliation
- `opsctl catalog build`;
- graph requirements/bindings;
- `opsctl validate --all`;
- `opsctl reconcile --all`;
- отчёт по stale verified facts, unresolved requirements, orphan bindings и unsupported operations.
### Фаза 4 — только затем интерфейс
Выбор по фактической потребности:
- достаточно CLI — остаться на варианте 1;
- нужен human portal — добавить вариант 2 как derived UI;
- нужен agent/tool interoperability — добавить read-only MCP, затем строго scoped write-tools.
## 10. Что принципиально не делать
- Не создавать центральный YAML со всеми IP, hostnames, versions и counts вручную.
- Не считать snapshot desired state.
- Не помещать live topology в `SKILL.md` или `AGENTS.md`.
- Не дублировать один handler под `.agents` и `.claude` без generation/hash check.
- Не давать общему агенту произвольный SSH/shell как «универсальную операцию».
- Не считать `--dry-run` безопасным без измерения before/after, как уже правильно делает Monitoring.
- Не считать source автоматически правильнее live: LXD уже знает случаи intentional drift.
- Не выполнять cross-repo apply без сохранённого plan, revisions и checkpoints.
- Не требовать rollback там, где он физически невозможен; объявлять compensating action и остаточный риск.
- Не хранить secret values в contract, KDB, evidence или MCP result.
- Не делать catalog новым источником истины: это rebuildable projection.
## 11. Критерии готовности первой версии
Первая версия считается полезной, если выполняются все условия:
1. `opsctl` находит contracts минимум Antivirus, LXD, Network, AD и Monitoring.
2. Contract validation работает полностью offline.
3. Catalog показывает requirement `Antivirus → LXD` и соответствующий provider binding.
4. Read-only `inspect` выдаёт единый JSON envelope независимо от домена.
5. LXD и Monitoring поддерживают `validate/diff-or-drift/plan/verify` с одинаковой семантикой exit codes.
6. Ни один mutating handler не доступен без plan и явного approval.
7. Service acceptance живёт в service repo и вызывается после provider verification.
8. Stale snapshot не выглядит как current state: есть `observedAt`, provenance и probe reference.
9. Две agent ecosystems не могут незаметно получить разные handlers.
10. `reconcile` обнаруживает как минимум:
- unresolved requirement;
- orphan binding;
- stale verified fact;
- desired/live drift;
- отсутствующую verification operation.
## 12. Итоговое решение
Рекомендуемая архитектура — **вариант 1 как ядро, вариант 3 как будущий транспорт**.
Ключевая идея не в едином инструменте, который умеет всё, а в едином договоре о том:
- как repo сообщает, чем он владеет;
- что сервис требует от инфраструктуры;
- чем provider это требование выполнил;
- какие операции доступны;
- что операция читает и меняет;
- как строится план;
- как проверяется результат;
- где лежит rollback;
- откуда взят каждый факт и когда он был проверен.
После этого локальный CLI, портал и MCP становятся взаимозаменяемыми интерфейсами над одной моделью. Без этого любой «импровизированный MCP» лишь централизует текущую неоднородность и увеличит blast radius.