Platform Golden Path: [Path name]

Specification of one supported, opinionated route for building and running a type of software on the internal platform: who it is for, what it covers, the chosen stack, the scaffolding template, CI/CD, environments, observability and security defaults, service catalogue registration, support, adoption metrics and how to deviate. Based on common platform engineering practice; the catalogue example uses the Backstage catalog-info.yaml descriptor format. Replace every [bracketed] value and every row marked Example. Worked examples use a "Java HTTP service on Kubernetes" path.

1. Target users and problem

Target users: [Example: Stream-aligned teams building synchronous HTTP services in Java that store data in PostgreSQL.]

Problem today: [Example: Creating a production-ready service takes three to five weeks: teams copy an older service, re-create pipelines, request databases by ticket and wire monitoring by hand. Security findings repeat across services.]

Promise of the path: [Example: From empty repository to a service in production with monitoring, alerting and security scanning in under one day, without tickets.]

2. Path scope

The flow below shows the developer journey the path covers.

3. Opinionated stack

4. Scaffolding template

Inputs requested: service name, owning team, tier (1 to 3), database yes or no, public or internal API, data classification.

Generated:

• repository with application skeleton, health endpoints, sample endpoint and tests;
• OpenAPI document and contract test setup;
• Dockerfile, Helm values per environment, pipeline definition;
• catalog-info.yaml, README.md, docs/ with runbook and ADR folder;
• dashboards and alert rules as code;
• dependency update bot configuration.

Template lifecycle: changes to the template are released with versions; existing services receive upgrade pull requests from [tool].

5. CI/CD

Lead time target from merge to production: [under 60 minutes].

6. Environments

7. Observability defaults

• Structured JSON logs with trace ID, shipped to [log platform], retained [30 days].
• OpenTelemetry tracing auto-instrumented; sampling [10%] plus all errors.
• Metrics: RED (rate, errors, duration) per endpoint, JVM and pool metrics.
• Dashboard per service generated from template.
• Default SLO for tier 1: availability 99.9% over 30 days, p95 latency under [300 ms]; burn-rate alerts route to the owning team.

The default error budget follows from the SLO: $(1 - 0.999) \times 30 \times 24 \times 60 \approx 43$ minutes per 30 days.

8. Security defaults

9. Service catalogue registration

The scaffolding creates this descriptor at the repository root; the catalogue discovers it automatically.

apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: order-history
  description: Read API for customers' past orders
  annotations:
    github.com/project-slug: example-org/order-history
    backstage.io/techdocs-ref: dir:.
  tags:
    - java
    - golden-path-gp-003
spec:
  type: service
  lifecycle: production
  owner: group:team-orders
  system: ordering
  providesApis:
    - order-history-api
  dependsOn:
    - resource:order-history-db
---
apiVersion: backstage.io/v1alpha1
kind: API
metadata:
  name: order-history-api
spec:
  type: openapi
  lifecycle: production
  owner: group:team-orders
  system: ordering
  definition:
    $text: ./api/openapi.yaml

10. Support model

11. Adoption metrics

12. Deviation process

Deviation requests are filed in [platform intake] and reviewed weekly. Each approved deviation is recorded below and considered for the path roadmap.

Standard and licence note

Based on common platform engineering practice for golden paths (also called paved roads). The catalogue descriptor example follows the Backstage software catalog descriptor format (backstage.io/v1alpha1, kinds Component and API) as documented at https://backstage.io; Backstage is a CNCF project and no documentation text is reproduced. All text and examples are original to this collection. Template licence: MIT.