An Introduction to Platform Engineering and IDPs (Internal Developer Platforms) — How Developers Can Focus on Code Without Worrying About Infrastructure

Honestly, when I first heard the term "platform engineering," I thought it was just a rebrand of DevOps. If you've ever wrestled with hundreds of lines of Kubernetes YAML, burned half a day configuring a CI/CD pipeline, or filed a ticket with the infrastructure team and waited days just to spin up a single new service — you'll probably relate. But when I actually dug into it, this wasn't a simple rebrand. It was an attempt to change the very premise that "you need to understand infrastructure to deploy" — and once you introduce the resulting artifact, an IDP (Internal Developer Platform), you get to experience firsthand how creating a new service shrinks down to a few button clicks.

An IDP is an internal product that abstracts away complex operational concerns, allowing developers to self-service and provision the resources they need directly. As of 2025, 55% of all organizations have already adopted one, and Gartner projects that figure will reach 80% by 2026 (source: Port.io, 2025 State of Internal Developer Portals). This post covers what platform engineering is, how an IDP works in practice, and the pitfalls you absolutely need to know before adopting one. By the end, you'll be ready to run a Backstage local demo in under 10 minutes with a single line: npx @backstage/create-app@latest.

Core Concepts

What's the Difference Between DevOps and Platform Engineering?

If DevOps addresses why development and operations should collaborate, platform engineering addresses how to make that collaboration easy for every developer. DevOps is a philosophy; platform engineering is the strategic approach that puts that philosophy into practice.

Platform Engineering: The engineering discipline of designing, building, and maintaining self-service infrastructure and tooling so that software development teams can deploy and operate applications efficiently. The key concepts are self-service and abstraction.

The 6 Core Components of an IDP

When you first encounter an IDP, you might think "isn't this just a developer portal?" — but it's actually a much broader concept. Among these components, the software catalog is typically the first one where you feel real value in practice. Just being able to find out "how many services does our team have?" without asking on Slack already changes your productivity.

FinOps: An operational approach that connects cloud costs to engineering decisions and makes them visible. When integrated into an IDP, it can show estimated costs before a deployment or send alerts when a cost threshold is exceeded.

Policy-as-Code: An approach where security and compliance policies are defined as code and enforced automatically. Implemented with OPA or Kyverno, it lets you manage rules like "block deployments using unapproved base images" as code.

What Is a Golden Path?

It's one of the most frequently mentioned concepts in practice, and it's simpler than it sounds. It's a standard workflow where the team's validated best practices are templatized so that "if you follow this path, security, monitoring, and CI/CD come along automatically."

Below is an example of defining a golden path template in Backstage. For working code, we recommend consulting the official Backstage docs — this is a simplified example intended to illustrate the structure.

# Golden Path Template Example (Backstage catalog-info.yaml) — simplified conceptual example
apiVersion: scaffolder.backstage.io/v1beta3
kind: Template
metadata:
  name: spring-boot-api
  title: Spring Boot REST API
  description: Standard API service with built-in security, monitoring, and CI/CD
spec:
  owner: platform-team
  type: service
  parameters:
    - title: Service Basic Info
      properties:
        serviceName:
          type: string
          description: Service name (lowercase, hyphens allowed)
        owner:
          type: string
          description: Owning team
  steps:
    - id: fetch-template
      name: Generate Template Code
      action: fetch:template
      input:
        url: ./skeleton
        values:
          serviceName: ${{ parameters.serviceName }}
          owner: ${{ parameters.owner }}
    - id: create-github-repo
      name: Create GitHub Repository
      action: publish:github
      input:
        repoUrl: github.com?repo=${{ parameters.serviceName }}&owner=my-org
    - id: register-catalog
      name: Register in Service Catalog
      action: catalog:register
      input:
        repoContentsUrl: ${{ steps['create-github-repo'].output.repoContentsUrl }}

Golden Path Core Principle: It's a recommendation, not a mandate. It's good practice to always provide an "Ejection" escape hatch — a way to take direct control of lower-level settings — for senior engineers who want finer-grained control. For example, you might add a platformOverride: true field, or provide a separate raw namespace free of platform constraints.

