A convenção de Repositórios de Aplicação muda isso. Quando um novo serviço é scaffoldado via Backstage, ele entrega um repositório completo e opinativo com código fonte, Dockerfile, pipeline de CI e uma pasta .k8s — dando à equipe da aplicação autonomia sobre a configuração de sua carga de trabalho enquanto mantém a plataforma no controle do modelo de implantação.

A arquitetura: dois repos, uma implantação​

Nosso modelo GitOps usa uma separação clara entre configuração de implantação e configuração da aplicação:

{domain}-gitops/k8s/{env}/{service}/    ← Manifestos base gerenciados pela plataforma
{app}-repo/.k8s/values.yaml             ← Sobrescrições gerenciadas pelo desenvolvedor

O repositório GitOps do domínio contém a configuração fundacional do Kubernetes — Deployments, Services, NetworkPolicies, HPA, PDB — gerada pelo template create-service e mantida pelas convenções de plataforma do time do domínio.

O repositório da aplicação contém uma pasta .k8s onde o time de desenvolvimento gerencia valores que mudam frequentemente com os releases da aplicação.

O padrão de Múltiplas Fontes (Multiple Sources) do ArgoCD mescla ambas as fontes no momento da sincronização. Os manifestos base do repo GitOps fornecem estrutura e segurança. As sobrescrições da aplicação fornecem flexibilidade e velocidade.

O que os desenvolvedores podem sobrescrever​

O .k8s/values.yaml no repositório da aplicação dá aos desenvolvedores controle sobre:

• Tag da imagem: Atualizada automaticamente pelo CI em cada build bem-sucedido
• Réplicas: Sobrescrever limites min/max do HPA para necessidades específicas da carga de trabalho
• CPU e memória: Ajustar requests e limits conforme o perfil da aplicação evolui
• Variáveis de ambiente: Configuração específica da aplicação que muda com os releases

Esses são os valores que mudam com mais frequência e estão mais diretamente ligados ao código da aplicação. Mantendo-os no repo da app, desenvolvedores não precisam de um PR no repo GitOps toda vez que fazem push de um release.

O que os desenvolvedores não tocam​

Os manifestos base em {domain}-gitops/k8s/ permanecem sob controle da convenção da plataforma:

• Definição do Namespace com todos os 9 labels obrigatórios
• Contexto de segurança: runAsNonRoot, readOnlyRootFilesystem, capabilities: drop: [ALL]
• NetworkPolicy: isolamento por fronteira de projeto
• PodDisruptionBudget: rede de segurança apenas para prod
• ResourceQuota: limites dimensionados por ambiente

Essa separação garante que as garantias de segurança e conformidade nunca sejam acidentalmente sobrescritas por um desenvolvedor que "só precisa mudar o limite de memória."

O pipeline de CI: do commit ao deploy​

Todo repositório de aplicação scaffoldado pelo create-service inclui um workflow pré-configurado do GitHub Actions. O pipeline não é algo que o time precisa escrever — ele chega pronto:

Desenvolvedor faz push do código
        │
        ▼
┌─── Pipeline de CI ─────────────────────────────────┐
│                                                     │
│  1. Test & Lint      Executa testes, verificações  │
│  2. Build            Constrói contêiner do Dockerfile│
│  3. Publish          Push da imagem para o registry │
│  4. Atualização de   Atualiza .k8s/values.yaml com │
│     Tag              nova tag, commit de volta      │
│                                                     │
└─────────────────────────────────────────────────────┘
        │
        ▼
ArgoCD detecta mudança no app repo (fonte secundária)
        │
        ▼
Implantação sincroniza com nova tag da imagem

O passo chave é a Atualização de Tag. Após publicar a imagem do contêiner, o pipeline atualiza automaticamente image.tag em .k8s/values.yaml e faz commit da mudança de volta no repositório da aplicação. Esse commit é o que o ArgoCD observa.

Como o ArgoCD está configurado com Multiple Sources — uma apontando para o repo GitOps para manifestos base, outra apontando para o repo da app para sobrescrições — a nova tag aciona uma sincronização automática para o ambiente alvo.

