The Application Repository convention changes this. When a new service is scaffolded via Backstage, it delivers a complete, opinionated repository with source code, Dockerfile, CI pipeline, and a .k8s folder — giving the application team autonomy over their workload configuration while keeping the platform in control of the deployment model.

The architecture: two repos, one deployment​

Our GitOps model uses a clear separation between deployment configuration and application configuration:

{domain}-gitops/k8s/{env}/{service}/    ← Platform-managed base manifests
{app}-repo/.k8s/values.yaml             ← Developer-managed overrides

The domain GitOps repository contains the foundational Kubernetes configuration — Deployments, Services, NetworkPolicies, HPA, PDB — generated by the create-service template and maintained by the domain team's platform conventions.

The application repository contains a .k8s folder where the development team manages values that change frequently with application releases.

ArgoCD's Multiple Sources pattern merges both sources at sync time. The base manifests from the GitOps repo provide structure and safety. The application overrides provide flexibility and speed.

What developers can override​

The .k8s/values.yaml in the application repository gives developers control over:

• Image tag: Updated automatically by CI on every successful build
• Replicas: Override min/max HPA thresholds for specific workload needs
• CPU and memory: Adjust requests and limits as the application's profile evolves
• Environment variables: Application-specific configuration that changes with releases

These are the values that change most frequently and are most directly tied to the application code. By keeping them in the app repo, developers don't need a PR on the GitOps repo every time they push a release.

What developers don't touch​

The base manifests in {domain}-gitops/k8s/ remain under platform convention control:

• Namespace definition with all 9 required labels
• Security context: runAsNonRoot, readOnlyRootFilesystem, capabilities: drop: [ALL]
• NetworkPolicy: project-boundary isolation
• PodDisruptionBudget: prod-only safety net
• ResourceQuota: env-sized limits

This separation ensures that security and compliance guarantees are never accidentally overridden by a developer who "just needs to change the memory limit."

The CI pipeline: from commit to deploy​

Every application repository scaffolded by create-service includes a pre-configured GitHub Actions workflow. The pipeline is not something the team needs to write — it arrives ready:

Developer pushes code
        │
        ▼
┌─── CI Pipeline ────────────────────────────────────┐
│                                                     │
│  1. Test & Lint      Run unit tests, lint checks   │
│  2. Build            Build container from Dockerfile│
│  3. Publish          Push image to container registry│
│  4. Tag Update       Update .k8s/values.yaml with  │
│                      new image tag, commit back     │
│                                                     │
└─────────────────────────────────────────────────────┘
        │
        ▼
ArgoCD detects change in app repo (secondary source)
        │
        ▼
Deployment syncs with new image tag

The key step is Tag Update. After publishing the container image, the pipeline automatically updates image.tag in .k8s/values.yaml and commits the change back to the application repository. This commit is what ArgoCD watches.

Because ArgoCD is configured with Multiple Sources — one pointing at the GitOps repo for base manifests, one pointing at the app repo for overrides — the new tag triggers an automatic sync to the target environment.

No manual image tag updates. No separate "deploy" step. Push code, get deployment.

The Dockerfile: secure by default​

The scaffolded Dockerfile follows platform security standards:

• Multi-stage build: Separate build and runtime stages to minimize image size
• Non-root user: USER 1000 — matches the pod security context (runAsNonRoot: true)
• Read-only filesystem compatible: Application writes go to /tmp (mounted as emptyDir)
• Language-specific optimization: Node.js, .NET, and Python each get a tailored Dockerfile with appropriate base images and dependency caching

The developer does not need to know about pod security contexts or read-only filesystems. The Dockerfile and the Kubernetes manifests are designed to work together from day one.

The full picture​

When create-service runs, the developer gets:

Three repositories, three ownership boundaries, one deployment that works without manual coordination.

Why not everything in the app repo?​

A common question: "Why not put all Kubernetes manifests in the application repository?"

Because it breaks the ownership model:

1. Security context and network policies are platform concerns, not application concerns. Developers should not need to (or be able to) modify them.
2. Multiple services share the same ApplicationSet and domain structure. Centralizing this in the GitOps repo avoids duplication and ensures consistency.
3. Convention validation runs on the GitOps repo. CI checks for naming, labels, and security defaults happen where those definitions live.

The .k8s folder gives developers the autonomy they need — image tags, scaling, resources — without giving them access to the things they should not change.

The Application Repositories convention is documented in the Platform Convention — Application Repositories. The ArgoCD Multiple Sources pattern is in the ArgoCD Convention.

