docs: baseline specification-only repository stewardship
This commit is contained in:
@@ -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.
|
||||
Reference in New Issue
Block a user