Imagine a developer joining a new team. On the first day, they're told that the team runs its applications on Kubernetes, uses GitHub for source code, has CI/CD pipelines for deployments, and uses a few different tools for monitoring and security. None of this is unusual. In fact, this is probably a fairly normal setup for a modern engineering team.
Then the developer gets their first task: create a new service.
That simple request suddenly opens a much bigger list of questions. Where should the repository be created? How should the deployment pipeline be configured? Which Kubernetes resources are needed? How does the service get its environment variables and secrets? Who creates the database? Which monitoring dashboard should be used? What security rules need to be followed?
The developer can spend a few days figuring all of this out, or they can ask the platform team for help. If every new developer and every new service follows the same path, the platform team can quickly turn into a help desk answering the same set of questions over and over again.
This is one of the problems that platform engineering tries to solve. Instead of asking every development team to understand all the infrastructure and tools underneath their applications, organizations can build a set of reusable capabilities and give developers a simpler way to use them.
This is where two terms often appear: Internal Developer Platform (IDP) and Internal Developer Portal (IDP).
They're closely related, but they are not the same thing.
The Platform Behind the Developer Experience
An Internal Developer Platform is the collection of technologies, automation, workflows, and services that make it easier for developers to build, deploy, and operate applications.
It can bring together infrastructure provisioning, CI/CD, Kubernetes, cloud resources, secrets, security policies, observability, and other engineering capabilities. The point isn't just to put these tools in one place. The platform should hide unnecessary complexity and provide developers with reliable ways to perform common tasks.
For example, a platform team might create a standard way to deploy a web service. Instead of every development team writing its own Kubernetes configuration and deployment pipeline, the platform provides a reusable workflow. The developer supplies the information that matters to the application, while the platform takes care of the underlying details.
This is where the idea of a golden path comes in.
A golden path is a recommended way of doing something. It doesn't mean that developers are forced to use only one technology or one approach. It means that if they want the path that is already supported, secure, and maintained by the platform team, they have an easy way to follow it.
This distinction is important because an Internal Developer Platform is not simply a collection of DevOps tools. Kubernetes, GitHub Actions, Terraform, Argo CD, Prometheus, and other tools can all be part of a platform, but putting them next to each other doesn't automatically create one.
The value comes from connecting them into useful workflows.
The CNCF Platforms White Paper describes platforms in a similar way: they bring together capabilities and provide an interface that reduces the amount of infrastructure complexity developers need to deal with. Humanitec frames it as a set of capabilities that creates a self-service experience for developers and supports the organization's preferred ways of building and delivering software.
That's half the picture. The other half is still a question: How does a developer actually find and use all these capabilities?
The front door: Internal Developer Portals
Go back to our developer who needs to create a new service. Suppose the organization has already built a good internal platform. There are templates for new services, automated deployment workflows, documentation, monitoring integrations, and all the required infrastructure automation.
That sounds great.
Now imagine the developer has to search through Git repositories, internal documentation, Slack messages, and several different tools to find all of it.
The platform may be excellent, but the developer experience is not.
An Internal Developer Portal helps solve this problem by giving developers a central place to discover and interact with the software and capabilities available to them.
One of the best-known examples is Backstage, the open-source developer portal framework created at Spotify. Backstage provides a software catalog where teams can keep information about their services, documentation, ownership, and dependencies. It also provides templates that can help developers create new software using the organization's preferred patterns.
This matters because, as an engineering organization grows, knowing what exists can become almost as difficult as building it.
A developer may know that a payment service exists, but who owns it? Where is its source code? What does it depend on? Where is its documentation? Which team should they contact if something breaks?
A good developer portal answers these questions without requiring the developer to play Sherlock Holmes.
Spotify's experience with Backstage is quite interesting because it started as an internal tool and grew into an open-source project used by many organizations. Spotify has written about this journey in Celebrating Five Years of Backstage.
Commercial products such as Port and Cortex take a similar idea and add capabilities around service catalogs, engineering standards, scorecards, and self-service workflows.
But calling a portal a "directory" would undersell what modern portals can do. A developer portal can also be the place where a developer starts an action. It might allow them to create a service, request an environment, trigger a deployment, or perform another operational task.
This is where the line between the portal and the platform starts to become less obvious.
So where does the platform end and the portal begin?
Let's return to that new service.
The developer opens the internal portal and selects Create a new component. They choose a service template, enter the name of the application, connect the source code repository, and submit the request.
The portal itself doesn't need to know how Kubernetes works. It doesn't need to know which API should be called or how the deployment pipeline should be configured. Instead, it passes the request to the underlying platform capabilities.
The platform then does the hard work with it's control plane acting as its brain.
The control plane coordinates the underlying tools and capabilities through a platform contract, enforcing governance. It knows how the different pieces of the platform need to work together and based on the request, it manages the necessary steps behind the scenes. It can create the Kubernetes manifests, configure the required resources, set up the deployment workflow, apply security policies, and connect the application to monitoring and other services.
From the developer's point of view, this might feel like one simple action. Behind that button, however, there could be several systems working together.
That is the key difference.
The portal is the place where developers discover and interact with the platform. The platform is the set of capabilities that actually enables the work.
The distinction isn't always a clean technical boundary. A portal can contain automation. A platform can expose APIs and command-line tools. Some products combine both ideas. What matters more is understanding the roles they play in the developer experience.
This is also where a lot of the confusion comes from. Backstage's Software Templates can run real actions: create a repository, open a pull request, etc. It's tempting to keep adding steps until the template is your deployment process. At that point you've built a platform, just a thin one that lives inside your portal's template files. That holds up until a second interface, like a CLI, a CI job, or an AI agent, needs the same capability and has no way to reach it.
It's also why you can have an Internal Developer Platform without a traditional portal. Developers could interact with the platform through APIs, CLIs, MCP (Model Context Protocol), or other interfaces. In the same way, it's possible to have a developer portal that provides a catalog and documentation without having a strong platform underneath it.
The two become much more useful when they work together.
What does this look like in a real platform?
Open-source projects such as OpenChoreo provide an interesting example of the platform side of this story.
OpenChoreo is an open-source Internal Developer Platform designed to simplify application development and deployment on Kubernetes. Instead of exposing every Kubernetes detail to application developers, it provides higher-level concepts and workflows that allow platform teams to define how applications should be built and deployed.
This is an important idea in platform engineering.
Developers don't necessarily need less technology. They need less unnecessary complexity.
Kubernetes is powerful. So is a commercial aircraft. Neither means every passenger should have to understand how the engine works. Most application developers do not want to think about every Kubernetes resource required to deploy a service. They want to build the service and have a reliable way to run it.
OpenChoreo approaches this by providing platform abstractions, reusable workflows, deployment capabilities, GitOps, and observability. Platform engineers can define the capabilities and rules of the platform, while application developers work with simpler application-level concepts.
OpenChoreo also includes a developer portal experience built around Backstage. This creates a useful example of how the two ideas can come together: the portal provides the developer-facing experience, while the underlying platform provides the capabilities and automation.
The OpenChoreo architecture documentation describes how its different platform components work together. At the heart of this architecture is the control plane, which acts as the brain of the platform. It brings the underlying tools and capabilities together, providing a consistent way to enforce governance and manage how applications are built, deployed, and operated.
In addition to the control plane, OpenChoreo separates the platform into multiple planes, each with a distinct role. The experience plane provides the interaction interface (for both humans and agents), the data plane runs application workloads, the workflow plane handles build and deployment workflows, and the observability plane collects logs, metrics, and traces. The control plane coordinates the other planes, ensuring their capabilities work together as a cohesive platform while each plane focuses on its specific role.
Looking at examples like this makes one thing clear. An Internal Developer Platform doesn't have to be a single tool. It can be a system made up of several connected capabilities, with clear interfaces between them.
And the portal doesn't have to replace those capabilities. It gives developers a simpler way to consume them.
Why does the distinction matter?
It may be tempting to say that this is all just terminology. After all, developers do not really care whether something is called a portal or a platform. They care whether they can get their work done without spending three hours searching for the right configuration file.
True, but the distinction becomes useful when deciding what to build.
Imagine a company where developers constantly ask, "Who owns this service?", "Where is the documentation?", or "Which repository contains this application?" The immediate problem is discoverability. A software catalog and developer portal could make a big difference.
Now imagine another company where developers know exactly where everything is, but creating a new environment takes three days and every team has a different deployment process. In that case, adding another portal page probably will not solve the real problem. The organization needs better platform automation.
In many organizations, the answer is both.
The portal becomes the front door, while the platform provides what is behind the door.
This also explains why simply installing a developer portal doesn't automatically create an Internal Developer Platform. You can have a beautiful catalog with hundreds of services listed in it and still require developers to open tickets every time they need an environment.
That is a very nice catalog. It is not necessarily a platform.
The reverse is also true. An organization can have excellent platform automation but make developers interact with it through a confusing collection of scripts, repositories, and internal documentation.
The machinery works, but nobody knows where the buttons are.
Building the right thing
Platform engineering usually goes better when you don't start with the question, "Which platform should we build?"
Start with a developer problem.
Maybe creating a new service takes too long. Maybe developers spend too much time configuring deployment pipelines. Maybe service ownership is difficult to discover. Maybe every team has invented its own way of deploying applications.
Pick one of these problems and solve it well.
A good platform team can then turn the solution into a reusable capability. A good portal can make that capability easy to discover and use. Over time, more workflows can be added as new problems appear.
This is also why platform engineering should be treated as an ongoing product rather than a one-time infrastructure project. Developers are the users of the platform, and their feedback should shape what the platform provides.
The CNCF Platform Engineering Maturity Model is useful here because it looks at platform engineering as something that evolves as organizations mature.
The goal is to remove the right complexity, not to build the biggest platform or the most impressive portal.
The difference, in short
After all the architecture diagrams, tools, portals, Kubernetes clusters, templates, and very serious platform-engineering discussions, the difference can be reduced to something quite simple:
An Internal Developer Platform provides the capabilities and automation developers need to build and run software, while an Internal Developer Portal gives them a simple place to discover and use those capabilities.
The two are not competitors. A portal without useful platform capabilities can become a nice-looking directory. A platform without a good developer experience can become another complicated system developers have to learn.
When they work together, something much better happens.
When the two work together, a developer can open one place, pick the supported path, get what they need, and go back to writing code. Tht might be the real test of a developer platform: how little time developers spend thinking about the platform itself.
Top comments (0)