Internal Developer Platforms on Kubernetes: A Platform Engineer’s Complete Guide

What Is an Internal Developer Platform (IDP)?

An Internal Developer Platform (IDP) is a self-service layer built and maintained by a platform engineering team that abstracts away infrastructure complexity so application developers can deploy, operate, and manage services without becoming experts in Kubernetes, Terraform, or cloud provider APIs.

The distinction is important: an IDP is not a product you buy, it is an opinionated system your platform team constructs from composable tools and exposes to developers as a coherent experience. Its primary job is to eliminate the ticket queue. A developer who needs a database, a CI/CD pipeline, or a new namespace shouldn’t have to file a request and wait three days. They should be able to provision those resources themselves, within guardrails the platform team has already encoded.

At its best, an IDP compresses the cognitive overhead of modern software delivery into a set of well-defined workflows (often called golden paths) that encode security requirements, capacity policies, observability defaults, and compliance controls automatically.

What’s the Difference Between an IDP and a Developer Portal?

These terms are frequently conflated, but they refer to distinct layers of the platform engineering stack.

A developer portal (such as Backstage) is a UI surface – a catalog of services, APIs, documentation, and templates that gives developers a unified view of the software ecosystem. It surfaces discoverability and provides a launchpad for golden path workflows.

An Internal Developer Platform is the operational substrate beneath the portal. It includes the automation, APIs, provisioners, controllers, and policy engines that actually fulfill developer requests. When a developer clicks “create new service” in Backstage, the IDP is what provisions the namespace, attaches the storage class, wires up secrets management, and registers the CI pipeline.

In practice, most mature platforms have both: Backstage (or a similar portal) as the human interface, and a collection of Kubernetes controllers, GitOps pipelines, and infrastructure APIs as the IDP.

What Are the Core Components of a Kubernetes-Based IDP?

Most production IDPs running on Kubernetes share a common set of building blocks:

Developer Portal and Service Catalog

Backstage remains the dominant choice for internal developer portals in 2026. It now has more than 3,400 adopters, including Airbnb, LEGO, HCA Healthcare, and Toyota North America, and ranks among the highest-velocity projects in the CNCF (CNCF 2025 Annual Survey). It provides a software catalog, TechDocs integration, and a plugin ecosystem that surfaces the IDP’s capabilities (e.g., golden path templates, scaffolding, and operational dashboards) through a unified UI.

GitOps Engine

GitOps is the deployment model of choice for Kubernetes-based IDPs. Argo CD or Flux CD reconcile cluster state against Git as the source of truth, providing a full audit trail and enabling developers to trigger deployments through pull requests rather than CLI commands or Slack messages.

This model is foundational for IDPs because it encodes the approval and deployment workflow into version-controlled artifacts (YAML manifests, Helm values, or Kustomize overlays) that the platform team can gate with policy.

Infrastructure Provisioning Layer

Crossplane has emerged as the standard approach for provisioning cloud infrastructure, such as RDS instances, S3 buckets, and managed Kafka clusters directly through Kubernetes APIs. A platform team defines composite resource definitions (XRDs) that expose a simplified interface to developers while handling the underlying provider-specific complexity.

Terraform-based approaches remain common, particularly in organizations with large existing Infrastructure as Code (IaC) estates, often surfaced through Atlantis or integrated into GitOps pipelines.

Policy and RBAC

Open Policy Agent (OPA) / Gatekeeper or Kyverno enforce guardrails at admission time. This is how the platform team ensures that every workload that touches the cluster meets baseline requirements: resource limits set, container images from approved registries, required labels present, security contexts enforced.

Secrets Management

Secrets should never live in Git. The standard pattern integrates Vault (or a cloud-provider equivalent) with the External Secrets Operator to sync secrets into Kubernetes namespaces at runtime. Developers declare what secrets their application needs; the platform handles provisioning and rotation.

Observability Stack

A built-in observability stack, typically Prometheus, Grafana, and an OpenTelemetry collector, is provisioned automatically as part of any golden path. Developers get metrics, dashboards, and alerting without having to configure them. The platform team owns the retention policies and alert routing.

