OnCallReadyStart learning

Infrastructure as code Lesson 42.31 · Platform Engineering: Backstage & Crossplane · 7 min read

Putting it together: one golden path, end to end

In plain words

A golden path is a well-lit road through a forest. You can walk anywhere you like, but the lit road has signs, a bridge over the river and someone who fixes the lamps. This lesson walks the whole road once: from filling in a form in the portal to a running service with its database, docs and owner, and shows who keeps each lamp working.

Putting it together: one golden path, end to end

You now have every piece. Here is how they fit into the path a developer actually walks on day one of a new service - and what the platform team owns at each step.

 1. Backstage > Create > "Java service"            the template (platform team)
        │  name: billing-api, owner: team-billing, database: small
        ▼
 2. scaffolder: fetch:template ─ publish:gitlab ─ catalog:register
        │  repo apps/billing-api on git.lab, with:
        │    catalog-info.yaml   Component + Resource (the database)
        │    deploy/database.yaml    kind: Database (the Crossplane API)
        │    deploy/app.yaml         Deployment labelled backstage.io/kubernetes-id
        │    docs/ + mkdocs.yml  TechDocs
        ▼
 3. GitOps (Argo CD) syncs deploy/ into the team's namespace
        ▼
 4. Crossplane: Database/billing-api ─▶ Composition ─▶ RDS Instance + Secret
        ▼
 5. Backstage shows it: the catalog entity, owner, relations, Docs tab,
    Kubernetes tab, links to the repo and the pipeline

Two design decisions make this a platform rather than a pile of scripts:

  • The template writes declarative files, not resources. It never calls AWS. It writes a Database object into the repository, and GitOps applies it. The request is reviewable, reproducible and lives with the service.
  • Every decision the team did not make is in one reviewed place. Instance class, backups, encryption, tags, the deletion protection: the Composition. The repository layout, CI and docs skeleton: the template. Change them once and every new service gets the change; existing ones follow through Composition revisions (carefully - the lifecycle lesson).

The catalog entry for the infrastructure

Model the database in the catalog too, so ownership and dependencies are visible and on-call can find who owns billing-api-db at 3 a.m.:

apiVersion: backstage.io/v1alpha1
kind: Resource
metadata:
  name: billing-api-db
  description: PostgreSQL for billing-api (Crossplane Database/billing-api)
spec:
  type: database
  owner: team-billing
  system: billing
---
apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: billing-api
  annotations:
    backstage.io/kubernetes-id: billing-api
    backstage.io/techdocs-ref: dir:.
spec:
  type: service
  lifecycle: experimental
  owner: team-billing
  system: billing
  dependsOn:
    - resource:billing-api-db

Community plugins go further and show Crossplane XRs and their trees directly on the entity page; the principle is the same: the portal is the front door, the control plane does the work.

Operating the platform

A platform is production software with internal customers. Run it like one:

  • SLOs for the platform itself. "A new service is live in under 30 minutes" (template to running pod); "a Database is Ready within 15 minutes, 99% of the time". Measure them from the objects you already have: task timestamps, conditions' lastTransitionTime.
  • Alert on stuck reconciles. Crossplane exposes Prometheus metrics; at least alert on XRs and managed resources that stay Synced=False or Ready=False longer than their normal creation time. The expired-credentials incident is invisible to application monitoring: the database keeps working while nothing manages it.
  • Upgrade on purpose. Crossplane ships a minor release every few months with patch releases in between; providers and functions release more often. Pin versions, read release notes, upgrade in a staging control plane first. Backstage moves faster still - a release every month (backstage-cli versions:bump upgrades an app's packages together).
  • Credentials are the platform's crown jewels. The ProviderConfig secret can create and delete everything. Prefer workload identity (IRSA, Pod Identity) over keys; restrict who can read crossplane-system.
  • Version your APIs. XRDs get new versions instead of breaking changes; templates get new names (java-service-v2) instead of silently changing what java-service produces.

What to measure

Ask whether the platform reduces load and speeds teams up, not whether it exists:

SignalExample
Adoptionshare of services created from templates this quarter; share of databases requested through the API
Time to first deploytemplate run to first successful deploy
Waitingtickets to the platform team per month (should fall)
OutcomesDORA metrics of teams on the golden path vs off it
Satisfactiona short survey each quarter; the free-text answers are your backlog

Where to stop

The thinnest viable platform wins. Do not wrap every AWS service in an XRD; wrap the five things every team needs and let the rest come later, when demand shows. Do not hide everything: a team that needs a non-standard database should be able to request a raw managed resource (with review) rather than be blocked. And keep the escape hatch documented, because every team that uses it tells you what the next golden path should be.

In an interview: a golden path in an IDP: a Backstage template creates the repository with declarative requests (a Crossplane XR for the database), its catalog-info.yaml and docs; GitOps applies the requests; Crossplane builds the infrastructure from a reviewed Composition; Backstage shows the result. Run the platform like a product, with its own SLOs and adoption metrics.

Why it helps

Interviews for platform roles almost always end with "put it together": how would a new service go from idea to production on your platform. Seeing the template, GitOps, Crossplane and the catalog as one flow, and knowing how to operate and measure the platform itself, is what turns a set of tools into an answer and into a platform people actually choose to use.

FAQ

Why should a template write files instead of creating resources?

Writing a Database request into the repository keeps it reviewable, reproducible and next to the service, and GitOps applies it like any other change. A template that calls the cloud directly creates resources nobody can see in git or recreate.

Should infrastructure be in the catalog?

Yes, as Resource entities with owners and dependsOn relations from the components that use them. On call, the first question about a database at night is who owns it and which services depend on it.

What should we alert on for the platform itself?

At least XRs and managed resources that stay Synced False or Ready False longer than their normal creation time. Expired credentials are invisible to application monitoring, because existing resources keep working while nothing manages them.

How often do these projects release?

Crossplane ships a minor release every few months with patches in between, providers and functions more often, and Backstage every month. Pin versions, read the release notes, and always upgrade a staging control plane first.

How do I avoid building too much?

Follow the thinnest viable platform: wrap the few things every team needs first, keep an escape hatch for teams with real needs, and let demand decide what comes next. Teams that leave the path tell you what the next golden path should be.

In an interview Mid

Walk me through a new service going to production on your platform.

The developer runs a Software Template in Backstage; the scaffolder creates the repository with catalog-info.yaml, docs and a declarative request such as a Crossplane Database, publishes it and registers it in the catalog. GitOps applies the request to the team's namespace, and Crossplane builds the database from a reviewed Composition with the company's defaults. Backstage shows owner, relations, docs and the Kubernetes tab. The platform has its own SLOs and adoption metrics.

Also asked: What would you measure to prove the platform helps? · Where does the company's security policy live in this flow? · How do you roll out a change to the golden path?

Practise this lesson in the terminal Free, in your browser - a real Ubuntu terminal to try it in, with missions that check your work.