Naming Convention
Kubernetes Namespaces
{project}-{env}-{service}
payments-dev-api
payments-staging-worker
payments-prod-frontend
platform-mgmt-monitoring
ArgoCD Resources
AppProject: {project} → payments
ApplicationSet: {system} → gateway
Application: {system}-{service}-{env} → gateway-api-prod
Backstage Entities
Domain: {project} → payments
System: {system} → gateway
Component: {system}-{service} → gateway-api
Resource: {provider}-{project}-{env}-{type}-{name} → gcp-payments-prod-gke-main
Group: {slug} → team-payments
User: {username} → jane-doe
Crossplane
Infra namespace: {project}-{env}-infra → payments-prod-infra
Claim name: {resourceType}-{name} → cloudsql-main
XR name: {project}-{env}-{type}-{name} → payments-prod-cloudsql-main
ArgoCD App: crossplane-{project}-{env}-{type}-{name}
Backstage entity: {provider}-{project}-{env}-{type}-{name}
Rules That Apply Everywhere
| Rule | Reason |
|---|---|
| Lowercase, hyphen-separated | DNS-safe and valid in all systems |
| Max 63 characters per segment | Kubernetes namespace limit |
| No version or region in names | Use labels for those dimensions |
No env in Backstage entity names | Entities are env-agnostic; env is observed at runtime |
platform-* prefix for shared infra | Visually separates app from infra namespaces |
Reserved Namespaces
| Namespace | Status | Reason |
|---|---|---|
argocd | Fixed | ArgoCD hardcodes this name internally |
kube-system | Reserved | Kubernetes internals |
default | Avoid | Never deploy application workloads here |
crossplane-system | Fixed | Crossplane controllers |
platform-mgmt-* | Convention | Platform services on the management cluster |
platform-{env}-* | Convention | Platform services per environment |
{project}-{env}-{service} | Convention | Application workloads |
{project}-{env}-infra | Convention | Crossplane Claims per domain per env |