Cloud and DevOps · Platform engineering
Building golden pathsA platform team's first internal developer platform.
Every team builds its own pipeline, its own Terraform and its own dashboards. A new service takes two weeks, and the same security findings keep coming back. Here's how a new platform team builds one paved road that people choose to use.
Here's the situation. A company has 150 engineers in many product teams. Each team set up its own CI pipeline, wrote its own Terraform, hand-rolled its own Kubernetes manifests and built its own dashboards. None of it is wrong on its own. Together, it means a new service takes about two weeks to reach production, and the security team files the same findings against different repos every quarter. Leadership has just formed a platform team.
We'll use one picture all the way through: a growing town. Until now, every household built its own track to the main road, dug its own water hookup and fitted its own smoke alarm. The town has just set up a public works department. Its job isn't to build every house. It's to lay a paved road with water, power and fire hydrants already in it, so building a new house is quick and safe. Nobody is forced onto the road. It's just the obvious way to go.
01 / The case
When is a platform team worth it?
The CNCF Platforms white paper starts from the same pain. Years of process improvement gave product teams flexible infrastructure and developer services, but it also shifted more and more responsibility onto those teams, "forcing them to spend more and more time and cognitive energy on infrastructure concerns". [1]
The gains it lists include less cognitive load on product teams, more reliable products, reuse across teams, and less security and regulatory risk through governed capabilities. It also says why the gains appear: "just a few platform teams serve many product teams, multiplying their impact". [1] That's the test for our company. Is the same work being done many times over? Here it is: many pipelines, many Terraform layouts, many dashboard styles, and one security problem repeated across repos. Duplication at that scale is the signal that a shared team can pay for itself.
The other side matters just as much. The paper warns that platforms affect value streams "only indirectly", so leadership support is vital, and that platform teams must show their impact on product teams to keep it. [1] DORA adds a timing warning: platform engineering often follows a "J-curve", with early gains, then a dip as complexity grows, then a recovery to a higher level as the platform matures. [3] Tell leadership about the dip before it happens.
- In the town
- One family digging its own well is fine. Fifty families each digging their own, and each getting the same contamination test wrong, is when a water department pays off.
- In the system
- A platform team pays off when many teams repeat the same undifferentiated work, such as pipelines, infrastructure and observability, and repeat the same mistakes.
02 / The definition
What is a platform, exactly?
The white paper's definition: "A platform for cloud-native computing is an integrated collection of capabilities defined and presented according to the needs of the platform's users." It gives a consistent experience through things like web portals, project templates and self-service APIs. [1]
Two details shape everything a new team does. First, the platform team doesn't have to build the capabilities itself. Managed providers or other internal teams can run them, and the platform should be "the thinnest reasonable layer" that makes them consistent. Its simplest example of a platform is a wiki page linking to standard procedures. [1] Second, the platform team is "most responsible for the interfaces (i.e., GUI, CLI, and API) and user experiences" for those capabilities. [1]
Its list of capability domains runs from portals and APIs to golden path templates, build and delivery automation, observability, identity and secrets, and security services. It's a menu: teams should choose and prioritise "together with its users". [1]
DORA describes the same thing from the delivery side. It calls platform engineering "a sociotechnical discipline" and the result an "Internal Developer Platform" that provides shared tools, services and golden paths, so teams can build, test and deploy "securely, reliably, and in a compliant way". [3]
- In the town
- Public works doesn't run the power station. It lays the road and the conduits, so every house connects to power the same way.
- In the system
- The cloud provider runs the database. The platform team owns the consistent way teams ask for it, connect to it and watch it.
03 / The road
Golden path or mandate?
The white paper uses "golden path" for a bundle: a reusable workflow for building, scanning, testing, deploying and observing an app, offered with "an initial project template and documentation". [1] DORA calls the same idea a "paved road". [3]
The key attribute is that it's optional. The white paper says a platform should be optional and composable: teams can use only parts of it, and can run their own capabilities outside it when they need to. [1] It's blunt about the alternative. Platform teams that "rely on top-down mandates to achieve adoption are almost certain to find resistance and resentment from their users". [1]
The CNCF maturity model describes the two kinds of adoption. At its second level, "Extrinsic push", internal directives incentivise or require platform use, and users have low motivation to learn it. At the third level, "Intrinsic pull", teams choose the platform "because of the clear value they provide". [2] DORA names the trap on the other side too: a rigid "golden cage" that ignores what different teams need. [3]
So a golden path isn't the absence of rules. It's the easy way to meet the rules. Some things stay non-negotiable, like no plaintext secrets or every service having an owner. Those become guardrails that apply on and off the path. Everything else, like the language, the test framework or the dashboard layout, is a default that teams may change.
- In the town
- The paved road is the easy route, not the only legal one. The building code, like smoke alarms in every house, applies whichever road you take.
- In the system
- The template is optional. A small set of policies, enforced at deploy time, applies to every service whether it came from the template or not.
04 / The users
How do you run a platform as a product?
"Platform as a product" is the first attribute the white paper lists: a platform exists to serve its users and "should be designed and evolved based on those requirements, similar to any other software products". [1] In practice that means three things.
Have a product manager. The white paper says platform teams "should include product managers from the start". [1] DORA says the same and suggests mapping critical user journeys, such as "spinning up a new service", to find the worst friction. [3] For our company, that journey is the two-week onboarding. It's the first thing to map, step by step, with timings.
Start with a few partner teams. The white paper suggests focusing first on "a limited number of engaged and skillful app teams", whose feedback improves the first experience and whose people later champion it. It also suggests starting with capabilities that are frequently needed and undifferentiated, "like pipelines, databases and observability". [1]
Listen, and market. The white paper's ways to learn what users need include interviews, hackathons, issue trackers, surveys and watching real usage. Its ways to drive adoption include announcements, demos and regular feedback sessions. [1] DORA adds one thing users value most: the platform capability most correlated with a positive experience in its 2025 data was giving "clear feedback on the outcome of my tasks". [3] Error messages are product features.
- In the town
- Before paving, public works asks where people actually walk, and paves those routes first, with a few households who agree to try it and say what's wrong.
- In the system
- The team maps the "new service" journey with two or three partner teams, fixes the slowest steps, and tells everyone what changed.
05 / The playbook
What goes into the first thin platform?
DORA's advice is to start with a "minimum viable platform": find the golden path for the most common workflow and "build just enough to make that specific journey demonstrably better". [3] The white paper's version is to "build the thinnest viable platform layer over implementations from managed providers". [1]
For our company, the most common painful journey is creating a new backend service and getting it to production. So the first platform is one service template. A new repo created from it already has:
- CI: a pipeline that builds, tests and packages the service into a container image.
- Deployment: Kubernetes manifests and a delivery workflow to staging and production.
- Observability: standard metrics, logs and a starter dashboard and alerts.
- Security defaults: dependency and image scanning in CI, no secrets in the repo, and manifests that already pass the cluster's policies.
- Ownership: a catalog file naming the owning team.
That mirrors the white paper's golden path example: "building, scanning, testing, deploying, and observing". [1] Don't invent a pipeline. Pick the best one the company already has and make it the default. Step through what happens when an engineer uses the template.
Figure 1 · One new service on the golden path
- 1. The engineer opens the template and fills in a short form: service name, owning team and repository location. Nothing exists yet.
- 2. The template renders the skeleton files with those values: code, pipeline, manifests, dashboard and a catalog file.
- 3. A new repository is published with those files. Its first push runs CI: build, test, scan and package an image.
- 4. The delivery workflow deploys to staging. The cluster's policies check the manifests at admission, and the template's manifests already pass.
- 5. Standard metrics and logs flow, and the starter dashboard and alerts exist from the first deploy.
- 6. The service is registered in the software catalog with its owning team, so anyone can find it and know who to call.
- The whole path: one form, then a repo with CI, a policy-checked deploy, a dashboard and an owner. The goal is to turn two weeks into the same afternoon.
- Time the current "new service" journey with two partner teams. That's your baseline.
- Pick the best existing pipeline, manifests and dashboard in the company. Don't write new ones.
- Turn them into one template. Run it with the partner teams before anyone else sees it.
- Fix what they trip on, then announce it with a demo, not a memo.
- Only then add the second capability users ask for most.
- In the town
- The first thing public works offers is a serviced plot: a plot on the paved road, already connected to water, power and drains, with a smoke alarm fitted.
- In the system
- The first platform is one template that gives a new service CI, deployment, observability, security defaults and an owner on day one.
06 / The register
Where does a software catalog fit?
The white paper lists Backstage as an example CNCF project for web portals that publish docs, service catalogs and project templates. [1] It's one option, not a requirement. If you use it, two of its features matter for a first platform: the software catalog and software templates.
The Backstage docs describe the software catalog as "a centralized system that keeps track of ownership and metadata for all the software in your ecosystem". It's built around metadata YAML files stored with the code, which Backstage harvests and shows. [7] The file usually sits in the repo root, though it can live anywhere in the repo. Teams that own a component update its file through their normal Git workflow. [7]
Here's a minimal descriptor for one of our services, using fields from the Backstage descriptor format and its well-known annotations page: [8] [9]
# catalog-info.yaml
apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
name: payments-api
description: Takes card payments for checkout
annotations:
github.com/project-slug: example-org/payments-api
spec:
type: service
lifecycle: production
owner: group:default/payments-team
For a Component, spec.type, spec.lifecycle and
spec.owner are required. The well-known values for type include
service, website and library, and for lifecycle
experimental, production and deprecated. The
catalog accepts any value, and the docs ask organisations to take "great care" over
their own taxonomy. [8] The owner is an entity reference, a
Group by default or a User. [8] References take the form
[<kind>:][<namespace>/]<name>, so
group:default/payments-team spells all three parts out.
[17]
One detail is easy to miss. The docs say the owner is "the singular entity (commonly a team) that bears ultimate responsibility", and that the field's main purpose is display. "It is not to be used by automated processes to for example assign authorization in runtime systems." [8] Use it to find who to page. Don't use it to decide who may deploy.
- In the town
- The land register lists every building and who's responsible for it. When a pipe bursts, you know whose door to knock on.
- In the system
-
The catalog lists every component and its owning team, read from a
catalog-info.yamlfile that lives in the component's own repo.
07 / The plot plan
What does a software template look like?
Backstage Software Templates can "load skeletons of code, template in some variables,
and then publish the template to some locations like GitHub or GitLab". Users find them
under /create, fill in a form, review their inputs, then run it.
[10] Software created through a template is automatically
registered in the catalog. [7]
A template is a YAML file with parameters (the form) and
steps (the actions the scaffolder runs in series).
[11] This one is cut down from the example in the Backstage
"Writing Templates" docs, with names changed for our golden path:
apiVersion: scaffolder.backstage.io/v1beta3
kind: Template
metadata:
name: backend-service
title: Backend service (golden path)
description: A new service with CI, deploy, dashboards and an owner
spec:
owner: group:default/platform-team
type: service
parameters:
- title: About the service
required:
- name
- owner
properties:
name:
title: Name
type: string
description: Unique name of the component
owner:
title: Owner
type: string
description: Team that owns the service
ui:field: OwnerPicker
ui:options:
catalogFilter:
kind: Group
- title: Choose a location
required:
- repoUrl
properties:
repoUrl:
title: Repository Location
type: string
ui:field: RepoUrlPicker
ui:options:
allowedHosts:
- github.com
steps:
- id: fetchBase
name: Fetch Base
action: fetch:template
input:
url: ./skeleton
values:
name: ${{ parameters.name }}
owner: ${{ parameters.owner }}
- id: publish
name: Publish
action: publish:github
input:
description: This is ${{ parameters.name }}
repoUrl: ${{ parameters.repoUrl }}
defaultBranch: 'main'
- id: register
name: Register
action: catalog:register
input:
repoContentsUrl: ${{ steps.publish.output.repoContentsUrl }}
catalogInfoPath: '/catalog-info.yaml'
output:
links:
- title: Repository
url: ${{ steps['publish'].output.remoteUrl }}
- title: Open in catalog
icon: catalog
entityRef: ${{ steps['register'].output.entityRef }}
A few things the docs spell out. OwnerPicker shows a searchable list of
groups and users already in the catalog, filtered here to Groups.
RepoUrlPicker's allowedHosts sets where the template may
publish, and you can narrow it further with allowedOwners and
allowedRepos. [11] Step outputs, such as the
repo URL, feed later steps and the links shown when the run finishes.
[11] Use camelCase step IDs: the docs warn that dashes,
like fetch-base, are read as subtraction inside expressions.
[11] [10]
Inside the skeleton, the files use ${{ values.name }}, not
parameters. The docs say parameters works only in the template
file, and form values reach your code through the values passed to
fetch:template. [11] So the skeleton's
catalog file looks like this:
# skeleton/catalog-info.yaml
apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
name: ${{ values.name }}
spec:
type: service
lifecycle: experimental
owner: ${{ values.owner }}
The publish:github action comes from the GitHub scaffolder module,
@backstage/plugin-scaffolder-backend-module-github, which you add to your
Backstage backend. Every registered action is listed at /create/actions.
[12] The template editor at /create/edit runs a
template in dry-run mode, so you can test changes safely. [11]
- In the town
- The plot plan is a form: house name, owner, which street. Public works fills in the standard drawings and registers the deed.
- In the system
- The template's parameters are the form, and its steps render the skeleton, publish the repo and register the component.
08 / The building code
How do you add guardrails without adding tickets?
Self-service is one of the white paper's platform attributes: users "must be able to request and receive capabilities autonomously and automatically". Another is "secure by default", with capabilities to check compliance against the organisation's rules. [1] DORA calls the opposite the "Ticket-ops" trap, where the platform team acts like a vending machine for infrastructure tickets. [3]
The way to have both is policy as code: rules stored in Git and enforced by machines, not by a reviewer reading each request. The white paper lists OPA and Kyverno among its example security projects. [1] Kyverno describes itself as a policy engine that lets platform engineers "deliver secure self-service to application teams". [16]
Here's a guardrail for our ownership rule: every Deployment needs an
owner label. The label key is our own convention. This is a Kyverno
ValidatingPolicy. Kyverno's current policy types are written in CEL and all
use the policies.kyverno.io/v1 API. [14] Its
docs mark this one stable as of Kyverno 1.20, and this is adapted from their example:
[13]
apiVersion: policies.kyverno.io/v1
kind: ValidatingPolicy
metadata:
name: require-owner-label
spec:
validationActions:
- Audit
matchConstraints:
resourceRules:
- apiGroups: ['apps']
apiVersions: ['v1']
operations: [CREATE, UPDATE]
resources: ['deployments']
validations:
- message: "label 'owner' is required"
expression: "'owner' in object.metadata.?labels.orValue([])"
A ValidatingPolicy extends the Kubernetes
ValidatingAdmissionPolicy type. [13] In that
Kubernetes type, Deny means a failed validation denies the request, and
Audit means the failure is recorded in the audit event for the request.
[15] Kyverno's docs add that when a
ValidatingPolicy is evaluated, the results are recorded in PolicyReports,
which show whether resources passed or failed. [13]
That gives a safe rollout order for every new rule. Start with Audit.
Read the reports to see who would be blocked. Fix the template first, so new services
pass by default. Then help the existing teams fix theirs, and only then switch the
policy to Deny. The same policies apply to services built off the path, so
the rules are universal even though the template is optional.
- In the town
- The building code is written down and checked by an inspector at the door, for every house, on the paved road or not. A new rule gets a grace period first.
- In the system
- Policies in Git are checked at admission for every workload. New rules start in Audit, then move to Deny once the template passes them.
09 / The scorecard
How do you know it's working?
The white paper suggests three groups of measures: user satisfaction and productivity, organisational efficiency, and product and feature delivery. It also says to use "the smallest viable effort", and that simple surveys may be most valuable at first. [1]
Delivery: DORA's metrics, as DORA defines them today
The white paper names DORA's original four keys: deployment frequency, lead time for changes, time to restore services after failure, and change failure rate. [1] DORA has changed them since. In 2023, mean time to recover was renamed and redefined as failed deployment recovery time, to count only failures caused by a change. In 2024, DORA added a fifth metric, deployment rework rate. [5] DORA's current guide defines five metrics in two groups: [4]
| Group | Metric | DORA's definition |
|---|---|---|
| Throughput | Change lead time | The time it takes for a change to go from committed to version control to deployed in production. |
| Throughput | Deployment frequency | The number of deployments over a given period or the time between deployments. |
| Throughput | Failed deployment recovery time | The time it takes to recover from a deployment that fails and requires immediate intervention. |
| Instability | Change fail rate | The ratio of deployments that require immediate intervention following a deployment. |
| Instability | Deployment rework rate | The ratio of deployments that are unplanned but happen as a result of an incident in production. |
Note where recovery time sits: DORA groups it under throughput, not instability. [4] DORA also warns against common misuses. The metrics are best applied one application or service at a time. Don't blend them across teams, don't compare very different systems, don't turn them into targets, and don't use them to make teams compete. [4] To start, DORA suggests setting a baseline with its Quick Check, a five-question survey, before building integrations. [4] [6]
DORA's platform guidance asks for a balanced scorecard, because platforms "can sometimes lead to a decrease in throughput and change stability if not carefully managed". [3] Its page names the instability metric "change failure percentage"; it's the same metric as change fail rate.
Adoption, satisfaction and the onboarding clock
DORA's platform page adds three more measures: [3]
- Developer satisfaction: regular CSAT or Net Promoter Score surveys.
- Adoption and retention: the rate of new teams onboarding, and the rate at which they keep using it.
- Task success: how well developers complete key workflows on the platform.
And from the white paper's efficiency list, one fits our use case exactly: "Latency to build and deploy a brand new service into production". [1] That's the two-week number. Measure it the same way before and after.
- Time from opening the template to the first production deploy, for each new service. Compare with the baseline.
- Count new services created from the template versus by hand, per month. Rising share means pull, not push.
- Track the repeated security findings by rule. Services from the template should not produce them.
- Check the five DORA metrics per service for teams that moved, before and after.
- Survey the partner teams. Ask what they'd lose if the template went away.
- In the town
- Public works counts how long a new house takes to connect, how many builders choose the paved road, and asks residents if they're happy.
- In the system
- The team tracks onboarding time, adoption, satisfaction and DORA's five metrics per service, never as a league table.
10 / What goes wrong
What sinks first platforms?
The sources agree on the usual failure modes.
- Building a portal nobody asked for. DORA's "Build it and they will come" trap: a platform built on assumptions, without user research, that doesn't fit real workflows. [3] A portal is a door. Build the path behind it first.
- Big bang. Trying to build everything before releasing anything. By launch, needs have changed. [3]
- Over-abstracting. The white paper wants the platform to hide complexity, but also to let users "configure and observe certain services as needed". [1] A wrapper that hides everything leaves teams stuck when the defaults are wrong. DORA's "golden cage" is the same mistake. [3]
- Mandating too early. Mandates bring "resistance and resentment". [1] DORA's "Ivory tower" version leads to shadow IT. [3]
- Template drift. The maturity model warns that teams take templates, customise them, "and then cannot merge in changes from the centralized team". [2] A template creates a repo once. Plan from day one how fixes reach services that already exist, for example shared pipeline definitions that repos reference rather than copy.
Pick the signal you're seeing to get the likely cause and a next move.
Figure 2 · What is the signal telling you?
Pick what you're seeing
- Likely cause
- The path does not yet beat what teams already have, or they do not know it exists.
- Next move
- Sit with two teams who chose not to use it and watch them create a service. Fix the biggest friction you see, then announce the change and demo it.
- Avoid
- Do not answer low adoption with a mandate. Pushed adoption tends to bring resistance, not value.
What to keep watching, beyond the checks in chapter 9: template runs that fail, and at which step, because each one is a user who hit a wall; and Audit results per rule, before any rule moves to Deny.
- In the town
- A grand town hall with no roads behind it, a road that only fits one kind of car, and a law banning dirt tracks before the road reaches your street.
- In the system
- A portal with no working path, an abstraction with no escape hatch, and a mandate before the path is better than what teams have.
Keep these names
A small glossary
- Platform engineering
- Building shared tools, services and golden paths so teams can build, test and deploy safely. DORA calls it sociotechnical.
- Internal developer platform
- An integrated collection of capabilities presented according to its users' needs. The town's public works.
- Golden path (paved road)
- A ready workflow with a project template and docs. Optional, and the easiest way to meet the rules.
- Guardrail
- A rule that applies on and off the path, enforced by a machine. The building code.
- Thinnest viable platform
- The smallest consistent layer over capabilities that others may run.
- Software catalog
- Backstage's register of software and its owners, read from YAML files kept with the code.
- Software template
- A Backstage YAML file with a form (parameters) and actions (steps) that creates new components.
- Policy as code
- Rules stored in Git and checked automatically, for example at Kubernetes admission.
- DORA metrics
- Five software delivery measures: change lead time, deployment frequency, failed deployment recovery time, change fail rate and deployment rework rate.
- Template drift
- Repos made from a template that were edited and can no longer take the template's later changes.
Check the concept
Can you explain it back?
1. Leadership asks the platform team to "build all the infrastructure". What does the white paper suggest instead?
Rely on managed providers and other teams where possible, and build the thinnest reasonable layer that makes those capabilities consistent. The team mostly owns the interfaces and the experience.
2. Adoption is slow, so a director proposes requiring the template for all new services. What's the risk?
The white paper says mandate-driven platforms are almost certain to meet resistance and resentment. Find out why teams aren't choosing it and fix that first. Keep the universal rules as policies instead.
3. Your skeleton's catalog file uses ${{ parameters.name }} and the name comes out empty. Why?
parameters only works in the template file. Pass the value into
fetch:template under values, and use
${{ values.name }} in the skeleton.
4. Someone wants to grant deploy rights based on the catalog's owner field. Is that what it's for?
No. The Backstage docs say the owner field is mainly for display and should not be used by automated processes to assign authorization in runtime systems.
5. Your dashboard tracks MTTR as one of "the four keys". What does DORA call it now, and how many metrics are there?
Failed deployment recovery time, redefined in 2023 to cover only failures caused by a change. DORA now uses five metrics, adding deployment rework rate in 2024.
Continue the thread
More on the pieces of the path
- CI/CD and environments: the pipeline and the staging-to-production route your template wires up.
- Terraform modules: how to package infrastructure so teams reuse it instead of copying it.
- GitOps with Argo CD: one way to run the delivery step from Git.
- Kubernetes observability: what the standard dashboards and alerts should be built from.
- Secretless access with workload identity: a security default worth baking into the template's pipeline.
- Canary releases: a safer rollout default once the basic path works.
Read further
Sources
All read on 20 November 2026. These are living pages; definitions, versions and figures here are as served that day.
- CNCF TAG App Delivery: CNCF Platforms White Paper
- CNCF TAG App Delivery: Platform Engineering Maturity Model
- DORA: Capabilities, Platform engineering
- DORA: DORA's software delivery performance metrics
- DORA: A history of DORA's software delivery metrics
- DORA: Quick Check
- Backstage: Backstage Software Catalog
- Backstage: Descriptor Format of Catalog Entities
- Backstage: Well-known Annotations on Catalog Entities
- Backstage: Backstage Software Templates
- Backstage: Writing Templates
- Backstage: Builtin actions
- Kyverno: ValidatingPolicy
- Kyverno: Policy types overview
- Kubernetes: Validating Admission Policy
- Kyverno: Introduction
- Backstage: Entity References
Written with AI assistance. Every technical claim was checked against the original sources listed above.