How to build an Internal Developer Platform

This article covers everything you need to know about how to build an Internal Developer Platform (IDP). We’ll start with an overview followed by why you should build one, a few considerations before setting off on your IDP journey, and what the architecture of an IDP looks like. We’ll also zoom in on getting started the right way by building a Minimum Viable Platform (MVP), what exactly an MVP is, and how to deliver one quickly and effectively with the Humanitec MVP program.

What is an Internal Developer Platform?

An Internal Developer Platform (IDP) is built by platform teams within large enterprises using a combination of open source, commercial, and in-house tools. Done well, IDPs reduce ticketops, standardize config setups and workflows, cut lead time and time to market (TTM).

Crafted through the integration of various tools and technologies, an IDP can enable true DevOps. When done well, it embodies "you build it, you run it" at an enterprise scale and for complex cloud native setups. Well-designed IDPs also follow a platform as a product approach. The platform team builds, maintains, and continuously works to improve the platform by following product management principles and best practices. 

Some solutions are mistaken for an IDP and cause confusion. This includes end-to-end DevOps platforms and Heroku-like Platform-as-a-Service (PaaS) models that try to cover the entire software delivery cycle within a single commercial solution. The shared acronym "IDP" is also confusing when associated with internal developer portals (which function only as an interface to an IDP) and service catalogs.

Unlike PaaS solutions, IDPs are not readily available as off-the-shelf solutions. They cover the software delivery cycle end-to-end including:

• Infrastructure orchestration
• Application configuration
• Deployment management
• Environment management
• RBAC

Why build an IDP?

The impact of an IDP is far-reaching and extends across every corner of an enterprise. On an organizational level, a well-designed IDP slashes TTM and speeds up innovation cycles. For development teams using an IDP, we’ve seen improvements across key DevOps metrics including lead time, deployment frequency, change failure rate, and Mean Time to Recovery (MTTR). 

This was proven for the first time by the Puppet State of DevOps Report 2021. More studies such as Humanitec's 2023 DevOps Benchmarking Study reinforced these findings, revealing an overwhelming 93.15% of top-performing engineering organizations use internal tooling like an IDP compared to just 1.88% of low-performing teams who did the same. 

From an operational standpoint, an IDP drives standardization and automation. It eliminates ticket-based workflows (ticket ops) and minimizes repetitive manual tasks having to be performed under time constraints, which causes DevOps burnout.

For developers, an IDP enables self-service capabilities (no more ticket ops). At the same time it solves the issue of developers being expected to shoulder Ops tasks and be an expert in everything. The results are less cognitive load, an improved developer experience, and in the end; higher developer productivity. 

Pre considerations before building an IDP

Although the benefits of an IDP are clear, you may still wonder whether to build or buy a platform. 

In short, you cannot buy an enterprise-grade IDP. You can buy a platform as a service (PaaS) which is great for small teams in greenfield scenarios. But you’ll encounter huge limitations in a brownfield enterprise setting. For this reason, large enterprises steer clear of PaaS and instead build their IDP using a combination of open-source and commercial tools. 

You might also wonder if you can build your platform completely from scratch, or build core components like CI/CD tooling and a Platform Orchestrator entirely on your own. Successful platform teams understand the more they try to build on their own, the more likely they are to fail. A Platform Orchestrator for example is the centrepiece of a platform’s architecture and the de facto industry standard solution that transforms a disjointed toolchain into a truly enterprise-grade IDP. 

However when categories such as platform orchestration are young, there’s a tendency to try and build everything yourself. We’ve seen this before with CI systems or container orchestration. But could you today imagine wanting to build your own Kubernetes? The talent needed to build and run it on your own and the total cost of ownership (TCO) of a Platform Orchestrator are just some of the things you should consider.

The architecture of an IDP

If you’re ready to start your platform journey, your next question should be “What should an IDP look like?” Until recently no proven, standard pattern existed for platform teams to follow. Based on data from 100s of setups across varying company sizes we created battle-tested reference architectures for enterprise-grade IDPs on AWS, Azure, and GCP. Adopting them will save you months figuring out what your IDP should look like, by following standard patterns that apply regardless of your technology and requirements.

Within these reference architectures, there are five main planes that make up an IDP:

1. Developer Control Plane: This is the primary configuration layer and interaction point for platform users. Components include Workload specifications such as Score and a portal for developers to interact with which can be the Humanitec Portal, but you might also use Backstage or any other portal on the market.
2. Integration and Delivery Plane: This plane is about building and storing the image, creating app and infra configs, and deploying the final state. It usually contains a CI pipeline, an image registry, a Platform Orchestrator, and the CD system.
3. Resource Plane: This is where the actual infrastructure exists including clusters, databases, storage, or DNS services.
4. Monitoring and Logging Plane: Provides real-time metrics and logs for apps and infrastructure. 
5. Security Plane: Manages secrets and identity to protect sensitive information, e.g., storing, managing, and security retrieving API keys and credentials/secrets.

To further simplify and speed up the process of building an IDP, we’ve open sourced the implementation codes for reference architectures on Azure, AWS, and GCP. This provides a starting point for you to build your IDP within minutes, and include customization capabilities to ensure your platform meets the unique needs of your users (developers). 

Head to our GitHub repo to find out more and fork our pre-packaged platform architecture as code for AWS, Azure, or for GCP. 

We’re currently working on an open source version of this architecture for platforms on OpenShift, Oracle, and Red Hat. 

Core components: Platform Orchestrator  