Persistent Storage Layer

This is where most IDPs have a gap, and where significant operational complexity lives. More on this below.

What Are Golden Paths in Platform Engineering?

A golden path is an opinionated, pre-built workflow for a specific category of developer need. Rather than giving developers unrestricted access to a Kubernetes cluster and expecting them to figure out the right way to deploy a PostgreSQL database, the platform team builds a golden path that produces a properly configured, HA-enabled, observable, and backed-up database instance through a single template or API call.

Golden paths work because they encode decisions that developers shouldn’t have to make repeatedly. The platform team decides once what a “production-grade database” looks like, including: replication factor, backup schedule, monitoring thresholds, storage class, encryption settings, and more, and bakes that into a template. The developer declares their intent (“I need a PostgreSQL instance for this service”); the golden path handles the implementation.

Well-designed golden paths have these properties:

Self-service by default. Developers don’t wait for human approvals for standard requests. Policy gates happen at admission time, not through ticket queues.

Opinionated but not rigid. Golden paths cover 80% of use cases with no configuration required. Escape hatches exist for the remaining 20%, but they require deliberate action and may trigger a review process.

Observable from the start. Every resource provisioned through a golden path inherits the platform’s observability configuration automatically.

Portable across environments. The same template works in dev, staging, and production. Environment-specific values (replica counts, resource limits, backup retention) are parameterized, not hardcoded.

The Stateful Storage Gap in Most IDPs

Here is the honest reality of most Kubernetes-based IDPs in production today: stateless workloads have excellent golden paths; stateful workloads don’t.

Platform teams have invested heavily in abstracting deployment, scaling, and networking for stateless services. Spinning up a new API service with CI/CD, ingress, and observability is often a five-minute workflow. But the moment a developer needs persistent state (e.g. a database, a message queue, a distributed cache) the experience degrades. Yet stateful workloads are now mainstream: 72% of organizations run databases on Kubernetes (Data on Kubernetes 2024 Report) so this gap affects the majority of production estates.

The reasons the gap exists are structural.

CSI Driver Fragmentation

The Container Storage Interface (CSI) is the standard Kubernetes mechanism for connecting storage to pods. 

Most platform teams rely on cloud-provider CSI drivers such as Amazon EBS CSI, Google Persistent Disk CSI, or Azure Disk CSI, or on vendor-provided CSI integrations. These are effective for many basic RWO volume use cases, but capabilities such as RWX, application-consistent snapshots, cross-cluster replication & DR, and policy-based capacity automation vary significantly by driver, backend, and cloud provider.

Each cloud provider handles these features differently, with different APIs, different limitations, and different operational models. A platform team building for multi-cloud or hybrid environments ends up maintaining a patchwork of storage classes, annotations, and provider-specific workarounds that are difficult to expose as a coherent golden path.

Day 2 Operations Are Manual

Even when initial storage provisioning is self-service, Day 2 operations frequently are not. Capacity expansion, snapshot management, backup verification, and disaster recovery testing often require intervention from a storage or infrastructure team that sits outside the platform team. This creates the exact ticket-queue bottleneck that IDPs are designed to eliminate.

A developer whose service is hitting storage capacity limits shouldn’t need to file a ticket with a storage team. But in most organizations, they do.

StatefulSets Add Orchestration Complexity

Kubernetes StatefulSets provide stable network identities and persistent volume claims for stateful applications, but they require significantly more orchestration knowledge than Deployments. Pod disruption budgets, volume claim templates, ordered rolling updates, and the interaction between StatefulSets and storage class binding modes are all sources of operational complexity that most developers cannot be expected to understand.

The platform team’s job is to abstract this complexity, but doing so requires a storage layer with the right automation primitives. Standard CSI drivers don’t provide them.

Building Storage Into Your IDP Golden Path

A production-ready IDP needs storage to behave as a first-class platform primitive, not an infrastructure afterthought. This means the platform team must treat the storage layer with the same design rigor applied to compute and networking.