Sem atualizações manuais de tag de imagem. Sem passo separado de "deploy". Faça push do código, obtenha a implantação.

O Dockerfile: seguro por padrão​

O Dockerfile scaffoldado segue os padrões de segurança da plataforma:

• Build multi-estágio: Estágios separados de build e runtime para minimizar o tamanho da imagem
• Usuário não-root: USER 1000 — combina com o contexto de segurança do pod (runAsNonRoot: true)
• Compatível com filesystem somente leitura: Escritas da aplicação vão para /tmp (montado como emptyDir)
• Otimização específica por linguagem: Node.js, .NET e Python recebem cada um um Dockerfile adaptado com imagens base e cache de dependências apropriados

O desenvolvedor não precisa saber sobre contextos de segurança de pod ou filesystems somente leitura. O Dockerfile e os manifestos Kubernetes são projetados para funcionar juntos desde o primeiro dia.

O quadro completo​

Quando o create-service é executado, o desenvolvedor recebe:

Três repositórios, três fronteiras de propriedade, uma implantação que funciona sem coordenação manual.

Por que não tudo no repo da app?​

Uma pergunta comum: "Por que não colocar todos os manifestos Kubernetes no repositório da aplicação?"

Porque quebra o modelo de propriedade:

1. Contexto de segurança e políticas de rede são preocupações da plataforma, não da aplicação. Desenvolvedores não deveriam precisar (nem poder) modificá-los.
2. Múltiplos serviços compartilham o mesmo ApplicationSet e estrutura de domínio. Centralizar isso no repo GitOps evita duplicação e garante consistência.
3. Validação de convenção roda no repo GitOps. Verificações de CI para nomenclatura, labels e padrões de segurança acontecem onde essas definições vivem.

A pasta .k8s dá aos desenvolvedores a autonomia que precisam — tags de imagem, escalonamento, recursos — sem dar acesso às coisas que não deveriam mudar.

A convenção de Repositórios de Aplicação está documentada na Convenção da Plataforma — Repositórios de Aplicação. O padrão de Múltiplas Fontes do ArgoCD está na Convenção ArgoCD.

Os templates do Backstage Scaffolder mudam essa equação. Em vez de documentar o caminho correto e torcer para que os engenheiros sigam, codificamos o caminho correto em um formulário que produz saída correta todas as vezes. Este post é sobre como nossa cadeia de templates funciona, por que a ordem de dependência importa, e o que acontece quando você clica em Create.

O problema com padrões baseados em documentação​

Nossa convenção de plataforma define um padrão preciso de nomenclatura, 9 labels obrigatórios, padrões de segurança e uma estrutura específica de repositório. Antes dos templates, aplicar esses padrões significava:

1. Ler 3 páginas diferentes de wiki
2. Copiar e colar YAML de exemplos (frequentemente desatualizados)
3. Torcer para o revisor pegar o que você esqueceu
4. Esperar o time de plataforma corrigir o que o revisor não pegou

O resultado: 80% dos novos serviços precisavam de pelo menos um PR de correção após a criação inicial. Conformidade com a convenção era aspiracional.

Templates como mecanismo de aplicação​

Um template do Backstage Scaffolder é uma definição YAML que combina um formulário voltado ao usuário com uma sequência de ações automatizadas. O desenvolvedor preenche o formulário. O template gera todos os arquivos, abre os PRs e registra a entidade no catálogo.

O template não documenta a convenção — ele implementa a convenção. Não existe como criar um serviço com labels faltando, nomenclatura errada ou contexto de segurança incorreto, porque o template gera tudo isso.

A cadeia de templates​

Templates têm dependências. Você não pode criar um serviço sem um system. Não pode criar um system sem um domain. A cadeia impõe esta ordem:

Camada de pessoas (execute a qualquer momento)
──────────────────────────────────────────────────────
 create-group → entidade Group + RBAC + papéis ArgoCD
 create-user  → entidade User  + RBAC + acesso ArgoCD

