Platform Engineering: Building Your Internal Developer Platform

Platform engineering reduces cognitive load on developers by abstracting infrastructure complexity behind self-service interfaces. A 100-developer organization with a good platform team ships 30-50% faster than one without.

---

The Internal Developer Platform (IDP)

Developers                    Platform
┌──────────────────┐    ┌──────────────────┐
│ Self-Service UI  │───▶│ Service Catalog  │
│ or CLI           │    │                  │
└──────────────────┘    │ ┌──────────────┐ │
                        │ │ Golden Paths │ │
                        │ │ (Templates)  │ │
                        │ └──────────────┘ │
                        │ ┌──────────────┐ │
                        │ │ Infra as     │ │
                        │ │ Code (GitOps)│ │
                        │ └──────────────┘ │
                        │ ┌──────────────┐ │
                        │ │ Observability│ │
                        │ │ (Built-in)   │ │
                        │ └──────────────┘ │
                        └──────────────────┘

---

Step 1: Define Golden Paths

Golden paths are opinionated, paved roads for common developer tasks.

Service Template (Backstage)

# backstage/templates/node-microservice/template.yaml
apiVersion: scaffolder.backstage.io/v1beta3
kind: Template
metadata:
  name: node-microservice
  title: Node.js Microservice
  description: Production-ready Node.js service with observability
spec:
  owner: platform-team
  type: service
  parameters:
    - title: Service Details
      properties:
        name:
          type: string
          description: Name of the service
        description:
          type: string
        owner:
          type: string
          ui:field: OwnerPicker
    - title: Infrastructure
      properties:
        database:
          type: string
          enum: [postgres, none]
          default: postgres
        cache:
          type: string
          enum: [redis, none]
          default: none
  steps:
    - id: scaffold
      name: Scaffold
      action: fetch:template
      input:
        url: ./skeleton
        values:
          name: ${{ parameters.name }}
          description: ${{ parameters.description }}
          database: ${{ parameters.database }}
    - id: publish
      name: Create Repository
      action: publish:github
      input:
        repoUrl: github.com?owner=yourorg&repo=${{ parameters.name }}
    - id: deploy
      name: Deploy Infrastructure
      action: custom:terraform-apply
      input:
        template: microservice
        vars:
          name: ${{ parameters.name }}
          database: ${{ parameters.database }}
          cache: ${{ parameters.cache }}

---

Step 2: Self-Service Infrastructure

# Platform CLI example
# Developers run: `platform create service --name my-api`

# Under the hood, this creates:
# 1. GitHub repo from template
# 2. CI/CD pipeline (GitHub Actions)
# 3. Kubernetes namespace + RBAC
# 4. Database (if requested)
# 5. Monitoring dashboards
# 6. DNS entry
# 7. TLS certificate
# 8. Service catalog entry

# Developer experience
$ platform create service --name order-api --database postgres --cache redis

Creating service 'order-api'...
✅ GitHub repo created: github.com/org/order-api
✅ CI/CD pipeline configured
✅ Kubernetes namespace: order-api-dev
✅ PostgreSQL database provisioned
✅ Redis cache provisioned
✅ Monitoring dashboard: https://grafana.internal/order-api
✅ DNS: order-api.internal.company.com
✅ Catalog entry: https://backstage.internal/catalog/order-api

Service ready! Run `git clone` and start coding.

---

Step 3: Platform Team Structure

Role	Responsibility	Count (per 100 devs)
Platform Lead	Strategy, roadmap, stakeholder management	1
Platform Engineer	IDP development, tooling, automation	2-3
SRE	Reliability, incident response, observability	1-2
DevX Engineer	Developer experience, documentation, support	1
Total		5-7 (5-7% of eng)

Team Principles

1. Treat developers as customers — run surveys, track NPS
2. Build products, not projects — long-lived platform, not one-off scripts
3. Paved roads, not walls — guide developers, don’t block them
4. Measure everything — time to first deploy, developer satisfaction, incident MTTR

---

Step 4: Measure Platform Success

Metric	Target	How to Measure
Time to first deploy (new service)	< 30 minutes	Track from create to first deploy
Developer satisfaction (NPS)	> 30	Quarterly survey
Platform adoption	> 80% of services	Catalog vs actual services
Incident MTTR	< 1 hour	Incident tracking
Change failure rate	< 5%	Deploys that cause incidents
Deployment frequency	Daily per team	CI/CD metrics

---

Platform Engineering Checklist

• Service catalog deployed (Backstage, Port, or custom)
• Golden path templates for top 3 service types
• Self-service database provisioning
• Self-service environment creation
• Built-in observability (traces, metrics, logs)
• Automated CI/CD for all golden path services
• Developer documentation site
• Platform NPS tracked quarterly
• Time-to-first-deploy measured and improving
• Platform team staffed at 5-7% of engineering

---

:::note[Source] This guide is derived from operational intelligence at Garnet Grid Consulting. For DevOps maturity assessments, visit garnetgrid.com. :::