Backstage na Prática: Construindo seu Primeiro Portal Interno de Desenvolvedor (IDP)

A Complexidade Crescente no Ecossistema de Desenvolvimento Moderno

Equipes de engenharia de software enfrentam uma carga cognitiva cada vez maior. A proliferação de microsserviços, a diversidade de ferramentas de CI/CD, as múltiplas plataformas de cloud e a necessidade de manter a conformidade e a segurança criaram um labirinto tecnológico. Nesse cenário, desenvolvedores gastam um tempo precioso navegando por dashboards, wikis desatualizadas e scripts de automação dispersos, em vez de focar na entrega de valor. É aqui que o conceito de um Portal Interno de Desenvolvedor (IDP) se torna não apenas útil, mas essencial. Um IDP atua como uma camada de abstração sobre a complexidade, oferecendo um ponto de acesso unificado para todas as ferramentas, serviços e documentação que uma equipe de desenvolvimento precisa.

Decodificando o Backstage: A Fundação Open Source para seu IDP

Originado no Spotify e agora um projeto incubado pela Cloud Native Computing Foundation (CNCF), o Backstage emergiu como o padrão de fato para a construção de IDPs. Ele não é uma solução pronta, mas uma plataforma extensível para criar um portal adaptado às necessidades específicas da sua organização. Sua filosofia é fornecer um “single pane of glass” que centraliza a gestão de todo o ciclo de vida do software. Seus pilares fundamentais são projetados para resolver problemas específicos de autonomia e padronização.

Os Componentes Centrais do Backstage

• Catálogo de Software (Software Catalog): O coração do Backstage. Ele permite que as equipes modelem seu ecossistema de software, definindo componentes, APIs, recursos e, crucialmente, suas relações de propriedade e dependência. Tudo é definido via metadados em arquivos `catalog-info.yaml` versionados junto ao código-fonte.
• Templates de Software (Scaffolder): Automatiza a criação de novos projetos, serviços ou componentes. Em vez de seguir um manual com dezenas de passos, um desenvolvedor pode preencher um formulário simples para provisionar um novo serviço com todas as melhores práticas da empresa já incorporadas: pipeline de CI/CD, configuração de logging, alertas e estrutura de código padrão.
• TechDocs: Uma solução de documentação técnica “docs-as-code”. O TechDocs renderiza documentação escrita em Markdown e armazenada em repositórios Git, apresentando-a de forma unificada e acessível dentro do portal, diretamente associada ao componente de software correspondente.
• Ecossistema de Plugins: A verdadeira força do Backstage reside em sua arquitetura baseada em plugins. É possível integrar praticamente qualquer ferramenta do seu toolchain – de provedores de CI/CD como GitHub Actions e Jenkins a sistemas de observabilidade como Grafana e Datadog – diretamente na interface do IDP.

Preparando o Terreno: Pré-requisitos para a Instalação

Antes de iniciar a construção do seu portal, é fundamental garantir que o ambiente de desenvolvimento esteja corretamente configurado. O Backstage é um monorepo baseado em TypeScript e Node.js, gerenciado com Yarn Workspaces. A seguir, os pré-requisitos essenciais:

• Node.js: É recomendada a versão Active LTS (atualmente, a v18 ou v20).
• Yarn: A versão 1.x é a ferramenta de gerenciamento de pacotes utilizada pelo Backstage.
• Docker: Necessário para a funcionalidade do TechDocs, que constrói os sites de documentação em contêineres isolados.
• Git: Essencial para o versionamento do próprio Backstage e para a integração com repositórios de componentes.

Com o ambiente pronto, a criação de uma nova aplicação Backstage é realizada com um único comando através do npx. Este comando inicializa um novo diretório com toda a estrutura básica de um monorepo Backstage.

npx @backstage/create-app@latest

Após a execução, você terá uma estrutura de diretórios que inclui o `packages/` (onde residem o frontend e o backend), o arquivo `app-config.yaml` para configurações e o `package.json` na raiz.

Executando sua Primeira Instância Local do Backstage

Com a estrutura do projeto criada, o próximo passo é iniciar a aplicação localmente. Navegue até o diretório raiz do seu novo projeto e execute o comando para iniciar os servidores de frontend e backend simultaneamente em modo de desenvolvimento.

yarn dev

Este comando iniciará o frontend na porta `3000` e o backend na porta `7007`. Ao acessar `http://localhost:3000` em seu navegador, você será recebido pela interface do Backstage. Inicialmente, o catálogo estará populado com alguns exemplos. O primeiro passo prático é registrar um de seus próprios componentes. Para isso, crie um arquivo `catalog-info.yaml` na raiz de um repositório Git existente e aponte o Backstage para ele através da funcionalidade de registro.

O Catálogo de Software: Mapeando seu Universo Tecnológico

