Nimendra's Notes 🪴

OpenChoreo Overview

11 min read

platformengineering/openchoreo wso2

Core Idea

OpenChoreo is a complete, modular, open-source developer platform for Kubernetes that bundles the abstractions teams need, so nobody assembles an IDP from scratch.

  • Problems it solves: the IDP challenge table (Kubernetes complexity, tool sprawl, compliance, multi-cluster ops, cognitive load, no AI path) and how OpenChoreo answers each.
  • Architecture and concepts: multi-plane overview, developer and platform abstractions, ecosystem extensions, and modular design.
  • AI as a first-class platform construct, an end-to-end walkthrough of how it works, and documentation links.

Introduction

OpenChoreo is a complete, modular, open-source developer platform for Kubernetes that brings together the abstractions platform and application teams actually need — development and architecture guardrails, a Backstage-powered developer portal, application CI/CD, GitOps, and observability — in a single, cohesive platform.

OpenChoreo orchestrates Kubernetes and other CNCF and open-source projects to give platform teams a strong head start. You can use it as-is, or tailor it to fit your own Internal Developer Platform (IDPs) vision.

OpenChoreo is a CNCF Sandbox project, originally developed by WSO2, as the successor and next evolution of its SaaS WSO2 Developer Platform (formerly known as WSO2 Choreo), bringing years of battle-hardened Platform Engineering experience and lessons learnt to the CNCF open-source community.

Current Version: v1.1.x (Release Notes)

Problems OpenChoreo Solves

Many organizations are investing in Internal Developer Platform (IDPs) to improve developer velocity, reduce cognitive load, enforce organization-wide standards, and lower overall operational complexity. However, designing, building and maintaining a production-grade platform is a difficult task.

Challenges teams face when building IDPs

ChallengeDescription
Kubernetes ComplexityManaging the complexity and cognitive load of the Kubernetes API and its auxiliary ecosystem to keep developer experience simple and intuitive
Tool Integration SprawlIntegrating, maintaining and standardizing CI/CD, observability, security, and policy tools across the organization
Compliance & GovernanceMeeting compliance and governance requirements across teams and environments
Multi-cluster OperationsOperating reliably across multiple clusters and clouds with consistent policies
Developer Cognitive LoadDevelopers are forced to understand low-level infrastructure details instead of focusing on business logic
No AI Integration PathNo clear path to supporting AI-assisted/driven engineering and operations through the platform
Access Control ComplexityManaging access controls and multi-tenancy between teams, projects, tools and runtime resources

How OpenChoreo addresses these challenges

OpenChoreo provides an Internal Developer Platform (IDPs) that is usable from day one, including:

  • A scalable, modular architecture for your Internal Developer Platform (IDPs)
  • Platform APIs and abstractions as building blocks
  • Programmable developer abstractions and golden paths covering the SDLC
  • Integrated, intelligent observability (logs, metrics, traces, and alerts)
  • Built-in agents (for site reliability engineering, cost control, and architecture)
  • AI-assisted/driven development and operations via MCP servers
  • Declarative platform and application state with Kubernetes as the system of record (native GitOps)
  • Multi-tenancy and access controls for enterprise teams
  • A module catalog to integrate external tools, or build your own

Key differentiator: Unlike many platforms that attempt to hide Kubernetes behind proprietary layers or “black box” abstractions, OpenChoreo keeps Kubernetes visible and operable. It augments Kubernetes into a complete developer platform. All platform APIs and programmable developer abstractions are Kubernetes-native and are reconciled by OpenChoreo’s controllers in the control plane.

Architecture

OpenChoreo is architected as a modular, multi-plane Kubernetes-native system that integrates deeply with other open-source projects to provide a complete, extensible Internal Developer Platform (IDPs)). It uses a domain-and-abstraction-driven, API-first approach as its core design philosophy — setting it apart from platforms built from disparate tools stitched together with scripts.

Multi-Plane Architecture Overview

Each plane in OpenChoreo operates as a distinct functional unit, with its own deployment and upgrade lifecycle, scaling behavior, and security boundaries.

Experience Plane

The user-facing layer of OpenChoreo, built for platform teams, development teams and agents to interact with the Internal Developer Platform (IDPs) based on their respective roles and permissions.

ComponentDescription
CLI (occ)Command-line interface for interacting with the platform
Internal Developer PortalBackstage-based UI with native Backstage plugins and custom OpenChoreo plugins
OpenAPI-v3 APIsRESTful APIs exposed by the control plane and observability plane
MCP ServersModel Context Protocol servers for AI-assisted development and operations

The declarative nature of OpenChoreo’s APIs allows it to be operated imperatively via the UI, CLI, and MCPs, or declaratively with Git as the source of truth (native GitOps).

Control Plane

The control plane is a Kubernetes cluster that acts as the “brain” of OpenChoreo. It runs a central control loop that continuously monitors the state of the platform and developer resources.

