145 lines
11 KiB
Markdown
145 lines
11 KiB
Markdown
---
|
||
name: admin-runbooks
|
||
author: ours
|
||
version: 1.0.0
|
||
description: >
|
||
Единый контур ранбуков зоны админа (.admin): НАЙТИ нужный ранбук перед любой
|
||
прод-операцией → ИСПОЛНИТЬ по нему (чек-лист + verify + откат + письмо/таска) →
|
||
ВЕСТИ (обновлять после инцидентов/изменений) и СОЗДАВАТЬ новые. Поглощает
|
||
writing-runbooks (v1.0.0, superseded) — секция WRITE это его канон.
|
||
Trigger (user): деплой/редеплой/рестарт/ротация/миграция любого сайта или стека;
|
||
«по ранбуку», «как деплоить X», «напиши/обнови ранбук», «есть ли ранбук по X»;
|
||
любой прод-инцидент на сайте, который может потребовать операции.
|
||
---
|
||
|
||
# admin-runbooks
|
||
|
||
Один контур: **индекс → USE → EXECUTE → WRITE/UPDATE**. Цель — устранить
|
||
«рыскание» (поиск рецепта по сессиям/чатам/grep), когда ранбук есть или должен быть.
|
||
|
||
> ⚠️ **СЛУЖЕБНАЯ зона `.admin`.** Ранбуки — служебные документы `.admin`:
|
||
> применять/выполнять может только `.admin`; другие проекты читают по запросу,
|
||
> не выполняют; наружу не выносить. Прод-операция по ранбуку = таска на борде
|
||
> `.admin` + письмо от заказчика (исполнитель-не-админ не деплоит сам).
|
||
|
||
## 0. ИНДЕКС РАНБУКОВ (всегда первый шаг)
|
||
|
||
**Индекс:** `.admin/.wiki/concepts/runbooks-index.md` (единственный источник
|
||
«какой ранбук для чего»). **Прибит в AGENTS.md** — контур обязателен.
|
||
|
||
Перед ЛЮБОЙ прод-операцией (деплой/редеплой/рестарт/ротация/миграция/инцидент):
|
||
|
||
1. **Прочитай индекс** (`read .admin/.wiki/concepts/runbooks-index.md`) — найди
|
||
строку по проекту/операции → путь ранбука.
|
||
2. Ранбук может жить в трёх местах (индекс указывает, где):
|
||
- `.admin/.wiki/concepts/*-runbook*.md` — канон для VDS-проектов;
|
||
- `<репо-проекта>/.wiki/concepts/docker-deploy.md` и т.п. — репо-вики проекта
|
||
(pilorama98.ru: `apps/web/.wiki/concepts/docker-deploy.md`);
|
||
- mappa wiki (`wiki_search`) — если индекса ещё нет, искать там.
|
||
3. **Нет ранбука → НЕ деплоить молча.** Создать (см. WRITE) до/вместе с операцией:
|
||
отдельной таской или в теле операционной таски (пункт «нужен ранбук»).
|
||
Это не бюрократия: отсутствие ранбука = повторное рыскание в следующий раз.
|
||
|
||
## 1. USE — найти и прочитать ранбук
|
||
|
||
- Сначала индекс → ранбук. Не начинать grep по сессиям/чатам — это анти-паттерн
|
||
(источник этой секции: инцидент 2026-08-26 pilonuxt — рыскал, ранбука не было).
|
||
- Прочитать ранбук **целиком** перед операцией (секреты — плейсхолдеры, реальные
|
||
значения — из pass по указателям; ранбук сам секретов не несёт).
|
||
- Сверить актуальность: теги/версии на проде могут обогнать ранбук (пример:
|
||
stostayer-web ранбук показывал 0.3.23, прод был 0.3.26 → тег брать с проде,
|
||
а ранбук потом обновить — WRITE). Если расхождение → пометить на апдейт.
|
||
|
||
## 2. EXECUTE — деплой/операция по ранбуку
|
||
|
||
Выполнять шаги ранбука как чек-лист, **не пропуская**:
|
||
|
||
1. **Предусловия** (auth: JWT/токены из pass; docker login; pull-ДО-рестарта;
|
||
.dockerignore/.yarnrc временные модификации — пометить на возврат).
|
||
2. **Шаги операции** — дословно по ранбуку, порядок важен (gotchas в ранбуке).
|
||
3. **Verify** по секции ранбука (страницы/эндпоинты/логи/uptime) — зелёный перед
|
||
закрытием. При красном — rollback-путь из ранбука, не импровизация.
|
||
4. **Фиксация результата:**
|
||
- sync source-of-truth compose (если менялся тег) → commit + push;
|
||
- письмо-отчёт заказчику (inbox_send, from `.admin`, с verify-таблицей);
|
||
- закрыть операционную таску (reason = что сделано + verify);
|
||
- при необходимости — обновить ранбук (WRITE): новый тег, новые gotchas.
|
||
|
||
Ограничения: одна попытка там, где ранбук велит одну (egress-баны, retry-штормы);
|
||
не отклоняться от ранбука без причины — отклонение фиксировать в письме.
|
||
|
||
## 3. WRITE / UPDATE — создание и ведение ранбуков
|
||
|
||
Канон (наследие writing-runbooks v1.0.0, поглощено):
|
||
|
||
### Жёсткие правила
|
||
|
||
1. **Ранбук — служебный документ `.admin`.** Применять может только `.admin`.
|
||
2. **Из проекта не выносить.** Не копировать в другие вики, не публиковать.
|
||
3. **Деплой = таска + письмо админу.** Любая прод-операция — по задаче на борде
|
||
`.admin` и письму. Исполнитель-не-админ ставит задачу, не деплоит сам.
|
||
4. **Служебный блок — в первых абзацах** (машиночитаемый маркер служебности):
|
||
|
||
```markdown
|
||
> **⚙️ СЛУЖЕБНЫЙ РАНБУК — только для администратора проекта `.admin`.**
|
||
> Применять/выполнять шаги может только **`.admin`** (оператор проекта admin). Другим проектам/агентам — читать по запросу, не выполнять.
|
||
> Из проекта не выносить: не копировать в другие вики, не пересказывать, не публиковать.
|
||
> Нужен деплой или прод-операция по этому ранбуку — **поставить задачу админу (`.admin`) и написать письмо**. Админ выполняет, остальные верифицируют.
|
||
```
|
||
|
||
Дословно, без перефразирования.
|
||
|
||
### Гигиена секретов (решение 5, write-тайм сканер mappa)
|
||
|
||
**В ранбуках никогда не бывает реальных секретов.** Только плейсхолдеры +
|
||
указатели на pass: `<из pass <path>/<FIELD>>`. Сканер блокирует запись (422)
|
||
на password/token/api_key/secret+значение ≥6 симв., AKIA…, JWT, ssh-ключи.
|
||
Обход плейсхолдером: значение <6 симв. (`'<...>'`), либо ключ-слово не латиницей,
|
||
либо разрыв `: ` коротким словом (`PASSWORD: см. pass (…)`). После записи —
|
||
проверить `admin_secret_scan` (0 хитов).
|
||
|
||
### Структура ранбука
|
||
|
||
1. Frontmatter: `title`, `type: concept`, `tags: [.., runbook]`, `related`, `updated`.
|
||
2. H1 + служебный блок (обязательно, дословно).
|
||
3. Scope (VDS, стек Portainer Id, endpointId, source-of-truth compose).
|
||
4. Артефакты (код/образ/стек/БД/эндпоинт; тег = как на проде).
|
||
5. Шаги операции (копируемые команды) + таблица «рестарт vs пересборка» если уместно.
|
||
6. Verify/smoke после операции.
|
||
7. Rollback-путь всегда.
|
||
8. Gotchas из практики (нумерованные, с датой).
|
||
|
||
### Ведение (UPDATE)
|
||
|
||
Обновлять ранбук когда:
|
||
- прод ушёл вперёд (новый тег/версия) — поправить инвентарь/таблицы;
|
||
- появилась новая gotcha (инцидент с неочевидной причиной);
|
||
- изменился канал деплоя (адреса/стек/порядок).
|
||
После правки: bump `updated:`, синхронизировать с индексом (что покрывает),
|
||
проверить secret_scan. Коммит отдельный от операционного («docs(runbook): …»).
|
||
|
||
## Порядок записи (мутации вики)
|
||
|
||
- **Ранбук ОБЯЗАН быть в mappa как wiki-сущность, не только файлом** (2026-08-28, инцидент
|
||
skills-catalog-deploy: записал только файл → ранбук невидим через wiki_search, оператор
|
||
вернул «в mappa нужно писать»). Двойная запись:
|
||
1. Файл в `.admin/.wiki/concepts/` (репо .admin, git) → commit → push (push свободно);
|
||
2. Wiki-сущность в mappa: `wiki_create(project=".admin", slug="concepts/<имя>")`
|
||
(или `wiki_update` при правках) — тело = содержимое файла. НЕ полагаться на
|
||
mappa-импорт: он может отставать/не покрывать `.admin`.
|
||
- Секрет-сканер: `mcp__mappa__admin_secret_scan` после записи — 0 hits.
|
||
|
||
## Место жительства этого скила
|
||
|
||
Скил лежит в `.admin/.agents/skills/admin-runbooks/SKILL.md` — проектные скилы
|
||
`.admin` (pi: `.agents/skills/` в cwd). НЕ дублировать в `~/.agents/skills/`
|
||
(глобальная установка, перезаписывается update-skills) и НЕ в общий skills-репо.
|
||
Обновление — правкой файла в проекте + commit/push (.admin).
|
||
|
||
## Связи
|
||
|
||
- `concepts/runbooks-index.md` — индекс ранбуков (обязательный первый шаг).
|
||
- `writing-skills` — RED-GREEN-REFACTOR для скилов (если править сам скил).
|
||
- `using-vds-ops` — диагностика контейнеров (read-only), не деплой.
|
||
- `project-discipline` — семвер/пуш-правила при правке версионируемых артефактов.
|