Internal Developer Platforms (IDPs)

An Internal Developer Platform (IDP) is a layer of tooling and automation that sits between developers and the underlying infrastructure. It's the concrete implementation of platform engineering principles.

IDP Architecture

A well-designed IDP has five core layers:

┌─────────────────────────────────────────────────────────┐
│                    DEVELOPER PORTAL                      │
│              (Backstage, Port, Cortex)                   │
│    ┌──────────┬──────────┬──────────┬──────────┐        │
│    │ Catalog  │ Templates│ TechDocs │ Plugins  │        │
│    └──────────┴──────────┴──────────┴──────────┘        │
├─────────────────────────────────────────────────────────┤
│                  SELF-SERVICE LAYER                      │
│    ┌──────────────────────────────────────────┐         │
│    │ Infrastructure Claims • App Deployments  │         │
│    │ Environment Requests • Secret Management │         │
│    └──────────────────────────────────────────┘         │
├─────────────────────────────────────────────────────────┤
│                    GITOPS LAYER                          │
│    ┌──────────────────────────────────────────┐         │
│    │    ArgoCD • Flux • Git Repositories      │         │
│    └──────────────────────────────────────────┘         │
├─────────────────────────────────────────────────────────┤
│              INFRASTRUCTURE PROVISIONING                 │
│    ┌──────────────────────────────────────────┐         │
│    │  Crossplane • Terraform • Cloud APIs     │         │
│    └──────────────────────────────────────────┘         │
├─────────────────────────────────────────────────────────┤
│                  KUBERNETES LAYER                        │
│    ┌──────────────────────────────────────────┐         │
│    │   Clusters • Namespaces • Resources      │         │
│    └──────────────────────────────────────────┘         │
└─────────────────────────────────────────────────────────┘

IDP Components Specification

Here's a detailed specification of each component:

# IDP Architecture Specification
apiVersion: platform.io/v1
kind: InternalDeveloperPlatform
metadata:
  name: acme-platform
spec:

  # Layer 1: Developer Portal
  developerPortal:
    tool: backstage
    features:
      - serviceCatalog: true
      - softwareTemplates: true
      - techDocs: true
      - searchEnabled: true
    plugins:
      - kubernetes
      - github
      - pagerduty
      - prometheus

  # Layer 2: Self-Service
  selfService:
    capabilities:
      - type: "infrastructure"
        provider: "crossplane"
        resources:
          - databases
          - caches
          - queues
          - storage
      - type: "environments"
        provider: "vcluster"
        options:
          - dev
          - staging
          - preview
      - type: "secrets"
        provider: "vault"

  # Layer 3: GitOps
  gitops:
    tool: argocd
    repositories:
      - type: "infrastructure"
        path: "infra/"
      - type: "applications"
        path: "apps/"
    syncPolicy:
      automated: true
      selfHeal: true

  # Layer 4: Infrastructure
  infrastructure:
    provisioner: crossplane
    providers:
      - aws
      - gcp
    compositions:
      - AppDatabase
      - AppCache
      - AppQueue

  # Layer 5: Kubernetes
  kubernetes:
    clusters:
      - name: "production"
        provider: "eks"
      - name: "staging"
        provider: "eks"
    policies:
      - opa-gatekeeper
      - kyverno

Self-Service Capabilities

The power of an IDP is in self-service. Developers should be able to:

Capability	Traditional	With IDP
Create new service	File ticket, wait 2-3 days	Use template, 5 minutes
Request database	File ticket, wait 1 week	Claim resource, 10 minutes
Deploy to staging	Ask DevOps, wait hours	Push to Git, automatic
Get logs/metrics	Ask SRE for access	Self-service dashboards
Create preview env	Not available	One-click creation

# Example: Developer self-service workflow
developer_workflow:

  step1_create_service:
    action: "Use Backstage template"
    input: "Service name, owner, language"
    output: "Git repo, CI/CD pipeline, catalog entry"
    time: "5 minutes"

  step2_request_database:
    action: "Submit Crossplane claim"
    input: "Database type, size"
    output: "RDS instance, connection string in Vault"
    time: "10 minutes"

  step3_deploy:
    action: "Merge to main"
    input: "Code changes"
    output: "ArgoCD deploys to staging"
    time: "Automatic"

  step4_promote_production:
    action: "Create release tag"
    input: "Version number"
    output: "Production deployment"
    time: "5 minutes"

IDP Maturity Levels

Organizations progress through maturity levels:

Level 0: Ad-hoc
├─ No platform team
├─ Every team manages own infra
└─ Tribal knowledge

Level 1: Standardized
├─ Central CI/CD pipelines
├─ Shared Kubernetes clusters
└─ Basic documentation

Level 2: Self-Service
├─ Developer portal (Backstage)
├─ Software templates
└─ Some infrastructure self-service

Level 3: Automated
├─ Full GitOps workflow
├─ Crossplane for all infra
└─ Policy-as-code enforcement

Level 4: Optimized
├─ AI-assisted operations
├─ Predictive scaling
└─ Cost optimization automation

IDP Success Criteria

An IDP is successful when:

success_criteria:

  developer_experience:
    - "New developers productive in < 1 day"
    - "First deployment in < 1 hour"
    - "No infrastructure tickets for routine tasks"

  operational_efficiency:
    - "90%+ deployments are automated"
    - "MTTR < 30 minutes"
    - "Zero-touch infrastructure provisioning"

  security_compliance:
    - "100% of deployments pass policy checks"
    - "Secrets never in Git"
    - "Audit trail for all changes"

  cost_optimization:
    - "Resource utilization > 60%"
    - "Automatic cleanup of unused resources"
    - "Cost visibility per team/service"

In the next lesson, we'll explore golden paths and paved roads—the opinionated workflows that make self-service powerful. :::