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

41 KiB
Raw Permalink Blame History

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 без транспорта»:

  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, 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:

  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.

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.

  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.
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.

Есть два подварианта:

  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

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.