The Key Tool Ecosystem

Practical Applications

Let's look at how the concepts covered above are actually used in the field, through three case studies.

Example 1: Spotify's Backstage Adoption — From Chaos to Order

When I first researched Backstage, I came across the Spotify case and thought, "Ah, this was built to solve a real problem." In 2016, rapid growth led to hundreds of microservices proliferating, and it became difficult to even track what services existed or where. By the time they open-sourced it, they were already managing 280 engineering teams, 2,000 backend services, and 4,000 data pipelines on a single platform.

Once services are registered in the software catalog, you can check the owner, dependencies, and API documentation all in one place.

// Backstage Software Catalog — Example of customizing a service detail page
// packages/app/src/components/catalog/EntityPage.tsx
import {
  EntityAboutCard,
  EntityDependsOnComponentsCard,
  EntityHasApisCard,
} from '@backstage/plugin-catalog';
 
export const serviceEntityPage = (
  <EntityLayout>
    <EntityLayout.Route path="/" title="Overview">
      <Grid container spacing={3}>
        <Grid item md={6}>
          <EntityAboutCard variant="gridItem" />
        </Grid>
        <Grid item md={6}>
          <EntityHasApisCard variant="gridItem" />
        </Grid>
        <Grid item md={12}>
          <EntityDependsOnComponentsCard variant="gridItem" />
        </Grid>
      </Grid>
    </EntityLayout.Route>
  </EntityLayout>
);

The real value here isn't the code itself — it's the outcome. When you open a service page, "what APIs does this service expose" and "what components does it depend on" are automatically visualized, making it possible to find out without asking on Slack.

Example 2: An Typical Enterprise IDP Adoption — From Developer Request to Deployment

This is the most common pattern I encounter in practice. You need to create a new service, but you also have to know Kubernetes, provision a DB, and manage secrets. Whether it's a backend Spring Boot API, a Next.js frontend app, or a mobile team's build pipeline — the stack varies, but this flow applies the same way. With an IDP, it changes to look like this:

Developer Request (select service name and stack in the portal UI)
    ↓
Golden Path Template Auto-Applied
(Spring Boot API / Next.js App / Mobile Build Pipeline / etc.)
    ↓
Infrastructure Auto-Provisioned
    - Kubernetes namespace created
    - PostgreSQL instance created
    - Secrets auto-registered in Vault
    ↓
CI/CD Pipeline Auto-Connected (GitHub Actions / ArgoCD)
    ↓
Monitoring & Alerts Auto-Connected (Grafana dashboard auto-generated)
    ↓
Deployment Complete — the developer just needs to push code

When I first saw this flow, I thought "seriously?" — but after trying Crossplane, it works. Crossplane lets you declaratively manage cloud resources with Kubernetes CRDs, making it possible for developers to provision a DB without writing a single line of YAML.

# Example of environment provisioning with Crossplane
# The developer doesn't write this YAML directly —
# the platform team defines it in advance as a Composition (Custom Resource),
# and the developer just clicks a button in the portal UI to auto-create the resources below
apiVersion: platform.example.com/v1alpha1  # Custom Resource defined by the platform team
kind: AppEnvironment
metadata:
  name: my-new-service-dev
spec:
  parameters:
    region: ap-northeast-2
    dbSize: small
    replicas: 2
# The Crossplane Composition receives this Claim and automatically handles:
# - RDS PostgreSQL instance (AWS resource)
# - Kubernetes Namespace + RBAC
# - Vault Secret Path
# - Grafana Dashboard

Think of a Composition as the platform team defining "what bundle of resources to create" once, and a Claim as the object a developer uses to say "I need this environment." Once a Composition is created, developers no longer need to know anything about the cluster or RDS directly.

Example 3: Netflix's Federated Platform Console

