Platform Engineering: Building an Internal Developer Platform That Teams Actually Use

The promise of platform engineering is compelling: give developers self-service access to infrastructure, reduce cognitive load, and let them focus on writing business logic instead of fighting YAML. The reality is that most internal developer platforms fail — not because of technology, but because they are built for the platform team, not for the developers who are supposed to use them.

Here is how to build an internal developer platform (IDP) that teams actually adopt, based on patterns we have seen succeed (and fail) across enterprise organisations.

Why Most Internal Platforms Fail

Before building anything, understand the three ways platforms fail:

The "build it and they will come" fallacy. A self-service portal with no documentation, no onboarding, and no feedback loop. Developers try it once, hit a wall, and go back to filing Jira tickets.
The "pave the cow path" trap. Automating broken processes. If deploying to production requires 14 manual steps, automating all 14 steps produces a fragile pipeline, not a platform.
The "golden cage" problem. Opinionated platforms that offer no escape hatches. When a team hits an edge case the platform does not support, they either abandon the platform entirely or build increasingly creative workarounds.

The common thread: all three prioritise the platform team's vision over the developer's actual workflow.

Start with Golden Paths, Not Golden Cages

A golden path is an opinionated, well-paved route through a common workflow — creating a new service, deploying to production, provisioning a database. It is the recommended way, not the only way.

What makes a good golden path:

It handles 80% of use cases without customisation. If most teams deploy Node.js services on Kubernetes, your golden path should make that trivially easy.
It is escapable. Teams with non-standard requirements can step off the path and manage resources directly. They lose the convenience, not the capability.
It is documented with examples, not just reference docs. A working example repository that developers can clone and modify is worth more than a 50-page specification.
It evolves based on feedback. Golden paths are products, not projects. They need continuous iteration based on developer usage data and friction reports.

A practical example:

A golden path for "create a new microservice" might include:

A Backstage software template that scaffolds a Git repository with a Dockerfile, Helm chart, CI pipeline, and Flux GitOps manifests.
Automatic creation of a database (via Crossplane), a Key Vault for secrets, and a service principal with least-privilege access.
A pre-configured CI/CD pipeline that builds, tests, scans, and deploys to a dev environment — all from the first commit.

The developer fills in a form (service name, language, database type), clicks create, and has a running service in 15 minutes. That is the golden path.

The Technology Stack

An IDP is not a product you buy — it is a composition of tools. Here is a proven stack:

Backstage: The Developer Portal

Backstage (originally from Spotify, now a CNCF project) provides the developer-facing layer:

Software Catalog: A single source of truth for all services, their owners, documentation, and dependencies. Eliminates the "who owns this service?" problem.
Software Templates: Scaffolding that creates new projects with best practices baked in. Templates call APIs (GitHub, Azure, Crossplane) to provision everything a service needs.
TechDocs: Documentation-as-code rendered alongside the service in the catalog. Developers do not need to hunt for docs in Confluence.
Plugins: Kubernetes status, CI/CD pipeline status, security scan results, cost dashboards — all surfaced in one portal.

Practical advice: Start with the software catalog. Populate it with existing services by importing from your Git provider. Templates and plugins come later, once the catalog proves its value.

Crossplane: Self-Service Infrastructure

Crossplane extends Kubernetes with custom resource definitions (CRDs) that provision cloud resources. It turns infrastructure requests into Kubernetes manifests.

A developer who needs a PostgreSQL database creates a claim:

YAML

apiVersion: database.platform.internal/v1alpha1
kind: PostgreSQLClaim
metadata:
  name: my-service-db
  namespace: my-service
spec:
  size: small
  version: "15"

The platform team defines Compositions that map this simple claim to the actual Azure resources: a Flexible Server, firewall rules, a private endpoint, a Key Vault secret with the connection string.

Why Crossplane over Terraform for self-service?

Crossplane is declarative and continuously reconciled — if someone deletes the firewall rule in the portal, Crossplane recreates it.
Crossplane claims are namespaced — natural multi-tenancy. Teams can only see and manage their own resources.
Crossplane uses the Kubernetes API — no additional tooling, authentication, or state management.

Argo Workflows or Tekton: Orchestration

For workflows that go beyond simple resource provisioning — onboarding a new team, rotating credentials, running compliance checks — use a workflow engine.

Argo Workflows for complex DAG-based workflows with a visual UI.
Tekton if you want to stay fully Kubernetes-native and already use it for CI/CD.

Measuring Developer Experience

If you do not measure adoption and satisfaction, you are flying blind. These are the metrics that matter:

Lead Time Metrics

Time from code commit to running in production. This is your north star metric. If the platform is working, this number decreases over time.
Time to provision a new service. From template invocation to first successful deployment. Target: under 30 minutes.
Time to onboard a new developer. From laptop setup to first commit deployed. Target: under one day.

Adoption Metrics

Percentage of services using the golden path. Track this by team and service age. New services should be near 100%. Legacy services will lag, and that is fine.
Template usage frequency. How many new services are created per month via the platform versus manually?
Self-service ratio. What percentage of infrastructure requests are fulfilled via the platform versus manual tickets? Target: 80%+ self-service within 12 months.

Satisfaction Metrics

Developer Net Promoter Score (NPS) for the platform, surveyed quarterly.
Friction logs. Ask developers to document every point where the platform slowed them down. These are gold for prioritising improvements.
Support ticket volume. A decreasing trend indicates the platform is becoming more self-explanatory.

Key insight: The most important metric is not how many features the platform has. It is how many teams voluntarily choose to use it. If you have to mandate adoption, your platform has a product problem.

Organisational Design

Technology is the easy part. The hard part is operating the platform as a product.

The Platform Team as a Product Team

Assign a product owner who represents developer needs, not infrastructure preferences.
Run user research — shadow developers using the platform, conduct interviews, review friction logs.
Maintain a public roadmap that developers can see and influence.
Treat platform features like product features: discovery, design, build, measure, iterate.

The Inner Source Model

Make platform code open for contribution. If a team needs a new Backstage plugin or Crossplane composition, they should be able to build it and submit a PR.
The platform team reviews and maintains the core, but the ecosystem grows through contribution.
Publish contribution guidelines and hold regular office hours for teams that want to extend the platform.

Gradual Rollout

Start with 2-3 early adopter teams who are motivated and forgiving.
Iterate based on their feedback until the golden path is genuinely smooth.
Expand to the next wave only when early adopters are successful and willing to advocate.
Never mandate platform adoption before it is ready. Forcing teams onto a half-baked platform destroys trust that takes years to rebuild.

Common Pitfalls to Avoid

Do not build a UI before you have working APIs. The portal is a front end. If the underlying automation does not work reliably, a pretty UI just makes failures more visible.
Do not abstract too early. Start with concrete golden paths for your most common use case. Abstract into a generalised platform only after you have three or more concrete paths working.
Do not ignore escape hatches. Every golden path needs a documented way to go "off-road." If developers cannot do something the platform does not support, they will abandon it entirely.
Do not compete with your cloud provider's portal. The platform should complement Azure/AWS, not replicate it. If a developer needs to configure a one-off resource, let them use the cloud console.

The Path Forward

Platform engineering is a multi-year investment, not a quarter-long project. Start small, measure ruthlessly, and iterate based on what developers actually need — not what the platform team thinks they should need.

The platforms that succeed are the ones built by teams that think like product engineers, not infrastructure engineers.

Building an internal developer platform? Talk to our team — we help enterprises design, build, and operationalise IDPs that drive real adoption.