Key components:

  • API Server — Exposes the OpenChoreo API, handles authentication, authorization, and request validation. Hosts the authorization engine providing fine-grained RBAC, ABAC, and hierarchical instance-level access control (powered by Apache Casbin)
  • Controller Manager — A set of Kubernetes controllers that implement the core reconciliation logic. They watch for changes to CRD instances and take actions to ensure desired state is achieved across all planes
  • Cluster Gateway — A hub-and-spoke communication system using Secure WebSocket (wss) with mTLS authentication. Other planes establish outbound connections to the control plane, preventing their Kubernetes API servers from being exposed to the internet

Authentication: Integrates with any OAuth2/OIDC-compatible Identity Provider. Ships with ThunderID by default.

Data Plane(s)

Data Planes represent Kubernetes clusters where application workloads run. They abstract the complexity of cluster management, providing a unified interface for deploying applications across multiple clusters.

  • Provide isolated, observable runtime environments and gateway topology
  • Host multiple environments and projects with automatic namespace, network policy management
  • Enable strategies like geographic distribution, compliance-based placement, and disaster recovery
  • Support optional modules for API management, scale-to-zero, and zero-trust networking

Workflow Plane(s)

Workflow Planes provide dedicated infrastructure for CI/CD and automation workloads, separated from runtime workloads.

  • Integrate with Argo Workflows for Kubernetes-native CI/CD execution
  • Handle the complete build lifecycle: source retrieval → compilation → testing → container image creation
  • Security isolation of untrusted build processes from production environments
  • Also run GitOps workflows and general-purpose automation (e.g., Infrastructure as Code)

Observability Plane(s)

Observability Planes provide centralized infrastructure for logs, metrics, traces, and alerts across all other planes.

  • Uses a pluggable adapter-pattern: OpenSearch (logs/traces) + Prometheus (metrics) by default
  • Observer API provides authenticated access for integration with external tools
  • Module authors can swap backends by implementing the adapter API
  • Configurable alerting rules with email/webhook notification routing

Concepts

OpenChoreo’s concepts are organized into two categories: Developer Abstractions (used by application teams) and Platform Abstractions (used by platform engineers).

Transclude of from-cell-based-architecture-to-openchoreo#core-concepts-from-cells-to-platform-objects

Developer Abstractions

Developer abstractions enable teams to build, deploy, and operate cloud-native applications without managing infrastructure complexity. They provide a declarative model for expressing application architecture, dependencies, and operational requirements.

Project

A Project represents a bounded context (Domain-Driven Design) — a cohesive collection of components that together implement a specific business capability or application domain.

  • Primary organizational unit for developers
  • Defines clear boundaries for code ownership, deployment coordination, and operational responsibility
  • Logical boundaries: Groups related components sharing common business logic, data models, and team ownership
  • Physical boundaries: Translates into isolated deployment units (Cells) with dedicated namespaces, network boundaries, and security policies
  • Components within a project can communicate freely with each other (locality principle)

Component

A Component represents a deployable unit of software — the fundamental building block of applications in OpenChoreo (e.g., a microservice, a web application, or a background job).

Components connect four essential elements:

ElementDescription
ComponentType ReferenceSpecifies which platform-defined template governs deployment (e.g., deployment/web-service, cronjob/data-processor)
ParametersComponent-specific configuration values captured in release snapshots — identical across all environments
TraitsComposable additional capabilities (persistent storage, caching, monitoring) — instantiated multiple times with different configurations
SourceReference to the source code repository and build configuration

ComponentRelease

A ComponentRelease is an immutable snapshot of a component at a point in time, capturing the exact parameter values, trait configurations, and build artifacts. Releases are the unit of deployment promotion.

ReleaseBinding

A ReleaseBinding connects a ComponentRelease to a specific Environment. This is what actually deploys a release to a data plane — it can also carry environment-specific overrides via environmentConfigs (e.g., resource limits, storage sizes).

Platform Abstractions

Platform abstractions provide the foundational infrastructure layer that platform engineers use to build and manage the Internal Developer Platform (IDPs).

Namespace

OpenChoreo uses Kubernetes namespaces to organize and isolate groups of related resources. Platform resources are created as cluster-scoped resources by default (e.g., ClusterComponentType, ClusterTrait, ClusterWorkflow), making them visible to all namespaces. Namespace-scoped variants can be created for isolation.

Namespaces are identified via a label: openchoreo.dev/control-plane: true

Environment

An Environment represents a stage in the software delivery lifecycle (e.g., development, staging, production).

  • First-class abstractions — not just labels or namespaces
  • Define where applications should be deployed (which DataPlane)
  • Serve as targets for deployment pipelines

DeploymentPipeline

A DeploymentPipeline defines the allowed progression paths for applications moving through environments.

  • Encodes promotion rules and quality gates as declarative configuration
  • Supports complex promotion topologies (parallel paths, conditional progressions)
  • Integration point for automated testing and compliance checks at promotion boundaries

ComponentType & Trait

