Building an Internal Developer Platform (IDP): A 90-Day Playbook
Platform engineering is the discipline replacing classic DevOps in growing engineering organizations. The IDP, an internal developer platform, is the artifact. Here's the playbook for building one that actually accelerates your team, in 90 days.
Key takeaways
- An IDP is a self-service platform: developers click to deploy, observe, scale, and operate, without needing to know infrastructure.
- Build the "golden path" first, the one supported way to create, deploy, and run a typical service.
- Don't try to support every framework. Support 2-3, do them well.
- Observability and developer experience are first-class concerns.
Why this matters
The 30+ engineer engineering org with no IDP slows down. Each new service is a snowflake. Each deploy is a ticket. Each on-call is anxiety-driven. The right IDP cuts time-to-production for a new service from days to hours and reduces operational toil.
Days 1-30: The golden path
Pick the most common service shape in your stack, typically "stateless HTTP service in Go or Node, deploying to Kubernetes."
Build the one supported way to do everything for that shape:
- Project generation (Backstage software template or in-house)
- Code repository + CI/CD baseline
- Deployment via GitOps (ArgoCD or Flux)
- Observability stack pre-wired (logs, metrics, traces)
- Secrets management
- IAM defaults
Document the golden path. Make it obviously the easiest way to do anything.
Days 31-60: Self-service
Build the self-service surface. A portal (Backstage is the popular open-source choice) where developers can:
- Create a new service from a template (5 minutes)
- View their services' health, deploys, alerts
- Provision databases, queues, caches via Terraform-backed self-service
- Manage secrets and configuration
Self-service is the IDP's selling point. Without it, you've built a platform team's tools, not a developer's platform.
Days 61-90: Adoption
The IDP is only valuable if engineers use it. Days 61-90:
- Migrate 2-3 pilot services onto the IDP
- Iterate based on developer feedback
- Document migration playbooks
- Internal communication: blog posts, demos, success stories
- Train the engineering org
What works
Bias toward "boring"
Boring technology that engineers already know beats novel technology that requires learning. Postgres, Redis, Kubernetes, GitHub Actions.
Cost transparency
Every service has a cost dashboard. Developers see the cost of their decisions.
Documentation as code
Documentation lives with the code. The platform's docs are part of the platform.
Strong opinions, weak constraints
Strong defaults that 90% of cases follow. Escape hatches for the 10%.
Common pitfalls
Boil-the-ocean. Trying to support every framework at once. Pick 2-3.
Platform team that doesn't ship. A platform team that only advises rather than builds becomes a bottleneck.
No metric of success. Time-to-first-deploy, deployment frequency, change-failure rate, measure them.
Built without developer input. Run regular developer experience surveys.
What we recommend
90 days to V1 IDP supporting one service shape end-to-end. Iterate from there. Don't try to be Backstage from day one.
FAQs
Build or use Backstage? Backstage is the open-source default; consider it. But the "platform" is more than the portal, Backstage is the portal layer.
Team size for IDP? Typically 3-5 platform engineers for the first IDP.
What's the ROI? Hard-measured: deploys go up 2-3x; on-call incidents reduce; new-engineer productivity ramps faster.