Backstage Scaffolder templates change this equation. Instead of documenting the correct path and hoping engineers follow it, we encode the correct path into a form that produces correct output every time. This post is about how our template chain works, why the dependency order matters, and what happens when you click Create.

The problem with documentation-driven standards​

Our platform convention defines a precise naming pattern, 9 required labels, security defaults, and a specific repository structure. Before templates, applying these standards meant:

1. Reading 3 different wiki pages
2. Copy-pasting YAML from examples (often outdated)
3. Hoping the reviewer catches what you missed
4. Waiting for the platform team to fix what the reviewer missed

The result: 80% of new services needed at least one correction PR after the initial creation. Convention compliance was aspirational.

Templates as enforcement​

A Backstage Scaffolder template is a YAML definition that combines a user-facing form with a sequence of automated actions. The developer fills in the form. The template generates all the files, opens the PRs, and registers the entity in the catalog.

The template does not document the convention — it implements the convention. There is no way to create a service with missing labels, wrong naming, or incorrect security context, because the template generates all of those.

The template chain​

Templates have dependencies. You cannot create a service without a system. You cannot create a system without a domain. The chain enforces this order:

People layer (run any time)
──────────────────────────────────────────────────────
 create-group → Group entity + RBAC + ArgoCD roles
 create-user  → User entity  + RBAC + ArgoCD access

Platform layer (run in order)
──────────────────────────────────────────────────────
 create-domain
      │  Domain entity, {domain}-gitops repo, AppProject
      ▼
 create-system
      │  System entity, ApplicationSet
      ▼
      ├─────────────────────────┬─────────────────────┐
      ▼                         ▼                     ▼
 create-service          create-resource         create-secret
 Component entity,       Resource entity,        SealedSecret
 App Repo (CI/CD,        Crossplane Claim/env,   manifest/env
 TechDocs, .k8s),        infra namespace
 k8s manifests/env

Each template uses EntityPicker to select its parent. You pick the domain from a dropdown that only shows existing domains. You pick the system from a dropdown filtered to that domain's systems. Referential integrity is enforced by the UI itself.

What create-service actually does​

When a product engineer runs create-service, they fill in:

• System: selected from catalog (domain, repo, AppProject resolve automatically)
• Service name: e.g., api, worker, frontend
• Service type: api / worker / frontend / grpc / cronjob
• Container image: registry path
• Resource profile: which CPU/memory tier
• Target environments: which envs to deploy to

Then the template executes:

Step 1 — Generate the Application Repository​

A new repository is created with:

{app}-repo/
├── src/                    ← boilerplate source code
├── Dockerfile              ← optimized, non-root, language-specific
├── .github/workflows/
│   └── ci.yaml             ← lint, test, build, publish, tag update
├── .k8s/
│   └── values.yaml         ← overrides (image tag, replicas, resources)
├── docs/
│   └── index.md            ← TechDocs base
└── catalog-info.yaml       ← Backstage Component entity

Step 2 — Generate Kubernetes manifests in the domain repo​

In {domain}-gitops/k8s/{env}/{service}/, the template creates:

• Namespace with all 9 required labels
• Deployment with security context, resource limits, readiness/liveness probes
• Service exposing the correct port
• HPA with env-appropriate scaling (dev: 1→2, staging: 2→5, prod: 3→10)
• PDB (prod only, minAvailable: 1)
• NetworkPolicy isolating by project boundary

Step 3 — Update the ApplicationSet​

In platform-gitops, the template adds the new service as an element in the existing ApplicationSet:

elements:
  - service: api      # ← existing
  - service: worker   # ← added by template

Step 4 — Register and open PRs​

The template opens two PRs:

1. Domain repo PR: k8s manifests + Component entity
2. Platform repo PR: ApplicationSet element

It also registers the new catalog-info.yaml in the Backstage catalog.

Merge order matters: Platform PR first (ApplicationSet must exist before ArgoCD can sync), then domain PR. Within minutes of both merging, the service is running on the dev cluster.

The two-PR workflow​

Every template follows the same pattern: one PR on the domain/catalog repo, one PR on platform-gitops. This separation exists because:

• Domain teams own their manifests — they review and merge what they deploy
• Platform team owns the routing — they review changes to ArgoCD config and RBAC
• CODEOWNERS enforce this — wrong-repo changes get blocked automatically

Results​

Since adopting templates:

• 100% label compliance on all new services (was < 20%)
• < 3 minutes from clicking Create to PRs opened (was hours of manual YAML)
• Zero convention violations on template-generated services
• Service running in dev in < 30 minutes (was 2–5 days)

