Internal Developer Portals: Como o Backstage Está Revolucionando a Developer Experience

O Problema da Fragmentação de Ferramentas

Em organizações modernas, desenvolvedores precisam navegar entre dezenas de ferramentas diariamente: GitHub, Jira, Jenkins, ArgoCD, Grafana, PagerDuty, Confluence… Essa fragmentação gera carga cognitiva excessiva e reduz a produtividade.

O que é um Internal Developer Portal?

Um Internal Developer Portal (IDP) é uma plataforma centralizada que:

Backstage: O Padrão da Indústria

Criado pelo Spotify e doado à CNCF, o Backstage se tornou o padrão de facto para Internal Developer Portals.

Arquitetura do Backstage

100%

Backstage: Catalog, Scaffolder, TechDocs + Plugins sobre Backend Services

Esc fechar+/- zoom

Componentes Principais

Implementando o Software Catalog

O coração do Backstage é o catálogo de software, definido via arquivos YAML:

# catalog-info.yaml no repositório do serviço
apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: payments-api
  description: API de processamento de pagamentos
  tags:
    - python
    - fastapi
    - payments
  annotations:
    github.com/project-slug: myorg/payments-api
    pagerduty.com/service-id: PXXXXXX
    grafana/dashboard-selector: "app=payments-api"
spec:
  type: service
  lifecycle: production
  owner: team-payments
  system: checkout-system
  dependsOn:
    - component:users-api
    - resource:payments-database
  providesApis:
    - payments-api
---
apiVersion: backstage.io/v1alpha1
kind: API
metadata:
  name: payments-api
  description: API REST para processamento de pagamentos
spec:
  type: openapi
  lifecycle: production
  owner: team-payments
  definition:
    $text: ./openapi.yaml

Software Templates para Golden Paths

Templates permitem criar novos projetos padronizados:

# template.yaml
apiVersion: scaffolder.backstage.io/v1beta3
kind: Template
metadata:
  name: python-service
  title: Serviço Python com FastAPI
  description: Cria um novo microserviço Python com FastAPI, Docker, CI/CD e observability
  tags:
    - python
    - fastapi
    - recommended
spec:
  owner: platform-team
  type: service

  parameters:
    - title: Informações do Serviço
      required:
        - name
        - owner
      properties:
        name:
          title: Nome do Serviço
          type: string
          pattern: '^[a-z0-9-]+$'
        description:
          title: Descrição
          type: string
        owner:
          title: Time Owner
          type: string
          ui:field: OwnerPicker

    - title: Configurações Técnicas
      properties:
        database:
          title: Banco de Dados
          type: string
          enum:
            - postgresql
            - mysql
            - none
          default: postgresql

  steps:
    - id: fetch-template
      name: Fetch Template
      action: fetch:template
      input:
        url: ./skeleton
        values:
          name: ${{ parameters.name }}
          owner: ${{ parameters.owner }}
          database: ${{ parameters.database }}

    - id: create-repo
      name: Create Repository
      action: publish:github
      input:
        repoUrl: github.com?owner=myorg&repo=${{ parameters.name }}
        description: ${{ parameters.description }}

    - id: register-catalog
      name: Register in Catalog
      action: catalog:register
      input:
        repoContentsUrl: ${{ steps['create-repo'].output.repoContentsUrl }}
        catalogInfoPath: /catalog-info.yaml

  output:
    links:
      - title: Repository
        url: ${{ steps['create-repo'].output.remoteUrl }}
      - title: Open in Backstage
        icon: catalog
        entityRef: ${{ steps['register-catalog'].output.entityRef }}

Plugins Essenciais

Kubernetes Plugin

// Visualizar pods, deployments e logs diretamente no Backstage
import { EntityKubernetesContent } from '@backstage/plugin-kubernetes';

// No EntityPage.tsx
<EntityLayout.Route path="/kubernetes" title="Kubernetes">
  <EntityKubernetesContent />
</EntityLayout.Route>

CI/CD Integration

# Mostrar status de builds no catálogo
annotations:
  github.com/project-slug: myorg/my-service
  # ou
  circleci.com/project-slug: github/myorg/my-service
  # ou
  jenkins.io/job-full-name: folder/my-service

Observability

annotations:
  grafana/dashboard-selector: "app=my-service"
  prometheus.io/scrape-target: "my-service:9090"
  sentry.io/project-slug: my-service

TechDocs: Documentação como Código

# mkdocs.yml no repositório
site_name: Payments API
nav:
  - Home: index.md
  - Architecture: architecture.md
  - API Reference: api-reference.md
  - Runbook: runbook.md

plugins:
  - techdocs-core

<!-- docs/index.md -->
# Payments API

## Overview

A Payments API é responsável por processar todas as transações
financeiras da plataforma.

## Quick Start

\`\`\`bash
# Clone o repositório
git clone https://github.com/myorg/payments-api

# Instale dependências
pip install -r requirements.txt

# Execute localmente
uvicorn main:app --reload
\`\`\`

## Architecture Decision Records

- [ADR-001: Escolha do FastAPI](adr/001-fastapi.md)
- [ADR-002: Padrão de Retry](adr/002-retry-pattern.md)

Métricas de Sucesso

Como medir o impacto do seu IDP:

Roadmap de Implementação

Quer implementar um Internal Developer Portal na sua organização? Fale com nossos especialistas em Developer Experience.