MLOps Pathmlopspath.ru

01 · Процессы и командная работа1.1 · Онбординг в компанию1.1.4лёгкий

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.

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