Internal Developer Platforms - Architectures for True Self-Service

In the past two years, “Internal Developer Platform” has become a buzzword. However, while Gartner praises the IDP as a remedy for developers’ cognitive overload, many internal projects end up as rigid abstraction layers that create more problems than they solve.

True self-service is not achieved through a fancy GUI but through a well-thought-out technical foundation that views infrastructure as a product.

The Core Issue: The “Abstraction Paradox”

Many platform teams make the mistake of completely hiding Kubernetes from developers. They build complex wrappers around Helm charts or use proprietary portals that cover only 80% of use cases. As soon as a team needs the remaining 20%—such as specific ingress tuning or a sidecar config—the model breaks down, and the manual ticket process returns.

A successful IDP must therefore not hide the technology but define Golden Paths (not “Golden Cages”).

The Pillars of a Robust IDP Architecture

1. Control Plane Instead of Ticket System: Crossplane and the K8s API

Instead of manually executing Terraform scripts, modern IDPs use the Kubernetes API as a universal control plane.

• The Approach: With Crossplane, we define Composite Resources (XRDs). A developer no longer requests an “AWS RDS instance” but an “ayedo-Postgres-DB”.
• The Effect: The complexity of the cloud provider (VPCs, subnets, IAM roles) is encapsulated in the XRD. The developer uses a simple YAML manifest, and the platform takes care of provisioning and drift checking.

2. Orchestrating Workflows: GitOps as Single Source of Truth

An IDP without GitOps is merely a portal for shadow IT. The state of the platform and applications must reside in Git.

• Tools: ArgoCD or Flux are the established standards here.
• Worth Knowing: The crucial step is the integration of ApplicationSets in ArgoCD. This allows for the creation of templates that automatically instantiate environments (Preview, Staging, Prod) in the cluster based on Git repository structures.

3. The Interface: Backstage vs. CLI-First

The “Portal or CLI” debate is often misled. An IDP should offer both.

• Backstage (Spotify): Ideal as a service catalog and for visualizing dependencies (Software Catalog). However, it is not a deployment tool but the showcase of the platform.
• CLI/API: For power users, the platform must remain controllable via the API. Every action in the GUI must also be possible via kubectl or API call to not hinder automation.

Why Many IDP Projects Fail

The most common reason for failure is the lack of consideration for “Cognitive Load”. If the platform is so complex that developers need to read a manual to get an S3 bucket, they will find ways around the platform.

Our experience shows: An IDP is never finished. It must be treated like an external product—including user research with your own developers, documentation, and rapid feedback cycles.

Conclusion: Platform Engineering is Product Management

Building an IDP is a technological challenge but primarily a strategic one. Simply installing Crossplane, ArgoCD, and Backstage does not make a platform. Only the definition of meaningful abstractions and automated workflows turns a collection of tools into an enabling tool.

Technical FAQ: IDP & Platform Engineering

Why use Crossplane instead of Terraform for the IDP? Terraform is excellent for initial bootstrapping. Crossplane, on the other hand, uses the “Reconciliation Loop” principle of Kubernetes. It continuously checks the actual state against the desired state and corrects drift immediately. It also allows developers to manage cloud resources with the tool they already use for their apps: kubectl.

Is Backstage too complex for medium-sized businesses? Backstage is very powerful but requires significant effort for maintenance and plugin development. For smaller teams, a well-structured GitOps repository with clear templates (e.g., via Copier or Cookiecutter) and a simple dashboard can often be more efficient.

How do you measure the success of an IDP? The most important metrics are Lead Time for Changes and Deployment Frequency (DORA Metrics). If developers can deploy faster and more frequently after the platform is introduced without contacting the Ops team, the IDP is successful.