Define Storage Classes as Platform Contracts

Storage classes should be treated as named contracts that developers reference by intent, not by implementation detail. Instead of exposing gp2, pd-ssd, or Premium_LRS to developers, define classes with names like platform-database-ha, platform-cache-fast, or platform-analytics-bulk. Each class encodes the right performance tier, replication behavior, and encryption settings for its intended use case.

Developers declare which class they need; the platform determines how to fulfill it.

# Developer-facing PVC — no cloud-provider specifics

apiVersion: v1

kind: PersistentVolumeClaim

metadata:

  name: postgres-data

spec:

  storageClassName: platform-database-ha

  accessModes:

    - ReadWriteOnce

  resources:

    requests:

      storage: 100Gi

Automate Capacity Management

Persistent volumes should grow automatically when approaching capacity thresholds. Manual capacity expansion is a Day 2 operational burden that breaks the self-service model. The storage layer needs rules-based dynamic volume expansion: detecting when a volume approaches a configured threshold and expanding it within policy bounds without requiring human intervention or application downtime.

Integrate Backup Into the Golden Path

Backup should not be an opt-in capability that developers configure separately. Every stateful workload provisioned through a golden path should inherit a backup policy automatically. This means the storage layer needs application-aware backup that understands when a database is in a consistent state for snapshotting, not just filesystem-level snapshots that may capture data mid-transaction.

For PostgreSQL, application-consistent backup means coordinating snapshots with PostgreSQL’s backup process and ensuring the required WAL files are retained for recovery. For distributed databases, it means coordinating snapshots across multiple volumes and replicas so the restored application returns to a consistent state

Build for Multi-Cluster Portability

Modern IDP architectures often span multiple Kubernetes clusters: dedicated clusters per environment, per team, or per region. The storage layer must provide consistent behavior and consistent operational interfaces across all of these clusters, whether they run on the same cloud provider or different ones. Developers and platform operators shouldn’t need to reason about which cloud-provider storage API is in play.

What Are the Storage Architecture Patterns for IDPs?

Database-as-a-Service Within the Platform

Rather than exposing raw PersistentVolumeClaims to developers, mature IDPs provide a Database-as-a-Service (DBaaS) abstraction. Developers request a database instance through the service catalog; the platform provisions the StatefulSet, PVCs, secrets, monitoring, and backup schedule as a unit.

Crossplane composite resources are well-suited to this pattern. The platform team defines a composite resource like PostgreSQLInstance that encapsulates all of the operational complexity:

apiVersion: platform.company.io/v1alpha1

kind: PostgreSQLInstance

metadata:

  name: payments-db

spec:

  version: "16"

  size: medium          # maps to CPU/memory/storage profiles

  ha: true              # triggers replication setup

  backupRetention: 30d

  environment: production

The composite resource controller handles everything else: volume provisioning with the right storage class, StatefulSet configuration, network policy, service account, backup schedule, and monitoring dashboard registration.

Storage Pools and Aggregation

A common limitation of node-local storage approaches is that individual node capacity becomes a ceiling for individual volume sizes. Storage pool aggregation (pooling the available storage across multiple nodes into a logical layer) eliminates this constraint and enables large volumes to be provisioned dynamically without manual node-level configuration.

Portworx Enterprise uses this model, aggregating local or attached storage across the cluster into storage pools that can be allocated on demand. This is what makes self-service provisioning of large volumes viable: the developer requests a 2TB volume and the platform fulfills it from the pool without requiring a human to identify which node has sufficient capacity.

High Availability and Replication

For production stateful workloads, volumes should be replicated synchronously across multiple nodes. If a node fails, the volume should be immediately available on another node without data loss, and without the platform team being paged. This requires a storage layer that handles replication independently of the application.

Standard CSI drivers delegate this responsibility to the underlying storage backend, which may not provide node-level replication semantics within a Kubernetes cluster. A platform-native storage solution handles replication in-cluster, making HA a storage class property rather than an application architecture decision.