Camada de plataforma (execute em ordem)
──────────────────────────────────────────────────────
 create-domain
      │  Entidade Domain, repositório {domain}-gitops, AppProject
      ▼
 create-system
      │  Entidade System, ApplicationSet
      ▼
      ├─────────────────────────┬─────────────────────┐
      ▼                         ▼                     ▼
 create-service          create-resource         create-secret
 Entidade Component,     Entidade Resource,      SealedSecret
 App Repo (CI/CD,        Claim Crossplane/env,   manifesto/env
 TechDocs, .k8s),        namespace de infra
 manifestos k8s/env

Cada template usa EntityPicker para selecionar seu pai. Você escolhe o domain de um dropdown que mostra apenas domains existentes. Escolhe o system de um dropdown filtrado pelos systems daquele domain. A integridade referencial é aplicada pela própria interface.

O que o create-service realmente faz​

Quando um engenheiro de produto executa create-service, ele preenche:

• System: selecionado do catálogo (domain, repo e AppProject resolvem automaticamente)
• Nome do serviço: ex., api, worker, frontend
• Tipo do serviço: api / worker / frontend / grpc / cronjob
• Imagem do contêiner: caminho do registry
• Perfil de recursos: qual tier de CPU/memória
• Ambientes alvo: em quais envs fazer deploy

Então o template executa:

Passo 1 — Gerar o Repositório da Aplicação​

Um novo repositório é criado com:

{app}-repo/
├── src/                    ← código fonte boilerplate
├── Dockerfile              ← otimizado, non-root, específico da linguagem
├── .github/workflows/
│   └── ci.yaml             ← lint, test, build, publish, atualização de tag
├── .k8s/
│   └── values.yaml         ← sobrescrições (tag da imagem, réplicas, recursos)
├── docs/
│   └── index.md            ← base do TechDocs
└── catalog-info.yaml       ← entidade Component do Backstage

Passo 2 — Gerar manifestos Kubernetes no repositório do domínio​

Em {domain}-gitops/k8s/{env}/{service}/, o template cria:

• Namespace com todos os 9 labels obrigatórios
• Deployment com contexto de segurança, limites de recursos, probes de readiness/liveness
• Service expondo a porta correta
• HPA com escalonamento apropriado por env (dev: 1→2, staging: 2→5, prod: 3→10)
• PDB (apenas prod, minAvailable: 1)
• NetworkPolicy isolando por fronteira de projeto

Passo 3 — Atualizar o ApplicationSet​

No platform-gitops, o template adiciona o novo serviço como elemento no ApplicationSet existente:

elements:
  - service: api      # ← existente
  - service: worker   # ← adicionado pelo template

Passo 4 — Registrar e abrir PRs​

O template abre dois PRs:

1. PR do repositório do domínio: manifestos k8s + entidade Component
2. PR do repositório da plataforma: elemento do ApplicationSet

Ele também registra o novo catalog-info.yaml no catálogo do Backstage.

A ordem de merge importa: PR da plataforma primeiro (o ApplicationSet deve existir antes que o ArgoCD possa sincronizar), depois o PR do domínio. Em minutos após ambos serem mergeados, o serviço está rodando no cluster dev.

O workflow de dois PRs​

Todo template segue o mesmo padrão: um PR no repositório do domínio/catálogo, um PR no platform-gitops. Essa separação existe porque:

• Times de domínio são donos de seus manifestos — eles revisam e mergeiam o que implantam
• Time de plataforma é dono do roteamento — eles revisam mudanças na configuração do ArgoCD e RBAC
• CODEOWNERS impõe isso — mudanças no repositório errado são bloqueadas automaticamente

Resultados​

Desde a adoção dos templates:

• 100% de conformidade de labels em todos os novos serviços (era < 20%)
• < 3 minutos do clique em Create até os PRs abertos (eram horas de YAML manual)
• Zero violações de convenção em serviços gerados por template
• Serviço rodando em dev em < 30 minutos (era 2–5 dias)

