DevOps5 min read

Platform Engineering

Build Internal Developer Platforms - Backstage service catalog, golden paths, self-service infrastructure, and reducing cognitive load for product teams.

Platform EngineeringInternal Developer PlatformBackstageDeveloper ExperienceGolden Path

skill: Platform Engineering category: DevOps tags: [Platform Engineering, Internal Developer Platform, Backstage, Developer Experience, Golden Path] readingTime: 5

Platform engineering reduces cognitive load on product teams by providing paved roads (golden paths) for common tasks - creating a new service, deploying to production, adding a database. The platform team is a product team: the product is the developer experience. Measure it with DORA metrics and developer satisfaction surveys.

Workflow

Set up Backstage service catalogBackstage is the open-source platform from Spotify that provides a single pane of glass for all services - who owns them, what APIs they expose, their deployment status, and documentation.
Create software templates for golden pathsSoftware templates let developers create correctly configured new services via a form - with CI/CD, Kubernetes manifests, monitoring, and logging pre-configured, eliminating setup mistakes.
Provide self-service infrastructurePlatform engineering's core value: product teams provision databases, queues, and caches without filing tickets. Self-service with guardrails reduces wait time from days to minutes.
Measure developer experience with DORA metricsDORA metrics (Deployment Frequency, Lead Time, MTTR, Change Failure Rate) quantify developer productivity. Platform improvements should move these metrics.
Implement developer portals and documentationDevelopers can't use what they can't find. A developer portal aggregates runbooks, ADRs, API docs, and onboarding guides in one place.

Output Format

Platform engineering: Backstage catalog-info.yaml, software templates for golden paths, Crossplane for self-service infra, DORA metrics, and TechDocs for developer portal.

catalog-info.yaml: kind Component + owner + dependsOn
Template: fetch:template → publish:github → catalog:register
Self-service: Crossplane RDSInstance CR or Port actions
DORA: deployment frequency + lead time < 1hr + MTTR + CFR
TechDocs: MkDocs in repo → auto-rendered in Backstage

Examples

Input

Output

Edge Cases & Gotchas

Backstage plugin maintenance burden - Backstage has 100+ community plugins but many are unmaintained. Evaluate plugin health (last commit, open issues) before adopting - a broken plugin degrades the portal experience.
Golden path vs. flexibility - Golden paths cover 80% of use cases. For the other 20%, provide an escape hatch with slightly more friction (a ticket + review). Never make the golden path mandatory.
Platform team as bottleneck - A platform team of 3 can't unblock 50 product engineers. Focus on self-service first; anything requiring platform team involvement should be the exception, not the norm.
Catalog accuracy decay - Service catalog data becomes stale if not maintained. Use automated ingestion (GitHub topics, Kubernetes annotations) and make catalog-info.yaml part of service templates to keep data fresh.

When to Break These Rules

Don't start with Backstage for a 5-person team - a Notion wiki and a Slack channel is your platform. Platform engineering investment pays off at 50+ engineers.
Use Cortex.io or Humanitec instead of building on Backstage when you need a faster time-to-value - Backstage requires significant engineering investment to customize.

Reference Files

https://backstage.io/docs/
https://platformengineering.org/