O ROI de Nomear as Coisas: Como Uma Chave de 3 Segmentos Eliminou a Confusão Entre Times
Nomear coisas é famosamente o problema mais difícil da ciência da computação. É também, silenciosamente, um dos mais caros. Quando quatro equipes diferentes nomeiam seus namespaces de quatro formas diferentes, o custo aparece em incidentes que demoram mais para diagnosticar, em onboardings que viram sessões de conhecimento tribal, e em um time de plataforma que gasta suas semanas traduzindo entre sistemas ao invés de construir.
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:
| Pergunta | Sem convenção | Com convenção |
|---|---|---|
| Qual app do ArgoCD gerencia este namespace? | Pergunte a alguém, consulte planilha | Leia o label argocd/app |
| Qual time é responsável? | Verifique JIRA, Slack ou git blame | Leia o label team |
| Quais pods pertencem a este serviço em todos os envs? | kubectl manual em cada cluster | kubectl get ns -l backstage.io/component=gateway-api |
| Este serviço está saudável em prod? | Abra Grafana, ArgoCD, kubectl separadamente | Abra uma página de Component no Backstage |
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
| Segmento | O que significa | Onde aparece |
|---|---|---|
project | Fronteira de propriedade (domínio) | Domain no Backstage, AppProject no ArgoCD, prefixo do namespace |
env | Alvo de implantação | Label do cluster, segmento do meio do namespace |
service | Carga de trabalho individual | Sufixo do namespace, sufixo do Component no Backstage |
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:
| Métrica | Antes | Depois |
|---|---|---|
| Tempo para responder "quem é dono deste namespace?" | 5–15 min (pergunte por aí) | 0 seg (leia o label) |
| Referência cruzada entre ferramentas em incidentes | Manual, propenso a erros | Automático via labels |
| Bootstrapping de novo serviço | 8–15 passos manuais | 1 template, 2 PRs |
| Namespaces com todos os labels obrigatórios | < 20% | 100% (novos serviços) |
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.