Designing Golden Paths

Article 6: Golden Paths and Paved Roads

📖 Introduction

The concept of "golden paths" fundamentally changed how I think about developer experience. Early in my career, I believed that giving developers maximum flexibility was the ultimate goal. But after watching teams struggle with decision fatigue and inconsistent implementations, I realized that sometimes the best thing you can do is provide an opinionated, well-maintained path that "just works."

Golden paths are not about restricting developers—they're about reducing cognitive load while accelerating delivery. Done right, they become the default choice because they're genuinely easier and more productive.

---

🎯 What Are Golden Paths?

Definition

Golden paths (also called "paved roads" or "happy paths") are opinionated, supported workflows that platform teams provide to guide developers through common tasks while meeting organizational standards.

Key Characteristics

Characteristic	Description
Opinionated	Prescriptive choices already made
Supported	Platform team maintains and troubleshoots
Optimized	Best practices baked in
Observable	Built-in monitoring and logging
Secure	Security controls embedded
Optional	Escape hatches available

---

🛤️ Golden Paths vs Golden Cages

The Critical Distinction

Golden Path:                      Golden Cage:
┌────────────────────┐           ┌────────────────────┐
│   Recommended      │           │   Mandatory        │
│   Fast lane        │           │   Only option      │
│   Easy to follow   │           │   No flexibility   │
│   Exit ramps exist │           │   Walls everywhere │
│   Evolves with     │           │   Rigid, outdated  │
│   feedback         │           │                    │
└────────────────────┘           └────────────────────┘

The 80/20 Rule

• 80% of use cases should be covered by golden paths

• 20% of cases may need customization or alternative approaches

• If you're forcing 100% compliance, you've built a cage

Escape Hatches

# Example: Template with escape hatch annotations
from dataclasses import dataclass
from typing import Optional


@dataclass
class ServiceConfig:
    """Golden path service configuration.
    
    For standard services, use defaults.
    For special cases, override specific fields.
    """
    # Golden path defaults
    replicas: int = 3
    memory_limit: str = "512Mi"
    cpu_limit: str = "500m"
    
    # Escape hatch: custom resource requirements
    custom_resources: Optional[dict] = None
    
    # Escape hatch: bypass standard networking
    custom_network_config: Optional[dict] = None
    
    def get_resources(self) -> dict:
        """Return resources, preferring custom if specified."""
        if self.custom_resources:
            # Log escape hatch usage for platform team visibility
            print(f"⚠️ Using custom resources: {self.custom_resources}")
            return self.custom_resources
        
        return {
            "limits": {
                "memory": self.memory_limit,
                "cpu": self.cpu_limit,
            },
            "requests": {
                "memory": "256Mi",
                "cpu": "250m",
            }
        }

---

🏗️ Designing Golden Paths

Step 1: Identify Common Workflows

Start by mapping what developers do most frequently:

from dataclasses import dataclass
from typing import List
from enum import Enum


class WorkflowCategory(Enum):
    SERVICE_CREATION = "service_creation"
    ENVIRONMENT_PROVISIONING = "environment_provisioning"
    DATABASE_SETUP = "database_setup"
    DEPLOYMENT = "deployment"
    DEBUGGING = "debugging"


@dataclass
class WorkflowAnalysis:
    category: WorkflowCategory
    frequency: str  # daily, weekly, monthly
    time_to_complete: str  # minutes, hours, days
    pain_points: List[str]
    tools_involved: List[str]
    automation_potential: str  # high, medium, low


