| 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
- 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.
- 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.
- Abstract workloads with Score so developers describe intent, not Kubernetes YAML. Platform translates Score to environment-specific manifests.
- Build the control plane with Crossplane / Kratix: declarative composite resources (XRDs / Promises) for databases, queues, buckets, DNS. Multi-tenant by default.
- Integrate Backstage as the front door: software catalog, TechDocs, scaffolder templates, scorecards (security, reliability, FinOps), TechInsights.
- Enforce paved-road policy via OPA/Kyverno: only platform-issued composites in prod, signed images, OTel mandatory, SLOs declared.
- Run as product. Office hours, RFC process, quarterly user research, deprecation policy with SLAs. Measure adoption vs. shadow IT.
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 } }
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).
