Platform Engineering: Building Internal Developer Platforms That Developers Actually Want to Use

An Internal Developer Platform earns its keep the day an engineer can ship a service without filing a ticket. The default that gets there is narrower than most platform roadmaps assume: one golden path, built with one pilot team, exposed through an API or CLI before any portal UI, and adopted because it is the fastest route rather than because someone mandated it.

Catalog, self-service actions, IaC orchestration, metrics and tooling all hang off that default. Backstage, Port and the AWS building blocks are decisions you take after the first golden path has earned voluntary adoption.

Understanding Platform Engineering

Platform Engineering is about designing toolchains and workflows that give software engineering organizations self-service capabilities. The shift that matters is treating internal developers as customers who are free to walk away.

What makes Platform Engineering different from traditional DevOps?

The core difference is the platform-as-a-product mindset. Instead of DevOps teams acting as service providers responding to tickets, platform teams become product owners who build tools that developers voluntarily choose because they provide superior experiences.

The change shows up in what a developer hears when they need a deployment:

• DevOps: “We’ll deploy that for you (ticket required)”
• Platform Engineering: “Here’s how you deploy it yourself in 5 minutes”

Why Platform Engineering keeps gaining traction:

Two pressures push in the same direction. Cloud-native stacks keep adding moving parts, and a single shared team answering tickets stops scaling somewhere around the first few dozen services. A platform team absorbs that complexity once so every product team does not absorb it separately.

Core Philosophy:

These principles matter most in practice:

• Developer empowerment through self-service (the ticket queue is the thing being replaced)
• Standardization without reducing flexibility (golden paths ship with an exit ramp)
• Reducing cognitive load (one way that works well beats ten options)
• Speed and safety at the same time (guardrails live inside the path)
• Product thinking applied to internal tools (research first, build second)

Core Components of an Internal Developer Platform

An effective IDP consists of several interconnected components:

Software Catalog / Service Catalog

A central registry of all services, APIs, resources, and teams. It stays useful only while it answers two questions on demand: who owns this, and what depends on what?

Backstage uses YAML-based catalog entities (Component, System, API, Resource, User, Group, Domain). The key is version control integration with GitHub or GitLab for catalog-as-code:

apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: user-service
  description: User management microservice
  annotations:
    github.com/project-slug: org/user-service
    backstage.io/techdocs-ref: dir:.
spec:
  type: service
  lifecycle: production
  owner: team-platform
  system: user-management
  providesApis:
    - user-api
  consumesApis:
    - auth-api
  dependsOn:
    - resource:user-database

Golden Paths / Paved Roads

The term “Golden Paths” comes from Spotify (Netflix calls the same concept “Paved Roads”). The definition that holds up in practice: an opinionated, well-documented, supported way of building and deploying software.

Characteristics of effective golden paths:

• Fully self-serviceable (no ticket filing required)
• Minimal cognitive load (sensible defaults, clear documentation)
• Discoverable by anyone in the organization
• Optional but most convenient (adoption follows from being the easiest route)
• Drives standardization naturally (people choose it because it’s better)

Technical examples of golden paths:

• Standardized service templates (new microservice in 30 minutes)
• Pre-configured CI/CD pipelines (testing + deployment wired up)
• Infrastructure-as-Code modules (common patterns ready to use)
• Containerization blueprints (security baseline included)
• Monitoring and observability pre-wired (no after-the-fact instrumentation)

Self-Service Actions / Developer Portal

The UI layer for platform capabilities. This is where developers interact with the platform to create services, deploy environments, provision databases, all without waiting.

Common implementations include web portals, CLI tools, IDE plugins, and Slack/ChatOps integrations. The best platforms support all of these, letting developers work however they prefer.

Infrastructure as Code (IaC) Orchestration

Centralized IaC templates and modules enable consistent infrastructure provisioning. Version-controlled infrastructure definitions ensure repeatability.

Examples include AWS CDK constructs, Terraform modules, and Pulumi components. Note that AWS Proton is being discontinued (October 2026), so teams should plan alternatives.

CI/CD Integration

Standardized pipeline templates with automated testing, quality gates, and progressive deployment strategies (canary, blue-green). Integration with GitHub Actions, GitLab CI, Jenkins, or CircleCI.

Observability and Monitoring

Pre-configured monitoring dashboards, standardized logging and tracing, alerting templates, and cost tracking. Tools like Prometheus, Datadog, New Relic, or CloudWatch integrate here.

