supraj.dev

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.

Supraj Maripeddi · · 17 min read

Cover: four teams on tangled dirt tracks join one paved road with guardrails. The road passes four stations, CI, deploy, observe and secure, and every service on it is listed in a catalog with an owner.
Start hereYou know CI/CD, infrastructure as code and Kubernetes, and you've seen what happens when every team does them differently.
Leave knowingWhen a platform team pays off, how to build a first thin platform around one service template, and how to tell if it's working.
Keep in mindThere's no single right platform. The CNCF and DORA sources here describe principles, not products. Backstage and Kyverno are examples, not requirements.

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

All 6 steps
  1. 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.
Steps 1, 2, 3 and 6 match the Backstage software template flow in chapter 7: form, fetch:template, publish and catalog:register. CI, deploy and observability come from files in the skeleton, run by your existing tools.
What I'd do first
  1. Time the current "new service" journey with two partner teams. That's your baseline.
  2. Pick the best existing pipeline, manifests and dashboard in the company. Don't write new ones.
  3. Turn them into one template. Run it with the partner teams before anyone else sees it.
  4. Fix what they trip on, then announce it with a demo, not a memo.
  5. 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.yaml file 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]

DORA's software delivery performance metrics, from dora.dev, read on 20 November 2026.
Group Metric DORA's definition
ThroughputChange lead timeThe time it takes for a change to go from committed to version control to deployed in production.
ThroughputDeployment frequencyThe number of deployments over a given period or the time between deployments.
ThroughputFailed deployment recovery timeThe time it takes to recover from a deployment that fails and requires immediate intervention.
InstabilityChange fail rateThe ratio of deployments that require immediate intervention following a deployment.
InstabilityDeployment rework rateThe 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.

Verify the first template worked
  1. Time from opening the template to the first production deploy, for each new service. Compare with the baseline.
  2. Count new services created from the template versus by hand, per month. Rising share means pull, not push.
  3. Track the repeated security findings by rule. Services from the template should not produce them.
  4. Check the five DORA metrics per service for teams that moved, before and after.
  5. 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.
The advice draws on the CNCF white paper, the CNCF maturity model and DORA's platform engineering pitfalls. The specific next moves are recommendations, not rules from those sources.

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

Read further

Sources

All read on 20 November 2026. These are living pages; definitions, versions and figures here are as served that day.

  1. CNCF TAG App Delivery: CNCF Platforms White Paper
  2. CNCF TAG App Delivery: Platform Engineering Maturity Model
  3. DORA: Capabilities, Platform engineering
  4. DORA: DORA's software delivery performance metrics
  5. DORA: A history of DORA's software delivery metrics
  6. DORA: Quick Check
  7. Backstage: Backstage Software Catalog
  8. Backstage: Descriptor Format of Catalog Entities
  9. Backstage: Well-known Annotations on Catalog Entities
  10. Backstage: Backstage Software Templates
  11. Backstage: Writing Templates
  12. Backstage: Builtin actions
  13. Kyverno: ValidatingPolicy
  14. Kyverno: Policy types overview
  15. Kubernetes: Validating Admission Policy
  16. Kyverno: Introduction
  17. Backstage: Entity References

Written with AI assistance. Every technical claim was checked against the original sources listed above.