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

Зазначимо: коли в компанії працює більше 20 сервісів, починається тиха катастрофа: ніхто не знає власника мікросервісу, де його документація, з якими сервісами він пов'язаний і в якому стані деплой. Новий розробник витрачає перший тиждень на те, щоб просто зрозуміти, що задеплоєно в кластері. Ми впроваджуємо Service Catalog, щоб зупинити цей хаос. Наш досвід показує: за 1–2 тижні можна отримати працюючий каталог, який окупається за рахунок зниження часу на інциденти на 30% і прискорення адаптації новачків до 2 днів (в 3 рази швидше). Економія від впровадження сягає $30,000 на рік.

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

Чому без каталогу настає криза?

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

Як 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 день — просто вкажіть кількість сервісів та поточні інструменти, і ми запропонуємо план впровадження.