Templates Backstage

A Cadeia de Templates

Os templates codificam toda a convenção da plataforma. Os desenvolvedores preenchem um formulário — os templates geram todo YAML, PR e registro no catálogo automaticamente.

Camada de pessoas (execute a qualquer momento)
──────────────────────────────────────────────────────────────────
 create-group  →  Entidade Group + RBAC + instruções de papel ArgoCD
 create-user   →  Entidade User  + RBAC + instruções de usuário ArgoCD

Camada de plataforma (execute em ordem)
──────────────────────────────────────────────────────────────────
 create-domain
      │  Entidade Domain, repositório {domain}-gitops criado, AppProject
      ▼
 create-system
      │  Entidade System, ApplicationSet skeleton (vazio)
      ▼
      ├── create-service          ├── create-resource   ├── create-secret
      │   Entidade Component,     │   Entidade Resource,│   SealedSecret/env
      │   App Repo (CI/CD, docs)  │   Claim Crossplane  │
      │   manifestos k8s/env,     │   namespace de infra│
      │   serviço → AppSet        │                     │
      ▼                           ▼
   [merge PR domínio]          [merge PR domínio]
   [merge PR plataforma]       [merge PR catálogo]

O que Cada Template Produz

Template	Novo repositório?	PR 1 destino	PR 2 destino
create-domain	✅ <domain>-gitops	repositório do domínio (entidade, padrões, CI)	platform-gitops (AppProject)
create-system	❌	domain-gitops (entidade System + TechDocs)	platform-gitops (ApplicationSet)
create-service	✅ <app>-repo	domain-gitops (manifests + Component)	novo app-repo (CI/CD + TechDocs), platform-gitops (AppSet element)
create-resource	❌	domain-gitops (Claims + namespace)	repositório do catálogo (entidade Resource)
create-secret	❌	domain-gitops (SealedSecret)	(nenhum)
create-group	❌	repositório do catálogo (entidade Group)	platform-gitops (RBAC)
create-user	❌	repositório do catálogo (entidade User)	platform-gitops (RBAC)

Arquivos Gerados por Template

create-domain — novo repositório + PR AppProject

{domain}-gitops/
├── README.md                     ← referência de convenção + contatos
├── CODEOWNERS
├── catalog-info.yaml             ← registro de Location no Backstage
├── catalog/domain.yaml           ← entidade Domain
├── k8s/_defaults/
│   ├── resourcequota.yaml        ← template de quota (dimensionado por perfil)
│   └── networkpolicy.yaml        ← política de isolamento padrão
└── .github/
    ├── pull_request_template.md  ← checklist de PR aplicando convenção
    └── workflows/validate-conventions.yaml ← CI: kubeconform + verificações de nomenclatura e label

platform-gitops/argocd/projects/{domain}.yaml  ← AppProject + papéis RBAC + sync windows

create-system — Entidade System + ApplicationSet

domain-gitops/catalog/systems/{system}.yaml             ← entidade System
domain-gitops/docs/index.md                             ← base para TechDocs
domain-gitops/mkdocs.yml                                ← configuração TechDocs
domain-gitops/catalog-info.yaml                         ← lista de targets atualizada
platform-gitops/argocd/applicationsets/{domain}-{system}.yaml  ← AppSet (elements: [])

create-service — manifestos k8s + Component + atualização do AppSet

{app-repo}/
  Dockerfile       ← instruções de build base
  mkdocs.yml       ← configuração TechDocs
  docs/index.md    ← base para TechDocs
  .github/workflows/ci.yaml  ← Workflow de build e push

domain-gitops/k8s/{env}/{service}/
  namespace.yaml   ← conjunto de 9 labels
  deployment.yaml  ← dimensionado por env + serviceType + perfil de recursos
  service.yaml     ← ClusterIP (omitido para worker/cronjob)
  config.yaml      ← ServiceAccount + ConfigMap
  policies.yaml    ← HPA + PDB (prod) + ResourceQuota + NetworkPolicy

domain-gitops/catalog/components/{system}-{service}.yaml  ← entidade Component
platform-gitops/argocd/applicationsets/{domain}-{system}.yaml  ← elemento de serviço adicionado