Security and Compliance

Policy-as-code enforcement, security scanning automation (SAST, DAST, dependency scanning), compliance guardrails built into golden paths, and secret management integration.

Tools like Snyk, Dependabot, AWS Security Hub, and OPA (Open Policy Agent) automate security at platform level.

Platform as a Product Mindset

Platform success is measured by voluntary adoption. Mandate platform usage and you lose the most important feedback signal you have: whether developers find it valuable.

Critical practices that work:

• Research developer pain points before building
• Gather continuous feedback loops (surveys, office hours, Slack channels)
• Measure developer satisfaction quarterly (NPS or custom metrics)
• Don’t mandate platform adoption (it closes feedback loops)
• Build what developers need, not what you think they need
• Maintain a product roadmap and communicate changes transparently

Product thinking checklist:

• Defined user personas (different dev team types)
• User research conducted (surveys, interviews)
• Clear value proposition for developers
• Onboarding experience designed
• Documentation written for humans
• Support channels established
• Success metrics defined and tracked
• Roadmap shared transparently
• Feedback mechanisms in place

Implementation Patterns and Best Practices

Starting Your Platform Journey

Don’t start with:

• Biggest, most critical service (too risky for nascent platform)
• Portal/UI first (need solid backend APIs first)
• Top-down mandates (kills adoption)
• “Build it and they will come” mentality
• Everything in-house (“Not Invented Here” syndrome)

Do start with:

• Minimum viable platform (MVP) with core value
• Pilot with friendly, interested team
• Backend APIs and orchestration first, UI second
• One golden path done really well
• Existing pain point that everyone feels
• Developer research and feedback

Build vs. Buy Considerations

Build custom when:

• Highly specific organizational requirements
• Deep integration with legacy systems needed
• Have dedicated platform engineering team (3+ engineers)
• Long-term investment commitment
• React/TypeScript expertise available (for Backstage)

Buy/adopt existing when:

• Standard requirements covered by existing tools
• Limited platform engineering resources
• Need fast time-to-value (weeks, not months)
• Prefer managed solutions over self-hosting
• Want active community and ecosystem

Team Structure Recommendations

Platform Engineering Team Composition:

• Former infrastructure engineers (already have expertise)
• Product-minded engineers (user empathy)
• Developer experience (DevEx) specialists
• Technical writers (documentation matters)

Avoid: Moving all senior engineers to platform team (creates knowledge gaps in dev teams)

Team size by organization:

• Small (< 50 engineers): 1-2 platform engineers
• Medium (50-200 engineers): 3-5 platform engineers
• Large (200-500 engineers): 5-10 platform engineers
• Enterprise (500+ engineers): 10-20+ platform engineers

Common guideline (not industry standard): ~1 platform engineer per 30-50 application developers. This ratio varies significantly based on platform maturity, organizational complexity, and automation level.

Tooling Landscape

A default before the catalog of options: stay off a portal entirely until the first golden path has adoption. When a portal does become necessary, organizations that already run React and TypeScript in production default to Backstage, and organizations that do not default to a commercial platform. Picking the tool before the path is the most common way to spend two quarters and ship nothing a developer wants.

Backstage (Open Source by Spotify)

Open-sourced in 2020, Backstage has the largest ecosystem and market share. It’s a plugin-based architecture with React/TypeScript frontend and Node.js backend.

Strengths:

• Highly customizable for complex requirements
• Rich plugin ecosystem (100+ plugins)
• Free and open source
• Large community support
• Unified developer experience

Challenges:

• Significant implementation effort (3-6 months typical)
• Requires React/TypeScript/SAML expertise
• Self-hosting required (or use managed service like Roadie)
• Steep learning curve
• Ongoing maintenance burden

Worth knowing before you commit: Backstage is a framework, not a product. Adopting it means building your IDP out of Backstage components, and teams routinely underestimate how much of that work is theirs.

When to choose Backstage:

• Large-scale, complex environments
• Need deep customization
• Have dedicated development resources
• React/TypeScript expertise available
• Open source preference

Port (Commercial Platform)

Port is a commercial, SaaS-hosted platform for assembling an IDP without writing frontend code.

Strengths:

