Internal Developer Platform

Comprehensive guide to designing and building Internal Developer Platforms (IDPs) that improve developer productivity and experience.

When to Use This Skill

• Designing an Internal Developer Platform
• Building or restructuring platform teams
• Improving developer experience (DevEx)
• Evaluating platform technologies (Backstage, Port, etc.)
• Creating self-service capabilities for developers
• Measuring platform adoption and success

Platform Engineering Fundamentals

What is an Internal Developer Platform?

Internal Developer Platform (IDP):
A layer on top of infrastructure that provides self-service
capabilities to development teams while maintaining governance.

┌─────────────────────────────────────────────────────────────┐
│                    DEVELOPERS                                │
│  ┌─────────┐  ┌─────────┐  ┌─────────┐  ┌─────────┐       │
│  │ Team A  │  │ Team B  │  │ Team C  │  │ Team D  │       │
│  └────┬────┘  └────┬────┘  └────┬────┘  └────┬────┘       │
│       │            │            │            │              │
│       └────────────┴─────┬──────┴────────────┘              │
│                          │                                   │
│  ┌───────────────────────┴───────────────────────────────┐  │
│  │              INTERNAL DEVELOPER PLATFORM               │  │
│  │  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │  │
│  │  │ Service  │ │ Template │ │ Self-    │ │ Docs &   │ │  │
│  │  │ Catalog  │ │ Library  │ │ Service  │ │ Discovery│ │  │
│  │  └──────────┘ └──────────┘ └──────────┘ └──────────┘ │  │
│  └───────────────────────────────────────────────────────┘  │
│                          │                                   │
│  ┌───────────────────────┴───────────────────────────────┐  │
│  │                  INFRASTRUCTURE                        │  │
│  │  Kubernetes │ Cloud │ CI/CD │ Observability │ Security │  │
│  └───────────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────────┘

Key Value Propositions:
├── Self-service: Developers can provision without tickets
├── Standardization: Consistent patterns across teams
├── Guardrails: Security and compliance built-in
├── Visibility: Centralized service catalog and docs
└── Efficiency: Reduce cognitive load on developers

Platform vs Infrastructure

Infrastructure Team (Traditional):
- Ticket-based requests
- Manual provisioning
- Bespoke solutions per team
- Ops handles deployments
- Documentation scattered

Platform Team (Modern):
- Self-service capabilities
- Automated provisioning
- Standardized templates
- Developers own deployments
- Centralized documentation

Key Shift:
"You Build It, You Run It" + "Platform Handles the How"

Platform Core Components

Service Catalog

Service Catalog:
Centralized registry of all services with ownership, docs, and metadata.

┌─────────────────────────────────────────────────────────────┐
│                    SERVICE CATALOG                           │
├─────────────────────────────────────────────────────────────┤
│                                                              │
│  ┌─────────────────────────────────────────────────────────┐ │
│  │ Payment Service                                [API]     │ │
│  │ Owner: Payments Team     │ Tier: Critical              │ │
│  │ Tech: Node.js, PostgreSQL │ Dependencies: 4            │ │
│  │ [Docs] [API Spec] [Runbook] [Alerts] [Deploy]          │ │
│  └─────────────────────────────────────────────────────────┘ │
│                                                              │
│  ┌─────────────────────────────────────────────────────────┐ │
│  │ User Service                                 [Backend]   │ │
│  │ Owner: Identity Team     │ Tier: High                  │ │
│  │ Tech: Go, MongoDB        │ Dependencies: 2             │ │
│  │ [Docs] [API Spec] [Runbook] [Alerts] [Deploy]          │ │
│  └─────────────────────────────────────────────────────────┘ │
│                                                              │
│  Service Metadata:                                           │
│  ├── Owner team and contacts                                │
│  ├── Technical stack                                        │
│  ├── Service tier/criticality                               │
│  ├── Dependencies (upstream/downstream)                     │
│  ├── API specifications                                     │
│  ├── Documentation links                                    │
│  ├── Deployment information                                 │
│  └── Observability dashboards                               │
└─────────────────────────────────────────────────────────────┘

Template Library

Template Library:
Pre-built templates for common patterns that encode best practices.

