Skip to content
On this page 7

The golden path for new services

A golden path turns a platform team from a ticket queue into a paved road: what it must include, the new-repository flow, and the 18 pitfalls to design out.

A golden path is the supported route to creating a new service: a written procedure that produces a repository which already builds, deploys, is monitored and is governed — without anyone opening a ticket. It is the difference between a platform team that reviews pull requests and a platform team that provisions things for people, and the second one does not scale past about a dozen services.

This post is the mechanics: what the path has to contain, what the new-repository flow actually looks like when it is real, the guards that catch mistakes before a human reviews them, and the eighteen pitfalls that turn a two-hour task into a two-day one.

Why does a platform team become a ticket queue?

#

Not because it is understaffed. Because of a structural fact: every new service needs things that live in accounts the service team cannot write to.

A deploy role in an automation account. A container registry in a shared artifacts account. A parameter in the landing zone. An environment protection rule. A network decision. If the only way to obtain any of those is to ask, then all of them become requests, and the requests arrive at one team.

The queue is the architecture working exactly as drawn. Adding engineers to it shortens the wait without changing the shape, which is why platform teams that hire their way out of the queue find themselves back in it a year later with a bigger salary bill.

The fix is not “say no more often”. It is to convert each request into a reviewable change: the service team opens a pull request against the platform repository, and a code owner approves it. The platform team still decides. It just decides in a diff, in minutes, instead of in a ticket, in days.

What does a golden path have to include?

#

A template repository is not a golden path. A template gives you files. What teams get stuck on is everything that has to be true around the files.

The path must provideWhy it is on the listWhat happens without it
A repository layout with working examplesThe first question is always “where does this go”Every service invents a different structure, and nothing is reviewable across teams
A deploy identity, obtained by pull requestThe service cannot create its own permissionsA ticket, then a broad role granted to make the ticket go away
A place for build artifactsImages have to live somewhere the workload accounts can pull fromA registry per team, with inconsistent scanning and retention
Pipelines that already workCopying a workflow from another repository copies its assumptions tooFive variants of the same pipeline, four of them subtly wrong
Environment protection with real reviewersProduction needs a gate that is not a conventionA gate that exists in a wiki
Secret deliveryApplications need configuration they must not holdA secret in a pipeline variable, which nobody can rotate
Network and DNS by defaultReachability is not the service team’s specialtyEither an overly open security group or a week of debugging
Guards that fail fastThe document cannot anticipate everythingThe reviewer becomes the guard, which does not scale and is unreliable
A verification checklist“Done” needs a definitionServices that are 80 percent onboarded, permanently

Everything above is a one-time decision that the platform team makes once and encodes. That is the entire economic argument for a golden path: the decisions do not get cheaper by being made repeatedly.

What does the new-repository flow actually look like?

#

Here is the shape it takes in a real implementation — the AWS Enterprise Baseline and the BuiltForProd Blueprints — described as a worked example rather than as the only way to arrange it.

A new service is two repositories and three registrations. The infrastructure repository owns the service’s own cloud resources; the code repository owns the application and its delivery. The registrations are pull requests against the platform repository, reviewed by the code owners of the paths they touch.

Figure 1
The new-service flow across two repositories

The service team creates an infrastructure repository and a code repository. Three pull requests against the platform repository register a deploy role, a container registry entry with a second deploy role, and the application in the GitOps configuration. A first plan and apply follow, then the first release.

service team’s repositoriesinfra repounits and stackscode repoapp and pipelinesplatform repositorydeployroleregistryentryGitOpsentryPRssecret setdeploy role ARNfirst planguards run firstfirst applydev stageliveEvery registration is a reviewed diff. No step is a ticket, and no step needs a person to be available.
A new service is two repositories and three registrations. Each registration is a pull request against the platform repository, reviewed by a code owner, rather than a ticket assigned to a person.

The infrastructure repository, in order. Create the repository and copy the scaffolding from the smallest existing example — the guard scripts, the pre-commit configuration, the root and common configuration, and an ignore file that excludes the generated directories. Lay out modules, unit definitions, stack templates and per-environment folders. Write the stack template and the environment stage file. Set the state key prefix and the default tags in the root configuration and change nothing else, so the version pins stay as delivered. Fill in the common values: home region, namespace, account identifiers. Then register the deploy role in the platform repository — one map entry, which produces a role named after the repository. Set exactly one repository secret, the deploy role identifier. Copy the plan and apply workflows. Create the access groups. Run the first apply.