• Much faster time-to-value (weeks vs months)
• No React/TypeScript expertise required
• Excellent onboarding experience
• Auto-import from GitHub/GitLab
• Less maintenance overhead
• Built-in tutorials and guides
• Dynamic inventorying (CI/CD flows, clusters, environments)
• Advanced search and RBAC

Challenges:

• Implementation still lengthy (3-6 months reported)
• Significant licensing costs (higher than competitors)
• Less customizable than Backstage
• Vendor lock-in concerns
• Higher total cost of ownership

When to choose Port:

• Want user-friendly, hassle-free IDP
• Limited technical expertise for platform development
• Prefer SaaS over self-hosted
• Need fast deployment
• Budget for commercial tooling

AWS Services for Platform Engineering

AWS Proton (Note: being discontinued on October 7, 2026)

• Managed service for infrastructure template vending
• Platform engineers define standards, developers self-serve
• Organizations should plan alternatives

Amazon EKS (Elastic Kubernetes Service)

• Fully managed Kubernetes for platform foundations
• EKS Blueprints: Curated templates for complete EKS setup
• Platform engineering patterns well-supported
• Integrates with Backstage, Port, custom IDPs

AWS CDK (Cloud Development Kit)

Infrastructure as Code in programming languages. Perfect for building platform golden paths:

// Platform team creates reusable construct
import * as cdk from 'aws-cdk-lib';
import * as lambda from 'aws-cdk-lib/aws-lambda';
import * as apigateway from 'aws-cdk-lib/aws-apigateway';
import { Construct } from 'constructs';

export interface StandardApiServiceProps {
  serviceName: string;
  team: string;
  runtime: lambda.Runtime;
  handler: string;
  codeAsset: lambda.Code;
}

export class StandardApiService extends Construct {
  public readonly api: apigateway.RestApi;
  public readonly function: lambda.Function;

  constructor(scope: Construct, id: string, props: StandardApiServiceProps) {
    super(scope, id);

    // Lambda with standard configuration
    this.function = new lambda.Function(this, 'Handler', {
      runtime: props.runtime,
      handler: props.handler,
      code: props.codeAsset,
      timeout: cdk.Duration.seconds(30),
      memorySize: 1024,
      environment: {
        SERVICE_NAME: props.serviceName,
        TEAM: props.team,
      },
      // Observability built-in
      tracing: lambda.Tracing.ACTIVE,
      insightsVersion: lambda.LambdaInsightsVersion.VERSION_1_0_229_0,
    });

    // API Gateway with standard settings
    this.api = new apigateway.RestApi(this, 'Api', {
      restApiName: props.serviceName,
      // Security defaults
      defaultCorsPreflightOptions: {
        allowOrigins: apigateway.Cors.ALL_ORIGINS,
        allowMethods: apigateway.Cors.ALL_METHODS,
      },
    });

    // Standard integration
    const integration = new apigateway.LambdaIntegration(this.function);
    this.api.root.addProxy({ defaultIntegration: integration });

    // Standard tags
    cdk.Tags.of(this).add('Service', props.serviceName);
    cdk.Tags.of(this).add('Team', props.team);
    cdk.Tags.of(this).add('ManagedBy', 'Platform');
  }
}

// Developers use the golden path
const service = new StandardApiService(this, 'UserService', {
  serviceName: 'user-service',
  team: 'platform',
  runtime: lambda.Runtime.NODEJS_20_X,
  handler: 'index.handler',
  codeAsset: lambda.Code.fromAsset('./dist'),
});

AWS Service Catalog

• Vending machine for approved AWS resources
• Pre-configured product portfolios
• Budget controls and governance
• Alternative to AWS Proton

Other Notable Tools

• Humanitec: Platform orchestration, focuses on application configuration
• Kratix: Platform-as-a-product framework on Kubernetes
• Crossplane: Infrastructure composition using Kubernetes APIs
• Terraform Cloud/Enterprise: Workspace management for teams
• Pulumi: Multi-language IaC with state management
• ArgoCD / Flux: GitOps for Kubernetes deployments
• Cortex: Developer scorecards and standards tracking

Measuring Platform Success

DORA Metrics (Traditional DevOps)

Four Key Metrics:

1. Deployment Frequency: How often code deploys to production
2. Lead Time for Change: Time from commit to production
3. Time to Restore Service: How long to recover from failure
4. Change Failure Rate: Percentage of deployments causing issues

Elite Performers (DORA 2024):

