README
¶
A complete, open-source developer platform for Kubernetes
OpenChoreo is a developer platform for Kubernetes that lets developers and AI agents build, deploy, and operate apps, resources, and agentic workloads. It provides development and platform abstractions, a Backstage-powered developer portal, CI/CD, GitOps, and observability.
Why OpenChoreo?
Kubernetes gives you powerful primitives like Namespaces, Deployments, CronJobs, Services, and NetworkPolicies, but they're too low-level for most developers. Platform engineers end up building the actual platform from scratch: defining higher-level abstractions, wiring together tools for delivery, security and observability, and maintaining all of it as an in-house product.
That means stitching together a developer portal, CI pipelines, GitOps workflows, an observability stack, and access controls and then owning the glue between them indefinitely. The result is a fragile, bespoke system that's expensive to maintain and hard to evolve.
Developers and platform engineers need different things from the same platform. Developers want a simple, self-service experience. Platform engineers want control over what's running underneath. Most DIY platforms end up optimizing for one side at the expense of the other.
What is OpenChoreo?
OpenChoreo, now a CNCF Sandbox project, takes a different approach. Instead of giving you a toolkit to assemble your own platform, it provides a complete, open-source developer platform for Kubernetes with abstractions that translate developer intent into platform reality. So platform engineers don't have to reinvent the wheel, and developers get a self-service experience that stays out of their way.
Under the hood, OpenChoreo brings together a Backstage-powered developer portal, built-in CI and GitOps, observability, RBAC, and analytics and all of them are organized across dedicated control, CI, data, and observability planes. Platform engineers get a production-ready foundation they can operate and extend, not scaffolding they'll eventually replace.
OpenChoreo was originally developed by WSO2, based on its experience building the SaaS internal developer platform formerly known as WSO2 Choreo (now WSO2 Developer Platform), bringing its core ideas to the open-source community. It's not a fork or an open-source dump; it's a complete rewrite based on what we learned from Choreo’s users over the years.
How does OpenChoreo work?
OpenChoreo is built around a multi-plane architecture, where each plane handles a distinct concern and operates independently.
-
The Experience Plane is where developers, platform engineers, and SREs interact with the platform via a Backstage-powered OpenChoreo Portal, CLI, GitOps, or AI agents.
-
The Control Plane sits at the center of OpenChoreo. It takes developer intent and platform intent expressed through high-level abstractions like components, endpoints, dependencies, environments, pipelines, and namespaces and translates them into the underlying Kubernetes resources. It also reflects runtime reality back up, so what developers see always matches what's actually running.
-
The Data Plane is where your workloads run. It is where OpenChoreo enforces and guarantees the semantics of those high-level abstractions, such as isolation between projects, traffic policies, and security boundaries. These aren't just configurations; they're guaranteed by the platform.
-
The Observability Plane feeds the loop with metrics, logs, and tracing, all surfaced through the abstractions your developers already understand.
-
The optional CI Plane handles builds using cloud native Buildpacks and Argo Workflows by default.
At the center of this is a set of opinionated abstractions. Developers work with components (services, workers, cron jobs, and other types defined as component types), expose functionality through endpoints, and declare dependencies on other endpoints or resources. Platform engineers control what component types are available, what traits can be applied, and how workloads behave, through configuration, not custom code.
The result is a clear separation of concerns: developers express what they want to run, the control plane figures out how to run it, and platform engineers govern the boundaries.
Underpinning all of this is the Platform API. It is a set of Kubernetes CRDs that let platform engineers declaratively define the structure and behavior of the entire platform. Instead of writing custom controllers or glue scripts, you configure organizational boundaries, environments, data planes, deployment pipelines, and observability through familiar Kubernetes-native resources. The Platform API also includes programmable abstractions like ComponentTypes, Traits, and Workflows that let platform teams define golden paths for their developers, encapsulate best practices, and enforce organizational standards. Together, they enable OpenChoreo's approach to policy, security, and governance by design.
The diagram below illustrates some of the core concepts of the Platform API and how they relate to each other. It represents one possible platform topology, not a prescribed structure.
Getting Started
The easiest way to try OpenChoreo is by following the Quick Start Guide. It walks you through setting up Choreo using a Dev Container, so you can start experimenting without affecting your local environment.
For a deeper understanding of OpenChoreo's architecture, see OpenChoreo Concepts.
Visit Installation Guide to learn more about installation methods.
Samples
Explore hands-on examples to help you configure and deploy your applications using OpenChoreo.
- Platform Configuration – Set up deployment pipelines and environments.
- Deploy from Source – Deploy services and web apps from source code.
- Deploy from Image – Deploy pre-built container images.
Check out the Samples Directory for more details.
Join the Community & Contribute
We’d love for you to be part of OpenChoreo’s journey! Whether you’re fixing a bug, improving documentation, or suggesting new features, every contribution counts.
- Contributor Guide – Learn how to get started.
- Report an Issue – Help us improve Choreo.
- Join our Slack – Be part of the community.
We’re excited to have you onboard!
Roadmap
We maintain an OpenChoreo Roadmap as a GitHub project board to share what we’re building and when we expect to deliver it.
The roadmap is organized by calendar quarters, and each column represents a set of features or enhancements planned for that period. This allows contributors, adopters, and maintainers to understand what’s coming up and what’s already being worked on.
How It Works
- Quarterly columns: Group features by when we aim to deliver them (e.g., 2025 Q2 – Apr–Jun).
- Future column: Tracks ideas or initiatives we intend to explore but haven’t scheduled yet.
- Each card links to a GitHub issue with context and discussion.
- We continuously update the roadmap as priorities evolve, and completed features may remain in their quarter for historical visibility.
License
OpenChoreo is licensed under Apache 2.0. See the LICENSE file for full details.
Directories
¶
| Path | Synopsis |
|---|---|
|
api
|
|
|
v1alpha1
Package v1alpha1 contains API Schema definitions for the v1alpha1 API group.
|
Package v1alpha1 contains API Schema definitions for the v1alpha1 API group. |
|
cluster-agent
command
|
|
|
cluster-gateway
command
|
|
|
event-forwarder
command
|
|
|
observer
command
|
|
|
occ
command
|
|
|
openchoreo-api
command
|
|
|
remote-agent
command
|
|
|
remote-agent-router
command
|
|
|
config
|
|
|
crd
Package crd embeds the generated CRD YAML files so other packages can access them without filesystem reads at runtime.
|
Package crd embeds the generated CRD YAML files so other packages can access them without filesystem reads at runtime. |
|
internal
|
|
|
auditconfig
Package auditconfig holds the koanf-decode-and-validate layer for a service's audit.policies configuration.
|
Package auditconfig holds the koanf-decode-and-validate layer for a service's audit.policies configuration. |
|
cluster-gateway/fabric
Package fabric implements the cluster gateway fabric: horizontal scaling of the websocket-terminating gateway by replicating the connection registry across replicas and forwarding requests between them (connect-to-one + gateway mesh).
|
Package fabric implements the cluster gateway fabric: horizontal scaling of the websocket-terminating gateway by replicating the connection registry across replicas and forwarding requests between them (connect-to-one + gateway mesh). |
|
config
Package config provides a unified configuration loader for OpenChoreo components.
|
Package config provides a unified configuration loader for OpenChoreo components. |
|
controller/testutils/testgateway
Package testgateway provides a fake cluster-gateway HTTP server for controller tests.
|
Package testgateway provides a fake cluster-gateway HTTP server for controller tests. |
|
dataplane/kubernetes/types
Package types contains resource type definitions for the Kubernetes integration that are derived from the following projects: - Cilium: https://github.com/cilium/cilium/tree/main/pkg/k8s/apis/cilium.io - Argo Workflow: https://github.com/argoproj/argo-workflows/tree/main/pkg/apis/workflow - Secret Store CSI Driver: https://github.com/kubernetes-sigs/secrets-store-csi-driver/tree/main/apis/v1
|
Package types contains resource type definitions for the Kubernetes integration that are derived from the following projects: - Cilium: https://github.com/cilium/cilium/tree/main/pkg/k8s/apis/cilium.io - Argo Workflow: https://github.com/argoproj/argo-workflows/tree/main/pkg/apis/workflow - Secret Store CSI Driver: https://github.com/kubernetes-sigs/secrets-store-csi-driver/tree/main/apis/v1 |
|
dataplane/kubernetes/types/argoproj.io/workflow/v1alpha1
Package v1alpha1 is the v1alpha1 version of the API.
|
Package v1alpha1 is the v1alpha1 version of the API. |
|
dataplane/kubernetes/types/externalsecrets/v1
Package v1 contains resources for external-secrets +kubebuilder:object:generate=true +groupName=external-secrets.io +versionName=v1
|
Package v1 contains resources for external-secrets +kubebuilder:object:generate=true +groupName=external-secrets.io +versionName=v1 |
|
logging
Package logging provides a standardized logger construction for all OpenChoreo components.
|
Package logging provides a standardized logger construction for all OpenChoreo components. |
|
observer/api/finopsadapterclientgen
Package finopsadapterclientgen provides primitives to interact with the openapi HTTP API.
|
Package finopsadapterclientgen provides primitives to interact with the openapi HTTP API. |
|
observer/api/gen
Package gen provides primitives to interact with the openapi HTTP API.
|
Package gen provides primitives to interact with the openapi HTTP API. |
|
observer/api/internalgen
Package internalgen provides primitives to interact with the openapi HTTP API.
|
Package internalgen provides primitives to interact with the openapi HTTP API. |
|
observer/api/logsadapterclientgen
Package logsadapterclientgen provides primitives to interact with the openapi HTTP API.
|
Package logsadapterclientgen provides primitives to interact with the openapi HTTP API. |
|
observer/labels
Package labels provides constant definitions for Kubernetes labels used across the Choreo logging system.
|
Package labels provides constant definitions for Kubernetes labels used across the Choreo logging system. |
|
occ/cmd/remote
Package remote implements `occ remote` (tunnel one or more workloads' dependencies to the developer's machine).
|
Package remote implements `occ remote` (tunnel one or more workloads' dependencies to the developer's machine). |
|
occ/flags
Package flags provides helper functions for registering and reading commonly used CLI flags across occ subcommands.
|
Package flags provides helper functions for registering and reading commonly used CLI flags across occ subcommands. |
|
occ/testutil
Package testutil provides shared test helper utilities for occ sub-packages.
|
Package testutil provides shared test helper utilities for occ sub-packages. |
|
openchoreo-api/api/gen
Package gen provides primitives to interact with the openapi HTTP API.
|
Package gen provides primitives to interact with the openapi HTTP API. |
|
pipeline/component
Package component provides the main rendering pipeline for Component resources.
|
Package component provides the main rendering pipeline for Component resources. |
|
pipeline/component/renderer
Package renderer handles ResourceTemplate orchestration for ComponentTypes.
|
Package renderer handles ResourceTemplate orchestration for ComponentTypes. |
|
pipeline/component/schemaextract
Package schemaextract parses an endpoint's API schema (OpenAPI for HTTP, protobuf for gRPC) into a flat list of renderable routes.
|
Package schemaextract parses an endpoint's API schema (OpenAPI for HTTP, protobuf for gRPC) into a flat list of renderable routes. |
|
pipeline/component/trait
Package trait handles trait processing for component rendering.
|
Package trait handles trait processing for component rendering. |
|
pipeline/project
Package projectpipeline renders the inlined (Cluster)ProjectType.spec.resources templates for a single ProjectReleaseBinding.
|
Package projectpipeline renders the inlined (Cluster)ProjectType.spec.resources templates for a single ProjectReleaseBinding. |
|
pipeline/resource
Package resourcepipeline renders ResourceType templates and resolves ResourceType outputs for a single ResourceReleaseBinding.
|
Package resourcepipeline renders ResourceType templates and resolves ResourceType outputs for a single ResourceReleaseBinding. |
|
pipeline/workflow
Package workflowpipeline provides workflow rendering by combining CRs and evaluating CEL expressions.
|
Package workflowpipeline provides workflow rendering by combining CRs and evaluating CEL expressions. |
|
remote-agent
Package remoteagent implements the OpenChoreo remote-agent: a per-project+env data-plane component that terminates TLS + yamux tunnels from `occ remote`, and for each stream calls the control plane's authorize endpoint to turn the session capability + target key into a concrete host:port, then dials it and pipes bytes.
|
Package remoteagent implements the OpenChoreo remote-agent: a per-project+env data-plane component that terminates TLS + yamux tunnels from `occ remote`, and for each stream calls the control plane's authorize endpoint to turn the session capability + target key into a concrete host:port, then dials it and pipes bytes. |
|
remote-agent-router
Package remoteagentrouter implements the OpenChoreo remote-connect SNI router: a single per-data-plane L4 entrypoint that terminates nothing.
|
Package remoteagentrouter implements the OpenChoreo remote-connect SNI router: a single per-data-plane L4 entrypoint that terminates nothing. |
|
remote-agent-router/config
Package config loads the remote-connect SNI router configuration through the shared OpenChoreo config framework, so the router honors the same override chain as every other component: struct defaults, then a YAML file, then environment variables, then explicitly-set CLI flags.
|
Package config loads the remote-connect SNI router configuration through the shared OpenChoreo config framework, so the router honors the same override chain as every other component: struct defaults, then a YAML file, then environment variables, then explicitly-set CLI flags. |
|
remote-agent/config
Package config loads the remote-agent configuration through the shared OpenChoreo config framework, so the agent honors the same override chain as every other component: struct defaults, then a YAML file, then environment variables, then explicitly-set CLI flags.
|
Package config loads the remote-agent configuration through the shared OpenChoreo config framework, so the agent honors the same override chain as every other component: struct defaults, then a YAML file, then environment variables, then explicitly-set CLI flags. |
|
remoteconnect
Package remoteconnect defines the wire contract shared by the `occ remote` client, the control plane (openchoreo-api), and the per-project+env remote-agent: the resolve request/response (resolve.go), the CP-signed capability that scopes a session (capability.go), the occ<->agent tunnel protocol and client (protocol.go, client.go), and the agent->CP authorize callback (authorize.go).
|
Package remoteconnect defines the wire contract shared by the `occ remote` client, the control plane (openchoreo-api), and the per-project+env remote-agent: the resolve request/response (resolve.go), the CP-signed capability that scopes a session (capability.go), the occ<->agent tunnel protocol and client (protocol.go, client.go), and the agent->CP authorize callback (authorize.go). |
|
scaffold/component
Package component provides scaffolding generators for OpenChoreo Component YAML files.
|
Package component provides scaffolding generators for OpenChoreo Component YAML files. |
|
scaffold/project
Package project generates OpenChoreo Project YAML from a (Cluster)ProjectType.
|
Package project generates OpenChoreo Project YAML from a (Cluster)ProjectType. |
|
pkg
|
|
|
hash
Package hash provides generic utilities for computing hashes.
|
Package hash provides generic utilities for computing hashes. |
|
observability
Package observability provides public interfaces for component observability.
|
Package observability provides public interfaces for component observability. |
|
test
|
|
|
e2e/cmd/tier3-fixtures
command
|
|
|
tools
|
|
|
auditcoverage
command
Command auditcoverage generates a service's audit coverage matrix: every audited REST operation, every exemption with its reason, which operations supply full resource identity, and known non-events.
|
Command auditcoverage generates a service's audit coverage matrix: every audited REST operation, every exemption with its reason, which operations supply full resource identity, and known non-events. |
|
auditgen
command
Command auditgen generates a service's definitions.gen.go: one audit.OperationDef per state-modifying REST operation, stamping its action, resource type and category.
|
Command auditgen generates a service's definitions.gen.go: one audit.OperationDef per state-modifying REST operation, stamping its action, resource type and category. |
|
helm-gen
command
|
|
|
internal/auditgen
Package auditgen holds the OpenAPI-spec-walking logic tools/auditgen uses for every service it generates (see that command's -service flag).
|
Package auditgen holds the OpenAPI-spec-walking logic tools/auditgen uses for every service it generates (see that command's -service flag). |