The concept of Internal Developer Platforms is compelling: give developers self-service access to infrastructure, standardised deployment pipelines, and a unified view of their services. The reality is that most IDP initiatives fail — not because the technology is wrong, but because the platform is built for the platform team's idea of what developers need, not what developers actually need.
Here's how to build an IDP that teams adopt willingly.
What an IDP Provides
An IDP is a set of tools, services, and workflows — curated and maintained by a platform team — that reduces the cognitive load on development teams by abstracting infrastructure and operational complexity.
What it is NOT:
- A ticket system where developers request infrastructure
- A portal that wraps existing tools with a new UI
- A mandate without value
- A replacement for understanding your infrastructure
What it IS:
- Self-service infrastructure provisioning
- Standardised, opinionated deployment workflows
- A service catalog for discovery and ownership
- Built-in observability for every service
- Security and compliance by default
Reference Architecture
┌──────────────────────────────────────────────────────┐
│ Developer Portal (Backstage) │
│ ┌─────────┐ ┌──────────┐ ┌─────────┐ ┌──────────┐ │
│ │ Service │ │ Software │ │ TechDocs│ │ Plugins │ │
│ │ Catalog │ │Templates │ │ │ │(CI/CD, │ │
│ │ │ │ │ │ │ │monitoring)│ │
│ └────┬─────┘ └────┬─────┘ └────┬────┘ └────┬─────┘ │
└───────┼─────────────┼───────────┼───────────┼────────┘
│ │ │ │
┌───────▼─────────────▼───────────▼───────────▼────────┐
│ Orchestration Layer │
│ ┌────────────┐ ┌───────────┐ ┌────────────────────┐ │
│ │ Crossplane/ │ │ ArgoCD/ │ │ Policy Engine │ │
│ │ Terraform │ │ Flux │ │ (OPA/Kyverno) │ │
│ └─────┬──────┘ └─────┬─────┘ └────────┬───────────┘ │
└────────┼──────────────┼────────────────┼─────────────┘
│ │ │
┌────────▼──────────────▼────────────────▼─────────────┐
│ Infrastructure │
│ Kubernetes │ Cloud Resources │ Databases │ Monitoring │
└──────────────────────────────────────────────────────┘
Building the IDP: Start Small
Phase 1: Service Catalog (Month 1-2)
Start with visibility. Deploy Backstage and register all existing services.
What developers get:
- A single place to find any service, its owner, its documentation, and its APIs
- Ownership clarity (who owns this service?)
- Documentation discovery (where are the docs for the payments API?)
Why this works first: It's immediately useful, requires no workflow changes from developers, and builds trust in the platform.
Phase 2: Golden Path Templates (Month 2-4)
Create software templates for the most common service types. When a developer creates a new service, they get:
- Pre-configured repository with CI/CD pipeline
- Standard project structure
- Monitoring and alerting configured
- Security scanning enabled
- Database provisioning (if needed)
- Service registered in the catalog automatically
Start with 2-3 templates:
- Backend API service (Node.js/Python/.NET)
- Frontend application (React/Next.js)
- Background worker / event processor
Phase 3: Environment Management (Month 4-6)
Self-service environment creation is typically the highest-value capability.
What developers get:
- Create preview environments per pull request
- Spin up staging environments on demand
- Environment parity with production (same configuration, same services)
Technology: Kubernetes namespaces, Crossplane for cloud resources, ArgoCD for deployment.
Phase 4: Infrastructure Self-Service (Month 6-9)
Developers can provision infrastructure (databases, caches, message queues, storage) through the portal or declarative configuration, without filing tickets.
Implementation: Crossplane resource claims or Terraform modules exposed through Backstage templates. Developer requests are translated into infrastructure resources with security, networking, and cost controls applied automatically.
Phase 5: Observability Integration (Month 9-12)
Built-in monitoring, logging, and alerting for every service deployed through the platform.
What developers get:
- Pre-configured dashboards per service (latency, error rate, throughput)
- Centralised log access
- Alert templates that can be customised
- Distributed tracing across services
Adoption Strategy
Rule 1: Make It Better, Not Mandatory
If the platform is genuinely easier than the alternative, developers will adopt it voluntarily. If you have to mandate it, the platform isn't good enough yet.
Rule 2: Start with Friendly Teams
Find 2-3 development teams who are early adopters. Work closely with them to refine the platform before broader rollout.
Rule 3: Measure and Show Value
Track the metrics that matter to developers: time to first deployment, time to provision infrastructure, time to resolve incidents. Show the improvement.
Rule 4: Listen Actively
Conduct monthly developer surveys. Hold office hours where developers can ask questions and provide feedback. The platform roadmap should be driven by developer pain points.
Rule 5: Accept Escape Hatches
The platform should handle 80% of use cases. For the other 20%, provide an escape hatch — a way for teams to do things their own way while still integrating with the platform's observability and security layers.
Common Pitfalls
- Big bang launch. Building for 12 months before releasing anything. Ship incremental value every 2-4 weeks.
- Technology-first thinking. Choosing Backstage, Crossplane, and ArgoCD before understanding what developers actually need.
- No product ownership. Treating the platform as an infrastructure project rather than a product with users.
- Ignoring existing tools. Developers have workflows they've built over years. Integrate with them before replacing them.
- Under-investing in documentation. The platform is only as useful as its documentation.
An Internal Developer Platform is the highest-leverage investment in engineering productivity. If you're building an IDP or evaluating platform engineering for your organisation, let's talk.