# Common workflows that benefit from golden paths
HIGH_VALUE_WORKFLOWS = [
    WorkflowAnalysis(
        category=WorkflowCategory.SERVICE_CREATION,
        frequency="weekly",
        time_to_complete="1-3 days",
        pain_points=[
            "Too many decisions to make",
            "Inconsistent project structures",
            "Missing security configurations",
            "No standard CI/CD setup",
        ],
        tools_involved=["Git", "Docker", "Kubernetes", "CI/CD", "IaC"],
        automation_potential="high",
    ),
    WorkflowAnalysis(
        category=WorkflowCategory.ENVIRONMENT_PROVISIONING,
        frequency="daily",
        time_to_complete="hours to days",
        pain_points=[
            "Manual ticket-based process",
            "Configuration drift",
            "Long wait times",
        ],
        tools_involved=["Terraform", "Cloud Console", "Tickets"],
        automation_potential="high",
    ),
]

Step 2: Define the Path Layers

Step 3: Build Progressive Disclosure

Reveal complexity only when needed:

# Level 1: Simple - Just name and team
apiVersion: platform.example.com/v1
kind: Service
metadata:
  name: user-api
spec:
  team: checkout-team
  
---
# Level 2: Intermediate - Some customization
apiVersion: platform.example.com/v1
kind: Service
metadata:
  name: user-api
spec:
  team: checkout-team
  tier: production
  scaling:
    min: 3
    max: 10
  
---
# Level 3: Advanced - Full control
apiVersion: platform.example.com/v1
kind: Service
metadata:
  name: user-api
spec:
  team: checkout-team
  tier: production
  scaling:
    min: 3
    max: 10
    metrics:
      - type: cpu
        target: 70
      - type: memory
        target: 80
  networking:
    ingress:
      enabled: true
      tls: true
    egress:
      allowedHosts:
        - database.internal
        - cache.internal
  advanced:
    podDisruptionBudget:
      minAvailable: 2
    topologySpreadConstraints:
      - maxSkew: 1
        topologyKey: topology.kubernetes.io/zone

---

🚀 Implementation Patterns

Pattern 1: Service Templates

"""
Golden path service template generator.
Creates a new service with all required components.
"""

from dataclasses import dataclass, field
from pathlib import Path
from typing import List, Optional
import yaml
import os


@dataclass
class ServiceTemplate:
    name: str
    team: str
    language: str
    service_type: str  # api, worker, scheduled
    
    # Optional customizations
    database: Optional[str] = None  # postgres, mysql, none
    cache: Optional[str] = None  # redis, memcached, none
    messaging: Optional[str] = None  # kafka, rabbitmq, none
    
    # Golden path defaults
    port: int = 8080
    health_check_path: str = "/health"
    metrics_path: str = "/metrics"
    log_format: str = "json"