Template Categories:
├── Application Templates
│   ├── REST API (Go, Node.js, .NET, Python)
│   ├── GraphQL Service
│   ├── gRPC Service
│   ├── Event Consumer
│   ├── Scheduled Job
│   └── Frontend (React, Vue, Angular)
│
├── Infrastructure Templates
│   ├── Database (PostgreSQL, MySQL, MongoDB)
│   ├── Cache (Redis, Memcached)
│   ├── Message Queue (Kafka, RabbitMQ)
│   └── Storage (S3, GCS)
│
└── Integration Templates
    ├── Third-party API client
    ├── Authentication flow
    └── Webhook handler

Template Contents:
┌─────────────────────────────────────────────────────────────┐
│ Template: node-rest-api                                      │
├─────────────────────────────────────────────────────────────┤
│ ├── src/                    │ Application code              │
│ ├── tests/                  │ Test setup                    │
│ ├── Dockerfile              │ Container image               │
│ ├── helm/                   │ Kubernetes deployment         │
│ ├── .github/workflows/      │ CI/CD pipelines               │
│ ├── docs/                   │ Documentation templates       │
│ ├── catalog-info.yaml       │ Backstage registration        │
│ └── terraform/              │ Infrastructure as Code        │
│                                                              │
│ Built-in:                                                    │
│ ✓ Health checks             ✓ Structured logging            │
│ ✓ OpenTelemetry tracing     ✓ Prometheus metrics           │
│ ✓ Security headers          ✓ Input validation             │
│ ✓ Error handling            ✓ API documentation            │
└─────────────────────────────────────────────────────────────┘

Self-Service Portal

Self-Service Capabilities:
Actions developers can perform without tickets or approvals.

┌─────────────────────────────────────────────────────────────┐
│                  SELF-SERVICE PORTAL                         │
├─────────────────────────────────────────────────────────────┤
│                                                              │
│  Create New Service     [5 min setup, no tickets]           │
│  ├── Choose template                                        │
│  ├── Configure options                                      │
│  ├── Generate repository                                    │
│  ├── Create CI/CD pipeline                                  │
│  ├── Provision infrastructure                               │
│  └── Register in catalog                                    │
│                                                              │
│  Common Self-Service Actions:                               │
│  ┌────────────────┬────────────────┬────────────────┐      │
│  │ Environments   │ Databases      │ Secrets        │      │
│  │ ├── Create env │ ├── Provision  │ ├── Create     │      │
│  │ ├── Clone env  │ ├── Scale      │ ├── Rotate     │      │
│  │ └── Destroy    │ └── Backup     │ └── Access     │      │
│  └────────────────┴────────────────┴────────────────┘      │
│  ┌────────────────┬────────────────┬────────────────┐      │
│  │ Deployments    │ Domains        │ Access         │      │
│  │ ├── Deploy     │ ├── Request    │ ├── Request    │      │
│  │ ├── Rollback   │ ├── Configure  │ ├── Review     │      │
│  │ └── Promote    │ └── Cert       │ └── Audit      │      │
│  └────────────────┴────────────────┴────────────────┘      │
│                                                              │
│  Guardrails (automatic):                                    │
│  ✓ Security scanning        ✓ Compliance checks            │
│  ✓ Cost limits              ✓ Naming conventions           │
│  ✓ Resource quotas          ✓ Approval workflows           │
└─────────────────────────────────────────────────────────────┘

Platform Team Structure

Team Topologies

Platform Team Types:

1. Enabling Team (Recommended Start)
   Purpose: Help stream-aligned teams adopt platform
   Size: 3-5 people
   Activities:
   ├── Pair programming with product teams
   ├── Create documentation and guides
   ├── Gather feedback and requirements
   └── Provide training and support

2. Platform Team (Mature)
   Purpose: Build and maintain the platform
   Size: 5-15 people (scale with org)
   Activities:
   ├── Build self-service capabilities
   ├── Maintain templates and tooling
   ├── Define and enforce standards
   └── Operate platform infrastructure

3. Complicated Subsystem Team (Specialized)
   Purpose: Handle complex technical domains
   Size: 3-7 people per domain
   Examples:
   ├── Data platform team
   ├── ML platform team
   └── Security platform team

