Internal Developer Platform design · Prasanta Kumar Behera

Turn a Kubernetes cluster into a product developers love to use: golden paths, self-service through platform APIs and portals, guard-rails instead of gates, and metrics that prove it works.

From cluster to platform

A Kubernetes cluster is a powerful engine with a thousand knobs. Most application developers don't want the knobs. They want to ship their service safely, quickly, and without learning 40 YAML fields. An Internal Developer Platform (IDP) is the product that sits between the two.

Kubernetes is a professional kitchen: every tool, every ingredient, and very easy to burn yourself. A platform team turns it into a restaurant kitchen with recipe cards. Cooks pick "Pizza" and get the right oven, temperature and timer (the golden path). They can still cook something unusual, but the safe, fast way is the one on the card.

Principles

Platform as a product: developers are your customers. Interview them, watch where they struggle, publish a roadmap, measure adoption.
Reduce cognitive load: hide what teams don't need to decide; expose what they must decide.
Self-service over tickets: anything a team does more than a few times a month should not need a human on the platform team.
Guard-rails over gates: encode rules as automatic policy (admission control, CI checks), not approval meetings.
Paved roads, not walls: golden paths are the easy default; teams may leave them, and then own the extra work.

A golden path, end to end

"New service" might mean one click or one command that produces:

Step	What the platform provides
Repository	From a template: app skeleton, Dockerfile, tests, CODEOWNERS
CI	Build, test, scan, sign the image (see CI/CD & Supply Chain)
Deployment	A standard Helm chart or Kustomize base, with probes and resources set
Environments	Namespaces with the tenant kit (lesson 29) in dev, staging, prod
Delivery	GitOps Applications created automatically (see GitOps with Argo CD)
Operations	Dashboards, alerts and log queries already wired up with the service name
Catalog	An entry in the developer portal with owner, docs and links

Platform APIs: the interface that hides the plumbing

Developers should describe what they need, not how it's built. The interface can be a Terraform module, a Helm values file, a template, or a Kubernetes custom resource reconciled by a controller or by Crossplane. For example, an illustrative platform API (not a standard resource):

# Illustrative only: a platform team's own API, handled by their controller.
apiVersion: platform.example.com/v1
kind: Service
metadata:
  name: orders-api
  namespace: team-orders
spec:
  image: registry.example.com/orders-api:1.4.2
  exposure: internal          # platform picks Service/Ingress/Gateway, TLS, DNS
  size: small                 # platform maps to requests/limits and HPA
  database: postgres-small    # platform provisions it, and injects the credentials

Behind this one object, the platform creates a Deployment, HPA, PDB, Service, route, certificate, database and dashboards: all the correct, secure defaults in one place, upgraded centrally.

The developer portal

A portal such as Backstage gives one place to find every service, its owner, docs, dashboards and self-service actions. Services describe themselves with a small file in their repository:

apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: orders-api
  description: Order management API
spec:
  type: service
  lifecycle: production
  owner: team-orders

A portal is a window onto the platform, not the platform itself. It succeeds only if the paths behind it are solid.

Try it: design a golden path on paper

Pick one real kind of service in your organisation (for example "a stateless HTTP API").

List every step from "new idea" to "running in production with alerts". Mark who does each step today, and how long it takes.
Circle the steps that need a ticket or a meeting. Which could become self-service or an automatic guard-rail?
Write the smallest platform API (5–8 fields) a developer would need to fill in.
Define two metrics you'd use to prove the path helped, for example time to first deploy and change failure rate.

Going deeper: platform team realities

Start with the thinnest viable platform: docs + templates + a few automations. Build a portal only when there's something worth putting in it.
Version your platform APIs like any API. Deprecate with notice; never break golden-path users silently.
Track DORA metrics (deployment frequency, lead time, change failure rate, time to restore) and developer satisfaction together. Speed without safety, or safety without speed, both fail.
Beware building a second cloud provider. Use managed services and existing open-source projects wherever they fit, and spend your effort on the glue that's specific to your organisation.

Recap

An IDP is a product: golden paths, self-service, guard-rails, and a feedback loop with developers.
Platform APIs let teams declare what they need; the platform owns how.
Portals (Backstage) are useful windows, and only as good as the paths behind them.
Measure with DORA metrics and developer satisfaction.

This site is a public version of my personal engineering knowledge hub. It intentionally excludes confidential company information and internal operational details.