Platform Engineering

Building internal developer platforms — golden paths, self-service, and the team that scales engineering.

What Problem Platform Engineering Solves

As organizations grow, every product team rebuilds the same things:
• CI/CD pipelines
• Kubernetes manifests
• Monitoring setup
• Database provisioning
• Service-to-service auth
• Logging conventions

Each team's version is slightly different. Onboarding a new engineer means learning your team's particular setup. Knowledge silos form. Standards drift. Security audits become detective work.

The platform engineering answer: a small dedicated team builds an Internal Developer Platform (IDP) that ABSTRACTS the complexity. Product teams get golden paths: easy ways to do the right thing, without becoming Kubernetes experts.

Mature platform engineering shows up as:
• "Run pf new service to scaffold a new service with all defaults"
• "Push to main, your service is auto-deployed with monitoring, logging, certs"
• "Want a Postgres database? Submit a ticket in our Backstage portal."
• "All services automatically get tracing, metrics, structured logs"

The platform team makes the right thing the easy thing. Product teams ship faster because they're not reinventing infrastructure.

Golden Paths

A golden path is the supported, easy way to do something common. Examples:

Golden path: deploy a new microservice
1. pf new service my-api --template=node-typescript-rest
2. Tool scaffolds repo with all standards: Dockerfile, CI, K8s manifests, observability hooks
3. Push code to GitHub
4. CI builds, scans, signs, pushes image
5. ArgoCD deploys to dev automatically
6. PR to bump prod tag → review → ArgoCD deploys to prod
7. Service appears in service catalog with auto-generated docs

Golden path: provision a database
1. Open Backstage portal
2. Click "Request database"
3. Pick template: postgres-small / postgres-large / mysql-cluster
4. Submit
5. Terraform module runs, creates RDS instance, secret in Vault, monitoring setup
6. Connection details delivered via Slack message

The point: making the right thing easy. NOT making everything else impossible. Teams that need to deviate can — they just don't get the support and convenience.

Anti-pattern: "platform mandates" that block teams from doing their work. Mandates breed shadow IT. Convenience wins compliance every time.

Tools for golden paths:
• Backstage (Spotify open-source) — most popular service catalog and template engine
• Port — commercial alternative
• Custom CLIs — pf new ..., kustomize templates, etc.

Building an Internal Developer Platform

A typical IDP has these components:

1. Service catalog — every service registered with metadata
   • Owner, on-call rotation
   • Dependencies
   • Documentation
   • Dashboards, runbooks, playbooks
   • Backstage is the standard

2. Self-service infrastructure
   • Provision databases, queues, caches via UI or CLI
   • Backed by Terraform / Pulumi / Crossplane
   • No tickets or wait times

3. Standardized CI/CD
   • Reusable workflows / templates
   • Built-in scanning, signing, deployment
   • Hard to deviate from

4. Observability defaults
   • New services get dashboards, alerts, tracing automatically
   • Conventions enforced (log format, metric naming)

5. Documentation
   • TechDocs in Backstage
   • Auto-generated where possible (OpenAPI specs → API docs)

6. Cost and compliance dashboards
   • Per-team spend visibility
   • Per-service security posture
   • Compliance status

Crossplane — emerging tool: define cloud resources via K8s CRDs. Combined with ArgoCD, your entire cloud infra reconciles GitOps-style. Cool but requires investment.

For most companies: Backstage + Terraform modules + GitOps is the practical IDP.

Platform vs Product Mindset

The platform team isn't just operations with a new name. The mindset is different.

Operations team:
• Reactive: tickets come in, get processed
• Defines policies and enforces them
• Often a bottleneck

Platform team:
• Proactive: builds tools that prevent the need for tickets
• Defines defaults and makes deviation hard
• Builds an actual product (the platform)

Platform engineering principles:

1. Treat your platform as a product. You have users (the developers). Talk to them. Ship features they ask for. Measure satisfaction.

2. Internal NPS. Survey developers: "How likely are you to recommend our platform to a peer?" Track over time. Improvement directly translates to engineering productivity.

3. Self-service everything. If something requires a ticket, you've failed. The exceptions are things genuinely needing human review.

4. Deprecation is a real feature. Old paths must die for new ones to be adopted. Support sunsets. Communicate aggressively.

5. Document like crazy. Every feature has a quickstart. Every error has a runbook link. Discoverability matters more than feature count.

6. Measure adoption. New features that nobody uses are waste. Track usage of every part of the platform. Cut what's not adopted; double down on what is.

When to Invest in a Platform Team

Premature platforms are common and painful. Signs you're ready:

• 50+ engineers (below this, the cost outweighs the benefit)
• Multiple product teams duplicating infrastructure work
• Onboarding takes weeks because every team is different
• Security audits drag because each service is configured differently
• You're spending more time on ops than features

Signs you're NOT ready:
• 5 engineers (build platform later when there are teams to serve)
• You haven't even adopted basic IaC yet
• Product priorities are clear and concentrated

When you start: 2-3 platform engineers, ~5-15% of total engineering. They build the foundation. As the company grows, the platform team grows roughly in proportion.

Failure modes:
• Platform built without product team input → solving wrong problems
• Platform tries to handle everything → enormous, overcomplicated
• Platform team becomes a bottleneck → tickets pile up, not really self-service

Success looks like:
• Product teams ship faster
• Onboarding is hours, not weeks
• Compliance is automatic
• Cost and quality both visible per-team
• Platform engineers love their job because they're shipping product, not firefighting

Backstage in Practice

Backstage is Spotify's open-source developer portal — the de facto standard for service catalogs in 2026.

What Backstage gives you:
• Service catalog — every service indexed with metadata
• Software templates — scaffolding tools for new services
• Tech docs — markdown rendered as searchable docs alongside the catalog
• Plugins for everything — Kubernetes, ArgoCD, GitHub, Datadog, PagerDuty

A catalog-info.yaml in each repo:

apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: my-api
  description: User-facing API
  annotations:
    backstage.io/techdocs-ref: dir:.
    pagerduty.com/integration-key: abc123
spec:
  type: service
  lifecycle: production
  owner: team-platform
  system: user-platform
  dependsOn:
    - resource:postgres-prod
    - component:auth-service

Backstage indexes this and provides:
• Search across all services
• "What does this service depend on?" graphs
• Direct links to dashboards, runbooks, repos
• "Who owns this?" instantly answered

Templates — Backstage software templates let users scaffold new services through the UI:
1. Click "Create Component"
2. Pick template (microservice-typescript, lambda-python, etc.)
3. Fill form (service name, owner)
4. Backstage creates the repo, opens the PR, registers in catalog

Operationally: setup is non-trivial, but the value is massive. Most teams that adopt Backstage become enthusiastic about it within a quarter.

The next lesson — the final one in the series — covers edge computing and CDNs.