WTF?! Internal Developer Platform vs Internal Developer Portal vs PaaS

You’re given a mandate to build an Internal Developer Platform (IDP) which management says will fix your Ops overhead and enable developer self-service. Exciting times. But before you get started, you first want to figure out what an IDP actually is and what it means to ship one. Seems reasonable… So you start Googling away.

You do some research, land on internaldeveloperplatform.org, and start mapping out what tooling you can assemble to build your platform. You join the Platform Engineering Slack channel and find multiple threads of practitioners discussing the latest reference architectures for enterprise-grade IDPs. You then figure out these platforms are usually composed of five planes and have a Platform Orchestrator gluing them together. So far so good, you feel you can report back to your VP with a design that makes sense. Now you can go to bed and sleep blissfully.

Did that seem too quick? The next day you wake up and get targeted by a LinkedIn ad telling you an IDP actually stands for internal developer portal. So you go on Reddit and see lots of people praising Backstage, a portal open-sourced by Spotify, which seems to be all the rage. But then your friend comes back from KubeCon and tells you Backstage is already history. They also tell you there are now a bunch of closed source copycats taking over the exhibition floor, and that you should probably check them out. You dive deep and try to work out the difference between all these portals, which one is the best for you? They all seem to offer very similar functionality, and you remain undecided.

At this point your sleep is getting progressively worse as you try to make sense of it all, but the more you look, the more questions you have. One thing you know for sure is that one way or another, you need to build this IDP. 

Not so fast! Even this last certainty is taken away from you. A sales guy cold calls you to give you the big news: building is for losers and you can simply buy a platform, it’s called a PaaS, or Platform as a Service.

Peak confusion. Multiple sleepless nights. Your life is in shambles and your job is on the line. The only comfort you find is that you are not alone in this. Many other engineers are also trying to navigate the hot new space of platform engineering, desperately hoping to make sense of it one day.

But despair no longer, you’ve come to the right article. We’re here to set the record straight on what an IDP actually is and give you the (actually surprisingly simple) intel you need to make the right choice for your setup. And to get that sleep back.

What is an Internal Developer Platform?

Let’s start with the OG. When platform engineering started shaping up as a category and a trend a couple of years back, there was only one IDP in town, the Internal Developer Platform.

According to Kaspar von Grünberg, a pioneer in the space, “an Internal Developer Platform is the sum of all the tech and tools that a platform engineering team binds together to pave golden paths for developers. IDPs lower cognitive load across the engineering organization and enable developer self-service, without abstracting away context from developers or making the underlying tech inaccessible. Well-designed IDPs follow a Platform as a Product approach, where a platform team builds, maintains and continuously improves the IDP, following product management principles and best practices.”

TLDR, an IDP is the platform layer for the enterprise that is built and shipped as a product by a dedicated platform engineering team, in order to remove complexity (without removing context) and enable developer self-service. An IDP effectively enables true DevOps, true “you build it, you run it”, at an enterprise scale and for complex cloud native setups.

In practice, your IDP would look similar to the reference architectures below, depending on if your infrastructure is running on AWS, Google Cloud, Azure or a multi-cloud setup:

One of the biggest steps forward in platform engineering this year was the talk at PlatformCon23 (the largest platform engineering event in the world) by a team of McKinsey engineers who presented a set of reference architectures for enterprise-grade IDPs. These are based on research looking at 100s of platform engineering setups in the enterprise and distilling best practices and clear design patterns.

An enterprise-ready IDP consists of five planes:

Developer Control Plane 

This is where application developers interact with the platform. It’s the primary configuration and interaction interface, and includes:

• A version Control System (VCS) like GitHub or Bitbucket, which usually contains two types of repositories:
• Application Source Code
• Platform Source Code, e.g. with Terraform
• A workload specification like Score
• A portal for developers to interact with, e.g. Backstage or the Humanitec Portal

Integration and Delivery Plane 

This is where application developers and platform teams meet. It’s where the building and storing of images happen, as well as the generation and management of application and infrastructure configurations. This plane usually contains four different tools:

• A CI pipeline like GitHub Actions
• An image registry like JFrog
• A Platform Orchestrator like Humanitec’s
• A CD system, which can be either the one of the Platform Orchestrator itself or a dedicated tool like ArgoCD

Monitoring and Logging Plane 

This plane can vary greatly depending on the monitoring and logging requirements of an engineering organization. It is not however a key focus of this reference architecture.

Security Plane

The security plane of the reference architecture is focused on the secrets management system. The secrets manager stores config information such as passwords, API keys, or TLS certificates needed by an app or service at runtime. The Platform Orchestrator references the secrets and injects them into the workloads dynamically.

Resource Plane

This is where the actual infrastructure is including clusters, databases, storage, DNS services, and more. The configuration of these resources is also managed by the Platform Orchestrator which dynamically configures infrastructure with every deployment and creates, updates, or deletes resources as required.

These are the five planes that make up an IDP and they need an orchestration layer, a “glue” that makes sure they are working together nicely instead of in silos. A Platform Orchestrator is the key for an IDP to be truly enterprise-grade. Not just because it brings all the pieces together, but because it also enables crucial enterprise functionality, like RBAC and clear governance across all workflows and services.

