docs: baseline specification-only repository stewardship

This commit is contained in:
Alexander Baranov
2026-08-24 14:39:09 +03:00
commit 9a39b8a941
11 changed files with 4191 additions and 0 deletions
@@ -0,0 +1,692 @@
---
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.