Production-grade guide to platform golden paths covering architecture patterns, implementation strategies, testing approaches, and operational best practices for enterprise engineering teams.
Platform Golden Paths are standardized, opinionated workflows that guide developers through the full lifecycle of building, deploying, and operating a service on a platform. They matter when a team ships multiple services, each with distinct requirements, and consistency, velocity, and reliability are more valuable than flexibility. A golden path is not a checklist; it is a *system*—a defined set of conventions, tools, and automation that, when followed, ensure every new service is production-ready, observant, and maintainable with minimal onboarding. It is the "way" the platform expects developers to work.
To start a new service, a developer runs platform new-service my-frontend in their project root. The command invokes a CLI that reads a platform.yaml file in the project root and generates a template service structure.
name: my-frontend
type: web
runtime: react
base-image: ubuntu:22.04
dependencies:
- npm
- node:18
- typescript
- tailwindcss
build:
command: npm run build
output: dist/
artifacts:
- path: dist/
type: static
- path: dist/
type: bundle
format: esm
cache:
- key: "npm-${platform.git.commit}"
path: ~/.npm
- key: "tsc-${platform.git.commit}"
path: .tsc-cacheThe command creates a directory structure with src/, public/, package.json, Dockerfile, and platform.yaml. It initializes a Git repository with a main branch and configures the platform's continuous integration (CI) pipeline.
The generated Dockerfile includes a multi-stage build:
FROM node:18 as builder
WORKDIR /app
COPY package*.json ./
RUN npm install
COPY . .
RUN npm run build
FROM nginx:alpine
COPY --from=builder /app/dist /usr/share/nginx/html
EXPOSE 80
CMD ["nginx", "-g", "daemon off;"]The service is automatically registered in the platform’s service catalog, and a platform.json file is created at the root:
{
"service": "my-frontend",
"version": "0.1.0",
"created": "2024-04-11T10:30:00Z",
"ci": {
"pipeline": "my-frontend-build",
"branch": "main",
"trigger": "push"
},
"deploy": {
"environment": "staging",
"target": "k8s-staging",
"strategy": "rolling"
}
}This platform.json is consumed by the platform’s deployment orchestrator.
Deployments are triggered by pushing to a branch named deploy/staging or by creating a pull request to main. The platform listens for Git events via a webhook that posts to https://platform/api/v1/hooks/git with a JSON body:
{
"event": "push",
"repository": "my-frontend",
"ref": "refs/heads/deploy/staging",
"commit": "a1b2c3d4e5f67890",
"author": "[email protected]",
"payload": {
"branch": "deploy/staging",
"target": "staging"
}
}The platform validates the payload and invokes platform deploy --environment staging --commit a1b2c3d4e5f67890.
Under the hood, the command:
platform.json and platform.yaml.build.command and build.output.services/my-frontend/0.1.0/a1b2c3d4e5f67890.tar.gz.platform.yaml and the built artifacts.# k8s/deploy-staging.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
name: my-frontend-staging
labels:
app: my-frontend
environment: staging
spec:
replicas: 3
selector:
matchLabels:
app: my-frontend
environment: staging
template:
metadata:
labels:
app: my-frontend
environment: staging
spec:
containers:
- name: frontend
image: registry.example.com/my-frontend:0.1.0-a1b2c3d4e5f67890
ports:
- containerPort: 80
env:
- name: NODE_ENV
value: "staging"
- name: LOG_LEVEL
valueFrom:
configMapKeyRef:
name: common-config
key: log_level
resources:
limits:
memory: "256Mi"
cpu: "250m"
requests:
memory: "128Mi"
cpu: "125m"
---
apiVersion: v1
kind: Service
metadata:
name: my-frontend-staging
spec:
selector:
app: my-frontend
environment: staging
ports:
- protocol: TCP
port: 80
targetPort: 80
type: LoadBalancerThe platform applies this manifest using kubectl apply -f - and waits for the rollout to complete, checking kubectl get pods -l app=my-frontend -l environment=staging --watch.
If any pod fails to reach Ready status, the deployment logs a failure:
Error: Pod my-frontend-staging-789abc1234 failed readiness probe:
- Container frontend failed liveness probe: HTTP 503
- Log from container: "Error: Failed to load config: ENOENT: no such file or directory, open '/app/config.json'"The platform marks the deployment as failed and sends an alert via the platform’s notification service to the team’s Slack channel.
The platform enforces a unified configuration model. All services read configuration from a combination of:
config.yaml in the service’s rootconfig/production.yaml, config/staging.yaml, etc./etc/config in the container.The platform expects configuration to be structured as a flat hierarchy with nested objects. For example:
# config/staging.yaml
database:
url: postgres://staging-db.example.com:5432/myapp
pool_size: 16
logging:
level: info
format: json
features:
analytics: true
caching: enabled
feature_flags:
- name: "checkout-v2"
enabled: true
rollout: 0.75The platform automatically generates a ConfigMap from the config/ directory and applies it to the Kubernetes cluster.
Secrets are managed via a secrets/ directory. A secrets/production.yaml file contains:
# secrets/production.yaml
database:
password: "s3cr3t-p4ssw0rd"
username: "prod-user"
auth:
jwt:
secret: "long-secure-jwt-secret-here-12345"
issuer: "https://auth.example.com"
sso:
client_id: "prod-client-123"
client_secret: "sso-client-secret-67890"The platform uses platform secrets sync --environment production to push these secrets to a secrets manager (e.g., HashiCorp Vault, AWS Secrets Manager, or a custom key-value store) and mounts them as environment variables and files.
The command writes:
{
"action": "secrets.sync",
"environment": "production",
"status": "success",
"processed": 3,
"failed": 0,
"secrets": [
{
"name": "database.password",
"value": "s3cr3t-p4ssw0rd",
"updated": "2024-04-11T14:22:00Z"
},
{
"name": "auth.jwt.secret",
"value": "long-secure-jwt-secret-here-12345",
"updated": "2024-04-11T14:22:00Z"
}
]
}When a service starts, it reads secrets from /etc/secrets/*.json and /etc/secrets/*.yaml, merging them with config.yaml.
Every service must implement a health check endpoint at /health. The platform expects the response to be a JSON object with a status field and optional details:
{
"status": "ok",
"details": {
"database": "connected",
"cache": "healthy",
"queue": "processing"
},
"version": "0.1.0",
"build": "a1b2c3d4e5f67890"
}If the status is not ok, the platform marks the service as degraded or down.
The platform automatically configures a Kubernetes LivenessProbe and ReadinessProbe using the platform.yaml:
liveness:
path: /health
port: 80
initialDelaySeconds: 30
periodSeconds: 10
timeoutSeconds: 5
failureThreshold: 3
readiness:
path: /health
port: 80
initialDelaySeconds: 10
periodSeconds: 5
timeoutSeconds: 3
failureThreshold: 2The platform collects logs via journalctl and stdout from the container. All services are required to emit logs in JSON format with a timestamp, level, and message field.
A typical log line:
{
"timestamp": "2024-04-11T14:22:34.123Z",
"level": "info",
"message": "User logged in",
"userId": 12345,
"sessionId": "abc123-def456"
}The platform aggregates logs into a central stream and exposes them via a query API at https://platform/api/v1/logs.
When a developer pushes a change to main, the platform triggers a new build and deploys it to staging. After validation, they can promote the service to production by creating a release/production branch.
The platform automatically creates a platform-release.yaml file in the root:
# platform-release.yaml
version: 0.2.0
target: production
description: "Add user profile editing"
changes:
- "Add profile edit form"
- "Add avatar upload"
- "Fix pagination on mobile"
- "Update dependencies"
- "Optimize image loading"
- "Add caching layer"
- "Enable feature flag: checkout-v2"
deployments:
- environment: staging
status: success
started: "2024-04-11T15:00:00Z"
completed: "2024-04-11T15:15:00Z"
- environment: production
status: pending
started: nullThe platform applies this release manifest and deploys the service to production using the platform deploy --release production.
If a deployment fails in production, the platform allows rolling back to a previous version via platform rollback --service my-frontend --version 0.1.0.
The command:
platform.json for version 0.1.0.config/production.yaml to point to the earlier artifact.If the rollback fails, the platform logs:
Rollback failed for my-frontend:
- Failed to apply manifest: 'error: failed to apply: error: unable to connect to server'
- Health check failed after 5 minutes:
- /health returned 500: {"status": "error", "details": {"database": "timeout"}}The platform sends a notification and marks the service as rollback-in-progress.
platform.yaml: A service built but not deployed. The CI pipeline fails with "error: missing required file: platform.yaml".build.output path: Artifacts are not found in the expected location. The deployment logs show "error: no such file or directory: dist/".auth.jwt.secret is missing from the secrets store, but the secrets/production.yaml file has auth.jwt.secret instead of jwt.secret.Ready status because the initialDelaySeconds is too short and the application takes longer than expected to initialize.config/staging.yaml for production, leading to inconsistent behavior.The platform treats a golden path as a contract: when a service is created, it *must* follow the path. Deviations are caught early and documented. The golden path is not a guide—it is the system.
This page was rewritten on 18 October 2026. It replaced a templated version that was not specific to its own title. How these pages are written and checked. If anything here is wrong, tell us at [email protected] and we will correct it.
We use cookies for analytics (Google Analytics) and advertising (Google AdSense) to improve your experience and support free content. Privacy Policy