ConceptDescription
ComponentTypePlatform-defined templates that govern deployment patterns (e.g., deployment/web-service). Defines available configuration schema, resource templates, and allowed workflows
TraitReusable cross-cutting concerns that can be composed into components (e.g., observability sidecar, security proxy, persistent storage)
WorkflowTemplates for CI/CD and automation pipelines that can be referenced by ComponentTypes

Ecosystem

The OpenChoreo Ecosystem provides community-driven extensions that seamlessly integrate with the platform to expand its capabilities. Rather than bundling every possible integration into the core, the ecosystem approach lets you choose the tools that fit your needs.

Extension Types

TypeDescription
ModulesPluggable integrations (packaged as Helm charts) that extend platform planes — swap or supplement tools for networking, security, observability, and CI/CD
Curated Backstage ModulesValidated Backstage plugins bundled into the OpenChoreo portal to extend the developer experience
AgentsAI-powered platform agents for SRE, cost control, and architecture governance
SkillsReusable capabilities that can be referenced by agents and workflows
Component TypesCommunity-defined deployment patterns and templates
WorkflowsReusable CI/CD and automation workflow templates

Key Technologies Integrated

OpenChoreo orchestrates and deeply integrates with these open-source projects:

TechnologyRole in OpenChoreo
BackstagePowers the Internal Developer Portal — extended from a static service catalog into an actionable platform
Argo WorkflowsPowers the Workflow Plane for CI/CD automation, builds, and infrastructure provisioning
Envoy GatewayAPI/AI gateway management, routing, authentication, and authorization within the cell-based architecture
CiliumNetworking and security foundation — enforces zero-trust security and network policies
cert-managerTLS certificate management for mTLS between planes
OpenSearchDefault backend for logs and traces in the Observability Plane
PrometheusDefault backend for metrics in the Observability Plane
ThunderIDDefault open-source identity server (OAuth2/OIDC)
Apache CasbinPowers the built-in authorization engine (RBAC, ABAC)

Modular Architecture

OpenChoreo is designed to be highly extensible when it comes to platform tooling. You can:

  1. Use default modules — OpenChoreo ships with sensible defaults for each plane
  2. Swap modules — Replace any default module with your preferred choice from the modules catalog
  3. Build your own — Create custom modules that integrate with OpenChoreo’s core APIs and concepts

This module-based architecture allows tools to be integrated without impacting the unified end-user experience.

AI as a First-Class Platform Construct

OpenChoreo was designed from the ground up to support AI-assisted/driven development and operations:

  • MCP Servers — Both the control plane and observability plane expose MCP (Model Context Protocol) servers, enabling AI agents like Claude Code, Codex, etc. to interact with the platform
  • Same Golden Paths — AI agents follow the same guardrails and authorization policies as human users
  • Built-in platform agents — Optional agents for site reliability engineering, cost control, and architecture governance
  • Future-proof — Even if your team doesn’t use AI today, the architecture provides a foundation for integrating AI tools later

How OpenChoreo Works (End-to-End)

Developer / AI Agent
        │
        ▼
┌─────────────────────────────┐
│    Experience Plane         │
│  CLI · Portal · API · MCP   │
└────────────┬────────────────┘
             │ Declarative APIs (CRDs)
             ▼
┌─────────────────────────────┐
│      Control Plane          │
│  API Server · Controllers   │
│  Authorization · Gateway    │
└──┬──────────┬───────────┬───┘
   │          │           │
   ▼          ▼           ▼
┌───────┐ ┌────────┐ ┌───────────┐
│ Data  │ │Workflow│ │Observa-   │
│Plane  │ │ Plane  │ │bility     │
│(s)    │ │ (s)    │ │Plane(s)   │
│       │ │        │ │           │
│ K8s   │ │ Argo   │ │OpenSearch │
│Cluster│ │Workflow│ │Prometheus │
└───────┘ └────────┘ └───────────┘
  1. Developers create Components within Projects via the CLI, Portal, API, or AI agents
  2. The Control Plane validates requests, resolves references, and triggers workflows
  3. The Workflow Plane builds container images from source code
  4. A ComponentRelease captures the immutable build artifact
  5. ReleaseBindings deploy releases to target Environments on Data Planes
  6. The Observability Plane collects and correlates logs, metrics, and traces
  7. DeploymentPipelines govern the promotion flow (dev → staging → production)

Ready to try OpenChoreo? Start here:

  1. Architecture — Learn more about OpenChoreo’s multi-plane architecture
  2. Quick Start Guide — Experience OpenChoreo locally in minutes with just Docker
  3. Try It Out — Run Locally (K3d) or On Your Environment
  4. Concepts — Learn about core concepts and abstractions
  5. Platform Engineer Guide — Set up in production, configure workflows, govern your platform
  6. Developer Guide — Build, deploy and observe your applications with self-service
  7. Working with AI — Use AI assistants (Claude Code, Codex, etc.) with OpenChoreo

OpenChoreo - Building AI-Native, K8s-First Platforms

Backlinks

Graph View