Platform Engineering: Building an Internal Developer Platform from Scratch
Platform engineering is the discipline of building tools and workflows that make developers self-sufficient. Instead of filing tickets and waiting for DevOps, developers provision infrastructure, deploy services, and manage environments through a self-service portal. Therefore, the platform team becomes a product team — their product is developer productivity, and their customers are the engineers who use the platform every day.
The Problem: Developer Friction
In a typical organization, deploying a new microservice takes two to three weeks. The developer files an infrastructure ticket (wait two days), gets a Kubernetes namespace (wait one day), requests a database (wait two days), configures CI/CD (half a day), sets up monitoring (half a day), and configures networking (another day). Moreover, each step involves a different team, a different tool, and a different approval process. Every handoff adds queue time, and queue time — not work time — is what actually dominates the calendar.
An Internal Developer Platform (IDP) compresses this to roughly fifteen minutes. The developer fills in a form — service name, team, database type, environment — and the platform provisions everything automatically. The result is dramatic: the same microservice is production-ready before the old process would have cleared the first ticket. Crucially, the friction this removes is not just elapsed time; it is the context-switching tax developers pay every time they have to chase another team for a dependency.
What an IDP Actually Contains
A practical IDP has five layers:
1. Service Catalog — A searchable registry of every service, who owns it, what it depends on, and where its documentation lives. When someone gets paged at 2 AM, they can immediately find the runbook, the owning team, and the monitoring dashboard. Backstage is the most popular tool for this.
2. Software Templates (Golden Paths) — Pre-configured project templates that create a new service with CI/CD, monitoring, infrastructure, and documentation already wired up. These encode your organization’s best practices into reusable patterns.
3. Infrastructure Provisioning — Self-service access to databases, caches, queues, and other infrastructure through a simple interface. Crossplane, Terraform modules, or Pulumi programs behind a Backstage template.
4. Deployment Pipeline — Standardized CI/CD that works the same way for every service. GitHub Actions, GitLab CI, or Jenkins pipelines defined in the template and configured automatically.
5. Observability — Pre-configured dashboards, alerts, and logging for every service. When a new service is created from a template, its Grafana dashboard and PagerDuty integration exist from day one.
The Control Plane: Crossplane and Abstraction
Underneath the form a developer fills in, something has to translate their intent into real cloud resources. This is the job of the platform’s control plane. Crossplane has become a popular choice because it lets you define a high-level abstraction — for example, a PostgreSQLInstance — and bind it to concrete cloud resources through a composition. The developer never touches an RDS parameter group or a VPC subnet; they ask for a database, and the platform enforces sane defaults, encryption, backups, and cost-appropriate sizing behind the scenes.
# A platform-owned abstraction the developer consumes.
# They request "a database"; the composition decides the rest.
apiVersion: platform.acme.io/v1alpha1
kind: PostgreSQLInstance
metadata:
name: orders-db
spec:
parameters:
storageGB: 20
version: "15"
environment: production
compositionRef:
name: postgres-aws-production # enforces backups, encryption, sizing
writeConnectionSecretToRef:
name: orders-db-conn # credentials land in a Kubernetes SecretThe power of this approach is that the abstraction is a contract. Platform engineers can change what postgres-aws-production means — switch instance classes, tighten security groups, add a read replica — without any developer changing a line of their request. In other words, the abstraction decouples what developers want from how the platform delivers it, which is exactly the leverage a platform team needs.
Building Your First Golden Path
Don’t try to build everything at once. Start with the single most common developer request — probably “I need a new REST API with a database.” Build one golden path that handles this end-to-end.
# What the developer sees: a simple form
# What happens behind the scenes:
1. GitHub repository created from template
- Application code (Spring Boot / Express / Go)
- Dockerfile + Kubernetes manifests
- GitHub Actions CI/CD pipeline
- catalog-info.yaml for Backstage
2. Kubernetes namespace created
3. Database provisioned (Crossplane PostgreSQLInstance)
4. Credentials stored in Kubernetes Secret
5. Grafana dashboard created from template
6. PagerDuty service linked
7. Service registered in Backstage catalog
# Total time: 5-15 minutes (mostly waiting for database provisioning)
# Previous time: 2-3 weeks of ticketsAfter the first golden path works reliably, add more: “I need a data pipeline,” “I need a frontend application,” “I need a scheduled job.” Each golden path serves a common developer need and eliminates a category of tickets. Importantly, resist the urge to parameterize the first template into an infinitely flexible monster. A golden path earns its name precisely because it is opinionated — it makes a hundred small decisions so the developer makes none.
GitOps as the Deployment Backbone
Self-service provisioning is only half the story; you also need a reliable way for those resources to converge on the desired state and stay there. The dominant pattern in 2026 is GitOps, where a Git repository is the single source of truth and a controller such as Argo CD continuously reconciles the cluster against it. When a golden path scaffolds a new service, it commits the service’s manifests to Git, and the GitOps controller does the rest — no developer runs kubectl apply by hand, and every change is auditable through the commit history.
# Argo CD Application created by the golden path.
# Git is the source of truth; the controller reconciles drift.
apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
name: orders-service
namespace: argocd
spec:
project: team-checkout
source:
repoURL: https://github.com/acme/orders-service
path: deploy/overlays/production
targetRevision: main
destination:
server: https://kubernetes.default.svc
namespace: orders
syncPolicy:
automated:
prune: true # remove resources deleted from Git
selfHeal: true # revert manual drift automaticallyThis combination — Crossplane for infrastructure abstraction and Argo CD for continuous reconciliation — is what makes the fifteen-minute experience repeatable rather than a one-off demo. For a deeper treatment of wiring these together, see the GitOps with ArgoCD and Crossplane guide.
Measuring Platform Success
A platform is successful when developers use it voluntarily and ship faster. Track these metrics:
- Time to first deploy (new service): The most impactful metric. Target: under one hour.
- Time to first deploy (new hire): How quickly a new developer can ship a change. Target: day one.
- Golden path adoption rate: What percentage of new services use templates? Target: above 80%.
- Ticket volume reduction: Infrastructure and DevOps tickets should decrease as self-service increases.
- Developer satisfaction: Survey quarterly. If developers don’t like your platform, fix it or they’ll work around it.
It is worth grounding these against an industry baseline. The DORA research program popularized four key delivery metrics — deployment frequency, lead time for changes, change failure rate, and time to restore service — and a good platform should visibly improve all four over time. Treat your own dashboards the same way you treat the services on the platform: instrument them, review them regularly, and act when the trend goes the wrong way.
Common Mistakes
Building a platform nobody asked for. Talk to developers first. What actually slows them down? It might not be what you think.
Making the platform mandatory. If developers can’t bypass it for edge cases, they’ll resent it. Paved roads, not walled gardens.
Over-engineering the first version. Start with Backstage plus one template plus one Crossplane composition. Expand based on demand, not speculation.
Platform team as gatekeepers. Self-service means self-service. Add guardrails (cost limits, security policies) but remove gates (approval workflows for standard requests).
When NOT to Build an IDP
An internal developer platform is a serious, ongoing investment, and it is the wrong choice for many organizations. If you have one team and a handful of services, the “platform” is overhead with no friction to remove — a few well-written scripts and a shared Terraform module will serve you better than a Backstage deployment that needs its own maintainers. A reasonable heuristic from the platform engineering community is that the case strengthens once you are past roughly twenty-five to fifty engineers, where coordination cost starts to dominate. Below that, building an IDP is premature optimization.
Be honest about the staffing reality as well: a platform is a product, and an unowned product rots. If you cannot dedicate a small, stable team to run it as a product — gathering feedback, fixing the golden paths, and keeping the dependencies current — you will end up with abandonware that developers route around, which is worse than the tickets you started with. In short, build an IDP when the friction is real, recurring, and felt across many teams, and when you can commit to maintaining it. Otherwise, invest that energy in better documentation and a couple of solid automation scripts.
Related Reading:
- Platform Engineering Developer Portal
- GitOps with ArgoCD and Crossplane
- OpenTofu Terraform Migration
Resources:
In conclusion, platform engineering isn’t about building a fancy portal — it’s about systematically removing friction from the developer workflow. Start small, solve real pain points, ground your abstractions in tools like Crossplane and GitOps, and expand based on what developers actually need. Measure relentlessly, staff the platform as a real product, and remember that the best platform is the one developers choose to use.