Service Catalog на Backstage: автоматизация и внедрение

Отметим: когда в компании работает больше 20 сервисов, начинается тихая катастрофа: никто не знает владельца микросервиса, где его документация, с какими сервисами он связан и в каком состоянии деплой. Новый разработчик тратит первую неделю на то, чтобы просто понять, что задеплоено в кластере. Мы внедряем Service Catalog, чтобы остановить этот хаос. Наш опыт показывает: за 1–2 недели можно получить работающий каталог, который окупается за счёт снижения времени на инциденты на 30% и ускорения адаптации новичков до 2 дней. Экономия от внедрения достигает десятков тысяч долларов в год.

Service Catalog — это реестр всех внутренних сервисов, компонентов, API, библиотек и команд с машиночитаемыми метаданными и живыми данными о состоянии. Вместо хранения схемы кластера в головах инженеров вы получаете единую точку правды, которая обновляется автоматически. Мы используем Backstage — единственный зрелый open-source вариант для enterprise service catalog, активно поддерживаемый CNCF.

Почему без каталога наступает кризис?

В компаниях без каталога знание об инфраструктуре распределено хаотично: кто-то помнит про сервис X, потому что написал его три года назад. Кто-то знает, что в production используется специфичная версия библиотеки, потому что участвовал в инциденте. Новый DevOps-инженер не может ответить на вопрос «сколько сервисов использует Redis?» без ручного grep по репозиториям. При инциденте это становится критично: payments-service упал, нужно определить on-call, зависимости и runbook. Без единого реестра время реакции растёт — люди в панике пингуют коллег в Slack. Наш Service Catalog сокращает это время до нескольких кликов.

Как Backstage решает проблему «знания в головах»?

Backstage написан на TypeScript, имеет огромный plugin ecosystem и разворачивается в 5 раз быстрее самодельных решений. Центральная сущность — catalog-info.yaml рядом с кодом сервиса. Backstage сканирует репозитории и строит граф зависимостей из этих файлов:

Backstage читает этот файл, регистрирует сервис и автоматически строит dependency graph. На странице order-service видно: владелец, on-call, статус Kubernetes (pods running/failed), последние коммиты из GitLab, Grafana dashboard, документация.

Что мы реально строим в каталоге?

Инвентаризация компонентов. Каждый сервис, библиотека, база данных, очередь — всё становится сущностью с типом (service, library, database, queue, api). Для существующих репозиториев используем Backstage entity providers — GitHub Discovery, GitLab Discovery автоматически сканируют группы и создают записи.

Граф зависимостей. Backstage строит визуальный dependency graph на основе dependsOn и consumesApis/providesApis. Это первый инструмент, показывающий blast radius: если упадёт inventory-service, какие сервисы пострадают.

Ownership и команды. Backstage поддерживает Group и User entities, синхронизируется из LDAP, Okta, GitHub Teams. Каждый компонент имеет owner — команду или инженера. При инциденте сразу видно, кто отвечает.

API catalog. Для REST API — OpenAPI spec прямо в Backstage с UI для просмотра. Разработчики находят нужные API без хождения по конфлюенсу. Backstage поддерживает OpenAPI, AsyncAPI (для Kafka/event-driven), GraphQL schema.

apiVersion: backstage.io/v1alpha1
kind: API
metadata:
  name: order-api-v2
  description: REST API для управления заказами
spec:
  type: openapi
  lifecycle: production
  owner: group:order-team
  definition:
    $text: https://gitlab.company.com/backend/order-service/-/raw/main/openapi.yaml

TechDocs: документация рядом с кодом

Backstage TechDocs — MkDocs, встроенный в каталог. Разработчик пишет docs/ рядом с кодом, Backstage рендерит их на странице компонента. Документация версионируется вместе с кодом и всегда актуальна.

# mkdocs.yml в корне репозитория
site_name: Order Service
nav:
  - Обзор: index.md
  - Архитектура: architecture.md
  - API: api.md
  - Runbook: runbook.md
  - ADR: adr/

Это решает проблему устаревшей документации в Confluence: если код изменился — разработчик меняет docs в том же PR.

Пошаговый план внедрения Service Catalog

Мы выполняем работы в несколько этапов, гарантируя результат уже через неделю:

1. Установка и интеграция. Настраиваем Backstage, аутентификацию (Okta/GitHub SSO), подключаем GitLab/GitHub для автоматического сканирования репозиториев. Первая неделя.
2. Ключевые плагины. Добавляем Kubernetes (статус pod'ов), Grafana (dashboards), PagerDuty (on-call). Команда получает немедленную ценность. Вторая неделя.
3. Заселение каталога. Добавляем catalog-info.yaml в существующие репозитории. Создаём Group и User entities. Описываем dependency graph, заводим API entities. Третья–четвёртая неделя.
4. CI-валидация. В пайплайне проверяем catalog-info.yaml через Backstage CLI — если файл невалиден, PR не мёрджится. Это предотвращает деградацию каталога.

---
# .gitlab-ci.yml — валидация catalog-info.yaml
validate-catalog:
  image: node:18
  script:
    - npx @backstage/cli catalog validate --config catalog-info.yaml
  only:
    changes:
      - catalog-info.yaml

Что входит в работу?

• Развёртывание Backstage на kubernetes (Helm-чарт) с резервированием.
• Интеграция с GitLab/ GitHub, PagerDuty, Grafana, Prometheus.
• Создание шаблонов catalog-info.yaml и ADR-документации.
• Обучение команды (1–2 воркшопа) и написание runbook'а.
• Поддержка на этапе заселения: помощь в заполнении метаданных.

Сравнение решений: Backstage vs самодельный каталог

Backstage опережает самодельные решения по скорости внедрения в 5 раз и имеет готовую экосистему для управления API, документацией и зависимостями.

Почему каталог деградирует и как это предотвратить?

Без двух вещей Service Catalog превращается в «кладбище YAML»: владелец платформы, следящий за актуальностью, и требование регистрировать новые сервисы перед деплоем. Мы встраиваем quality gate в CI: если компонент не зарегистрирован в Backstage — деплой в staging блокируется. Жёстко, но эффективно. Дополнительно мы настраиваем автоматические проверки на outdated metadata и запускаем регулярный аудит.

Более 5 лет мы внедряем DevOps-решения, выполнили 50+ проектов по управлению инфраструктурой. Наши сертифицированные инженеры гарантируют, что каталог будет живым инструментом, а не статической витриной. Свяжитесь с нами, чтобы получить консультацию по внедрению каталога. Оценим ваш проект за 1 день — просто укажите количество сервисов и текущие инструменты, и мы предложим план внедрения.