# 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.

<!--
Guidance: How to use this template
- One document per golden path. A path is a product: it has users, a
  roadmap, an owner and metrics. Write it from the user's point of view.
- Fill sections 1 to 3 first and validate them with two or three real
  teams before building scaffolding. Paths built without users go unused.
- Be explicit about what is optional and what is enforced. "Golden" means
  recommended and supported, not mandatory, unless section 12 says so.
- Keep the defaults in sections 5 to 8 in sync with the template
  repository; link to the exact version.
-->

| Field | Value |
|---|---|
| Path name | [Java HTTP service on Kubernetes] |
| Path ID | [GP-003] |
| Version | [2.1] |
| Status | [Alpha / Beta / Generally available / Deprecated] |
| Owning platform team | [@platform-runtime] |
| Product manager | [@platform-pm] |
| Template repository | [git URL @ tag] |
| Developer portal entry | [Link] |
| Last updated | YYYY-MM-DD |

## 1. Target users and problem

<!-- Guidance: Who should use this path and what pain it removes. Measure the pain before and after. Mistake: a path for "all developers" that fits nobody well. -->

**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

<!-- Guidance: What the path covers end to end, and what it does not. Non-goals prevent the path from growing into a framework nobody can maintain. -->

| In scope | Out of scope |
|---|---|
| *Example:* New HTTP services and APIs | Batch jobs and stream processors (see GP-005) |
| *Example:* PostgreSQL and Redis | Other databases (deviation process) |
| *Example:* Deployment to [shared Kubernetes clusters] | Serverless functions |
| *Example:* Internal and public APIs behind the API gateway | Services needing PCI DSS scope (use GP-007) |

The flow below shows the developer journey the path covers.

```mermaid
flowchart LR
  A["Create from template in portal"] --> B["Repository and pipeline created"]
  B --> C["First commit builds, tests, scans"]
  C --> D["Auto-deploy to dev"]
  D --> E["Promote to staging"]
  E --> F["Promote to production"]
  F --> G["Dashboards, alerts, catalogue entry live"]
```

## 3. Opinionated stack

<!-- Guidance: The specific choices, with versions and the reason. Each choice should be supported by the platform team for at least the next year. -->

| Layer | Choice | Version policy | Why |
|---|---|---|---|
| Language and runtime | *Example:* Java on Eclipse Temurin | Current LTS; upgrade within 6 months of new LTS | Organisation skill base |
| Framework | *Example:* Spring Boot | Supported release line | Mature, wide knowledge |
| Build | *Example:* Gradle with organisation plugin | Pinned in template | Shared conventions |
| Database | *Example:* Managed PostgreSQL | Platform-managed minor upgrades | Default relational store |
| Cache | *Example:* Managed Redis | Platform-managed | Optional module |
| API contract | *Example:* OpenAPI document in `api/` | Linted with organisation ruleset | API-first review |
| Container base image | *Example:* Distroless Java image | Rebuilt weekly | Small attack surface |
| Runtime platform | *Example:* Kubernetes via Helm chart `service-base` | Chart version pinned | Shared operations |
| [Layer] | [Choice] | [Policy] | [Reason] |

## 4. Scaffolding template

<!-- Guidance: What the template generates and which inputs it asks for. Users should get a running, deployable service, not a skeleton with gaps. -->

**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

<!-- Guidance: The pipeline stages, gates and time budget. State which gates block deployment. -->

| Stage | What runs | Blocking | Time budget |
|---|---|---|---|
| Build and unit test | Compile, unit tests, coverage report | Yes | 5 min |
| Static analysis | Linting, OpenAPI lint, SAST | Yes on high severity | 3 min |
| Dependency and image scan | SCA, container scan, licence check | Yes on critical | 3 min |
| SBOM and signing | SBOM generated, image signed, provenance attested | Yes | 1 min |
| Deploy to dev | Automatic on main | n/a | 5 min |
| Integration and contract tests | Against dev | Yes | 10 min |
| Promote to staging and production | Automatic for tier 3; one approval for tier 1 and 2 | Yes | 10 min |

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

## 6. Environments

<!-- Guidance: The environments a service on this path gets and how they differ. -->

| Environment | Purpose | Data | Created | Access |
|---|---|---|---|---|
| Preview | Per pull request | Synthetic | Automatically, deleted on merge | Team |
| Dev | Integration | Synthetic | With service | Engineering |
| Staging | Release verification, load tests | Anonymised copy | With service | Engineering |
| Production | Live traffic | Real | With service | On-call and break-glass only |

## 7. Observability defaults

<!-- Guidance: What every service gets without extra work. Users should only add business-specific signals. -->

- 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

<!-- Guidance: Controls that are on by default. Every default removed must go through the deviation process. -->

| Control | Default |
|---|---|
| Identity | Workload identity per service; no long-lived credentials |
| Secrets | Pulled from [secrets manager] at runtime; none in repository or images |
| Network | Deny-all network policy plus declared dependencies; mTLS in mesh |
| Ingress | Through API gateway with OAuth 2.0 token validation |
| Container | Non-root user, read-only file system, no privilege escalation |
| Dependencies | Automated update pull requests; critical CVEs fixed within [7 days] |
| Data | Encryption at rest and in transit; data classification label required |

## 9. Service catalogue registration

<!-- Guidance: Every service on the path is registered automatically. The descriptor below follows the Backstage catalog format; adapt annotations to your plugins. -->

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

```yaml
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

<!-- Guidance: What the platform team supports, how fast, and what remains the service team's job. -->

| Topic | Platform team | Service team |
|---|---|---|
| Template, pipeline, base chart | Owns and fixes | Applies upgrade pull requests within [30 days] |
| Cluster and managed databases | Operates, on call 24/7 | Uses within quotas |
| Application code and data | Advises | Owns, on call |
| Questions | `#platform-help`, answer within 4 working hours | n/a |
| Office hours | [Thursday 14:00] | Optional |

## 11. Adoption metrics

<!-- Guidance: Measure whether the path delivers its promise, not only how many use it. -->

| Metric | Baseline | Target | Current |
|---|---|---|---|
| Time from template to first production deploy | 3 to 5 weeks | < 1 day | [Value] |
| Share of new services created from the path | 0% | 80% | [Value] |
| Services on the latest template version (within 30 days) | n/a | 90% | [Value] |
| Developer satisfaction with the path (survey, 1 to 5) | n/a | >= 4.0 | [Value] |
| Repeat security findings per service per quarter | 6 | < 1 | [Value] |
| Deviation requests per quarter | n/a | Tracked; trend reviewed | [Value] |

## 12. Deviation process

<!-- Guidance: Teams will need to step off the path. Make it easy to ask, record the reason and feed it back into the roadmap. Distinguish recommended defaults from enforced guardrails. -->

| Category | Examples | Who approves | Conditions |
|---|---|---|---|
| Free choice | Libraries inside the service, test frameworks | Nobody | Must pass pipeline gates |
| Recommended default | Database engine, framework | Team lead, recorded in ADR | Team accepts extra support responsibility |
| Enforced guardrail | Secrets handling, image signing, network policy | Security lead and platform lead | Time-limited exception with compensating control |

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

| ID | Service | Deviation | Reason | Approved by | Expires |
|---|---|---|---|---|---|
| DEV-01 | *Example:* search-indexer | Uses OpenSearch instead of PostgreSQL | Full-text relevance needs | @team-lead (ADR-019) | n/a |
| [DEV-NN] | [Service] | [Deviation] | [Reason] | [@name] | YYYY-MM-DD |

## 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.