Platform Engineering
Best practices for building Internal Developer Platforms (IDPs) that reduce cognitive load, accelerate delivery, and create golden paths for development teams.
IDP Architecture Layers
A well-designed IDP separates concerns into distinct layers. Each layer abstracts complexity from the one above it.
Developer Interface (Portal / CLI / API)
|
Orchestration Layer (Workflows, Templates, Scaffolding)
|
Integration Layer (APIs, Plugins, Connectors)
|
Resource Layer (Infrastructure, Services, Tools)
| Layer | Purpose | Components | Owned By |
|---|
| Developer Interface | Self-service entry point | Backstage portal, CLI tools, API gateway | Platform team |
| Orchestration | Workflow automation, templating | Scaffolder, Terraform modules, Crossplane | Platform team |
| Integration | Connect tools and services | Backstage plugins, API adapters, webhooks | Platform + tool owners |
| Resource | Actual infrastructure and services | Kubernetes, databases, CI/CD, monitoring | Infrastructure team |
| Governance | Policy enforcement and compliance | OPA, Kyverno, cost policies, security scans | Security + platform team |
Platform Team Topology and Responsibilities
Team Structure
| Role | Responsibility | Focus Area |
|---|
| Platform Product Manager | Roadmap, prioritization, user research | Developer needs, adoption metrics |
| Platform Engineer | IDP core, golden paths, automation | Infrastructure abstraction, tooling |
| Developer Advocate | Documentation, onboarding, feedback loops | DevEx, training, communication |
| SRE/Reliability Lead | Platform reliability, SLOs, incident response | Uptime, performance, observability |
| Security Engineer | Policy-as-code, compliance automation | Guardrails, scanning, access control |
Interaction Model
Stream-Aligned Teams (consumers)
|
| self-service requests
v
Platform Team (enablers)
|
| golden paths, templates, APIs
v
Infrastructure / Cloud (resources)
Platform teams operate as enabling teams (Team Topologies model). They reduce cognitive load on stream-aligned teams by providing curated, opinionated abstractions.
Backstage: Service Catalog and Developer Portal
catalog-info.yaml -- Service Registration
Every service registers itself in the catalog via a catalog-info.yaml at the repo root.
apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
name: payment-service
description: Handles payment processing and refunds
annotations:
github.com/project-slug: acme-corp/payment-service
backstage.io/techdocs-ref: dir:.
pagerduty.com/service-id: P1234ABC
grafana/dashboard-selector: "payment-service"
tags:
- java
- spring-boot
- payments
links:
- url: https://grafana.internal/d/payments
title: Dashboard
icon: dashboard
- url: https://runbooks.internal/payments
title: Runbook
icon: docs
spec:
type: service
lifecycle: production
owner: team-payments
system: checkout-system
providesApis:
Service Catalog API -- Querying Components
curl -s "https://backstage.internal/api/catalog/entities?filter=kind=component,spec.owner=team-payments" \
-H "Authorization: Bearer $BACKSTAGE_TOKEN" | jq '.[] | {name: .metadata.name, lifecycle: .spec.lifecycle}'
curl -s "https://backstage.internal/api/catalog/entities?filter=kind=component,spec.consumesApis=payment-api" \
-H "Authorization: Bearer $BACKSTAGE_TOKEN" | jq '.[] | .metadata.name'
curl -s "https://backstage.internal/api/catalog/entities/by-name/component/default/payment-service" \
-H "Authorization: Bearer $BACKSTAGE_TOKEN" | jq '{
name: .metadata.name,
owner: .spec.owner,
apis: .spec.providesApis,
dependencies: .spec.dependsOn
}'
Golden Path Templates
Golden paths are opinionated, pre-configured templates that encode best practices. They give teams a paved road to production.
Backstage Software Template
apiVersion: scaffolder.backstage.io/v1beta3
kind: Template
metadata:
name: spring-boot-service
title: Spring Boot Microservice
description: Creates a production-ready Spring Boot service with CI/CD, monitoring, and database
tags:
- java
- spring-boot
- recommended
spec:
owner: platform-team
type: service
parameters:
- title: Service Details
required:
- name
- owner
- description
properties:
name:
title: Service Name
type: string
pattern: '^[a-z][a-z0-9-]*$'
[, ]
[, , ]
[, ]
[, , ]
Golden Path Coverage Matrix
| Category | What the Golden Path Provides | Without Golden Path |
|---|
| Repository | Pre-configured with CI/CD, linting, CODEOWNERS | Manual setup, inconsistent configs |
| CI/CD | Working pipeline from day one | Copy-paste from other repos, broken configs |
| Observability | Dashboards, alerts, SLOs pre-configured | No monitoring until first incident |
| Security | Dependency scanning, SAST, secrets detection | Added retroactively (if at all) |
| Documentation | ADR template, README structure, API docs | Empty README, no docs |
| Infrastructure | Terraform modules, Kubernetes manifests | Hand-crafted YAML, drift between envs |
| Testing | Test framework, coverage gates, fixtures | Ad-hoc test setup, no coverage requirements |
Developer Experience Metrics (SPACE Framework)
Measure platform effectiveness using the SPACE framework. Never rely on a single dimension.
| Dimension | What It Measures | Example Metrics | Collection Method |
|---|
| Satisfaction | How developers feel about the platform | NPS score, satisfaction survey (1-5) | Quarterly survey |
| Performance | Outcome of developer work | Deployment frequency, change failure rate | DORA metrics pipeline |
| Activity | Volume of actions | Scaffolding requests, API calls, portal visits | Platform telemetry |
| Communication | Quality of collaboration | Time to first response on platform support | Ticketing system |
| Efficiency | Flow and minimal friction | Time from commit to deploy, onboarding time | Pipeline metrics |
Key DevEx Metrics Dashboard
metrics:
onboarding:
time_to_first_deploy:
target: "< 2 hours"
description: "Time from new hire to first successful deployment"
source: "scaffolder + pipeline timestamps"
time_to_first_commit:
target: "< 4 hours"
description: "Time from repo creation to first merged commit"
source: "github events"
self_service:
template_adoption_rate:
target: "> 80%"
description: "Percentage of new services using golden path templates"
source: "backstage scaffolder logs"
self_service_resolution_rate:
target: "> 70%"
description: "Percentage of requests resolved without platform team intervention"
source: "support tickets vs portal actions"
reliability:
platform_availability:
target: "99.9%"
description: "Uptime of developer portal, CI/CD, and artifact registry"
source: "synthetic monitoring"
mean_time_to_recovery:
target: "< 30 minutes"
description: "Time to restore platform services after incident"
Self-Service Portal Workflow
Request Flow Architecture
Developer submits request via Portal UI
|
v
Request Validation (schema check, policy check)
|
v
Approval Gate (if required by policy)
| |
| auto | manual
v v
Orchestration Engine (executes workflow)
|
+---> Provision Infrastructure (Terraform/Crossplane)
+---> Configure CI/CD (GitHub Actions / ArgoCD)
+---> Register in Catalog (Backstage)
+---> Set Up Monitoring (Grafana / PagerDuty)
+---> Notify Team (Slack / Email)
|
v
Verification (health checks, smoke tests)
|
v
Developer notified -- ready to use
Self-Service Capability Matrix
| Capability | Automation Level | Approval Required | Typical Time |
|---|
| Create new service | Fully automated | No | 5 minutes |
| Provision database | Fully automated | No (dev/staging), Yes (prod) | 10 minutes |
| Add CI/CD pipeline | Fully automated | No | 2 minutes |
| Request cloud credentials | Semi-automated | Yes (security review) | 1 hour |
| Create new environment | Fully automated | No (non-prod), Yes (prod) | 15 minutes |
| Add monitoring/alerts | Fully automated | No | 5 minutes |
| Resize infrastructure | Semi-automated | Yes (cost review > threshold) | 30 minutes |
| Decommission service | Automated with safeguards | Yes (owner confirmation) | 10 minutes |
Platform Engineering Maturity Model
| Level | Name | Characteristics | Capabilities |
|---|
| 0 | Ad Hoc | No platform, tribal knowledge | Teams manage their own infra |
| 1 | Reactive | Shared scripts, wiki docs | Basic CI/CD, manual provisioning |
| 2 | Standardized | Golden paths, basic portal | Service templates, catalog, basic self-service |
| 3 | Optimized | Full IDP, metrics-driven | Self-service everything, DevEx metrics, policy-as-code |
| 4 | Strategic | Platform as product, innovation | API-first platform, marketplace, continuous feedback |
Maturity Assessment Checklist
Level 1 --> Level 2:
[x] Service catalog exists and is maintained
[x] At least 3 golden path templates available
[x] Basic developer portal deployed
[x] CI/CD standardized across teams
Level 2 --> Level 3:
[x] Self-service for >80% of common requests
[x] SPACE metrics collected and reviewed monthly
[x] Policy-as-code enforced (not advisory)
[x] Platform team has dedicated product manager
[x] Internal SLOs defined for platform services
Level 3 --> Level 4:
[x] API-first platform (all capabilities programmable)
[x] Internal developer marketplace for plugins/extensions
[x] Continuous developer experience research program
[x] Platform economics model (cost attribution per team)
[x] Platform contributes to organizational strategy
Anti-Patterns
| Anti-Pattern | Problem | Fix |
|---|
| Build it and they will come | No adoption without developer input | Treat platform as product; user research before building |
| Ticket-ops disguised as platform | Self-service portal that just creates tickets | Automate end-to-end; tickets are a smell, not a solution |
| Mandating platform use | Forced adoption breeds resentment and workarounds | Make the golden path the easiest path, not the only path |
| One-size-fits-all templates | Overly rigid templates that don't fit team needs | Composable templates with sensible defaults and escape hatches |
| No feedback loops | Platform team builds in isolation | Regular surveys, office hours, embedded rotations with teams |
| Ignoring developer experience | Technically correct but painful to use | Measure DevEx metrics, optimize for developer happiness |
| Platform team as bottleneck | All changes go through platform team | Self-service with guardrails; teams should not wait on platform |
| Over-abstracting too early | Complex abstraction layers before understanding needs | Start with concrete solutions, abstract when patterns emerge |
| Neglecting documentation | Powerful platform nobody knows how to use | Docs-as-code, TechDocs in Backstage, examples for everything |
| No platform SLOs | Platform reliability treated as best-effort | Define and publish SLOs; platform is a product with SLAs |
| Shadow platforms | Teams build their own tooling around the platform | Understand why and address gaps; shadow platforms reveal unmet needs |
| Gold plating the portal | Spending months on portal UI before delivering value | Ship incrementally; a working CLI beats a beautiful but empty portal |
Platform Engineering Checklist