class GoldenPathGenerator:
    """Generate service from golden path template."""
    
    SUPPORTED_LANGUAGES = {
        "python": {
            "dockerfile": "python:3.11-slim",
            "package_manager": "poetry",
            "framework": "fastapi",
        },
        "go": {
            "dockerfile": "golang:1.21-alpine",
            "package_manager": "go mod",
            "framework": "chi",
        },
        "typescript": {
            "dockerfile": "node:20-alpine",
            "package_manager": "pnpm",
            "framework": "nestjs",
        },
    }
    
    def __init__(self, template: ServiceTemplate):
        self.template = template
        self.output_path = Path(f"./{template.name}")
    
    def generate(self) -> Path:
        """Generate complete service structure."""
        self._create_directory_structure()
        self._generate_dockerfile()
        self._generate_kubernetes_manifests()
        self._generate_ci_cd_pipeline()
        self._generate_documentation()
        return self.output_path
    
    def _create_directory_structure(self) -> None:
        """Create standard directory structure."""
        directories = [
            "src",
            "tests",
            "deploy/kubernetes",
            "deploy/terraform",
            ".github/workflows",
            "docs",
        ]
        
        for dir_path in directories:
            (self.output_path / dir_path).mkdir(parents=True, exist_ok=True)
    
    def _generate_kubernetes_manifests(self) -> None:
        """Generate Kubernetes deployment manifests."""
        deployment = {
            "apiVersion": "apps/v1",
            "kind": "Deployment",
            "metadata": {
                "name": self.template.name,
                "labels": {
                    "app": self.template.name,
                    "team": self.template.team,
                    "managed-by": "golden-path",
                },
            },
            "spec": {
                "replicas": 3,
                "selector": {
                    "matchLabels": {"app": self.template.name}
                },
                "template": {
                    "metadata": {
                        "labels": {
                            "app": self.template.name,
                            "team": self.template.team,
                        },
                        "annotations": {
                            "prometheus.io/scrape": "true",
                            "prometheus.io/path": self.template.metrics_path,
                            "prometheus.io/port": str(self.template.port),
                        },
                    },
                    "spec": {
                        "containers": [{
                            "name": self.template.name,
                            "image": f"registry.example.com/{self.template.team}/{self.template.name}:latest",
                            "ports": [{"containerPort": self.template.port}],
                            "livenessProbe": {
                                "httpGet": {
                                    "path": self.template.health_check_path,
                                    "port": self.template.port,
                                },
                                "initialDelaySeconds": 10,
                                "periodSeconds": 10,
                            },
                            "readinessProbe": {
                                "httpGet": {
                                    "path": self.template.health_check_path,
                                    "port": self.template.port,
                                },
                                "initialDelaySeconds": 5,
                                "periodSeconds": 5,
                            },
                            "resources": {
                                "requests": {"cpu": "100m", "memory": "128Mi"},
                                "limits": {"cpu": "500m", "memory": "512Mi"},
                            },
                            "env": [
                                {"name": "LOG_FORMAT", "value": self.template.log_format},
                                {"name": "SERVICE_NAME", "value": self.template.name},
                            ],
                        }],
                        "securityContext": {
                            "runAsNonRoot": True,
                            "runAsUser": 1000,
                        },
                    },
                },
            },
        }
        
        manifest_path = self.output_path / "deploy/kubernetes/deployment.yaml"
        with open(manifest_path, "w") as f:
            yaml.dump(deployment, f, default_flow_style=False)
    
    def _generate_ci_cd_pipeline(self) -> None:
        """Generate GitHub Actions workflow."""
        workflow = {
            "name": "CI/CD Pipeline",
            "on": {
                "push": {"branches": ["main", "develop"]},
                "pull_request": {"branches": ["main"]},
            },
            "env": {
                "REGISTRY": "registry.example.com",
                "IMAGE_NAME": f"{self.template.team}/{self.template.name}",
            },
            "jobs": {
                "test": {
                    "runs-on": "ubuntu-latest",
                    "steps": [
                        {"uses": "actions/checkout@v4"},
                        {"name": "Run tests", "run": "make test"},
                        {"name": "Run linting", "run": "make lint"},
                        {"name": "Security scan", "run": "make security-scan"},
                    ],
                },
                "build": {
                    "needs": "test",
                    "runs-on": "ubuntu-latest",
                    "if": "github.event_name == 'push'",
                    "steps": [
                        {"uses": "actions/checkout@v4"},
                        {
                            "name": "Build and push",
                            "uses": "docker/build-push-action@v5",
                            "with": {
                                "push": True,
                                "tags": "${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:${{ github.sha }}",
                            },
                        },
                    ],
                },
                "deploy": {
                    "needs": "build",
                    "runs-on": "ubuntu-latest",
                    "if": "github.ref == 'refs/heads/main'",
                    "steps": [
                        {"name": "Deploy to production", "run": "make deploy ENV=production"},
                    ],
                },
            },
        }
        
        workflow_path = self.output_path / ".github/workflows/ci-cd.yaml"
        with open(workflow_path, "w") as f:
            yaml.dump(workflow, f, default_flow_style=False)
    
    def _generate_dockerfile(self) -> None:
        """Generate Dockerfile based on language."""
        lang_config = self.SUPPORTED_LANGUAGES.get(self.template.language, {})
        base_image = lang_config.get("dockerfile", "alpine:latest")
        
        dockerfile_content = f"""# Generated by Golden Path Generator
FROM {base_image} AS builder

WORKDIR /app
COPY . .
RUN make build

FROM {base_image}
WORKDIR /app

# Security: Run as non-root user
RUN adduser -D -u 1000 appuser
USER appuser

COPY --from=builder /app/bin/app /app/app

EXPOSE {self.template.port}
HEALTHCHECK --interval=30s --timeout=3s \\
    CMD wget -q --spider http://localhost:{self.template.port}{self.template.health_check_path} || exit 1

ENTRYPOINT ["/app/app"]
"""
        
        dockerfile_path = self.output_path / "Dockerfile"
        with open(dockerfile_path, "w") as f:
            f.write(dockerfile_content)
    
    def _generate_documentation(self) -> None:
        """Generate README and docs."""
        readme = f"""# {self.template.name}

> Generated from Golden Path template

## Team
{self.template.team}

## Quick Start

```bash
# Run locally
make run

# Run tests
make test

# Build container
make build

# Deploy
make deploy ENV=staging

Architecture

• Language: {self.template.language}

• Port: {self.template.port}

• Health Check: {self.template.health_check_path}

• Metrics: {self.template.metrics_path}

Dependencies

{"- Database: " + self.template.database if self.template.database else ""} {"- Cache: " + self.template.cache if self.template.cache else ""} {"- Messaging: " + self.template.messaging if self.template.messaging else ""}

Golden Path Compliance

This service follows the organization's golden path standards:

• ✅ Standard directory structure

• ✅ CI/CD pipeline

• ✅ Health checks configured

• ✅ Metrics endpoint

• ✅ Structured logging

• ✅ Security scanning """

    readme_path = self.output_path / "README.md"
    with open(readme_path, "w") as f:
        f.write(readme)