The code repository, in order. Choose the template that matches the runtime. Create the repository. Register a container registry entry in the platform repository — immutable tags, scan on push, a lifecycle policy, pullable from the workload accounts and pushable only from automation. Register a second deploy role scoped to that registry. Set the secrets and create the environments, with required reviewers on production and none on the earlier stages. Wire the workflow variables, which ship empty on purpose. Add the delivery configuration — for a Kubernetes service, a chart plus a per-stage values file that holds only the image reference. Add any public routing. Then run it: a pull request builds, tests and scans and pushes nothing; a merge pushes an image and opens a deploy pull request for development; a release promotes to staging; production is separate and gated.

Two properties of that flow matter more than the step count. Nothing in it is a request. And the first apply is the acceptance test — if the path is broken, it is broken before anybody depends on it.

What sits at the end of that flow depends on the runtime. For a containerized web service it is a cluster with a GitOps controller and an approval-gated promotion path, described in an EKS platform without a platform team; for a data workload it is a governed lake with tag-based access. The registrations are the same shape either way, which is the point of having a path rather than a runbook per team.

Guards catch what review cannot

#

Code review is good at finding wrong code and bad at finding absent code. Nobody notices the missing tag, the dependency with no mock, the unit nobody references. So the conventions that the path depends on become scripts, and the scripts run both as pre-commit hooks and in the pipeline — so skipping the hook does not skip the check.

The Baseline runs six, and the useful thing about them is their provenance: each was written after its convention broke once.

GuardWhat it rejectsWhy it exists
No hardcoded CIDRsA private address range literal in configuration, outside comments, default routes and mocksAddresses come from the address map, so a typed CIDR is an overlap waiting for a future region
Address map checkMalformed subnet keys, bad masks, subnets outside their VPC, overlapping VPCsThe map is the source of truth, and a broken map fails late and loudly
Mock completenessA dependency with no mocks, or a mock missing an attribute the unit readsWithout complete mocks, a brand-new environment cannot be planned before it exists
Stack layoutA stage folder with no stack file, a checked-in configuration where one should be generated, a unit definition no stack referencesLayout mistakes produce plans that are confusing rather than failing
Module version pinsA module whose version constraints do not match the root configurationUnpinned providers turn a re-run into a different plan
Required inputsA unit that does not supply a required variable of its moduleOtherwise the failure surfaces partway through a multi-account apply

If you take one thing from this section: the mock completeness guard is the one that protects the property everyone actually wants, which is planning an entire environment before it exists. Mocks use deliberately obvious sentinel values — account identifiers made of zeros, resource identifiers containing the word mock, addresses from a reserved range — so that if one ever reached a real plan, it would be unmistakable.

The eighteen pitfalls

#

These are the mistakes that turn a two-hour onboarding into a two-day one. They are worth reading before your first service, not after.

#The pitfallWhat you seeThe fix
1The generated directory is committedPlans that make no sense and do not match the codeIgnore the generated and cache directories from the first commit
2Running the tool from the repository rootThe generator writes into your unit catalogRun from the stage folder, and delete the stray generated tree
3Editing a file inside the generated treeThe change disappears on the next runEdit the definition or the template; the tree is output
4Renaming a unit’s pathThe next plan proposes to create everything againThe path is the state key. Choose it once; moving it is a deliberate state operation
5Naming a module after its functions3-data-lake cannot be reused for anything elseName modules after the resource type: s3, lambda, eks
6A relative source path in a templateThe source does not exist when the template is evaluatedAnchor sources at the repository root; templates are copied before they are read
7A unit definition no stack file referencesCode that is never planned and slowly rotsThe layout guard rejects it; keep it that way
8Reading dependency outputs in localsEmpty values, or an error that blames the wrong thingLocals are evaluated before dependencies. Outputs belong in inputs
9A dependency with no mocks, or a partial mockA new environment cannot be plannedMock every attribute the unit reads. A partial mock is no better than none
10Using the exclusion mechanism as a feature switchResources orphaned in the cloud with no code managing themExcluded units are skipped by every command, including destroy. Use a module-level count toggle, so off means destroyed
11Forgetting a shared definition is sharedA change lands somewhere nobody was lookingPlan every account and stage that references the definition
12A workload role created without the exemption tagAccess denied, or an internal error, with nothing in the message naming the causeTag every role the policy expects to exempt, in the module that creates it
13The deploy role secret has the wrong nameFederated sign-in fails on the first pipeline runThe name is exact. Copy it rather than typing it
14Referencing a registry that does not exist yetThe platform plan fails on a lookupMerge the registry registration first. Order matters between the two pull requests
15A deploy role missing state access, or the wrong key prefixAccess denied on state, after everything else workedCopy the existing role entry rather than composing a new one
16A code deploy role without registry permissionsPush denied at the end of a green buildScope the role to the registry when you create it, not after the first failure
17The trusted-subject list replaced instead of extendedThe role stops trusting the subjects it used toSetting the list per role overrides the default. Include everything you still need
18A job that declares an environment, restricted by branchThe subject presented is the environment, not the branchPut the branch restriction in the environment’s own deployment branch policy

