Internal Developer Platforms
An internal developer platform (IDP) is a self-service layer that sits between developers and infrastructure. Its purpose is to abstract away the complexity of Kubernetes, cloud providers, CI/CD pipelines, and monitoring so that product engineers can focus on shipping features instead of wrestling with YAML files.
What a Platform Actually Is
A platform is not a product you buy. It is a curated set of tools, workflows, and self-service capabilities that your organization assembles to reduce the cognitive load on product engineers. The platform team builds and maintains it. Product engineers consume it.
Without a platform:
Developer wants to deploy a new service
→ Writes Dockerfile
→ Configures Kubernetes manifests
→ Sets up CI/CD pipeline
→ Configures monitoring
→ Sets up alerting
→ Requests DNS entry
→ Waits for security review
→ Total time: 2 weeks
With a platform:
Developer wants to deploy a new service
→ Runs "create-service" from the platform CLI
→ Everything is configured automatically
→ Total time: 30 minutes
The platform does not replace infrastructure. It provides a paved road on top of it.
The Build vs Buy Decision
There are three approaches to building an IDP:
Build from Scratch
You assemble your own platform from open-source tools, custom scripts, and internal tooling. This gives you full control but requires significant engineering investment.
Pros:
- Perfectly fits your organization
- No vendor lock-in
- Full control over features and roadmap
Cons:
- Expensive to build and maintain
- Requires a dedicated platform team
- Takes 6-18 months to reach usability
Adopt an Open-Source Framework
Backstage (by Spotify) is the most popular open-source platform framework. It provides a plugin-based architecture for building a developer portal with a service catalog, documentation, and CI/CD visibility.
# Example Backstage catalog-info.yaml
apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
name: payment-service
description: Handles payment processing
annotations:
github.com/project-slug: myorg/payment-service
pagerduty.com/service-id: PXXXXXX
spec:
type: service
lifecycle: production
owner: team-payments
system: checkout
dependsOn:
- component:user-service
- resource:payments-db
Buy a Commercial Platform
Port, Humanitec, and Cortex are commercial platforms that provide self-service infrastructure out of the box. They reduce build time but come with licensing costs and less flexibility.
Build: Full control, high cost, slow start
Backstage: Good middle ground, plugin ecosystem, still needs engineering
Buy: Fast start, less control, recurring cost
The right choice depends on your organization's size, engineering capacity, and how unique your infrastructure is.
The Platform Team's Job
The platform team exists to reduce cognitive load for product engineers. Their customers are internal developers. Their product is the platform.
What the Platform Team Does
1. Builds self-service tooling for common tasks
2. Maintains golden paths (the recommended way to do things)
3. Manages shared infrastructure (Kubernetes, CI/CD, monitoring)
4. Provides documentation and support
5. Measures developer experience and iterates
What the Platform Team Does Not Do
1. Deploy your service for you (self-service means you do it)
2. Write your application code
3. Make architectural decisions for product teams
4. Become a bottleneck for every infrastructure request
The platform team succeeds when developers do not need to talk to them. If every deployment requires a platform team member, the platform has failed.
Golden Paths
A golden path is an opinionated default that works. It is the recommended way to accomplish a common task: create a service, deploy to production, set up monitoring, configure alerting.
Golden path for creating a new microservice:
1. Run the service template CLI
2. Get a repo with Dockerfile, CI/CD pipeline, monitoring, and alerts
3. Push code
4. Service deploys automatically to staging
5. Promote to production with one command
Golden paths are not enforced. Teams can deviate if they have good reasons. But the golden path is the easiest option, which means most teams will follow it by default. This is the key insight: make the right thing the easy thing.
# Example golden path service template
service:
name: "{{ service_name }}"
language: "{{ language }}"
framework: "{{ framework }}"
infrastructure:
compute: kubernetes
database: postgresql
cache: redis
observability:
metrics: prometheus
logging: structured-json
tracing: opentelemetry
ci_cd:
pipeline: github-actions
deploy_strategy: rolling
environments:
- staging
- production
When You Need a Platform Team
Not every organization needs a dedicated platform team. The decision depends on scale.
10 engineers: You do not need a platform team.
A few shell scripts and a wiki page are enough.
30 engineers: One or two people start spending most of their
time on shared tooling. This is the seed of a
platform team.
50+ engineers: A dedicated platform team becomes essential.
Without one, every team reinvents the wheel.
Deployments are inconsistent. Onboarding is slow.
100+ engineers: The platform team is 5-10 people. They run the
IDP as a product with roadmaps, SLOs, and user
research.
The mistake companies make is building a platform too early (wasting engineering effort on infrastructure nobody needs yet) or too late (every team has built their own deployment pipeline and now you have fifteen different ways to deploy).
Real-World Example
A fintech company with 80 engineers had 12 microservices, each deployed differently. One used Jenkins, three used GitHub Actions, two used CircleCI. Kubernetes manifests were copied between repos with subtle differences. Onboarding a new engineer took two weeks because they had to learn whichever deployment system their team happened to use.
They formed a three-person platform team. In six months they built:
- A service template that generated a new repo with CI/CD, Docker, monitoring, and standard Kubernetes manifests
- A deployment CLI that abstracted away Kubernetes complexity
- A service catalog in Backstage that showed every service, its owner, its dependencies, and its health
After the platform launched, onboarding dropped from two weeks to two days. New services went from idea to production in hours instead of weeks. The platform team measured success by tracking time-to-first-deploy for new engineers.
Common Pitfalls
- Building too early -- At 10 engineers, a platform is premature optimization; you do not have enough users or enough complexity to justify it
- Building without talking to users -- The platform team builds what they think developers need instead of what developers actually need; run surveys, do interviews, watch people work
- Making the platform mandatory -- Forcing teams onto the platform before it is ready creates resentment; make it the easy choice, not the only choice
- Understaffing the platform team -- One person cannot build and maintain a platform for 100 engineers; this leads to burnout and a half-built platform that nobody trusts
- Forgetting documentation -- A platform without documentation is a black box; developers will not use what they do not understand
- Platform as gatekeeper -- If the platform team must approve every change, they have become a bottleneck, not an enabler
Key Takeaways
- An internal developer platform is a self-service layer that reduces cognitive load for product engineers
- The platform team's job is to make the right thing the easy thing through golden paths and self-service tooling
- Build vs buy depends on scale, engineering capacity, and how unique your infrastructure is
- Backstage is the most popular open-source framework; Port and Humanitec are commercial alternatives
- Golden paths are opinionated defaults that work -- not enforced, but the easiest option
- You do not need a platform team at 10 engineers; you likely do at 50+
- Measure success by developer productivity: time to onboard, time to first deploy, developer satisfaction