Настройка Developer Portal (Backstage) для внутренних инструментов

Настройка Developer Portal (Backstage) для внутренних инструментов

Мы часто видим такую картину: команда растёт, сервисов становится больше сотни, разработчик тратит полдня на поиск документации или выяснение владельца микросервиса. Backstage — решение, которое мы внедрили уже на десятке проектов. Это единый портал, объединяющий каталог сервисов, документацию, шаблоны и инструменты. Но развернуть Backstage из коробки и получить реально работающий продукт — разные вещи. Расскажу, как это делаем мы.

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

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

Что стоит за 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: scaffolding через веб-интерфейс

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 звёзд.