Usage example

if name == "main": template = ServiceTemplate( name="order-processor", team="checkout-team", language="python", service_type="worker", database="postgres", messaging="kafka", )

generator = GoldenPathGenerator(template)
output = generator.generate()
print(f"✅ Service generated at: {output}")

### Pattern 2: Environment Provisioning

```python
"""
Golden path for environment provisioning.
Self-service with guardrails.
"""

from dataclasses import dataclass
from typing import Optional, List
from enum import Enum
import json


class EnvironmentTier(Enum):
    DEVELOPMENT = "development"
    STAGING = "staging"
    PRODUCTION = "production"


class Region(Enum):
    US_EAST = "us-east-1"
    US_WEST = "us-west-2"
    EU_WEST = "eu-west-1"
    AP_SOUTHEAST = "ap-southeast-1"


@dataclass
class EnvironmentRequest:
    """Self-service environment request."""
    name: str
    team: str
    tier: EnvironmentTier
    region: Region
    
    # Resource sizing (limited choices for golden path)
    size: str = "small"  # small, medium, large
    
    # Optional add-ons
    database: bool = False
    cache: bool = False
    
    # Expiry for non-production (auto-cleanup)
    expires_in_days: Optional[int] = None


class EnvironmentProvisioner:
    """Provision environments following golden path."""
    
    SIZE_MAPPINGS = {
        "small": {"cpu": "1", "memory": "2Gi", "nodes": 2},
        "medium": {"cpu": "2", "memory": "4Gi", "nodes": 3},
        "large": {"cpu": "4", "memory": "8Gi", "nodes": 5},
    }
    
    TIER_CONSTRAINTS = {
        EnvironmentTier.DEVELOPMENT: {
            "allowed_sizes": ["small"],
            "max_expiry_days": 7,
            "requires_approval": False,
        },
        EnvironmentTier.STAGING: {
            "allowed_sizes": ["small", "medium"],
            "max_expiry_days": 30,
            "requires_approval": False,
        },
        EnvironmentTier.PRODUCTION: {
            "allowed_sizes": ["medium", "large"],
            "max_expiry_days": None,  # No auto-expiry
            "requires_approval": True,
        },
    }
    
    def __init__(self, request: EnvironmentRequest):
        self.request = request
        self._validate()
    
    def _validate(self) -> None:
        """Validate request against golden path constraints."""
        constraints = self.TIER_CONSTRAINTS[self.request.tier]
        
        if self.request.size not in constraints["allowed_sizes"]:
            raise ValueError(
                f"Size '{self.request.size}' not allowed for {self.request.tier.value}. "
                f"Allowed: {constraints['allowed_sizes']}"
            )
        
        max_expiry = constraints["max_expiry_days"]
        if max_expiry and self.request.expires_in_days:
            if self.request.expires_in_days > max_expiry:
                raise ValueError(
                    f"Expiry cannot exceed {max_expiry} days for {self.request.tier.value}"
                )
    
    def provision(self) -> dict:
        """Provision the environment."""
        constraints = self.TIER_CONSTRAINTS[self.request.tier]
        
        if constraints["requires_approval"]:
            return self._create_approval_request()
        
        return self._provision_immediately()
    
    def _provision_immediately(self) -> dict:
        """Provision environment immediately."""
        resources = self.SIZE_MAPPINGS[self.request.size]
        
        terraform_vars = {
            "environment_name": self.request.name,
            "team": self.request.team,
            "tier": self.request.tier.value,
            "region": self.request.region.value,
            "node_count": resources["nodes"],
            "node_cpu": resources["cpu"],
            "node_memory": resources["memory"],
            "enable_database": self.request.database,
            "enable_cache": self.request.cache,
            "auto_delete_after": self.request.expires_in_days,
            "labels": {
                "managed-by": "golden-path",
                "team": self.request.team,
                "tier": self.request.tier.value,
            },
        }
        
        # In real implementation, trigger Terraform/Crossplane
        print(f"🚀 Provisioning environment: {self.request.name}")
        print(f"📋 Configuration: {json.dumps(terraform_vars, indent=2)}")
        
        return {
            "status": "provisioning",
            "environment_name": self.request.name,
            "estimated_time": "5 minutes",
            "config": terraform_vars,
        }
    
    def _create_approval_request(self) -> dict:
        """Create approval request for production."""
        return {
            "status": "pending_approval",
            "environment_name": self.request.name,
            "approvers": ["platform-team", f"{self.request.team}-lead"],
            "message": "Production environments require approval.",
        }


# Usage
if __name__ == "__main__":
    # Developer requests a dev environment (self-service)
    dev_request = EnvironmentRequest(
        name="feature-xyz-dev",
        team="checkout-team",
        tier=EnvironmentTier.DEVELOPMENT,
        region=Region.US_EAST,
        size="small",
        database=True,
        expires_in_days=3,
    )
    
    provisioner = EnvironmentProvisioner(dev_request)
    result = provisioner.provision()
    print(f"Result: {result}")

---

📊 Measuring Golden Path Adoption

Key Metrics

from dataclasses import dataclass
from datetime import datetime
from typing import List
from enum import Enum


class AdoptionLevel(Enum):
    FULL = "full"  # Using golden path as-is
    PARTIAL = "partial"  # Using with customizations
    NONE = "none"  # Not using golden path


@dataclass
class GoldenPathMetrics:
    """Track golden path adoption and effectiveness."""
    
    # Adoption metrics
    total_services: int
    services_on_golden_path: int
    services_with_customizations: int
    services_off_path: int
    
    # Velocity metrics
    avg_time_to_deploy_on_path: float  # minutes
    avg_time_to_deploy_off_path: float  # minutes
    
    # Quality metrics
    incidents_on_path: int
    incidents_off_path: int
    security_issues_on_path: int
    security_issues_off_path: int
    
    @property
    def adoption_rate(self) -> float:
        """Percentage of services using golden path."""
        return (self.services_on_golden_path / self.total_services) * 100
    
    @property
    def time_savings(self) -> float:
        """Time saved by using golden path."""
        return self.avg_time_to_deploy_off_path - self.avg_time_to_deploy_on_path
    
    @property
    def quality_improvement(self) -> float:
        """Incident reduction on golden path."""
        if self.incidents_off_path == 0:
            return 0
        return ((self.incidents_off_path - self.incidents_on_path) 
                / self.incidents_off_path) * 100
    
    def generate_report(self) -> str:
        """Generate adoption report."""
        return f"""
Golden Path Adoption Report
===========================

📊 Adoption
- Total Services: {self.total_services}
- On Golden Path: {self.services_on_golden_path} ({self.adoption_rate:.1f}%)
- With Customizations: {self.services_with_customizations}
- Off Path: {self.services_off_path}

⏱️ Velocity
- Deploy Time (On Path): {self.avg_time_to_deploy_on_path:.1f} minutes
- Deploy Time (Off Path): {self.avg_time_to_deploy_off_path:.1f} minutes
- Time Saved: {self.time_savings:.1f} minutes per deployment

🛡️ Quality
- Incidents (On Path): {self.incidents_on_path}
- Incidents (Off Path): {self.incidents_off_path}
- Quality Improvement: {self.quality_improvement:.1f}%
- Security Issues (On Path): {self.security_issues_on_path}
- Security Issues (Off Path): {self.security_issues_off_path}
"""


# Example metrics
metrics = GoldenPathMetrics(
    total_services=150,
    services_on_golden_path=120,
    services_with_customizations=20,
    services_off_path=10,
    avg_time_to_deploy_on_path=15.0,
    avg_time_to_deploy_off_path=90.0,
    incidents_on_path=5,
    incidents_off_path=25,
    security_issues_on_path=2,
    security_issues_off_path=15,
)

print(metrics.generate_report())

---

🔄 Evolving Golden Paths

Feedback Loop

Version Management

# golden-path-version.yaml
apiVersion: platform.example.com/v1
kind: GoldenPathVersion
metadata:
  name: service-template
spec:
  version: "2.1.0"
  
  changelog:
    - version: "2.1.0"
      date: "2025-01-15"
      changes:
        - "Added OpenTelemetry tracing support"
        - "Updated base images for security patches"
        - "Improved health check defaults"
    
    - version: "2.0.0"
      date: "2025-01-01"
      changes:
        - "Breaking: Migrated from custom logging to structured JSON"
        - "Added automatic secret injection"
        - "New: Support for gRPC services"
  
  migration:
    from: "1.x"
    to: "2.x"
    guide: "https://docs.example.com/golden-path/migration-v2"
    automated: true
    
  deprecation:
    version: "1.x"
    sunset_date: "2025-06-01"
    message: "Please upgrade to v2.x for continued support"

---

✅ Best Practices

Do's

1. Start with pain points - Build paths for actual developer struggles

2. Get feedback early - Pilot with friendly teams first

3. Make adoption easy - One command to get started

4. Document escape hatches - Clear guidance for exceptions

5. Measure everything - Track adoption, velocity, quality

6. Iterate frequently - Update based on feedback

Don'ts

1. Don't mandate without value - Paths should be attractive, not forced

2. Don't over-abstract - Developers need to understand what's happening

3. Don't ignore edge cases - Plan for the 20% that need flexibility

4. Don't set and forget - Paths require ongoing maintenance

5. Don't skip documentation - Clear docs drive adoption

---

📝 Practice Exercise

Design a golden path for your organization:

1. Identify the top 3 most time-consuming developer workflows

2. Map the current steps and pain points

3. Design an opinionated path that eliminates friction

4. Define escape hatches for legitimate exceptions

5. Plan metrics to track adoption and effectiveness

---

🔗 What's Next?

In Article 7: Platform Capabilities Model, we'll explore Microsoft's framework for assessing and building platform engineering maturity across six key capability areas.

---

📚 References

• Paved Roads at Spotify

• Golden Paths at Netflix

• Thoughtworks on Platform Engineering

• Team Topologies