Team Interaction:
┌─────────────────────────────────────────────────────────────┐
│                                                              │
│  ┌──────────────┐         ┌──────────────┐                 │
│  │ Stream-      │◄───────►│ Platform     │                 │
│  │ Aligned Team │ X-as-a- │ Team         │                 │
│  └──────────────┘ Service └──────────────┘                 │
│         │                        │                          │
│         │ Collaboration          │ Facilitation            │
│         │                        │                          │
│         ▼                        ▼                          │
│  ┌──────────────┐         ┌──────────────┐                 │
│  │ Complicated  │◄───────►│ Enabling     │                 │
│  │ Subsystem    │ Service │ Team         │                 │
│  └──────────────┘         └──────────────┘                 │
│                                                              │
└─────────────────────────────────────────────────────────────┘

Platform Team Skills

Platform Team Competencies:

Technical:
├── Kubernetes and container orchestration
├── Infrastructure as Code (Terraform, Pulumi)
├── CI/CD pipeline design
├── API design and development
├── Observability tooling
├── Security engineering
└── Cloud platforms (AWS, GCP, Azure)

Product:
├── Developer experience research
├── User journey mapping
├── Metrics and analytics
├── Documentation writing
└── Training and enablement

Organizational:
├── Stakeholder management
├── Communication skills
├── Change management
└── Technical leadership

Platform Technology Choices

Backstage (Spotify)

Backstage:
Open-source developer portal framework by Spotify.

Core Features:
├── Service Catalog (software component registry)
├── Software Templates (scaffolding)
├── TechDocs (docs-as-code)
├── Search (unified search across everything)
└── Plugins (extensible ecosystem)

Architecture:
┌─────────────────────────────────────────────────────────────┐
│                     BACKSTAGE                                │
│  ┌──────────────────────────────────────────────────────┐   │
│  │                    Frontend (React)                    │   │
│  │  ├── Catalog UI    ├── Templates UI    ├── Plugins   │   │
│  └──────────────────────────────────────────────────────┘   │
│                           │                                  │
│  ┌──────────────────────────────────────────────────────┐   │
│  │                    Backend (Node.js)                   │   │
│  │  ├── Catalog API   ├── Auth          ├── Plugin APIs │   │
│  └──────────────────────────────────────────────────────┘   │
│                           │                                  │
│  ┌──────────────────────────────────────────────────────┐   │
│  │                    Integrations                        │   │
│  │  ├── GitHub     ├── Kubernetes    ├── CI/CD          │   │
│  │  ├── PagerDuty  ├── Prometheus    ├── Custom         │   │
│  └──────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────┘

Catalog Entity:
# catalog-info.yaml
apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: payment-service
  description: Handles payment processing
  annotations:
    github.com/project-slug: org/payment-service
    backstage.io/techdocs-ref: dir:.
spec:
  type: service
  lifecycle: production
  owner: payments-team
  system: payments
  dependsOn:
    - component:user-service
  providesApis:
    - payment-api

Alternative Platforms

Platform Options Comparison:

| Platform | Type | Strengths | Considerations |
|----------|------|-----------|----------------|
| Backstage | OSS | Extensible, active community | Requires customization |
| Port | Commercial | Quick setup, polished UI | Vendor lock-in |
| Cortex | Commercial | SRE focused, scorecards | Enterprise pricing |
| OpsLevel | Commercial | Service maturity | Smaller ecosystem |
| Roadie | Managed | Hosted Backstage | Less control |

Decision Factors:
├── Build vs Buy tolerance
├── Customization requirements
├── Team capacity for maintenance
├── Integration needs
├── Budget constraints
└── Timeline expectations

Developer Experience Metrics

DORA Metrics

DORA (DevOps Research and Assessment) Metrics:

1. Deployment Frequency
   How often you deploy to production
   ├── Elite: Multiple times per day
   ├── High: Weekly to monthly
   ├── Medium: Monthly to every 6 months
   └── Low: Every 6+ months

2. Lead Time for Changes
   Time from code commit to production
   ├── Elite: < 1 hour
   ├── High: 1 day to 1 week
   ├── Medium: 1 week to 1 month
   └── Low: 1 month to 6 months

