What an Internal Developer Platform is
An Internal Developer Platform (IDP) is an integrated collection of capabilities that a platform team provides and maintains for the development teams of its own company. That is how the CNCF Platforms Whitepaper describes it: the platform bundles infrastructure, pipelines, environments and operational tasks so that teams can use them without one-off agreements. Three building blocks show up in almost every implementation.
- Golden paths: prepared, documented routes for recurring tasks. A new service repository is created from a template, comes with pipeline, deployment and base configuration. Technical requirements can be built in and checked automatically; additional application requirements still need to be assessed.
- Self-service: teams request environments, databases or permissions through defined interfaces instead of writing a ticket and waiting.
- Portal: a surface that makes services, ownership, documentation and templates visible in one place.
The CNCF whitepaper justifies the approach with reduced cognitive load: development teams should deal with their product, not with the twentieth variant of pipeline, network approval and deployment. For that to hold, the platform itself is run like a product, with an owning team, a roadmap and the development teams as customers you have to retain.
The order of this list matters. The portal is the most visible building block, but the last one. An IDP becomes load-bearing through the golden paths and the self-service underneath, and those in turn require a solid foundation: a landing zone and infrastructure that exists as code.
How to tell that an IDP pays off
An IDP is an investment in an internal product, with its own team and ongoing maintenance. The CNCF maturity model for platform engineering is clear on this: every further stage of expansion costs additional money and additional time, and the highest stage is not a goal in itself. So the question is not whether an IDP is good in principle, but whether your situation justifies the effort. Three signals are reliable.
The number of teams. As long as a handful of teams talk to each other directly, conventions can be kept in agreements and shared modules. The more teams deliver in parallel, the more often the same foundation is built multiple times and the more expensive every deviation becomes. Shared routes can distribute effort across several teams. Additional users can also increase support, operational effort and ongoing development.
Ticket-ops pain. When new environments, access or deployments regularly run through tickets to a central team and sit there, operations has become the bottleneck. Waiting time on routine tasks is the clearest signal that self-service is missing.
Sprawl. Every team has its own pipeline, its own deployment pattern and its own interpretation of the security requirements. Onboarding takes weeks because nothing looks the same twice, and audits turn into archaeology. Golden paths make the desired route the most convenient one and thereby tidy up without forbidding.
An Internal Developer Platform pays off when recurring tickets and inconsistent home-grown builds visibly cost more than a platform team. If these signals are missing, a portal is a solution in search of a problem.
What an IDP does not solve
A platform amplifies the state it finds. If the cloud foundation is unstable or infrastructure exists only partially as code, the IDP merely automates the chaos faster. Unclear responsibilities do not disappear either: who operates a service, who answers for costs and who enforces requirements has to be settled beforehand.
The second limit is adoption. The CNCF maturity model distinguishes adoption driven by requirements from adoption driven by users themselves. For lasting acceptance, golden paths need to make everyday work easier; outdated templates and unmaintained documentation work against that.
The minimal start: templates and docs before the portal
The most common mistake is to begin with portal procurement. A viable entry point needs no new product, but two artefacts that work in any Git environment:
- One or two templates for the most common use case, say a new service with pipeline, deployment and base configuration. Shared Terraform modules are often the first golden path a company already half owns; our article Terraform for teams covers how to organise them.
- Documentation that describes the route from zero to a running service and can be followed by an uninvolved team.
If these routes are used voluntarily and requests for the next template come in, there is a platform product that a portal can usefully make visible. If usage stays away, the test has cost little and shown a lot.
This approach matches the CNCF maturity model, which explicitly describes the lower stages as tactical solutions: first the targeted benefit, then the strategy. Whoever goes the other way round and starts with a portal tender buys a surface for content that does not yet exist.
Backstage as an example
The best-known open-source tool in this field is Backstage, a framework for building developer portals. It comes with a software catalogue for services and their ownership, plus software templates for new projects, TechDocs for documentation following the docs-like-code principle and a plugin system for connecting existing tools.
Backstage is, however, a framework, not a finished product: setup, operation, updates and plugin maintenance stay with the platform team and require development capacity of their own. That is not an argument against it, but it is a line item in the calculation. Whoever does not recognise the signals from the sections above is initially better off with templates and documentation without a portal.
What you can decide afterwards
- Whether the three signals (many teams delivering in parallel, ticket waiting times, sprawl) are present in your organisation or not.
- Where you start: templates and documentation first, the portal only after demonstrated use.
- What you measure after the start to see whether the golden paths are used voluntarily.
Frequently asked questions
Is Backstage the only option?
No. Backstage is the best-known open source framework, and there are commercial portals alongside it. More important than the product is that templates and self-service exist underneath before an interface is put on top.
Do we need our own platform team?
Not for the minimal start. Templates and documentation can be maintained by an existing team. The platform needs its own team as soon as several teams depend on it and it has to be run like a product.
How do we measure whether the platform is adopted?
By use: how many new services are created from a template, how often self-service is used instead of a ticket and whether requests for more templates come in. Mandatory use alone does not prove the benefit. Team feedback, shorter waiting times and fewer manual workarounds also matter.
Sources
- CNCF Platforms White Paper CNCF TAG App Delivery
- Platform Engineering Maturity Model CNCF TAG App Delivery
- What is Backstage? Backstage documentation
- What is platform engineering? platformengineering.org