Platform Engineering: How to Build an Internal Developer Platform (IDP)

From DevOps to Platform Engineering: why the shift

The DevOps 'shift left' gave teams autonomy over their infrastructure, but at scale that autonomy has a cost: cognitive load. A developer who wants to launch a new service ends up making decisions about Kubernetes, Terraform, CI/CD, secrets, observability, and networking — none of which add direct value to the product. Platform Engineering recognizes that most of those decisions were already made well once, and that repeating them on every team is waste.

The core idea: a platform team treats the internal platform as a product, with the organization's developers as its users. Instead of tickets and wikis, it offers self-service; instead of documenting how to do something, it makes the correct way the easiest one. The result is measured in time: how long it takes a developer to go from 'I want a new service' to 'it's in production with logs, metrics, and CI/CD'.

What an Internal Developer Platform (IDP) is

An IDP is the layer that sits between developers and infrastructure complexity. It isn't a single tool — it's a set of integrated capabilities that a developer consumes without needing to understand what's underneath:

• Self-service: the developer provisions what they need (a service, a database, an environment) without opening a ticket or waiting on another team.
• Golden paths: paved, opinionated routes for common tasks — create a service, add a database, expose an API — with the right decisions already built in.
• Software catalog: a living inventory of all services, their owners, dependencies, and status. It answers 'what exists and who maintains it?' without archaeology.
• Templates (scaffolding): generation of new services already wired with CI/CD, observability, security, and organizational standards from the first commit.

Golden Paths: the heart of the IDP

A golden path is the recommended, supported way to do something common, packaged so it's the path of least resistance. It doesn't forbid alternatives — it makes the correct route so easy that most people choose it by default. The canonical example: creating a new service.

Without a golden path, a new service means copying another repo, tweaking the pipeline, configuring secrets, adding dashboards, and hoping you didn't forget anything. With a golden path, it's a command or a form that generates all of that correct from the start:

# Backstage Scaffolder — "new service" template (golden path)
apiVersion: scaffolder.backstage.io/v1beta3
kind: Template
metadata:
  name: nodejs-service
  title: Node.js Service (with CI/CD and observability)
  description: Creates a service with pipeline, dashboards, and IQS standards
spec:
  parameters:
    - title: Service details
      required: [name, owner]
      properties:
        name:  { type: string, description: Service name }
        owner: { type: string, description: Owning team }
  steps:
    - id: fetch
      action: fetch:template
      input:
        url: ./skeleton
        values:
          name: ${{ parameters.name }}
          owner: ${{ parameters.owner }}
    - id: publish
      action: publish:gitlab
      input:
        repoUrl: gitlab.com?repo=${{ parameters.name }}
    - id: register
      action: catalog:register        # auto-registers in the catalog
      input:
        catalogInfoUrl: /catalog-info.yaml

The skeleton this template generates already includes the CI/CD pipeline, the Dockerfile, the Kubernetes manifests, the logging and metrics configuration, and the catalog file. The developer makes none of those decisions — the platform team made them once, well, and encoded them.

The software catalog with Backstage

The catalog answers the question that becomes impossible at scale: 'what services exist, who maintains them, and what do they depend on?'. Each component is described with a declarative file that lives next to the code, so the catalog never goes stale:

# catalog-info.yaml — lives at the root of the service repository
apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: checkout-api
  description: Checkout and orders API
  annotations:
    gitlab.com/project-slug: iqs/checkout-api
    backstage.io/techdocs-ref: dir:.
spec:
  type: service
  lifecycle: production
  owner: team-payments
  dependsOn:
    - resource:postgres-orders
    - component:pricing-service

With this information declared by each service, the portal automatically builds the dependency graph, the per-team ownership pages, and the technical documentation. When something breaks, the catalog answers in seconds who owns it and what else is affected.

Self-service without losing governance

The legitimate fear of self-service is chaos: if anyone can provision whatever they want, security and costs spiral. The solution isn't to go back to tickets — it's to encode governance inside the self-service path itself. The developer asks in application terms; the platform translates to infrastructure that complies with policy.

# The developer declares intent; the platform enforces the standard.
# High-level resource (Crossplane) — never touches Terraform or IAM directly
apiVersion: platform.iqs.io/v1alpha1
kind: PostgresInstance
metadata:
  name: orders-db
spec:
  size: small          # small | medium | large -> approved sizes
  environment: prod
  team: team-payments  # derives permissions, cost tags, and backups by policy

Behind that simple resource, the platform applies encryption, backups, cost tags, network rules, and least privilege — all without the developer configuring them or being able to bypass them. Governance stops being a manual review and becomes part of the definition.

Metrics: how to know your platform works

An IDP is an internal product, and like every product it's measured by adoption and by the outcome it produces, not by the features it has. The metrics that matter:

• Time to first deploy: how long a new developer takes from zero to their first change in production. It's the most honest indicator of your platform's real friction.
• Golden path adoption: what percentage of new services use the platform's templates versus those created outside it. Low adoption means the path isn't easy enough.
• DORA metrics: deployment frequency, lead time, change failure rate, and time to restore. A good platform improves them across all teams.
• Developer satisfaction (DevEx): short, periodic surveys. The platform exists to serve developers; if they hate it, it doesn't matter how elegant it is inside.

Common mistakes adopting Platform Engineering

• Building the platform without treating developers as customers: if the platform team decides in isolation what everyone else needs, it builds something nobody asked for. Talk to your internal users like you'd talk to external customers.
• Starting with the portal instead of the golden paths: a Backstage installed without automation behind it is a pretty, empty catalog. The value is in the paved roads, not the interface.
• Enforcing instead of paving: forcing the platform with prohibitions generates clandestine workarounds. Win adoption by making the correct path the most comfortable one.
• Adopting Platform Engineering too early: with 2-3 teams, the overhead of a formal platform isn't justified. It makes sense when duplication across teams and cognitive load start costing more than the platform.