• Deploy multiple times per day
• Lead time < 1 day
• Recovery time < 1 hour
• Failure rate < 5%

DORA Limitations for Platform Engineering

Critical gap: DORA measures software delivery performance. Platform engineering effectiveness is a different question, and the four keys do not answer it.

What DORA misses:

• Infrastructure management quality
• Security and compliance improvements
• Platform usability and developer happiness
• Tech debt reduction (unless it causes failures)
• Scalability and maintainability work
• Day 2-N operations improvements

Platform-Specific Metrics

Developer Experience (DevEx) Metrics:

• Platform Adoption Rate: % of teams using IDP vs alternatives
• Self-Service Success Rate: % of self-service actions completed without help
• Time to First Deployment: How long for new team to deploy using platform
• Developer Satisfaction Score: Quarterly surveys (NPS or custom)
• Tool Fragmentation Score: Number of tools developers must use
• Onboarding Time: Days to productivity for new engineers

Platform Health Metrics:

• Golden Path Usage: % of deployments using standard templates
• Support Ticket Volume: Platform-related help requests (downward trend = success)
• Platform Uptime: Availability of platform services
• Template Update Velocity: How quickly platform capabilities improve
• Documentation Coverage: % of platform features documented

Business Impact Metrics:

• Cost Optimization: Infrastructure spend reduction through standardization
• Security Posture: Vulnerability reduction, compliance improvements
• Velocity Impact: Team throughput before/after platform adoption
• Operational Efficiency: Reduced toil, automation coverage

Recommended Approach (DX Core 4 Framework):

Combine quantitative DORA metrics with:

1. Speed: Deployment frequency, lead time
2. Effectiveness: Self-service success, time to value
3. Quality: Change failure rate, security posture
4. Business Impact: Cost savings, team efficiency

Report all four dimensions together. A platform that raises deployment frequency while change failure rate climbs is not a win, and only the combined view makes that visible.

Platform metrics tracking example:

// Platform metrics collection example
interface PlatformMetrics {
  deployments: {
    total: number;
    viaGoldenPath: number;
    selfService: number;
    requiredSupport: number;
  };
  adoption: {
    totalTeams: number;
    teamsUsingPlatform: number;
    activeUsers: number;
  };
  performance: {
    avgTimeToFirstDeploy: number; // days
    avgSelfServiceDuration: number; // minutes
    supportTickets: number;
  };
  satisfaction: {
    npsScore: number;
    surveyResponses: number;
  };
}

// Track golden path usage
function trackDeployment(method: 'golden-path' | 'custom' | 'manual') {
  metrics.deployments.total++;
  if (method === 'golden-path') {
    metrics.deployments.viaGoldenPath++;
  }
  // Golden path adoption rate
  const adoptionRate =
    (metrics.deployments.viaGoldenPath / metrics.deployments.total) * 100;

  console.log(`Golden path adoption: ${adoptionRate.toFixed(1)}%`);
}

Common Anti-Patterns and Pitfalls

Strategic Anti-Patterns

Confusing Platform with Portal

• Reality: Platform is backend APIs, orchestration, and golden paths
• Portal is just the UI layer
• Fix: Build solid backend first, UI second

Not Treating Platform as Product

• Symptom: Low adoption, developer frustration
• Root cause: Building without user research
• Fix: Apply product management practices, treat developers as customers

Top-Down Mandates Without Buy-In

• Problem: Forces developers to use tools they don’t want
• Impact: Resistance, workarounds, shadow IT
• Fix: Make platform best option through superior experience

“Field of Dreams” Mentality

• Mistake: “Build it and they will come”
• Reality: Platform must solve actual developer pain
• Fix: Start with research, validate with pilots

Implementation Anti-Patterns

Starting with Biggest/Most Critical Service

• Risk: Too much pressure on nascent platform
• Impact: Failed pilot damages platform credibility
• Fix: Start with friendly team, non-critical service

Overly Complex Platforms

• Symptoms: Unfamiliar config formats, no documentation, inconsistent APIs
• Impact: Developers avoid platform
• Fix: Simplicity first, consistency always, document everything

Over-Reliance on Ticket Systems

• Problem: Tickets create bottlenecks, reduce autonomy
• Impact: Slow delivery, developer frustration
• Fix: True self-service, minimal approval workflows

Templates-as-a-Service Only

