Developer platforms & IDPs (Backstage/Roadie) — Real‑World Case Study — Practical Guide (Apr 26, 2026)

Developer platforms & IDPs (Backstage/Roadie) — Real‑World Case Study

Level: Intermediate

As of April 26, 2026

Organisations adopting Cloud Native and microservices architectures face an evolving challenge: increasing developer velocity without compromising governance or discoverability. Internal Developer Platforms (IDPs) like Spotify’s Backstage have rapidly matured as foundational tools to centralise infrastructure, tooling, and service metadata. Roadie, a hosted commercial offering built on Backstage, simplifies onboarding and scaling.

This article presents a practical case study based on real-world usage spanning Backstage 1.10.x through 1.13.x and Roadie’s latest platform as of early 2026. We’ll share prerequisites, hands-on steps to onboard services, common pitfalls, and validation techniques. Whether you’re considering IDPs for the first time or scaling an existing platform, this guide delivers actionable insights.

Prerequisites

Setting up or extending a developer platform with Backstage or Roadie requires some prior foundations:

Active Kubernetes cluster: Backstage plugins often integrate with Kubernetes (K8s) APIs to surface live service status and deployment metrics. Clusters must be reachable and authentication (e.g. via OIDC or kubeconfig) configured.
Single Sign-On (SSO): Backstage supports multiple authenticators (OIDC, LDAP, SAML). Setting these up ensures secure, seamless developer experience.
Service metadata repository: Structured metadata, typically in catalog-info.yaml files stored in Git, describing each service, resource, or library. Essential for catalog-driven navigation.
Familiarity with Backstage software catalog principles: Understanding concepts like Components, APIs, and Domains is key. See the official docs under Software Catalog.
Access to Roadie or self-hosted Backstage environment: Roadie manages cloud-based Backstage with managed upgrades and plugins, good for rapid adoption. Self-hosting requires managing your CI/CD pipelines, backend, and plugin ecosystem.
Basic YAML and Git proficiency: Service entries are defined declaratively and version controlled.

When to choose Backstage self-hosted vs Roadie

Self-hosting Backstage offers flexibility, plugin customisation, and full control of infrastructure—but also requires more operational effort. Roadie provides a hosted experience with managed upgrades, pre-integrated plugins, and enterprise support, which accelerates time to value.

Roadie is recommended for organisations prioritising rapid onboarding and minimal maintenance, or with smaller DevOps teams. Self-hosted is preferred for complex, bespoke workflows or strict compliance requirements.

Hands-on steps: Onboarding a microservice into Backstage/Roadie

Here we focus on the common core flow of onboarding a service represented as a Git repository with manifest files.

1. Define `catalog-info.yaml`

Each component must declare its metadata in a standard schema. Below is an example for a simple microservice:

apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: payment-service
  description: Handles all payment transactions
  tags:
    - payments
    - backend
spec:
  type: service
  lifecycle: production
  owner: team-payment
  providesApis:
    - payment-api
  consumesApis:
    - user-api

You store this YAML file in your service’s Git repository, typically at the root or under a /catalog folder.

2. Register the component in Backstage catalog

Logged into your Backstage/ Roadie portal, navigate to “Create” > “Register Existing Component”. Provide the Git URL and select or confirm the catalog-info.yaml file location.

Backstage will parse and validate the entity and add it to the software catalog, triggering metadata ingestion.

3. Connect source code & pipelines

Integrate your repository with CI/CD tools like GitHub Actions, Azure DevOps, or Jenkins. Backstage plugins can link pipeline run data (build status, test coverage) back into the developer portal UI.

Example GitHub Actions snippet providing status badges:

name: CI

on:
  push:
    branches:
      - main

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Build and Test
        run: |
          ./gradlew clean build

4. Configure plugins to enrich developer experience

TechDocs plugin: Generate and host Markdown or MkDocs documentation inside Backstage.
Kubernetes plugin: Show live pod and deployment status of your services.
Cost insights (preview): Visualise cloud cost attribution per service. Currently a preview feature in Backstage 1.13.x.

Example snippet to enable the Kubernetes plugin in app-config.yaml:

kubernetes:
  clusterLocatorMethods:
    - type: config
      clusters:
        - name: prod-cluster
          url: https://k8s.example.com
          authProvider: serviceAccount

Common pitfalls

Incomplete or inconsistent catalog-info.yaml: Missing required fields, incorrect API versions, or inconsistencies cause ingestion errors or missing entities in UI.
Authentication misconfigurations: Backstage SSO setup can be complex. Misconfigured OIDC issuers or callback URLs commonly block sign-in.
Plugin version mismatches: Plugins like Kubernetes or TechDocs must align with the Backstage core version to avoid runtime errors.
Ignoring plugin permissions: Kubernetes plugin requires API credentials with appropriate RBAC permissions scoped to namespaces.
Neglecting scalability: Large organisations must consider catalog refresh rates and caching to maintain responsiveness.

Validation

Verify the onboarding workflow by:

Confirming the service appears in the software catalog with correct metadata.
Checking documentation is rendered via TechDocs plugin.
Viewing CI/CD pipeline status badges on the component page.
If using Kubernetes plugin, confirm live cluster data reflects actual deployments.
Testing SSO by logging out and logging back in, observing permissions.

Use the Backstage CLI tool catalog-info-check to lint your YAML files before commit:

npx @backstage/catalog-info-check --path ./catalog-info.yaml

Checklist / TL;DR

Ensure Kubernetes cluster access and SSO configured.
Define complete catalog-info.yaml for each component.
Register components through Backstage UI or CLI.
Connect CI/CD pipelines and integrate status plugin(s).
Configure additional plugins (TechDocs, Kubernetes, cost insights preview).
Validate YAML syntax and run catalog lint checks.
Monitor plugin and platform versions compatibility.
Review RBAC and API permissions thoroughly.