PlatformEngr® Platform fundamentals course

Module 04 · What the platform offers · 25 min · You are: Platform and product

Golden paths: the supported way, not the only way

In this module

  • You learn: What a golden path is, why it is opinionated and supported but optional, what an escape hatch is for, and why a path may only use capabilities that exist.
  • You do: Write the first golden path of the example company, the one the platform team builds with team-checkout. Walk it as team-checkout. Then let a product manager add a step on a capability that is only planned, and see the check stop it.
  • You end with: golden-paths/new-service.yaml passes the check: six steps on offered capabilities, optional: true, an escape hatch, a support channel, and for: [humans].

Every team solving the same problem its own way is how a company ends up with three pipelines and nobody who knows which one is supported. A golden path is the platform's answer: one well-trodden way that is easier than the alternatives because it is supported, not because it is enforced. Spotify, who made the term popular, describe it as "the 'opinionated and supported' path to 'build something'" (Spotify Engineering, 2020), and are explicit that you can leave it, "but then you will not have the same support".

Open this module in the interactive course to track progress.

Concepts

Golden path
The opinionated and supported way to do one common job, such as starting a new service, end to end. Called a paved road in some companies.
Optional
Teams choose the path because it is the easiest way. The CNCF Platforms White Paper calls this "optional and composable". Rules every team must follow are guardrails, enforced by policy, not by the path.
Escape hatch
What a team does when the path does not fit: who they tell, what they take on themselves. Without one, teams leave silently.
Supported
Someone answers when the path breaks, within a stated time. An unsupported path is a suggestion.
Paved with what exists
Every step uses a capability that is offered or in beta. A step on a planned capability is a promise the path cannot keep.

Golden path, template, guardrail

What it isOptional?Example
Golden pathThe supported way to do a whole jobYesA new service, from repository to production
TemplateOne step of a path: a starting point for a repositoryYesThe new-service repository template
GuardrailA rule every change must pass, on or off the pathNoNo image without a scan; no prod deploy without approval

Files to know

Open them in your editor or on GitHub; the bullets say what to look at.

Steps

1. Write the path

Six steps, each on one capability from your map. The escape hatch says what a team takes on when it leaves the path.

cd ~/platformengr/platform-design

Create golden-paths/new-service.yaml

# The golden path for a new service: the supported, opinionated way, for people and agents.
# Owner: the platform team. Read by the design check (rules G1 to G5).
id: new-service
name: A new HTTP service, from repository to production
owner: platform
for: [humans]
optional: true
escapeHatch: >-
  A team that needs something else builds it themselves, writes an ADR, and owns its pipeline and on-call.
  The platform team reviews the ADR and adds the need to the backlog if two teams ask for it.
support: "#platform-help, answered within one working day"
target: First change in production on the first day
steps:
  - t: Create the repository from the template
    capability: repo-template
  - t: Register the service and its owning team in the catalog
    capability: service-catalog
  - t: Get a namespace in dev and prod
    capability: team-namespace
  - t: Build, test and scan every pull request
    capability: ci-pipeline
  - t: Deploy to dev on merge, to prod with a progressive rollout
    capability: deploy
  - t: See logs and metrics for the new service
    capability: logs-and-metrics

Run the check. Expect ok golden-paths/new-service.yaml. It checked that every step's capability exists in capabilities.yaml and is not planned, and that the path is optional, supported and has an escape hatch.

npm run check

2. Walk it as team-checkout

You are team-checkout, starting a new service. For each step, find the capability and how you reach it. The path is only as self-service as its least self-service step.

The six capabilities, in order. Expect repo-template, service-catalog, team-namespace, ci-pipeline, deploy, logs-and-metrics:

grep "capability:" golden-paths/new-service.yaml

And how you reach each one. Every line should name portal, cli, api or git; none says only ticket. That is why the target, a change in production on the first day, is possible.

grep -A5 -E "id: (repo-template|service-catalog|team-namespace|ci-pipeline|deploy|logs-and-metrics)$" capabilities.yaml | grep -E "id:|interfaces:"

3. Commit

Save it.

git add -A && git commit -qm "Golden path: new service" && git push -q
gh run list --workflow design-check --limit 1

Simplified for the course

The path is a list of steps in a file. On a real platform each step is automated: a template in the portal or a CLI command creates the repository, registers it and opens the first pull request.

One path. Most platforms start with one or two (a new service, a new database) and add more when the same request arrives from several teams.

The support promise is one line. Real paths publish their support hours, where to report a problem, and who is on call for the path itself.

Break it on purpose: A step on a promise

Team-checkout's product manager reads the path and points out that every new service needs a database. They add the step themselves, on the Postgres capability, "so it is in the path when it arrives".

You practise: keeping a path to what exists today, and handling a real need that the platform cannot meet yet.

1. Break it

Add to golden-paths/new-service.yaml at the end of the file

  - t: Get a Postgres database
    capability: postgres
npm run check

2. What you see

Expected: ok golden-paths/new-service.yaml. You get: FAIL and a line with [G2] naming the new step.

3. Fix it yourself

Keep the path honest and still give team-checkout an answer about databases. Done when the check passes, and the path tells a team what to do about a database today.

Hint 1

Look at postgres in capabilities.yaml. Could a team follow this step today?

Hint 2

Take the step out. Where in the path file does a team find out what to do when the path does not cover something they need?

The fix

The escape hatch already covers it: a team that needs a database opens the ticket and owns that part, and two teams asking puts Postgres higher on the backlog. The step goes back in when Postgres is offered.

Delete from golden-paths/new-service.yaml

-   - t: Get a Postgres database
-     capability: postgres
npm run check
git add -A && git commit -qm "The path uses only what exists" && git push -q
After you fixed it: the five questions
What failed?
The golden path. One step depended on a capability that does not exist.
How was it detected?
By rule G2 of the check, before any team tried to follow it.
Who responds?
The platform team, which owns the path; the product manager owns the need.
How is it corrected?
Remove the step, and route the need through the escape hatch and the backlog.
How is it prevented?
Add a step to a path only in the same pull request that changes its capability to offered or beta.

Quiz

  1. A team leaves the golden path because it needs a different language runtime. What should happen?
    • The platform blocks their deployments until they move back onto the path
    • Nothing should be recorded: the path is optional, so leaving it is private to the team
    • They follow the escape hatch: write down why, take on what the path did for them, and tell the platform team
  2. Which belongs in a guardrail rather than in a golden path?
    • No production deploy without an approval, for every service on or off the path
    • The repository template a new service starts from
    • The order in which a new service is registered and deployed
  3. What makes a golden path "golden" rather than a wiki page with steps?
    • It is written by the most senior engineer in the company
    • It is supported and kept working by the platform team, and it is the easiest way to do the job
    • Every team is required to use it by a company policy
Answers
  1. They follow the escape hatch: write down why, take on what the path did for them, and tell the platform team Optional does not mean invisible: the escape hatch tells the platform team what the path is missing.
  2. No production deploy without an approval, for every service on or off the path Guardrails apply to everyone and are enforced; paths are chosen.
  3. It is supported and kept working by the platform team, and it is the easiest way to do the job Spotify: opinionated and supported. Leave it and you lose the support, not the permission.

Field note

The first golden path I helped build had eleven steps and covered every case anyone had ever asked about. Nobody used it. The second had five steps and an escape hatch, and the teams that left it told us exactly which sixth step to add.

Report a problem with this module