I came across the Netflix case while evaluating Backstage adoption, and it has particularly strong implications for organizations with a lot of legacy systems. Netflix leveraged Backstage's loose coupling between frontend and backend, keeping their existing Federated GraphQL backend in place and using Backstage only as a frontend layer.

The reason this approach works well for legacy environments is clear. Replacing internal backend systems that have been built up over years carries high risk and cost. Using Backstage only as a UI integration layer lets you unify the developer experience while keeping existing APIs and data sources connected as-is. This was the case that dispelled the misconception that "you have to throw away existing systems to adopt an IDP."

Pros and Cons Analysis

Advantages

Additional note for senior engineers: What an IDP provides beyond simple convenience is significant. If you're interested in how to structure a platform team and measure KPIs (DORA metrics integration, platform NPS, etc.), we recommend Team Topologies and the CNCF Platforms Working Group's maturity model.

Disadvantages and Caveats

Listing all the disadvantages in a single table tends to blur priorities, so I've separated them by organizational, technical, and cost/decision-making perspectives.

Organizational Perspective

Technical Perspective

Cost & Decision-Making Perspective

The Most Common Mistakes in Practice

These are patterns that repeatedly appear in teams that are evaluating or have actually operated an IDP. Knowing them in advance will let you avoid at least half of them.

1. Treating the platform as a project — An IDP isn't something you build once and finish; it's an internal product that continuously evolves. Starting without product ownership and a roadmap turns it into an abandoned tool six months later. You should be able to immediately answer the question "Who is the PM of this platform?"

2. Building without developer feedback — The abstractions a platform team thinks are good may actually be inconvenient for real developers. Running internal user interviews and collecting usage metrics from the beginning is recommended. Simply keeping a channel open where people can say "this feature is annoying" is enough to change your direction.

3. Trying to build the perfect Golden Path all at once — It's common to try to cover every stack from the start and end up doing nothing properly. A more realistic approach is to start with the one stack your team uses most and expand incrementally.

Closing Thoughts

An IDP is the culmination of DevOps — making infrastructure invisible. Creating an environment where a developer's decision of "I'm going to build this service" is all it takes for everything else to follow — that's the direction platform engineering is heading.

Not every team needs to build a full-stack IDP right away. You can start at a scale that fits your situation.

Three steps you can start right now:

1. (30 minutes) Identify your team's current pain points — Ask your teammates "what takes the most time when creating a new service?" For a 5-person startup, this conversation alone will give you direction. For organizations of 50 or more, it's recommended to first formalize team interviews. The recurring complaints become the first targets for your IDP.

2. (10 minutes) Run the Backstage local demo — You can spin up Backstage locally in under 10 minutes with npx @backstage/create-app@latest. Registering just a few of your team's services in the software catalog is enough to experience the value of an IDP firsthand.

3. (1 hour) Draft your first Golden Path — Pick one service type your team creates most often (e.g., REST API, batch job, Next.js app) and start by documenting the configuration checklist you repeat every time you create a new service. This will later become the seed of your Backstage template.

Next Post: A hands-on Backstage adoption story — covering everything from building a software catalog to deploying Golden Path templates, including the trial-and-error and solutions encountered during real-world implementation.

References

• What is an Internal Developer Platform (IDP)? | internaldeveloperplatform.org
• Platform engineering vs. DevOps | Google Cloud
• Platform Engineering vs. DevOps | Red Hat
• Internal Developer Platforms: Top 5 Use Cases & Key Components | Octopus Deploy
• Internal Developer Platform Benefits + Best Practices | Atlassian
• Top 11 Internal Developer Platforms in 2025 | Cycloid
• Top 20 Platform Engineering Tools 2026 | Spacelift
• Celebrating Five Years of Backstage | Spotify Engineering
• How Netflix Unified Engineering Experience | platformengineering.org
• 2025 State of Internal Developer Portals | Port.io
• Platform Engineering in 2026: The Numbers Behind the Boom | DEV Community
• Golden Paths Guide | platformengineering.org
• Navigating Internal Developer Platforms in 2025 | Infisical
• How to Set Up an Internal Developer Platform | platformengineering.org