Understanding IDP Core Components and Self-Service

Introduction

In our last lesson, we explored the strategic "why" behind modern platform engineering, establishing that a successful platform must be treated as a product, not a project. We focused on the mindset shift required to serve internal developers as customers, with the ultimate goals of reducing their extraneous cognitive load and enabling economies of speed.

This session transitions from strategy to architecture. Our objective is to identify the core components of an Internal Developer Platform (IDP) and understand how they work together to provide the developer self-service capabilities we've discussed. We will dissect the blueprint of a modern IDP, moving from a high-level conceptual model to the specific components and tools that bring it to life. For a senior engineer, this means connecting the abstract principles to the concrete system design that makes them a reality.

The Architectural Blueprint: The Five Planes of an IDP

Before diving into individual tools, it's helpful to have a conceptual framework. Modern IDPs, regardless of the specific technologies used, can be understood as a collection of integrated capabilities organized into five distinct "planes."

This short video from the Platform Engineering community provides a clear and concise overview of this model.

What is an Internal Developer Platform?

This video introduces the five conceptual planes that form the standard architectural pattern for an IDP.

Please watch the segment from the five planes. Pay attention to the role each plane plays in the overall system.

As the video explained, these five planes are:

Developer Control Plane: This is the user interface of the platform. It's how developers interact with the system. This can be a UI-based developer portal (like Backstage), a command-line interface (CLI), an API, or a code-based workload specification file checked into a repository.
Integration & Delivery Plane: This is the engine that takes a developer's request and makes it a reality. It includes CI/CD pipelines, image registries, and, most importantly, a Platform Orchestrator that translates developer intent into specific infrastructure configurations.
Resource Plane: This plane contains the actual infrastructure components that the platform manages—Kubernetes clusters, databases, object storage, DNS services, etc.—whether on-premise or in the cloud.
Security Plane: This layer handles all aspects of security, including identity management, Role-Based Access Control (RBAC), policy enforcement, and secret management.
Monitoring & Logging (Observability) Plane: This provides the necessary tooling for logging, metrics, and tracing, giving both platform and application teams visibility into the health and performance of their services.

The following diagram illustrates how these planes are composed using real-world tools across different cloud environments.

These diagrams show reference architectures for IDPs on AWS, Google Cloud, Azure, and a multicloud setup. Each one is organized according to the five planes, demonstrating how different tools (e.g., GitHub, Score, Humanitec, Datadog, Vault) fit into this standardized structure.

This five-plane model provides a powerful mental map for understanding where any given tool or process fits within the broader platform architecture.

The Building Blocks of Self-Service

Now let's zoom in from the high-level planes to the specific components that enable developer self-service. A well-designed IDP is more than just a collection of tools; it's a curated experience built from a set of core functional components.

The following resource provides a clear, structured list of these components.

Platform Engineering with Internal Developer Portals: The Complete Guide to Building Self-Service Infrastructure | policyascode.dev

This guide offers a great breakdown of the fundamental components of an IDP, presented in a YAML format that clearly outlines their features.

Please read the section IDP Fundamentals. Focus on the list under "IDP Architecture Components" to understand the role of each element.

As you just read, the key components that enable a self-service experience include:

Service Catalog: A centralized, searchable registry of all software, services, APIs, and resources. It answers the questions: "What services do we have?", "Who owns them?", and "How do they relate to each other?". This is the "front door" to the platform.
Software Templates: Also known as "scaffolding," these are pre-defined templates for creating new services or resources. They instantiate "golden paths" by automatically including best practices for security, logging, CI/CD, and deployment from day one.
Tech Docs: A centralized system for technical documentation, often co-located with the services in the catalog. This ensures that knowledge is discoverable and maintained, reducing the need to ask colleagues for basic information.
Workflows: These are the automated processes that execute tasks. This can range from a CI/CD pipeline to a complex workflow that provisions a new environment with a database, message queue, and DNS entry, all triggered by a single developer action.
Scorecards: A mechanism for defining and tracking service health, quality, and compliance. Scorecards provide a feedback loop to developers, showing them how their service stacks up against production readiness checklists, security standards, or performance benchmarks.

The Engine Room: Workload Specs and the Platform Orchestrator

