Referência Rápida
Guia de Nomenclatura
payments - prod - api
│ │ └── service → Component Backstage (base) → gateway-api
│ └────────── env → sufixo de Application ArgoCD → gateway-api-prod
└──────────────────── project → Domain Backstage → payments
→ AppProject ArgoCD
gcp - payments - prod - cloudsql - main
│ │ │ │ └── nome
│ │ │ └──────────── tipo de recurso → spec.type: database
│ │ └───────────────────── env → ns infra: payments-prod-infra
│ └──────────────────────────────── project → Domain Backstage
└────────────────────────────────────── provider → compositionSelector.provider
Correspondência Entre Sistemas
payments → AppProject: payments → Domain: payments
gateway → ApplicationSet: gateway → System: gateway
gateway-api → Application base → Component: gateway-api
gateway-api-prod → Application instância → observado via plugin ArgoCD
payments-prod-api → Namespace de destino da Application → observado via plugin k8s
gcp-payments-prod-cloudsql-main → Claim Crossplane → entidade Resource
Labels Obrigatórias em Todo Namespace (9 no Total)
| Label | Exemplo | Propósito |
|---|---|---|
project | payments | Agrupar namespaces por domínio |
env | prod | Aplicar políticas, quotas, RBAC por ambiente |
service | api | Identificar a carga de trabalho |
team | team-payments | Propriedade para alertas |
backstage.io/domain | payments | Rastreabilidade → Domain Backstage |
backstage.io/system | gateway | Rastreabilidade → System Backstage |
backstage.io/component | gateway-api | Label selector do plugin k8s Backstage |
argocd/app | gateway-api-prod | Rastreabilidade → Application ArgoCD |
argocd/app-set | gateway | Rastreabilidade → ApplicationSet |
Navegação Entre Sistemas
# Namespace → Application ArgoCD
kubectl get ns payments-prod-api -o jsonpath='{.metadata.labels.argocd/app}'
# → gateway-api-prod
# Namespace → Component Backstage
kubectl get ns payments-prod-api -o jsonpath='{.metadata.labels.backstage\.io/component}'
# → gateway-api
# Application ArgoCD → namespace
argocd app get gateway-api-prod -o json | jq '.spec.destination.namespace'
# → payments-prod-api
# Todos os namespaces de um component (todos os envs, todos os clusters)
kubectl get ns -l backstage.io/component=gateway-api
# Todas as Applications ArgoCD de um sistema
argocd app list -l argocd/app-set=gateway
# Todos os namespaces de prod
kubectl get ns -l env=prod
# Status do Claim Crossplane
kubectl get cloudsqlinstance cloudsql-main -n payments-prod-infra
# NAME READY SYNCED EXTERNAL-NAME AGE
# cloudsql-main True True payments-prod-cloudsql-main 5m
Salvaguardas de Produção
| Salvaguarda | Como é aplicada |
|---|---|
| Sem deploy automático em prod | ArgoCD syncWindows: deny + templatePatch remove o bloco automated |
| Sem deleção acidental de DB | Crossplane deletionPolicy: Orphan em todos os Claims de prod |
| Sem bypass de convenção | GitHub Actions (validate-conventions.yaml) executa automaticamente validate-namespaces.sh para bloquear merges de PR |
| Bloqueio de prod para desenvolvedor | RoleBinding de Prod não criado para papel developer |
| Sem segredos em texto claro | Sealed Secrets via template create-secret do Backstage |
Matriz de Responsabilidades
| Aspecto | Responsável | Mecanismo |
|---|---|---|
| O que um component é | Backstage | Entidades Domain / System / Component |
| Quem é o dono | Backstage | spec.owner |
| Onde roda | Kubernetes | Label env + nome do namespace |
| Como é implantado | ArgoCD | ApplicationSet → Application |
| Que infraestrutura precisa | Crossplane | Claim → Composite → recurso em nuvem |
| Saúde em tempo de execução por env | Plugin k8s Backstage | Label selector em todos os clusters |
| Status de sync por env | Plugin ArgoCD Backstage | App selector |
| Infraestrutura READY/SYNCED | Plugin k8s Backstage | Label selector do CRD do Claim |
| Controle de acesso | Kubernetes RBAC | RoleBinding (sujeito Group) por namespace |
| Isolamento de tráfego | Kubernetes | NetworkPolicy por label project |
| Limites de recursos | Kubernetes | ResourceQuota por namespace |
| Aplicação de convenção | Templates + CI | Scaffolder + GitHub Actions validate |
Diagrama de Arquitetura Completo
┌─────────────────────────────────────────────────────────────────────────┐
│ Catálogo Backstage │
│ Domain System Component Resource │
│ payments gateway gateway-api gcp-payments-prod-cloudsql │
│ ├── aba k8s → saúde por env por cluster │
│ ├── aba argo → status de sync por env │
│ └── deps → cloudsql ← READY/SYNCED via k8s │
└──────────┬──────────────────────────────────┬───────────────────────────┘
│ plugins k8s + argocd │ plugin k8s (Claim CRD)
┌──────────▼──────────────┐ ┌────────────▼─────────────────────────┐
│ ArgoCD │ │ Clusters Kubernetes │
│ cluster-mgmt/argocd │ │ │
│ │ │ cluster-dev payments-dev-api │
│ AppProject: payments │ │ cluster-stg payments-staging-api │
│ AppProject: platform │ │ cluster-prod payments-prod-api │
│ │ │ │
│ AppSet: gateway ───┼───────┼►payments-<env>-api (por cluster) │
│ │ │ │
│ AppSet: crossplane ───┼───────┼►cluster-mgmt │
│ -claims │ │ payments-prod-infra/cloudsql-main │
│ │ │ READY: True SYNCED: True │
│ AppSet: platform ───┼───────┼►platform-<env>-monitoring │
└──────────┬───────────────┘ └──────────────┬────────────────────────┘
│ sincroniza │ Crossplane reconcilia
┌──────────▼───────────────────────────────────────▼───────────────────────┐
│ Repositórios Git │
│ platform-gitops/ <domain>-gitops/ │
│ ├── argocd/projects/ ├── k8s/<env>/<service>/ │
│ ├── argocd/applicationsets/ ├── crossplane/claims/<env>/<type>/ │
│ ├── crossplane/providers/ └── catalog/ │
│ ├── crossplane/xrds/ │
│ ├── crossplane/compositions/ Provedores de Nuvem │
│ ├── k8s/platform/ ────► GCP / AWS / Azure / IBM │
│ ├── k8s/rbac/ │
│ └── backstage-templates/ │
└──────────────────────────────────────────────────────────────────────────┘