The templates did not just make service creation faster — they made convention violations structurally impossible for new services. The "correct way" is the only way.

The full template chain and output summary are documented in the Platform Convention — Templates. The Backstage entity model and catalog design are in the Backstage Convention.

This post is about how a single naming convention — three segments, one key — unified Kubernetes, ArgoCD, Backstage, and Crossplane. And why the return on investment was measured in days saved per week.

The cost of naming drift​

Before the convention, every team had its own style:

• Team A named namespaces payments-api-prod
• Team B used prod-orders-backend
• Team C went with frontend_staging

None of these are wrong. All of them are incompatible. When an incident hit payments-api-prod, the first question was always: "What ArgoCD application manages this?" Nobody knew without digging. The answer lived in someone's head, or in a spreadsheet last updated three months ago.

The real cost was not the naming itself — it was the manual mapping required every time a human or a tool needed to cross-reference systems:

Each of these questions cost 5–15 minutes per occurrence. Multiply by the number of engineers asking them daily, and naming drift was consuming hours per week across the organization.

The semantic key​

The convention is simple. Every resource in the platform is addressed by three segments:

{project}-{env}-{service}

payments-prod-api

The key insight is that this is not just a naming pattern — it is a contract. When the naming is consistent, tools can talk to each other without a human in the middle.

How one key connects four systems​

Here is the full mapping for a single service:

Backstage Domain:    payments          ← project
ArgoCD AppProject:   payments          ← project
Backstage System:    gateway           ← logical grouping
ArgoCD ApplicationSet: gateway        ← logical grouping
Backstage Component: gateway-api      ← system + service
ArgoCD Application:  gateway-api-prod ← system + service + env
Kubernetes Namespace: payments-prod-api ← project + env + service

When a developer opens the Backstage Component page for gateway-api, the Kubernetes plugin finds pods across all clusters using a single label selector: project=payments,service=api. No configuration per environment. No manual registration of each cluster's namespace. The label does the work.

The ArgoCD plugin surfaces sync status per environment using the same label approach. The dependency graph shows which databases and queues this service connects to.

One name, one query, one page, one source of truth.

The 9 labels that make it work​

Every namespace in the platform carries 9 required labels:

labels:
  project: payments               # domain
  env: prod                       # environment
  service: api                    # workload
  team: team-payments             # owning team
  backstage.io/domain: payments   # → Backstage Domain
  backstage.io/system: gateway    # → Backstage System
  backstage.io/component: gateway-api  # → Backstage Component
  argocd/app: gateway-api-prod    # → ArgoCD Application
  argocd/app-set: gateway         # → ArgoCD ApplicationSet

Missing any of these labels fails the PR in CI. There is no exception path. This is not enforced by documentation — it is enforced by code.

The business impact​

After rolling out the convention to the first domain team:

The convention is the cheapest thing we built and the highest ROI investment in the entire platform. Every tool integration, every automation, every dashboard depends on it. Without consistent naming, the platform is just a collection of tools. With it, the platform is a product.

The lesson​

Invest in naming before investing in tooling. A perfect ArgoCD setup with inconsistent namespace names is worse than a basic setup with consistent ones. The naming convention is not a document to write after the architecture is done — it is the foundation the architecture is built on.

Every hour we spent getting the three-segment key right saved ten hours of debugging tool integrations later.

The full naming convention and cross-system mapping are documented in the Platform Convention. The business goals and success metrics are in the Platform PRD.

We hit that wall. This post is about how we got out of it.

The problem​

Before the IDP, onboarding a new service looked like this:

1. Open a JIRA ticket for namespace creation
2. Wait 2–5 days for the platform team to review it
3. Receive the namespace — with the wrong labels, or missing resource limits
4. Open another ticket for the ArgoCD application
5. Open another ticket for the database

Eight to fifteen manual steps across multiple tools. Every step required a human from the platform team. Every error required another round-trip.

The root cause was not a lack of automation. We had Terraform, we had Helm, we had ArgoCD. The problem was that none of it was self-service. The automation only ran when the platform team ran it.

What we built​

The IDP is four tools working together:

The key insight was that conventions are the product. A naming convention is not documentation — it is the contract that lets every tool talk to every other tool without a human in the middle.

The semantic key​

Every resource in the platform — namespace, ArgoCD application, Backstage entity, Crossplane claim — is addressed by the same three-segment key:

{project}-{env}-{service}

payments-prod-api
│         │     └── Kubernetes namespace: payments-prod-api
│         │         Backstage Component: gateway-api
│         └── ArgoCD Application: gateway-api-prod
└── ArgoCD AppProject: payments
    Backstage Domain: payments

