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

O Fim da Sobrecarga Cognitiva e a Ascensão da Engenharia de Plataforma

O ecossistema moderno de desenvolvimento de software atingiu um nível de complexidade que frequentemente sufoca a produtividade. Com a transição massiva para arquiteturas de microsserviços, kubernetes, infraestrutura como código e pipelines de CI/CD fragmentados, o desenvolvedor médio hoje gasta mais tempo navegando em ferramentas de infraestrutura do que escrevendo lógica de negócio. É nesse cenário que a engenharia de plataforma emerge não apenas como uma tendência, mas como uma necessidade operacional, introduzindo o conceito de Portais Internos de Desenvolvedor (IDPs). O backstage.io, originalmente criado pelo Spotify e agora um projeto incubado pela CNCF, tornou-se o padrão de fato para construir esses portais. Ele não é apenas uma interface; é uma estrutura extensível que centraliza serviços, documentação e fluxos de trabalho de infraestrutura em uma única experiência unificada.

A Estrutura Core do Backstage: Catálogo de Software e o Modelo de Dados

No coração de qualquer implementação bem-sucedida do Backstage reside o Software Catalog. Diferente de um simples inventário de ativos, o catálogo do Backstage utiliza um modelo de dados baseado em grafos que estabelece relações claras entre componentes, sistemas, domínios e recursos. Ao definir um arquivo catalog-info.yaml na raiz de um repositório, os times declaram a propriedade e as dependências de seu serviço. Essa abordagem de ‘metadata as code’ garante que a fonte da verdade resida junto com o código, enquanto o Backstage atua como o motor de descoberta. Dentro deste catálogo, a entidade Component representa a unidade básica de software, enquanto entidades de API permitem que equipes diferentes descubram contratos de integração sem precisar vasculhar documentações desatualizadas em wikis corporativas ou pastas perdidas no SharePoint.

Preparando o Terreno: Requisitos e Inicialização do Ambiente

Para construir seu primeiro IDP com Backstage, é necessário um ambiente de desenvolvimento robusto baseado em Node.js (versão 18 ou superior) e o gerenciador de pacotes Yarn. A instalação inicial é simplificada pelo comando npx @backstage/create-app, que gera um monorepo contendo tanto o frontend (React) quanto o backend (Node.js/Express). É crucial configurar uma instância de banco de dados PostgreSQL desde o início, pois embora o SQLite seja suportado para testes rápidos, ele não possui a persistência e as capacidades de concorrência necessárias para um ambiente de produção. Durante a inicialização, o arquivo app-config.yaml torna-se o seu centro de controle, onde segredos, integrações de provedores de Git (GitHub, GitLab ou Bitbucket) e configurações de autenticação são definidos de forma declarativa.

Software Templates: Padronização Através do Scaffolder

Uma das funcionalidades mais poderosas do Backstage é o Scaffolder. Ele resolve o problema do ‘dia zero’ na criação de novos serviços. Em vez de copiar e colar código de repositórios antigos, os desenvolvedores utilizam Software Templates. Esses templates são definidos via YAML e utilizam o motor de renderização Nunjucks para injetar variáveis em projetos boilerplate. Um template bem estruturado no Backstage executa uma série de ‘steps’ atômicos: ele solicita parâmetros ao usuário (como nome do serviço e descrição), gera o código-fonte, cria um novo repositório no provedor de Git, registra o componente automaticamente no catálogo e até dispara o primeiro pipeline de CI/CD. Essa automação não apenas acelera o desenvolvimento, mas garante que todos os novos serviços sigam os padrões de segurança, arquitetura e observabilidade da organização por padrão.

Integrando Documentação com TechDocs: O Modelo Docs-as-Code

O Backstage aborda a documentação técnica com a filosofia de ‘Docs-as-Code’. Através do plugin TechDocs, a documentação é escrita em Markdown, armazenada no mesmo repositório do código e processada pelo gerador de sites estáticos MkDocs. O Backstage então centraliza a visualização dessas documentações no portal. Isso resolve o problema crônico de documentação fragmentada. Quando um desenvolvedor consulta um serviço no catálogo, ele tem acesso imediato à documentação técnica sem sair da interface. Além disso, o TechDocs permite a indexação de busca centralizada, facilitando a localização de informações específicas através de múltiplos repositórios e domínios, eliminando o isolamento de conhecimento entre equipes.

Expandindo o Portal com o Ecossistema de Plugins

A verdadeira força do Backstage reside em sua arquitetura modular de plugins. Quase toda a interface que o usuário vê é um plugin. Para um IDP robusto, integrações comuns incluem o plugin do Kubernetes, que permite visualizar o status de pods e deployments diretamente na página do serviço, e o plugin do GitHub Actions, que traz o status dos builds para o portal. A criação de plugins customizados em TypeScript permite que empresas integrem ferramentas proprietárias de segurança, dashboards de custo de nuvem (como FinOps) ou métricas de qualidade de código do SonarQube. Ao centralizar essas visões, o Backstage reduz a troca de contexto (‘context switching’), permitindo que o desenvolvedor tenha uma visão de 360 graus da saúde de suas aplicações em um único lugar.

Governança, Autenticação e o Caminho para a Produção

Mover o Backstage de um experimento local para uma ferramenta de nível empresarial exige atenção rigorosa à segurança e governança. A integração com provedores de identidade (IdP) como Okta, Azure AD ou GitHub OAuth é mandatória. O sistema de permissões do Backstage permite definir políticas de controle de acesso baseado em funções (RBAC), controlando quem pode registrar novos componentes ou deletar recursos críticos. Para o deployment em produção, a estratégia recomendada envolve a containerização do backend e frontend em imagens Docker, orquestradas preferencialmente no Kubernetes. O uso de um Ingress Controller bem configurado e a gestão de segredos via ferramentas como HashiCorp Vault ou AWS Secrets Manager garantem que as chaves de API usadas para integrar com outras ferramentas permaneçam seguras enquanto o portal serve como a interface central da sua plataforma de engenharia.

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.