3. Mean Time to Recovery (MTTR)
   Time to recover from production failure
   ├── Elite: < 1 hour
   ├── High: < 1 day
   ├── Medium: < 1 week
   └── Low: 1 week to 1 month

4. Change Failure Rate
   Percentage of deployments causing failure
   ├── Elite: 0-15%
   ├── High: 16-30%
   ├── Medium: 31-45%
   └── Low: 46-60%

Platform-Specific Metrics

Platform Success Metrics:

Adoption:
├── % of services in catalog
├── % of teams using templates
├── Self-service usage rate
├── Portal active users
└── Template utilization

Efficiency:
├── Time to first deployment (new service)
├── Time to provision infrastructure
├── Ticket reduction rate
├── Toil automation percentage
└── Developer time saved

Satisfaction:
├── Developer NPS
├── Platform satisfaction surveys
├── Support ticket volume
├── Documentation usefulness
└── Onboarding feedback

Quality:
├── Template adoption vs custom builds
├── Security compliance rate
├── Standards adherence
└── Incident rate for platform-built services

Implementation Roadmap

Phased Approach

Phase 1: Foundation (3-6 months)
├── Service catalog (inventory what exists)
├── Basic documentation site
├── Initial template (1-2 golden paths)
├── Platform team formation
└── Metrics baseline

Phase 2: Self-Service (6-12 months)
├── Template library expansion
├── Self-service provisioning
├── CI/CD standardization
├── Developer portal launch
└── Adoption campaigns

Phase 3: Optimization (12-18 months)
├── Advanced templates
├── Platform APIs
├── Automation expansion
├── Cost optimization
└── Advanced analytics

Phase 4: Ecosystem (18+ months)
├── Plugin ecosystem
├── ML/data platform integration
├── Cross-team collaboration features
├── External developer experience
└── Continuous evolution

Success Criteria Per Phase:
Phase 1: 50% service discovery complete
Phase 2: 70% of new services use templates
Phase 3: 80% self-service capability
Phase 4: Platform is indispensable

Common Anti-Patterns

Platform Anti-Patterns:

1. "Build It and They Will Come"
   ❌ Building features without user research
   ✓ Start with developer interviews and pain points

2. "One Size Fits All"
   ❌ Forcing every team into same workflow
   ✓ Provide flexibility with sensible defaults

3. "Platform as Gatekeeper"
   ❌ Adding friction and approval gates
   ✓ Enable self-service with guardrails

4. "Technical Purity"
   ❌ Choosing tech for platform team excitement
   ✓ Choose what solves developer problems

5. "Big Bang Launch"
   ❌ Building for 2 years before releasing
   ✓ Iterate quickly with early adopters

6. "Mandates Without Value"
   ❌ Forcing adoption via policy
   ✓ Make platform so good teams want to use it

7. "Documentation Afterthought"
   ❌ Minimal or outdated docs
   ✓ Treat docs as product feature

8. "Ivory Tower Platform"
   ❌ Platform team isolated from users
   ✓ Embed with product teams regularly

Best Practices

Platform Engineering Best Practices:

1. Treat Platform as Product
   ├── Have product owner/manager
   ├── Conduct user research
   ├── Prioritize based on impact
   └── Measure outcomes, not outputs

2. Start with Golden Paths
   ├── Identify most common use cases
   ├── Create templates for those first
   ├── Make golden path easiest choice
   └── Don't block non-golden paths

3. Optimize for Self-Service
   ├── Target <5 minutes for common tasks
   ├── Eliminate manual approvals where safe
   ├── Provide escape hatches when needed
   └── Clear error messages and guidance

4. Build Community
   ├── Developer advocates/champions
   ├── Office hours and support channels
   ├── Contribution guidelines
   └── Celebrate platform wins

5. Measure Everything
   ├── Adoption metrics
   ├── Developer satisfaction
   ├── Time savings
   └── Platform reliability

6. Iterate Rapidly
   ├── Ship early, improve often
   ├── Gather feedback continuously
   ├── Deprecate gracefully
   └── Communicate changes clearly

Related Skills

• golden-paths

  - Designing standardized development workflows

• self-service-infrastructure

  - Infrastructure self-service patterns

• slo-sli-error-budget

  - Platform reliability targets

• observability-patterns

  - Platform observability