Os templates não apenas tornaram a criação de serviços mais rápida — tornaram violações de convenção estruturalmente impossíveis para novos serviços. O "jeito correto" é o único jeito.

A cadeia completa de templates e resumo de saída estão documentados na Convenção da Plataforma — Templates. O modelo de entidades do Backstage e design do catálogo estão na Convenção Backstage.

Este post é sobre como uma única convenção de nomenclatura — três segmentos, uma chave — unificou Kubernetes, ArgoCD, Backstage e Crossplane. E por que o retorno sobre investimento foi medido em dias economizados por semana.

O custo da deriva de nomenclatura​

Antes da convenção, cada equipe tinha seu próprio estilo:

• Time A nomeava namespaces payments-api-prod
• Time B usava prod-orders-backend
• Time C optava por frontend_staging

Nenhum desses está errado. Todos são incompatíveis. Quando um incidente atingia payments-api-prod, a primeira pergunta era sempre: "Qual aplicação do ArgoCD gerencia isso?" Ninguém sabia sem investigar. A resposta vivia na cabeça de alguém, ou em uma planilha atualizada pela última vez três meses atrás.

O custo real não era a nomenclatura em si — era o mapeamento manual necessário toda vez que um humano ou ferramenta precisava cruzar referências entre sistemas:

Cada uma dessas perguntas custava 5–15 minutos por ocorrência. Multiplique pelo número de engenheiros fazendo-as diariamente, e a deriva de nomenclatura consumia horas por semana em toda a organização.

A chave semântica​

A convenção é simples. Todo recurso na plataforma é endereçado por três segmentos:

{project}-{env}-{service}

payments-prod-api

O insight principal é que isso não é apenas um padrão de nomenclatura — é um contrato. Quando a nomenclatura é consistente, as ferramentas conversam entre si sem um humano no meio.

Como uma chave conecta quatro sistemas​

Aqui está o mapeamento completo para um único serviço:

Backstage Domain:      payments          ← project
ArgoCD AppProject:     payments          ← project
Backstage System:      gateway           ← agrupamento lógico
ArgoCD ApplicationSet: gateway           ← agrupamento lógico
Backstage Component:   gateway-api       ← system + service
ArgoCD Application:    gateway-api-prod  ← system + service + env
Kubernetes Namespace:  payments-prod-api ← project + env + service

Quando um desenvolvedor abre a página do Component gateway-api no Backstage, o plugin de Kubernetes encontra pods em todos os clusters usando um único label selector: project=payments,service=api. Sem configuração por ambiente. Sem registro manual do namespace de cada cluster. O label faz o trabalho.

O plugin do ArgoCD mostra o status de sincronização por ambiente usando a mesma abordagem de labels. O grafo de dependências mostra quais bancos de dados e filas este serviço utiliza.

Um nome, uma consulta, uma página, uma fonte de verdade.

Os 9 labels que fazem funcionar​

Todo namespace na plataforma carrega 9 labels obrigatórios:

labels:
  project: payments               # domínio
  env: prod                       # ambiente
  service: api                    # carga de trabalho
  team: team-payments             # time responsável
  backstage.io/domain: payments   # → Backstage Domain
  backstage.io/system: gateway    # → Backstage System
  backstage.io/component: gateway-api  # → Backstage Component
  argocd/app: gateway-api-prod    # → ArgoCD Application
  argocd/app-set: gateway         # → ArgoCD ApplicationSet

Qualquer label faltando reprova o PR no CI. Não existe caminho de exceção. Isso não é aplicado por documentação — é aplicado por código.

O impacto no negócio​

Após implantar a convenção na primeira equipe de domínio:

A convenção é a coisa mais barata que construímos e o investimento de maior ROI em toda a plataforma. Toda integração de ferramenta, toda automação, todo dashboard depende dela. Sem nomenclatura consistente, a plataforma é apenas uma coleção de ferramentas. Com ela, a plataforma é um produto.

A lição​