Eleven of the eighteen are structural: a path, a name, an ordering. That is the pattern worth noticing. Golden paths fail on plumbing, not on judgment, which is exactly why they can be fixed by scripts and documentation rather than by seniority.

How do you know it is working?

#

Three measures, and they should move together.

Time to first deploy, unaided. Hand the document to an engineer who has not seen it and time them. Do not help. The places they stop are the backlog.

Coverage. What share of live services were created through the path? A path used by a third of your services is a suggestion, and the other two thirds are where your incidents come from.

Ticket composition. Count platform requests that are provisioning or access, versus genuine design questions. The first category should shrink toward zero; the second is the work you actually wanted your platform team doing.

There is a fourth signal that is qualitative and reliable: whether people improvise. If teams are standing up their own registries and roles, the path is slower than going around it, and no policy will fix that.

Where to start, if you have a queue and no path

#
  1. Read your last twenty platform tickets and sort them into provisioning, access and design. The first two categories are your path’s scope, already written by your users.
  2. Pick the single most common request and turn it into a pull request against a file, with code owners. One request type, converted, is worth more than a strategy.
  3. Write the procedure as you do it for the next service, in order, with the commands. Not a design document — a procedure someone can follow.
  4. Have someone else follow it without help. Fix what stops them.
  5. Turn the first thing they got wrong into a guard script. Then the second.

That loop, run for a quarter, produces a usable path. It is also the work that never gets prioritized, because the queue is always more urgent — which is the honest reason most platform teams stay queues. If it is the work your team does not have room for, it is the shape of work BuiltForProd Managed does through your own pull requests, and the BuiltForProd Baseline arrives with the path, the guards and the procedures already written and handed over with the repositories.

Questions

What is a golden path in platform engineering?

A golden path is the supported, documented, well-lit route to doing a common thing — usually creating and deploying a new service. It is not a mandate. It is the option that is so obviously easier than improvising that teams choose it, and it works only if following it produces a working service without a conversation.

How is a golden path different from a template repository?

A template gives you files. A golden path gives you files plus the registrations that make them work: a deploy role in the right account, a secret with the right name, a container registry entry, environment protection rules, and a first deploy that actually succeeds. The registrations are where teams get stuck, and they are what a template silently omits.

Why does a platform team turn into a ticket queue?

Because the only path to infrastructure runs through a person. Every new service needs an account role, a registry, a pipeline and a network decision, and if none of those can be obtained by a pull request, all of them become requests. The queue is the architecture working as designed; adding engineers to it shortens the wait without changing the design.

Should the golden path be mandatory?

Make it the default and the cheapest option, not a rule. Enforce the small number of things that must be true everywhere — identity, tagging, review, no long-lived credentials — with policy that applies regardless of route, and let the path win on convenience for everything else. A mandated path that is slower than improvising produces shadow infrastructure.

How do you know a golden path is working?

Three measures: how long it takes a new engineer to get a service deployed to a development environment without help, what proportion of live services were created through the path, and how many platform tickets are requests for access or provisioning rather than genuine design questions. All three should move in the same direction.

This is what we build.

BuiltForProd deploys a production foundation into your own cloud accounts, hands over the repositories and the documentation, and, if you want it, keeps running it with your team. Tell us what you are running and what is coming next. The first call is 30 minutes, with an engineer who scopes engagements, not a salesperson.

The calendar invite and the video link go to this address. Prefer to write? Send a message instead.

An EKS platform without a platform team

A worked EKS golden path: a managed node group with Karpenter, ArgoCD, External Secrets, promotion by approval, and what Kubernetes costs you to operate.