How Internal Developer Platforms Are Actually Built, Not Just Diagrammed
Internal Developer Platforms (IDPs) have become one of the most talked-about ideas in modern DevOps and platform engineering. Architecture diagrams make them look deceptively simple: a developer portal on top, Kubernetes and cloud infrastructure underneath, with CI/CD, GitOps, security, and observability connected in the middle.
But building an IDP that developers actually use is a very different challenge.
An IDP is not simply a Backstage installation, a collection of Terraform modules, or a polished dashboard. It is a combination of infrastructure, automation, workflows, guardrails, and developer experience designed to make common engineering tasks easier and more consistent. (Google Cloud)
The real question is: How do you go from an architecture diagram to a working platform?
This article breaks down what that process actually looks like.
What Is an Internal Developer Platform?
An Internal Developer Platform is a self-service layer that sits between developers and the underlying infrastructure they need to build and operate applications.
Instead of asking developers to understand every detail of Kubernetes, Terraform, cloud networking, IAM, CI/CD, secrets management, and observability, the platform provides supported workflows that hide unnecessary complexity.
For example, a developer might select:
Create a new production-ready Node.js service
Behind that simple request, the platform could automatically:
Create a Git repository.
Generate the application structure.
Configure CI.
Build and publish a container image.
Create infrastructure resources.
Configure deployment manifests.
Register the service in a catalog.
Apply security policies.
Configure monitoring.
Deploy the application through GitOps.
The developer sees a simple workflow. The platform team manages the complexity underneath.
That is the fundamental value of an IDP: turning infrastructure complexity into reusable developer workflows.
The Diagram Is Not the Platform
One of the biggest mistakes organizations make is starting with architecture diagrams instead of developer problems.
A typical diagram might look like this:
Developer
|
v
Developer Portal
|
+---------+---------+
| |
CI/CD GitOps
| |
+---------+---------+
|
Kubernetes
|
+-----------+-----------+
| | |
Cloud Database Observability
It looks impressive.
But it doesn't answer the questions developers actually care about:
How do I create a service?
How do I get a database?
How do I deploy to staging?
How do I get production access?
Where do I find logs?
Who owns this service?
How do I rotate secrets?
What happens if my deployment fails?
A useful IDP starts by answering those questions.
Platform engineering is essentially about treating the platform as a product, with developers as its customers. (Google Cloud)
Step 1: Start With Developer Pain, Not Tools
Before selecting Backstage, Kubernetes, Terraform, Crossplane, Argo CD, or any other technology, platform teams should understand where developers are losing time.
For example, suppose developers currently need to submit tickets for:
New repositories
Kubernetes namespaces
Cloud resources
Databases
DNS records
Deployment pipelines
Monitoring
Production access
Don't try to automate everything at once.
Look for repetitive workflows that happen frequently and create significant friction.
A simple prioritization model is:
Frequency × Time Consumed × Developer Friction
If creating a new service takes two days and happens 30 times a month, that is probably a better first candidate than an obscure infrastructure workflow used twice a year.
Step 2: Build One Golden Path
The heart of a useful IDP is the golden path.
A golden path is the organization's recommended and supported way of accomplishing a common engineering task. It should provide sensible defaults without preventing developers from taking alternative approaches when necessary. (Open Empower)
For example:
Golden path: Create a new microservice
The developer provides:
Service name: payments-api
Language: Go
Database: PostgreSQL
Environment: Production
The platform handles:
Repository
↓
Application template
↓
CI pipeline
↓
Container build
↓
Security scanning
↓
Infrastructure provisioning
↓
GitOps configuration
↓
Deployment
↓
Monitoring
↓
Service catalog
This is much more valuable than simply giving developers a portal containing links to 20 different tools.
Step 3: Build the Automation Layer
This is where an IDP becomes real.
The portal may be the visible part, but automation is the engine underneath.
A practical platform can connect several layers:
| Layer | Typical responsibility |
|---|---|
| Developer portal | Discovery and self-service |
| Templates | Standardize application creation |
| Git | Source and configuration management |
| CI/CD | Build, test, scan, package |
| IaC | Provision infrastructure |
| GitOps | Manage deployments |
| Kubernetes | Run workloads |
| Secrets | Protect credentials |
| Observability | Monitor applications |
| Policy | Enforce security and compliance |
The important point is that the IDP doesn't necessarily replace these tools.
Instead, it connects them into a coherent developer experience.
An IDP is often the orchestration layer that turns existing infrastructure and tools into repeatable workflows. (Internal Developer Platform)
Step 4: Create Reusable Templates
Templates are one of the easiest ways to convert platform standards into developer workflows.
Imagine a company has three supported application patterns:
Node.js API
Python API
Java Spring Boot Service
Instead of asking every developer to configure:
Docker
CI
Kubernetes
monitoring
security scanning
deployment
documentation
the platform team creates templates containing those defaults.
A new service might automatically receive:
service/
├── src/
├── Dockerfile
├── tests/
├── deployment/
├── .github/
│ └── workflows/
├── docs/
└── catalog-info.yaml
The developer focuses on application logic rather than repeatedly rebuilding the same delivery infrastructure.
Step 5: Put Infrastructure Behind APIs and Automation
Developers shouldn't necessarily need to know how the platform creates infrastructure.
For example:
Developer
|
| "I need PostgreSQL"
v
Platform API
|
v
Infrastructure Automation
|
v
Cloud Provider
|
v
Managed PostgreSQL
Terraform, Crossplane, or other infrastructure automation systems can provide the implementation layer.
The platform should expose the intent, rather than forcing developers to understand every infrastructure implementation detail.
This is one of the major distinctions between an IDP and simply giving developers access to a cloud console.
Step 6: Add Guardrails Instead of Gates
Security is where poorly designed platforms often become frustrating.
A traditional approach might be:
Developer requests production access → Security reviews ticket → Operations approves → Developer waits.
A platform-oriented approach tries to automate the rules.
For example:
Developer deploys
↓
Automated policy checks
↓
┌─────┴─────┐
| |
Pass Fail
| |
Deploy Explain
Issue
The platform can enforce requirements such as:
Approved container images
Required resource limits
Encryption
Authentication
Network policies
Vulnerability scanning
Required monitoring
Approved cloud regions
The goal isn't to remove governance.
It is to embed governance into the workflow so that developers don't need to repeatedly navigate manual approval processes.
Step 7: Connect CI/CD and GitOps
An IDP becomes much more powerful when application creation and application delivery are connected.
A typical flow might look like:
Developer
|
v
Create Service
|
v
Git Repository
|
v
CI Pipeline
|
+--> Tests
|
+--> Security Scan
|
+--> Container Build
|
v
Container Registry
|
v
GitOps Configuration
|
v
Kubernetes
The important part is that the developer doesn't have to manually connect every step.
The platform provides the paved road.
Step 8: Make Observability Part of the Default
A common mistake is treating observability as something developers configure after deployment.
A better IDP makes it part of the service template.
When a developer creates a service, the platform can automatically configure:
Application logs
Metrics
Health checks
Dashboards
Alerts
Tracing
Service ownership
That means a newly created service isn't just deployed—it is operationally visible from day one.
A service catalog can also show ownership, dependencies, APIs, and operational information in one place.
Step 9: Build the Developer Portal Last—or at Least Don't Start There
Tools such as Backstage can provide a useful front door for an IDP, including service catalogs, documentation, templates, and developer workflows.
But a portal alone isn't an IDP.
Think about it this way:
Portal = Front Door
IDP = Everything Behind the Door
The platform might include:
Developer Portal
|
+--------------+--------------+
| | |
Templates Catalog Docs
|
v
Automation
|
+----+----+
| |
IaC GitOps
| |
+----+----+
|
Kubernetes / Cloud
|
Observability
Security
Secrets
This distinction matters because organizations can spend months building a beautiful portal while the underlying workflows remain manual.
Step 10: Measure Whether Developers Actually Use It
A platform isn't successful because it contains 50 integrations.
It is successful when developers voluntarily use it because it makes their jobs easier.
Useful metrics include:
Platform adoption
What percentage of services use the supported platform workflows?
Lead time
How long does it take to go from creating a service to its first deployment?
Deployment frequency
Are teams deploying more frequently?
Developer satisfaction
Do developers actually find the platform useful?
Self-service rate
How many previously manual requests can developers complete themselves?
Failure rate
Are platform-provided workflows more reliable than manual processes?
These metrics help distinguish a functioning platform from an impressive architecture diagram.
Common IDP Mistakes
1. Building Everything at Once
Trying to create a universal platform from day one usually creates a huge engineering project.
Start with one workflow.
2. Choosing Tools Before Problems
Don't begin with:
"Let's install Backstage."
Begin with:
"What developer workflow currently takes three days?"
Then determine which technologies can solve it.
3. Making the Platform Mandatory Too Early
If developers are forced onto a platform that is slower than their existing workflow, they'll find ways around it.
The golden path should be attractive because it is easier, not merely because it is mandatory.
4. Creating Too Many Golden Paths
Golden paths should reduce choices, not create another menu of endless options.
Start with the most common patterns.
5. Ignoring Platform UX
Platform engineering is still engineering, but the users are developers.
If the workflow is confusing, slow, or poorly documented, adoption will suffer.
Where DevOps Training Fits Into Platform Engineering
Building an IDP requires more than knowing a single platform tool.
Engineers need to understand the principles connecting:
Continuous integration
Continuous delivery
Infrastructure as code
Containers
Kubernetes
Cloud infrastructure
Monitoring
Security
Automation
Version control
That is why strong DevOps training can be valuable for engineers moving toward platform engineering.
The goal isn't simply to learn another collection of tools. It is to understand how software delivery, infrastructure, automation, and operations fit together, which is exactly the foundation needed when designing internal developer platforms.
The Real Architecture of an IDP
If you strip away the marketing terminology, a practical IDP can be viewed as five connected layers:
┌─────────────────────────────────────┐
│ Developer Experience │
│ Portal / CLI / APIs / Docs │
├─────────────────────────────────────┤
│ Golden Paths │
│ Templates / Workflows / Defaults │
├─────────────────────────────────────┤
│ Automation │
│ CI/CD / IaC / GitOps / APIs │
├─────────────────────────────────────┤
│ Platform Foundation │
│ Kubernetes / Cloud / Networking │
├─────────────────────────────────────┤
│ Governance & Operations │
│ Security / Policy / Observability │
└─────────────────────────────────────┘
The portal is only one layer.
The real platform is the combination of automation + infrastructure + standards + developer experience.
Final Thoughts
The hardest part of building an Internal Developer Platform isn't choosing between Backstage, Terraform, Kubernetes, Argo CD, Crossplane, or another tool.
The hardest part is understanding what developers actually need and turning those needs into reliable, self-service workflows.
A good IDP doesn't try to expose every capability of the underlying infrastructure. It deliberately hides complexity.
The best platforms make the right thing easy:
Create a service → get the right defaults → pass automated checks → deploy → observe → operate.
That's the difference between an IDP that looks impressive in an architecture presentation and one that developers actually use every day.