Key principles of a successful internal developer platform

Modern software delivery is a story of increasing complexity. As organizations adopt cloud-native technologies, the number of tools, APIs, and processes keeps multiplying. Developers spend more time wrestling with infrastructure than building features, while platform engineering teams struggle to keep systems secure, compliant, and cost‑efficient.

That’s why more and more enterprises are turning to internal developer platforms (IDPs). But what makes a good IDP? Let’s break it down.

Why do you need an IDP?

Think of an unplanned city. Every resident builds their own house, lays their own water pipes, runs their own electricity, and decides their own traffic rules. The result? Chaos: tangled wires, pothole‑ridden streets, constant outages, and no way to keep things safe or efficient. You end up with factories within residential areas, schools in the midst of factories, a jumble of mismatched structures and systems. And the chaos continues.

That’s what software delivery looks like without an IDP:

Fragile, snowflake environments.

Inconsistent developer experiences.

Slow onboarding times.

Gaps in security and compliance.

Now compare that with a planned city. Roads, plumbing, electricity, and zoning are built once, shared by everyone, and maintained by city planners. Residents build houses, schools, or shops on top of that orderly foundation, within demarcated neighborhoods.

That’s what an IDP provides:

Faster delivery through golden paths.

Secure and compliant environments.

Governed, monitored processes.

Happy developers.

An IDP is the paved road that lets teams focus on what they’re building, not on how it runs.

What should an IDP deliver, and to whom?

An IDP has two primary audiences, developers and platform engineers. Think of developers as the city’s citizens and builders, and platform engineers as the city planners and utility operators.

Developers:

Build applications (homes, shops, schools).

Rely on infrastructure (roads, power, water, emergency services).

Shouldn’t need to worry about how utilities work under the hood.

Platform engineers:

Provide paved roads, power lines, zoning codes, and shared services.

Don’t build every building but ensure safety, connectivity, and scalability.

Use automation and blueprints to replicate working neighborhoods.

The magic of an IDP lies in getting the abstractions right. Developers need only the abstractions relevant to their work (e.g., database type), while platform teams need deeper visibility (e.g., how workloads run across VMs, containers, or serverless).

Think of the abstractions needed for running a well-planned city. A city is made up of:

Neighborhoods or districts (residential, urban, financial)

Units (houses, schools, shops)

Utilities (electricity, water, roads)

Connectivity (traffic lights, speed limits, lane directions)

A digital enterprise has similar characteristics. This is where the following four layers of enterprise abstraction emerge. A digital enterprise is made up of:

Business domains such as marketing, sales, and customer service. Like a city’s neighborhoods, each domain has its own style, characteristics, and purpose.

Business functionalities such as microservices, web applications, and mobile applications within each domain. These are similar to shops, houses, and schools in neighborhoods.

Deployment services such as CI/CD, observability, runtime infrastructure, and scaling. Just as a city cannot function without electricity, water, and other utilities, an enterprise needs deployment services to be operational.

Middleware such as API gateways, service meshes, ingress, and firewalls. In a city, moving goods and services requires roads, intersections, speed limits, lane directions, and so on. In an enterprise, middleware services provide this connectivity.

By carefully defining these layers, an IDP ensures consistency, safety, and clarity across the enterprise.

10 key principles of a good IDP

So how do you build an IDP that truly delivers? Here are 10 guiding principles.

Separation of concerns

Enterprise portal

Domain-driven design

API-first mindset

Security-first mindset

Universal interface

Self-service

Ops-driven, declarative and automated

Intelligent and insightful

Product orientation

Separation of concerns

There are two types of separation of concerns that come to mind with respect to internal developer platforms, the separation between developers and operators and the separation between the control plane and the data plane.

Developers vs. operators

An IDP should serve both application developers and platform operators. Application developers focus on APIs, applications, databases, etc. Operators worry about infrastructure, scaling, costs, networking, etc. These two personas therefore are very different. Their interests are different, and so should be the abstractions for these roles.

A developer is focused on implementing code for his/her application. Developers write code on their local workstations (laptops), test it out, and commit to the repositories when done. CI/CD kicks in at that point and deploys their changes to a development environment. Developers wouldn’t really care whether this code runs in a VM or container in these environments, but the operators certainly do. What should we think about abstractions in this case then? Since developers wouldn’t typically care about this detail, it should be abstracted out (hidden away). But since this detail is critical for operators, it should not be abstracted away from them, it should be exposed. Another example we could think of is the implementation language and technology stack of the application. Whereas developers need to understand the language and technology stack of their applications, operators may not. After all, these are just workloads of different types. A microservice written in Java vs. Go is the same from an operator point of view; it’s a workload with environment variables. This detail should therefore be abstracted away from operators but exposed to developers.

