Pular para o conteúdo principal

Requisitos

Requisitos Funcionais​

RF1 — Convenção de Nomenclatura​

  • Todo namespace Kubernetes segue o padrão {project}-{env}-{service}
  • Todo namespace carrega todas as 9 labels obrigatórias: project, env, service, team, backstage.io/domain, backstage.io/system, backstage.io/component, argocd/app, argocd/app-set
  • Nomes de entidades Backstage são agnósticos de ambiente: {system}-{service} para Components, {provider}-{project}-{env}-{type}-{name} para Resources
  • Nomes de Applications ArgoCD seguem {system}-{service}-{env}

RF2 — Repositórios GitOps​

  • Um repositório platform-gitops de propriedade da equipe de plataforma contendo AppProjects, ApplicationSets, XRDs/Compositions do Crossplane, RBAC e templates do Backstage
  • Um repositório {domain}-gitops por domínio contendo manifestos k8s, Claims do Crossplane e entidades do catálogo Backstage
  • Um repositório de aplicação {app}-repo por serviço contendo o código-fonte, Dockerfile, TechDocs e pipelines de CI
  • Repositórios de domínio são criados automaticamente pelo template create-domain do Backstage, e repositórios de aplicação pelo create-service

RF3 — Entrega via ArgoCD​

  • Todo domínio tem um AppProject que restringe repositórios de origem e namespaces de destino
  • Serviços são implantados via geradores de matriz ApplicationSet (serviços × clusters)
  • Applications em Prod exigem sync manual — aplicado via syncWindows e templatePatch
  • Sync windows negam deploys automatizados em prod nas noites de dias úteis e fins de semana
  • ignoreDifferences do ArgoCD em /spec/replicas evita sobrescrever decisões do HPA
  • Claims do Crossplane são implantados via ApplicationSets com gerador git-directory

RF4 — Catálogo Backstage​

  • Entidades Domain, System, Component, Resource, Group e User para todo ativo da plataforma
  • backstage.io/kubernetes-label-selector em todo Component exibe saúde em todos os clusters com uma única annotation
  • argocd/app-selector em todo Component exibe o status de sincronização por ambiente
  • backstage.io/kubernetes-label-selector em todo Resource exibe o status READY/SYNCED do Claim Crossplane
  • Catálogo registrado via entidades de Location em catalog-info.yaml por repositório de domínio

RF5 — Provisionamento de Recursos de Nuvem (Crossplane)​

  • Recursos de nuvem declarados como Claims do Crossplane em {domain}-gitops/crossplane/claims/{env}/
  • Namespaces de infra {domain}-{env}-infra isolados dos namespaces de aplicação
  • deletionPolicy: Orphan como padrão em todos os Claims de produção
  • Segredos de conexão escritos no namespace de infra após o provisionamento
  • Provedores suportados: GCP, AWS, Azure, IBM
  • Tipos de recursos suportados: clusters (GKE/EKS/AKS/IKS), bancos de dados (Cloud SQL/RDS/PostgreSQL/Cosmos), filas (Pub/Sub/SQS/Service Bus/Event Streams), armazenamento (GCS/S3/Blob/COS), cache (Memorystore/ElastiCache/Redis), registries, secret stores

RF6 — RBAC e Controle de Acesso​

  • RoleBindings do Kubernetes usam sujeitos de Grupo apenas (nunca sujeitos de Usuário individuais para acesso rotineiro)
  • Quatro papéis de plataforma: viewer, developer, lead, platform-engineer
  • Papel developer: nenhum RoleBinding criado para namespaces de prod
  • Papel platform-engineer: ClusterRoleBinding para namespaces platform-*
  • Papéis de projeto ArgoCD: readonly, developer (sync apenas em dev/staging), domain-admin
  • RBAC aplicado exclusivamente via templates Backstage (create-group, create-user)

RF7 — Templates Scaffolder do Backstage​

TemplateGatilhoSaída
create-domainOnboarding de nova área de produtoEntidade Domain, repositório {domain}-gitops, AppProject
create-systemAdição de novo agrupamento de produtoEntidade System, ApplicationSet, base para TechDocs
create-serviceAdição de nova carga de trabalhoNovo {app}-repo (CI/CD, TechDocs), manifestos k8s por ambiente, entidade Component, elemento do AppSet
create-resourceSolicitação de infraestrutura de nuvemClaims Crossplane por ambiente, entidades Resource
create-secretCriptografia de dados sensíveisManifestos SealedSecret enviados de forma segura para o domain-gitops
create-groupOnboarding de nova equipeEntidade Group, bindings RBAC, papéis ArgoCD
create-userOnboarding de novo engenheiroEntidade User, bindings RBAC, usuário ArgoCD

Todos os templates usam EntityPicker para garantir integridade referencial — uma entidade filha não pode ser criada sem que seu pai já exista no catálogo.

RF8 — CI de Validação de Convenção​

  • Todo repositório de domínio contém .github/workflows/validate-conventions.yaml gerado pelo create-domain
  • Verificações: validação de schema kubeconform, padrão de nomenclatura de namespaces via validate-namespaces.sh, todas as 9 labels obrigatórias, requests/limits de recursos em todos os containers, dry-run diff do ArgoCD contra o cluster de dev
  • Violações de convenção reprovam o PR — o merge é bloqueado

Requisitos Não-Funcionais​

RNF1 — Confiabilidade​

  • ArgoCD: 99,9% de uptime no cluster de gerenciamento
  • Backstage: 99,5% de uptime; funcionalidade degradada aceitável durante interrupções
  • Crossplane: loop de reconciliação contínua — drift corrigido em até 5 minutos após a detecção

RNF2 — Performance​

  • Carregamento de página do catálogo Backstage: < 2 segundos (p95)
  • Latência de sync do ArgoCD: < 60 segundos do push até a atualização do namespace
  • Tempo de execução do template create-service: < 3 minutos de ponta a ponta

RNF3 — Segurança​

  • Nenhum segredo em texto plano no Git — Sealed Secrets self-service via template create-secret
  • Isolamento de rede aplicado por NetworkPolicy em todo namespace (negar tudo por padrão)
  • Padrões de segurança de Pod: runAsNonRoot, readOnlyRootFilesystem, allowPrivilegeEscalation: false
  • Sync windows de prod: syncs automatizados negados fora do horário comercial
  • Autenticação OIDC para Backstage, ArgoCD e Headlamp

RNF4 — Escalabilidade​

  • A plataforma deve suportar 20+ domínios, 100+ sistemas, 500+ serviços sem mudanças arquiteturais
  • O gerador de matriz ApplicationSet escala linearmente — nenhuma criação manual de Application necessária
  • O gerador git-directory do Crossplane descobre novos Claims automaticamente sem mudanças no ApplicationSet

RNF5 — Observabilidade​

  • Todos os serviços de plataforma instrumentados com métricas Prometheus
  • Logs enviados ao Loki central via Alloy em cada cluster
  • Plugin k8s do Backstage exibe saúde dos pods e eventos recentes por componente por ambiente
  • Status READY/SYNCED do Claim Crossplane exibido nas páginas de Resource do Backstage

RNF6 — Experiência do Desenvolvedor​

  • P1 (Engenheiro de Produto) pode criar um novo serviço sem nenhuma interação com a equipe de plataforma
  • Todo conhecimento necessário está codificado em templates — nenhuma documentação externa necessária durante o fluxo normal
  • CI de validação de convenção fornece mensagens de erro acionáveis