How Portworx Addresses the IDP Storage Gap

Portworx Enterprise is designed specifically for the operational model that IDPs require: API-first, automation-friendly, and consistent across cloud providers.

Where standard CSI drivers stop at volume provisioning, Portworx extends Kubernetes storage semantics to cover the full lifecycle of stateful workloads (provisioning, capacity management, replication, snapshot, backup, restore, and migration) through Kubernetes-native APIs that integrate cleanly with GitOps workflows and Crossplane composites.

For platform teams building golden paths, this means storage behaves as a programmable platform primitive rather than infrastructure that requires manual intervention. Automated capacity expansion, application-consistent snapshots, and multi-cluster replication are all available as declarative configuration, not operational runbooks.

For developer self-service, Portworx removes the dependencies that break the self-service model. A developer provisioning a database through a golden path gets HA-replicated storage, automated backups, and capacity management without knowing or caring what’s underneath. The platform team defines the policy once; Portworx enforces it automatically.

For multi-cloud and hybrid environments, Portworx provides a consistent storage and data-management control plane across supported Kubernetes distributions, managed cloud services, OpenShift, and on-premises clusters. This helps platform teams define policy once and expose storage through reusable golden paths.

HSBC captures it directly 

“We needed a (storage) platform that could retain data integrity. That’s what brought us to Portworx. It’s a valuable platform where we can build at scale.” – Steve Lewis, Global Head of Engineering – Container Platforms.

And Fiserv confirms:

“The impacts of the business are clearly reliable software deployments, where we’re deploying more features…this allows developers to get towards multiple deployments perhaps per month, per week.” – John Durko, Director of IT, Product Architect, Container Services

Day 2 Operations: Where IDPs Succeed or Fail

The first effort of platform engineering is building things that work at day zero. The remaining and ongoing effort is making them work reliably over months and years. Day 2 operations are where IDPs can struggle to deliver on their promise.

Capacity Planning and Expansion

Volumes fill up. The right operational model proactively monitors volume utilization and expands capacity before an application hits its limit. This requires integration between the storage layer and the platform’s alerting infrastructure, plus automation that can expand a volume without application downtime.

Backup Verification

Backups that aren’t tested aren’t backups. A mature IDP includes scheduled restore verification – automatically restoring from recent backups to an isolated environment and verifying application-level consistency. This closes the gap between “we have backups” and “our backups actually work.”

Disaster Recovery Testing

DR plans that require manual runbooks fail under pressure. The platform should support automated DR testing: simulating a cluster failure, failing over to the replica cluster, verifying application availability, and failing back, all driven by automation rather than a step-by-step guide.

Security and RBAC for Storage

Storage is a data security boundary. The platform needs to enforce encryption at rest for all persistent volumes, control which namespaces can provision which storage classes, and provide audit logging for data access and operations. These controls should be enforced by the platform, not delegated to individual application teams.

Getting Started: Building Storage Into Your IDP

If you’re building or maturing a Kubernetes-based IDP and storage is still a source of manual operations, ticket-based requests, or inconsistent behavior across environments, the right time to address it is before your golden paths are fully established.

Adding a programmable, automation-native storage layer early means your golden paths can include storage as a first-class capability from the start — rather than retrofitting it into existing templates and abstractions later.

Portworx Enterprise provides the storage primitives that IDPs need: self-service provisioning, automated capacity management, application-aware backup, and consistent multi-cloud behavior — all through Kubernetes-native APIs that integrate with your existing GitOps and Crossplane workflows.

Explore the Portworx IDP use case or join a Hands-on lab to see how Portworx delivers a data management platform for Kubernetes. 

Related resources:

• Data-Aware Platform Engineering: The Kubernetes Storage Gap
• Top 5 Reasons CSI Drivers Fall Short in Enterprise-Scale Kubernetes
• Dynamic Yet Secure Storage for Platform Engineering
• Beyond CSI: Why CSI Drivers Fall Short in Enterprise-Scale Kubernetes