Overview
Unified naming, organizational, and operational convention across Kubernetes, ArgoCD, Backstage, and Crossplane. One semantic key drives every layer — no manual translation, no drift.
The Platform Model
The semantic key that maps every resource across Backstage, ArgoCD, Kubernetes, and Crossplane — project, env, service — and how it connects all platform layers.
Naming Convention
Standard naming patterns for Kubernetes namespaces, ArgoCD resources, Backstage entities, and Crossplane claims. Rules, reserved namespaces, and cross-system mapping.
Repository Strategy
Two-tier Git repository layout separating platform-gitops from domain-gitops. Responsibility split, ApplicationSet patterns, branch strategy, and CODEOWNERS enforcement.
Kubernetes
Kubernetes namespace conventions — 9 required labels, NetworkPolicy isolation by project, ResourceQuota per environment, and workload security defaults.
ArgoCD
ArgoCD architecture — cluster topology, AppProjects as domain boundaries, ApplicationSet matrix generators, Crossplane git-directory generators, and the app-of-apps bootstrap.
Backstage
Backstage catalog design — Domain, System, Component, and Resource entities. Kubernetes and ArgoCD plugin integration, label selectors, and catalog registration.
IaC — Crossplane
Crossplane IaC architecture — Providers, XRDs, Compositions managed by platform team. Claims managed by domain teams. Infra namespaces, deletion policies, and Backstage integration.
Platform Services
Platform services catalog — Tier A (all clusters) and Tier B (mgmt only). Sync wave ordering from sealed-secrets at wave -20 to headlamp at wave +10.
People — Groups and Users
Group and User entity conventions for Backstage. RBAC model with 4 roles — viewer, developer, lead, platform-engineer. Group-based access, developer prod block.
Backstage Templates
Backstage Scaffolder template chain — create-domain, create-system, create-service, create-resource, create-secret, create-group, create-user. Dependency order, PR workflow, and Scaffolder packages.
Quick Reference
Quick reference cheat sheet — naming patterns, label requirements, kubectl queries, ArgoCD commands, Backstage navigation, and common mistakes to avoid.
Application Repositories
Convention for application repositories scaffolded via Golden Paths — base source code, Dockerfile, CI pipeline, and .k8s folder with ArgoCD Multiple Sources for workload overrides.