Key design principles

There are dedicated resources if you want to learn more about what best practice design patterns for an IDP looks like. But just as a quick overview, the key design principles that top-performing platform teams follow when building their IDP are:

1. Developers should be able to pick their interface of choice, be it a UI, API, CLI, or simply code-based
2. An IDP shouldn’t break developers’ workflows
3. Code should be the single source of truth
4. Your IDP should be compatible with your complex brownfield setup, both current and future
5. Build golden paths, not cages 
6. Ship your platform as a product (iterate and listen to your devs)
7. You can never make everyone happy. Focus on the 80/20 when building your platform

In summary, an IDP is what best describes the layer between Ops and development teams that lets enterprises enable self-service, while still being able to onboard 100s or 1000s of engineers to an increasingly complex cloud native setup. It’s the superset of all tooling and workflows that are the end product of a platform engineering initiative and team.

What is an internal developer portal?

Three things happened over the last year that contributed to the general nomenclature confusion in the platform engineering space:

1. A bunch of new portal vendors emerged hoping to capitalize on the success of Backstage, by offering a closed-source, easier-to-get-started version of the open source portal.
2. Platform engineering and IDPs went mainstream, capturing a lot of headlines, KubeCon booth graphics, etc.
3. Gartner published the following definition (ironically trying to clarify things): “Internal developer portals serve as the interface through which developers can discover and access internal developer platform capabilities.” Source: “A Software Engineering Leader’s Guide to Improving Developer Experience” by Manjunath Bhat, Research VP, Software Engineering Practice at Gartner. https://www.gartner.com/document/4017457‍

All this led to most new portal vendors seizing the opportunity (understandably) to both ride the IDP hype and leverage the Gartner definition. They started pushing the term IDP as an abbreviation for Internal Developer Portal instead of Internal Developer Platform. This is clearly far from ideal, especially considering portals are an important part of the overall platform engineering space, being one of the main interfaces INTO an IDP (see Gartner definition).

The reference architectures presented by McKinsey reconfirmed this, with service catalogs and portals sitting in the Developer Control Plane.

Typical features of portals are:

• Service catalog functionality, including metadata on e.g. service ownership
• Scaffolding and service templating functionality 
• Scorecards (app health, security status, etc.)

Main portal players: Backstage OSS but also commercial alternatives (Port, Cortex, Compass)

Again, it's important to highlight that portals can be a useful tool in your platform team’s toolbox and provide a great interface for your developers into your IDP. But they are an interface, they are not your IDP.

What is a PaaS?

As you’ve probably gathered by now, one of the defining qualities of an IDP is that it’s built and shipped as a product by a dedicated platform engineering team. Crucially, this means you can’t outsource the building to an external vendor, because they simply won’t be able to cover all your enterprise edge cases e.g. infrastructure integrations. Nor can they design golden paths that make sense for your developers, and that strike the right balance of abstraction while still providing context.

In short, you can’t buy an IDP. But what you can buy is a PaaS. PaaS offerings are great for small teams and greenfield scenarios, but the reality is they simply don’t scale to complex brownfield enterprise setups (the OG here was Heroku, which famously never broke into the enterprise market).

Again there are PaaS newcomers that try to milk the IDP hype to their benefit and pretend to be one. They promise a Heroku-like experience but with more integrations. They try to replace parts of your existing setup and enforce new workflows. Often, only a certain tech stack or cloud provider is supported. They usually don’t integrate with industry standards like GitOps or git-based workflows where you already use solutions like ArgoCD or FluxCD. You’d also struggle to make this work with your existing Helm or Terraform setup.

Again, it’s been proven over and over by the market that a PaaS solution can work well in very specific use cases (e.g. an e-commerce shop) or for small teams with greenfield setups. It just doesn’t scale to generalized enterprise setups, which is where the need for a true IDP emerges.

A PaaS also doesn’t follow the IDP design principles (listed above):

• Developers won’t be able to pick their interface of choice, be it a UI, API, CLI, or simply code-based
• Code won’t be the single source of truth

This doesn’t mean a PaaS won’t be the right solution for you. For instance, if you’re a startup just getting started building on top of a simple cloud setup, you won’t want to overcomplicate things (which there’s lots of value in). Just remember, you can’t buy an IDP.

Get started with an IDP

This hopefully gave you a clearer view into the fast-moving space of platform engineering and the emerging category of Internal Developer Platforms. Like every new category (which is also getting a lot of attention from analysts and enterprise buyers), Internal Developer Platforms (and especially their abbreviation to IDP) are getting fought over by all sorts of vendors. This is to be expected, but it’d be a shame if it ended up like one of those undefined terms like GitOps or DevOps — which mean everything and nothing — and don’t help you much when you’re trying to figure out what your team and organization needs.

If you’re working on an enterprise platform and looking for a clear blueprint to get started building your IDP, check out these recently open-sourced implementations of the reference architectures presented by McKinsey for GCP and AWS setups.