diff --git a/blog/2019-05-28-first-blog-post.md b/blog/2019-05-28-first-blog-post.md deleted file mode 100644 index 7d9f71c..0000000 --- a/blog/2019-05-28-first-blog-post.md +++ /dev/null @@ -1,13 +0,0 @@ ---- -slug: first-blog-post -title: First Blog Post -authors: [slorber, yangshun] -tags: [hola, docusaurus] -unlisted: true ---- - -Lorem ipsum dolor sit amet... - - - -...consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet diff --git a/blog/2019-05-29-long-blog-post.md b/blog/2019-05-29-long-blog-post.md deleted file mode 100644 index 22efbd3..0000000 --- a/blog/2019-05-29-long-blog-post.md +++ /dev/null @@ -1,45 +0,0 @@ ---- -slug: long-blog-post -title: Long Blog Post -authors: yangshun -tags: [hello, docusaurus] -unlisted: true ---- - -This is the summary of a very long blog post, - -Use a `` comment to limit blog post size in the list view. - - - -Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet - -Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet - -Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet - -Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet - -Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet - -Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet - -Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet - -Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet - -Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet - -Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet - -Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet - -Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet - -Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet - -Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet - -Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet - -Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet diff --git a/blog/2021-08-01-mdx-blog-post.mdx b/blog/2021-08-01-mdx-blog-post.mdx deleted file mode 100644 index e26f7e4..0000000 --- a/blog/2021-08-01-mdx-blog-post.mdx +++ /dev/null @@ -1,25 +0,0 @@ ---- -slug: mdx-blog-post -title: MDX Blog Post -authors: [slorber] -tags: [docusaurus] -unlisted: true ---- - -Blog posts support [Docusaurus Markdown features](https://docusaurus.io/docs/markdown-features), such as [MDX](https://mdxjs.com/). - -:::tip - -Use the power of React to create interactive blog posts. - -::: - -{/* truncate */} - -For example, use JSX to create an interactive button: - -```js - -``` - - diff --git a/blog/2021-08-26-welcome/docusaurus-plushie-banner.jpeg b/blog/2021-08-26-welcome/docusaurus-plushie-banner.jpeg deleted file mode 100644 index 11bda09..0000000 Binary files a/blog/2021-08-26-welcome/docusaurus-plushie-banner.jpeg and /dev/null differ diff --git a/blog/2021-08-26-welcome/index.md b/blog/2021-08-26-welcome/index.md deleted file mode 100644 index c409da8..0000000 --- a/blog/2021-08-26-welcome/index.md +++ /dev/null @@ -1,30 +0,0 @@ ---- -slug: welcome -title: Welcome -authors: [slorber, yangshun] -tags: [facebook, hello, docusaurus] -unlisted: true ---- - -[Docusaurus blogging features](https://docusaurus.io/docs/blog) are powered by the [blog plugin](https://docusaurus.io/docs/api/plugins/@docusaurus/plugin-content-blog). - -Here are a few tips you might find useful. - - - -Simply add Markdown files (or folders) to the `blog` directory. - -Regular blog authors can be added to `authors.yml`. - -The blog post date can be extracted from filenames, such as: - -- `2019-05-30-welcome.md` -- `2019-05-30-welcome/index.md` - -A blog post folder can be convenient to co-locate blog post images: - -![Docusaurus Plushie](./docusaurus-plushie-banner.jpeg) - -The blog supports tags as well! - -**And if you don't want a blog**: just delete this directory, and use `blog: false` in your Docusaurus config. diff --git a/blog/2025-08-26-welcome-to-openchoreo-blog.mdx b/blog/2025-08-26-welcome-to-openchoreo-blog.mdx new file mode 100644 index 0000000..6a8d987 --- /dev/null +++ b/blog/2025-08-26-welcome-to-openchoreo-blog.mdx @@ -0,0 +1,38 @@ +--- +slug: welcome-to-openchoreo-blog +title: Welcome to OpenChoreo Blog +authors: [sameera] +description: We’re excited to launch the OpenChoreo Blog! +--- + +import logo from '../static/img/openchoreo-logo.png'; + +Welcome to the OpenChoreo Blog, your new home for updates, ideas, and stories from the OpenChoreo open-source community! We’re just getting started, and we’re thrilled to share this journey with you. + +On this blog, we plan to post release updates, upcoming features, community adoption stories, and the occasional off-topic stuff (you’ve been warned). + +{/* truncate */} + +OpenChoreo Logo + +In the meantime, we’d love to hear your thoughts on the OpenChoreo logo. What comes to your mind when you see it? Feel free to share your impressions, interpretations, or wild guesses in whatever way you can. We’ll write more about the logo soon. + +To wrap things up, here’s a roundup of recent posts, talks, and videos that dive deeper into OpenChoreo or explore related ideas in the platform engineering space: +- [OpenChoreo GitHub repo](https://github.com/openchoreo/openchoreo) +- [OpenChoreo Architecture](https://openchoreo.dev/docs/next/overview/architecture/) +- [Why Companies Fail at Building Internal Developer Platforms (IDPs)](https://www.youtube.com/watch?v=K0ZQ2NmFRMo) +- [OpenChoreo: An Open Source Blueprint for Internal Developer Platforms](https://www.youtube.com/watch?v=9A-CIye50HY) +- [Platformless: How Choreo Built a Secure Kubernetes Platform with GitOps](https://itnext.io/platformless-how-choreo-built-a-secure-kubernetes-platform-with-gitops-b7bca909b9f3) + +We’re always looking for guest posts, community contributions, and feedback. If you’re building with OpenChoreo or thinking about it, don’t hesitate to reach out. + +Until next time — happy hacking, and welcome aboard. + + + + + + + + + diff --git a/blog/authors.yml b/blog/authors.yml index 0fd3987..794add2 100644 --- a/blog/authors.yml +++ b/blog/authors.yml @@ -1,25 +1,8 @@ -yangshun: - name: Yangshun Tay - title: Ex-Meta Staff Engineer, Co-founder GreatFrontEnd - url: https://linkedin.com/in/yangshun - image_url: https://github.com/yangshun.png +sameera: + name: Sameera Jayasoma + title: WSO2 + url: https://github.com/sameerajayasoma + image_url: https://github.com/sameerajayasoma.png page: true - socials: - x: yangshunz - linkedin: yangshun - github: yangshun - newsletter: https://www.greatfrontend.com - -slorber: - name: Sébastien Lorber - title: Docusaurus maintainer - url: https://sebastienlorber.com - image_url: https://github.com/slorber.png - page: - # customize the url of the author page at /blog/authors/ - permalink: '/all-sebastien-lorber-articles' - socials: - x: sebastienlorber - linkedin: sebastienlorber - github: slorber - newsletter: https://thisweekinreact.com + + diff --git a/docs/overview/architecture.md b/docs/overview/architecture.mdx similarity index 95% rename from docs/overview/architecture.md rename to docs/overview/architecture.mdx index 92907ba..c210070 100644 --- a/docs/overview/architecture.md +++ b/docs/overview/architecture.mdx @@ -3,11 +3,14 @@ title: Architecture description: Explore how OpenChoreo is architected across control, data, CI, and observability planes, and how these components work together to deliver a comprehensive Internal Developer Platform. --- -# OpenChoreo Architecture +import PlatformAPIDiagram from '../resources/openchoreo-platform-abstractions.png'; +import DeveloperAPIDiagram from '../resources/openchoreo-development-abstractions.png'; +import CellRuntimeDiagram from '../resources/openchoreo-cell-runtime-view.png'; +# OpenChoreo Architecture OpenChoreo is architected as a modular, Kubernetes-native control plane that integrates deeply with other open-source projects to provide a comprehensive, extensible Internal Developer Platform (IDP). -The Control Plane acts as the orchestrator, transforming high-level platform and developer intent into actionable workloads deployed across CI, Data planes, while wiring them into the Observability plane for visibility. +The Control Plane acts as the orchestrator, transforming high-level platform and developer intent into actionable workloads deployed across Data planes, while wiring them into the Observability plane for visibility. The diagram below illustrates how these components interact. @@ -37,7 +40,7 @@ The Control Plane is extensible, allowing integration with different backends fo ## Developer API The Developer API is a set of Kubernetes CRDs designed to simplify cloud-native application development. It provides self-service, low-cognitive-load abstractions so developers don’t have to deal with Kubernetes internals. -Platform API Diagram + These abstractions align with the Domain-Driven Design principles, where projects represent bounded contexts and components represent the individual services or workloads within a domain. Developers use these abstractions to describe the structure and intent of the application in a declarative manner without having to deal with runtime infrastructure details. @@ -58,7 +61,7 @@ These abstractions align with the Domain-Driven Design principles, where project ## Platform API The Platform API enables platform engineers to configure the overall platform topology. These CRDs define organizational boundaries, environment structure, runtime clusters, and automation logic. -Platform API Diagram + - **Organization** - A logical grouping of users and resources, typically aligned to a company, business unit, or team. @@ -81,7 +84,7 @@ To support multi-tenancy, environment isolation, and domain-driven design, the O In OpenChoreo, we refer to this namespace as a Cell — a secure, isolated, and observable boundary for all components belonging to that project-environment combination. The Cell becomes the unit of deployment, policy enforcement, and observability, aligning with the [cell-based architecture](https://github.com/wso2/reference-architecture/blob/master/reference-architecture-cell-based.md) pattern: a model where individual teams or domains operate independently within well-defined boundaries, while still benefiting from shared infrastructure capabilities. -Platform API Diagram + - **Cell** - A Cell is the runtime reification of a single project in OpenChoreo. It encapsulates all components of a project and controls how they communicate internally and externally through well-defined ingress and egress paths. diff --git a/docs/overview/what-is-openchoreo.mdx b/docs/overview/what-is-openchoreo.mdx index f48f815..51f036c 100644 --- a/docs/overview/what-is-openchoreo.mdx +++ b/docs/overview/what-is-openchoreo.mdx @@ -23,7 +23,7 @@ This creates gap: **Platform engineers are left to build the real platform** def - A **Control Plane** that understands and enforces these APIs with GitOps support - A **built-in CI system** - An **opinionated Data Plane** with runtime enforcement of design-time semantics -- Built-in **Security**, **networking** and **observability** integrations +- Built-in **security**, **networking** and **observability** integrations With OpenChoreo, we are bringing the best ideas of [WSO2 Choreo](https://choreo.dev) (an IDP as a Service) to the open-source community. WSO2 Choreo is designed not just to automate software delivery workflows, but to support engineering best practices: enforcing architecture standards, promoting service reuse, and integrating API management and observability. @@ -38,7 +38,7 @@ OpenChoreo is made up of several key components that work together to deliver a - **CI Plane** - A built-in CI engine powered by Argo Workflows. It builds the container images, runs tests and publishes artifacts. It is an optional plane. - **Observability Plane** - Out-of-the-box visibility with logs, metrics and traces, using tools like Prometheus, Fluent Bit and OpenSearch. -Learn more about how these components fit together in the [OpenChoreo Architecture](./architecture.md) section. +Learn more about how these components fit together in the [OpenChoreo Architecture](./architecture.mdx) section. ## Current Status @@ -51,7 +51,7 @@ See our [Roadmap](https://github.com/orgs/openchoreo/projects/4) for upcoming fe Ready to try OpenChoreo? Start here: -1. **[Architecture](./architecture.md)** - Understand the multi-plane architecture +1. **[Architecture](./architecture.mdx)** - Understand the multi-plane architecture 2. **[Quick Start Guide](../getting-started/quick-start-guide.mdx)** - Try OpenChoreo in minutes using a Dev Container 3. **[Installation Guide](../getting-started/single-cluster.mdx)** - Deploy OpenChoreo in your environment 4. **[Concepts](../concepts/developer-abstractions.md)** - Learn the platform abstractions diff --git a/docusaurus.config.ts b/docusaurus.config.ts index 0098f20..c8ede29 100644 --- a/docusaurus.config.ts +++ b/docusaurus.config.ts @@ -99,7 +99,7 @@ const config: Config = { position: 'left', label: 'Documentation', }, - // {to: '/blog', label: 'Blog', position: 'left'}, + {to: '/blog', label: 'Blog', position: 'left'}, { type: 'docsVersionDropdown', position: 'right', @@ -158,10 +158,10 @@ const config: Config = { { title: 'More', items: [ - // { - // label: 'Blog', - // to: '/blog', - // }, + { + label: 'Blog', + to: '/blog', + }, { label: 'GitHub', href: 'https://github.com/openchoreo/openchoreo', diff --git a/versioned_docs/version-v0.3.x/overview/architecture.md b/versioned_docs/version-v0.3.x/overview/architecture.md deleted file mode 100644 index e94af69..0000000 --- a/versioned_docs/version-v0.3.x/overview/architecture.md +++ /dev/null @@ -1,335 +0,0 @@ ---- -title: Architecture -description: Explore how OpenChoreo is architected across control, data, CI, and observability planes, and how these components work together to deliver a comprehensive Internal Developer Platform. ---- - -# OpenChoreo Architecture - -OpenChoreo implements a **multi-plane architecture** that separates infrastructure concerns across four specialized -planes: Control, Data, Build, and Observability. This architectural pattern enables clear separation of -responsibilities, independent scaling, and enhanced security through isolation boundaries. - -## Overview - -In OpenChoreo's architecture, each plane operates as a distinct functional unit with its own lifecycle, scaling -characteristics, and security boundaries. The planes work together through well-defined APIs and protocols to deliver a -complete Internal Developer Platform (IDP). - -The four planes are: - -- **Control Plane**: Orchestrates the platform and manages desired state -- **Data Plane**: Runs application workloads with cell-based isolation -- **Build Plane**: Executes CI/CD workflows in isolated environments -- **Observability Plane**: Aggregates metrics, logs, and traces from all planes - -While production deployments typically use separate Kubernetes clusters for each plane, OpenChoreo supports flexible -deployment topologies including colocated setups for development environments. - ---- - -## Control Plane - -The **Control Plane** is the brain of OpenChoreo, implementing the platform's core logic as Kubernetes operators that -extend the Kubernetes API. It manages all developer intent and orchestrates platform-wide activities. - -### Architecture Components - -The Control Plane consists of several key components: - -- **OpenChoreo Controller Manager**: A collection of Kubernetes controllers that reconcile custom resources and maintain - desired state -- **API Server (openchoreo-api)**: REST API that provides programmatic access for CLI tools, UI dashboards, and CI/CD - systems -- **Webhook Server**: Validates and mutates custom resources to enforce policies and defaults - -### Custom Resource Definitions (CRDs) - -OpenChoreo extends Kubernetes with three categories of CRDs: - -**Platform Resources** (Platform Engineer focused): - -- Examples: `Organization`, `DataPlane`, `Environment`, etc. - -**Application Resources** (Developer focused): - -- Examples: `Project`, `Component`, `Service`, etc. - -**Runtime Resources** (System managed): - -- Examples: `ServiceBinding`, `WebApplicationBinding`, `Release`, etc. - -### Resource Management Patterns - -The Control Plane implements several key patterns: - -**Claim/Class Pattern**: Platform engineers define Classes (templates with governance policies), while developers create -Claims (Services, WebApplications, etc.) that reference these Classes. This separation ensures standardization while -maintaining developer autonomy. - -**Environment Independence**: Developer resources (Component, Workload, Service) are environment-agnostic. -Environment-specific configurations are handled through Binding resources during deployment. - -**Progressive Delivery**: The Control Plane manages promotion workflows through DeploymentPipelines, creating -environment-specific Bindings that combine workload specifications with runtime configurations. - -### Cross-Plane Orchestration - -The Control Plane coordinates activities across other planes: - -- **DataPlane Management**: Registers and manages connections to multiple Kubernetes clusters, handling credentials, TLS - certificates, and cluster-specific configurations -- **BuildPlane Dispatching**: Triggers build jobs on registered BuildPlanes, managing build configurations and artifact - repositories -- **Observability Integration**: Configures connections to Observer APIs for centralized logging and metrics collection - ---- - -## Data Plane - -The **Data Plane** is where applications run, implementing a cell-based architecture that provides strong isolation, -security, and observability for workloads. Each Data Plane is a Kubernetes cluster enhanced with networking, security, -and API management capabilities. - -### Cell-Based Architecture - -At runtime, each **Project** becomes a **Cell** - an isolated, secure unit that encapsulates all components of a bounded -context. This architecture pattern: - -- **Isolates workloads**: Each cell runs in dedicated namespaces with network boundaries -- **Enforces domain boundaries**: Aligns with Domain-Driven Design principles -- **Enables autonomous operation**: Cells can be independently deployed and managed -- **Provides clear interfaces**: All inter-cell communication goes through well-defined gateways - -### Networking Stack - -The Data Plane leverages advanced networking technologies: - -**Cilium (eBPF-based networking)**: - -- Automatically generates network policies to enforce security boundaries -- Provides visibility into network flows and performance metrics -- Workload communication is secured with WireGuard transport encryption - -**Envoy Gateway**: - -- Manages ingress traffic with advanced routing capabilities -- Provides API management features (rate limiting, authentication) -- Handles TLS termination and certificate management -- Supports multiple protocols (HTTP/HTTPS, gRPC, WebSocket) - -### Traffic Flow Patterns - -Data Planes implement structured traffic patterns through directional gateways: - -- **Northbound Ingress**: Routes public internet traffic into cells (public APIs, web apps) -- **Southbound Egress**: Manages outbound internet access (third-party APIs, external services) -- **Westbound Ingress**: Handles organization-internal traffic between cells -- **Eastbound Egress**: Controls inter-cell communication within the platform - -Each visibility scope (`public`, `organization`, `project`) maps to specific gateway configurations, ensuring traffic -flows only through authorized paths. - -### Workload Management - -The Data Plane handles workload deployment through: - -- **Namespace Isolation**: Each Project/Environment combination gets dedicated namespaces -- **Release Deployment**: The Control Plane pushes Release resources containing Kubernetes manifests -- **Multi-tenancy**: Organizations are isolated through namespace boundaries and network policies -- **Resource Management**: Enforces quotas, limits, and scheduling constraints per project - -### Multi-Region Support - -Organizations can register multiple Data Planes for: - -- Geographic distribution (e.g., `us-west-2`, `eu-central-1`) -- Environment separation (e.g., `staging`, `production`) -- Compliance requirements (e.g., data residency) -- Disaster recovery and high availability - -Each Data Plane is registered using a `DataPlane` custom resource that stores connection details, credentials, and -configuration. - ---- - -## Build Plane - -The **Build Plane** provides dedicated infrastructure for executing continuous integration workflows, separating build -workloads from runtime environments. It handles source code compilation, container image creation, and test execution in -an isolated, scalable environment. - -### Argo Workflows Integration - -The Build Plane is powered by **Argo Workflows**, which provides: - -- **Workflow Orchestration**: Manages complex build pipelines with dependencies -- **Parallel Execution**: Runs multiple build steps concurrently for faster builds -- **Resource Management**: Controls CPU and memory allocation for build pods -- **Build Monitoring**: Tracks build progress and provides real-time status updates - -### Build Strategies - -OpenChoreo supports multiple build strategies to accommodate different application types: - -**Cloud Native Buildpacks**: - -- Automatically detects application type and runtime -- Provides consistent, reproducible builds without Dockerfiles -- Includes security patches and best practices by default -- Supports multiple languages and frameworks - -**Docker Builds**: - -- Uses custom Dockerfiles for complete control -- Supports multi-stage builds for optimized images -- Enables specialized build requirements - -### Build Workflow - -The build process follows a structured workflow: - -1. **Build Trigger**: Control Plane creates a Build resource from Component specifications -2. **Source Retrieval**: Clones source code from configured Git repositories -3. **Image Building**: Executes the selected build strategy (Buildpack or Docker) -4. **Registry Push**: Publishes container images to configured registries with appropriate tags -5. **Status Updates**: Reports build progress and results back to the Control Plane - -### Security & Isolation - -The Build Plane provides strong security boundaries: - -- **Namespace Isolation**: Each organization gets dedicated build namespaces -- **Resource Isolation**: Build jobs run independently without affecting other builds -- **Registry Authentication**: Secure credential management for image repositories - -### Integration Points - -The Build Plane integrates with other components: - -- **Control Plane Communication**: Receives build requests and reports status -- **Container Registries**: Pushes built images to configured registries -- **Observer API**: Streams build logs for monitoring and debugging - -Each Build Plane is registered using a `BuildPlane` custom resource, which stores connection details and configuration -for the Control Plane to dispatch build jobs. - ---- - -## Observability Plane - -The **Observability Plane** provides centralized logging infrastructure for the entire platform, collecting and -aggregating logs from all other planes for monitoring, debugging, and analysis. - -### Core Components - -**OpenSearch**: - -- Serves as the central log aggregation and search platform -- Provides full-text search capabilities across all platform logs -- Stores structured and unstructured log data with configurable retention -- Enables complex queries and log analysis - -**Observer API**: - -- Exposes a unified interface for querying logs -- Provides authenticated access to log data -- Supports filtering by organization, project, and component -- Enables integration with external tools and dashboards - -### Log Collection Architecture - -The Observability Plane implements a distributed log collection pattern: - -- **Fluentbit Agents**: Deployed on Control, Data, and Build planes to collect logs -- **Log Forwarding**: Fluentbit agents ship logs to the central OpenSearch cluster -- **Structured Logging**: Logs are enriched with metadata (plane, organization, project, component) - -### Integration with Other Planes - -Unlike other planes, the Observability Plane: - -- Has no custom resource definitions (CRDs) to manage -- Operates independently after initial setup via Helm charts -- Receives log streams from all planes through Fluentbit -- Provides read-only access through the Observer API - -Each plane connects to the Observability Plane by: - -- Configuring Fluentbit with OpenSearch endpoints -- Authenticating with appropriate credentials -- Enriching logs with plane-specific metadata - -### Deployment Flexibility - -The Observability Plane supports various deployment models: - -- **Dedicated Cluster**: Recommended for production with high log volumes -- **Colocated Deployment**: Can share infrastructure with other planes in development -- **Regional Placement**: Often deployed near Data Planes to minimize data transfer costs -- **Non-Kubernetes Options**: Can run on bare metal or cloud-managed services (e.g., Amazon OpenSearch) - ---- - -## Deployment Patterns - -OpenChoreo's flexible architecture supports various deployment topologies to match different organizational needs and -stages of adoption. - -### Development Setup - -For local development and testing, all planes can be deployed in a single Kubernetes cluster: - -- **Single Cluster**: All four planes share the same cluster with namespace separation -- **Minimal Resources**: Reduced replica counts and resource allocations -- **Simplified Networking**: No cross-cluster communication required -- **Quick Start**: Ideal for evaluating OpenChoreo and development environments - -This pattern is used in the OpenChoreo Quick Start guide and is suitable for teams getting started with the platform. - -### Production Setup - -Production deployments typically use dedicated clusters for each plane: - -- **Control Plane**: Dedicated cluster in a central region -- **Data Planes**: Multiple clusters across regions (e.g., us-west-2, eu-central-1) -- **Build Plane**: Isolated cluster for CI/CD workloads -- **Observability Plane**: Dedicated cluster or managed service for log aggregation - -This pattern provides: - -- Maximum isolation between planes -- Independent scaling and maintenance -- Geographic distribution for compliance and performance -- High availability and disaster recovery options - -### Hybrid Setup - -Many organizations use a hybrid approach that balances isolation with operational simplicity: - -- **Control + Build Plane**: Colocated in a management cluster -- **Data Planes**: Separate clusters for production and non-production -- **Observability**: Managed service (e.g., Amazon OpenSearch) or shared cluster - -This pattern works well for: - -- Medium-sized organizations with limited operational overhead -- Teams transitioning from development to production -- Cost-conscious deployments that still require production isolation - -### Multi-Environment Strategy - -Organizations typically map environments to Data Planes: - -- **Development Environment**: Shared Data Plane with relaxed policies -- **Staging Environment**: Dedicated Data Plane mirroring production -- **Production Environment**: Multiple Data Planes for regions and availability zones - ---- - -## Next Steps - -- **[Concepts](../concepts/developer-abstractions.md)** - Learn about Projects, Components, and other abstractions -- **[Quick Start Guide](../getting-started/quick-start-guide.mdx)** - Try OpenChoreo with a single-cluster development - setup -- **[Installation Guide](../getting-started/single-cluster.mdx)** - Deploy OpenChoreo in your environment -- **[API Reference](../reference/api/application/project.md)** - Detailed documentation of all custom resources diff --git a/versioned_docs/version-v0.3.x/overview/architecture.mdx b/versioned_docs/version-v0.3.x/overview/architecture.mdx new file mode 100644 index 0000000..c210070 --- /dev/null +++ b/versioned_docs/version-v0.3.x/overview/architecture.mdx @@ -0,0 +1,132 @@ +--- +title: Architecture +description: Explore how OpenChoreo is architected across control, data, CI, and observability planes, and how these components work together to deliver a comprehensive Internal Developer Platform. +--- + +import PlatformAPIDiagram from '../resources/openchoreo-platform-abstractions.png'; +import DeveloperAPIDiagram from '../resources/openchoreo-development-abstractions.png'; +import CellRuntimeDiagram from '../resources/openchoreo-cell-runtime-view.png'; + +# OpenChoreo Architecture +OpenChoreo is architected as a modular, Kubernetes-native control plane that integrates deeply with other open-source projects to provide a comprehensive, extensible Internal Developer Platform (IDP). + +The Control Plane acts as the orchestrator, transforming high-level platform and developer intent into actionable workloads deployed across Data planes, while wiring them into the Observability plane for visibility. + +The diagram below illustrates how these components interact. + +![](../resources/openchoreo_components.svg) + +Each plane in OpenChoreo operates as a distinct functional unit, with its own lifecycle, scaling behavior, and security boundaries. Together, these planes and supporting interfaces form the core components of the platform: +- [Control Plane](#control-plane) +- [Developer API](#developer-api) +- [Platform API](#platform-api) +- [Data Plane](#data-plane) +- [CI Plane](#ci-plane) +- [Observability Plane](#observability-plane) + +## Control Plane + +The brain of OpenChoreo. It watches developer- and platform-defined CRDs, validates and processes them, and coordinates activities across other planes. It translates intent such as "deploy this component" or "connect these services" into concreteinfrastructure actions. + +Responsibilities include: + • Validating CRD instances and resolving references (e.g., Connections between Components) + • Applying policy and environment-specific rules + • Coordinating CI jobs, deployments, and observability configs + • Reconciling desired state with actual state across all planes + • Tracking the state of Components across environments and Data Planes + +The Control Plane is extensible, allowing integration with different backends for image building, observability tooling, environment provisioning, and more. + +## Developer API +The Developer API is a set of Kubernetes CRDs designed to simplify cloud-native application development. It provides self-service, low-cognitive-load abstractions so developers don’t have to deal with Kubernetes internals. + + + +These abstractions align with the Domain-Driven Design principles, where projects represent bounded contexts and components represent the individual services or workloads within a domain. Developers use these abstractions to describe the structure and intent of the application in a declarative manner without having to deal with runtime infrastructure details. + +- **Project** + - A cloud-native application composed of multiple components. Serves as the unit of isolation. + - Maps to a set of Namespaces (one per Environment) in one or more Data planes. +- **Component** + - A deployable unit within a project, such as a web service, API, worker, or scheduled task. + - Maps to workload resources like Deployment, Job, or StatefulSet. +- **Endpoint** + - A network-accessible interface exposed by a component, including routing rules, supported protocols, and visibility scopes (e.g., public, organization, project). + - Maps to HTTPRoute (for HTTP), Service resources, and routes via shared ingress gateways. Visibility is enforced via Cilium network policies. +- **Connection** + - An outbound service dependency defined by a component, targeting either other components or external systems. + - Maps to Cilium network policies and is routed through egress gateways. + + +## Platform API +The Platform API enables platform engineers to configure the overall platform topology. These CRDs define organizational boundaries, environment structure, runtime clusters, and automation logic. + + + +- **Organization** + - A logical grouping of users and resources, typically aligned to a company, business unit, or team. +- **Data Plane** + - A Kubernetes cluster to host one or more of your deployment environments. +- **Environment** + - A runtime context (e.g., dev, test, staging, prod) where workloads are deployed and executed. +- **Deployment Pipeline** + - A defined process that governs how workloads are promoted across environments. +- **CI Plane** + - A Kubernetes cluster dedicated to running continuous integration (CI) jobs and pipelines. +- **Observability Plane** + - A Kubernetes cluster focused on collecting and analyzing telemetry data (logs, metrics, traces) from all other planes. + + +## Data Plane +The Data Plane consists of one or more Kubernetes clusters where application workloads run. It is enhanced with eBPF-based zero-trust networking (via Cilium), observability tooling, and API management components to ensure secure and scalable communication. + +To support multi-tenancy, environment isolation, and domain-driven design, the OpenChoreo Control Plane maps each Project in a given Environment (e.g., dev, staging, prod) to a dedicated Kubernetes namespace in the Data Plane. + +In OpenChoreo, we refer to this namespace as a Cell — a secure, isolated, and observable boundary for all components belonging to that project-environment combination. The Cell becomes the unit of deployment, policy enforcement, and observability, aligning with the [cell-based architecture](https://github.com/wso2/reference-architecture/blob/master/reference-architecture-cell-based.md) pattern: a model where individual teams or domains operate independently within well-defined boundaries, while still benefiting from shared infrastructure capabilities. + + + +- **Cell** + - A Cell is the runtime reification of a single project in OpenChoreo. It encapsulates all components of a project and controls how they communicate internally and externally through well-defined ingress and egress paths. + - Communication between components in the same cell is permitted without interception. + - Cilium and eBPF are used to enforce fine-grained network policies across all ingress and egress paths. +- **Northbound Ingress** + - Routes incoming traffic from external (internet) sources into the cell. + - Endpoints with `visibility: public` are exposed through this ingress path. +- **Southbound Egress** + - Handles outbound Internet access from components in the Cell. Connections to external services are routed through this egress path. +- **Westbound Ingress** + - Handles traffic entering the Cell from within the organization, be it from another cell or just from the internal network. + - Endpoints with `visibility: organization` are exposed through this ingress path. +- **Eastbound Egress** + - Handles outbound traffic to other cells or to the internal network. + +## CI Plane + +The CI Plane in OpenChoreo provides dedicated infrastructure for executing continuous integration workflows, separating build-time activities from runtime environments. It ensures that tasks such as source code compilation, container image creation, and test execution are performed in a secure, isolated, and scalable environment, without interfering with the application runtime. + +By default, the CI Plane is powered by Argo Workflows, a Kubernetes-native workflow engine. However, OpenChoreo is designed to be flexible, you can customize the CI Plane to use an alternative engine like Tekton, depending on your organizational needs. + +While tightly integrated, the CI Plane is an optional component. If you already have an existing CI system, such as GitHub Actions, GitLab CI, or Jenkins, you can continue to use it instead of OpenChoreo’s built-in CI. In this setup, OpenChoreo can ingest externally built container images and proceed with deployment and observability workflows as usual. + +## Observability Plane + +The Observability Plane in OpenChoreo provides centralized logging infrastructure across all planes, enabling platform-wide monitoring, debugging, and analytics. It collects and aggregates logs from the Control, Data, and CI planes using a distributed log collection pattern powered by Fluent Bit agents. These agents run on each plane, enrich logs with metadata (such as plane, organization, project, and component), and forward them to a central OpenSearch cluster. + +OpenSearch serves as the core log aggregation and search platform, supporting full-text search, structured/unstructured log storage, configurable retention, and complex queries. On top of this, the Observer API provides a secure, unified interface for querying logs, with fine-grained filtering by organization, project, or component, making it easy to integrate with external tools and dashboards. + +Unlike other planes, the Observability Plane doesn’t require its own CRDs. It operates independently after its initial Helm-based setup. Each participating plane integrates by configuring Fluent Bit to stream logs to OpenSearch using authenticated credentials. The Observer API then provides read-only access to this log data, ensuring that observability remains a first-class, yet decoupled, aspect of the platform. + +## Full System View +The diagram below shows a complete view of the OpenChoreo Internal Developer Platform, including how platform abstractions, developer workflows, and control planes interact with runtime infrastructure and cloud-native tools. + +![](../resources/openchoreo-diagram-v1-with-borders.png) + + +This view illustrates the full path from source code and platform configuration through build, deployment, API exposure, and runtime observability — all orchestrated by OpenChoreo. + +## Deployment Topologies +OpenChoreo supports multiple deployment patterns to suit different organizational needs, from local development to large-scale, multi-cluster production setups. +- In development or testing setups, all planes can be deployed into a single Kubernetes cluster using namespace isolation. +- In production environments, each plane is typically deployed in a separate cluster for scalability, fault tolerance, and security. +- Hybrid topologies are also supported, allowing teams to colocate certain planes (e.g., Control + CI) for cost or operational efficiency. diff --git a/versioned_docs/version-v0.3.x/overview/what-is-openchoreo.mdx b/versioned_docs/version-v0.3.x/overview/what-is-openchoreo.mdx index c307763..51f036c 100644 --- a/versioned_docs/version-v0.3.x/overview/what-is-openchoreo.mdx +++ b/versioned_docs/version-v0.3.x/overview/what-is-openchoreo.mdx @@ -8,76 +8,41 @@ import Link from '@docusaurus/Link'; import {versions} from '../_constants.mdx'; # What is OpenChoreo? +OpenChoreo is a comprehensive, open-source Internal Developer Platform (IDP) designed for platform engineering (PE) teams who want to streamline developer workflows and deliver Internal Developer Portals without having to build everything from scratch. -OpenChoreo is an open-source Internal Developer Platform (IDP) that makes Kubernetes accessible to development teams. It -provides a complete platform engineering solution that transforms complex infrastructure into simple, self-service -developer experiences. +OpenChoreo orchestrates many CNCF and other projects to give a comprehensive framework for PE teams to build the platform they want. -OpenChoreo brings the best ideas from [WSO2 Choreo](https://choreo.dev) (an enterprise IDP) to the open-source -community. +## Why OpenChoreo? -## Who Should Use OpenChoreo? +Kubernetes gives you powerful primitives like Namespaces, Deployments, CronJobs, Services and NetworkPolicies—but they are too low-level for most developers. -OpenChoreo is designed for: +This creates gap: **Platform engineers are left to build the real platform** defining higher-level APIs for developers and integrating tools for security, CI/CD, observability and operational guardrails. -- **Platform Engineering Teams** building internal developer platforms on Kubernetes -- **DevOps Teams** looking to standardize deployments and reduce operational overhead -- **Development Teams** wanting self-service deployment without infrastructure complexity -- **Organizations** seeking to accelerate cloud-native adoption while maintaining security and compliance +**OpenChoreo fills that gap.** It provides all essentional building blocks of an IDP, including: +- **High-level APIs** for modeling cloud-native applications +- A **Control Plane** that understands and enforces these APIs with GitOps support +- A **built-in CI system** +- An **opinionated Data Plane** with runtime enforcement of design-time semantics +- Built-in **security**, **networking** and **observability** integrations -## The Problem +With OpenChoreo, we are bringing the best ideas of [WSO2 Choreo](https://choreo.dev) (an IDP as a Service) to the open-source community. WSO2 Choreo is designed not just to automate software delivery workflows, but to support engineering best practices: enforcing architecture standards, promoting service reuse, and integrating API management and observability. -Modern cloud-native development has become unnecessarily complex: +## OpenChoreo Components -- **Kubernetes is powerful but overwhelming**: Developers need to understand pods, services, ingress, ConfigMaps, and - dozens of other concepts just to deploy a simple application -- **Every team reinvents the wheel**: Without standards, each team creates their own deployment patterns, leading to - inconsistency and technical debt -- **Security is an afterthought**: Teams often sacrifice security for speed, leaving applications vulnerable -- **Platform building is expensive**: Companies spend months or years building internal platforms from scratch +OpenChoreo is made up of several key components that work together to deliver a comprehensive IDP. -## How OpenChoreo Solves It +- **Control Plane** - The orchestration layer that watch developer and platform APIs, validates configurations and translate them into Kubernetes-native and cloud-native infrastructure. +- **Developer API** - Simplified, self-service interfaces for developers to model, deploy and managed to the full SDLC of cloud-native applications, without needing to understand platform internals. +- **Platform API** - Declarative interfaces used by platform engineers to configure and manage OpenChoreo installation. +- **Data Plane** - The execution environment for applications that is built on Kubernetes and extended with Cilium, Envoy Gateway and other CNCF tools. Data Plane is where runtime semantics are enforced. +- **CI Plane** - A built-in CI engine powered by Argo Workflows. It builds the container images, runs tests and publishes artifacts. It is an optional plane. +- **Observability Plane** - Out-of-the-box visibility with logs, metrics and traces, using tools like Prometheus, Fluent Bit and OpenSearch. -OpenChoreo provides a layered approach with clear separation between platform engineering and development: - -**For Platform Engineers:** - -- Set up **Data**, **Build**, and **Observability Planes** for infrastructure separation -- Define **Organizations** for multi-tenant isolation -- Configure **Environments** on DataPlanes -- Create **Classes** (ServiceClass, WebApplicationClass) to enforce standards -- Configure **DeploymentPipelines** for promotion workflows - -**For Developers:** - -- Create **Projects** to organize related services (aligned with DDD bounded contexts) -- Define **Components** for applications -- Specify **Workloads** with runtime configurations -- Deploy **applications** (Services, WebApplications, ScheduledTasks) using platform Classes - -The platform automatically handles the complexity of Kubernetes, including: - -- [Cell-based isolation](https://github.com/wso2/reference-architecture/blob/master/reference-architecture-cell-based.md) - with zero-trust networking -- Automatic mTLS for all service communication -- Built-in observability and distributed tracing -- CI/CD pipelines with GitOps workflows -- RBAC and access control - -## What Makes OpenChoreo Different - -- **Kubernetes Native**: Built as operators extending Kubernetes, not a layer on top -- **Complete Solution**: Includes build, deploy, networking, API management, and observability—not just a UI -- **Open Source**: No vendor lock-in, transparent development, community-driven -- **Separation of Concerns**: Platform engineers define standards through Classes, developers express intent through - Claims - -Built on proven CNCF projects including Cilium (eBPF networking), Buildpacks, Argo (workflows), and Envoy Gateway (API -management). +Learn more about how these components fit together in the [OpenChoreo Architecture](./architecture.mdx) section. ## Current Status -OpenChoreo is currently in **active development** (v1alpha1). While the core platform is functional, APIs may change as +OpenChoreo is currently in **active development**. While the core platform is functional, APIs may change as we incorporate community feedback. We recommend starting with non-production workloads as you evaluate the platform. See our [Roadmap](https://github.com/orgs/openchoreo/projects/4) for upcoming features and stable release timeline. @@ -86,16 +51,15 @@ See our [Roadmap](https://github.com/orgs/openchoreo/projects/4) for upcoming fe Ready to try OpenChoreo? Start here: -1. **[Architecture](./architecture.md)** - Understand the multi-plane architecture +1. **[Architecture](./architecture.mdx)** - Understand the multi-plane architecture 2. **[Quick Start Guide](../getting-started/quick-start-guide.mdx)** - Try OpenChoreo in minutes using a Dev Container 3. **[Installation Guide](../getting-started/single-cluster.mdx)** - Deploy OpenChoreo in your environment 4. **[Concepts](../concepts/developer-abstractions.md)** - Learn the platform abstractions ## Community +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](https://github.com/openchoreo/openchoreo/blob/main/docs/contributors/contribute.md) – Learn how to get started. +- [Report an Issue](https://github.com/openchoreo/openchoreo/issues) – Help us improve OpenChoreo. +- [Join our Discord](https://discord.com/invite/asqDFC8suT) – Be part of the community. -OpenChoreo is an open-source project that welcomes contributions. Join our community: - -- [GitHub Discussions](https://github.com/openchoreo/openchoreo/discussions) for questions and ideas -- [Discord](https://discord.com/invite/asqDFC8suT) for real-time chat -- Contributing Guide to get - involved +We’re excited to have you onboard! diff --git a/versioned_docs/version-v0.3.x/resources/openchoreo-cell-runtime-view.png b/versioned_docs/version-v0.3.x/resources/openchoreo-cell-runtime-view.png new file mode 100644 index 0000000..917dc41 Binary files /dev/null and b/versioned_docs/version-v0.3.x/resources/openchoreo-cell-runtime-view.png differ diff --git a/versioned_docs/version-v0.3.x/resources/openchoreo-development-abstractions.png b/versioned_docs/version-v0.3.x/resources/openchoreo-development-abstractions.png new file mode 100644 index 0000000..ece2032 Binary files /dev/null and b/versioned_docs/version-v0.3.x/resources/openchoreo-development-abstractions.png differ diff --git a/versioned_docs/version-v0.3.x/resources/openchoreo-diagram-v1-with-borders.png b/versioned_docs/version-v0.3.x/resources/openchoreo-diagram-v1-with-borders.png new file mode 100644 index 0000000..0c146bb Binary files /dev/null and b/versioned_docs/version-v0.3.x/resources/openchoreo-diagram-v1-with-borders.png differ diff --git a/versioned_docs/version-v0.3.x/resources/openchoreo-platform-abstractions.png b/versioned_docs/version-v0.3.x/resources/openchoreo-platform-abstractions.png new file mode 100644 index 0000000..148268a Binary files /dev/null and b/versioned_docs/version-v0.3.x/resources/openchoreo-platform-abstractions.png differ diff --git a/versioned_docs/version-v0.3.x/resources/openchoreo_components.svg b/versioned_docs/version-v0.3.x/resources/openchoreo_components.svg new file mode 100644 index 0000000..c5ae2ae --- /dev/null +++ b/versioned_docs/version-v0.3.x/resources/openchoreo_components.svg @@ -0,0 +1 @@ + \ No newline at end of file