The magic of an IDP lies in how it connects a developer's simple request to the complex reality of provisioned infrastructure. This is handled by two critical components working in tandem: the workload specification and the Platform Orchestrator.

The diagram below illustrates this core workflow.

A developer defines WHAT their service needs in a simple YAML file (a workload spec like Score). This is passed to the Platform Orchestrator, which uses context (e.g., "staging") and pre-defined rules to dynamically generate the complex configurations needed to provision the resources (the resource graph on the right).

This workflow separates the developer's concern (the what) from the platform's concern (the how). The following resource from Humanitec, the company behind the Score specification and a leading Platform Orchestrator, explains these two components in detail.

How to build an Internal Developer Platform | Humanitec

This article details the roles of the Platform Orchestrator and the Score specification as core components of a modern IDP.

Please read the two subsections under "Core components": Platform Orchestrator and Score.

To summarize this crucial relationship:

The Workload Specification (e.g., Score) is a simple, environment-agnostic file where a developer declares their workload's runtime requirements. For example: "My service is a container, it needs a Postgres database, and it requires 5GB of file storage."
The Platform Orchestrator is the central brain of the IDP. It takes the workload specification as input, combines it with context (e.g., "deploying to the production environment"), and dynamically generates the detailed configuration files required for all the underlying tools (e.g., Kubernetes manifests, Terraform files, cloud provider settings).

This dynamic configuration management is what enables true self-service. The platform team sets the rules and baselines within the orchestrator, and developers can then provision complex, compliant infrastructure without needing to understand the underlying implementation details.

An End-to-End Assembly

Theory is useful, but seeing how these components are implemented with real-world tools provides a deeper understanding. The following video demonstrates how to build a complete IDP from scratch using popular open-source projects. It's a comprehensive walkthrough that shows how different tools are composed to fulfill the roles of the components we've discussed.

How To Create A Complete Internal Developer Platform (IDP)?

This video provides a practical, step-by-step guide to assembling an IDP. We will watch it in segments, mapping each tool to the IDP components we've learned about.

The Control Plane & Abstraction Layer: First, watch the segment that introduces Crossplane as the control plane and explains how Compositions are used to create user-friendly abstractions. This demonstrates how the platform team creates the self-service APIs. Watch from control planes and abstractions. State Management: Next, see how Argo CD is used to implement a GitOps workflow. This ensures that all desired state is stored in Git and synchronized with the cluster, preventing direct manual changes. Watch from implementing GitOps. The User Interface: Now, see how Port is introduced as the graphical user interface and service catalog. This is the "front door" for developers. Watch from the graphical user interface. The Automation Engine: Finally, see how GitHub Actions is used as the pipeline solution to execute the one-shot actions triggered from Port, such as scaffolding a new application repository. Watch from the final piece. After watching these segments, you can optionally watch the full demonstration at the end to see the entire self-service flow in action.

This walkthrough powerfully illustrates how distinct tools are pieced together, each serving a specific function within the five-plane architecture, to create a cohesive platform that empowers developers with self-service capabilities.

Conclusion

In this lesson, we have moved from the strategic "why" of platform engineering to the architectural "what." We have deconstructed the Internal Developer Platform, identifying its core components and understanding how they enable developer self-service.

Key Takeaways:

An IDP is architecturally structured into five conceptual planes: Developer Control, Integration & Delivery, Resource, Security, and Observability.
The primary components that enable self-service are the Service Catalog, Software Templates, Tech Docs, Workflows, and Scorecards.
The technical engine of self-service consists of a Workload Specification (the developer's request) and a Platform Orchestrator (the engine that fulfills the request).
These components are realized by composing various tools like Port/Backstage (portals), Crossplane (orchestration), Argo CD (GitOps), and GitHub Actions (pipelines) into a unified system.
The ultimate goal of this architecture is to provide developers with "golden paths" that abstract away underlying complexity, allowing them to autonomously and safely provision and manage the resources they need.

Preview of the Next Lesson

Now that we understand the components of an IDP, a critical question arises: how do we know if our platform is actually effective? A platform can have all the right components but still fail if it provides a poor user experience. In our next lesson, we will focus on evaluating the Developer Experience (DevEx) of a platform, exploring key dimensions for measuring it and discussing how to propose concrete improvements. We will also delve deeper into the concept of golden paths and their crucial role in guiding developers.