Best Practices

The hardest parts of running an IDP are organizational, not technical.

Platform as Product

The single most important framing: your IDP is a product, your engineers are the customers.

This means:

• A product manager for the platform (could be the platform tech lead with a real PM mindset).
• User research: regular interviews with engineers. What's friction? What golden paths would help?
• A roadmap, published, with priorities. Engineers know what's coming.
• Metrics: time-to-first-deploy, % of services on golden paths, adoption rates per template.
• Sunset paths: deprecate old patterns, with timeline and migration help.

Without product thinking, the platform becomes a list of half-done features that nobody uses.

Adoption Strategy

Most platforms fail not because they're badly built but because nobody adopts them. Strategies:

Pilot with friendly teams first

Pick 2-3 teams that have real pain and are willing to be early adopters. Build the templates they need. Get them shipping faster. Make them visible internally as case studies.

Don't force adoption (too early)

Mandating "all new services must use the template" before the template is good produces hatred. Make the templates so good that not using them is the friction.

Later, when the platform is solid, you can require golden paths for production services — but only after demonstrating value.

Measure satisfaction

NPS / CSAT survey quarterly. "How likely are you to recommend the platform to a peer?" If trending down, stop adding features and fix what's broken.

Office hours

A regular slot for platform questions. Engineers learn the platform, platform team learns pain points. Cheap and effective.

Scaling the Platform Team

Headcount per platform engineer:

The Team Topologies model is useful: platform team supplies APIs (golden paths, catalog) consumed by stream-aligned product teams.

Don't Out-Build Your Vendor

A common trap: the platform team builds custom plugins for things commercial vendors already provide. Months later, the homegrown plugin breaks on a Backstage upgrade.

Buy commodities; build differentiators:

• Buy: CI runners, monitoring backend, secrets store, portal hosting (Port / Roadie).
• Build: golden path templates, scorecards specific to your org, integrations with your unique systems.

The 80/20: commodities are 80% of the platform code but 20% of the value. Inverted ROI.

Documentation Is Part of the Platform

A platform without docs isn't a platform; it's a maze.

• Every template has a README explaining what it does, when to use it.
• Every plugin has a page explaining the integration and any caveats.
• A "getting started for engineers" guide that walks a new hire through their first scaffolded service.
• Runbooks: when the platform itself breaks, who fixes it and how.

TechDocs makes this easy because docs live next to the platform code.

Backstage-Specific

Notes from running Backstage in production:

• Upgrades are work. Backstage moves fast; upgrade quarterly to avoid 8-version jumps. Test before rolling.
• Database matters. Postgres only at any real scale; SQLite is dev-only.
• Catalog ingestion can be slow. Tune the schedule for your org size; consider entity providers over polling.
• Custom plugins are expensive. Each one is a maintenance burden; weigh ROI carefully.
• Plugin compatibility breaks on upgrade. Pin versions; test plugins as part of the upgrade gauntlet.
• Auth complexity grows. Multi-team RBAC needs design upfront; permission framework is non-trivial.

For many orgs, Port or Roadie (hosted Backstage) is the right answer — you focus on golden paths, they handle the infra.

Don't Reinvent Auth

The portal needs to know who the engineer is, which team, what they can do. Don't build a user database.

• SSO via your IdP (Okta, Google, Auth0, Keycloak): use OIDC.
• Group membership from your IdP: maps to Backstage groups; powers RBAC.
• No local accounts, no separate password.

A new hire gets portal access automatically when added to the IdP's engineering group. They lose it when they leave.

Compliance Integration

The catalog is your compliance gold mine:

• Asset inventory: every service is in the catalog (SOC2 CC6, ISO 27001 A.8).
• Ownership: every service has a team; team has on-call (SOC2 CC7).
• Change management: linked to GitOps PR / CI history (SOC2 CC8).
• Access control: portal RBAC + IdP integration evidences (SOC2 CC6.3).
• Operational evidence: dashboards, SLOs, incident history linked per service.

Auditors love a portal that answers "what runs in production?" in one query.

Common Pitfalls

Building before knowing what to build. Spending 6 months on Backstage with no concrete golden paths in mind. Pick 2-3 concrete pain points first; build to those.

Plugin proliferation. Installing every plugin "in case." Each one is config and maintenance. Curate; remove what nobody uses.

The catalog as graveyard. Services tagged "production" with no deploy in 2 years, owners that left, dependencies that no longer exist. Quarantine quarterly.

No metrics on platform value. "Do engineers use it? We don't know." Track lead time, deploy frequency, time-to-first-PR for new hires; measure how the platform moves them.

Treating onboarding as one-time. A new engineer onboards once, but new services onboard constantly. Optimize for service onboarding more than engineer onboarding.

The senior engineer who hates the portal. Senior engineers know the underlying tools and feel the portal as friction. The portal is for the median engineer; seniors should be able to bypass for legitimate reasons.

Platform team that doesn't ship product code. They drift from the engineer experience. Have platform engineers occasionally embed in product teams to feel the pain.

Mandate before product-market fit. Forcing all teams onto the platform before it's actually good. Earn adoption; don't decree it.

Sunsetting Old Paths

When you replace a golden path:

1. Announce deprecation with a clear migration timeline (3-6 months typical).
2. New services blocked from the deprecated path.
3. Existing services get migration helpers (scaffolder for the new pattern, scripts that transform old → new).
4. Office hours scheduled for migration help.
5. After the deadline, removed entirely.

Don't leave deprecated paths up "just in case." They confuse new engineers and dilute the canonical answer.

Checklist

What's Next

You have an IDP practice. Connect it to:

• GitOps — IDP creates intents; GitOps enforces them
• CI/CD — IDP scaffolds CI; CI builds; GitOps deploys
• Monitoring — service dashboards embedded in catalog
• FinOps — cost per service visible in catalog
• Policy as Code — golden paths emit compliant resources