• Problem: Rigid templates, no customization
• Impact: Workarounds, shadow IT, abandoned templates
• Fix: Templates as starting point, allow customization within boundaries

Organizational Anti-Patterns

Skill Concentration Trap

• Mistake: Moving all senior engineers to platform team
• Impact: Knowledge gaps in development teams
• Fix: Balanced team distribution, rotate people

Underinvested Platforms

• Symptom: Platform team disbands after initial delivery
• Impact: Platform becomes unmaintained anchor
• Fix: Long-term investment commitment, ongoing team

Lack of Cost Controls

• Problem: Self-service without spending limits
• Impact: Runaway cloud costs
• Fix: Budget controls, automated spending limits, cost visibility

Anti-Pattern	Symptom	Fix
Portal-First	No backend APIs	Build orchestration first
No Product Thinking	Low adoption	User research, feedback loops
Mandatory Platform	Resistance	Make it best option
Complex Config	Developers avoid it	Simplify, document
Ticket-Driven	Bottlenecks	True self-service
Skill Concentration	Knowledge gaps	Balanced distribution
Underinvestment	Abandoned platform	Long-term commitment
No Cost Controls	Cloud bill shock	Automated limits

Getting Started: Practical Roadmap

Phase 1: Foundation (Weeks 1-4)

• Identify 3-5 biggest developer pain points (surveys, interviews)
• Define platform vision and success metrics
• Form initial platform team (2-3 people)
• Choose pilot team (friendly, non-critical service)
• Document current state (tools, workflows, pain points)

Phase 2: MVP Development (Weeks 5-12)

• Build one golden path (e.g., standard API service template)
• Create basic service catalog (manual is fine)
• Implement self-service workflow (CLI or simple UI)
• Write clear documentation
• Deploy pilot with friendly team

Phase 3: Validation (Weeks 13-16)

• Gather pilot feedback (what works, what doesn’t)
• Measure baseline metrics (time to deploy, satisfaction)
• Iterate on golden path based on feedback
• Expand to 2-3 more teams
• Document learnings and adjust roadmap

Phase 4: Scale (Months 5-12)

• Add 2-3 more golden paths (common use cases)
• Build or adopt developer portal (Backstage/Port decision)
• Integrate observability and security
• Implement cost controls
• Scale to 25-50% of organization
• Establish support channels

Phase 5: Mature (Year 2+)

• Continuous improvement based on metrics
• Advanced features (AI assistance, automated optimization)
• Cross-team collaboration features
• Platform API stability and versioning
• Community building (internal user groups)

Quick win ideas for early momentum:

1. Standardized service template: New service in < 30 minutes
2. One-click environment: Ephemeral dev/test environments
3. Automated security scanning: Build into pipelines
4. Cost dashboards: Show teams their spend
5. Onboarding automation: New engineer productivity in < 1 day

When the Default Holds

The narrow default (one golden path, one pilot team, backend before portal, adoption measured by voluntary use) holds while the platform is young and the organization sits under a few hundred engineers. It also holds longer than most teams expect, because a second path costs the same maintenance as the first.

Override it in three situations. When a regulator or a security baseline makes a path mandatory rather than optional, adoption stops being the signal and compliance coverage takes its place. When the catalog is already the only reliable inventory of who owns what, the portal earns its place early instead of last. And when the platform team is large enough to keep several paths current at once, breadth beats depth.

The useful next step is the smallest one: take the pain point every team complains about and build one route through it that needs no ticket.

References

• CNCF Platforms White Paper - CNCF TAG App Delivery canonical definition of internal developer platforms, capabilities, and maturity levels
• Platform Engineering Maturity Model - CNCF guidance on progressing from ad-hoc tooling to managed, optimized platform products
• What is Platform Engineering? - CNCF - CNCF’s current definition of platform engineering, its goals, and its relationship to DevOps
• Platform as a Product - platformengineering.org - Community resource on applying product thinking to internal developer platforms
• Team Topologies - Platform Engineering - How Team Topologies’ “platform team” and “thinnest viable platform” concepts apply to IDP design
• What is Platform Engineering? - platformengineering.org - Community definition and foundational reading on platform engineering goals and golden paths
• DORA - Source for the four key metrics and the performance benchmarks quoted in the metrics section
• Backstage - Official documentation for the open source developer portal framework, including catalog entity formats
• Port - Product documentation for the commercial SaaS alternative discussed in the tooling section