Golden Paths: Making the Right Thing the Easy Thing

A golden path is a pre-built, well-maintained way to accomplish a common task. It is the answer to “how do I deploy a new service?” or “how do I add a database?” that does not require reading 15 Confluence pages, asking 3 people, and configuring 8 tools.

The golden path philosophy is simple: make the right thing the easy thing. If the secure, observable, well-architected way to deploy a service is also the fastest way, engineers will choose it every time. If the right way is harder than the wrong way, they will choose the wrong way — and you will spend your time fighting the consequences.

What Golden Paths Cover

Golden Path	What It Provides	Without It
New Service	Template repo with CI/CD, monitoring, logging, Dockerfile	Engineer copies another service’s repo, removes 60% of it, misses critical configs
New API Endpoint	Boilerplate with auth, validation, error handling, docs	Engineer writes it from scratch, forgets rate limiting and input validation
New Database	Provisioned DB with backups, monitoring, connection pooling	Engineer creates RDS in console, forgets backups, loses data 3 months later
New Background Job	Queue consumer template with retry logic, dead letter handling	Engineer writes a while-true loop with no error handling
New Frontend App	React/Next.js template with design system, auth, analytics	Every team’s frontend looks different and uses different patterns

Designing Effective Golden Paths

The 80/20 Rule

A golden path should handle 80% of use cases perfectly and allow engineers to eject for the remaining 20%. If it handles 100% of cases, it is over-engineered. If it handles 50%, it is not useful enough.

Good golden path:
  "Here is a service template. Override these 5 values. Deploy in 10 minutes."
  For the 80%: 10-minute setup, production-ready.
  For the 20%: "Fork the template and customize anything."

Bad golden path:
  "Here is a service template with 200 configuration options."
  For everyone: 2 hours reading documentation, still unsure.

Template Architecture

service-template/
├── .github/
│   └── workflows/
│       ├── ci.yaml              # Test + build + scan
│       └── deploy.yaml          # Deploy to staging/production
├── src/
│   ├── main.ts                  # Application entry
│   ├── health.ts                # /health endpoint (pre-built)
│   ├── metrics.ts               # Prometheus metrics (pre-built)
│   └── config.ts                # Configuration from env vars
├── deploy/
│   ├── base/
│   │   ├── deployment.yaml      # K8s deployment with probes
│   │   ├── service.yaml         # K8s service
│   │   └── kustomization.yaml
│   └── overlays/
│       ├── staging/
│       └── production/
├── Dockerfile                   # Multi-stage, non-root, optimized
├── docker-compose.yaml          # Local development
├── .env.example                 # Required environment variables
├── cookiecutter.json            # Template variables
│   {
│     "service_name": "my-service",
│     "team": "platform",
│     "language": "typescript",
│     "needs_database": false,
│     "needs_queue": false
│   }
└── README.md                    # Auto-generated from template

What the Template Includes by Default

Concern	Included	Why
Health check endpoint	`/health` and `/ready`	Kubernetes needs these for probes
Prometheus metrics	Request count, latency histogram, error rate	Observable from day 1
Structured logging	JSON logs with correlation IDs	Searchable in log aggregator
Graceful shutdown	SIGTERM handler with connection draining	No dropped requests during deploy
Dockerfile	Multi-stage, non-root user, minimal image	Secure by default
CI/CD pipeline	Build, test, scan, deploy	No manual deployment
Kubernetes manifests	Deployment, service, HPA, network policy	Production-ready from creation
Error handling	Global error handler with proper status codes	Consistent API behavior

Self-Service Workflows

The golden path should be executable without filing a ticket or asking anyone for help.

CLI-Based Path

# Ideal: one command to create a new service
$ platform create-service \
    --name checkout-api \
    --team payments \
    --language typescript \
    --needs-database postgres \
    --needs-queue rabbitmq

Creating service "checkout-api"...
  ✅ Repository created: github.com/company/checkout-api
  ✅ CI/CD pipeline configured
  ✅ Database provisioned: checkout-api-db (PostgreSQL 15)
  ✅ Queue configured: checkout-api-events (RabbitMQ)
  ✅ Monitoring dashboard created
  ✅ Kubernetes namespace: payments-checkout-api
  ✅ ArgoCD application registered

Your service is ready. Run locally:
  cd checkout-api && docker-compose up

Deploy to staging:
  git push origin main  (CI/CD handles the rest)

Time to first deployment: ~10 minutes.

Portal-Based Path (Backstage / Custom)

# Backstage Software Template
apiVersion: scaffolder.backstage.io/v1beta3
kind: Template
metadata:
  name: new-service
  title: Create a New Service
  description: "Deploy a production-ready service in 10 minutes"
spec:
  parameters:
    - title: Service Details
      properties:
        name:
          type: string
          description: "Service name (lowercase, hyphens)"
        team:
          type: string
          enum: [platform, payments, growth, data]
        language:
          type: string
          enum: [typescript, go, python]
          default: typescript
        needs_database:
          type: boolean
          default: false
        needs_queue:
          type: boolean
          default: false

  steps:
    - id: create-repo
      action: publish:github
      input:
        repoUrl: "github.com?owner=company&repo=${{ parameters.name }}"
    - id: provision-infra
      action: custom:provision-infrastructure
    - id: register-catalog
      action: catalog:register

Measuring Golden Path Success

Metric	What It Tells You	Target
Time to first deployment	How long from “I want a service” to running in staging	< 30 minutes
Golden path adoption rate	% of new services using the golden path	> 80%
Eject rate	% of teams that fork/modify the template significantly	10-20% (some customization is healthy)
Time to production	How long from first commit to serving production traffic	< 1 day
Developer satisfaction	Survey: “How easy was it to create a new service?”	> 4/5
Support tickets for setup	Questions about how to set up new services	Decreasing trend

Common Failures

Failure	Symptom	Fix
Template rot	Template was created 18 months ago, uses deprecated dependencies	Assign a team to maintain templates quarterly
Too many choices	Template has 30 configuration options	Reduce to 5 with sensible defaults
No eject hatch	Engineers cannot customize when needed	Always allow forking and customization
Undiscoverable	Template exists but nobody knows about it	Promote via onboarding, internal docs, Slack
Not tested	Template itself has bugs	Run CI on the template repo — test the template, not just template outputs