It becomes clear then that abstractions for developers and operators on an IDP aren’t the same. It is crucial to understand this difference and build your IDP such that the concerns of developers and operators are separated.

Control plane vs. data plane

Another important separation in an IDP is between controls and runtimes. The control plane is similar to a signalling tower. It issues instructions and commands, but doesn’t run workloads. Workloads are run on the data plane. Permissions, scaling, and other operational characteristics of a control plane are therefore very different to that of a data plane. Understanding this difference is critical to having a smoothly operating IDP.

Another point to consider is that application workloads may run on heterogeneous infrastructures in various forms. You might run your development environment in a low-cost data center while QA, staging, and production run in a public cloud. This would mean that the same set of workloads must be operated on different infrastructures. Having one control interface that works with any data plane infrastructure is therefore of paramount importance.

Enterprise portal

An enterprise portal is the front door to an internal developer platform. Developers in organizations end up creating many different digital artifacts. These could be APIs, applications, jobs, databases, caches, queues, and so on. The value of these artifacts are only realized if they are easily discoverable and reused. A lack of discoverability leads to duplication of workloads, zombie assets, wasted spend, and potential security risks.

In addition to discoverability, a portal should provide easy consumption of these artifacts as well. Having self-service access to an artifact’s documentation and convenience mechanisms to connect and consume artifacts are important considerations when building an enterprise portal to an IDP.

An enterprise portal should also provide guardrails for creating artifacts. For example, if a developer wants to create a microservice in Spring Boot, the portal should have the relevant templates that comply with the organization’s rules and regulations that allow him/her to do so. For example, templates should declare allowed versions, folder structures, style guides, and so on. Lack of adherence to the given standards should result in warnings and error reports.

Domain-driven design

Think of an unplanned city where builders are allowed to build anything they want wherever they want to. Not only would you end up with a lot of inefficiencies and inconvenience, but the city would be ugly as well. There would be no consistency, no design, and therefore no beauty in it.

A planned city has neighborhoods. Each neighborhood has its own personality and rules of operations. For example, the speed limits in a school zone would be different form those in urban area. Zoning rules of an urban area would be very different from residential areas. Builders who build infrastructure need to adhere to these rules so that you have a well functioning city.

A digital enterprise is no different. It needs to have its domains, each with its own personalities and operational rules. A customer experience domain would be very different from an operations domain. One would need access to CRMs and other front-office tools, whereas the other would need access to ERPs and other internal systems. The levels of access needed, types of data accessed, etc. would therefore be very different in these respective domains.

An IDP should help align software structure with business processes. It should allow platform engineers to define, tune, and maintain the rules of engagement based on the organizational domains. It should naturally guide developers to create digital artifacts in the right places. Failure to meet these needs will result in inefficiencies, confusion, extra effort, delays, and security risks.

Unfortunately, many IDPs today only focus on reducing cognitive load on developers and increasing delivery velocity. One has to realize that going faster only makes sense if you are headed in the right direction. A well-designed IDP keeps developers on the right track and streamlines the path to the goal.

API-first mindset

Just as the buildings in a city are most useful when connected via roads, digital artifacts in a development organization are most useful when they can be discovered and consumed easily. This means that artifacts must maintain a contractual obligation to its consumers. Every digital artifact therefore needs an API-first mindset behind it.

An API-first mindset means:

Treating everything as an API. Everything you create in an organization, such as services, databases, caches, queues, applications, etc., should be treated as an API.

Sharing and reuse. Everything should be properly discoverable, properly governed, and accessed using standards. No hidden artifacts or private backdoors.

Life-cycle management. All artifacts should be properly versioned and life-cycle managed. Changes should be made on new versions only, adhering to contractual obligations. Older versions should be deprecated and eventually retired.

Quality enablers. Everything should be observed and monitored, with feedback incorporated into the roadmaps of those artifacts.

An IDP built on the above principle enforces a natural order on the organization. That order is critical for a safe and efficient environment that fosters innovation at scale.

Security-first mindset

A city’s residents need to feel safe and protected so that they can get along with their day to day tasks with ease. This sense of security does not come from having security guards and military personnel on every streetcorner. You don’t get a sense of safety when your bags are being checked whenever you enter a public place. This form of ensuring safety comes because security is being added as a patchwork, instead of being built into the design of the city. An IDP needs to have security aspects built in, not bolted on as patchwork. That is why having a security-first mindset when building an IDP is important.

