1.1.4 · блок 1

Confluence: документация команды

Зачем это нужно

Код отвечает на вопрос *как* система работает сейчас. Но команда также должна знать *зачем* принято решение, *как* поднять сервис в 3 часа ночи и *кто* владелец компонента. Confluence — wiki-корпоративного уровня от Atlassian: место для документации, которая не помещается в комментарии к коду.

Если Jira — «что делаем сейчас», то Confluence — «что мы знаем о системе в целом». Без связки Jira ↔ Confluence теряется контекст: через полгода никто не вспомнит, почему выбрали batch-inference вместо online.

Основные идеи

Типы страниц, которые должен знать инженер:

Service Page (страница сервиса) — паспорт микросервиса или ML-компонента:

Назначение и владелец (owner + backup).
Репозиторий, ссылка на CI/CD.
Зависимости: базы, очереди, другие сервисы.
SLO: доступность, latency, error budget.
Контакты on-call.

Runbook (руководство по эксплуатации) — пошаговые инструкции для типовых и аварийных ситуаций:

Как проверить, что сервис жив (curl, Grafana dashboard).
Как перезапустить pod / systemd-unit.
Как откатить релиз.
Что делать при алерте «ModelLatencyHigh».

Runbook пишут так, чтобы дежурный инженер *без глубокого знания ML* мог стабилизировать сервис.

ADR (Architecture Decision Record) — короткая запись об архитектурном решении. Формат: контекст → решение → последствия. ADR хранят в Confluence или в репозитории (docs/adr/). Подробнее — в модуле 2.2.

Связь Jira ↔ Confluence:

В Story вставляют макрос «Ссылка на Confluence» — design doc, runbook.
На странице Confluence — макрос «Jira Issues» — список открытых задач по компоненту.
При закрытии Epic обновляют Service Page: новая версия API, изменившиеся зависимости.

Принцип «docs as part of DoD»: если вы выкатили фичу, но не обновили runbook — задача не Done.

Как это выглядит на практике

Страница «ML Scoring Service» в Confluence:


Owner: @ivanov (MLE), backup: @petrov (SRE)
Repo: gitlab.company.com/ml/scoring-service
Prod URL: https://scoring.internal/v1/predict
SLO: 99.5% availability, p95 < 200ms

Dependencies:
  - PostgreSQL (features store)
  - Redis (model cache)
  - S3 (model artifacts)

Runbook: [ссылка на дочернюю страницу]
ADR-003: Batch vs Online inference [ссылка]
Open Jira: [макрос JQL: component = scoring AND status != Done]

Runbook «Scoring Service — High Error Rate»:

1. Открыть Grafana dashboard «Scoring Overview».

2. Проверить kubectl get pods -n ml-scoring — все Running?

3. Если CrashLoopBackOff — посмотреть логи: kubectl logs -l app=scoring --tail=100.

4. Откат: helm rollback scoring 42.

5. Эскалация: #ml-oncall в Slack, создать Incident в Jira.

Story ML-89 в Jira содержит в описании: «Design: Confluence → ML Scoring / ADR-004 Feature Store Migration».

Что сделать после занятия

[ ] Создайте шаблон Service Page для учебного ML-сервиса (можно в Markdown локально).
[ ] Напишите runbook на 1 страницу: «сервис не отвечает» — минимум 5 шагов с командами.
[ ] Опишите, какие 3 ссылки из Jira-ticket вы бы добавили на Confluence.

Официальные материалы

Открыть интерактивную версию