O Catálogo de Software é a fonte da verdade sobre todo o software e recursos da sua organização. A sua eficácia depende da riqueza e precisão dos metadados fornecidos nos arquivos `catalog-info.yaml`. A estrutura de um arquivo básico para um serviço web é a seguinte:

apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: meu-servico-exemplo
  description: Um serviço de exemplo para o IDP
  annotations:
    github.com/project-slug: minha-org/meu-repo
    backstage.io/techdocs-ref: dir:.
spec:
  type: service
  lifecycle: experimental
  owner: meu-time
  system: sistema-principal

O Backstage define vários tipos (`kind`) de entidades para modelar o ecossistema:

• Component: Uma peça de software, como um serviço, website ou biblioteca.
• API: Descreve uma interface, como uma API REST ou gRPC.
• Resource: Uma infraestrutura necessária para um componente, como um banco de dados S3 ou um cluster Kubernetes.
• User e Group: Mapeiam as pessoas e times, definindo a propriedade sobre as outras entidades.
• System: Um conjunto de componentes e recursos que, juntos, entregam uma funcionalidade de negócio maior.

A verdadeira potência emerge ao definir as relações entre essas entidades usando campos como `owner`, `system`, `dependsOn` e `providesApi`, o que permite ao Backstage construir um grafo visual e navegável do seu ecossistema.

Automação com o Scaffolder: Padronização na Criação de Projetos

O Scaffolder é a ferramenta que transforma o Backstage de um visualizador passivo em uma plataforma de ação. Ele permite criar templates que automatizam a criação de novos componentes. Um template é definido por um arquivo `template.yaml` que descreve um formulário para coletar parâmetros e uma série de ações a serem executadas.

A estrutura de um `template.yaml` consiste em três seções principais:

1. `parameters`: Define os campos do formulário que serão apresentados ao usuário, utilizando a especificação JSON Schema para definir tipos, validações e layout.
2. `steps`: A sequência de ações a serem executadas. As ações mais comuns incluem `fetch:template` para copiar um esqueleto de código, `publish:github` para criar um novo repositório, e `catalog:register` para registrar o novo componente no Catálogo de Software.
3. `output`: Define as variáveis que serão retornadas ao final da execução, como o link para o novo repositório ou para a página do componente no Backstage.

Criar um template para um novo microsserviço Node.js, por exemplo, pode garantir que ele já nasça com o Dockerfile correto, um pipeline de GitHub Actions configurado e o `catalog-info.yaml` preenchido, reduzindo o tempo de setup de dias para minutos e garantindo conformidade com os padrões da empresa.

Documentação como Código: A Abordagem do TechDocs

Manter a documentação atualizada é um desafio crônico em engenharia. O TechDocs aborda esse problema tratando a documentação como parte do código-fonte. Os desenvolvedores escrevem a documentação em arquivos Markdown, que vivem no mesmo repositório do componente. Para habilitar o TechDocs, basta adicionar a anotação `backstage.io/techdocs-ref: dir:.` no `catalog-info.yaml` do componente.

O processo funciona da seguinte forma:

• O Backstage detecta a anotação e busca por um arquivo `mkdocs.yml` e um diretório `/docs` no repositório do componente.
• Ele utiliza um processo de build (geralmente em um contêiner Docker) para executar o MkDocs, um gerador de site estático, que converte os arquivos Markdown em HTML.
• O site HTML gerado é armazenado em um local configurado (como AWS S3, Google Cloud Storage ou armazenamento local) e servido diretamente na página do componente dentro do Backstage.

Essa abordagem garante que a documentação evolua junto com o código, facilitando as revisões e mantendo a consistência.

Da Instância Local à Produção: Próximos Passos Essenciais

Migrar seu IDP Backstage do ambiente local para um ambiente de produção envolve algumas considerações críticas para garantir escalabilidade, segurança e confiabilidade. Primeiramente, a configuração padrão utiliza um banco de dados SQLite, que é inadequado para produção. É essencial configurar uma conexão com um banco de dados robusto, como o PostgreSQL. Isso é feito ajustando a seção `database` no seu `app-config.production.yaml`.

Outro ponto fundamental é a autenticação. Um IDP contém informações sensíveis sobre seu ecossistema. O Backstage suporta diversos provedores de autenticação, como GitHub, GitLab, Okta, e Auth0. Configurar um provedor de identidade garante que apenas usuários autorizados tenham acesso ao portal. Finalmente, o processo de descoberta de componentes deve ser automatizado. Em vez de registrar manualmente cada `catalog-info.yaml`, configure integrações, como o `GitHubOrgEntityProvider`, que varrem automaticamente sua organização no GitHub em busca de repositórios que contenham esses arquivos, mantendo seu catálogo sempre atualizado e refletindo a realidade do seu ambiente de desenvolvimento.

Rogerio Lima

Sou um profissional na área de Tecnologia da informação, especializado em monitoramento de ambientes, Sysadmin e na cultura DevOps. Possuo certificações de Segurança, AWS e Zabbix.