Internal Developer Platform (IDP) Part 3 - Principles and Pillars
Principles
"Those are my principles, and if you don’t like them… well, I have others."
In Platform Engineering, "Groucho Principles" are a major pitfall. If a team defines a principle like "Self-Service" but then immediately adds a manual approval process because one manager was worried about costs, they have followed Groucho’s lead.
Engineering principles are the operational and technical guidelines that govern how the platform engineering team builds and maintains the platform. They shape the technical attributes of every feature or capability the team delivers.
Here are the principles for this Internal Developer Platform (IDP), categorized by their primary impact:
The "Golden Path" Principles
- Roads over Fences
Focus on making the "right" way the easiest way. Don’t block developers from using custom tools; instead, make the platform-supported path so attractive that they want to use it.
- Opinionated by Default, Flexible by Necessity
The platform should provide sensible defaults for security, scaling, and logging. However, it must provide "escape hatches" for senior engineers with edge-case requirements to avoid becoming a bottleneck.
- Abstraction, Not Hidden Complexity
Expose the "what" (e.g., I need a Postgres DB) and hide the "how" (e.g., VPC peering, IAM roles, subnet tagging). The goal is to reduce cognitive load, not to make the underlying infrastructure a "black box" that is impossible to debug.
The "Developer Experience" Principles
- Self-Service is Non-Negotiable
Any task that can be automated must be available via API or UI without human intervention. If a developer has to "open a ticket" for a standard resource, the platform is failing its core mission.
- Zero-Trust Continuity
Security and compliance shouldn’t be a "final check" at the end of a project. They should be baked into the platform’s templates (Shift-Left), ensuring that every resource provisioned is secure by design.
- Empathy for the End-User (The Developer)
Treat developers like customers. If they find a feature confusing or frustrating, it’s a bug in the platform, not a "lack of training" on the developer’s part.
The "Product Mindset" Principles
- Evolutionary Architecture
Build the platform to be modular. Technical requirements change every 12–18 months; the platform must be able to swap out underlying providers (e.g., moving from one CI tool to another) without breaking the developer’s interface.
- Measure What Matters (DORA & DevEx)
Don’t just track "uptime." Measure the platform’s success by Developer Velocity (lead time for changes) and Developer Satisfaction (Net Promoter Score). If it’s up but nobody uses it, it’s a failure.
- Documentation is a Feature
An undocumented feature does not exist. High-quality, searchable documentation and "getting started" guides are as important as the code that provisions the infrastructure.
The "Operational" Principle
- Automate the Toil Away
The platform team should follow a "SRE mindset": if you have to do something manually twice, automate it the third time. The platform team’s capacity should grow through better automation, not by hiring more "Ops" people.
Pillars
Pillars represent the high-level objectives, desired outcomes, and foundational mindset of the platform. They are outward-facing and define the value the platform is supposed to deliver to the organization and its developers.
A Pillar is a strategic, load-bearing priority that defines what the platform focuses on to achieve its mission. It acts as a structural category of work (e.g., Self-Service Infrastructure or Governance) that organizes the roadmap and provides the boundaries for technical implementation.
The difference between a Pillar and a Principle is simple: A Pillar is what keeps the ceiling from falling on your head, and a Principle is the reason you decided to walk into the building in the first place. Of course, if you’re following the Groucho Marx school of engineering, you’ll just change both the moment the landlord asks for rent.
Treating the Platform as a Product (PaaP)
What it is: The foundational mindset of platform engineering is treating the platform as a dedicated internal product with developers as its primary customers. This approach relies on three main pillars: the platform must be compelling (adopted voluntarily because it provides value, not because of a top-down mandate), self-service, and accessible.
Why it is a pillar: Building a platform in an "ivory tower" without understanding developer workflows often results in a "ghost town" platform that no one uses. Treating the platform as a product ensures you are solving real developer pain points and earning adoption rather than creating resentment through forced mandates.
Self-Service Workflows
What it is: Developers must have the autonomy to provision resources, deploy code, and manage environments independently through automated interfaces, APIs, or developer portals.
Why it is a pillar: Traditional "ticket-ops" models—where developers must file Jira tickets and wait for operations teams to manually approve and provision infrastructure—create bottlenecks. Self-service eliminates these human gatekeepers, preventing developers from losing momentum and context while waiting for access.
Reducing Cognitive Load
What it is: A successful platform "shifts down" or abstracts away underlying infrastructure complexities, such as container orchestration (Kubernetes), cloud networking, and infrastructure provisioning.
Why it is a pillar: The cloud-native era has introduced a sprawl of tools that overwhelm developers. By absorbing this complexity, the platform allows developers to focus on application logic, rather than forcing them to become part-time infrastructure experts.
Pervasive Automation and Infrastructure as Code (IaC)
What it is: Automation is the backbone of the platform, using Infrastructure as Code (IaC) to programmatically manage and configure infrastructure. This includes automating continuous integration and continuous delivery (CI/CD) pipelines, testing, and resource provisioning.
Why it is a pillar: Manual interventions create friction, slow down delivery, and introduce human error. Automation and IaC ensure that deployment patterns remain consistent, repeatable, and version-controlled across all environments, reducing the risk of configuration drift.
Embedded Security, Governance, and Observability
What it is: Security controls, compliance guardrails, and observability tools (such as metrics, logs, and distributed tracing) are "baked into" the foundation of the platform rather than retrofitted at the end of the development cycle.
Why it is a pillar: In older models, security reviews acted as late-stage blockers that delayed releases. Embedding security directly into the platform creates "golden paths" that naturally enforce compliance without sacrificing development speed. Similarly, built-in observability is required so developers can monitor and debug their own services, and so the platform team can track platform health and adoption.
Summary
This post lists the principles and pillars for this project. Principles guide how a team builds a platform, while pillars guide what the platform delivers. They are used to make and reason about architecture and implementation decisions, and tie those back to platform engineering.
The next post covers the overall bootstrapping and testing approach for the Kubernetes-based self-contained IDP.
This post and the underlying code was written and developed in collaboration with several AIs.