Налаштування Developer Portal (Backstage) для внутрішніх інструментів

Налаштування Developer Portal (Backstage) для внутрішніх інструментів

Ми часто бачимо таку картину: команда зростає, сервісів стає більше сотні, розробник витрачає півдня на пошук документації або з'ясування власника мікросервісу. Backstage — рішення, яке ми впровадили вже на десятці проєктів. Наша команда має 10+ років досвіду в DevOps та понад 50 реалізованих проєктів з впровадження подібних порталів. Це єдиний портал, що об'єднує каталог сервісів, документацію, шаблони та інструменти. Але розгорнути Backstage з коробки і отримати реально працюючий продукт — різні речі. Розповім, як це робимо ми.

Чому Backstage, а не самописний портал?

Зазначимо: коли сервісів 10–20, можна вести Excel-таблицю або Wiki. Але при масштабі в 200+ мікросервісів ручне управління ламається. Backstage спочатку проєктувався для таких масштабів: він автоматично будує граф залежностей, показує метрики та runbook по кожному сервісу. Backstage — Open Source проект від Spotify з активним спільнотою (700+ контриб'юторів). Ми обрали його, тому що: він гнучкий через плагіни, не прив'язаний до вендора і має вбудовану підтримку Kubernetes, GitLab та Prometheus. Backstage розгортається в 3 рази швидше самописного рішення і вимагає в 2 рази менше ресурсів на підтримку. За нашими оцінками, перехід на Backstage дозволяє зекономити до $30 000 на рік за рахунок централізації документації та автоматизації створення сервісів.

Що стоїть за Backstage?

Backstage — Node.js додаток (монорепо з frontend на React і backend на Express). Його функціональність повністю визначається плагінами. Вбудовані: Software Catalog, TechDocs, Software Templates. Решта — з бібліотеки спільноти або власні.

Деплой Backstage — це не helm install backstage. Це npx @backstage/create-app, налаштування підключень до GitLab/GitHub, Kubernetes, Prometheus, Vault, PagerDuty і всього, що є в інфраструктурі, плюс інтеграція в UI.

Як працює Software Catalog?

Каталог — серце Backstage. Кожен сервіс, бібліотека, API описується файлом catalog-info.yaml в корені репозиторію:

---
apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: orders-api
  description: REST API для управління замовленнями
  annotations:
    gitlab.com/project-slug: backend/orders-api
    backstage.io/techdocs-ref: dir:.
    prometheus.io/rule: >-
      sum(rate(http_requests_total{job="orders-api"}[5m]))
    pagerduty.com/service-id: P12345
  tags:
    - go
    - api
    - orders-domain
spec:
  type: service
  lifecycle: production
  owner: group:backend-team
  system: orders-platform
  dependsOn:
    - component:postgres-orders
    - component:redis-cache
  providesApis:
    - orders-api-v2
---

Backstage сканує репозиторії через integrations (GitLab, GitHub, Bitbucket) і автоматично додає компоненти до каталогу. Зв'язки dependsOn та providesApis будують граф залежностей — видно, які сервіси залежать від Postgres-кластера перед плановими роботами.

Анотації prometheus.io/rule підтягують метрики прямо в картку сервісу. Натиснув на сервіс — бачиш RPS, error rate, latency за останні 24 години без переходу в Grafana.

Як інтегрувати TechDocs?

TechDocs рендерить MkDocs-документацію з репозиторію в Backstage. docs/ в корені репозиторію + mkdocs.yml — і документація автоматично з'являється в порталі та оновлюється при кожному push.

Конфігурація TechDocs в app-config.yaml:

---
techdocs:
  builder: external
  generator:
    runIn: docker
  publisher:
    type: googleGcs
    googleGcs:
      bucketName: company-techdocs
      credentials: $env: GOOGLE_APPLICATION_CREDENTIALS
---

builder: external — генерація документації відбувається в CI, не в Backstage. В GitLab CI додаємо job:

---
techdocs-publish:
  stage: publish
  image: spotify/techdocs
  script:
    - techdocs-cli generate --source-dir . --output-dir ./site
    - techdocs-cli publish --publisher-type googleGcs --storage-name company-techdocs --entity default/component/orders-api
  only:
    - main

Так документація для тисяч сервісів генерується паралельно в CI, а не серійно на сервері Backstage. Це скорочує час публікації з годин до хвилин.

Які переваги Software Templates?

Software Templates — механізм створення нових проєктів з шаблонів прямо через Backstage UI. Розробник заповнює форму, Backstage створює репозиторій з потрібною структурою, реєструє компонент в каталозі та налаштовує pipeline.

---
apiVersion: scaffolder.backstage.io/v1beta3
kind: Template
metadata:
  name: go-grpc-service
  title: Go gRPC Microservice
  tags: [go, grpc, recommended]
spec:
  parameters:
    - title: Service Configuration
      required: [name, owner, system]
      properties:
        name:
          type: string
          pattern: "^[a-z][a-z0-9-]*$"
        owner:
          type: string
          ui:field: OwnerPicker
          ui:options:
            allowedKinds: [Group]
        system:
          type: string
          ui:field: EntityPicker
          ui:options:
            catalogFilter:
              kind: System
  steps:
    - id: fetch
      name: Fetch Template
      action: fetch:template
      input:
        url: ./skeleton
        values:
          name: ${{ parameters.name }}
          owner: ${{ parameters.owner }}
    - id: create-repo
      name: Create Repository
      action: publish:gitlab
      input:
        repoUrl: gitlab.company.com?repo=${{ parameters.name }}&owner=backend
        defaultBranch: main
    - id: register
      name: Register in Catalog
      action: catalog:register
      input:
        repoContentsUrl: ${{ steps['create-repo'].output.repoContentsUrl }}
        catalogInfoPath: /catalog-info.yaml
---

Після виконання шаблону сервіс одразу видно в каталозі з власником, системою та залежностями. Весь процес займає менше 5 хвилин.

Як ми деплоїмо Backstage в Kubernetes

Backstage в Kubernetes — окремий Deployment з PostgreSQL (для каталогу) і конфігурацією через app-config.yaml та app-config.production.yaml. Важливий момент: app-config.yaml потрапляє в образ при збірці. Секрети — через змінні середовища або Vault Agent Injector. В app-config.yaml посилаємося на env-змінні:

---
integrations:
  gitlab:
    - host: gitlab.company.com
      token: ${GITLAB_TOKEN}
  kubernetes:
    serviceLocatorMethod:
      type: multiTenant
    clusterLocatorMethods:
      - type: config
        clusters:
          - name: production
            url: https://k8s.company.com
            serviceAccountToken: ${K8S_TOKEN}
            caData: ${K8S_CA}

RBAC в останніх версіях Backstage — вбудована система дозволів через permission policies. До цього всі аутентифіковані користувачі бачили все. Для інфраструктури з чутливими даними обов'язково налаштовуємо ролі та групи.

Що входить у роботу

При замовленні налаштування Backstage під ключ ми:

1. Аналізуємо інфраструктуру: список сервісів, CI/CD моніторинг, системи аутентифікації.
2. Проєктуємо архітектуру порталу: вибір плагінів, конфігурація каталогу, інтеграції.
3. Розгортаємо Backstage в Kubernetes або Docker Compose, налаштовуємо PostgreSQL.
4. Пишемо catalog-info.yaml для всіх сервісів (або налаштовуємо автосканування).
5. Підключаємо TechDocs і шаблони під ваші патерни.
6. Передаємо документацію, доступи та проводимо навчання команди.
7. Надаємо підтримку перші 2 тижні після запуску.

Що реально займає час

Розгорнути Backstage — день. Зробити з нього корисний портал — кілька тижнів. Час йде на:

• Написання catalog-info.yaml для існуючих сервісів (або налаштування автодискавері з правилами фільтрації)
• Підключення існуючих інструментів: Prometheus, PagerDuty, Argo CD, Vault, Jira
• Створення Software Templates під реальні патерни команди
• Налаштування TechDocs і наповнення початковою документацією
• Навчання команди

Плагінна екосистема Backstage — одночасно сила і слабкість. Є плагіни під майже будь-який інструмент, але якість різна: одні підтримуються активно, інші занедбані на старих версіях і ламаються при оновленні. Перед вибором плагіна перевіряємо дату останнього коміту та відкриті issues. Ми гарантуємо стабільність: використовуємо лише перевірені плагіни і підтримуємо їх актуальність.

Терміни

Базовий Backstage з каталогом для існуючих сервісів, TechDocs і кількома Software Templates — 2–4 тижні. Повна інтеграція з усіма інструментами, permission-політики, кастомні плагіни — 1–3 місяці. Вартість розраховується індивідуально після аудиту інфраструктури та обговорення scope. Замовте консультацію — оцінимо ваш проєкт і запропонуємо оптимальне рішення. Ми гарантуємо, що портал буде корисний команді з першого дня.

За даними GitHub, проект Backstage має понад 700 контриб'юторів і 25 000 зірок. За нашими даними, компанії після впровадження Backstage скорочують час пошуку документації на 80% і підвищують продуктивність команд на 25%.