create-resource — Claims Crossplane + entidade Resource

domain-gitops/crossplane/claims/namespace.yaml              ← namespaces de infra
domain-gitops/crossplane/claims/{env}/{type}-{name}.yaml    ← Claim por ambiente
catalog-repo/catalog/resources/{provider}-{domain}-{env}-{type}-{name}.yaml

create-secret — SealedSecrets

domain-gitops/k8s/{env}/{service}/sealedsecret-{name}.yaml  ← segredo criptografado

create-group — Entidade Group + RBAC

catalog-repo/groups/{groupName}.yaml                        ← entidade Group
platform-gitops/k8s/rbac/groups/{groupName}.yaml            ← RoleBinding por domínio/env
platform-gitops/k8s/rbac/groups/{groupName}-argocd-patch.yaml  ← instruções AppProject

create-user — Entidade User + RBAC

catalog-repo/users/{username}.yaml                          ← entidade User
platform-gitops/k8s/rbac/users/{username}.yaml              ← RoleBinding por domínio/env
platform-gitops/k8s/rbac/users/{username}-argocd-patch.yaml    ← instruções AppProject

Seletores de Catálogo Aplicam Integridade Referencial

Os templates usam EntityPicker — você seleciona do que já existe no catálogo. Não é possível criar um System para um Domain que não existe:

create-system  → seleciona Domain   → nome do domínio + URL do repositório resolvidos da entidade
create-service → seleciona System   → domínio + AppProject + política de sync todos derivados
create-resource → seleciona Domain  → prefixo do namespace de infra derivado
create-user    → seleciona Groups   → escopo de RBAC derivado da associação ao grupo

Validação de Convenção na CI

create-domain gera um workflow do GitHub Actions para cada repositório de domínio. Ele aplica regras automaticamente, bloqueando merges de PR se ocorrerem violações:

.github/workflows/validate-conventions.yaml
  kubeconform   — valida todo YAML contra schemas da API Kubernetes
  naming check  — roda validate-namespaces.sh (todo namespace segue {domain}-{env}-{service})
  label check   — todas as 9 labels obrigatórias presentes nos arquivos de namespace
  argocd diff   — dry-run diff contra o cluster de dev

Registro de Templates

# platform-gitops/backstage-templates/catalog-info.yaml
apiVersion: backstage.io/v1alpha1
kind: Location
metadata:
  name: platform-templates
spec:
  targets:
    - ./create-domain/template.yaml
    - ./create-system/template.yaml
    - ./create-service/template.yaml
    - ./create-resource/template.yaml
    - ./create-secret/template.yaml
    - ./create-group/template.yaml
    - ./create-user/template.yaml

# app-config.yaml
catalog:
  locations:
    - type: url
      target: https://github.com/myorg/platform-gitops/blob/main/backstage-templates/catalog-info.yaml
      rules:
        - allow: [Template]

Ações Scaffolder Necessárias

yarn workspace backend add \
  @backstage/plugin-scaffolder-backend-module-github \
  @roadiehq/scaffolder-backend-module-utils

Ação	Pacote	Usado por
fetch:template	built-in	todos
catalog:fetch	built-in	create-system, service, resource, user, group
catalog:register	built-in	todos
publish:github	@backstage/plugin-scaffolder-backend-module-github	create-domain apenas
publish:github:pull-request	@backstage/plugin-scaffolder-backend-module-github	todos
roadiehq:utils:jsonata	@roadiehq/scaffolder-backend-module-utils	create-system, service, resource, user, group

Fluxos de Onboarding — Ordem de Merge

Onboarding de um Novo Time

1. create-group → merge PR do catálogo → merge PR da plataforma
2. create-user  → repetir por membro

Onboarding de um Novo Domínio

Equipe de plataforma                     Equipe de domínio
──────────────────────────────────────────────────────────
create-domain → merge PR AppProject
                                     create-system  → merge ambos os PRs
                                     create-service → merge ambos os PRs (repetir por serviço)
                                     create-resource → merge ambos os PRs (opcional)
create-group  → merge ambos os PRs
create-user   → repetir por membro