platform-engineering

name	platform-engineering
description	Architect an Internal Developer Platform (IDP) with golden paths, Backstage, Score, and Crossplane. Use when establishing platform-as-product, paved roads, or replacing ticket-driven ops with self-service for stream-aligned teams.

Platform Engineering

An Internal Developer Platform reduces cognitive load for stream-aligned teams by curating a thin, opinionated layer over cloud and tooling. Treat it as a product: real users, a roadmap, SLAs, and adoption metrics, not a side project of the ops team.

Stack Baseline (2026)

Concern	Recommended
Developer portal	Backstage 1.30+ (CNCF incubating), Port, Cortex
Workload spec	Score (score.dev), OAM, Radius
Control plane	Crossplane v2, Kratix, Humanitec, Upbound
GitOps	Argo CD, Flux 2; Argo Workflows / Tekton
Runtime	Kubernetes + service mesh (Istio ambient, Linkerd)
Policy	OPA Gatekeeper, Kyverno, Conftest
Secrets / identity	External Secrets, SPIFFE/SPIRE, Workload Identity
Observability	OpenTelemetry, Prometheus, Grafana, Tempo, Loki
Org model	Team Topologies (stream-aligned + platform team)
Reference	CNCF Platforms WG, "Platforms White Paper" v2 (2024)

When to Use

• Cognitive load on product teams is degrading flow (DORA dropping).
• Inconsistent service quality, security, and cost across teams.
• Multiple bespoke pipelines and infra patterns per team.
• Scaling beyond ~5 stream-aligned teams sharing infra.

Prerequisites

• Executive sponsor; platform team funded as product team.
• At least one stream-aligned pilot team willing to co-design.
• Baseline metrics: lead time, deploy frequency, change-failure rate, dev NPS.

Instructions

flowchart LR
  U[Stream-aligned teams] -->|Score / templates| P[Backstage portal]
  P --> G[GitOps repos]
  G --> CP[Crossplane / Kratix control plane]
  CP --> K[Kubernetes + cloud APIs]
  K --> O[OTel telemetry]
  O --> P
  Pol[OPA / Kyverno policies] --> CP
  Pol --> K

1. Define the platform as product. Vision, personas, jobs-to-be-done, success metrics (lead time, time-to-first-deploy, % adoption, dev NPS). Publish a roadmap.
2. Design golden paths for the top 3-5 workload archetypes (stateless API, async worker, batch job, frontend, ML service). Each path is opinionated end-to-end: scaffold, build, deploy, observe, secure, deprecate.
3. Abstract workloads with Score so developers describe intent, not Kubernetes YAML. Platform translates Score to environment-specific manifests.
4. Build the control plane with Crossplane / Kratix: declarative composite resources (XRDs / Promises) for databases, queues, buckets, DNS. Multi-tenant by default.
5. Integrate Backstage as the front door: software catalog, TechDocs, scaffolder templates, scorecards (security, reliability, FinOps), TechInsights.
6. Enforce paved-road policy via OPA/Kyverno: only platform-issued composites in prod, signed images, OTel mandatory, SLOs declared.
7. Run as product. Office hours, RFC process, quarterly user research, deprecation policy with SLAs. Measure adoption vs. shadow IT.

# score.yaml - developer-authored
apiVersion: score.dev/v1b1
metadata: { name: orders-api }
containers:
  api:
    image: ghcr.io/acme/orders-api:1.4.2
    variables: { DB_URL: "${resources.db.uri}" }
resources:
  db:    { type: postgres }
  queue: { type: amqp }
  route: { type: route, params: { host: orders.acme.com } }

# Crossplane Composition fragment - platform-owned
apiVersion: apiextensions.crossplane.io/v2
kind: Composition
metadata: { name: postgres.acme.platform }
spec:
  compositeTypeRef: { apiVersion: platform.acme/v1, kind: XPostgres }
  mode: Pipeline
  pipeline:
    - step: render
      functionRef: { name: function-kcl }

Common Pitfalls

Pitfall	Mitigation
Platform built without users	Co-design with one stream-aligned team first
YAML-as-API leaks K8s complexity	Use Score / OAM / Radius abstractions
Mandate before product readiness	Earn adoption; mandates only after parity
One golden path forced on all	Offer 3-5 archetypes; allow exception paths
Platform team becomes ticket queue	Self-service via portal; office hours, not tickets
No deprecation strategy	Versioned templates with EOL dates and migration tooling

Output Format

• Platform product page: vision, personas, golden paths, SLAs, roadmap.
• Backstage scaffolder templates per archetype.
• Crossplane / Kratix composite catalog with versioning.
• Score reference + examples; policy bundle in repo.
• Adoption dashboard: % services on golden path, dev NPS, DORA.

Authoritative References

• CNCF Platforms WG, Platforms White Paper, v2, 2024.
• Skelton & Pais, Team Topologies, IT Revolution.
• Humanitec, Platform Engineering Maturity Model 2025.
• Score specification (score.dev); Crossplane v2 docs; Backstage 1.30 docs.
• Gartner, "Hype Cycle for Platform Engineering", 2025.
• ThoughtWorks Technology Radar Vol. 31 (Platform engineering = Adopt).