41 KiB
documentId, documentVersion, status, normative, language
| documentId | documentVersion | status | normative | language |
|---|---|---|---|---|
| infrastructure-operations-architecture-options | 0.1.0 | research | false | 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 без транспорта»:
- каждый репозиторий публикует одинаково устроенный контракт;
- общий
opsctlумеет найти контракты, построить граф и вызвать объявленную операцию; - операции имеют единый жизненный цикл
inspect → validate → plan → apply → verify → reconcile/rollback; - skills лишь объясняют агенту, какую операцию выбрать, и не дублируют изменчивые факты;
- позже тот же 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, MCP specification — Tools.
- Backstage показывает полезный, но более тяжёлый паттерн: YAML-descriptor хранится рядом с кодом, центральный каталог его агрегирует, а сам каталог не считается первоисточником. Отдельные сущности и relations формируют граф: Software Catalog, Creating the Catalog Graph, 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:
- зафиксировать revisions входных репозиториев и live snapshots;
- построить план и dependency order;
- применить один provider change;
- выполнить provider verification;
- выполнить service acceptance;
- только затем перейти к следующему шагу;
- хранить run evidence и явно указывать, где rollback невозможен.
4. Общая модель, одинаковая для всех трёх вариантов
4.1. Минимальный шаблон репозитория
Не нужно немедленно переносить существующие profiles-source/, Docker stack folders или endpoint-management/. Контракт декларирует их как domain-native paths.
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.
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, а не копирует требования сервиса:
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:
{
"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.
- Service repo добавляет/уточняет requirements и acceptance criteria.
ops-change-planнаходит providers:- LXD — server instance;
- Docker — proxy на NAS02;
- Network — route/IP/DNS/firewall;
- AD — Windows rollout;
- Monitoring — service checks.
- Каждый provider возвращает свой
validate/diff/plan. - Общий plan строит dependency order, но не склеивает changes в одну непрозрачную команду.
- После каждого apply выполняется provider verify.
- В конце Antivirus выполняет end-to-end acceptance.
- Providers записывают bindings; service repo не копирует их конфигурацию.
Инфраструктура переносит сервисы на новые хосты
- LXD выбирает candidate instances и публикует proposed placement plan.
- Catalog находит связанные service contracts и их требования: downtime, backup, affinity, address stability, health/acceptance operations.
- Capacity/placement validation выполняется инфраструктурой; service impact validation — сервисом.
- Миграция идёт batch-ами с checkpoints.
- После platform verification выполняются service acceptance и monitoring verification.
- Binding обновляется только после успешной проверки; старый host остаётся в evidence, а не в актуальном contract.
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:
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.
Есть два подварианта:
- центральные descriptor files редактируются вручную;
- рекомендуемый — 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
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;
- добавить одинаковый
--jsonenvelope и 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. Критерии готовности первой версии
Первая версия считается полезной, если выполняются все условия:
opsctlнаходит contracts минимум Antivirus, LXD, Network, AD и Monitoring.- Contract validation работает полностью offline.
- Catalog показывает requirement
Antivirus → LXDи соответствующий provider binding. - Read-only
inspectвыдаёт единый JSON envelope независимо от домена. - LXD и Monitoring поддерживают
validate/diff-or-drift/plan/verifyс одинаковой семантикой exit codes. - Ни один mutating handler не доступен без plan и явного approval.
- Service acceptance живёт в service repo и вызывается после provider verification.
- Stale snapshot не выглядит как current state: есть
observedAt, provenance и probe reference. - Две agent ecosystems не могут незаметно получить разные handlers.
reconcileобнаруживает как минимум:- unresolved requirement;
- orphan binding;
- stale verified fact;
- desired/live drift;
- отсутствующую verification operation.
12. Итоговое решение
Рекомендуемая архитектура — вариант 1 как ядро, вариант 3 как будущий транспорт.
Ключевая идея не в едином инструменте, который умеет всё, а в едином договоре о том:
- как repo сообщает, чем он владеет;
- что сервис требует от инфраструктуры;
- чем provider это требование выполнил;
- какие операции доступны;
- что операция читает и меняет;
- как строится план;
- как проверяется результат;
- где лежит rollback;
- откуда взят каждый факт и когда он был проверен.
После этого локальный CLI, портал и MCP становятся взаимозаменяемыми интерфейсами над одной моделью. Без этого любой «импровизированный MCP» лишь централизует текущую неоднородность и увеличит blast radius.