Subscribe
Reference Architecture

Kubernetes Internal Developer Platform

A reference architecture for an internal developer platform on Kubernetes, with golden paths, GitOps delivery and unified observability built in.

  • Containers
  • Platform Engineering
  • Observability
  • Cloud
  • Cross-industry

The challenge

Giving product teams a paved road to production on Kubernetes without every team owning a bespoke pipeline, cluster configuration and alerting setup.

Layered diagram of a Kubernetes internal developer platform, from the developer portal and golden paths through GitOps delivery to cluster runtime and observability
Kubernetes Internal Developer Platform — reference architecture

An internal developer platform is worth building when the same YAML, the same pipeline and the same alerting rules are being reinvented by every team — and each copy drifts, so an upgrade means touching dozens of near-identical repositories.

How it works

The platform exposes golden paths rather than a wiki page. Scaffolding a service from a template produces the repository, pipeline, chart, dashboards and alerts together, and those templates stay owned by the platform team, so an upgrade lands by regenerating rather than by asking teams to hand-edit.

Delivery is GitOps. The cluster is reconciled to what is in Git, which makes the deployed state auditable, drift visible, and rollback an ordinary revert rather than a rehearsed emergency procedure.

Infrastructure is requested through platform APIs. A team declares that it needs a database; the platform provisions it with the organisation’s encryption, backup and tagging defaults already applied. That is the difference between a paved road and a pile of Terraform modules.

What to get right

  • Golden paths, not gates. A path teams choose because it is faster works; one enforced by a review board gets routed around.
  • Ship observability with the template. Retrofitting dashboards and alerts onto an existing fleet never finishes.
  • Treat the platform as a product. It needs a roadmap, versioning, release notes and users you talk to — an internal platform with no product owner becomes a ticket queue.
  • Budget for upgrades. Kubernetes and its add-ons move constantly; an upgrade path that is not automated becomes an annual crisis.

How it fits together

  1. Developer portal

    The front door: service catalogue, ownership, scorecards and templates. A new service is scaffolded from a template rather than copied from a neighbour.

  2. Golden paths

    Opinionated templates covering repository layout, CI, Dockerfile, Helm chart, alerts and dashboards — the supported route, not the only permitted one.

  3. GitOps delivery

    Git is the desired state and a controller reconciles the cluster to it. Deploys are pull requests, rollbacks are reverts, and drift is detected rather than discovered.

  4. Platform APIs

    Databases, queues, buckets and DNS requested declaratively and provisioned by the platform, so a team does not need cloud console access to ship.

  5. Cluster runtime

    Multi-tenant namespaces with quotas, network policy, a service mesh for mTLS and traffic shifting, and autoscaling at both pod and node level.

  6. Policy and supply chain

    Admission policy for what may run, image signing and SBOM generation in CI, and scanning that gates promotion rather than merely reporting.

  7. Unified observability

    Metrics, logs and traces collected through one agent and correlated, with dashboards and alerts shipped by the template so a new service is observable on day one.

Layered diagram of a Kubernetes internal developer platform, from the developer portal and golden paths through GitOps delivery to cluster runtime and observability — detailed architecture
Kubernetes Internal Developer Platform — detailed architecture

Typically built with

  • Kubernetes
  • Argo CD
  • Backstage
  • Terraform
  • Prometheus
  • OpenTelemetry

Go deeper

More reference architectures

Layered diagram of an enterprise graph architecture for agentic search, from ingestion and entry points through retrieval, the enterprise graph context layer, and agentic reasoning to the model and tool ecosystem, beside rails for governance and for trust, security and observabilityEnterprise Context Graph Reference Architecture for Agentic Enterprise SearchLayered diagram of a real-time agentic AI architecture, from triggers and gateways through an event mesh and orchestrator to agents and the tools, data and LLM services they call, beside rails for deployment footprint and for trust, governance and observabilityReal-Time Agentic AI Reference Architecture using an Event MeshLayered diagram of the Salesforce Data 360 agentic enterprise reference architecture, from sources and ingestion through the harmonized C360 data model to segmentation, query and agentic activation, beside a foundational elements rail for governance, security, sandboxes and Data Cloud OneSalesforce Data 360 Agentic Enterprise Reference Architecture