Platform Engineering: Internal Developer Platforms, Golden Paths, and Backstage

Platform engineering is the practice of building internal products for developers — infrastructure, tooling, and workflows that reduce cognitive load and let engineers ship faster without becoming infrastructure experts.

The key shift: platform teams think like product teams. Their "customers" are internal developers. Success is measured by adoption, not just capability.

---

What Is an Internal Developer Platform (IDP)?

An IDP is the collection of tools and workflows a platform team provides to stream-aligned engineering teams. It's self-service by design — teams provision infrastructure, deploy services, and access tooling without filing tickets with the platform team.

Components of a mature IDP:

---

The Golden Path

A golden path is the opinionated, supported route to getting something done. It's not mandatory — engineers can go off-path — but going off-path means accepting reduced platform support.

Example golden paths:

Golden Path: New TypeScript Service

When you need: A new backend microservice What you get:

• Fastify TypeScript service with health checks, Prometheus metrics, structured logging
• Dockerfile optimized for production (non-root user, minimal image)
• Helm chart pre-configured with HPA, PDB, security context
• GitHub Actions CI with test, lint, build, push to ECR
• ArgoCD Application auto-created for staging and production
• Datadog dashboard pre-created with golden signals
• README with runbook links and architecture notes

Time to first deployment: < 2 hours Ongoing platform support: Full

Golden Path: New PostgreSQL Database

When you need: A persistent database for a new service What you get:

• Crossplane PostgreSQLInstance claim (→ RDS with Multi-AZ, backups, monitoring)
• Connection string injected as Kubernetes secret
• PgBouncer sidecar pre-configured
• Automated daily backups with 7-day retention
• Datadog RDS dashboard

Time to provision: < 10 minutes (Crossplane creates RDS asynchronously) Ongoing platform support: Full

---

Backstage: Software Catalog

Backstage is CNCF's open-source developer portal. Its core feature is the software catalog — a searchable, auto-updating registry of all your services, APIs, libraries, and documentation.

# catalog-info.yaml — add to every repo root
apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: orders-api
  description: Order management service — create, update, track orders
  annotations:
    # Auto-link to GitHub
    github.com/project-slug: yourorg/orders-api
    # Auto-pull documentation from TechDocs
    backstage.io/techdocs-ref: dir:.
    # Link to Datadog dashboard
    datadoghq.com/dashboard-url: https://app.datadoghq.com/dashboard/xxx
    # PagerDuty service
    pagerduty.com/service-id: PXXX123
  tags:
    - typescript
    - fastify
    - postgresql
  links:
    - url: https://app.datadoghq.com/apm/service/orders-api
      title: Datadog APM
    - url: https://api.yourproduct.com/docs
      title: API Documentation
spec:
  type: service
  lifecycle: production
  owner: group:payments-team
  providesApis:
    - orders-api-v2
  consumesApis:
    - users-api-v1
    - payments-api-v1
  dependsOn:
    - resource:orders-postgres
    - resource:orders-redis

Backstage app-config.yaml (minimal setup):

# app-config.yaml
app:
  title: Viprasol Developer Portal
  baseUrl: https://backstage.internal.yourproduct.com

backend:
  baseUrl: https://backstage.internal.yourproduct.com
  database:
    client: pg
    connection: ${POSTGRES_CONNECTION_STRING}

integrations:
  github:
    - host: github.com
      token: ${GITHUB_TOKEN}

catalog:
  providers:
    github:
      yourorg:
        organization: yourorg
        catalogPath: /catalog-info.yaml
        filters:
          branch: main
        schedule:
          frequency: { minutes: 30 }
          timeout: { minutes: 3 }

techdocs:
  builder: external
  generator:
    runIn: docker
  publisher:
    type: awsS3
    awsS3:
      bucketName: your-backstage-techdocs
      region: us-east-1

---

Backstage Scaffolder: Golden Path Templates

The scaffolder lets engineers create new services from templates through the Backstage UI:

# backstage/templates/typescript-service/template.yaml
apiVersion: scaffolder.backstage.io/v1beta3
kind: Template
metadata:
  name: typescript-service
  title: TypeScript Microservice
  description: Fastify TypeScript service with Helm chart, CI/CD, and observability
  tags: [typescript, fastify, recommended]