Invista em nomenclatura antes de investir em ferramental. Um setup perfeito do ArgoCD com nomes de namespaces inconsistentes é pior do que um setup básico com nomes consistentes. A convenção de nomenclatura não é um documento para escrever depois que a arquitetura está pronta — é a fundação sobre a qual a arquitetura é construída.

Cada hora que investimos acertando a chave de três segmentos economizou dez horas de debugging de integrações de ferramentas depois.

A convenção completa de nomenclatura e o mapeamento entre sistemas estão documentados na Convenção da Plataforma. Os objetivos de negócio e métricas de sucesso estão no PRD da Plataforma.

Chegamos nesse limite. Este post é sobre como saímos dele.

O problema​

Antes do IDP, onboardar um novo serviço tinha essa cara:

1. Abrir um ticket no JIRA para criação de namespace
2. Esperar de 2 a 5 dias para a equipe de plataforma revisar
3. Receber o namespace — com as labels erradas ou sem limites de recursos
4. Abrir outro ticket para a aplicação ArgoCD
5. Abrir outro ticket para o banco de dados

De oito a quinze etapas manuais em múltiplas ferramentas. Cada etapa exigia uma pessoa da equipe de plataforma. Cada erro exigia mais uma rodada de ida e volta.

A causa raiz não era falta de automação. Tínhamos Terraform, tínhamos Helm, tínhamos ArgoCD. O problema era que nada disso era self-service. A automação só rodava quando a equipe de plataforma a executava.

O que construímos​

O IDP é quatro ferramentas trabalhando juntas:

O insight fundamental foi que as convenções são o produto. Uma convenção de nomenclatura não é documentação — é o contrato que permite que cada ferramenta fale com todas as outras sem um humano no meio.

A chave semântica​

Todo recurso da plataforma — namespace, aplicação ArgoCD, entidade Backstage, claim Crossplane — é endereçado pela mesma chave de três segmentos:

{project}-{env}-{service}

payments-prod-api
│         │     └── Namespace Kubernetes: payments-prod-api
│         │         Component Backstage: gateway-api
│         └── Application ArgoCD: gateway-api-prod
└── AppProject ArgoCD: payments
    Domain Backstage: payments

Quando a nomenclatura é consistente, o plugin Kubernetes do Backstage consegue encontrar todos os pods de um serviço em cada cluster com um único label selector. O plugin ArgoCD consegue exibir o status de sync por ambiente. Sem mapeamento manual. Sem planilhas.

Templates Backstage como caminhos dourados​

A camada de self-service é um conjunto de templates do Backstage Scaffolder — um por operação da plataforma:

• create-domain — cria o limite de propriedade, o repositório GitOps e o AppProject ArgoCD
• create-system — cria um agrupamento de produto, seu ApplicationSet e base para TechDocs
• create-service — estrutura um Repositório de Aplicação (com Dockerfile, workflow de CI e base para TechDocs), gera manifestos Kubernetes por ambiente, registra a entrada no catálogo e abre os PRs
• create-resource — cria Claims Crossplane para infraestrutura de nuvem (bancos de dados, filas, buckets)
• create-secret — fornece criptografia segura de segredos via self-service usando Sealed Secrets
• create-group / create-user — onboarda times e engenheiros com RBAC correto desde o primeiro dia

Um engenheiro de produto executa create-service, seleciona seu sistema, nomeia o serviço, escolhe um perfil de recursos e clica em Create. Dois PRs são abertos automaticamente. Quando ambos são mesclados, o ArgoCD detecta o novo elemento do ApplicationSet e sincroniza o serviço com o cluster de dev. O serviço está rodando em menos de 30 minutos sem nenhuma intervenção da equipe de plataforma.

Validação de convenção na CI​

Os templates garantem a saída correta no momento da criação. A validação da CI mantém os repositórios corretos ao longo do tempo.

Todo repositório GitOps de domínio inclui um workflow do GitHub Actions (validate-conventions.yaml) gerado pelo create-domain. Em cada PR ele roda o validate-namespaces.sh e verifica:

