Platform Engineering & Internal Developer Platforms

Platform engineering exists because DevOps at scale doesn’t work by giving every team raw access to Terraform, Kubernetes, and CI/CD pipelines. The cognitive load is too high. Teams spend 40% of their time on infrastructure instead of building features. Platform engineering creates “golden paths” — self-service, opinionated workflows that let developers deploy without becoming infrastructure experts.

This guide covers how to build an Internal Developer Platform (IDP) that teams actually want to use.

What a Platform Provides

Developer Experience Layer
┌──────────────────────────────────────────────┐
│  Developer Portal (Backstage, Port, Cortex)   │
│  • Service catalog  • Documentation           │
│  • Templates        • Scorecard compliance     │
└───────────────────────┬──────────────────────┘
                        ↓
Platform Capabilities Layer
┌───────────┬───────────┬───────────┬──────────┐
│ Deploy    │ Observe   │ Secure    │ Data      │
│ • CI/CD   │ • Metrics │ • Secrets │ • DBaaS   │
│ • GitOps  │ • Logs    │ • mTLS   │ • Cache   │
│ • Preview │ • Traces  │ • Scan   │ • Queue    │
└───────────┴───────────┴───────────┴──────────┘
                        ↓
Infrastructure Layer
┌───────────────────────────────────────────────┐
│  Kubernetes │ Cloud Providers │ Terraform/Pulumi │
└───────────────────────────────────────────────┘

Golden Paths

A golden path is the opinionated, supported way to do something:

Example: Creating a New Service

# Golden path template (Backstage scaffolding)
apiVersion: scaffolder.backstage.io/v1beta3
kind: Template
metadata:
  name: new-microservice
  title: Create a New Microservice
  description: Production-ready service with CI/CD, monitoring, and docs
spec:
  type: service
  parameters:
    - title: Service Details
      properties:
        name:
          type: string
          description: Service name (lowercase, hyphens only)
          pattern: "^[a-z][a-z0-9-]*$"
        language:
          type: string
          enum: ["go", "python", "typescript"]
        team:
          type: string
          description: Owning team
        tier:
          type: string
          enum: ["tier-1-critical", "tier-2-important", "tier-3-standard"]
  
  steps:
    - id: scaffold
      action: fetch:template
      input:
        url: ./templates/${{ parameters.language }}
        values:
          name: ${{ parameters.name }}
          team: ${{ parameters.team }}
    
    - id: create-repo
      action: github:create-repo
      input:
        repoUrl: github.com/company/${{ parameters.name }}
    
    - id: create-ci
      action: github-actions:create-workflow
      input:
        template: .github/workflows/${{ parameters.language }}.yml
    
    - id: register-catalog
      action: catalog:register
      input:
        repoContentsUrl: ${{ steps.create-repo.output.repoContentsUrl }}

Result: Developer fills out a form, gets a fully configured repo with CI/CD, Kubernetes manifests, monitoring dashboards, and Backstage catalog entry in under 5 minutes.

Developer Portal (Backstage)

Service Catalog

apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: order-service
  description: Order management microservice
  annotations:
    github.com/project-slug: company/order-service
    pagerduty.com/service-id: PORDER123
    grafana/dashboard-url: https://grafana.internal/d/orders
    sonarqube.org/project-key: order-service
  tags:
    - go
    - grpc
    - tier-1
spec:
  type: service
  lifecycle: production
  owner: team-commerce
  system: commerce-platform
  providesApis:
    - order-api
  consumesApis:
    - inventory-api
    - payment-api
  dependsOn:
    - resource:orders-database
    - resource:orders-cache

Self-Service Infrastructure

What Should Be Self-Service

Capability	Self-Service?	Implementation
Create new service	✅ Yes	Backstage template
Deploy to staging	✅ Yes	CI/CD pipeline
Deploy to production	✅ Yes (with guardrails)	GitOps + automated checks
Provision database	✅ Yes	Terraform module + approval
Create DNS record	✅ Yes	Automated via API
Request cloud account	⚠️ Semi	Approval workflow
Change network rules	❌ No	Security team review
Access production data	❌ No	Formal access request

Measuring Success

DORA Metrics

Metric	Definition	Elite	High	Medium	Low
Deployment Frequency	How often you deploy	On-demand (multiple/day)	Weekly-monthly	Monthly-biannual	Biannual+
Lead Time	Commit to production	< 1 hour	1 day - 1 week	1-6 months	6+ months
Change Failure Rate	% of deploys causing issues	0-15%	16-30%	31-45%	46-60%
MTTR	Time to restore service	< 1 hour	< 1 day	< 1 week	1+ week

Platform Adoption Metrics

Metric	Target	Measures
Golden path adoption	> 80% of new services	Are teams using the platform?
Time to first deploy	< 1 day	How fast can a new dev be productive?
Self-service resolution	> 90%	Can devs solve problems without platform team?
Developer satisfaction (NPS)	> 40	Do developers like using the platform?
Ticket volume to platform team	Decreasing trend	Is self-service working?

Anti-Patterns

Anti-Pattern	Problem	Fix
Building a platform nobody asked for	Low adoption, wasted effort	Start with developer interviews, solve real problems
Forcing platform adoption	Resentment, shadow IT	Make the golden path easier than the alternative
Platform as bottleneck	Platform team reviews every change	Self-service with guardrails, not gatekeeping
Over-abstracting	Developers can’t debug through the abstraction	Allow escape hatches, expose lower layers when needed
No feedback loop	Platform team guesses what developers need	Regular surveys, embedded platform engineers

Checklist

:::note[Source] This guide is derived from operational intelligence at Garnet Grid Consulting. For platform engineering consulting, visit garnetgrid.com. :::