Internal Developer Platforms

An Internal Developer Platform (IDP) is the product you build for your engineers. Not the cluster. Not the CI pipeline. The portal through which engineers discover, create, deploy, observe, and own software — without becoming Kubernetes experts.

The term "platform engineering" gained currency around 2022 as the industry realized that "give every team kubectl and good luck" produces neither productivity nor consistency. An IDP packages cluster, pipeline, monitoring, secrets, and policies into a small set of self-service paths.

Why an IDP

The IDP doesn't replace the underlying tools (Kubernetes, CI, Vault, monitoring). It composes them into the experience engineers want.

The Three Layers

A real IDP has three layers:

┌────────────────────────────────────────────┐
│  Developer Portal (Backstage / Port)       │  ← what engineers see
│  - Catalog, docs, scaffolders, dashboards  │
├────────────────────────────────────────────┤
│  Platform Orchestrator (Crossplane / Humanitec / Kratix)
│  - Templates → real resources             │
│  - One API for "create a service"          │
├────────────────────────────────────────────┤
│  Underlying tools                          │
│  - Kubernetes, CI/CD, secrets, monitoring  │
└────────────────────────────────────────────┘

Some teams skip the orchestrator and call cloud / cluster APIs directly. Some skip the portal and ship CLI tools. The full stack is more powerful but you don't need it on day one.

The Players

Developer portals

Platform orchestrators

Scaffolders / golden paths

Many portals include scaffolding. Standalone:

• Cookiecutter — Python-based templating
• Yeoman — Node-based
• Backstage Templates — most popular today

For a fresh stack: Backstage + Crossplane is the OSS reference architecture. Port + your existing cluster is the fast-start commercial alternative.

What a Golden Path Provides

A "golden path" or "paved road" is a template that handles the 80% case end-to-end. Example for a new Go HTTP service:

1. Scaffold a repo with directory structure, Dockerfile, README
2. Add CI workflow with linting, tests, image build, push
3. Generate Kubernetes manifests (Deployment, Service, Ingress, NetworkPolicy)
4. Wire OpenTelemetry instrumentation
5. Create dashboards in Grafana (auto-template per service)
6. Configure secrets template in Vault
7. Add to service catalog
8. Open a PR to the GitOps repo to start deploying

The engineer fills in a form (service name, language, team), clicks "create," and the platform produces all of that in a few minutes. Day one of a new service, ready.

Service Catalog

The catalog is the map of your software. For each service:

apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: checkout-service
  description: Handles checkout flow
  tags: [golang, payments, public-facing]
  annotations:
    github.com/project-slug: my-org/checkout-service
    pagerduty.com/integration-key: ...
    grafana/dashboard-selector: 'service=checkout'
    backstage.io/techdocs-ref: dir:.
spec:
  type: service
  lifecycle: production
  owner: team-payments
  system: payments-platform
  dependsOn:
    - resource:postgres-checkout-db
    - component:user-service
  consumesApis:
    - user-service-api

From this, the portal shows:

• Owner + on-call rotation
• Repos and pipelines
• Live dashboards
• Open incidents
• Dependencies (visual graph)
• API contracts
• Documentation (TechDocs)
• SLO status

A new engineer landing on the page understands the service in 5 minutes instead of 5 weeks.

Scorecards and Maturity

Most IDPs include scorecards that grade each service against standards:

Teams see their gaps. Leadership sees fleet-wide trends. Compliance auditors get evidence. Cortex makes this its core product; Backstage has plugins for it.

Don't make scorecards punitive at first. Make them visible. Teams self-correct when their service stands out.

Learning Path

When Not to Build an IDP

Honest cases:

• Under ~10 engineers. A wiki + a CLI tool serves you. Building Backstage is overhead until you have multiple teams to align.
• Single product team. IDP is most valuable when teams need to find each other's stuff. If everyone knows everything, no IDP needed.
• You think it's a tool not a product. Installing Backstage doesn't make an IDP. The IDP is the templates, paths, and policies — they need a product owner.
• Without platform team buy-in. An IDP without a team that maintains it goes stale in 6 months; engineers route around it.

The IDP industry has burned through a generation of failed Backstage installs because of this last one. The tool is 20% of the work; the product is 80%.

Backstage in 60 Seconds

The architecture:

• Catalog — services, APIs, websites, resources, users, groups
• Scaffolder — runs templates to bootstrap things
• TechDocs — docs in markdown next to code, rendered in portal
• Plugins — everything else (CI status, Datadog, PagerDuty, GitHub, …)

Catalog entries live in catalog-info.yaml files in each service repo; Backstage discovers and ingests them. Templates live in template repos; the portal calls them.

The plugin ecosystem is enormous (50+) — and uneven. Curate carefully.