Building an internal developer platform: six decisions that determine whether it works
An internal developer platform succeeds or fails on six decisions. Not on the technology — Kubernetes, ArgoCD and Terraform are the baseline, and every platform uses them. The decisions are architectural, and they are invisible until the platform is in production and developers are either adopting it or working around it.
1. Multi-tenancy: soft or hard?
The first decision is how much isolation belongs between teams. There are two answers, and picking the wrong one for your organisation is the most expensive mistake a platform team can make.
Soft multi-tenancy — namespaces with RBAC, NetworkPolicy and resource quotas. One cluster, many teams, trust enforced by configuration. Cheaper to run, simpler to operate, sufficient for most organisations.
Hard multi-tenancy — separate clusters per team or per environment. Full blast radius isolation. Needed when regulatory compliance requires it or when workloads are adversarial (one team's code must not share a kernel with another).
The decision is not technical. It is about the blast radius your organisation can tolerate. A SaaS product with 20 engineers and a single customer base can run on soft multi-tenancy. A platform hosting code from 50 teams across three business units that cannot share failure domains needs hard multi-tenancy.
The mistake is starting with one and switching later. Migrating from soft to hard multi-tenancy means moving workloads between clusters — which is a migration project, with all the sequencing problems of one. Decide before the first workload lands.
2. GitOps: push or pull?
The second decision is how configuration reaches the cluster. There are two models, and the industry has largely converged on one.
Push — a CI pipeline runs kubectl apply or helm upgrade. Simple, familiar, and wrong at scale. The pipeline needs cluster credentials. The pipeline is the only thing that knows what was applied. If a drift happens — someone runs kubectl edit on a production deployment — the pipeline does not know and does not fix it.
Pull — an agent inside the cluster (ArgoCD, Flux) watches a Git repository and reconciles the cluster state to match. No external credentials. Drift is detected and corrected automatically. The Git repository is the source of truth, and what is in Git is what is running.
Use pull. The push model works for a team of five and breaks at fifty. The pull model works for both, and the infra cost difference is one controller pod.
3. How do developers ask for something?
This is the decision that determines adoption. A platform that requires a developer to open a ticket and wait for a platform engineer to provision a namespace is a platform that developers route around.
The self-service API is the interface between the platform and its users. It can be:
- A Git repository with a template — developer copies a directory, fills in a few values, opens a PR. The PR merge triggers provisioning. Low ceremony, easy to start, and fits the pull model.
- A CLI or web form — developer fills in a form, clicks submit, gets a namespace. Higher ceremony to build, lower ceremony to use.
- Backstage or equivalent portal — a UI that wraps the provisioning workflow. High upfront investment, easiest for developers who do not write YAML.
Start with the template. It costs a README and a directory of example files. If adoption is high enough to justify a portal, build the portal. If adoption is low, the interface was not the problem.
4. What does a golden path include?
A golden path is the supported, documented, tested way to ship a service. Developers who follow it get observability, security scanning, CI/CD and deployment to production with one merge. Developers who go off-path are on their own.
The minimum golden path includes:
| Capability | What it delivers |
|---|---|
| Scaffolding | A repo template with the right directory structure, Dockerfile and pipeline config |
| CI/CD | Build, test, scan, deploy — all triggered by a PR merge |
| Observability | Metrics scraped, logs shipped, dashboards pre-populated for RED metrics |
| Secrets | Injected at runtime from a secrets manager, never in the repo |
| Networking | Service exposed behind the ingress, TLS provisioned automatically |
| Deployment | One command or one merge from PR to production |
The golden path is not optional infrastructure. It is the infrastructure that exists so developers do not have to build it themselves. Every capability listed above that the platform does not provide is one your developers will build independently, differently, and with varying quality.
5. Who owns what?
A platform without clear ownership boundaries creates two problems: platform engineers are paged for every application outage, and application developers cannot debug their own services because they do not have access.
Define the line:
- Platform team owns: cluster, networking, ingress, cert-manager, secrets operator, monitoring stack, logging pipeline, golden path templates
- Application team owns: their namespace, their deployments, their alerting rules, their SLOs, their on-call rotation
The platform team's SLA is that the platform is available. The application team's SLA is that their service is available. A platform that accepts pages for application outages has erased the line, and the platform team becomes the operations team for the whole company.
6. How do you know it is working?
The platform's success metrics are not uptime and latency. Those are the application's metrics. The platform's metrics are:
- Time to first deploy: how long from "I want to ship a new service" to "it is in production, monitored and receiving traffic." If this is more than a day, the golden path is missing steps.
- Adoption rate: what fraction of services run on the platform versus outside it. If the number is low, find out why — and fix the platform, not the teams.
- Platform toil: how many hours per week the platform team spends on operational work that could be automated. A platform team that spends more than 20% of its time on toil is a team that is not improving the platform, and a platform that is not improving is a platform that is losing its users.
A platform is a product
The platform that ships and is never improved is a platform that is abandoned within a year. Treat it as a product with users — your developers — and an ongoing roadmap. The metrics tell you what to build next.
Building or scaling an internal platform? I take on Kubernetes and GitOps platform builds and fractional DevOps retainers for teams that need senior platform expertise without a full-time hire — independently, for the US, EU and APAC.