When developers create digital artifacts, the IDP must ensure they are secured by default. Developers should not be expected to BYOS (bring your own security). An IDP should offer end-to-end security required for all kinds of artifacts—for example, authentication, authorization, rate limits, encryption of data at rest, encryption of data in transit, role-based access control, prevention against container escapes, and so on.

Governance of digital artifacts in an IDP is also critically important to ensure safety. This involves things like removing unused artifacts, controlling access to public endpoints, controlling usage of third-party libraries and services, and so on.

A good IDP has to be built upon this principle of a security-first mindset. For an organization to be truly safe it needs to adhere to a “zero-trust” mode of operation. But security needs to be built-in, not bolted-on, so that developers get security “for free.”

Universal interface

An IDP must present a single, consistent interface with consistent abstractions. Many IDPs are a patchwork of many tools with different abstractions, usually “linked together” with a single portal. Such a patchwork makes it very hard for developers and platform engineers to use the platform for their needs. To get something done, you need to jump through many tools and their interfaces. To troubleshoot an issue, you need to have a good “guess” of where the issue might be visible, navigate to that tool, and trace back to wherever the root cause might be.

For example, when something goes wrong in a production system, you may need to navigate to Argo CI to check for deployment-related issues, navigate to Datadog for application-related issues, look at Nginx logs for routing-related issues, and so on.

A good IDP should be like the vehicle diagnostic scanner we plug into the on-board diagnostics port of a car, which provides one interface that aggregates the data from many sensors. Imagine how inconvenient it would be to have 20 different tools to diagnose the many different parts of your car. Unfortunately many IDPs today are like that—a collection of different tools linked together with a single portal. A good IDP should be built on this principle of having one consistent set of abstractions and one universal interface.

Self-service

Self service is probably the most popular principle of an IDP. A good IDP must provide self-service capabilities for both application developers and platform engineers.

For application developers, it’s about the ability to get things done without having to create tickets and wait for days for someone else to attend to them. Self service for developers is supported through what we call golden paths or paved roads. A golden path is a pre-defined, opinionated, and supported way of building, deploying, and operating software. A golden path may not be the only way to get something done on the platform, but it certainly is the recommended, curated path of least resistance.

Platform engineers are often ignored when it comes to self service. Usually, they are just expected to build self-service capabilities for app developers but almost never considered as engineers who need to be served by the platform themselves. But as we discussed in the first principle of this article, an IDP should serve platform engineers too. Platform engineers are expected to provide consistent infrastructures, environments, pipelines, and so on. Just like city builders are expected to provide the same voltage of electricity to all parts of a city, the same water pressure to every household, so are platform engineers expected to provide the same consistent foundations for developers to build on.

This consistency can only be achieved via self-service golden paths that are available to platform engineers. Self service for platform engineers means giving the platform team itself a set of automated, composable building blocks that allows them to design, extend, and operate the IDP efficiently without having to manually stitch together infrastructure or re-invent patterns each time. These self-service golden paths need to have the right guardrails built-in (for handling risky actions such as removing environments, for example), as well as audit trails and proper governance at scale.

Self-service golden paths, for both developers and platform engineers are therefore a key principle in an IDP. Characteristics of such golden paths are:

Opinionated, not restrictive: They encode best practices (tech stack choices, CI/CD templates, security policies) while leaving flexibility for edge cases.

End-to-end workflow: They cover the full life cycle from scaffolding an app, provisioning infrastructure, and CI/CD to observability, monitoring, and incident response.

Self-serviceable: They are exposed to developers through self-service tools, UI, or CLI commands in the IDP.

Abstract away complexity: Developers and platform engineers don’t need to wire together Kubernetes, observability stacks, IAM, etc. The golden path bakes those in behind easy interfaces.

Continuously maintained: Platform engineers evolve golden paths alongside organizational needs, security requirements, and new technologies.

Ops-driven, declarative and automated

Automation (obviously) is critical for an IDP. You cannot achieve the goals of an IDP without automation. But automation without discipline is just a recipe for chaos. That is why ops-driven automation is the way to go. Ops-driven automation is basically about following GitOps workflows for changes made on the IDP. Every action performed on the IDP has to be versioned, recorded, and reversible. All actions need to have audit trails.