spec:
  owner: platform-team
  type: service

  parameters:
    - title: Service Details
      required: [name, owner, description]
      properties:
        name:
          title: Service Name
          type: string
          pattern: '^[a-z][a-z0-9-]{2,30}$'
          description: Lowercase, kebab-case (e.g. orders-api)
        owner:
          title: Owning Team
          type: string
          ui:field: OwnerPicker
          ui:options:
            catalogFilter:
              kind: Group
        description:
          title: Description
          type: string
        database:
          title: Needs a PostgreSQL database?
          type: boolean
          default: false

  steps:
    - id: fetch-base
      name: Fetch Base Template
      action: fetch:template
      input:
        url: ./skeleton
        values:
          name: ${{ parameters.name }}
          owner: ${{ parameters.owner }}
          description: ${{ parameters.description }}
          database: ${{ parameters.database }}

    - id: publish
      name: Publish to GitHub
      action: publish:github
      input:
        allowedHosts: [github.com]
        description: ${{ parameters.description }}
        repoUrl: github.com?owner=yourorg&repo=${{ parameters.name }}
        defaultBranch: main

    - id: register
      name: Register in Catalog
      action: catalog:register
      input:
        repoContentsUrl: ${{ steps.publish.output.repoContentsUrl }}
        catalogInfoPath: /catalog-info.yaml

    - id: create-argocd-app
      name: Create ArgoCD Application
      action: argocd:create-resources
      input:
        projectName: ${{ parameters.name }}
        namespace: staging
        repoUrl: https://github.com/yourorg/infra
        labelValue: ${{ parameters.name }}
        path: charts/${{ parameters.name }}
        valueFiles:
          - values.yaml
          - values-staging.yaml

  output:
    links:
      - title: Repository
        url: ${{ steps.publish.output.remoteUrl }}
      - title: Open in Backstage Catalog
        icon: catalog
        entityRef: ${{ steps.register.output.entityRef }}

---

Platform Team Metrics

Platform teams measure success by developer adoption and productivity, not infrastructure output:

## Platform Team Health Metrics

### Adoption
- Golden path adoption rate: % of new services using golden paths (target: >80%)
- Time to first deployment (new service): days from new repo to first production deploy (target: <1 day)
- Backstage catalog coverage: % of production services with catalog entries (target: >95%)

### Developer Experience
- Platform NPS: quarterly survey of stream-aligned engineers (target: >30)
- Support ticket volume trend: is ticket volume declining as self-service improves?
- Time to provision resources: database/queue/cache creation time (target: <15 min)

### Reliability
- Platform uptime: CI/CD pipeline, Backstage, ArgoCD availability (target: 99.9%)
- Self-service success rate: % of resource provisions that succeed without platform team help (target: >95%)

### Not the right metrics:
- Number of features shipped by platform team (output vs outcome)
- Platform team utilization (wrong incentive — want low ticket volume)

---

Crossplane: Self-Service Infrastructure

Crossplane lets developers provision cloud resources (RDS, S3, ElastiCache) using Kubernetes Custom Resources — no Terraform knowledge required:

# Developer creates this claim to get a PostgreSQL database
apiVersion: database.platform.yourcompany.com/v1alpha1
kind: PostgreSQLInstance
metadata:
  name: orders-db
  namespace: production
spec:
  parameters:
    storageGB: 100
    instanceClass: db.t3.medium
    multiAZ: true
    backupRetentionDays: 7
  writeConnectionSecretToRef:
    name: orders-db-secret  # Kubernetes secret with connection string

Crossplane's platform team configures the Composition (Terraform equivalent) once. Developers just file the claim — no AWS console, no Terraform PR.

---

Working With Viprasol

We build Internal Developer Platforms — Backstage setup and customization, golden path template design, Crossplane infrastructure provisioning, ArgoCD GitOps pipelines, and the platform team practices that make IDPs succeed long-term.

→ Talk to our team about platform engineering and developer experience.

---

See Also

• Team Topologies — platform teams in the organizational context
• Kubernetes Helm — Helm as a golden path component
• CI/CD Pipeline Setup — CI in the golden path
• Developer Onboarding — IDPs accelerate new engineer onboarding
• Cloud Solutions — platform engineering services