When the naming is consistent, the Backstage Kubernetes plugin can find all pods for a service across every cluster with a single label selector. The ArgoCD plugin can surface sync status per environment. No manual mapping. No spreadsheets.

Backstage templates as golden paths​

The self-service layer is a set of Backstage Scaffolder templates — one per platform operation:

• create-domain — creates the ownership boundary, the GitOps repo, and the ArgoCD AppProject
• create-system — creates a product grouping, its ApplicationSet, and TechDocs base
• create-service — scaffolds an Application Repository (with Dockerfile, CI workflow, and TechDocs base), generates Kubernetes manifests per environment, registers the catalog entry, and opens the PRs
• create-resource — creates Crossplane Claims for cloud infrastructure (databases, queues, buckets)
• create-secret — provides self-service secure secrets encryption using Sealed Secrets
• create-group / create-user — onboards teams and engineers with correct RBAC from day one

A product engineer runs create-service, selects their system, names the service, picks a resource profile, and clicks Create. Two PRs are opened automatically. When both are merged, ArgoCD detects the new ApplicationSet element and syncs the service to the dev cluster. The service is running in under 30 minutes with zero platform team involvement.

Convention validation in CI​

Templates guarantee correct output at creation time. CI validation keeps repos correct over time.

Every domain GitOps repository includes a GitHub Actions workflow (validate-conventions.yaml) generated by create-domain. On every PR it runs validate-namespaces.sh and checks:

• Namespace naming matches {project}-{env}-{service}
• All 9 required labels are present
• Every container has resource requests and limits
• Kubernetes manifests pass schema validation (kubeconform)
• ArgoCD dry-run diff against the dev cluster passes

Convention violations block the PR merge. There is no exception path.

Cloud infrastructure as code — without Terraform expertise​

Cloud resources (databases, queues, storage) are declared as Crossplane Claims committed to Git. ArgoCD syncs them to the cluster. Crossplane provisions the actual resource on GCP, AWS, Azure, or IBM.

A developer requesting a Cloud SQL instance does not write Terraform. They run create-resource, select GCP → Cloud SQL, fill in a form, and merge the PR. The Claim lands in crossplane/claims/prod/cloudsql-main.yaml. Crossplane reconciles continuously — drift is corrected automatically. deletionPolicy: Orphan on production Claims means an accidental kubectl delete cannot destroy a database.

The Backstage Resource page for that database shows READY: True and SYNCED: True once provisioning completes. No digging through cloud console.

RBAC without the maintenance burden​

Access is granted via identity provider groups, never individual users. Removing someone from the GitHub or Okta group immediately revokes all Kubernetes access — no manual RoleBinding cleanup.

The developer role has no RoleBinding created for production namespaces. Not by convention. Not by documentation. By the fact that the binding does not exist. Production access requires explicit role elevation.

Secure secrets management​

Access to production environments is strictly controlled, and the platform enforces a strict "no plain-text secrets" rule. Instead of opening tickets to manage secrets, developers use the create-secret Backstage template. They encrypt their secrets locally using kubeseal and fill out the template. The platform automatically opens a PR with the SealedSecret manifest directly into their domain's GitOps repository. The platform service sealed-secrets runs in the cluster and handles the decryption, ensuring secure secrets management remains entirely self-service.

Results so far​

We are in Phase 1 of the rollout. The first domain team is fully self-sufficient:

• Service creation: < 30 minutes (was 2–5 days)
• Platform team tickets: trending down
• Namespaces with all required labels: 100% (for new services)
• Engineer onboarding time: < 2 hours (was 1–3 days)

Phase 2 will extend self-service to all product teams and bring Backstage full-stack observability to every service. Phase 3 migrates existing services and cloud resources into the catalog.

What we learned​

Conventions first. No tool integration works without consistent naming. We spent time on the convention before building templates, and every hour there saved ten hours of debugging tool integrations.

Templates as the enforcement mechanism. Documentation gets ignored. Templates make the correct path the only path. If you can run create-service and get a working service, you have no reason to do it manually.

GitOps scales. ApplicationSet matrix generators mean adding a new service to a new cluster is one line in a YAML file. ArgoCD handles the rest. We are not creating Applications by hand.

Crossplane for cloud IaC belongs in Kubernetes. Keeping cloud resources in the same reconciliation loop as application workloads means one place to look for drift, one place to look for status, one RBAC model for access.

The full requirements, architecture, and roadmap are documented in the Platform PRD. The naming convention and operational standards are in the Platform Convention.