It’s important for an IDP’s automations to be in declarative form. This is about declaring the desired state of the system instead of continuously monitoring and reacting to events and alerts. Think of a city’s street lights. Someone needs to turn on the lights at dusk and turn them off at dawn. If something goes wrong in the middle of the night and the lights go off, someone needs to attend to it and turn the lights back on. This is a cumbersome process and requires a lot of labour. However, imagine being able to declare the desired state as the “lights need to be on whenever there’s darkness.” If the system can automatically reconcile the state of the lights to this desired state, the operation of the city’s lights become much more efficient and smooth. No one needs to wake up in the middle of the night just because of a glitch in the system. The system automatically recovers by itself.

For a truly hands-off experience of operating an IDP, the platform’s automations need to work in a declarative manner. Declarative automations with ops-driven workflows are therefore a key principle to build an IDP on.

Intelligent and insightful

An IDP serves many stakeholders. While it may primarily cater to application developers and platform engineers, the benefits of an IDP can be realized by many parts of an organization. To make this possible, the IDP should expose relevant intelligence and insights to all parties. Here are some examples of different stakeholders and the relevant data and insights.

For developers and operators: Insights needed for troubleshooting incidents. Primarly driven by observability data (i.e., logs, metrics, traces).

For business stakeholders: Insights that showcase the impact of digital artifacts on the business. For example, data such as orders placed, user growth, order cancellations, etc. This basically involves converting technical data from an organization’s APIs to business insights.

For engineering managers: Insights needed for assessing the organization’s speed and stability of delivering software. Primarily built on the well-known DORA metrics.

For architects: Insights that help determine the ROI of digital artifacts, insights on the efficiency of resources, cost breakdowns, etc.

In our data-intensive era, insights without intelligence are insufficient. For many years, we’ve been accustomed to looking at all kinds of graphs, charts, and reports. We’ve had to undergo the hard task of analyzing these reports to understand areas of improvements. But now, many of these tasks can be offloaded to AI agents within the IDP. In addition to showing graphs, charts, and reports, these agents can help determine the causes of failures and other areas of improvements for our digital artifacts as well.

Intelligence of course applies across the board, not just for insights. An IDP should incorporate AI everywhere it makes sense. Think of compliance, governance, monitoring, etc. AI has become a tool that can assist many such areas of an IDP. It is therefore crucial to consider AI and insights as a key principle of an IDP.

Product orientation

An IDP should not be a one-off project. A project is something you do once and finish. It has a start date and an end date. An IDP is never a finished project. It is something that continues to live and evolve, forever.

Delivery of software never ends. Furthermore, the types of software that are delivered and the ways in which they are delivered inevitably change. What you deliver today is not the same thing that you will deliver tomorrow. If you treat your IDP as a one-off project, you will build for today’s requirements and stop, and your IDP will not cater to the needs of tomorrow. This is why you need a product mindset for your IDP. Your IDP should evolve to meet future needs, keeping pace with the tools and technologies of the modern industry and providing a platform to lift up and modernize your organization.

A product mindset for an IDP requires proper product management. This includes maintaining a clear roadmap, having regular release cadence, life-cycle management of features, issue tracking, and so on. It also requires paying attention to non-technical factors required for its success. You need to create sufficient awareness around the platform, increase its adoption, gather feedback from users, feed those learnings into the roadmap, and continue to iterate.

This product mindset is therefore a key principle of an IDP. It is critical for long-term success. Treating an IDP as a project will give you short-term benefits but eventually fail in the long term. Strong product management with a real commitment to evolve the IDP like a product is what will guarantee its overall success.

Closing thoughts

A great IDP is more than a collection of tools. It’s your “planned city” for software delivery, providing consistent abstractions, reliable guardrails, and golden paths that empower both developers and platform engineers.

Many IDPs, both home-grown and off-the-shelf solutions, tend to focus only on reducing the cognitive load of developers and delivering software faster. While this approach may deliver short-term wins, it creates inefficiencies and extra toil in the long run.

A successful IDP removes barriers to efficiency and puts both developers and platform engineers on self-service golden paths. It creates order, saves time, saves money, increases satisfaction, and significantly improves an organization’s ability to innovate.

—

New Tech Forum provides a venue for technology leaders—including vendors and other outside contributors—to explore and discuss emerging enterprise technology in unprecedented depth and breadth. The selection is subjective, based on our pick of the technologies we believe to be important and of greatest interest to InfoWorld readers. InfoWorld does not accept marketing collateral for publication and reserves the right to edit all contributed content. Send all inquiries to doug_dineley@foundryco.com.