Backstage e catálogos de serviço

Duas perguntas aparecem em toda organização que passa de umas dezenas de serviços: “quem é o dono disto?” e “o que existe aqui?”. Durante um incidente, a primeira custa minutos caros; numa auditoria, a segunda custa semanas.

Um catálogo de serviços responde às duas. Backstage é a implementação mais conhecida — e também um projeto de software que alguém precisa manter.

Catálogo de software

O catálogo é um inventário vivo dos serviços, seus donos, dependências e links úteis. No Backstage, cada componente se descreve em um arquivo dentro do próprio repositório, o que é a decisão de projeto mais importante: o catálogo acompanha o código e não vira planilha desatualizada.

# catalog-info.yaml na raiz do repositório do serviço
apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: pedidos
  description: API de criação e consulta de pedidos.
  annotations:
    github.com/project-slug: empresa/pedidos
    grafana/dashboard-selector: "tags @> 'pedidos'"
    pagerduty.com/service-id: PXYZ123
  tags: [go, api, critico]
spec:
  type: service
  lifecycle: production
  owner: time-loja                 # dono é um time, nunca uma pessoa
  system: loja
  dependsOn: [resource:postgres-pedidos, component:pagamentos]

O valor aparece quando o catálogo vira ponto de partida real: do serviço para o painel, para o runbook, para o plantão, para o repositório e para as dependências. Se ele for só uma lista de nomes, ninguém abre duas vezes.

Mantenha a qualidade com automação: verificação no CI de que todo repositório tem catalog-info.yaml com dono válido, e um relatório periódico de componentes órfãos ou com dono inexistente.

Templates de scaffolding

O Backstage também expõe os golden paths como formulários: a pessoa preenche nome, time e tipo, e o template cria repositório, pipeline, manifests e registra o serviço no catálogo.

apiVersion: scaffolder.backstage.io/v1beta3
kind: Template
metadata: { name: servico-http-go, title: "Serviço HTTP em Go" }
spec:
  parameters:
    - title: Identificação
      required: [nome, time]
      properties:
        nome: { type: string, pattern: "^[a-z][a-z0-9-]{2,29}$" }
        time: { type: string, ui:field: OwnerPicker }
  steps:
    - id: gerar
      action: fetch:template
      input: { url: ./esqueleto, values: { nome: "${{ parameters.nome }}" } }
    - id: publicar
      action: publish:github
      input: { repoUrl: "github.com?owner=empresa&repo=${{ parameters.nome }}" }
    - id: registrar
      action: catalog:register

Documentação junto do código

O TechDocs renderiza Markdown do próprio repositório dentro do portal. É o modelo certo: documentação que mora ao lado do código é revisada no mesmo pull request e envelhece muito menos que wiki separado. Para runbook e decisões de arquitetura (ADRs), a diferença é grande.

Plugins e o custo de manter

Aqui está a parte que costuma ser subestimada. Backstage é uma aplicação React/Node que você hospeda, atualiza e opera:

• Upgrades frequentes do upstream, às vezes com quebra.
• Plugins de terceiros com qualidade e manutenção variáveis.
• Autenticação, permissões e integrações a configurar e manter.
• Alguém precisa saber TypeScript para customizar de verdade.
• Se o portal ficar fora do ar durante um incidente, ele deixa de ajudar exatamente quando seria mais útil.

Uma regra prática honesta: se o seu time de plataforma tem menos de quatro pessoas, não comece por Backstage. Ele é bom quando existe operação para sustentá-lo. Existem também alternativas gerenciadas e produtos comerciais (Roadie, Port, Cortex, Spotify Portal), que trocam custo de operação por custo de licença — comparação legítima.

Alternativas mais leves

Você pode ter 80% do valor com muito menos:

• Um repositório servicos/ com um YAML por serviço, validado no CI, e uma página estática gerada a partir dele.
• Labels e anotações padronizadas no Kubernetes (app.kubernetes.io/part-of, owner), com um painel que lista serviço, dono e alerta.
• Templates de repositório do GitHub/GitLab, sem portal.
• Um SERVICE.md na raiz de cada repositório, com dono, plantão, painel e runbook.

Comece pelo mais simples que responde às duas perguntas do início. Portal é consequência de ter conteúdo bom, não o contrário — catálogo sem dados confiáveis é pior que nenhum, porque as pessoas confiam nele e erram.

Próximo passo: meça se tudo isso está reduzindo atrito em Experiência do desenvolvedor.