From fragmented inline configurations to a version-controlled, fully validated IDP catalog, built to scale.

Customer Overview

The client is a data-driven enterprise with a mature internal developer portal (IDP) practice, managing a growing catalog of software components and APIs through Harness IDP. As their engineering footprint expanded, the need to modernize their catalog management approach, moving from inline to remote configuration, became a critical initiative to ensure version control, governance, and long-term maintainability.

When Harness released IDP 2.0, the client saw an opportunity to align their catalog infrastructure with the latest standards. They needed a trusted implementation partner to navigate the migration with precision and minimal disruption.

The Challenge

The platform team was operating on an inline catalog configuration that lacked version control and scalability. Transitioning to IDP 2.0 meant navigating a newly released framework with its own set of early-stage limitations, while keeping critical pipelines operational.

Key challenges included:

• Inline Configuration Debt: All catalog entities (Components and APIs) were stored inline, with no remote version control in place.

• Syntax Overhaul Required: The existing YAML structure was built on older Backstage conventions and required a full rewrite to conform to IDP 2.0 specifications.

• Pipeline Fragility: The primary "All In One" pipeline, responsible for IDP OpenAPI spec validation and API definition generation, began failing immediately after IDP 2.0 was enabled.

• Framework Gaps: IDP 2.0, being newly launched, did not yet support multi-branch entity storage within a single repository or custom user group creation at the time of implementation.

• Script Dependency: The client's existing Python scripts for catalog entity lifecycle management (create, update, delete) were incompatible with the new IDP 2.0 framework.

The Breaking Point: 

What began as a structured migration quickly became a live troubleshooting exercise. With most IDP functionalities failing post-enablement and the primary validation pipeline non-operational, the client needed immediate, expert-led resolution, not just implementation support.

The Avyka Approach

Avyka took full ownership of the migration, partnering directly with the Harness IDP expert team to resolve framework-level limitations while simultaneously delivering on all client requirements.

Solution Overview

• IDP 2.0 Enablement: Raised a Harness support ticket to activate IDP 2.0 within the client's account, initiating the automatic conversion of existing entities, scorecards, and plugins.

• Manual Catalog Migration: Transitioned all catalog entities, Components and APIs, from inline to remote configuration for robust version control.

• YAML Re-architecture: Rewrote entity YAML structures, syntax, and spec blocks to fully comply with IDP 2.0 standards, moving away from legacy Backstage conventions.

• Python Script Modification: Overhauled the client's existing Python scripts to support entity lifecycle management within the new IDP 2.0 framework.

• Pipeline Validation: Triggered the "All In One" pipeline via a GitHub PR, successfully passing all IDP OpenAPI spec and API definition checks post-migration.

• Staged Feature Integration: As Harness released updates supporting multi-branch entity storage and custom user groups, these capabilities were immediately integrated to close remaining use-cases.

What We Did

Engineering Insights

• New Frameworks Come With Moving Parts: IDP 2.0's early limitations, including restricted multi-branch support and absent custom user group functionality, required real-time collaboration with the Harness product team rather than relying solely on documentation. Building a direct escalation path proved essential.

• Script Ownership is Migration Ownership: The client's Python-based entity management scripts were a hidden dependency that surfaced only post-enablement. Auditing and adapting automation scripts should be a first-order concern in any IDP framework migration.

• Stage Your Integration: Rather than waiting for the framework to be feature-complete before proceeding, we adopted an iterative approach, delivering core migration first and integrating newly released capabilities (multi-branch, custom groups) as they became available, keeping the project moving without blocking on vendor timelines.

Results

The migration delivered a stable, future-ready IDP catalog environment with every client objective met:

• Full Catalog Migration: All Component and API entities successfully transitioned from inline to remote, version-controlled configuration.

• Pipeline Restored & Validated: The "All In One" pipeline, including IDP OpenAPI spec and API definition checks, passed successfully following migration.

• Zero Blocked Use-Cases: All requirements, including multi-branch entity storage and custom user group creation, were fulfilled upon feature availability.

• Increased Client Trust: Avyka's ownership of the Python script modifications and proactive issue resolution significantly strengthened the client relationship.

• IDP 2.0 Ready: The client now operates on a fully compliant, scalable IDP 2.0 environment positioned for future growth.

Conclusion

Migrating to a newly released framework is never without turbulence, but with the right approach, early limitations become solvable problems rather than project blockers. By taking complete ownership of the migration, rewriting the underlying scripts, and maintaining a direct line with the Harness IDP team, Avyka delivered a robust IDP 2.0 environment that met every requirement the client set out with.

The result is a version-controlled, governed, and fully validated internal developer portal, built to scale with the client's engineering ambitions.