• Nomenclatura de namespace segue {project}-{env}-{service}
• Todas as 9 labels obrigatórias estão presentes
• Todo container tem requests e limits de recursos
• Manifestos Kubernetes passam na validação de schema (kubeconform)
• Dry-run diff do ArgoCD contra o cluster de dev passa

Violações de convenção bloqueam o merge do PR. Não existe caminho de exceção.

Infraestrutura de nuvem como código — sem expertise em Terraform​

Recursos de nuvem (bancos de dados, filas, armazenamento) são declarados como Claims do Crossplane commitados no Git. O ArgoCD os sincroniza com o cluster. O Crossplane provisiona o recurso real no GCP, AWS, Azure ou IBM.

Um desenvolvedor solicitando uma instância Cloud SQL não escreve Terraform. Ele executa create-resource, seleciona GCP → Cloud SQL, preenche um formulário e mescla o PR. O Claim cai em crossplane/claims/prod/cloudsql-main.yaml. O Crossplane reconcilia continuamente — o drift é corrigido automaticamente. deletionPolicy: Orphan nos Claims de produção significa que um kubectl delete acidental não pode destruir um banco de dados.

A página de Resource do Backstage para esse banco de dados exibe READY: True e SYNCED: True assim que o provisionamento é concluído. Sem cavar no console da nuvem.

RBAC sem o fardo de manutenção​

O acesso é concedido via grupos do provedor de identidade, nunca usuários individuais. Remover alguém do time GitHub ou do grupo Okta revoga imediatamente todo acesso ao Kubernetes — sem limpeza manual de RoleBinding.

O papel developer não tem RoleBinding criado para namespaces de produção. Não por convenção. Não por documentação. Pelo fato de que o binding simplesmente não existe. O acesso a produção exige elevação explícita de papel.

Gerenciamento seguro de segredos​

O acesso aos ambientes de produção é estritamente controlado, e a plataforma impõe uma regra rigorosa de "nenhum segredo em texto claro". Em vez de abrir tickets para gerenciar segredos, os desenvolvedores usam o template create-secret do Backstage. Eles criptografam seus segredos localmente usando kubeseal e preenchem o template. A plataforma abre automaticamente um PR com o manifesto SealedSecret diretamente no repositório GitOps do seu domínio. O serviço de plataforma sealed-secrets roda no cluster e lida com a descriptografia, garantindo que o gerenciamento seguro de segredos permaneça totalmente self-service.

Resultados até agora​

Estamos na Fase 1 do rollout. O primeiro time de domínio é totalmente autossuficiente:

• Criação de serviço: < 30 minutos (eram 2–5 dias)
• Tickets para a equipe de plataforma: em queda
• Namespaces com todas as labels obrigatórias: 100% (para novos serviços)
• Tempo de onboarding do engenheiro: < 2 horas (eram 1–3 dias)

A Fase 2 estenderá o self-service para todos os times de produto e trará observabilidade full-stack do Backstage para cada serviço. A Fase 3 migrará serviços e recursos de nuvem existentes para o catálogo.

O que aprendemos​

Convenções primeiro. Nenhuma integração de ferramenta funciona sem nomenclatura consistente. Investimos tempo na convenção antes de construir templates, e cada hora ali economizou dez horas de depuração de integrações de ferramentas.

Templates como mecanismo de aplicação. Documentação é ignorada. Templates tornam o caminho correto o único caminho. Se você pode executar create-service e obter um serviço funcionando, você não tem razão para fazer manualmente.

GitOps escala. Geradores de matriz ApplicationSet significam que adicionar um novo serviço a um novo cluster é uma linha em um arquivo YAML. O ArgoCD cuida do resto. Não criamos Applications manualmente.

Crossplane para IaC de nuvem pertence ao Kubernetes. Manter recursos de nuvem no mesmo loop de reconciliação que as cargas de trabalho de aplicação significa um lugar para olhar drift, um lugar para olhar status, um modelo RBAC para acesso.

Os requisitos completos, arquitetura e roadmap estão documentados no PRD da Plataforma. A convenção de nomenclatura e os padrões operacionais estão na Convenção da Plataforma.