As shown in the reference architecture diagrams, a Platform Orchestrator is a core component of any IDP. It’s the configuration engine that orchestrates the entire platform layer and is built on learnings from hundreds of engineering teams. Engineering teams using a Platform Orchestrator can build golden paths for developers and enable them to add any resource they need, spin up environments, roll back, and much more. All without having to wait for Ops help, thanks to clear baselines that drive standardization by design across all teams and workflows. Op teams no longer have to fight tickets and because both app and infrastructure configs are generated with each deployment dynamically, the number of config files is reduced by up to 95%. 

Core components: Score 

When it comes to interface choice, successful platform teams leave this to the developers. If there is no abstraction layer, you have not built a platform and by removing too much context, developers will push back on you. The reference architectures apply smart abstractions that are layered so developers can follow them,  but are not obliged to. Offering a code-based abstraction layer like Score keeps developers in the git-based workflows they’re familiar with. By using Score, they can describe how their apps fit together and define what resources they depend on. These requests are then matched by the Humanitec Platform Orchestrator against the baseline configs (which are set by the platform team). 

Start the right way, build a Minimum Viable Platform first!

The main reason to build a Minimum Viable Platform (MVP) is because when starting their IDP journey, most businesses fall into the trap of trying to solve all their problems at once. This quickly devolves into what we like to call “complexity quicksand” as the project scope (and risks) increase exponentially. Even worse, some companies mistake platform engineering as being all about tools and spend months figuring out which tool should go where rather than actually building something useful. Instead, start small and build an MVP first.

What is an MVP?

So how do you define an MVP? The MVP concept is rooted in a lean methodology of starting simple and small which allows you to prove value fast, using feedback to  expand effectively over time. 

It’s important to remember that the MVP is a representative case for your platform. It should have as much in common with your target setup as possible, but avoid complicated or unique cases. The MVP is a highly simplified, representative first version of the platform in the context of a “HelloWorld” scenario.

 The MVP for your HelloWorld app should be:

1. Representative: The MVP should have representative basic resources and components that are common across the technical estate. Generally, this includes clusters, containers, version control, a single database type, basic DNS, and basic CI/CD.

2. Repeatable: You should be able to use the basic skeleton created in the MVP process as a “quick start” for other applications and teams within an organization. The MVP is the foundation from which the full-scale platform is built.

3. Iterative: MVPs focus on the future. The context of creating this version of the platform is with growth and iteration in mind. Remember that commitment is required to scale.

4. Innovative: The teams that work on these MVPs are pioneers and drive new ideas forward. MVPs should inspire contributors to learn new things and engage with new technologies. 

At this stage, your MVP should not involve:

1. High compliance scenarios: You can think about security and high-compliance requirements, but an MVP shouldn’t have to meet high compliance standards.

2. Advanced architectures: Service meshes, multi-cluster deployments, failover, customized portal integrations, advanced CI/CD (Blue/Green), etc., do not need to be covered by an MVP.

3. Advanced resource configuration: You should pick one common resource type to begin with and not try to cover every possible developer request.

4. Advanced observability: Integration of advanced components and highly complex observability services is something you can build on top of later. 

Following these principles, your MVP should easily be achievable within just four phases. The speed of these four phases is dependent on your organization. With certain fast moving, it has taken as little as 4 weeks. However, whether it takes 4 weeks, or 4 months, this MVP process successfully avoids the dreaded yearslong timeline that has wasted so much time, effort and money for so many platform initiatives.

To successfully build your Minimum Viable Platform it is crucial to utilize the open source reference architectures referenced in this article, and to take advantage of available prepared resource packs. You can also use our learning path where you’ll find hands-on tutorials on how to set up your reference architecture across all major cloud providers.

If you need more certainty in the success of your Minimum Viable Platform, you can join the Humanitec MVP program to get direct help from experts with experience building dozens of MVPs.

Deliver your MVP in just four phases

If you’re ready to get started building your platform, the Humanitec MVP program is a guided playbook that helps you do so in the fastest, most reliable, and cost-efficient way possible. It includes a four-week process that we’ve successfully executed dozens of times, enabling enterprises to deliver value at speed. And it comes with expert help and guidance from some of the industry's best, most experienced platform architects.

Below is how each week looks for the companies we’ve helped as part of our MVP program.

‍

Iterate and expand

At the end of the four phases, you should have an MVP that proves value beyond just the developer and platform teams. It should be ready to grow into an enterprise-grade IDP in a scalable, sustainable way.

Getting stakeholder buy-in allows you to widen the net of users from whom you can get feedback. This then enables you to iterate and expand your MVP scope. And the more teams that see the value, the easier it’ll be to secure funding for a larger platform engineering initiative.

What you’re left with is a clear path from a simple MVP to an enterprise-grade IDP that enables Dynamic Configuration Management and standardization by design. Both are key drivers for better DevEx and the velocity gains expected from platform engineering.

Looking ahead: faster innovation and time to value 

Once your IDP is up and running, developers will no longer need to be experts in everything which reduces cognitive load and elevates the developer experience. They’ll be free from wasting time waiting for Ops (ticketops), able to perform daily developer activities (debug, rollback, diffs, logs), self-serve, and capable of tackling routine tasks such as scaffolding a new Workload and deploying ephemeral environments. Driving efficiencies and productivity in this way helps speed up innovation cycles which ultimately, reduces time to market. 

By following the best practices set out in this article together with the Humanitec MVP program, your organization can start realizing tangible benefits fast by building an IDP that’s truly enterprise-grade.

Need further support and guidance on how to master your IDP? Talk to a platform architect.