| Myth | Reality |
|---|---|
| An IDP is just a Kubernetes cluster with a wiki page | An IDP is a self-service product with a catalog, templates, and measured adoption, not raw infrastructure |
| You need Backstage on day one to start | Most teams should validate a single golden path with scripts or a simple CLI before adopting a full portal framework |
| Building an IDP is primarily an infrastructure project | It is primarily a product and adoption project; the infrastructure is the easy part |
| Once built, the platform is done | A platform is never done; it needs a roadmap, feedback loops, and ongoing golden-path maintenance |
| Mandating usage guarantees adoption | Mandates without a genuinely faster workflow produce shadow infrastructure and resentment |
Most teams that attempt to build an internal developer platform start in the wrong place: they buy a portal tool, install it, and wonder why nobody uses it six months later. A working internal developer platform, the kind engineers actually choose over the alternative, is built in a specific order, starting with a single painful workflow and expanding only once that workflow proves itself. This blueprint walks through the twelve steps that hold up in practice, drawing on patterns documented by the Cloud Native Computing Foundation’s platforms working group and Spotify’s own account of building Backstage.
Step 1: Diagnose the Actual Friction Before Building Anything
Before writing a line of Terraform, interview a representative sample of engineering teams about their slowest, most repeated workflow. Common answers include provisioning a new service, requesting a database, getting a preview environment, or onboarding a new hire’s local setup. Skipping this step is the single most common cause of platforms nobody uses, because teams end up building what platform engineers assume is painful rather than what developers actually report as painful.
Step 2: Pick One Thin Golden Path, Not a Full Platform
Resist the urge to build a comprehensive system in the first iteration. Choose the single highest-friction workflow identified in step one and commit to solving only that one well. A narrow, genuinely useful golden path for “spin up a new service” beats a broad, half-finished platform that touches ten workflows shallowly.
Step 3: Define Ownership and Staff the Platform as a Product Team
Assign a small team, often three to five engineers, and give it a product mandate rather than a ticket queue. Per the Team Topologies model, this is a platform team whose customers are the stream-aligned teams building product features. Without a named owner and a roadmap, the platform reverts to shared infrastructure maintained by whoever has spare time.
Platform Team as a Product
A platform team collects requests from internal developers, prioritizes a roadmap, ships a golden path, and measures adoption, the same loop an external product team runs with paying customers.
Step 4: Standardize Infrastructure as Code Before Automating It
Audit existing Terraform, Pulumi, or CloudFormation modules across teams and consolidate them into a small number of vetted, reusable modules. Automation built on top of inconsistent infrastructure code just automates the inconsistency faster. This step is unglamorous but it determines whether later steps are stable.
Step 5: Build the Service Scaffolding Template
Create a template that generates a new service with CI/CD wiring, a starter test suite, observability hooks, and security defaults already configured. This is usually the single highest-leverage artifact in the entire platform, since it directly addresses the most common friction point identified in step one for most organizations.
What a Good Template Includes
A strong scaffolding template pre-wires logging and tracing, sets sane default resource limits, includes a working CI pipeline out of the box, and registers the new service automatically in whatever catalog the organization uses, so ownership and metadata are never entered manually.
Step 6: Choose a Catalog and Portal Layer
Decide whether to adopt an existing framework like Backstage, the CNCF incubating project originally built by Spotify, or a lighter internal tool such as a well-documented CLI backed by a metadata file in each repository. Backstage suits organizations with dozens of services and dedicated platform capacity; smaller teams often get more value from a simple, fast internal tool than from operating a full portal framework.
| Organization size | Recommended catalog approach | Why |
|---|---|---|
| Under 30 engineers | Lightweight CLI plus a metadata file per repo | Full portal framework overhead exceeds the benefit at this scale |
| 30 to 150 engineers | Backstage or equivalent with a small plugin set | Enough services exist that discovery and templating pay for themselves |
| 150+ engineers | Backstage with custom plugins and dedicated platform product management | Cognitive load and duplicated tooling become the dominant cost center |
Step 7: Wire Self-Service Environment Provisioning
Let developers request an ephemeral preview environment or a new database instance through the portal or CLI, backed by the infrastructure-as-code modules from step four. This is where the platform starts saving measurable hours per week, since environment requests are typically one of the slowest manual bottlenecks reported in step one.
Step 8: Bake in Security and Compliance Defaults
Rather than layering security review on top of the golden path as a separate gate, embed secrets management, dependency scanning, and access control defaults directly into the scaffolding template so compliant behavior is the path of least resistance. This mirrors the “shift left” principle from DevOps culture, applied through tooling instead of policy documents.
Golden Path with Security Built In
A new service scaffolded through the platform arrives with secrets management, dependency scanning, and access policies already configured, so teams do not need a separate security review to get started.
Step 9: Instrument Adoption, Not Just Uptime
Track how many teams choose the golden path voluntarily, how long it takes a new hire to ship their first change, and how often developers bypass the platform for manual workarounds. Google’s DORA research and the SPACE framework both emphasize outcome and experience metrics over raw infrastructure uptime, and a platform team that only watches server health will miss the signals that predict abandonment.
Common Mistakes When Building an Internal Developer Platform
Pitfalls to avoid
Building for imagined workflows instead of measured ones. Skipping the interview step in the process and guessing at pain points produces a platform that solves problems nobody actually has.
Trying to platform everything in the first release. A platform covering ten workflows shallowly gets abandoned faster than one covering a single workflow well.
No opt-out for edge cases. Forcing every workload, including legitimately unusual ones, through the same golden path creates shadow infrastructure and undermines trust in the platform.
Ignoring documentation and onboarding. A powerful platform with no clear “getting started” guide gets used by early adopters only and never spreads past the first few teams.
Measuring server uptime instead of developer time saved. Infrastructure health metrics say nothing about whether the platform actually reduced cognitive load for the people using it.
Step 10: Expand the Golden Path Catalog Gradually
Pattern that holds up
Once the first golden path has measurable voluntary adoption, usually defined as most eligible teams choosing it without being told to, expand to the second highest-friction workflow identified back in step one. Organizations that succeed with this staged rollout typically add one or two new golden paths per quarter rather than attempting to platform every workflow simultaneously. This mirrors how Spotify’s Backstage grew: it began as an internal tool solving one service-sprawl problem before being generalized across many more workflows and eventually open-sourced.
Step 11: Establish a Feedback Loop and a Real Roadmap
Run regular office hours, collect internal developer satisfaction scores, and maintain a visible backlog that internal developers can see and comment on. Treat the platform’s roadmap with the same discipline a product team would apply to an external customer-facing roadmap, prioritizing based on adoption data and reported friction rather than internal platform team preferences.
Step 12: Plan for Platform Team Longevity, Not Just Launch
A platform that launches successfully but loses its dedicated team within a year tends to decay as golden paths drift out of sync with evolving cloud provider APIs and security requirements. Budget for ongoing maintenance headcount from the outset, and treat platform engineering as a permanent product line rather than a project with a defined end date.
Once the twelve-step foundation is in place, the comparison of how platform engineering differs from traditional DevOps ownership models, covered in our platform engineering vs DevOps comparison, helps clarify how to staff and message the new team internally. The scaffolding decisions in step five also interact heavily with how services communicate; organizations leaning on event-driven architecture should bake messaging conventions directly into the template, while those consolidating services toward a modular monolith may need fewer scaffolding variants overall. Consistent API design standards and a shared TypeScript at scale convention make templates easier to maintain across dozens of services, and teams running workloads across providers should read our multi-cloud architecture guide before hardcoding provider-specific assumptions into golden paths.
Glossary
- Golden path
- An opinionated, pre-built, supported workflow for a common engineering task, designed to be the easiest option rather than a mandatory one.
- Service catalog
- A searchable registry of services, their owners, documentation, and dependencies, typically the central feature of a developer portal like Backstage.
- Scaffolding template
- A pre-built starter project that generates a new service with CI/CD, observability, and security defaults already wired in.
- Platform as a product
- An operating model where an internal platform is managed with a roadmap, user research, and adoption metrics, rather than as background infrastructure.
- Cognitive load
- The mental effort a developer must expend to understand and operate the systems they are responsible for, a core concept from Team Topologies.
- Ephemeral environment
- A temporary, on-demand environment, often used for previewing a change, that is automatically created and torn down through self-service tooling.
Key Takeaways
- Start by diagnosing the actual highest-friction workflow through interviews, not by guessing which infrastructure gap to fill first.
- Build one thin golden path completely before expanding scope; broad, shallow platforms get abandoned faster than narrow, deep ones.
- Staff the platform as a product team with a named owner and roadmap, following the Team Topologies platform-team pattern.
- Service scaffolding templates are typically the single highest-leverage artifact, since new-service creation is the most common friction point.
- Choose a catalog and portal layer that matches your scale; Backstage pays off past roughly thirty engineers, not before.
- Track adoption metrics like voluntary golden path usage and time to first deploy, not just infrastructure uptime.
- Budget for permanent platform team headcount; a platform that loses its team after launch tends to decay within a year.
FAQs
How long does it take to build an internal developer platform?
A single validated golden path, such as service scaffolding, can typically be built and adopted within one to two quarters by a small dedicated team. A broader platform covering multiple workflows, environment provisioning, and a full portal usually takes twelve to twenty-four months of iterative expansion rather than a single project timeline.
Do we need Backstage to build an internal developer platform?
No. Backstage is a popular open-source option for organizations with dozens of services, but smaller teams often get more value from a lightweight CLI or a well-documented set of scripts. The platform is defined by the self-service golden path and product discipline behind it, not by any specific portal framework.
How many engineers should staff a platform team?
Most successful platform teams start with three to five engineers focused on one golden path at a time. Headcount typically grows as adoption expands across more workflows and more of the organization, but starting small and proving value first avoids overbuilding before anyone has validated demand.
What is the first thing we should build?
Interview engineering teams to find the single most repeated, most painful manual workflow, commonly service scaffolding, environment provisioning, or onboarding setup. Build a golden path for that one workflow first, since starting narrow and proving adoption beats attempting a comprehensive platform in the first release.
How do we measure whether the platform is actually working?
Track voluntary golden path adoption rate, time to first successful deploy for new hires, and self-service ticket deflection, alongside standard DORA metrics like deployment frequency and change failure rate. Infrastructure uptime alone does not indicate whether developers are actually choosing to use the platform.
Should the golden path be mandatory?
Generally no. Mandating a golden path before it is genuinely faster than the alternative creates resentment and shadow infrastructure. The healthiest platforms earn adoption by being the easiest option available, reserving mandates for narrow cases like security or compliance requirements that cannot be optional.
What happens if the platform team is disbanded after launch?
Golden paths tend to drift out of sync with evolving cloud provider APIs, security requirements, and dependency versions without ongoing maintenance. Organizations that treat platform engineering as a one-time project rather than a permanent product line typically see adoption and trust decline within twelve months of losing dedicated staffing.
Can a small startup benefit from an internal developer platform?
Usually not as a dedicated team below roughly thirty engineers; the coordination overhead of building and maintaining a platform tends to exceed the benefit at that scale. Small teams get more value from consistent conventions and shared scripts than from a dedicated platform engineering function.
References
- Cloud Native Computing Foundation, “Platforms Working Group,” cncf.io
- Spotify Engineering, “Backstage: An Open Platform for Building Developer Portals,” backstage.io
- Google Cloud, “DORA: DevOps Research and Assessment,” dora.dev
- Skelton, M. and Pais, M., “Team Topologies,” teamtopologies.com
- Forsgren, N. et al., “The SPACE of Developer Productivity,” ACM Queue
- HashiCorp, “Infrastructure as Code Best Practices,” hashicorp.com
