diff --git a/docs/reference/changelog.md b/docs/reference/changelog.md
index d94bb7b..e1f77b8 100644
--- a/docs/reference/changelog.md
+++ b/docs/reference/changelog.md
@@ -9,9 +9,9 @@ This document tracks all notable changes, new features, breaking changes, and im
## Current Release
-### [v0.3.0] - 2025-07-31
+### [v0.4.0] - 2025-11-17
-**[π View Full Release Notes](https://github.com/openchoreo/openchoreo/releases/tag/v0.3.0)**
+**[π View Full Release Notes](https://github.com/openchoreo/openchoreo/releases/tag/v0.4.0)**
---
@@ -21,6 +21,10 @@ This document tracks all notable changes, new features, breaking changes, and im
**[π View Full Release Notes](https://github.com/openchoreo/openchoreo/releases/tag/v0.2.0)**
+### [v0.3.0] - 2025-07-31
+
+**[π View Full Release Notes](https://github.com/openchoreo/openchoreo/releases/tag/v0.3.0)**
+
---
## Upcoming Releases and Release Schedule
diff --git a/docusaurus.config.ts b/docusaurus.config.ts
index 4c40bac..705bf47 100644
--- a/docusaurus.config.ts
+++ b/docusaurus.config.ts
@@ -43,10 +43,14 @@ const config: Config = {
'classic',
{
docs: {
- lastVersion: 'v0.3.x', // TODO: Remove this when v0.5.x is released to mark it as the latest version
+ lastVersion: 'v0.4.x', // TODO: Update this when v0.5.x is released to mark it as the latest version
versions: {
+ 'v0.5.x': {
+ label: 'v0.5.x (edge)',
+ banner: 'none',
+ },
'v0.4.x': {
- label: 'v0.4.x (edge)',
+ label: 'v0.4.x',
banner: 'none',
},
'v0.3.x': {
@@ -86,9 +90,9 @@ const config: Config = {
themeConfig: {
announcementBar: {
- id: 'release_v0_3_1',
+ id: 'release_v0_4_0',
content:
- 'ποΈ OpenChoreo v0.3.2 is released! ποΈ',
+ 'ποΈ OpenChoreo v0.4.0 is released! ποΈ',
isCloseable: true,
},
algolia: {
diff --git a/versioned_docs/version-v0.4.x/reference/changelog.md b/versioned_docs/version-v0.4.x/reference/changelog.md
index d94bb7b..e1f77b8 100644
--- a/versioned_docs/version-v0.4.x/reference/changelog.md
+++ b/versioned_docs/version-v0.4.x/reference/changelog.md
@@ -9,9 +9,9 @@ This document tracks all notable changes, new features, breaking changes, and im
## Current Release
-### [v0.3.0] - 2025-07-31
+### [v0.4.0] - 2025-11-17
-**[π View Full Release Notes](https://github.com/openchoreo/openchoreo/releases/tag/v0.3.0)**
+**[π View Full Release Notes](https://github.com/openchoreo/openchoreo/releases/tag/v0.4.0)**
---
@@ -21,6 +21,10 @@ This document tracks all notable changes, new features, breaking changes, and im
**[π View Full Release Notes](https://github.com/openchoreo/openchoreo/releases/tag/v0.2.0)**
+### [v0.3.0] - 2025-07-31
+
+**[π View Full Release Notes](https://github.com/openchoreo/openchoreo/releases/tag/v0.3.0)**
+
---
## Upcoming Releases and Release Schedule
diff --git a/versioned_docs/version-v0.5.x/_constants.mdx b/versioned_docs/version-v0.5.x/_constants.mdx
new file mode 100644
index 0000000..5feb309
--- /dev/null
+++ b/versioned_docs/version-v0.5.x/_constants.mdx
@@ -0,0 +1,7 @@
+[//] # (This file stores the constants used across the documentation.)
+
+export const versions = {
+ dockerTag: 'latest-dev',
+ githubRef: 'main', // Used for the GitHub Raw URL references. Example: main, latest, v0.1.0
+ helmChart: '0.0.0-latest-dev',
+};
diff --git a/versioned_docs/version-v0.5.x/concepts/developer-abstractions.md b/versioned_docs/version-v0.5.x/concepts/developer-abstractions.md
new file mode 100644
index 0000000..7e0c6f8
--- /dev/null
+++ b/versioned_docs/version-v0.5.x/concepts/developer-abstractions.md
@@ -0,0 +1,103 @@
+---
+title: Developer Abstractions
+description: Developer abstractions for building and running applications
+---
+
+# Developer Abstractions
+
+Developer abstractions in OpenChoreo enable teams to build, deploy, and operate cloud-native applications without
+managing infrastructure complexity. These abstractions provide a declarative model for expressing application
+architecture, dependencies, and operational requirements while the platform handles the underlying Kubernetes resources,
+networking, and security configurations automatically.
+
+## Project
+
+A **Project** represents a bounded context in Domain-Driven Design terms - a cohesive collection of components that
+together implement a specific business capability or application domain. It serves as the primary organizational unit
+for developers, defining clear boundaries for code ownership, deployment coordination, and operational responsibility.
+
+Projects establish both logical and physical boundaries in the platform. Logically, they group related components that
+share common business logic, data models, and team ownership. Physically, they translate into isolated deployment units
+with dedicated namespaces, network boundaries, and security policies. This alignment between organizational structure
+and technical architecture enables teams to work autonomously while maintaining clear integration points with other
+projects.
+
+The project boundary also defines the scope for internal communication and shared resources. Components within a project
+can communicate freely with each other. This locality principle reduces complexity for
+developers while maintaining security and isolation between different application domains.
+
+## Component
+
+A **Component** represents a deployable unit of software - the fundamental building block of applications in OpenChoreo.
+Each component encapsulates a specific piece of functionality, whether it's a microservice handling business logic, a
+web application serving user interfaces, or a background job processing data.
+
+Components provide the connection between source code and running applications. They define how code is built, what
+resources it requires, and how it should be deployed. This abstraction allows developers to focus on application logic
+while the platform handles the complexities of containerization, orchestration, and lifecycle management.
+
+## Component Types
+
+OpenChoreo provides specialized component types that represent common application patterns, each with its own
+operational characteristics and platform integrations.
+
+### Service
+
+A **Service** component represents backend applications that expose APIs or handle business logic. Services are the
+workhorses of cloud-native applications, processing requests, managing data, and integrating with other systems. The
+platform understands that services need stable network identities, load balancing, and API management capabilities.
+
+Services can expose multiple protocols including HTTP, gRPC, and TCP, with the platform handling the appropriate
+routing and load balancing for each protocol type.
+
+### WebApplication
+
+A **WebApplication** component represents frontend applications that serve user interfaces. These might be single-page
+applications, server-side rendered websites, or static content. The platform recognizes that web applications have
+different operational requirements than backend services and provides appropriate deployment patterns through the
+WebApplicationClass.
+
+### ScheduledTask
+
+A **ScheduledTask** component represents batch jobs, cron jobs, and other time-based workloads. Unlike continuously
+running services, scheduled tasks execute at specific times or intervals, complete their work, and terminate.
+ScheduledTasks are configured with cron expressions to define when they should run, and the platform handles the
+scheduling through the ScheduledTaskClass and Kubernetes CronJob resources.
+
+## Workload
+
+A **Workload** defines the runtime contract of a component - specifying what the component needs to run. The workload
+focuses on application requirements rather than infrastructure details, which are handled by the platform through Classes.
+
+Each component has one workload that describes its runtime needs through several key specifications:
+
+**Containers** define the container images to deploy, along with their commands, arguments, and environment variables.
+This tells the platform what code to run and how to configure it.
+
+**Endpoints** specify the network interfaces that the component exposes - the ports and protocols it listens on. Each
+endpoint declares its type (HTTP, gRPC, TCP, etc.) and port number. These definitions tell the platform what network
+services the component provides, enabling automatic service creation and network policy generation.
+
+**Connections** declare the component's dependencies on other services, whether internal to the platform or external
+third-party services. Each connection specifies how to inject service information into the component through environment
+variables. This enables the platform to manage service discovery, configure network policies, and track dependencies.
+
+This declarative specification can be generated from configuration files in the source repository or applied directly
+to the cluster. The separation between workload (what the application needs) and classes (how the platform provides it)
+enables platform teams to control infrastructure policies while developers focus on application requirements. Resource
+limits, scaling parameters, and operational policies come from the ServiceClass or WebApplicationClass, while the
+workload simply declares what the application needs to function.
+
+## Build
+
+A **Build** represents the process of transforming source code into deployable artifacts. It captures the build
+configuration, tracks build execution, and manages the resulting container images. The build abstraction provides a
+consistent interface for different build strategies while handling the complexities of secure, reproducible builds.
+
+Builds in OpenChoreo are first-class resources that can be monitored, audited, and managed independently of deployments.
+This separation enables practices like building once and deploying many times, pre-building images for faster
+deployments, and maintaining clear traceability from source code to running containers.
+
+The platform supports multiple build strategies to accommodate different technology stacks and organizational
+preferences. Whether using Cloud Native Buildpacks for automatic, opinionated builds or custom Dockerfiles for complete
+control, the build abstraction provides a consistent operational model.
diff --git a/versioned_docs/version-v0.5.x/concepts/platform-abstractions.md b/versioned_docs/version-v0.5.x/concepts/platform-abstractions.md
new file mode 100644
index 0000000..91a658c
--- /dev/null
+++ b/versioned_docs/version-v0.5.x/concepts/platform-abstractions.md
@@ -0,0 +1,142 @@
+---
+title: Platform Abstractions
+description: Platform abstractions for managing infrastructure
+---
+
+# Platform Abstractions
+
+Platform abstractions in OpenChoreo provide the foundational infrastructure layer that platform engineers use to build
+and manage Internal Developer Platforms. These abstractions establish organizational boundaries, manage infrastructure
+resources, and define the operational policies that enable developer self-service while maintaining security and
+compliance.
+
+## Organization
+
+The **Organization** represents the highest level of tenancy in OpenChoreo, serving as the root container for all
+platform resources. It establishes the fundamental isolation boundary between different business units, teams, or
+customers in a multi-tenant platform.
+
+Organizations provide complete resource isolation through dedicated Kubernetes namespaces, ensuring that resources,
+configurations, and workloads from different organizations never interact. This isolation extends beyond simple
+namespace separation to include network policies, RBAC rules, and resource quotas, creating a secure multi-tenant
+environment.
+
+Each organization maintains its own set of platform resources, application resources, and runtime configurations. This
+hierarchical structure enables platform teams to manage multiple independent tenants on the same OpenChoreo
+installation, each with their own governance policies, resource limits, and operational procedures.
+
+## Infrastructure Planes
+
+OpenChoreo separates infrastructure concerns into specialized planes, each serving a distinct purpose in the platform
+architecture. This separation enables independent scaling, security isolation, and operational management of different
+platform functions.
+
+### DataPlane
+
+A **DataPlane** represents a Kubernetes cluster where application workloads run. It abstracts the complexity of cluster
+management, providing a unified interface for deploying applications across multiple clusters regardless of their
+location or underlying infrastructure.
+
+DataPlanes encapsulate all the configuration needed to connect to and manage a Kubernetes cluster, including connection
+credentials, TLS certificates, and cluster-specific settings. They enable platform teams to register multiple clusters -
+whether on-premises, in public clouds, or at edge locations - and manage them through a single control plane.
+
+Each DataPlane can host multiple environments and projects, with OpenChoreo managing the creation of namespaces, network
+policies, and other cluster resources automatically. This abstraction allows platform teams to treat clusters as
+interchangeable infrastructure resources, enabling strategies like geographic distribution, compliance-based placement,
+and disaster recovery.
+
+### BuildPlane
+
+A **BuildPlane** provides dedicated infrastructure for executing continuous integration and build workloads. By
+separating build operations from runtime workloads, BuildPlanes ensure that resource-intensive compilation and testing
+processes don't impact production applications.
+
+BuildPlanes integrate with Argo Workflows to provide a scalable, Kubernetes-native CI/CD execution environment. They
+handle the complete build lifecycle, from source code retrieval through compilation, testing, and container image
+creation. This separation also provides security benefits, isolating potentially untrusted build processes from
+production environments.
+
+Platform engineers configure BuildPlanes with the necessary tools, credentials, and policies for building applications.
+This includes container registry credentials, build tool configurations, and security scanning policies. BuildPlanes can
+be scaled independently based on build demand and can be distributed geographically to reduce latency for development
+teams.
+
+### Observability Plane
+
+The **Observability Plane** provides centralized logging infrastructure for the entire platform. It collects and
+aggregates logs from all other planes - Control, Data, and Build - providing a unified view of platform operations and
+application behavior.
+
+Built on OpenSearch, the Observability Plane offers full-text search capabilities and log retention management. The
+Observer API provides authenticated access to log data, enabling integration with external monitoring tools and
+dashboards. Unlike other planes, the Observability Plane has no custom resources to manage - it operates independently
+after initial setup, receiving log streams from Fluentbit agents deployed across the platform.
+
+Platform engineers configure the Observability Plane once during initial setup, establishing log collection pipelines,
+retention policies, and access controls. This centralized approach ensures that all platform activity is auditable and
+debuggable while maintaining security boundaries between organizations.
+
+## Environment
+
+An **Environment** represents a stage in the software delivery lifecycle, such as development, staging, or production.
+Environments provide the context for deploying and running applications, defining the policies, configurations, and
+constraints that apply to workloads in that stage.
+
+Environments are not just labels or namespaces - they are first-class abstractions that define where applications
+should be deployed (which DataPlane) and serve as targets for deployment pipelines. This abstraction enables platform
+teams to organize different stages of the delivery pipeline.
+
+Each environment represents a distinct deployment target. Development environments might target smaller clusters or
+shared infrastructure, while production environments target dedicated, high-availability clusters. The Environment
+resource primarily defines the mapping to infrastructure (DataPlane) and serves as a reference point for deployments
+and promotion workflows.
+
+## DeploymentPipeline
+
+A **DeploymentPipeline** defines the allowed progression paths for applications moving through environments. It
+represents the organization's software delivery process as a declarative configuration, encoding promotion rules,
+approval requirements, and quality gates.
+
+DeploymentPipelines go beyond simple environment ordering to define complex promotion topologies. They can specify
+parallel paths for different types of releases and conditional progressions based on application characteristics.
+This flexibility allows organizations to implement sophisticated delivery strategies while maintaining governance and
+control.
+
+The pipeline abstraction also serves as an integration point for organizational processes. Manual approval gates can be
+configured for sensitive environments, automated testing can be triggered at promotion boundaries, and compliance checks
+can be enforced before production deployment. This ensures that all applications follow organizational standards
+regardless of which team develops them.
+
+## Class System
+
+OpenChoreo implements the standard Kubernetes Class pattern, similar to GatewayClass or StorageClass, enabling platform
+engineers to define platform-level abstractions that developers consume through their applications.
+
+### The Class Pattern
+
+Classes are platform-level resources that encode organizational standards, best practices, and governance policies.
+Platform engineers create Classes for different workload types - ServiceClass for backend services, WebApplicationClass
+for frontend applications, and ScheduledTaskClass for batch jobs. Each Class defines the platform standards that
+applications must follow when claiming these resources.
+
+Just as GatewayClass defines infrastructure capabilities that Gateway resources consume, or StorageClass defines how
+storage should be provisioned when a PersistentVolumeClaim is created, ServiceClass defines how services should be
+deployed when developers create Service resources. This pattern provides a clean separation between platform
+capabilities (defined by platform engineers) and application requirements (expressed by developers).
+
+### Class Consumption
+
+When developers create application resources like Service or WebApplication, they reference the appropriate Class,
+similar to how a PersistentVolumeClaim references a StorageClass. The platform uses the Class definition to provision
+the actual workload with the correct configuration, policies, and governance rules.
+
+Environment-specific Bindings act as the instantiation of this claim in a specific environment. While the Service
+resource expresses the developer's intent and references a ServiceClass, the ServiceBinding represents the actual
+deployment of that service in a particular environment with environment-specific overrides.
+
+This consumption model balances standardization with flexibility. Platform teams maintain control over critical
+configurations through Classes while developers express their requirements through simple resource definitions. The
+platform handles the complex mapping between developer intent and infrastructure reality.
+
+
diff --git a/versioned_docs/version-v0.5.x/concepts/resource-relationships.md b/versioned_docs/version-v0.5.x/concepts/resource-relationships.md
new file mode 100644
index 0000000..2d8d93f
--- /dev/null
+++ b/versioned_docs/version-v0.5.x/concepts/resource-relationships.md
@@ -0,0 +1,169 @@
+---
+title: Resource Relationships
+description: How resources connect and interact within the platform
+---
+
+# Resource Relationships
+
+OpenChoreo's resources form a carefully designed hierarchy that balances flexibility with governance. Understanding how
+these resources relate to each other is essential for designing applications, troubleshooting issues, and managing the
+platform effectively. These relationships define ownership, inheritance, and dependencies throughout the system.
+
+## Ownership Hierarchy
+
+The ownership model in OpenChoreo follows a strict hierarchical structure where each resource has a clear parent and
+defined scope. This hierarchy provides namespace isolation, access control boundaries, and lifecycle management.
+
+### Organization as Root
+
+At the top of the hierarchy, the **Organization** serves as the root container for all resources. Every resource in
+OpenChoreo ultimately belongs to an organization, establishing the fundamental tenant boundary in multi-tenant
+deployments. Organizations own platform resources like DataPlanes and Environments, application resources like Projects
+and Components, and runtime resources generated by the platform.
+
+This ownership model ensures complete isolation between different organizations. Resources from one organization cannot
+reference or interact with resources from another organization. This isolation extends to the runtime level, where
+different organizations' workloads run in separate namespaces with distinct security boundaries.
+
+### Project Ownership
+
+Within an organization, **Projects** form the next level of ownership for application resources. Projects own
+Components, establishing team boundaries and application domains. This ownership relationship means that components
+cannot exist without a parent project, and deleting a project removes all its components.
+
+The project ownership boundary also defines the scope for internal communication. Components within the same project
+can reference each other directly and communicate without crossing security boundaries. This locality enables teams to
+work efficiently within their domain while maintaining isolation from other projects.
+
+### Component and Runtime Resources
+
+**Components** own the runtime resources that result from their deployment. When a component deploys, it generates
+Builds and produces Releases. These resources maintain a clear ownership chain back to the component, enabling
+lifecycle management and garbage collection.
+
+This ownership relationship ensures that runtime resources are properly cleaned up when components are removed. It also
+provides clear attribution for resource usage, cost allocation, and audit trails. Platform operators can trace any
+running workload back to its originating component and project.
+
+## Class and Binding Relationships
+
+OpenChoreo implements the Kubernetes Class pattern that enables platform standardization while allowing
+application-specific customization. This system separates platform governance from developer flexibility through
+multiple layers of configuration.
+
+### Platform Classes
+
+**Classes** define platform-level abstractions that establish organizational standards. ServiceClass,
+WebApplicationClass, and ScheduledTaskClass provide platform capabilities for different workload types. These classes
+are created by platform engineers and encode organizational policies, security requirements, and operational best
+practices.
+
+Classes serve as the platform's contract for how applications should be deployed. They define standard resource limits,
+security policies, network configurations, and operational parameters. By centralizing these definitions in classes,
+platform teams ensure consistency across all applications while maintaining a single point of control for platform-wide
+changes.
+
+### Binding Instantiation
+
+**Bindings** create concrete instances of classes for specific environments. A ServiceBinding references a ServiceClass
+but can override certain parameters for its target environment. This relationship allows the same class to be used
+across different environments with appropriate customization.
+
+The binding relationship is not just a simple override mechanism. Bindings can only modify parameters that the class
+explicitly allows, ensuring that security policies and governance rules cannot be circumvented. This controlled
+flexibility enables environment-specific optimization while maintaining platform standards.
+
+
+### Component to Build
+
+Components define build specifications that result in **Build** resources. This relationship captures how source code
+should be transformed into container images. The component maintains the build configuration while builds represent
+individual execution instances.
+
+Each build maintains a relationship back to its originating component and the specific commit or tag that triggered it.
+This relationship provides complete traceability from running containers back to source code, essential for debugging
+and compliance.
+
+### Workload and Binding Creation
+
+When developers create a Service, WebApplication, or ScheduledTask (the claim), along with a Workload specification,
+the platform creates the appropriate Binding. The Binding combines:
+- The claim (Service/WebApplication/ScheduledTask) that references a Class
+- The Workload that defines the runtime requirements
+- The Environment where it should be deployed
+
+This relationship ensures that the platform standards from the Class are applied while respecting the application's
+runtime requirements from the Workload.
+
+### Binding to Release
+
+Bindings generate Releases that contain the actual Kubernetes resources to be deployed. The Release combines the Class
+configuration, Workload specifications, and environment-specific settings into concrete Kubernetes manifests that are
+applied to the target DataPlane.
+
+This relationship chain from Component β Build β Claim+Workload β Binding β Release ensures complete traceability
+and proper lifecycle management throughout the application delivery process.
+
+## Network Relationships
+
+Network relationships in OpenChoreo define how components communicate and expose functionality. These relationships
+translate into concrete network policies, routing rules, and security configurations.
+
+### Endpoint Exposure
+
+**Endpoints** establish relationships between components and their network interfaces. A component can expose multiple
+endpoints with different visibility scopes and protocols. These relationships define how the component can be accessed
+and by whom.
+
+The endpoint relationship includes more than just network configuration. It establishes contracts about protocols,
+expected behavior, and API compatibility. Other components can depend on these contracts, with the platform ensuring
+that communication follows the declared patterns.
+
+### Connection Dependencies
+
+**Connections** create explicit relationships between components and their dependencies. When a component declares a
+connection to another service, it establishes a formal dependency that the platform can track, secure, and monitor.
+
+Connection relationships make dependencies between components explicit. This relationship model helps teams understand
+their application architecture and service dependencies.
+
+
+## Environment Progression
+
+Environment relationships define how applications move through the delivery pipeline from development to production.
+These relationships ensure consistent progression while maintaining appropriate governance.
+
+### Pipeline Definition
+
+**DeploymentPipelines** establish relationships between environments, defining allowed transitions and promotion rules.
+These relationships create a directed graph of environment progression, potentially with multiple paths for different
+scenarios.
+
+Pipeline relationships include more than just ordering. They define approval requirements and testing gates. These
+relationships ensure that applications follow organizational processes while enabling automation where appropriate.
+
+
+
+## Lifecycle Dependencies
+
+Resource relationships in OpenChoreo include lifecycle dependencies that ensure proper initialization, updates, and
+cleanup.
+
+### Creation Order
+
+Some resources must be created before others can exist. DataPlanes must be registered before environments can target
+them. Projects must exist before components can be created within them. These relationships ensure that the platform
+maintains consistency during resource creation.
+
+### Update Propagation
+
+When resources are updated, changes propagate through relationships to dependent resources. Updating a class triggers
+reconciliation of all bindings that reference it. These relationships ensure that changes are consistently applied
+throughout the system.
+
+### Deletion Cascades
+
+Resource relationships define deletion behavior. When a project is deleted, all its components are removed. When a
+component is deleted, its builds and deployments are cleaned up. These cascading relationships ensure that resources are
+properly cleaned up without leaving orphaned objects.
+
diff --git a/versioned_docs/version-v0.5.x/concepts/runtime-model.md b/versioned_docs/version-v0.5.x/concepts/runtime-model.md
new file mode 100644
index 0000000..023e8f1
--- /dev/null
+++ b/versioned_docs/version-v0.5.x/concepts/runtime-model.md
@@ -0,0 +1,120 @@
+---
+title: Runtime Model
+description: Runtime execution and deployment model
+---
+
+# Runtime Model
+
+The runtime model describes how OpenChoreo's abstractions transform into running systems. When developers declare
+projects and components, the platform orchestrates a sophisticated runtime environment that provides isolation,
+security, and observability. Understanding this transformation from declaration to execution helps teams design better
+applications and troubleshoot issues effectively.
+
+## Cell Architecture
+
+At runtime, each **Project** transforms into a **Cell** - a secure, isolated runtime boundary that encapsulates all
+components of an application domain. This transformation represents a fundamental principle of OpenChoreo:
+organizational boundaries in code become physical boundaries in infrastructure.
+
+Cells provide complete isolation between different application domains. Each cell operates as an independent unit with
+its own namespace, network policies, and security boundaries. Components within a cell can communicate freely using
+cluster-local networking, but all communication across cell boundaries must flow through well-defined gateways. This
+architecture ensures that failures, security breaches, or performance issues in one cell cannot directly impact others.
+
+The cell model aligns with microservices best practices and Domain-Driven Design principles. By mapping bounded contexts
+to isolated runtime units, OpenChoreo ensures that architectural boundaries are enforced by infrastructure. This
+alignment reduces the cognitive load on developers - the same mental model used for designing applications applies to
+their runtime behavior.
+
+## Traffic Flow Patterns
+
+OpenChoreo implements a structured approach to network traffic through directional gateways, each serving a specific
+purpose in the overall communication architecture. These patterns provide clarity about how data flows through the
+system while enabling sophisticated security and routing policies.
+
+### Northbound Ingress
+
+Northbound ingress handles traffic entering cells from the public internet. This gateway serves as the entry point for
+external users, customers, and third-party integrations accessing public APIs and web applications. The platform
+automatically configures load balancing and TLS termination at this boundary.
+
+The northbound gateway translates friendly DNS names into internal service endpoints, handles HTTP routing based on
+hostnames and paths, and enforces public-facing API policies. This abstraction means developers can focus on application
+logic while the platform manages the complexities of internet-facing services.
+
+### Southbound Egress
+
+Southbound egress manages traffic leaving cells to reach external services on the internet. This gateway provides
+controlled access to third-party APIs, cloud services, and external databases. By channeling all outbound traffic
+through a managed gateway, the platform can enforce security policies, manage credentials, and provide observability for
+external dependencies.
+
+The southbound gateway enables capabilities like egress filtering to prevent data exfiltration, credential injection for
+authenticated external services, and circuit breaking for unreliable external dependencies. This controlled approach to
+external communication reduces security risks while improving reliability.
+
+### Westbound Ingress
+
+Westbound ingress handles traffic from other parts of the organization entering the cell. This gateway manages internal
+API consumption, service-to-service communication across projects, and administrative access. Unlike public northbound
+traffic, westbound traffic comes from trusted sources within the organization but still requires authentication and
+authorization.
+
+The westbound gateway enables internal service discovery, allowing components in other cells to locate and communicate
+with services using logical names. It enforces organization-wide policies while allowing more permissive communication
+than public interfaces. This balance enables productive development while maintaining security boundaries.
+
+### Eastbound Egress
+
+Eastbound egress manages traffic leaving the cell to reach other cells or internal services within the organization.
+This gateway handles inter-project dependencies, shared service consumption, and platform service integration. By
+managing internal outbound traffic, the platform can track dependencies, enforce quotas, and provide circuit breaking
+between internal services.
+
+The eastbound gateway makes internal service dependencies explicit and observable. Teams can understand which other
+projects they depend on, platform engineers can track usage patterns across the organization, and the system can prevent
+cascading failures through circuit breaking and retry policies.
+
+## Network Security
+
+OpenChoreo manages network security through the cell architecture and gateway pattern. Communication within a cell is
+allowed between components of the same project, while all cross-cell communication must flow through the defined
+gateways. This provides security boundaries between different application domains.
+
+The platform uses Cilium for network policy enforcement and Envoy Gateway for ingress traffic management. Developers
+declare their components' endpoints and connections in the workload specification, and the platform handles the
+underlying network configuration.
+
+## Workload Execution
+
+When components deploy to a runtime environment, OpenChoreo orchestrates a complex series of transformations. The
+abstract component definition combines with workload specifications, environment configurations, and platform policies
+to produce concrete Kubernetes resources.
+
+The platform manages the complete lifecycle of these resources. It creates deployments with appropriate resource limits
+and scaling parameters, configures services for network access and load balancing, injects configuration and secrets
+from secure stores, and establishes health checks and readiness probes. This orchestration happens transparently -
+developers see their components running while the platform manages the underlying complexity.
+
+Workload execution is environment-aware. The same component might run with different resource allocations, replica
+counts, or configuration values in different environments. The platform manages these variations through the binding
+system, where environment-specific bindings override default values from classes and workload specifications.
+
+## Service Discovery and Load Balancing
+
+Service discovery uses standard Kubernetes DNS, allowing services to communicate using service names. Within a cell,
+components can discover each other using simple service names. Across cells, services require routing through the
+appropriate gateways.
+
+## Observability
+
+The runtime model includes centralized logging through the Observability Plane. Logs from all containers flow through
+the platform's collection pipeline using Fluentbit, enriched with metadata about the source component, project, and
+environment. This enrichment enables queries across the entire platform while maintaining clear attribution of log
+entries to their sources.
+
+The Observer API provides access to these logs, allowing developers to search and analyze application behavior across
+environments. This centralized logging approach ensures that debugging information is always available without requiring
+additional configuration from developers.
+
+
diff --git a/versioned_docs/version-v0.5.x/getting-started/deploy-first-component.mdx b/versioned_docs/version-v0.5.x/getting-started/deploy-first-component.mdx
new file mode 100644
index 0000000..74db468
--- /dev/null
+++ b/versioned_docs/version-v0.5.x/getting-started/deploy-first-component.mdx
@@ -0,0 +1,132 @@
+---
+title: Deploy Your First Component
+---
+
+import CodeBlock from '@theme/CodeBlock';
+import {versions} from '../_constants.mdx';
+
+# Deploy Your First Component
+
+This guide walks you through deploying your first component on OpenChoreo. By the end of this tutorial, you'll have a running web service accessible through the platform, complete with monitoring and security configured automatically.
+
+## Prerequisites
+
+Before you begin, ensure you have:
+
+- **OpenChoreo installed** in your Kubernetes cluster ([Single Cluster Setup](single-cluster.mdx))
+- **kubectl** configured to access your cluster
+- **OpenChoreo context** set to your cluster (should be `k3d-openchoreo` if following the setup guide)
+
+## Step 1: Verify Your Setup
+
+First, make sure you have setup choreo on your local cluster following the [guide](single-cluster.mdx)
+
+You should see all OpenChoreo components running with the control plane and data plane pods in `Running` status.
+
+## Step 2: Deploy the Go Greeter Service
+
+For this tutorial, we'll use the Go Greeter Service sample that comes with OpenChoreo. This is a simple web service that demonstrates OpenChoreo's core capabilities.
+
+
+{`# Deploy the greeter service
+kubectl apply -f https://raw.githubusercontent.com/openchoreo/openchoreo/${versions.githubRef}/samples/from-image/go-greeter-service/greeter-service.yaml`}
+
+
+This single command creates:
+- **Component**: Defines the application and its requirements (references the `deployment/service` ComponentType)
+- **Workload**: Specifies the container image and runtime configuration
+- **ComponentDeployment**: Deploys the component to the development environment
+- **SecretReference**: Manages external secrets for the component
+
+## Step 3: Monitor the Deployment
+
+Track your component's deployment progress:
+
+```bash
+# Check that all resources are created
+kubectl get component,workload,componentdeployment -A
+
+# Check the component status
+kubectl get component greeter-service
+
+# Monitor the component deployment
+kubectl get componentdeployment greeter-service-development
+```
+
+## Step 4: Verify the Deployment
+
+Wait for the service to be ready (this may take 1-2 minutes):
+
+```bash
+# Check the actual Kubernetes deployment
+kubectl get deployment -A | grep greeter
+
+# Verify pods are running
+kubectl get pods -A | grep greeter
+
+# Check HTTP routes are configured
+kubectl get httproute -A -o wide
+```
+
+## Step 5: Test Your Application
+
+Test the greeter service using curl:
+
+```bash
+# Test the greeter service endpoint
+curl http://development.openchoreoapis.localhost:9080/greeter-service/greeter/greet
+```
+
+You should receive a successful response:
+```text
+Hello, Stranger!
+```
+
+This confirms that:
+- Your component is deployed and running
+- The API gateway is properly configured
+- Network routing is working correctly
+- Security policies are applied automatically
+
+## Step 6: Explore What OpenChoreo Created
+
+Let's examine what OpenChoreo automatically created for your component:
+
+```bash
+# View the OpenChoreo resources
+kubectl get component,workload,componentdeployment -n default
+
+# Check the underlying Kubernetes resources
+kubectl get deployment,pod,svc -A | grep greeter
+
+# View the HTTP routing configuration
+kubectl describe httproute -A | grep -A 20 greeter
+```
+
+OpenChoreo automatically created:
+- **Component** - High-level application definition (using the `deployment/service` ComponentType)
+- **Workload** - Container deployment specification
+- **ComponentDeployment** - Environment-specific deployment configuration
+- **Deployment** - Kubernetes deployment managing pods
+- **Service** - Kubernetes service for networking
+- **HTTPRoute** - Gateway API routing configuration
+- **Secret** - External secrets synchronized from the secret store
+
+## Summary
+
+You've successfully:
+- Deployed your first OpenChoreo component from a container image
+- Tested API access through the OpenChoreo gateway
+- Explored the resources OpenChoreo created automatically
+
+Your application is now running in a production-ready environment with enterprise-grade security, networking, and observabilityβall configured automatically by OpenChoreo!
+
+**Ready for more?** Try deploying additional samples or start building your own components using OpenChoreo's powerful abstractions.
+
+## Clean Up
+
+To remove the sample application:
+
+
+{`kubectl delete -f https://raw.githubusercontent.com/openchoreo/openchoreo/${versions.githubRef}/samples/from-image/go-greeter-service/greeter-service.yaml`}
+
diff --git a/versioned_docs/version-v0.5.x/getting-started/multi-cluster.mdx b/versioned_docs/version-v0.5.x/getting-started/multi-cluster.mdx
new file mode 100644
index 0000000..95ea6ea
--- /dev/null
+++ b/versioned_docs/version-v0.5.x/getting-started/multi-cluster.mdx
@@ -0,0 +1,370 @@
+---
+title: Multi Cluster
+description: Deploy OpenChoreo across multiple Kubernetes clusters for production-like environments. Step-by-step guide for setting up control plane, data plane, build plane, and observability plane in separate clusters using k3d.
+---
+
+import CodeBlock from '@theme/CodeBlock';
+import Link from '@docusaurus/Link';
+import {versions} from '../_constants.mdx';
+
+# Multi Cluster Setup
+
+This guide walks you through step-by-step instructions for deploying OpenChoreo across multiple k3d clusters. This deploys a **Control Plane**, a **Data Plane**, and optional **Build** and **Observability Planes** in separate clusters for better isolation and to mimic production architecture.
+
+## Prerequisites
+
+- **Docker** β Just have it installed on your machine, and you're good to go.
+ - We recommend using [Docker Engine version 26.0+](https://docs.docker.com/engine/release-notes/26.0/).
+ - Allocate at least **8 GB RAM** and **4 CPU** cores to Docker (or the VM running Docker).
+- **[k3d](https://k3d.io/stable/#installation)** v5.8+ installed
+- **[kubectl](https://kubernetes.io/docs/tasks/tools/)** v1.32+ installed
+- **[Helm](https://helm.sh/docs/intro/install/)** v3.12+ installed
+
+### Verify Prerequisites
+
+Before proceeding, verify that all tools are installed and meet the minimum version requirements:
+
+```bash
+# Check Docker (should be v20.10+)
+docker --version
+
+# Check k3d (should be v5.8+)
+k3d --version
+
+# Check kubectl (should be v1.32+)
+kubectl version --client
+
+# Check Helm (should be v3.12+)
+helm version --short
+```
+
+Make sure Docker is running:
+
+```bash
+docker info
+```
+
+:::note
+If you're using **Colima**, set the `K3D_FIX_DNS=0` environment variable when creating clusters to avoid DNS issues. See [k3d-io/k3d#1449](https://github.com/k3d-io/k3d/issues/1449) for more details.
+:::
+
+## Quick Setup
+
+This multi-cluster setup deploys OpenChoreo components across separate clusters for better isolation and scalability:
+
+- **Control Plane Cluster**: Hosts the OpenChoreo API server and controllers
+- **Data Plane Cluster**: Hosts application workloads and runtime components
+- **Build Plane Cluster** (Optional): Hosts CI/CD capabilities using Argo Workflows
+- **Observability Plane Cluster** (Optional): Hosts monitoring and logging infrastructure
+
+### 1. Setup the Control Plane
+
+#### Create the Control Plane Cluster
+
+Create a dedicated k3d cluster for the control plane components:
+
+
+ {`curl -s https://raw.githubusercontent.com/openchoreo/openchoreo/${versions.githubRef}/install/k3d/multi-cluster/config-cp.yaml | k3d cluster create --config=-`}
+
+
+This will:
+- Create a cluster named "openchoreo-cp"
+- Set up control plane with k3d
+- Configure port mappings: `localhost:8080` (HTTP), `localhost:8443` (HTTPS)
+- Expose Kubernetes API on port `6550`
+- Set kubectl context to "k3d-openchoreo-cp"
+
+#### Install OpenChoreo Control Plane
+
+Install the OpenChoreo control plane using Helm. This will create the `openchoreo-control-plane` namespace automatically:
+
+
+ {`helm install openchoreo-control-plane oci://ghcr.io/openchoreo/helm-charts/openchoreo-control-plane \\
+ --version ${versions.helmChart} \\
+ --kube-context k3d-openchoreo-cp \\
+ --namespace openchoreo-control-plane \\
+ --create-namespace \\
+ --values https://raw.githubusercontent.com/openchoreo/openchoreo/${versions.githubRef}/install/k3d/multi-cluster/values-cp.yaml`}
+
+
+Wait for the installation to complete and verify all pods are running:
+
+```bash
+kubectl get pods -n openchoreo-control-plane --context k3d-openchoreo-cp
+```
+
+You should see pods for:
+- `controller-manager` (Running)
+- `cert-manager-*` (3 pods, all Running)
+
+### 2. Setup the Data Plane
+
+#### Create the Data Plane Cluster
+
+Create a dedicated k3d cluster for the data plane components:
+
+
+ {`curl -s https://raw.githubusercontent.com/openchoreo/openchoreo/${versions.githubRef}/install/k3d/multi-cluster/config-dp.yaml | k3d cluster create --config=-`}
+
+
+This will:
+- Create a cluster named "openchoreo-dp"
+- Set up data plane with k3d
+- Configure port mappings: `localhost:9080` (HTTP), `localhost:9443` (HTTPS) - for deployed workloads
+- Expose Kubernetes API on port `6551`
+- Set kubectl context to "k3d-openchoreo-dp"
+
+#### Install OpenChoreo Data Plane
+
+Install the OpenChoreo data plane using Helm. This will create the `openchoreo-data-plane` namespace automatically:
+
+
+ {`helm install openchoreo-data-plane oci://ghcr.io/openchoreo/helm-charts/openchoreo-data-plane \\
+ --version ${versions.helmChart} \\
+ --kube-context k3d-openchoreo-dp \\
+ --namespace openchoreo-data-plane \\
+ --create-namespace \\
+ --values https://raw.githubusercontent.com/openchoreo/openchoreo/${versions.githubRef}/install/k3d/multi-cluster/values-dp.yaml`}
+
+
+Wait for dataplane components to be ready:
+
+```bash
+kubectl get pods -n openchoreo-data-plane --context=k3d-openchoreo-dp
+```
+
+You should see pods for:
+- `envoy-gateway-*` (Running)
+- `external-secrets-*` (3 pods, all Running)
+- `fluent-bit-*` (Running on each node)
+- `gateway-external-*` (Running)
+
+#### Configure DataPlane
+
+Register the data plane with the control plane by running:
+
+
+ {`curl -s https://raw.githubusercontent.com/openchoreo/openchoreo/${versions.githubRef}/install/add-data-plane.sh | bash -s -- \\
+ --control-plane-context k3d-openchoreo-cp \\
+ --target-context k3d-openchoreo-dp \\
+ --server https://host.k3d.internal:6551`}
+
+
+This script creates a DataPlane resource in the default namespace of the control plane cluster.
+
+Verify the DataPlane was created:
+
+```bash
+kubectl get dataplane -n default --context k3d-openchoreo-cp
+```
+
+### 3. Setup the Build Plane (Optional)
+
+The Build Plane is required if you plan to use OpenChoreo's internal CI capabilities. If you're only deploying pre-built container images, you can skip this step.
+
+#### Create the Build Plane Cluster
+
+Create a dedicated k3d cluster for the build plane components:
+
+
+ {`curl -s https://raw.githubusercontent.com/openchoreo/openchoreo/${versions.githubRef}/install/k3d/multi-cluster/config-bp.yaml | k3d cluster create --config=-`}
+
+
+This will:
+- Create a cluster named "openchoreo-bp"
+- Set up build plane with k3d
+- Configure port mappings: `localhost:10081` (Argo Workflows UI), `localhost:10082` (Container Registry)
+- Expose Kubernetes API on port `6552`
+- Set kubectl context to "k3d-openchoreo-bp"
+
+#### Install OpenChoreo Build Plane
+
+Install the OpenChoreo build plane using Helm for CI/CD capabilities. This will create the `openchoreo-build-plane` namespace automatically:
+
+
+ {`helm install openchoreo-build-plane oci://ghcr.io/openchoreo/helm-charts/openchoreo-build-plane \\
+ --version ${versions.helmChart} \\
+ --kube-context k3d-openchoreo-bp \\
+ --namespace openchoreo-build-plane \\
+ --create-namespace \\
+ --values https://raw.githubusercontent.com/openchoreo/openchoreo/${versions.githubRef}/install/k3d/multi-cluster/values-bp.yaml`}
+
+
+Wait for the build plane components to be ready:
+
+```bash
+kubectl get pods -n openchoreo-build-plane --context k3d-openchoreo-bp
+```
+
+You should see pods for:
+- `argo-server-*` (Running)
+- `argo-workflow-controller-*` (Running)
+- `registry-*` (Running)
+
+#### Configure BuildPlane
+
+Register the build plane with the control plane by running:
+
+
+ {`curl -s https://raw.githubusercontent.com/openchoreo/openchoreo/${versions.githubRef}/install/add-build-plane.sh | bash -s -- \\
+ --control-plane-context k3d-openchoreo-cp \\
+ --target-context k3d-openchoreo-bp \\
+ --server https://host.k3d.internal:6552`}
+
+
+This script creates a BuildPlane resource in the default namespace of the control plane cluster.
+
+Verify that the BuildPlane was created:
+
+```bash
+kubectl get buildplane -n default --context k3d-openchoreo-cp
+```
+
+### 4. Setup the Observability Plane (Optional)
+
+Install the OpenChoreo observability plane for monitoring and logging capabilities across all clusters.
+
+#### Create the Observability Plane Cluster
+
+Create a dedicated k3d cluster for the observability plane components:
+
+
+ {`curl -s https://raw.githubusercontent.com/openchoreo/openchoreo/${versions.githubRef}/install/k3d/multi-cluster/config-op.yaml | k3d cluster create --config=-`}
+
+
+This will:
+- Create a cluster named "openchoreo-op"
+- Set up observability plane with k3d
+- Configure port mappings: `localhost:11081` (OpenSearch Dashboard), `localhost:11082` (OpenSearch API)
+- Expose Kubernetes API on port `6553`
+- Set kubectl context to "k3d-openchoreo-op"
+
+#### Install OpenChoreo Observability Plane
+
+Install the OpenChoreo observability plane using Helm. This will create the `openchoreo-observability-plane` namespace automatically:
+
+
+ {`helm install openchoreo-observability-plane oci://ghcr.io/openchoreo/helm-charts/openchoreo-observability-plane \\
+ --version ${versions.helmChart} \\
+ --kube-context k3d-openchoreo-op \\
+ --namespace openchoreo-observability-plane \\
+ --create-namespace \\
+ --values https://raw.githubusercontent.com/openchoreo/openchoreo/${versions.githubRef}/install/k3d/multi-cluster/values-op.yaml`}
+
+
+Wait for the observability plane components to be ready:
+
+```bash
+kubectl get pods -n openchoreo-observability-plane --context k3d-openchoreo-op
+```
+
+You should see pods for:
+- `observer-*` (Running) - Log processing service
+- `opensearch-master-0` (Running) - Log storage backend
+- `opensearch-dashboards-*` (Running) - Visualization dashboard
+- `opensearch-cluster-setup-*` (Completed) - One-time setup job
+
+:::note
+The OpenSearch dashboard pod may take several minutes to start.
+:::
+
+Verify that all pods are ready:
+
+```bash
+kubectl wait --for=condition=Ready pod --all -n openchoreo-observability-plane --timeout=600s --context k3d-openchoreo-op
+```
+
+Verify FluentBit is sending logs to OpenSearch:
+
+```bash
+# Check if kubernetes indices are being created
+kubectl exec -n openchoreo-observability-plane opensearch-master-0 --context k3d-openchoreo-op -- curl -s "http://localhost:9200/_cat/indices?v" | grep kubernetes
+
+# Check recent log count
+kubectl exec -n openchoreo-observability-plane opensearch-master-0 --context k3d-openchoreo-op -- curl -s "http://localhost:9200/kubernetes-*/_count" | jq '.count'
+```
+
+If the indices exist and the count is greater than 0, FluentBit is successfully collecting and storing logs.
+
+## Verification
+
+### Check that default OpenChoreo resources were created:
+
+```bash
+# Check default organization and project (on control plane)
+kubectl get organizations,projects,environments -A --context k3d-openchoreo-cp
+
+# Check default component types (on control plane)
+kubectl get componenttypes -n default --context k3d-openchoreo-cp
+
+# Check all OpenChoreo CRDs (on control plane)
+kubectl get crds --context k3d-openchoreo-cp | grep openchoreo
+
+# Check gateway resources (on data plane)
+kubectl get gateway,httproute -n openchoreo-data-plane --context k3d-openchoreo-dp
+```
+
+#### Check that all components are running:
+
+```bash
+# Check control plane cluster
+kubectl cluster-info --context k3d-openchoreo-cp
+kubectl get pods -n openchoreo-control-plane --context k3d-openchoreo-cp
+
+# Check data plane cluster
+kubectl cluster-info --context k3d-openchoreo-dp
+kubectl get pods -n openchoreo-data-plane --context k3d-openchoreo-dp
+kubectl get nodes --context k3d-openchoreo-dp
+
+# Check build plane cluster (if installed)
+kubectl cluster-info --context k3d-openchoreo-bp
+kubectl get pods -n openchoreo-build-plane --context k3d-openchoreo-bp
+
+# Check observability plane cluster (if installed)
+kubectl cluster-info --context k3d-openchoreo-op
+kubectl get pods -n openchoreo-observability-plane --context k3d-openchoreo-op
+```
+
+## Troubleshooting
+
+### Cluster Creation Issues
+
+If you encounter issues creating k3d clusters:
+
+- Ensure you have sufficient CPU and memory allocated to Docker (or the VM running Docker). We recommend at least **8 GB RAM** and **4 CPU** cores.
+- If using Colima, make sure to set `K3D_FIX_DNS=0` environment variable when creating clusters.
+- Check Docker is running: `docker info`
+
+If k3d cluster creation gets stuck or hangs, you may need to increase inotify limits in your VM:
+
+```bash
+# For Colima users
+colima ssh
+sudo sysctl -w fs.inotify.max_user_watches=524288
+sudo sysctl -w fs.inotify.max_user_instances=512
+exit
+
+# Then retry creating the cluster
+```
+
+
+## Next Steps
+
+After completing this multi-cluster setup you can:
+
+1. [Deploy your first component](./deploy-first-component.mdx) to get started with OpenChoreo
+2. Test the GCP microservices demo to see multi-component applications in action across clusters
+3. Deploy additional sample applications from the OpenChoreo samples
+4. Experiment with cross-cluster deployments and observe how components interact across the distributed platform
+
+## Cleaning Up
+
+To completely remove the multi-cluster installation:
+
+```bash
+# Delete all k3d clusters
+k3d cluster delete openchoreo-cp
+k3d cluster delete openchoreo-dp
+k3d cluster delete openchoreo-bp # if installed
+k3d cluster delete openchoreo-op # if installed
+```
diff --git a/versioned_docs/version-v0.5.x/getting-started/qsg-install-status-success.png b/versioned_docs/version-v0.5.x/getting-started/qsg-install-status-success.png
new file mode 100644
index 0000000..86d0fbf
Binary files /dev/null and b/versioned_docs/version-v0.5.x/getting-started/qsg-install-status-success.png differ
diff --git a/versioned_docs/version-v0.5.x/getting-started/quick-start-guide.mdx b/versioned_docs/version-v0.5.x/getting-started/quick-start-guide.mdx
new file mode 100644
index 0000000..3ad705d
--- /dev/null
+++ b/versioned_docs/version-v0.5.x/getting-started/quick-start-guide.mdx
@@ -0,0 +1,259 @@
+---
+title: Quick Start Guide
+description: Try OpenChoreo with just Docker. Quick setup using a pre-configured container to create a local Kubernetes cluster with OpenChoreo and deploy a sample web application.
+---
+
+
+
+import CodeBlock from '@theme/CodeBlock';
+import Link from '@docusaurus/Link';
+import {versions} from '../_constants.mdx';
+
+# Quick Start Guide
+
+Follow this guide to quickly set up OpenChoreo in a local environment with Docker.
+
+The setup uses a preconfigured Dev Container that includes all required dependencies for installation and cleanup.
+
+
+
βοΈ Prerequisites
+
+ Ensure the following before you begin:
+
+ - **Docker** (Engine [26.0+](https://docs.docker.com/engine/release-notes/26.0/) recommended)
+ - Allocate at least **4 GB RAM** and **2 CPUs**.
+ - If you plan to install with BuildPlane, allocate **8 GB RAM** and **4 CPUs** for optimal performance.
+ - **5β10** minutes of setup time
+
+ :::note
+ If you encounter issues with Docker alternatives (Docker Desktop, Rancher Desktop, etc.), report them via
+ [GitHub](https://github.com/openchoreo/openchoreo/issues).
+ :::
+
+
+
+
+
1
+
Start the Dev Container
+
+ Run the following command to start the dev container and open a terminal session within it:
+
+
+ {String.raw`docker run --rm -it --name openchoreo-quick-start \
+ --pull always \
+ -v /var/run/docker.sock:/var/run/docker.sock \
+ --network=host \
+ ghcr.io/openchoreo/quick-start:`}{versions.dockerTag}
+
+
+
+
+
+
2
+
Install OpenChoreo
+
+
+ Inside the container, run the installation command:
+
+
+ {`./install.sh --version ${versions.helmChart}`}
+
+
+ This command performs the following:
+
+ - Creates a local [k3d](https://k3d.io/) (k3s-in-Docker) cluster
+ - Installs OpenChoreo and its dependencies using Helm charts.
+
+ :::tip
+ The installation script is idempotent. You can rerun it safely if the process is interrupted.
+ :::
+
+ When installation completes successfully, you see a summary of component statuses:
+
+
+
+ :::tip
+ If any components remain in the `pending` state, wait a few minutes and run the following command to check their
+ status:
+
+ ```bash
+ ./check-status.sh
+ ```
+ :::
+
+
+
+
+
3
+
Deploy a Sample Web Application
+
+
+ After setting up OpenChoreo in your Docker environment, deploy a sample web application by running:
+
+ ```bash
+ ./deploy-react-starter.sh
+ ```
+
+ When deployment completes, the output includes a message with the application URL:
+
+ ```text
+ [SUCCESS] React Starter web application is ready!
+ π Access the application at: http://react-starter-development.openchoreoapis.localhost:9080
+ Open this URL in your browser to see the React starter application.
+
+ [INFO] To clean up and delete this application, run:
+ [INFO] ./deploy-react-starter.sh --clean
+ ```
+
+
+
+
+ ### Understanding the Setup
+
+ Running the installation and deployment commands initializes OpenChoreo locally and deploys a sample web
+ application.
+ The following sections describe what occurs behind the scenes.
+
+ #### 1. The Install Command
+
+ The installation process:
+
+ - Initializes a Dev Container with all required tools.
+ - Creates a k3d (k3s-in-Docker) cluster in Docker.
+ - Installs the OpenChoreo IDP and dependencies using Helm charts.
+
+ #### Foundation Resources Created
+
+ The installation automatically provisions the following OpenChoreo abstractions:
+
+ - Organization
+ - Data Plane
+ - Build Plane
+ - Environments (e.g., Development, Staging, Production)
+ - Deployment Pipeline
+ - Project
+ - Component Types (e.g., service, web-application, scheduled-task)
+
+ View these resources using the following commands:
+
+ ```bash
+ kubectl get organizations
+ kubectl get dataplanes
+ kubectl get environments
+ kubectl get projects
+ kubectl get componenttypes
+ ```
+
+ View details for a specific resource:
+
+ ```bash
+ kubectl get project default -oyaml
+ ```
+
+ #### 2. Deploy Command
+
+ The deployment script creates:
+
+ - A sample Web Application Component
+ - The corresponding Deployment resource
+
+ List deployed components:
+
+ ```bash
+ kubectl get components
+ ```
+
+ :::tip
+ Explore more examples in the Samples directory or in
+ `/samples` inside the Dev Container.
+ :::
+
+ :::important
+ When running samples in the Dev Container, you don't need to expose the OpenChoreo Gateway manually; it's already
+ available on port 9080 (HTTP) and port 9443 (HTTPS) of the host machine.
+ :::
+
+
+
+
+ ## Explore More
+
+ After deploying your first application, try these additional examples to explore more of OpenChoreo's capabilities:
+
+ ### GCP Microservices Demo
+
+ Deploy a complete microservices application with 11 services (frontend, cart, checkout, payment, etc.):
+
+ ```bash
+ ./deploy-gcp-demo.sh
+ ```
+
+ This demonstrates how OpenChoreo handles multi-service applications and service-to-service communication.
+
+ ### Build and Deploy from Source
+
+ Experience the full development workflow by building a container image from source code and deploying it:
+
+ ```bash
+ ./build-deploy-greeter.sh
+ ```
+
+ :::note
+ This example requires the Build Plane. If you didn't install it initially, reinstall with:
+
+
+ {`./install.sh --version ${versions.helmChart} --with-build`}
+
+ :::
+
+ This demonstrates:
+ - Building container images from source
+ - Storing images in the integrated container registry
+ - Deploying the built image to the Data Plane
+
+
+
+
+
+
4
+
Cleaning up
+
+
+ After completing your work, choose one of the following options:
+
+ 1. **Exit and return later**: Exit the Dev Container to resume work later:
+ ```bash
+ exit
+ ```
+ 2. **Full cleanup**: Remove all resources and restore a clean environment:
+ ```bash
+ ./uninstall.sh
+ exit
+ ```
+
+ This completes the setup and teardown process for OpenChoreo.
+
+
+
+ ## Troubleshooting
+
+ ### Docker Resource Constraints
+
+ If installation fails, confirm Docker has sufficient resources:
+
+ ```bash
+ docker run --rm alpine:latest sh -c "echo 'Memory:'; free -h; echo; echo 'CPU Cores:'; nproc"
+ ```
+
+ Ensure at least **4 GB RAM** and **2 CPU cores** are allocated (or **8 GB RAM** and **4 CPU cores** if using
+ BuildPlane).
+
+
+
+You have now set up OpenChoreo locally using a preconfigured environment, deployed a sample web application, and learned how to inspect, manage, and clean up the setup.
+This environment serves as a reproducible baseline for testing and evaluating OpenChoreo components and workflows.
diff --git a/versioned_docs/version-v0.5.x/getting-started/single-cluster.mdx b/versioned_docs/version-v0.5.x/getting-started/single-cluster.mdx
new file mode 100644
index 0000000..4c3a886
--- /dev/null
+++ b/versioned_docs/version-v0.5.x/getting-started/single-cluster.mdx
@@ -0,0 +1,301 @@
+---
+title: Single Cluster
+description: Deploy OpenChoreo on a single Kubernetes cluster for development and testing. Complete setup guide with k3d, Helm charts, and configuration steps.
+---
+
+import CodeBlock from '@theme/CodeBlock';
+import Link from '@docusaurus/Link';
+import {versions} from '../_constants.mdx';
+
+# Single Cluster Setup
+
+This guide provides step-by-step instructions for setting up a local development environment for OpenChoreo using k3d (k3s in Docker).
+
+## Prerequisites
+
+- **Docker** β Just have it installed on your machine, and you're good to go.
+ - We recommend using [Docker Engine version 26.0+](https://docs.docker.com/engine/release-notes/26.0/).
+ - Allocate at least **8 GB RAM** and **4 CPU** cores to Docker (or the VM running Docker).
+- **[k3d](https://k3d.io/stable/#installation)** v5.8+ installed
+- **[kubectl](https://kubernetes.io/docs/tasks/tools/)** v1.32+ installed
+- **[Helm](https://helm.sh/docs/intro/install/)** v3.12+ installed
+
+### Verify Prerequisites
+
+Before proceeding, verify that all tools are installed and meet the minimum version requirements:
+
+```bash
+# Check Docker (should be v20.10+)
+docker --version
+
+# Check k3d (should be v5.8+)
+k3d --version
+
+# Check kubectl (should be v1.32+)
+kubectl version --client
+
+# Check Helm (should be v3.12+)
+helm version --short
+```
+
+Make sure Docker is running:
+
+```bash
+docker info
+```
+
+:::note
+If you're using **Colima**, set the `K3D_FIX_DNS=0` environment variable when creating clusters to avoid DNS issues. See [k3d-io/k3d#1449](https://github.com/k3d-io/k3d/issues/1449) for more details.
+:::
+
+## Quick Setup
+
+This setup uses pre-built images and Helm charts from the OpenChoreo registry.
+
+
+### 1. Create OpenChoreo k3d Cluster
+
+Create a new k3d cluster using the provided configuration:
+
+
+{`curl -s https://raw.githubusercontent.com/openchoreo/openchoreo/${versions.githubRef}/install/k3d/single-cluster/config.yaml | k3d cluster create --config=-`}
+
+
+This will:
+- Create a cluster named "openchoreo"
+- Set up a single k3d cluster with 1 server and 2 agents
+- Configure port mappings for accessing OpenChoreo services:
+ - **Control Plane**: `localhost:8080` (HTTP), `localhost:8443` (HTTPS)
+ - **Data Plane**: `localhost:9080` (HTTP), `localhost:9443` (HTTPS) - for deployed workloads
+ - **Build Plane**: `localhost:10081` (Argo Workflows UI), `localhost:10082` (Container Registry)
+ - **Observability Plane**: `localhost:11081` (OpenSearch Dashboard), `localhost:11082` (OpenSearch API)
+- Set kubectl context to "k3d-openchoreo"
+
+:::tip
+For faster setup or if you have slow network, consider preloading images after creating the cluster. See the [Image Preloading section](#image-preloading-optional) at the end of this guide.
+:::
+
+Verify the cluster is running:
+
+```bash
+kubectl get nodes
+```
+
+You should see nodes in `Ready` status.
+
+### 2. Install OpenChoreo Control Plane
+
+Install the OpenChoreo control plane using the following helm install command. This will create the `openchoreo-control-plane` namespace automatically:
+
+
+{`helm install openchoreo-control-plane oci://ghcr.io/openchoreo/helm-charts/openchoreo-control-plane \\
+ --version ${versions.helmChart} \\
+ --kube-context k3d-openchoreo \\
+ --namespace openchoreo-control-plane \\
+ --create-namespace \\
+ --values https://raw.githubusercontent.com/openchoreo/openchoreo/${versions.githubRef}/install/k3d/single-cluster/values-cp.yaml`}
+
+
+Wait for the installation to complete and verify all pods are running:
+
+```bash
+kubectl get pods -n openchoreo-control-plane
+```
+
+You should see pods for:
+- `controller-manager` (Running)
+- `cert-manager-*` (3 pods, all Running)
+
+### 3. Install OpenChoreo Data Plane
+
+Install the OpenChoreo data plane using the following helm install command. This will create the `openchoreo-data-plane` namespace automatically:
+
+
+{`helm install openchoreo-data-plane oci://ghcr.io/openchoreo/helm-charts/openchoreo-data-plane \\
+ --version ${versions.helmChart} \\
+ --kube-context k3d-openchoreo \\
+ --namespace openchoreo-data-plane \\
+ --create-namespace \\
+ --values https://raw.githubusercontent.com/openchoreo/openchoreo/${versions.githubRef}/install/k3d/single-cluster/values-dp.yaml`}
+
+
+Wait for dataplane components to be ready:
+
+```bash
+kubectl get pods -n openchoreo-data-plane
+```
+
+You should see pods for:
+- `envoy-gateway-*` (Running)
+- `external-secrets-*` (3 pods, all Running)
+- `fluent-bit-*` (Running on each node)
+- `gateway-external-*` (Running)
+
+### 4. Install OpenChoreo Build Plane (Optional)
+
+The Build Plane is required if you plan to use OpenChoreo's internal CI capabilities. If you're only deploying pre-built container images, you can skip this step.
+
+Install the OpenChoreo build plane using the following helm install command for CI/CD capabilities. This will create the `openchoreo-build-plane` namespace automatically:
+
+
+{`helm install openchoreo-build-plane oci://ghcr.io/openchoreo/helm-charts/openchoreo-build-plane \\
+ --version ${versions.helmChart} \\
+ --kube-context k3d-openchoreo \\
+ --namespace openchoreo-build-plane \\
+ --create-namespace \\
+ --values https://raw.githubusercontent.com/openchoreo/openchoreo/${versions.githubRef}/install/k3d/single-cluster/values-bp.yaml`}
+
+
+Wait for the build plane components to be ready:
+
+```bash
+kubectl get pods -n openchoreo-build-plane
+```
+
+You should see pods for:
+- `argo-server-*` (Running)
+- `argo-workflow-controller-*` (Running)
+- `registry-*` (Running)
+
+#### Configure BuildPlane
+
+Register the build plane with the control plane by running:
+
+
+{`curl -s https://raw.githubusercontent.com/openchoreo/openchoreo/${versions.githubRef}/install/add-build-plane.sh | bash -s -- --control-plane-context k3d-openchoreo`}
+
+
+This script creates a BuildPlane resource in the default namespace.
+
+Verify that the BuildPlane was created:
+
+```bash
+kubectl get buildplane -n default
+```
+
+### 5. Configure DataPlane
+
+Register the data plane with the control plane by running:
+
+
+{`curl -s https://raw.githubusercontent.com/openchoreo/openchoreo/${versions.githubRef}/install/add-data-plane.sh | bash -s -- --control-plane-context k3d-openchoreo`}
+
+
+This script creates a DataPlane resource in the default namespace.
+
+Verify the DataPlane was created:
+
+```bash
+kubectl get dataplane -n default
+```
+
+### 6. Install OpenChoreo Observability Plane (Optional)
+
+Install the OpenChoreo observability plane using the following helm install command for monitoring and logging capabilities. This will create the `openchoreo-observability-plane` namespace automatically:
+
+
+{`helm install openchoreo-observability-plane oci://ghcr.io/openchoreo/helm-charts/openchoreo-observability-plane \\
+ --version ${versions.helmChart} \\
+ --kube-context k3d-openchoreo \\
+ --namespace openchoreo-observability-plane \\
+ --create-namespace \\
+ --values https://raw.githubusercontent.com/openchoreo/openchoreo/${versions.githubRef}/install/k3d/single-cluster/values-op.yaml`}
+
+
+Wait for the observability plane components to be ready:
+
+```bash
+kubectl get pods -n openchoreo-observability-plane
+```
+
+You should see pods for:
+- `observer-*` (Running) - Log processing service
+- `opensearch-master-0` (Running) - Log storage backend
+- `opensearch-dashboards-*` (Running) - Visualization dashboard
+- `opensearch-cluster-setup-*` (Completed) - One-time setup job
+
+:::note
+The OpenSearch dashboard pod may take several minutes to start.
+:::
+
+Verify that all pods are ready:
+
+```bash
+kubectl wait --for=condition=Ready pod --all -n openchoreo-observability-plane --timeout=600s
+```
+
+Verify FluentBit is sending logs to OpenSearch:
+
+```bash
+# Check if kubernetes indices are being created
+kubectl exec -n openchoreo-observability-plane opensearch-master-0 -- curl -s "http://localhost:9200/_cat/indices?v" | grep kubernetes
+
+# Check recent log count
+kubectl exec -n openchoreo-observability-plane opensearch-master-0 -- curl -s "http://localhost:9200/kubernetes-*/_count" | jq '.count'
+```
+
+If the indices exist and the count is greater than 0, FluentBit is successfully collecting and storing logs.
+
+### 7. Verify OpenChoreo Installation
+
+#### Check that default OpenChoreo resources were created:
+
+```bash
+# Check default organization and project
+kubectl get organizations,projects,environments -A
+
+# Check default component types
+kubectl get componenttypes -n default
+
+# Check all OpenChoreo CRDs
+kubectl get crds | grep openchoreo
+
+# Check gateway resources
+kubectl get gateway,httproute -n openchoreo-data-plane
+```
+
+#### Check that all components are running:
+
+```bash
+# Check cluster info
+kubectl cluster-info --context k3d-openchoreo
+
+# Check control plane pods
+kubectl get pods -n openchoreo-control-plane
+
+# Check data plane pods
+kubectl get pods -n openchoreo-data-plane
+
+# Check build plane pods (if installed)
+kubectl get pods -n openchoreo-build-plane
+
+# Check observability plane pods (if installed)
+kubectl get pods -n openchoreo-observability-plane
+
+# Check nodes (should be Ready)
+kubectl get nodes
+```
+
+## Next Steps
+
+After completing this setup you can:
+
+1. [Deploy your first component](./deploy-first-component.mdx) to get started with OpenChoreo
+2. Test the GCP microservices demo to see multi-component applications in action
+3. Deploy additional sample applications from the OpenChoreo samples
+4. Develop and test new OpenChoreo features
+
+## Image Preloading (Optional)
+
+If you have slow network or want to save bandwidth when re-creating clusters, you can preload images before installing components. This pulls images to your host machine first, then imports them to the k3d cluster.
+
+Run this after creating the cluster (Step 1) but before installing components (Step 2). See the k3d single-cluster README for detailed preloading instructions.
+
+## Cleaning Up
+
+To completely remove the development environment:
+
+```bash
+# Delete the k3d cluster
+k3d cluster delete openchoreo
+```
diff --git a/versioned_docs/version-v0.5.x/integrating-with-openchoreo/ci-integration.md b/versioned_docs/version-v0.5.x/integrating-with-openchoreo/ci-integration.md
new file mode 100644
index 0000000..cab5ae3
--- /dev/null
+++ b/versioned_docs/version-v0.5.x/integrating-with-openchoreo/ci-integration.md
@@ -0,0 +1,303 @@
+---
+title: CI Integration
+unlisted: true
+---
+
+# CI Integration
+
+OpenChoreo seamlessly integrates with existing CI/CD pipelines to automate application deployment and management. This guide demonstrates how to incorporate OpenChoreo into popular CI systems for streamlined development workflows.
+
+## Overview
+
+OpenChoreo's CI integration enables:
+- **Automated deployments** triggered by code changes
+- **Environment promotion** through deployment pipelines
+- **Configuration validation** before deployment
+- **Rollback capabilities** for failed deployments
+- **Integration testing** in isolated environments
+
+## Supported CI Systems
+
+### GitHub Actions
+
+OpenChoreo provides official GitHub Actions for seamless integration:
+
+```yaml
+name: Deploy to OpenChoreo
+on:
+ push:
+ branches: [main]
+
+jobs:
+ deploy:
+ runs-on: ubuntu-latest
+ steps:
+ - uses: actions/checkout@v3
+
+ - name: Setup OpenChoreo CLI
+ uses: openchoreo/setup-choreo@v1
+ with:
+ version: 'latest'
+
+ - name: Deploy Application
+ run: |
+ choreo auth login --token ${{ secrets.CHOREO_TOKEN }}
+ choreo deploy --environment production
+ env:
+ CHOREO_TOKEN: ${{ secrets.CHOREO_TOKEN }}
+```
+
+### GitLab CI
+
+Integration with GitLab CI using Docker containers:
+
+```yaml
+stages:
+ - build
+ - test
+ - deploy
+
+deploy_production:
+ stage: deploy
+ image: openchoreo/cli:latest
+ script:
+ - choreo auth login --token $CHOREO_TOKEN
+ - choreo deploy --environment production
+ only:
+ - main
+ variables:
+ CHOREO_TOKEN: $CHOREO_API_TOKEN
+```
+
+### Jenkins
+
+Jenkins pipeline integration using the OpenChoreo CLI:
+
+```groovy
+pipeline {
+ agent any
+
+ environment {
+ CHOREO_TOKEN = credentials('choreo-api-token')
+ }
+
+ stages {
+ stage('Deploy') {
+ steps {
+ sh '''
+ curl -sSL https://install.openchoreo.dev | sh
+ choreo auth login --token ${CHOREO_TOKEN}
+ choreo deploy --environment production
+ '''
+ }
+ }
+ }
+}
+```
+
+## CI Workflow Patterns
+
+### Feature Branch Deployment
+
+Deploy feature branches to ephemeral environments:
+
+```yaml
+name: Feature Branch Deploy
+on:
+ pull_request:
+ types: [opened, synchronize]
+
+jobs:
+ deploy-feature:
+ runs-on: ubuntu-latest
+ steps:
+ - uses: actions/checkout@v3
+
+ - name: Create Feature Environment
+ run: |
+ choreo env create --name "feature-${{ github.head_ref }}" \
+ --template development
+
+ - name: Deploy to Feature Environment
+ run: |
+ choreo deploy --environment "feature-${{ github.head_ref }}"
+```
+
+### Multi-Environment Promotion
+
+Promote applications through environments:
+
+```yaml
+name: Multi-Environment Deploy
+on:
+ push:
+ branches: [main]
+
+jobs:
+ deploy-staging:
+ runs-on: ubuntu-latest
+ steps:
+ - name: Deploy to Staging
+ run: choreo deploy --environment staging
+
+ deploy-production:
+ needs: deploy-staging
+ runs-on: ubuntu-latest
+ environment: production
+ steps:
+ - name: Deploy to Production
+ run: choreo deploy --environment production
+```
+
+## Build Integration
+
+### Container Image Building
+
+Integrate with container registries:
+
+```yaml
+- name: Build and Push Image
+ run: |
+ docker build -t ${{ env.REGISTRY }}/app:${{ github.sha }} .
+ docker push ${{ env.REGISTRY }}/app:${{ github.sha }}
+
+- name: Update OpenChoreo Configuration
+ run: |
+ choreo component update app \
+ --image ${{ env.REGISTRY }}/app:${{ github.sha }}
+```
+
+### Cloud Native Buildpacks
+
+Use Buildpacks for automatic image creation:
+
+```yaml
+- name: Build with Buildpacks
+ run: |
+ pack build ${{ env.REGISTRY }}/app:${{ github.sha }} \
+ --builder paketobuildpacks/builder:base
+ docker push ${{ env.REGISTRY }}/app:${{ github.sha }}
+```
+
+## Testing Integration
+
+### Integration Testing
+
+Run tests against deployed environments:
+
+```yaml
+- name: Deploy Test Environment
+ run: choreo deploy --environment test
+
+- name: Run Integration Tests
+ run: |
+ export API_URL=$(choreo env get test --output json | jq -r '.endpoints.api.url')
+ npm run test:integration
+
+- name: Cleanup Test Environment
+ run: choreo env delete test
+ if: always()
+```
+
+### Load Testing
+
+Automated performance testing:
+
+```yaml
+- name: Load Testing
+ run: |
+ export APP_URL=$(choreo component get api --environment staging -o json | jq -r '.url')
+ k6 run --env API_URL=$APP_URL load-test.js
+```
+
+## Security and Secrets Management
+
+### API Token Management
+
+Secure token handling across CI systems:
+
+```yaml
+- name: Configure OpenChoreo Auth
+ run: |
+ echo "${{ secrets.CHOREO_TOKEN }}" | choreo auth login --stdin
+
+- name: Verify Authentication
+ run: choreo auth whoami
+```
+
+### Secrets Injection
+
+Automatic secrets deployment:
+
+```yaml
+- name: Deploy Application Secrets
+ run: |
+ choreo secret create database-url \
+ --value "${{ secrets.DATABASE_URL }}" \
+ --environment production
+```
+
+## Monitoring and Notifications
+
+### Deployment Status
+
+Track deployment progress:
+
+```yaml
+- name: Monitor Deployment
+ run: |
+ choreo deploy --environment production --wait
+
+- name: Verify Health Checks
+ run: |
+ choreo component status api --environment production
+```
+
+### Slack Integration
+
+Notify teams of deployment status:
+
+```yaml
+- name: Notify Deployment Success
+ uses: 8398a7/action-slack@v3
+ with:
+ status: ${{ job.status }}
+ text: "Deployment to production completed successfully"
+ if: success()
+```
+
+## Troubleshooting
+
+### Common Issues
+
+**Authentication Failures**
+- Verify API token permissions
+- Check token expiration
+- Ensure proper secret configuration
+
+**Deployment Timeouts**
+- Increase timeout values
+- Check resource availability
+- Monitor application startup logs
+
+**Environment Conflicts**
+- Use unique environment names
+- Implement proper cleanup strategies
+- Validate environment state before deployment
+
+### Debug Mode
+
+Enable verbose logging for troubleshooting:
+
+```bash
+choreo deploy --environment production --debug --verbose
+```
+
+## Best Practices
+
+- **Use environment-specific configurations**
+- **Implement proper secret management**
+- **Enable deployment monitoring and alerting**
+- **Use feature flags for gradual rollouts**
+- **Maintain deployment history and rollback capabilities**
+- **Test deployments in staging environments first**
\ No newline at end of file
diff --git a/versioned_docs/version-v0.5.x/integrating-with-openchoreo/gitops.md b/versioned_docs/version-v0.5.x/integrating-with-openchoreo/gitops.md
new file mode 100644
index 0000000..f24f5a0
--- /dev/null
+++ b/versioned_docs/version-v0.5.x/integrating-with-openchoreo/gitops.md
@@ -0,0 +1,746 @@
+---
+title: GitOps
+unlisted: true
+---
+
+# GitOps with OpenChoreo
+
+OpenChoreo embraces GitOps principles by treating Git repositories as the single source of truth for both platform configuration and application deployments. This approach enables declarative, versioned, and auditable infrastructure and application management across multiple environments and clusters.
+
+## GitOps Principles in OpenChoreo
+
+OpenChoreo implements GitOps through four core principles:
+
+1. **Declarative Configuration**: All system state described through OpenChoreo CRDs and YAML manifests
+2. **Version Control**: Platform and application configurations stored in Git repositories
+3. **Automated Deployment**: Changes automatically reconciled by Kubernetes controllers and GitOps operators
+4. **Continuous Monitoring**: System continuously reconciles desired vs actual state with drift detection
+
+## Repository Organization Patterns
+
+### Platform Configuration Repository
+
+Structure for platform engineers managing infrastructure and standards:
+
+```
+platform-config/
+βββ platform/
+β βββ organizations/
+β β βββ acme-corp.yaml # Organization definition
+β βββ dataplanes/
+β β βββ development-cluster.yaml # Development cluster config
+β β βββ staging-cluster.yaml # Staging cluster config
+β β βββ production-cluster.yaml # Production cluster config
+β βββ buildplanes/
+β β βββ ci-buildplane.yaml # Build infrastructure
+β βββ environments/
+β β βββ development.yaml # Dev environment
+β β βββ staging.yaml # Staging environment
+β β βββ production.yaml # Production environment
+β βββ deployment-pipelines/
+β β βββ standard-pipeline.yaml # Promotion workflows
+β βββ workload-classes/
+β β βββ service-class.yaml # Service templates
+β β βββ webapp-class.yaml # Web app templates
+β β βββ task-class.yaml # Scheduled task templates
+β βββ endpoint-classes/
+β βββ internal-api.yaml # Internal API policies
+β βββ public-api.yaml # Public API policies
+β βββ webapp-endpoint.yaml # Web application endpoints
+βββ configuration-groups/
+β βββ database-config.yaml # Shared database config
+β βββ monitoring-config.yaml # Observability settings
+β βββ security-config.yaml # Security policies
+βββ flux-system/
+ βββ gotk-components.yaml # Flux components
+ βββ gotk-sync.yaml # Repository sync config
+ βββ kustomization.yaml # Platform Kustomization
+```
+
+### Application Repository
+
+Structure for development teams managing applications:
+
+```
+user-service/
+βββ .choreo/
+β βββ project.yaml # Project definition
+β βββ components/
+β β βββ api-component.yaml # API ComponentV
+β β βββ worker-component.yaml # Background worker
+β β βββ database-component.yaml # Database component
+β βββ workloads/
+β β βββ base/
+β β β βββ api-workload.yaml # Base API workload
+β β β βββ worker-workload.yaml # Base worker workload
+β β βββ development/
+β β β βββ kustomization.yaml # Dev overrides
+β β β βββ api-dev-patch.yaml # Dev-specific config
+β β βββ staging/
+β β β βββ kustomization.yaml # Staging overrides
+β β β βββ api-staging-patch.yaml # Staging-specific config
+β β βββ production/
+β β βββ kustomization.yaml # Prod overrides
+β β βββ api-prod-patch.yaml # Prod-specific config
+β βββ endpoints/
+β βββ user-api-endpoint.yaml # API endpoint definition
+β βββ admin-api-endpoint.yaml # Admin endpoint definition
+βββ src/ # Application source code
+βββ Dockerfile # Container build definition
+βββ README.md
+```
+
+## OpenChoreo Resource Integration
+
+### Component with GitOps
+
+Define application components with integrated build and deployment:
+
+```yaml
+# .choreo/components/api-component.yaml
+apiVersion: choreo.dev/v1alpha1
+kind: Component
+metadata:
+ name: user-api
+ namespace: acme-corp
+spec:
+ componentOwner:
+ projectRef: "user-service"
+ componentType: "Service"
+ buildSpecInComponent:
+ repository: "https://github.com/acme-corp/user-service"
+ contextPath: "."
+ buildTemplate: "dockerfile"
+ parameters:
+ DOCKERFILE_PATH: "./Dockerfile"
+ BUILD_ARGS: |
+ NODE_ENV=production
+ API_VERSION=v1
+ workloadClassRef: "standard-service"
+ endpointClassRef: "internal-api"
+```
+
+### Workload with Environment Overrides
+
+Base workload specification:
+
+```yaml
+# .choreo/workloads/base/api-workload.yaml
+apiVersion: choreo.dev/v1alpha1
+kind: Workload
+metadata:
+ name: user-api-workload
+spec:
+ owner:
+ projectName: "user-service"
+ componentName: "user-api"
+ containers:
+ api:
+ image: "user-service:latest"
+ ports:
+ - containerPort: 3000
+ protocol: TCP
+ env:
+ - name: "NODE_ENV"
+ value: "development"
+ - name: "LOG_LEVEL"
+ value: "info"
+ resources:
+ requests:
+ memory: "256Mi"
+ cpu: "200m"
+ limits:
+ memory: "512Mi"
+ cpu: "500m"
+ endpoints:
+ http:
+ type: "HTTP"
+ port: 3000
+ schema: "openapi.yaml"
+ connections:
+ database:
+ type: "api"
+ url: "postgresql://user-db:5432/users"
+```
+
+Production environment overlay:
+
+```yaml
+# .choreo/workloads/production/api-prod-patch.yaml
+apiVersion: choreo.dev/v1alpha1
+kind: Workload
+metadata:
+ name: user-api-workload
+spec:
+ containers:
+ api:
+ env:
+ - name: "NODE_ENV"
+ value: "production"
+ - name: "LOG_LEVEL"
+ value: "warn"
+ resources:
+ requests:
+ memory: "512Mi"
+ cpu: "500m"
+ limits:
+ memory: "1Gi"
+ cpu: "1000m"
+```
+
+```yaml
+# .choreo/workloads/production/kustomization.yaml
+apiVersion: kustomize.config.k8s.io/v1beta1
+kind: Kustomization
+
+resources:
+- ../base
+
+patchesStrategicMerge:
+- api-prod-patch.yaml
+
+images:
+- name: user-service
+ newTag: v1.2.3
+```
+
+## Flux Integration
+
+### GitRepository Configuration
+
+Configure Flux to monitor OpenChoreo repositories:
+
+```yaml
+# Platform repository sync
+apiVersion: source.toolkit.fluxcd.io/v1
+kind: GitRepository
+metadata:
+ name: platform-config
+ namespace: flux-system
+spec:
+ interval: 1m
+ url: https://github.com/acme-corp/platform-config
+ ref:
+ branch: main
+ secretRef:
+ name: git-credentials
+---
+# Application repository sync
+apiVersion: source.toolkit.fluxcd.io/v1
+kind: GitRepository
+metadata:
+ name: user-service
+ namespace: flux-system
+spec:
+ interval: 30s
+ url: https://github.com/acme-corp/user-service
+ ref:
+ branch: main
+ secretRef:
+ name: git-credentials
+```
+
+### Kustomization for Platform Resources
+
+Deploy platform configuration with proper dependencies:
+
+```yaml
+# Platform infrastructure
+apiVersion: kustomize.toolkit.fluxcd.io/v1
+kind: Kustomization
+metadata:
+ name: platform-infrastructure
+ namespace: flux-system
+spec:
+ interval: 5m
+ path: "./platform"
+ prune: true
+ sourceRef:
+ kind: GitRepository
+ name: platform-config
+ healthChecks:
+ - apiVersion: choreo.dev/v1alpha1
+ kind: Organization
+ name: acme-corp
+ - apiVersion: choreo.dev/v1alpha1
+ kind: DataPlane
+ name: production-cluster
+---
+# Application deployments (depends on platform)
+apiVersion: kustomize.toolkit.fluxcd.io/v1
+kind: Kustomization
+metadata:
+ name: user-service-production
+ namespace: flux-system
+spec:
+ interval: 2m
+ path: "./.choreo/workloads/production"
+ prune: true
+ sourceRef:
+ kind: GitRepository
+ name: user-service
+ targetNamespace: user-service-prod
+ dependsOn:
+ - name: platform-infrastructure
+```
+
+## Multi-Environment Management
+
+### Environment-Specific Configurations
+
+Development environment with relaxed settings:
+
+```yaml
+# .choreo/workloads/development/kustomization.yaml
+apiVersion: kustomize.config.k8s.io/v1beta1
+kind: Kustomization
+
+resources:
+- ../base
+
+patchesStrategicMerge:
+- dev-overrides.yaml
+
+images:
+- name: user-service
+ newTag: latest
+
+replicas:
+- name: user-api-workload
+ count: 1
+```
+
+Production environment with enhanced security:
+
+```yaml
+# .choreo/workloads/production/kustomization.yaml
+apiVersion: kustomize.config.k8s.io/v1beta1
+kind: Kustomization
+
+resources:
+- ../base
+
+patchesStrategicMerge:
+- prod-overrides.yaml
+- security-policies.yaml
+
+images:
+- name: user-service
+ newTag: v1.2.3
+
+replicas:
+- name: user-api-workload
+ count: 3
+```
+
+### ConfigurationGroup for Environment Variables
+
+Environment-specific configuration management:
+
+```yaml
+apiVersion: choreo.dev/v1alpha1
+kind: ConfigurationGroup
+metadata:
+ name: user-service-config
+ namespace: acme-corp
+spec:
+ scope:
+ organization: "acme-corp"
+ project: "user-service"
+ environmentGroups:
+ - name: "non-production"
+ environments: ["development", "staging"]
+ - name: "production"
+ environments: ["production"]
+ configurations:
+ - key: "database.host"
+ values:
+ - environmentGroupRef: "non-production"
+ value: "dev-postgres.internal"
+ - environmentGroupRef: "production"
+ vaultKey: "secret/prod/database/host"
+ - key: "redis.url"
+ values:
+ - environment: "development"
+ value: "redis://dev-redis:6379"
+ - environment: "staging"
+ value: "redis://staging-redis:6379"
+ - environment: "production"
+ vaultKey: "secret/prod/redis/url"
+```
+
+## Advanced GitOps Patterns
+
+### Progressive Delivery with Canary Deployments
+
+Canary deployment configuration using Workload bindings:
+
+```yaml
+# Production canary binding
+apiVersion: choreo.dev/v1alpha1
+kind: ServiceBinding
+metadata:
+ name: user-api-canary
+ namespace: user-service-prod
+spec:
+ serviceClassRef: "standard-service"
+ environmentRef: "production"
+ workload:
+ containers:
+ api:
+ image: "user-service:v1.3.0-canary"
+ replicas: 1
+ traffic:
+ weight: 10 # 10% of traffic to canary
+---
+# Production stable binding
+apiVersion: choreo.dev/v1alpha1
+kind: ServiceBinding
+metadata:
+ name: user-api-stable
+ namespace: user-service-prod
+spec:
+ serviceClassRef: "standard-service"
+ environmentRef: "production"
+ workload:
+ containers:
+ api:
+ image: "user-service:v1.2.3"
+ replicas: 2
+ traffic:
+ weight: 90 # 90% of traffic to stable
+```
+
+### Multi-Repository Strategy
+
+Separate repositories for different concerns:
+
+```yaml
+# apps-of-apps.yaml - Root application managing multiple repositories
+apiVersion: argoproj.io/v1alpha1
+kind: Application
+metadata:
+ name: platform-apps
+ namespace: argocd
+spec:
+ project: default
+ source:
+ repoURL: https://github.com/acme-corp/gitops-apps
+ path: applications
+ targetRevision: main
+ destination:
+ server: https://kubernetes.default.svc
+ namespace: argocd
+ syncPolicy:
+ automated:
+ prune: true
+ selfHeal: true
+```
+
+```yaml
+# applications/user-service.yaml
+apiVersion: argoproj.io/v1alpha1
+kind: Application
+metadata:
+ name: user-service
+spec:
+ project: default
+ sources:
+ - repoURL: https://github.com/acme-corp/user-service
+ path: .choreo/workloads/production
+ targetRevision: main
+ - repoURL: https://github.com/acme-corp/platform-config
+ path: configuration-groups
+ targetRevision: main
+ destination:
+ server: https://kubernetes.default.svc
+ namespace: user-service-prod
+ syncPolicy:
+ automated:
+ selfHeal: true
+ syncOptions:
+ - CreateNamespace=true
+```
+
+## Secret Management Integration
+
+### Vault CSI Integration
+
+Vault secret configuration:
+
+```yaml
+apiVersion: choreo.dev/v1alpha1
+kind: ConfigurationGroup
+metadata:
+ name: user-service-secrets
+spec:
+ configurations:
+ - key: "database.password"
+ values:
+ - environment: "production"
+ vaultKey: "secret/prod/database/password"
+ vaultMount: "kv-v2"
+ - key: "api.jwt.secret"
+ values:
+ - environment: "production"
+ vaultKey: "secret/prod/api/jwt-secret"
+ vaultMount: "kv-v2"
+```
+
+Corresponding Vault CSI SecretProviderClass:
+
+```yaml
+apiVersion: secrets-store.csi.x-k8s.io/v1
+kind: SecretProviderClass
+metadata:
+ name: user-service-secrets
+ namespace: user-service-prod
+spec:
+ provider: vault
+ parameters:
+ vaultAddress: "https://vault.internal:8200"
+ roleName: "user-service"
+ objects: |
+ - objectName: "database-password"
+ secretPath: "secret/prod/database"
+ secretKey: "password"
+ - objectName: "jwt-secret"
+ secretPath: "secret/prod/api"
+ secretKey: "jwt-secret"
+ secretObjects:
+ - secretName: user-service-secrets
+ type: Opaque
+ data:
+ - objectName: database-password
+ key: password
+ - objectName: jwt-secret
+ key: jwt-secret
+```
+
+## Promotion Workflows
+
+### Automated Promotion Pipeline
+
+GitHub Actions workflow for environment promotion:
+
+```yaml
+# .github/workflows/promote.yml
+name: Promote Application
+on:
+ workflow_dispatch:
+ inputs:
+ environment:
+ description: 'Target environment'
+ required: true
+ type: choice
+ options:
+ - staging
+ - production
+ image_tag:
+ description: 'Image tag to promote'
+ required: true
+
+jobs:
+ promote:
+ runs-on: ubuntu-latest
+ steps:
+ - name: Checkout
+ uses: actions/checkout@v4
+
+ - name: Update Kustomization
+ run: |
+ cd .choreo/workloads/${{ inputs.environment }}
+ yq eval '.images[0].newTag = "${{ inputs.image_tag }}"' \
+ -i kustomization.yaml
+
+ - name: Create GitCommitRequest
+ run: |
+ kubectl apply -f - <> $GITHUB_OUTPUT
+
+ - name: Update Production Config
+ run: |
+ yq eval '.images[0].newTag = "${{ steps.image.outputs.tag }}"' \
+ -i .choreo/workloads/production/kustomization.yaml
+
+ - name: Create Pull Request
+ uses: peter-evans/create-pull-request@v5
+ with:
+ token: ${{ secrets.GITHUB_TOKEN }}
+ commit-message: "Promote to production: ${{ steps.image.outputs.tag }}"
+ title: "π Promote to Production"
+ body: |
+ ## Promote to Production Environment
+
+ **Image Tag**: `${{ steps.image.outputs.tag }}`
+
+ ### Changes
+ - Updated production image tag
+ - Ready for production deployment
+
+ ### Checklist
+ - [ ] Staging tests passed
+ - [ ] Security scan completed
+ - [ ] Performance validation completed
+ - [ ] Approved by platform team
+ base: main
+ branch: promote-to-production-${{ steps.image.outputs.tag }}
+ labels: |
+ promotion
+ production
+ auto-generated
+```
+
+## Monitoring and Observability
+
+### GitOps Health Monitoring
+
+Monitor GitOps deployment health:
+
+```yaml
+apiVersion: v1
+kind: ServiceMonitor
+metadata:
+ name: flux-system
+ namespace: flux-system
+spec:
+ selector:
+ matchLabels:
+ app: source-controller
+ endpoints:
+ - port: http-prom
+ interval: 30s
+ path: /metrics
+---
+apiVersion: monitoring.coreos.com/v1
+kind: PrometheusRule
+metadata:
+ name: gitops-alerts
+ namespace: flux-system
+spec:
+ groups:
+ - name: gitops.rules
+ rules:
+ - alert: GitOpsReconciliationFailure
+ expr: increase(gotk_reconcile_condition{type="Ready",status="False"}[5m]) > 0
+ for: 2m
+ labels:
+ severity: warning
+ annotations:
+ summary: "GitOps reconciliation failing"
+ description: "{{ $labels.kind }}/{{ $labels.name }} reconciliation has been failing"
+```
+
+### Deployment Status Dashboard
+
+Grafana dashboard for tracking deployments:
+
+```yaml
+apiVersion: v1
+kind: ConfigMap
+metadata:
+ name: gitops-dashboard
+ namespace: monitoring
+data:
+ dashboard.json: |
+ {
+ "dashboard": {
+ "title": "OpenChoreo GitOps Status",
+ "panels": [
+ {
+ "title": "Reconciliation Status",
+ "type": "stat",
+ "targets": [
+ {
+ "expr": "sum(gotk_reconcile_condition{type=\"Ready\",status=\"True\"})",
+ "legendFormat": "Successful"
+ },
+ {
+ "expr": "sum(gotk_reconcile_condition{type=\"Ready\",status=\"False\"})",
+ "legendFormat": "Failed"
+ }
+ ]
+ }
+ ]
+ }
+ }
+```
+
+## Best Practices
+
+### Repository Organization
+- **Separate platform and application repositories** for clear ownership boundaries
+- **Use consistent directory structures** across all repositories
+- **Implement branch protection rules** with required reviews for production changes
+- **Tag releases** with semantic versioning for traceability
+
+### Security and Compliance
+- **Never commit secrets in plaintext** - use Vault, External Secrets, or sealed secrets
+- **Implement RBAC** for repository access aligned with OpenChoreo Organizations
+- **Enable signed commits** and verify signatures in CI/CD pipelines
+- **Scan configurations** for security vulnerabilities and policy violations
+
+### Deployment Strategy
+- **Use staged deployments** with proper approval gates between environments
+- **Implement automated rollback** on health check failures
+- **Monitor deployment metrics** and application health post-deployment
+- **Maintain audit trails** through Git history and deployment logs
+
+### Configuration Management
+- **Use Kustomize overlays** for environment-specific configurations
+- **Leverage ConfigurationGroups** for shared configuration across components
+- **Implement configuration validation** in CI/CD pipelines
+- **Version configuration changes** alongside application releases
+
+### Troubleshooting and Operations
+- **Enable comprehensive logging** for all GitOps operators and controllers
+- **Implement drift detection** with automatic remediation where appropriate
+- **Set up proper alerting** for reconciliation failures and configuration drift
+- **Maintain disaster recovery procedures** for GitOps infrastructure and repositories
+- **Document operational runbooks** for common scenarios and incident response
+
+### Performance Optimization
+- **Optimize reconciliation intervals** based on change frequency and requirements
+- **Use resource limits** and requests for GitOps operators
+- **Implement caching strategies** for frequently accessed configurations
+- **Monitor resource utilization** and scale GitOps infrastructure appropriately
+
+By following these GitOps patterns and best practices with OpenChoreo, organizations can achieve reliable, auditable, and scalable application delivery while maintaining the benefits of declarative infrastructure management and automated operations.
diff --git a/versioned_docs/version-v0.5.x/learn-from-examples/examples-catalog.mdx b/versioned_docs/version-v0.5.x/learn-from-examples/examples-catalog.mdx
new file mode 100644
index 0000000..01a3704
--- /dev/null
+++ b/versioned_docs/version-v0.5.x/learn-from-examples/examples-catalog.mdx
@@ -0,0 +1,169 @@
+---
+title: Learn from Examples
+---
+
+import Link from '@docusaurus/Link';
+import {versions} from '../_constants.mdx';
+
+export const GitHubSampleLink = ({path, children}) => (
+
+ {children}
+
+);
+
+# Learn from Examples
+
+OpenChoreo empowers developers to build cloud-native applications through practical, real-world examples. This section provides comprehensive tutorials that demonstrate OpenChoreo's capabilities across different use cases and complexity levels.
+
+## Categories
+We have categorized the samples based on what you might want to do:
+- **[Platform Configuration](#platform-configuration)** - Define and customize foundational platform elements such as organizations, environments, and deployment pipelines according to your organization needs.
+- **[Application Deployment](#application-deployment)** - Deploy different types of applications (services, APIs, web apps, tasks) using various programming languages and deployment strategies.
+
+---
+
+## Platform Configuration
+When you set up OpenChoreo, certain default resources are automatically created to help you get started quickly:
+- A default organization
+- A default data plane and build plane
+- Three default environments (Dev, Staging, Prod)
+- A default deployment pipeline connecting these environments
+- A default project to organize applications
+
+OpenChoreo provides abstractions to define:
+- **Organizations** β Manage access and group related projects at cluster scope.
+- **Environments** β Set up Dev, Staging, and Prod runtime contexts.
+- **DataPlanes** β Define Kubernetes clusters for application deployments.
+- **BuildPlanes** β Define dedicated Kubernetes clusters for CI/CD operations.
+- **DeploymentPipelines** β Automate application rollouts with promotion workflows.
+
+For more details on these concepts, refer to the [Concepts](../concepts/platform-abstractions.md) documentation.
+
+These default configurations provide a quick starting point. Once you have done some exploration you can start creating the necessary artifacts to match the needs of your organization. You can:
+
+- Create new environments in your organization
+- Create a new deployment pipeline that will link these environments
+
+---
+
+## Application Deployment
+These samples help you deploy different types of applications using OpenChoreo. All samples refer to the default setup.
+
+### Component Types
+
+OpenChoreo supports different component types with the modern **Component** resource:
+
+- **Services** β Backend services & APIs built from source code
+ - Go Service with Docker - REST API service with Docker build
+ - Go Service with Buildpacks - Service using Cloud Native Buildpacks
+ - Ballerina Service - Ballerina language service
+
+- **Web Applications** β Frontend or full-stack applications
+ - React SPA - Single-page application built from source
+
+- **Pre-built Applications** β Applications deployed from existing container images
+ - Go Greeter Service - Service deployed from pre-built image
+ - React Web App - Web application from pre-built image
+ - GitHub Issue Reporter - Scheduled task with configuration management
+
+### Complete Application Examples
+
+- **GCP Microservices Demo** β Complete multi-service application demonstrating:
+ - Project organization with multiple components
+ - Service interactions and dependencies
+ - Coordinated deployment patterns
+ - Configuration management across services
+
+### Supported Languages (via BuildPacks)
+OpenChoreo abstracts the build and deployment process using BuildPacks and Build resources, enabling developers to deploy applications written in:
+- **Ballerina** - Patient Management Service
+- **Go** - Greeter Service and Reading List
+- **Node.js/React** - React Starter
+- **Python** - (Additional samples can be added)
+- **Ruby** - (Additional samples can be added)
+- (More languages can be added as extensions.)
+
+### Key Features Demonstrated
+
+- **Build Integration** β Component with integrated Build for CI/CD workflows
+- **Configuration Management** β Environment-specific configs and secrets
+- **Component Types** β Component types with environment-specific ComponentDeployments
+
+### Getting Started
+
+1. **Deploy Platform Configuration**:
+ ```bash
+ kubectl apply -f platform-config/new-environments/
+ kubectl apply -f platform-config/new-deployment-pipeline/
+ ```
+
+2. **Deploy a Simple Service**:
+ ```bash
+ kubectl apply -f from-source/services/go-docker-greeter/
+ ```
+
+3. **Deploy Complete Application**:
+ ```bash
+ kubectl apply -f gcp-microservices-demo/
+ ```
+
+> [!Note]
+> In case you need to try these application samples with custom platform configuration, remember to use the new resource names you created while following the "Platform Configuration" section above.
+
+---
+
+## Featured Examples
+
+### Go Greeting Service from Source
+Learn OpenChoreo fundamentals by deploying a simple Go REST service built from source code. This example demonstrates the complete CI/CD workflow from source code to running service.
+
+**Features:**
+- Source-to-deployment workflow
+- Docker-based build process
+- REST API with greeting endpoints
+- Gateway integration and testing
+
+**Try it:** Go Docker Greeter
+
+### Google Cloud Microservices Demo
+Build a complete e-commerce platform using Google's reference microservices architecture. This comprehensive example demonstrates service-to-service communication, distributed systems patterns, and complex application deployment.
+
+**Features:**
+- 11 interconnected microservices
+- Frontend web application
+- Redis cache integration
+- Production-ready container images
+- Service mesh communication patterns
+
+**Try it:** GCP Microservices Demo
+
+### Multi-Environment Deployment Pipeline
+Set up sophisticated deployment pipelines across development, QA, pre-production, and production environments with automated promotion workflows.
+
+**Features:**
+- Four-stage deployment pipeline
+- Environment-to-environment promotion
+- Automated rollout workflows
+- Production-ready governance
+
+**Try it:** New Deployment Pipeline
+
+---
+
+## Community Examples
+
+The OpenChoreo community can contribute additional examples covering:
+- Industry-specific use cases
+- Integration with third-party services
+- Custom component types
+- Advanced deployment patterns
+
+---
+
+## Getting Help
+
+- **Documentation**: Each example includes instruction documentation
+- **Community Forums**: Ask questions and share your implementations on Discord
+- **GitHub Issues**: Report bugs or request new examples
+
+Ready to start building? Choose an example that matches your use case, then follow along to see OpenChoreo in action!
diff --git a/versioned_docs/version-v0.5.x/overview/architecture.mdx b/versioned_docs/version-v0.5.x/overview/architecture.mdx
new file mode 100644
index 0000000..267d418
--- /dev/null
+++ b/versioned_docs/version-v0.5.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.
+
+
+
+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 concrete infrastructure 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 configurations
+- 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, and 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, so 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.
+
+
+
+
+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 co-locate certain planes (e.g., Control + CI) for cost or operational efficiency.
diff --git a/versioned_docs/version-v0.5.x/overview/what-is-openchoreo.mdx b/versioned_docs/version-v0.5.x/overview/what-is-openchoreo.mdx
new file mode 100644
index 0000000..dcabdb6
--- /dev/null
+++ b/versioned_docs/version-v0.5.x/overview/what-is-openchoreo.mdx
@@ -0,0 +1,65 @@
+---
+title: What is OpenChoreo
+slug: /
+description: "Introduction to OpenChoreo: an open-source Internal Developer Platform (IDP) that helps platform teams deliver scalable, self-service developer experiences on Kubernetes."
+---
+
+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 orchestrates many CNCF and other 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 vision.
+
+## Why OpenChoreo?
+
+Kubernetes gives you powerful primitives like Namespaces, Deployments, CronJobs, Services, and NetworkPoliciesβbut they are too low-level for most developers.
+
+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.
+
+**OpenChoreo fills that gap.** It provides all essential 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
+
+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.
+
+## OpenChoreo Components
+
+OpenChoreo is made up of several key components that work together to deliver a comprehensive IDP.
+
+- **Control Plane** - The orchestration layer that watches developer and platform APIs, validates configurations and translates them into Kubernetes-native and cloud-native infrastructure.
+- **Developer API** - Simplified, self-service interfaces for developers to model, deploy and manage 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 the OpenChoreo installation.
+- **Data Plane** - The execution environment for applications that is built on Kubernetes and extended with Cilium, Envoy Gateway, and other CNCF tools. The 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.
+
+Learn more about how these components fit together in the [OpenChoreo Architecture](./architecture.mdx) section.
+
+## Current Status
+
+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 the stable release timeline.
+
+## Getting Started
+
+Ready to try OpenChoreo? Start here:
+
+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.
+
+Weβre excited to have you on board!
diff --git a/versioned_docs/version-v0.5.x/reference/api/application/build.md b/versioned_docs/version-v0.5.x/reference/api/application/build.md
new file mode 100644
index 0000000..9b3cbc3
--- /dev/null
+++ b/versioned_docs/version-v0.5.x/reference/api/application/build.md
@@ -0,0 +1,159 @@
+---
+title: Build API Reference
+---
+
+# Build
+
+A Build represents a build job in OpenChoreo that transforms source code into a container image. It defines the
+source repository, revision, and build template to use for creating workloads. Upon successful
+completion, a Build creates a Workload resource containing the built container image.
+
+## API Version
+
+`openchoreo.dev/v1alpha1`
+
+## Resource Definition
+
+### Metadata
+
+Builds are namespace-scoped resources that must be created within an Organization's namespace and belong to a
+Component through the owner field.
+
+```yaml
+apiVersion: openchoreo.dev/v1alpha1
+kind: Build
+metadata:
+ name:
+ namespace: # Organization namespace
+```
+
+### Spec Fields
+
+| Field | Type | Required | Default | Description |
+|---------------|-----------------------------|----------|---------|--------------------------------------------------------------------|
+| `owner` | [BuildOwner](#buildowner) | Yes | - | Ownership information linking the build to a project and component |
+| `repository` | [Repository](#repository) | Yes | - | Source repository configuration |
+| `templateRef` | [TemplateRef](#templateref) | Yes | - | Build template reference and parameters |
+
+### BuildOwner
+
+| Field | Type | Required | Default | Description |
+|-----------------|--------|----------|---------|-----------------------------------------------------|
+| `projectName` | string | Yes | - | Name of the project that owns this build (min: 1) |
+| `componentName` | string | Yes | - | Name of the component that owns this build (min: 1) |
+
+### Repository
+
+| Field | Type | Required | Default | Description |
+|------------|-----------------------|----------|---------|--------------------------------------------------------------------|
+| `url` | string | Yes | - | Repository URL (e.g., https://github.com/org/repo) |
+| `revision` | [Revision](#revision) | Yes | - | Revision specification for the build |
+| `appPath` | string | Yes | - | Path to the application within the repository (e.g., "." for root) |
+
+### Revision
+
+| Field | Type | Required | Default | Description |
+|----------|--------|----------|---------|-------------------------------------------------------------------|
+| `branch` | string | No | "" | Branch to build from |
+| `commit` | string | No | "" | Specific commit hash to build from (takes precedence over branch) |
+
+### TemplateRef
+
+| Field | Type | Required | Default | Description |
+|--------------|---------------------------|----------|---------|------------------------------------------------------|
+| `engine` | string | No | "" | Build engine to use |
+| `name` | string | Yes | - | Name of the build template (ClusterWorkflowTemplate) |
+| `parameters` | [[Parameter](#parameter)] | No | [] | Template parameters |
+
+### Parameter
+
+| Field | Type | Required | Default | Description |
+|---------|--------|----------|---------|-----------------|
+| `name` | string | Yes | - | Parameter name |
+| `value` | string | Yes | - | Parameter value |
+
+### Status Fields
+
+| Field | Type | Default | Description |
+|---------------|-----------------|---------|---------------------------------------------------------|
+| `conditions` | []Condition | [] | Standard Kubernetes conditions tracking the build state |
+| `imageStatus` | [Image](#image) | {} | Information about the built image |
+
+### Image
+
+| Field | Type | Default | Description |
+|---------|--------|---------|-----------------------------------------------------------|
+| `image` | string | "" | Full image reference including registry, name, and digest |
+
+#### Condition Types
+
+Common condition types for Build resources:
+
+- `Ready` - Indicates if the build has completed successfully
+- `Building` - Indicates if the build is currently in progress
+- `Failed` - Indicates if the build has failed
+
+## Examples
+
+### Build with Docker Template
+
+```yaml
+apiVersion: openchoreo.dev/v1alpha1
+kind: Build
+metadata:
+ name: customer-service-build-abc123
+ namespace: default
+spec:
+ owner:
+ projectName: my-project
+ componentName: customer-service
+ repository:
+ url: https://github.com/myorg/customer-service
+ revision:
+ branch: main
+ commit: abc123def456
+ appPath: .
+ templateRef:
+ name: docker
+ parameters:
+ - name: docker-context
+ value: .
+ - name: dockerfile-path
+ value: ./Dockerfile
+```
+
+### Build with Buildpacks
+
+```yaml
+apiVersion: openchoreo.dev/v1alpha1
+kind: Build
+metadata:
+ name: frontend-build-xyz789
+ namespace: default
+spec:
+ owner:
+ projectName: my-project
+ componentName: frontend-app
+ repository:
+ url: https://github.com/myorg/frontend
+ revision:
+ branch: develop
+ appPath: ./webapp
+ templateRef:
+ name: google-cloud-buildpacks
+```
+
+## Annotations
+
+Builds support the following annotations:
+
+| Annotation | Description |
+|-------------------------------|------------------------------------|
+| `openchoreo.dev/display-name` | Human-readable name for UI display |
+| `openchoreo.dev/description` | Detailed description of the build |
+
+## Related Resources
+
+- [Component](./component.md) - Components that trigger builds
+- [Workload](./workload.md) - Workloads created by successful builds
+- [BuildPlane](../platform/buildplane.md) - Infrastructure where builds execute
diff --git a/versioned_docs/version-v0.5.x/reference/api/application/component.md b/versioned_docs/version-v0.5.x/reference/api/application/component.md
new file mode 100644
index 0000000..585aea4
--- /dev/null
+++ b/versioned_docs/version-v0.5.x/reference/api/application/component.md
@@ -0,0 +1,172 @@
+---
+title: Component API Reference
+---
+
+# Component
+
+A Component represents a deployable unit of an application in OpenChoreo. It serves as the core abstraction that
+defines the component type (Service, WebApplication, ScheduledTask, etc.) and optionally includes build configuration
+when using OpenChoreo's CI system to build from source. Components are the primary building blocks used to define
+applications within a Project.
+
+## API Version
+
+`openchoreo.dev/v1alpha1`
+
+## Resource Definition
+
+### Metadata
+
+Components are namespace-scoped resources that must be created within an Organization's namespace and belong to a
+Project through the owner field.
+
+```yaml
+apiVersion: openchoreo.dev/v1alpha1
+kind: Component
+metadata:
+ name:
+ namespace: # Organization namespace
+```
+
+### Spec Fields
+
+| Field | Type | Required | Default | Description |
+|---------|-----------------------------------------------|----------|---------|--------------------------------------------------------------------------------------------------------|
+| `owner` | [ComponentOwner](#componentowner) | Yes | - | Ownership information linking the component to a project |
+| `type` | [ComponentType](#componenttype) | Yes | - | Specifies the component type (Service, WebApplication, ScheduledTask, etc.) |
+| `build` | [BuildSpecInComponent](#buildspecincomponent) | No | - | Optional build configuration when using OpenChoreo CI to build from source (omit for pre-built images) |
+
+### ComponentOwner
+
+| Field | Type | Required | Default | Description |
+|---------------|--------|----------|---------|-------------------------------------------------------|
+| `projectName` | string | Yes | - | Name of the project that owns this component (min: 1) |
+
+### ComponentType
+
+The component type determines how the component will be deployed and what resources it can create.
+
+| Value | Description |
+|------------------|-------------------------------------|
+| `Service` | Long-running service component |
+| `WebApplication` | Web application with HTTP endpoints |
+| `ScheduledTask` | Scheduled/cron job component |
+
+### BuildSpecInComponent
+
+| Field | Type | Required | Default | Description |
+|---------------|-------------------------------------|----------|---------|-----------------------------------------------------------------------|
+| `repository` | [BuildRepository](#buildrepository) | Yes | - | Source repository configuration where the component code resides |
+| `templateRef` | [TemplateRef](#templateref) | Yes | - | Build template reference (ClusterWorkflowTemplate in the build plane) |
+
+### BuildRepository
+
+| Field | Type | Required | Default | Description |
+|------------|---------------------------------|----------|---------|-----------------------------------------------------------------------------|
+| `url` | string | Yes | - | Repository URL (e.g., https://github.com/org/repo) |
+| `revision` | [BuildRevision](#buildrevision) | Yes | - | Default revision configuration for builds |
+| `appPath` | string | Yes | - | Path to the application within the repository (relative to root, e.g., ".") |
+
+### BuildRevision
+
+| Field | Type | Required | Default | Description |
+|----------|--------|----------|---------|---------------------------------------------------------------|
+| `branch` | string | Yes | - | Default branch to build from when no specific commit provided |
+
+### TemplateRef
+
+| Field | Type | Required | Default | Description |
+|--------------|---------------------------|----------|---------|----------------------------|
+| `engine` | string | No | - | Build engine to use |
+| `name` | string | Yes | - | Name of the build template |
+| `parameters` | [[Parameter](#parameter)] | No | [] | Template parameters |
+
+### Parameter
+
+| Field | Type | Required | Default | Description |
+|---------|--------|----------|---------|-----------------|
+| `name` | string | Yes | - | Parameter name |
+| `value` | string | Yes | - | Parameter value |
+
+### Status Fields
+
+| Field | Type | Default | Description |
+|----------------------|-------------|---------|---------------------------------------------------------|
+| `observedGeneration` | integer | 0 | The generation observed by the controller |
+| `conditions` | []Condition | [] | Standard Kubernetes conditions tracking component state |
+
+#### Condition Types
+
+Common condition types for Component resources:
+
+- `Ready` - Indicates if the component is ready
+- `Reconciled` - Indicates if the controller has successfully reconciled the component
+
+## Examples
+
+### Service Component with Docker Build
+
+```yaml
+apiVersion: openchoreo.dev/v1alpha1
+kind: Component
+metadata:
+ name: customer-service
+ namespace: default
+spec:
+ owner:
+ projectName: my-project
+ type: Service
+ build:
+ repository:
+ url: https://github.com/myorg/customer-service
+ revision:
+ branch: main
+ appPath: .
+ templateRef:
+ name: docker
+ parameters:
+ - name: docker-context
+ value: .
+ - name: dockerfile-path
+ value: ./Dockerfile
+```
+
+### WebApplication Component with Buildpacks
+
+```yaml
+apiVersion: openchoreo.dev/v1alpha1
+kind: Component
+metadata:
+ name: frontend-app
+ namespace: default
+spec:
+ owner:
+ projectName: my-project
+ type: WebApplication
+ build:
+ repository:
+ url: https://github.com/myorg/frontend
+ revision:
+ branch: develop
+ appPath: ./webapp
+ templateRef:
+ name: google-cloud-buildpacks
+```
+
+## Annotations
+
+Components support the following annotations:
+
+| Annotation | Description |
+|-------------------------------|---------------------------------------|
+| `openchoreo.dev/display-name` | Human-readable name for UI display |
+| `openchoreo.dev/description` | Detailed description of the component |
+
+## Related Resources
+
+- [Project](./project.md) - Contains components
+- [Build](./build.md) - Build jobs triggered by components
+- [Workload](./workload.md) - Workload definitions associated with components
+- [Service](./service.md) - Service-type component resources
+- [WebApplication](./webapplication.md) - WebApplication-type component resources
+- [ScheduledTask](./scheduledtask.md) - ScheduledTask-type component resources
diff --git a/versioned_docs/version-v0.5.x/reference/api/application/componentdeployment.md b/versioned_docs/version-v0.5.x/reference/api/application/componentdeployment.md
new file mode 100644
index 0000000..cad0d97
--- /dev/null
+++ b/versioned_docs/version-v0.5.x/reference/api/application/componentdeployment.md
@@ -0,0 +1,297 @@
+---
+title: ComponentDeployment API Reference
+---
+
+# ComponentDeployment
+
+A ComponentDeployment represents an environment-specific deployment of a Component. It allows platform engineers to
+override component parameters, trait configurations, and workload settings for specific environments like development,
+staging, or production.
+
+## API Version
+
+`openchoreo.dev/v1alpha1`
+
+## Resource Definition
+
+### Metadata
+
+ComponentDeployments are namespace-scoped resources created in the same namespace as the Component they deploy.
+
+```yaml
+apiVersion: openchoreo.dev/v1alpha1
+kind: ComponentDeployment
+metadata:
+ name: -
+ namespace:
+```
+
+### Spec Fields
+
+| Field | Type | Required | Default | Description |
+|--------------------------|---------------------------------------------------------|----------|---------|--------------------------------------------------------|
+| `owner` | [ComponentDeploymentOwner](#componentdeploymentowner) | Yes | - | Identifies the component this deployment applies to |
+| `environment` | string | Yes | - | Name of the environment (must match an Environment CR) |
+| `overrides` | object | No | - | Overrides for ComponentType `envOverrides` parameters |
+| `traitOverrides` | map[string]object | No | - | Environment-specific trait parameter overrides |
+| `configurationOverrides` | [EnvConfigurationOverrides](#envconfigurationoverrides) | No | - | Overrides for workload configurations |
+
+### ComponentDeploymentOwner
+
+Identifies which component this deployment is for.
+
+| Field | Type | Required | Description |
+|-----------------|--------|----------|---------------------------------------------|
+| `projectName` | string | Yes | Name of the project that owns the component |
+| `componentName` | string | Yes | Name of the component to deploy |
+
+### EnvConfigurationOverrides
+
+Environment-specific configuration overrides for the workload.
+
+| Field | Type | Required | Description |
+|---------|-----------------------|----------|--------------------------------|
+| `env` | [[EnvVar](#envvar)] | No | Environment variable overrides |
+| `files` | [[FileVar](#filevar)] | No | File configuration overrides |
+
+#### EnvVar
+
+| Field | Type | Required | Description |
+|---------|--------|----------|----------------------------|
+| `name` | string | Yes | Environment variable name |
+| `value` | string | Yes | Environment variable value |
+
+#### FileVar
+
+| Field | Type | Required | Description |
+|-------------|--------|----------|-------------------------|
+| `name` | string | Yes | File name |
+| `mountPath` | string | Yes | Mount path in container |
+| `value` | string | Yes | File content |
+
+### Status Fields
+
+| Field | Type | Default | Description |
+|----------------------|-------------|---------|-------------------------------------------------------------------|
+| `observedGeneration` | integer | 0 | Generation observed by the controller |
+| `conditions` | []Condition | [] | Standard Kubernetes conditions tracking ComponentDeployment state |
+
+#### Condition Types
+
+Common condition types for ComponentDeployment resources:
+
+- `Ready` - Indicates if the deployment is ready
+- `Deployed` - Indicates if resources have been deployed successfully
+- `Synced` - Indicates if the deployment is in sync with the component definition
+
+## Examples
+
+### Basic ComponentDeployment
+
+```yaml
+apiVersion: openchoreo.dev/v1alpha1
+kind: ComponentDeployment
+metadata:
+ name: my-service-production
+ namespace: default
+spec:
+ owner:
+ projectName: default
+ componentName: my-service
+
+ environment: production
+```
+
+### ComponentDeployment with Parameter Overrides
+
+Override ComponentType `envOverrides` parameters for production:
+
+```yaml
+apiVersion: openchoreo.dev/v1alpha1
+kind: ComponentDeployment
+metadata:
+ name: my-service-production
+ namespace: default
+spec:
+ owner:
+ projectName: default
+ componentName: my-service
+
+ environment: production
+
+ overrides:
+ resources:
+ requests:
+ cpu: "500m"
+ memory: "1Gi"
+ limits:
+ cpu: "2000m"
+ memory: "4Gi"
+```
+
+### ComponentDeployment with Trait Overrides
+
+Override trait parameters for a specific environment:
+
+```yaml
+apiVersion: openchoreo.dev/v1alpha1
+kind: ComponentDeployment
+metadata:
+ name: my-service-production
+ namespace: default
+spec:
+ owner:
+ projectName: default
+ componentName: my-service
+
+ environment: production
+
+ traitOverrides:
+ data-storage: # instanceName of the trait attachment
+ size: 100Gi
+ storageClass: production-ssd
+ iops: 3000
+```
+
+### ComponentDeployment with Configuration Overrides
+
+Override workload environment variables and files:
+
+```yaml
+apiVersion: openchoreo.dev/v1alpha1
+kind: ComponentDeployment
+metadata:
+ name: my-service-production
+ namespace: default
+spec:
+ owner:
+ projectName: default
+ componentName: my-service
+
+ environment: production
+
+ configurationOverrides:
+ env:
+ - name: LOG_LEVEL
+ value: "error"
+ - name: CACHE_TTL
+ value: "3600"
+
+ files:
+ - name: config.yaml
+ mountPath: /etc/app
+ value: |
+ database:
+ host: prod-db.example.com
+ port: 5432
+ cache:
+ enabled: true
+```
+
+### Complete ComponentDeployment Example
+
+Combining all override types:
+
+```yaml
+apiVersion: openchoreo.dev/v1alpha1
+kind: ComponentDeployment
+metadata:
+ name: my-service-production
+ namespace: default
+spec:
+ owner:
+ projectName: default
+ componentName: my-service
+
+ environment: production
+
+ # Override ComponentType envOverrides
+ overrides:
+ resources:
+ requests:
+ cpu: "500m"
+ memory: "1Gi"
+ limits:
+ cpu: "2000m"
+ memory: "4Gi"
+
+ # Override trait parameters
+ traitOverrides:
+ data-storage:
+ size: 100Gi
+ storageClass: fast-ssd
+
+ backup:
+ schedule: "0 2 * * *"
+ retention: 30
+
+ # Override workload configurations
+ configurationOverrides:
+ env:
+ - name: LOG_LEVEL
+ value: "info"
+ - name: MAX_CONNECTIONS
+ value: "1000"
+```
+
+## Usage
+
+ComponentDeployments are typically created for each environment where a component should be deployed:
+
+```bash
+# Development environment
+kubectl apply -f my-service-development.yaml
+
+# Staging environment
+kubectl apply -f my-service-staging.yaml
+
+# Production environment
+kubectl apply -f my-service-production.yaml
+```
+
+View component deployments:
+
+```bash
+# List all component deployments
+kubectl get componentdeployments
+
+# Get deployments for a specific component
+kubectl get componentdeployment -l openchoreo.dev/component=my-service
+
+# View deployment details
+kubectl describe componentdeployment my-service-production
+```
+
+## Override Hierarchy
+
+Parameters are resolved in the following order (later overrides earlier):
+
+1. **ComponentType defaults** - Default values from ComponentType schema
+2. **Component parameters** - Values specified in the Component spec
+3. **ComponentDeployment overrides** - Environment-specific values in ComponentDeployment
+
+Example:
+
+```yaml
+# ComponentType defines: replicas default=1
+# Component sets: replicas=3
+# ComponentDeployment (prod) overrides: replicas=5
+# Result: Production deployment will have 5 replicas
+```
+
+## Best Practices
+
+1. **Naming Convention**: Use `-` pattern
+2. **Environment-Specific Values**: Only override what differs between environments
+3. **Resource Limits**: Always set appropriate limits for production environments
+4. **Configuration Management**: Use ConfigMaps/Secrets for complex configurations
+5. **Trait Management**: Override trait parameters rather than removing/adding traits
+6. **Testing**: Validate overrides in lower environments before production
+7. **Documentation**: Document why specific overrides are needed
+
+## Related Resources
+
+- [Component](component.md) - Defines the component being deployed
+- [Environment](../platform/environment.md) - Defines the target environment
+- [ComponentType](../platform/componenttype.md) - Defines available parameters for override
+- [Trait](../platform/trait.md) - Traits whose parameters can be overridden
diff --git a/versioned_docs/version-v0.5.x/reference/api/application/project.md b/versioned_docs/version-v0.5.x/reference/api/application/project.md
new file mode 100644
index 0000000..a7f61ab
--- /dev/null
+++ b/versioned_docs/version-v0.5.x/reference/api/application/project.md
@@ -0,0 +1,82 @@
+---
+title: Project API Reference
+---
+
+# Project
+
+A Project represents a cloud-native application composed of multiple components in OpenChoreo. It serves as the
+fundamental unit of isolation and provides a logical boundary for organizing related components, services, and
+resources.
+
+## API Version
+
+`openchoreo.dev/v1alpha1`
+
+## Resource Definition
+
+### Metadata
+
+Projects are namespace-scoped resources that must be created within an Organization's namespace.
+
+```yaml
+apiVersion: openchoreo.dev/v1alpha1
+kind: Project
+metadata:
+ name:
+ namespace: # Organization namespace
+```
+
+### Spec Fields
+
+| Field | Type | Required | Default | Description |
+|-------------------------|--------|----------|---------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `deploymentPipelineRef` | string | Yes | - | Reference to the DeploymentPipeline that defines the promotion paths between environments for this project. Must reference an existing DeploymentPipeline in the same namespace |
+
+### Status Fields
+
+| Field | Type | Default | Description |
+|----------------------|-------------|---------|-----------------------------------------------------------|
+| `observedGeneration` | integer | 0 | The generation observed by the controller |
+| `conditions` | []Condition | [] | Standard Kubernetes conditions tracking the project state |
+
+#### Condition Types
+
+Common condition types for Project resources:
+
+- `Ready` - Indicates if the project is fully provisioned and ready
+- `Reconciled` - Indicates if the controller has successfully reconciled the project
+- `NamespaceProvisioned` - Indicates if project namespaces have been created in all environments
+
+## Examples
+
+### Basic Project
+
+A simple project referencing the default deployment pipeline:
+
+```yaml
+apiVersion: openchoreo.dev/v1alpha1
+kind: Project
+metadata:
+ name: internal-apps
+ namespace: default
+ annotations:
+ openchoreo.dev/display-name: Internal Applications
+ openchoreo.dev/description: This project contains components that are used by company's internal applications
+spec:
+ deploymentPipelineRef: default-deployment-pipeline
+```
+
+## Annotations
+
+Projects support the following annotations:
+
+| Annotation | Description |
+|-------------------------------|-------------------------------------|
+| `openchoreo.dev/display-name` | Human-readable name for UI display |
+| `openchoreo.dev/description` | Detailed description of the project |
+
+## Related Resources
+
+- [Component](./component.md) - Deployable units within projects
+- [DeploymentPipeline](../platform/deployment-pipeline.md) - Defines environment promotion paths
+- [Organization](../platform/organization.md) - Contains projects
diff --git a/versioned_docs/version-v0.5.x/reference/api/application/scheduledtask.md b/versioned_docs/version-v0.5.x/reference/api/application/scheduledtask.md
new file mode 100644
index 0000000..18f9095
--- /dev/null
+++ b/versioned_docs/version-v0.5.x/reference/api/application/scheduledtask.md
@@ -0,0 +1,98 @@
+---
+title: ScheduledTask API Reference (Deprecated)
+---
+
+# ScheduledTask
+
+:::warning Deprecated
+ScheduledTask is deprecated as of OpenChoreo v0.4.0 and will be removed in a future version.
+Use [Component](component.md) with [ComponentType](../platform/componenttype.md) and [ComponentDeployment](componentdeployment.md) instead for a more flexible deployment model.
+:::
+
+A ScheduledTask represents a scheduled or cron job component in OpenChoreo. It defines the deployment configuration for
+scheduled task-type components by referencing a Workload and optionally a ScheduledTaskClass for platform-defined
+policies. ScheduledTasks are used for batch processing, periodic maintenance, or any workload that runs on a schedule.
+
+## API Version
+
+`openchoreo.dev/v1alpha1`
+
+## Resource Definition
+
+### Metadata
+
+ScheduledTasks are namespace-scoped resources that must be created within an Organization's namespace and belong to a
+Component through the owner field.
+
+```yaml
+apiVersion: openchoreo.dev/v1alpha1
+kind: ScheduledTask
+metadata:
+ name:
+ namespace: # Organization namespace
+```
+
+### Spec Fields
+
+| Field | Type | Required | Default | Description |
+|----------------|--------------------------------------------------|----------|-----------|------------------------------------------------------------------------------|
+| `owner` | [ScheduledTaskOwner](#scheduledtaskowner) | Yes | - | Ownership information linking the scheduled task to a project and component |
+| `workloadName` | string | Yes | - | Name of the workload that this scheduled task references |
+| `className` | string | No | "default" | Name of the ScheduledTaskClass that provides deployment configuration |
+
+### ScheduledTaskOwner
+
+| Field | Type | Required | Default | Description |
+|-----------------|--------|----------|---------|---------------------------------------------------------------|
+| `projectName` | string | Yes | - | Name of the project that owns this scheduled task (min: 1) |
+| `componentName` | string | Yes | - | Name of the component that owns this scheduled task (min: 1) |
+
+## Examples
+
+### Basic ScheduledTask
+
+```yaml
+apiVersion: openchoreo.dev/v1alpha1
+kind: ScheduledTask
+metadata:
+ name: data-cleanup-job
+ namespace: default
+spec:
+ owner:
+ projectName: my-project
+ componentName: data-cleanup
+ workloadName: data-cleanup-workload
+ className: default
+```
+
+### ScheduledTask with Custom Class
+
+```yaml
+apiVersion: openchoreo.dev/v1alpha1
+kind: ScheduledTask
+metadata:
+ name: report-generator
+ namespace: default
+spec:
+ owner:
+ projectName: my-project
+ componentName: reporting
+ workloadName: report-generator-workload
+ className: hourly-batch-job
+```
+
+## Annotations
+
+ScheduledTasks support the following annotations:
+
+| Annotation | Description |
+|-------------------------------|------------------------------------------|
+| `openchoreo.dev/display-name` | Human-readable name for UI display |
+| `openchoreo.dev/description` | Detailed description of the scheduled task |
+
+## Related Resources
+
+- [Component](./component.md) - Components that own scheduled tasks
+- [Workload](./workload.md) - Workloads referenced by scheduled tasks
+- [ScheduledTaskClass](../platform/scheduledtaskclass.md) - Platform-defined scheduled task templates
+- [ScheduledTaskBinding](../runtime/scheduledtaskbinding.md) - Environment-specific scheduled task instances
\ No newline at end of file
diff --git a/versioned_docs/version-v0.5.x/reference/api/application/service.md b/versioned_docs/version-v0.5.x/reference/api/application/service.md
new file mode 100644
index 0000000..b3d04f6
--- /dev/null
+++ b/versioned_docs/version-v0.5.x/reference/api/application/service.md
@@ -0,0 +1,152 @@
+---
+title: Service API Reference (Deprecated)
+---
+
+# Service
+
+:::warning Deprecated
+Service is deprecated as of OpenChoreo v0.4.0 and will be removed in a future version.
+Use [Component](component.md) with [ComponentType](../platform/componenttype.md) and [ComponentDeployment](componentdeployment.md) instead for a more flexible deployment model.
+:::
+
+A Service represents a long-running service component in OpenChoreo. It defines the deployment configuration for
+service-type components by referencing a Workload and optionally a ServiceClass for platform-defined policies.
+Services can expose APIs with different access levels and integrate with OpenChoreo's API management capabilities.
+
+## API Version
+
+`openchoreo.dev/v1alpha1`
+
+## Resource Definition
+
+### Metadata
+
+Services are namespace-scoped resources that must be created within an Organization's namespace and belong to a
+Component through the owner field.
+
+```yaml
+apiVersion: openchoreo.dev/v1alpha1
+kind: Service
+metadata:
+ name:
+ namespace: # Organization namespace
+```
+
+### Spec Fields
+
+| Field | Type | Required | Default | Description |
+|----------------|-----------------------------------------|----------|-----------|-----------------------------------------------------------------------------------|
+| `owner` | [ServiceOwner](#serviceowner) | Yes | - | Ownership information linking the service to a project and component |
+| `workloadName` | string | Yes | - | Name of the workload that this service references |
+| `className` | string | No | "default" | Name of the ServiceClass that provides deployment configuration |
+| `apis` | map[string][ServiceAPI](#serviceapi) | No | {} | API configuration for endpoints. Keys must match endpoint keys in the workload |
+
+### ServiceOwner
+
+| Field | Type | Required | Default | Description |
+|-----------------|--------|----------|---------|--------------------------------------------------------|
+| `projectName` | string | Yes | - | Name of the project that owns this service (min: 1) |
+| `componentName` | string | Yes | - | Name of the component that owns this service (min: 1) |
+
+### ServiceAPI
+
+| Field | Type | Required | Default | Description |
+|---------------|-------------------------------------|----------|-----------|--------------------------------------------------------|
+| `className` | string | No | "default" | API class name for management policies |
+| `type` | [EndpointType](#endpointtype) | Yes | - | Type of the API endpoint |
+| `rest` | [RESTEndpoint](#restendpoint) | No | - | REST-specific endpoint configuration |
+
+### EndpointType
+
+| Value | Description |
+|-------------|------------------------------------------------|
+| `HTTP` | Standard HTTP endpoint |
+| `REST` | RESTful API endpoint |
+| `gRPC` | gRPC service endpoint |
+| `GraphQL` | GraphQL API endpoint |
+| `Websocket` | WebSocket endpoint |
+| `TCP` | Raw TCP endpoint |
+| `UDP` | UDP endpoint |
+
+### RESTEndpoint
+
+| Field | Type | Required | Default | Description |
+|----------------|-------------------------------------------------------------|----------|---------|------------------------------------------------|
+| `backend` | [HTTPBackend](#httpbackend) | No | - | Backend configuration for the REST endpoint |
+| `exposeLevels` | [[RESTOperationExposeLevel](#restoperationexposelevel)] | No | [] | Access levels for the REST API |
+
+### HTTPBackend
+
+| Field | Type | Required | Default | Description |
+|------------|--------|----------|---------|--------------------------------------------------------|
+| `port` | int32 | Yes | - | Port number where the backend service is listening |
+| `basePath` | string | No | "" | Base path for the API (e.g., "/api/v1") |
+
+### RESTOperationExposeLevel
+
+| Value | Description |
+|----------------|------------------------------------------------------------------|
+| `Project` | API accessible only within the same project |
+| `Organization` | API accessible within the organization |
+| `Public` | API publicly accessible (subject to authentication/authorization) |
+
+## Examples
+
+### Basic Service
+
+```yaml
+apiVersion: openchoreo.dev/v1alpha1
+kind: Service
+metadata:
+ name: customer-service
+ namespace: default
+spec:
+ owner:
+ projectName: my-project
+ componentName: customer-service
+ workloadName: customer-service-workload
+ className: default
+```
+
+### Service with API Configuration
+
+```yaml
+apiVersion: openchoreo.dev/v1alpha1
+kind: Service
+metadata:
+ name: order-service
+ namespace: default
+spec:
+ owner:
+ projectName: my-project
+ componentName: order-service
+ workloadName: order-service-workload # References workload with endpoint "order-api"
+ className: production-service
+ apis:
+ order-api: # Must match endpoint key "order-api" in the workload
+ className: default
+ type: REST
+ rest:
+ backend:
+ port: 8080
+ basePath: /api/v1
+ exposeLevels:
+ - Organization
+ - Public
+```
+
+## Annotations
+
+Services support the following annotations:
+
+| Annotation | Description |
+|-------------------------------|-------------------------------------|
+| `openchoreo.dev/display-name` | Human-readable name for UI display |
+| `openchoreo.dev/description` | Detailed description of the service |
+
+## Related Resources
+
+- [Component](./component.md) - Components that own services
+- [Workload](./workload.md) - Workloads referenced by services
+- [ServiceClass](../platform/serviceclass.md) - Platform-defined service templates
+- [ServiceBinding](../runtime/servicebinding.md) - Environment-specific service instances
\ No newline at end of file
diff --git a/versioned_docs/version-v0.5.x/reference/api/application/webapplication.md b/versioned_docs/version-v0.5.x/reference/api/application/webapplication.md
new file mode 100644
index 0000000..698dcd3
--- /dev/null
+++ b/versioned_docs/version-v0.5.x/reference/api/application/webapplication.md
@@ -0,0 +1,98 @@
+---
+title: WebApplication API Reference (Deprecated)
+---
+
+# WebApplication
+
+:::warning Deprecated
+WebApplication is deprecated as of OpenChoreo v0.4.0 and will be removed in a future version.
+Use [Component](component.md) with [ComponentType](../platform/componenttype.md) and [ComponentDeployment](componentdeployment.md) instead for a more flexible deployment model.
+:::
+
+A WebApplication represents a web application component in OpenChoreo. It defines the deployment configuration for
+web application-type components by referencing a Workload and optionally a WebApplicationClass for platform-defined
+policies. WebApplications are typically frontend applications or web services that serve HTTP content.
+
+## API Version
+
+`openchoreo.dev/v1alpha1`
+
+## Resource Definition
+
+### Metadata
+
+WebApplications are namespace-scoped resources that must be created within an Organization's namespace and belong to a
+Component through the owner field.
+
+```yaml
+apiVersion: openchoreo.dev/v1alpha1
+kind: WebApplication
+metadata:
+ name:
+ namespace: # Organization namespace
+```
+
+### Spec Fields
+
+| Field | Type | Required | Default | Description |
+|----------------|---------------------------------------------------|----------|-----------|--------------------------------------------------------------------------------|
+| `owner` | [WebApplicationOwner](#webapplicationowner) | Yes | - | Ownership information linking the web application to a project and component |
+| `workloadName` | string | Yes | - | Name of the workload that this web application references |
+| `className` | string | No | "default" | Name of the WebApplicationClass that provides deployment configuration |
+
+### WebApplicationOwner
+
+| Field | Type | Required | Default | Description |
+|-----------------|--------|----------|---------|----------------------------------------------------------------|
+| `projectName` | string | Yes | - | Name of the project that owns this web application (min: 1) |
+| `componentName` | string | Yes | - | Name of the component that owns this web application (min: 1) |
+
+## Examples
+
+### Basic WebApplication
+
+```yaml
+apiVersion: openchoreo.dev/v1alpha1
+kind: WebApplication
+metadata:
+ name: frontend-app
+ namespace: default
+spec:
+ owner:
+ projectName: my-project
+ componentName: frontend
+ workloadName: frontend-workload
+ className: default
+```
+
+### WebApplication with Custom Class
+
+```yaml
+apiVersion: openchoreo.dev/v1alpha1
+kind: WebApplication
+metadata:
+ name: admin-dashboard
+ namespace: default
+spec:
+ owner:
+ projectName: my-project
+ componentName: admin-ui
+ workloadName: admin-ui-workload
+ className: production-webapp
+```
+
+## Annotations
+
+WebApplications support the following annotations:
+
+| Annotation | Description |
+|-------------------------------|-------------------------------------------|
+| `openchoreo.dev/display-name` | Human-readable name for UI display |
+| `openchoreo.dev/description` | Detailed description of the web application |
+
+## Related Resources
+
+- [Component](./component.md) - Components that own web applications
+- [Workload](./workload.md) - Workloads referenced by web applications
+- [WebApplicationClass](../platform/webapplicationclass.md) - Platform-defined web application templates
+- [WebApplicationBinding](../runtime/webapplicationbinding.md) - Environment-specific web application instances
\ No newline at end of file
diff --git a/versioned_docs/version-v0.5.x/reference/api/application/workload.md b/versioned_docs/version-v0.5.x/reference/api/application/workload.md
new file mode 100644
index 0000000..41c4af1
--- /dev/null
+++ b/versioned_docs/version-v0.5.x/reference/api/application/workload.md
@@ -0,0 +1,253 @@
+---
+title: Workload API Reference
+---
+
+# Workload
+
+A Workload defines the runtime specification for a Component in OpenChoreo, including container configurations,
+network endpoints, and connections to other services. It represents the actual deployment characteristics of a
+component, specifying what containers to run, what ports to expose, and what dependencies to inject. Workloads are
+created automatically by build processes or can be defined manually for pre-built images.
+
+## API Version
+
+`openchoreo.dev/v1alpha1`
+
+## Resource Definition
+
+### Metadata
+
+Workloads are namespace-scoped resources that must be created within an Organization's namespace and belong to a
+Component through the owner field.
+
+```yaml
+apiVersion: openchoreo.dev/v1alpha1
+kind: Workload
+metadata:
+ name:
+ namespace: # Organization namespace
+```
+
+### Spec Fields
+
+| Field | Type | Required | Default | Description |
+|---------------|------------------------------------------------------|----------|---------|--------------------------------------------------------------------------------------------------------|
+| `owner` | [WorkloadOwner](#workloadowner) | Yes | - | Ownership information linking the workload to a project and component |
+| `containers` | map[string][Container](#container) | Yes | - | Container specifications keyed by container name. Must have at least one container with the key "main" |
+| `endpoints` | map[string][WorkloadEndpoint](#workloadendpoint) | No | {} | Network endpoints for port exposure keyed by endpoint name |
+| `connections` | map[string][WorkloadConnection](#workloadconnection) | No | {} | Connections to internal/external resources keyed by connection name |
+
+### WorkloadOwner
+
+| Field | Type | Required | Default | Description |
+|-----------------|--------|----------|---------|--------------------------------------------------------|
+| `projectName` | string | Yes | - | Name of the project that owns this workload (min: 1) |
+| `componentName` | string | Yes | - | Name of the component that owns this workload (min: 1) |
+
+### Container
+
+| Field | Type | Required | Default | Description |
+|-----------|---------------------|----------|---------|------------------------------------------|
+| `image` | string | Yes | - | OCI image to run (digest or tag, min: 1) |
+| `command` | []string | No | [] | Container entrypoint |
+| `args` | []string | No | [] | Arguments for the entrypoint |
+| `env` | [[EnvVar](#envvar)] | No | [] | Environment variables |
+| `files` | [[File](#file)] | No | [] | File configurations and secrets |
+
+### EnvVar
+
+| Field | Type | Required | Default | Description |
+|----------------|---------------------------------|----------|---------|---------------------------------------------------------|
+| `key` | string | Yes | - | Environment variable name |
+| `value` | string | No | - | Environment variable value (required if secretKeyRef is not set) |
+| `secretKeyRef` | [SecretKeyRef](#secretkeyref) | No | - | Reference to a secret key (required if value is not set) |
+
+### File
+
+| Field | Type | Required | Default | Description |
+|----------------|---------------------------------|----------|---------|---------------------------------------------------------|
+| `key` | string | Yes | - | File name |
+| `mountPath` | string | Yes | - | Path where the file should be mounted |
+| `value` | string | No | - | File content (required if secretKeyRef is not set) |
+| `secretKeyRef` | [SecretKeyRef](#secretkeyref) | No | - | Reference to a secret key (required if value is not set) |
+
+### SecretKeyRef
+
+| Field | Type | Required | Default | Description |
+|---------|--------|----------|---------|------------------------|
+| `name` | string | Yes | - | Name of the secret |
+| `key` | string | Yes | - | Key within the secret |
+
+### WorkloadEndpoint
+
+| Field | Type | Required | Default | Description |
+|----------|-------------------------------|----------|---------|------------------------------------------|
+| `type` | [EndpointType](#endpointtype) | Yes | - | Protocol/technology of the endpoint |
+| `port` | int32 | Yes | - | Port number for the endpoint (1-65535) |
+| `schema` | [Schema](#schema) | No | - | Optional API definition for the endpoint |
+
+### EndpointType
+
+| Value | Description |
+|-------------|------------------------|
+| `HTTP` | Standard HTTP endpoint |
+| `REST` | RESTful API endpoint |
+| `gRPC` | gRPC service endpoint |
+| `GraphQL` | GraphQL API endpoint |
+| `Websocket` | WebSocket endpoint |
+| `TCP` | Raw TCP endpoint |
+| `UDP` | UDP endpoint |
+
+### Schema
+
+| Field | Type | Required | Default | Description |
+|-----------|--------|----------|---------|---------------------------------|
+| `content` | string | No | "" | Schema content (API definition) |
+
+### WorkloadConnection
+
+| Field | Type | Required | Default | Description |
+|----------|-------------------------------------------------------|----------|---------|-----------------------------------------------------------------------|
+| `type` | string | Yes | - | Type of connection (currently only "api" supported) |
+| `params` | map[string]string | No | {} | Connection configuration parameters (depends on connection type) |
+| `inject` | [WorkloadConnectionInject](#workloadconnectioninject) | Yes | - | Defines how connection details are injected (currently only env vars) |
+
+### WorkloadConnectionInject
+
+| Field | Type | Required | Default | Description |
+|-------|---------------------------------------------------------|----------|---------|---------------------------------|
+| `env` | [[WorkloadConnectionEnvVar](#workloadconnectionenvvar)] | Yes | - | Environment variables to inject |
+
+### WorkloadConnectionEnvVar
+
+| Field | Type | Required | Default | Description |
+|---------|--------|----------|---------|-----------------------------------------------------------------|
+| `name` | string | Yes | - | Environment variable name |
+| `value` | string | Yes | - | Template value using connection properties (e.g., `{{ .url }}`) |
+
+## Examples
+
+### Basic Service Workload
+
+```yaml
+apiVersion: openchoreo.dev/v1alpha1
+kind: Workload
+metadata:
+ name: customer-service-workload
+ namespace: default
+spec:
+ owner:
+ projectName: my-project
+ componentName: customer-service
+ containers:
+ main:
+ image: myregistry/customer-service:v1.0.0
+ env:
+ - key: LOG_LEVEL
+ value: info
+ endpoints:
+ http:
+ type: REST
+ port: 8080
+ metrics:
+ type: HTTP
+ port: 9090
+```
+
+### Workload with Environment Variables and Files
+
+```yaml
+apiVersion: openchoreo.dev/v1alpha1
+kind: Workload
+metadata:
+ name: secure-service-workload
+ namespace: default
+spec:
+ owner:
+ projectName: my-project
+ componentName: secure-service
+ containers:
+ main:
+ image: myregistry/secure-service:v1.0.0
+ env:
+ - key: LOG_LEVEL
+ value: info
+ - key: GIT_PAT
+ secretKeyRef:
+ name: git-secrets
+ key: pat
+ files:
+ - key: ssl.pem
+ mountPath: /tmp
+ secretKeyRef:
+ name: certificates
+ key: privateKey
+ - key: application.toml
+ mountPath: /tmp
+ value: |
+ schema_generation:
+ enable: true
+ endpoints:
+ api:
+ type: REST
+ port: 8080
+```
+
+### Workload with Connections
+
+```yaml
+apiVersion: openchoreo.dev/v1alpha1
+kind: Workload
+metadata:
+ name: order-service-workload
+ namespace: default
+spec:
+ owner:
+ projectName: my-project
+ componentName: order-service
+ containers:
+ main:
+ image: myregistry/order-service:v2.1.0
+ command: [ "/app/server" ]
+ args: [ "--config", "/etc/config.yaml" ]
+ endpoints:
+ api:
+ type: REST
+ port: 8080
+ schema:
+ content: |
+ openapi: 3.0.0
+ info:
+ title: Order API
+ version: 1.0.0
+ connections:
+ database:
+ type: api
+ params:
+ service: postgres-db
+ inject:
+ env:
+ - name: DATABASE_URL
+ value: "{{ .url }}"
+ - name: DB_HOST
+ value: "{{ .host }}"
+ - name: DB_PORT
+ value: "{{ .port }}"
+```
+
+## Annotations
+
+Workloads support the following annotations:
+
+| Annotation | Description |
+|-------------------------------|--------------------------------------|
+| `openchoreo.dev/display-name` | Human-readable name for UI display |
+| `openchoreo.dev/description` | Detailed description of the workload |
+
+## Related Resources
+
+- [Component](./component.md) - Components that own workloads
+- [Service](./service.md) - Service resources that reference workloads
+- [WebApplication](./webapplication.md) - WebApplication resources that reference workloads
+- [ScheduledTask](./scheduledtask.md) - ScheduledTask resources that reference workloads
+- [Build](./build.md) - Build jobs that create workloads
diff --git a/versioned_docs/version-v0.5.x/reference/api/platform/buildplane.md b/versioned_docs/version-v0.5.x/reference/api/platform/buildplane.md
new file mode 100644
index 0000000..a17acef
--- /dev/null
+++ b/versioned_docs/version-v0.5.x/reference/api/platform/buildplane.md
@@ -0,0 +1,102 @@
+---
+title: BuildPlane API Reference
+---
+
+# BuildPlane
+
+A BuildPlane represents the infrastructure layer responsible for executing build workloads in OpenChoreo. It provides
+the necessary compute resources and configuration for running CI/CD pipelines, typically using Argo Workflows or similar
+build orchestration systems. Each BuildPlane is associated with a specific Kubernetes cluster where build jobs are
+executed.
+
+## API Version
+
+`openchoreo.dev/v1alpha1`
+
+## Resource Definition
+
+### Metadata
+
+BuildPlanes are namespace-scoped resources that must be created within an Organization's namespace.
+
+```yaml
+apiVersion: openchoreo.dev/v1alpha1
+kind: BuildPlane
+metadata:
+ name:
+ namespace: # Organization namespace
+```
+
+### Spec Fields
+
+| Field | Type | Required | Default | Description |
+|---------------------|-------------------------------------------------|----------|---------|----------------------------------------------------------------------------------------------------|
+| `kubernetesCluster` | [KubernetesClusterSpec](#kubernetesclusterspec) | Yes | - | Defines the Kubernetes cluster where build workloads (e.g., Argo Workflows) will be executed |
+| `observer` | [ObserverAPI](#observerapi) | No | - | Configuration for the Observer API integration for monitoring and observability of build processes |
+
+### KubernetesClusterSpec
+
+| Field | Type | Required | Default | Description |
+|----------------------------|--------|----------|---------|--------------------------------------------|
+| `name` | string | Yes | - | Name identifier for the Kubernetes cluster |
+| `credentials.apiServerURL` | string | Yes | - | URL of the Kubernetes API server |
+| `credentials.caCert` | string | Yes | - | Base64-encoded CA certificate |
+| `credentials.clientCert` | string | Yes | - | Base64-encoded client certificate |
+| `credentials.clientKey` | string | Yes | - | Base64-encoded client private key |
+
+### ObserverAPI
+
+| Field | Type | Required | Default | Description |
+|-------------------------------------|--------|----------|---------|-----------------------------------|
+| `url` | string | Yes | - | Base URL of the Observer API |
+| `authentication.basicAuth.username` | string | Yes | - | Username for basic authentication |
+| `authentication.basicAuth.password` | string | Yes | - | Password for basic authentication |
+
+### Status Fields
+
+The BuildPlane status is currently minimal, with fields reserved for future use.
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------------------------------------|
+| - | - | - | Status fields are reserved for future use |
+
+## Examples
+
+### Basic BuildPlane
+
+```yaml
+apiVersion: openchoreo.dev/v1alpha1
+kind: BuildPlane
+metadata:
+ name: primary-buildplane
+ namespace: default
+spec:
+ kubernetesCluster:
+ name: build-cluster-1
+ credentials:
+ apiServerURL: https://api.build-cluster.example.com:6443
+ caCert: LS0tLS1CRUdJTi... # Base64-encoded CA cert
+ clientCert: LS0tLS1CRUdJTi... # Base64-encoded client cert
+ clientKey: LS0tLS1CRUdJTi... # Base64-encoded client key
+ observer:
+ url: https://observer.example.com
+ authentication:
+ basicAuth:
+ username: admin
+ password: secretpassword
+```
+
+## Annotations
+
+BuildPlanes support the following annotations:
+
+| Annotation | Description |
+|-------------------------------|----------------------------------------|
+| `openchoreo.dev/display-name` | Human-readable name for UI display |
+| `openchoreo.dev/description` | Detailed description of the BuildPlane |
+
+## Related Resources
+
+- [Build](../application/build.md) - Build job definitions that execute on BuildPlanes
+- [Component](../application/component.md) - Application components that trigger builds
+- [Organization](./organization.md) - Organizational context for BuildPlanes
diff --git a/versioned_docs/version-v0.5.x/reference/api/platform/componenttype.md b/versioned_docs/version-v0.5.x/reference/api/platform/componenttype.md
new file mode 100644
index 0000000..da7c315
--- /dev/null
+++ b/versioned_docs/version-v0.5.x/reference/api/platform/componenttype.md
@@ -0,0 +1,287 @@
+---
+title: ComponentType API Reference
+---
+
+# ComponentType
+
+A ComponentType is a platform-defined template that determines how components are deployed and what resources are
+generated for them. ComponentTypes enable platform engineers to create reusable deployment patterns with configurable
+parameters, replacing the fixed component classes from previous versions.
+
+## API Version
+
+`openchoreo.dev/v1alpha1`
+
+## Resource Definition
+
+### Metadata
+
+ComponentTypes are namespace-scoped resources typically created in an Organization's namespace to be available for
+components in that organization.
+
+```yaml
+apiVersion: openchoreo.dev/v1alpha1
+kind: ComponentType
+metadata:
+ name:
+ namespace: # Organization namespace
+```
+
+### Spec Fields
+
+| Field | Type | Required | Default | Description |
+|--------------------|---------------------------------------------|----------|---------|----------------------------------------------------------------------|
+| `workloadType` | string | Yes | - | Primary workload type: `deployment`, `statefulset`, `cronjob`, `job` |
+| `allowedWorkflows` | [[AllowedWorkflow](#allowedworkflow)] | No | [] | Workflows that developers can use for building this component type |
+| `schema` | [ComponentTypeSchema](#componenttypeschema) | No | - | Configurable parameters for components of this type |
+| `resources` | [[ResourceTemplate](#resourcetemplate)] | Yes | - | Templates for generating Kubernetes resources |
+
+:::note
+The `workloadType` field is immutable after creation and determines the primary resource type for components of this
+type.
+:::
+
+### ComponentTypeSchema
+
+Defines the configurable parameters that developers can set when creating components of this type.
+
+| Field | Type | Required | Default | Description |
+|----------------|--------|----------|---------|----------------------------------------------------------------|
+| `types` | object | No | - | Reusable type definitions referenced in parameters |
+| `parameters` | object | No | - | Static parameters exposed to developers (same across all envs) |
+| `envOverrides` | object | No | - | Parameters that can be overridden per environment |
+
+#### Parameter Schema Syntax
+
+Parameters use inline schema syntax with pipe-separated modifiers:
+
+```
+fieldName: "type | default=value | required=true | enum=val1,val2"
+```
+
+Supported types: `string`, `integer`, `boolean`, `array`, custom type references
+
+**Example:**
+
+```yaml
+schema:
+ types:
+ Resources:
+ cpu: "string | default=100m"
+ memory: "string | default=256Mi"
+
+ parameters:
+ replicas: "integer | default=1"
+ port: "integer | default=8080"
+ imagePullPolicy: "string | default=IfNotPresent | enum=Always,IfNotPresent,Never"
+
+ envOverrides:
+ resources:
+ requests: Resources
+ limits: Resources
+```
+
+### ResourceTemplate
+
+Defines a template for generating Kubernetes resources with CEL expressions for dynamic values.
+
+| Field | Type | Required | Default | Description |
+|---------------|--------|----------|---------|------------------------------------------------------------|
+| `id` | string | Yes | - | Unique identifier (must match `workloadType` for primary) |
+| `includeWhen` | string | No | - | CEL expression determining if resource should be created |
+| `forEach` | string | No | - | CEL expression for generating multiple resources from list |
+| `var` | string | No | - | Variable name for `forEach` iterations |
+| `template` | object | Yes | - | Kubernetes resource template with CEL expressions |
+
+#### CEL Expression Syntax
+
+Templates use CEL expressions enclosed in `${...}` that have access to:
+
+- `metadata.*` - Component metadata (name, namespace, labels, podSelectors)
+- `parameters.*` - ComponentType parameters
+- `workload.*` - Workload specification (containers, volumes)
+- `configurations.*` - Configuration and secret references
+- `environment.*` - Environment information
+- `dataplane.*` - DataPlane configuration
+- OpenChoreo helper functions: `oc_generate_name()`, `oc_hash()`, `oc_omit()`
+
+### AllowedWorkflow
+
+References a Workflow CR that developers can use for building components of this type.
+
+| Field | Type | Required | Description |
+|--------|--------|----------|----------------------|
+| `name` | string | Yes | Name of the Workflow |
+
+## Examples
+
+### Basic HTTP Service ComponentType
+
+```yaml
+apiVersion: openchoreo.dev/v1alpha1
+kind: ComponentType
+metadata:
+ name: service
+ namespace: default
+spec:
+ workloadType: deployment
+
+ schema:
+ parameters:
+ replicas: "integer | default=1"
+ port: "integer | default=80"
+ exposed: "boolean | default=false"
+
+ resources:
+ - id: deployment
+ template:
+ apiVersion: apps/v1
+ kind: Deployment
+ metadata:
+ name: ${metadata.name}
+ namespace: ${metadata.namespace}
+ spec:
+ replicas: ${parameters.replicas}
+ selector:
+ matchLabels: ${metadata.podSelectors}
+ template:
+ metadata:
+ labels: ${metadata.podSelectors}
+ spec:
+ containers:
+ - name: main
+ image: ${workload.containers["main"].image}
+ ports:
+ - containerPort: ${parameters.port}
+
+ - id: service
+ template:
+ apiVersion: v1
+ kind: Service
+ metadata:
+ name: ${metadata.componentName}
+ namespace: ${metadata.namespace}
+ spec:
+ selector: ${metadata.podSelectors}
+ ports:
+ - port: 80
+ targetPort: ${parameters.port}
+
+ - id: httproute
+ includeWhen: ${parameters.exposed == true}
+ template:
+ apiVersion: gateway.networking.k8s.io/v1
+ kind: HTTPRoute
+ metadata:
+ name: ${metadata.name}
+ namespace: ${metadata.namespace}
+ spec:
+ parentRefs:
+ - name: gateway-external
+ namespace: openchoreo-data-plane
+ hostnames:
+ - ${metadata.name}-${environment.name}.${environment.vhost}
+ rules:
+ - backendRefs:
+ - name: ${metadata.componentName}
+ port: 80
+```
+
+### Scheduled Task ComponentType
+
+```yaml
+apiVersion: openchoreo.dev/v1alpha1
+kind: ComponentType
+metadata:
+ name: scheduled-task
+ namespace: default
+spec:
+ workloadType: cronjob
+
+ schema:
+ parameters:
+ schedule: "string | required=true"
+ concurrencyPolicy: "string | default=Forbid | enum=Allow,Forbid,Replace"
+
+ resources:
+ - id: cronjob
+ template:
+ apiVersion: batch/v1
+ kind: CronJob
+ metadata:
+ name: ${metadata.name}
+ namespace: ${metadata.namespace}
+ spec:
+ schedule: ${parameters.schedule}
+ concurrencyPolicy: ${parameters.concurrencyPolicy}
+ jobTemplate:
+ spec:
+ template:
+ spec:
+ containers:
+ - name: main
+ image: ${workload.containers["main"].image}
+ restartPolicy: OnFailure
+```
+
+### ComponentType with Resource Iteration
+
+```yaml
+apiVersion: openchoreo.dev/v1alpha1
+kind: ComponentType
+metadata:
+ name: multi-config-service
+ namespace: default
+spec:
+ workloadType: deployment
+
+ resources:
+ - id: deployment
+ template:
+ # ... deployment spec ...
+
+ - id: file-config
+ includeWhen: ${has(configurations.configs.files) && configurations.configs.files.size() > 0}
+ forEach: ${configurations.configs.files}
+ var: config
+ template:
+ apiVersion: v1
+ kind: ConfigMap
+ metadata:
+ name: ${metadata.name}-${config.name}
+ namespace: ${metadata.namespace}
+ data:
+ ${config.name}: ${config.value}
+```
+
+## Usage
+
+Components reference a ComponentType using the `spec.componentType` field:
+
+```yaml
+apiVersion: openchoreo.dev/v1alpha1
+kind: Component
+metadata:
+ name: my-service
+spec:
+ componentType: deployment/service # References the ComponentType
+ parameters:
+ replicas: 3
+ port: 8080
+ exposed: true
+```
+
+## Best Practices
+
+1. **Naming Convention**: Use descriptive names like `service`, `web-application`, `scheduled-task`
+2. **Parameter Design**: Keep parameters focused and provide sensible defaults
+3. **Resource IDs**: Use clear, descriptive IDs for each resource template
+4. **Conditional Resources**: Use `includeWhen` for optional resources based on parameters
+5. **Type Definitions**: Define reusable types for complex parameter structures
+6. **Testing**: Validate ComponentTypes with sample components before platform-wide deployment
+
+## Related Resources
+
+- [Component](../application/component.md) - Uses ComponentTypes for deployment
+- [ComponentDeployment](../application/componentdeployment.md) - Can override ComponentType parameters per environment
+- [Trait](trait.md) - Adds cross-cutting concerns to components using ComponentTypes
diff --git a/versioned_docs/version-v0.5.x/reference/api/platform/dataplane.md b/versioned_docs/version-v0.5.x/reference/api/platform/dataplane.md
new file mode 100644
index 0000000..6e63d9b
--- /dev/null
+++ b/versioned_docs/version-v0.5.x/reference/api/platform/dataplane.md
@@ -0,0 +1,129 @@
+---
+title: DataPlane API Reference
+---
+
+# DataPlane
+
+A DataPlane represents a Kubernetes cluster where application workloads are deployed. It defines the connection to a
+target Kubernetes cluster, container registry configuration, and gateway settings for routing traffic to applications.
+
+## API Version
+
+`openchoreo.dev/v1alpha1`
+
+## Resource Definition
+
+### Metadata
+
+DataPlanes are namespace-scoped resources that must be created within an Organization's namespace.
+
+```yaml
+apiVersion: openchoreo.dev/v1alpha1
+kind: DataPlane
+metadata:
+ name:
+ namespace: # Organization namespace
+```
+
+### Spec Fields
+
+| Field | Type | Required | Default | Description |
+|---------------------|-------------------------------------------------|----------|---------|-----------------------------------------------------|
+| `kubernetesCluster` | [KubernetesClusterSpec](#kubernetesclusterspec) | Yes | - | Target Kubernetes cluster configuration |
+| `registry` | [Registry](#registry) | Yes | - | Container registry configuration for pulling images |
+| `gateway` | [GatewaySpec](#gatewayspec) | Yes | - | API gateway configuration for this DataPlane |
+| `observer` | [ObserverAPI](#observerapi) | No | - | Observer API integration for monitoring and logging |
+
+### KubernetesClusterSpec
+
+| Field | Type | Required | Default | Description |
+|----------------------------|--------|----------|---------|-----------------------------------|
+| `name` | string | Yes | - | Name of the Kubernetes cluster |
+| `credentials.apiServerURL` | string | Yes | - | URL of the Kubernetes API server |
+| `credentials.caCert` | string | Yes | - | Base64-encoded CA certificate |
+| `credentials.clientCert` | string | Yes | - | Base64-encoded client certificate |
+| `credentials.clientKey` | string | Yes | - | Base64-encoded client private key |
+
+### Registry
+
+| Field | Type | Required | Default | Description |
+|-------------|--------|----------|---------|-----------------------------------------------------------|
+| `prefix` | string | Yes | - | Registry domain and namespace (e.g., docker.io/namespace) |
+| `secretRef` | string | No | "" | Name of Kubernetes Secret with registry credentials |
+
+### GatewaySpec
+
+| Field | Type | Required | Default | Description |
+|---------------------------|--------|----------|---------|---------------------------------------------------------|
+| `publicVirtualHost` | string | Yes | - | Public virtual host for external traffic |
+| `organizationVirtualHost` | string | Yes | - | Organization-specific virtual host for internal traffic |
+
+### ObserverAPI
+
+| Field | Type | Required | Default | Description |
+|-------------------------------------|--------|----------|---------|-----------------------------------|
+| `url` | string | Yes | - | Base URL of the Observer API |
+| `authentication.basicAuth.username` | string | Yes | - | Username for basic authentication |
+| `authentication.basicAuth.password` | string | Yes | - | Password for basic authentication |
+
+### Status Fields
+
+| Field | Type | Default | Description |
+|----------------------|-------------|---------|-------------------------------------------------------------|
+| `observedGeneration` | integer | 0 | The generation observed by the controller |
+| `conditions` | []Condition | [] | Standard Kubernetes conditions tracking the DataPlane state |
+
+#### Condition Types
+
+Common condition types for DataPlane resources:
+
+- `Ready` - Indicates if the DataPlane is ready to accept workloads
+- `Connected` - Indicates if connection to the target cluster is established
+- `GatewayProvisioned` - Indicates if the gateway has been configured
+
+## Examples
+
+### Basic DataPlane
+
+```yaml
+apiVersion: openchoreo.dev/v1alpha1
+kind: DataPlane
+metadata:
+ name: production-dataplane
+ namespace: default
+spec:
+ kubernetesCluster:
+ name: production-cluster
+ credentials:
+ apiServerURL: https://k8s-api.example.com:6443
+ caCert: LS0tLS1CRUdJTi... # Base64-encoded CA cert
+ clientCert: LS0tLS1CRUdJTi... # Base64-encoded client cert
+ clientKey: LS0tLS1CRUdJTi... # Base64-encoded client key
+ registry:
+ prefix: docker.io/myorg
+ secretRef: registry-credentials
+ gateway:
+ publicVirtualHost: api.example.com
+ organizationVirtualHost: internal.example.com
+ observer:
+ url: https://observer.example.com
+ authentication:
+ basicAuth:
+ username: admin
+ password: secretpassword
+```
+
+## Annotations
+
+DataPlanes support the following annotations:
+
+| Annotation | Description |
+|-------------------------------|---------------------------------------|
+| `openchoreo.dev/display-name` | Human-readable name for UI display |
+| `openchoreo.dev/description` | Detailed description of the DataPlane |
+
+## Related Resources
+
+- [Environment](./environment.md) - Runtime environments deployed on DataPlanes
+- [Organization](./organization.md) - Contains DataPlane definitions
+- [Project](../application/project.md) - Applications deployed to DataPlanes
diff --git a/versioned_docs/version-v0.5.x/reference/api/platform/deployment-pipeline.md b/versioned_docs/version-v0.5.x/reference/api/platform/deployment-pipeline.md
new file mode 100644
index 0000000..4dd1202
--- /dev/null
+++ b/versioned_docs/version-v0.5.x/reference/api/platform/deployment-pipeline.md
@@ -0,0 +1,98 @@
+---
+title: DeploymentPipeline API Reference
+---
+
+# DeploymentPipeline
+
+A DeploymentPipeline defines the promotion paths and approval workflows for deploying applications across different
+environments in OpenChoreo. It establishes the progression order from development to production environments and
+specifies which promotions require approval.
+
+## API Version
+
+`openchoreo.dev/v1alpha1`
+
+## Resource Definition
+
+### Metadata
+
+DeploymentPipelines are namespace-scoped resources that must be created within an Organization's namespace.
+
+```yaml
+apiVersion: openchoreo.dev/v1alpha1
+kind: DeploymentPipeline
+metadata:
+ name:
+ namespace: # Organization namespace
+```
+
+### Spec Fields
+
+| Field | Type | Required | Default | Description |
+|------------------|-----------------------------------|----------|---------|----------------------------------------------------------------|
+| `promotionPaths` | [[PromotionPath](#promotionpath)] | No | [] | Defines the available paths for promotion between environments |
+
+### PromotionPath
+
+| Field | Type | Required | Default | Description |
+|-------------------------|-------------------------------------------------|----------|---------|-------------------------------------------------------------|
+| `sourceEnvironmentRef` | string | Yes | - | Reference to the source environment for promotion |
+| `targetEnvironmentRefs` | [[TargetEnvironmentRef](#targetenvironmentref)] | Yes | - | List of target environments and their approval requirements |
+
+### TargetEnvironmentRef
+
+| Field | Type | Required | Default | Description |
+|--------------------|---------|----------|---------|--------------------------------------------------------------|
+| `name` | string | Yes | - | Name of the target environment |
+| `requiresApproval` | boolean | No | false | Indicates if promotion to this environment requires approval |
+
+### Status Fields
+
+| Field | Type | Default | Description |
+|----------------------|-------------|---------|-----------------------------------------------------------------------|
+| `observedGeneration` | integer | 0 | The generation observed by the controller |
+| `conditions` | []Condition | [] | Standard Kubernetes conditions tracking the deployment pipeline state |
+
+#### Condition Types
+
+Common condition types for DeploymentPipeline resources:
+
+- `Available` - Indicates if the deployment pipeline is available and configured
+
+## Examples
+
+### Basic DeploymentPipeline
+
+```yaml
+apiVersion: openchoreo.dev/v1alpha1
+kind: DeploymentPipeline
+metadata:
+ name: default-deployment-pipeline
+ namespace: default
+spec:
+ promotionPaths:
+ - sourceEnvironmentRef: development
+ targetEnvironmentRefs:
+ - name: staging
+ requiresApproval: false
+ - sourceEnvironmentRef: staging
+ targetEnvironmentRefs:
+ - name: production
+ requiresApproval: true
+```
+
+## Annotations
+
+DeploymentPipelines support the following annotations:
+
+| Annotation | Description |
+|-------------------------------|-------------------------------------------------|
+| `openchoreo.dev/display-name` | Human-readable name for UI display |
+| `openchoreo.dev/description` | Detailed description of the deployment pipeline |
+
+## Related Resources
+
+- [Project](../application/project.md) - Projects reference deployment pipelines for their promotion
+ workflows
+- [Environment](./environment.md) - Environments that are connected through promotion paths
+- [Organization](./organization.md) - Contains deployment pipeline definitions
diff --git a/versioned_docs/version-v0.5.x/reference/api/platform/environment.md b/versioned_docs/version-v0.5.x/reference/api/platform/environment.md
new file mode 100644
index 0000000..5f2c576
--- /dev/null
+++ b/versioned_docs/version-v0.5.x/reference/api/platform/environment.md
@@ -0,0 +1,110 @@
+---
+title: Environment API Reference
+---
+
+# Environment
+
+An Environment represents a runtime context (e.g., dev, test, staging, production) where workloads are deployed and
+executed. Environments define deployment targets within a DataPlane and control environment-specific configurations like
+gateway settings and production flags.
+
+## API Version
+
+`openchoreo.dev/v1alpha1`
+
+## Resource Definition
+
+### Metadata
+
+Environments are namespace-scoped resources that must be created within an Organization's namespace.
+
+```yaml
+apiVersion: openchoreo.dev/v1alpha1
+kind: Environment
+metadata:
+ name:
+ namespace: # Organization namespace
+```
+
+### Spec Fields
+
+| Field | Type | Required | Default | Description |
+|----------------|---------------------------------|----------|-----------|---------------------------------------------------------------|
+| `dataPlaneRef` | string | No | "default" | Reference to the DataPlane where this environment is deployed |
+| `isProduction` | boolean | No | false | Indicates if this is a production environment |
+| `gateway` | [GatewayConfig](#gatewayconfig) | No | - | Gateway configuration specific to this environment |
+
+### GatewayConfig
+
+| Field | Type | Required | Default | Description |
+|---------------------------|--------|----------|---------|------------------------------------------------------------------|
+| `dnsPrefix` | string | No | "" | DNS prefix for the environment (e.g., "dev" for dev.example.com) |
+| `security.remoteJwks.uri` | string | No | "" | URI for remote JWKS endpoint for JWT validation |
+
+### Status Fields
+
+| Field | Type | Default | Description |
+|----------------------|-------------|---------|---------------------------------------------------------------|
+| `observedGeneration` | integer | 0 | The generation observed by the controller |
+| `conditions` | []Condition | [] | Standard Kubernetes conditions tracking the environment state |
+
+#### Condition Types
+
+Common condition types for Environment resources:
+
+- `Ready` - Indicates if the environment is fully provisioned and ready
+- `DataPlaneConnected` - Indicates if the environment is connected to its DataPlane
+- `GatewayConfigured` - Indicates if gateway configuration has been applied
+
+## Examples
+
+### Development Environment
+
+```yaml
+apiVersion: openchoreo.dev/v1alpha1
+kind: Environment
+metadata:
+ name: development
+ namespace: default
+spec:
+ dataPlaneRef: dev-dataplane
+ isProduction: false
+ gateway:
+ dnsPrefix: dev
+ security:
+ remoteJwks:
+ uri: https://auth.example.com/.well-known/jwks.json
+```
+
+### Production Environment
+
+```yaml
+apiVersion: openchoreo.dev/v1alpha1
+kind: Environment
+metadata:
+ name: production
+ namespace: default
+spec:
+ dataPlaneRef: prod-dataplane
+ isProduction: true
+ gateway:
+ dnsPrefix: api
+ security:
+ remoteJwks:
+ uri: https://auth.example.com/.well-known/jwks.json
+```
+
+## Annotations
+
+Environments support the following annotations:
+
+| Annotation | Description |
+|-------------------------------|-----------------------------------------|
+| `openchoreo.dev/display-name` | Human-readable name for UI display |
+| `openchoreo.dev/description` | Detailed description of the environment |
+
+## Related Resources
+
+- [DataPlane](./dataplane.md) - Kubernetes cluster hosting the environment
+- [DeploymentPipeline](./deployment-pipeline.md) - Defines promotion paths between environments
+- [Organization](./organization.md) - Contains environment definitions
diff --git a/versioned_docs/version-v0.5.x/reference/api/platform/organization.md b/versioned_docs/version-v0.5.x/reference/api/platform/organization.md
new file mode 100644
index 0000000..e14c3ee
--- /dev/null
+++ b/versioned_docs/version-v0.5.x/reference/api/platform/organization.md
@@ -0,0 +1,79 @@
+---
+title: Organization API Reference
+---
+
+# Organization
+
+An Organization is the top-level grouping mechanism in OpenChoreo. It represents a logical boundary for users and
+resources, typically aligned to a company, business unit, or team. Organizations provide namespace isolation and serve
+as the container for all projects and platform resources.
+
+## API Version
+
+`openchoreo.dev/v1alpha1`
+
+## Resource Definition
+
+### Metadata
+
+Organizations are cluster-scoped resources, meaning they exist at the cluster level rather than within a namespace.
+
+```yaml
+apiVersion: openchoreo.dev/v1alpha1
+kind: Organization
+metadata:
+ name:
+```
+
+### Spec Fields
+
+The Organization spec is currently empty. Organizations are provisioned based on their metadata alone.
+
+| Field | Type | Required | Default | Description |
+|-------|------|----------|---------|------------------------|
+| - | - | - | - | No spec fields defined |
+
+### Status Fields
+
+| Field | Type | Default | Description |
+|----------------------|-------------|---------|----------------------------------------------------------------|
+| `observedGeneration` | integer | 0 | The generation observed by the controller |
+| `namespace` | string | "" | The namespace provisioned for this organization |
+| `conditions` | []Condition | [] | Standard Kubernetes conditions tracking the organization state |
+
+#### Condition Types
+
+Common condition types for Organization resources:
+
+- `Ready` - Indicates if the organization is fully provisioned and ready
+- `NamespaceProvisioned` - Indicates if the organization namespace has been created
+
+## Examples
+
+### Basic Organization
+
+```yaml
+apiVersion: openchoreo.dev/v1alpha1
+kind: Organization
+metadata:
+ name: default-organization
+ annotations:
+ openchoreo.dev/display-name: Default Organization
+ openchoreo.dev/description: This is the default organization for this setup
+spec: { }
+```
+
+## Annotations
+
+Organizations support the following annotations:
+
+| Annotation | Description |
+|-------------------------------|------------------------------------------|
+| `openchoreo.dev/display-name` | Human-readable name for UI display |
+| `openchoreo.dev/description` | Detailed description of the organization |
+
+## Related Resources
+
+- [Project](../application/project.md) - Cloud-native applications within an organization
+- [DataPlane](./dataplane.md) - Kubernetes clusters managed by the organization
+- [Environment](./environment.md) - Runtime environments for the organization
diff --git a/versioned_docs/version-v0.5.x/reference/api/platform/scheduledtaskclass.md b/versioned_docs/version-v0.5.x/reference/api/platform/scheduledtaskclass.md
new file mode 100644
index 0000000..759327b
--- /dev/null
+++ b/versioned_docs/version-v0.5.x/reference/api/platform/scheduledtaskclass.md
@@ -0,0 +1,90 @@
+---
+title: ScheduledTaskClass API Reference (Deprecated)
+---
+
+# ScheduledTaskClass
+
+:::warning Deprecated
+ScheduledTaskClass is deprecated as of OpenChoreo v0.4.0 and will be removed in a future version.
+Use [ComponentType](componenttype.md) with [Traits](trait.md) instead for a more flexible and composable approach to
+defining component deployment patterns.
+:::
+
+A ScheduledTaskClass is a platform-level template that provides governance and standardization for ScheduledTask
+resources in OpenChoreo. It follows the Claim/Class pattern where platform teams define Classes to enforce
+organizational policies, resource limits, and scheduling configurations while application teams create
+ScheduledTasks (claims) that reference these classes.
+
+## API Version
+
+`openchoreo.dev/v1alpha1`
+
+## Resource Definition
+
+### Metadata
+
+ScheduledTaskClasses are namespace-scoped resources that must be created within an Organization's namespace.
+
+```yaml
+apiVersion: openchoreo.dev/v1alpha1
+kind: ScheduledTaskClass
+metadata:
+ name:
+ namespace: # Organization namespace
+```
+
+### Spec Fields
+
+| Field | Type | Required | Default | Description |
+|-------------------|-------------------------------------------------------------------------------------------------------------------------------------|----------|---------|------------------------------------------------------------------------|
+| `cronJobTemplate` | CronJobSpec | No | - | Kubernetes CronJob specification template for scheduled task workloads |
+
+## Examples
+
+### Basic ScheduledTaskClass
+
+```yaml
+apiVersion: openchoreo.dev/v1alpha1
+kind: ScheduledTaskClass
+metadata:
+ name: standard-cronjob
+ namespace: default
+spec:
+ cronJobTemplate:
+ schedule: "*/30 * * * *" # Every 30 minutes
+ concurrencyPolicy: Forbid
+ successfulJobsHistoryLimit: 3
+ failedJobsHistoryLimit: 1
+ jobTemplate:
+ spec:
+ backoffLimit: 3
+ template:
+ spec:
+ restartPolicy: OnFailure
+ containers:
+ - name: main
+ resources:
+ requests:
+ memory: "64Mi"
+ cpu: "50m"
+ limits:
+ memory: "256Mi"
+ cpu: "200m"
+```
+
+## Annotations
+
+ScheduledTaskClasses support the following annotations:
+
+| Annotation | Description |
+|-------------------------------|------------------------------------------------|
+| `openchoreo.dev/display-name` | Human-readable name for UI display |
+| `openchoreo.dev/description` | Detailed description of the ScheduledTaskClass |
+
+## Related Resources
+
+- [ScheduledTask](../application/scheduledtask.md) - ScheduledTask resources that reference
+ ScheduledTaskClasses
+- [ScheduledTaskBinding](../runtime/scheduledtaskbinding.md) - Environment-specific scheduled task
+ instances
+- [Organization](./organization.md) - Contains ScheduledTaskClass definitions
diff --git a/versioned_docs/version-v0.5.x/reference/api/platform/serviceclass.md b/versioned_docs/version-v0.5.x/reference/api/platform/serviceclass.md
new file mode 100644
index 0000000..56f72cc
--- /dev/null
+++ b/versioned_docs/version-v0.5.x/reference/api/platform/serviceclass.md
@@ -0,0 +1,91 @@
+---
+title: ServiceClass API Reference (Deprecated)
+---
+
+# ServiceClass
+
+:::warning Deprecated
+ServiceClass is deprecated as of OpenChoreo v0.4.0 and will be removed in a future version.
+Use [ComponentType](componenttype.md) with [Traits](trait.md) instead for a more flexible and composable approach to
+defining component deployment patterns.
+:::
+
+A ServiceClass is a platform-level template that provides governance and standardization for Service
+resources in OpenChoreo. It follows the Claim/Class pattern where platform teams define Classes to enforce
+organizational policies, resource limits, and deployment configurations while application teams create Services (claims)
+that reference these classes.
+
+## API Version
+
+`openchoreo.dev/v1alpha1`
+
+## Resource Definition
+
+### Metadata
+
+ServiceClasses are namespace-scoped resources that must be created within an Organization's namespace.
+
+```yaml
+apiVersion: openchoreo.dev/v1alpha1
+kind: ServiceClass
+metadata:
+ name:
+ namespace: # Organization namespace
+```
+
+### Spec Fields
+
+| Field | Type | Required | Default | Description |
+|----------------------|------------------------------------------------------------------------------------------------------------------------------------------|----------|---------|--------------------------------------------------------------------|
+| `deploymentTemplate` | DeploymentSpec | No | - | Kubernetes Deployment specification template for service workloads |
+| `serviceTemplate` | ServiceSpec | No | - | Kubernetes Service specification template for service networking |
+
+## Examples
+
+### Basic ServiceClass
+
+```yaml
+apiVersion: openchoreo.dev/v1alpha1
+kind: ServiceClass
+metadata:
+ name: standard-service
+ namespace: default
+spec:
+ deploymentTemplate:
+ replicas: 2
+ selector:
+ matchLabels:
+ app: service
+ template:
+ spec:
+ containers:
+ - name: main
+ resources:
+ requests:
+ memory: "128Mi"
+ cpu: "100m"
+ limits:
+ memory: "512Mi"
+ cpu: "500m"
+ serviceTemplate:
+ type: ClusterIP
+ ports:
+ - port: 80
+ targetPort: 8080
+ protocol: TCP
+```
+
+## Annotations
+
+ServiceClasses support the following annotations:
+
+| Annotation | Description |
+|-------------------------------|------------------------------------------|
+| `openchoreo.dev/display-name` | Human-readable name for UI display |
+| `openchoreo.dev/description` | Detailed description of the ServiceClass |
+
+## Related Resources
+
+- [Service](../application/service.md) - Service resources that reference ServiceClasses
+- [ServiceBinding](../runtime/servicebinding.md) - Environment-specific service instances
+- [Organization](./organization.md) - Contains ServiceClass definitions
diff --git a/versioned_docs/version-v0.5.x/reference/api/platform/trait.md b/versioned_docs/version-v0.5.x/reference/api/platform/trait.md
new file mode 100644
index 0000000..381cb43
--- /dev/null
+++ b/versioned_docs/version-v0.5.x/reference/api/platform/trait.md
@@ -0,0 +1,349 @@
+---
+title: Trait API Reference
+---
+
+# Trait
+
+A Trait represents a cross-cutting concern that can be attached to components to add additional capabilities like
+persistent storage, observability, security policies, or service mesh integration. Traits modify or extend the resources
+generated by ComponentTypes without requiring changes to the ComponentType itself.
+
+## API Version
+
+`openchoreo.dev/v1alpha1`
+
+## Resource Definition
+
+### Metadata
+
+Traits are namespace-scoped resources typically created in an Organization's namespace to be available for components in
+that organization.
+
+```yaml
+apiVersion: openchoreo.dev/v1alpha1
+kind: Trait
+metadata:
+ name:
+ namespace: # Organization namespace
+```
+
+### Spec Fields
+
+| Field | Type | Required | Default | Description |
+|-----------|-------------------------------|----------|---------|---------------------------------------------------|
+| `schema` | [TraitSchema](#traitschema) | No | - | Configurable parameters for this trait |
+| `creates` | [[TraitCreate](#traitcreate)] | No | [] | New Kubernetes resources to create |
+| `patches` | [[TraitPatch](#traitpatch)] | No | [] | Modifications to existing ComponentType resources |
+
+### TraitSchema
+
+Defines the configurable parameters that developers can set when attaching this trait to a component.
+
+| Field | Type | Required | Default | Description |
+|----------------|--------|----------|------------------------------------------------------------|
+| `types` | object | No | - | Reusable type definitions referenced in parameters |
+| `parameters` | object | No | - | Developer-facing configuration options |
+| `envOverrides` | object | No | - | Parameters that can be overridden per environment |
+
+#### Parameter Schema Syntax
+
+Uses the same inline schema syntax as ComponentType:
+
+```
+fieldName: "type | default=value | required=true | enum=val1,val2"
+```
+
+**Example:**
+
+```yaml
+schema:
+ parameters:
+ volumeName: "string | required=true"
+ mountPath: "string | required=true"
+ containerName: "string | default=app"
+
+ envOverrides:
+ size: "string | default=10Gi"
+ storageClass: "string | default=standard"
+```
+
+### TraitCreate
+
+Defines a new Kubernetes resource to be created when the trait is applied.
+
+| Field | Type | Required | Description |
+|------------|--------|----------|---------------------------------------------------|
+| `template` | object | Yes | Kubernetes resource template with CEL expressions |
+
+CEL expressions in trait templates have access to:
+
+- `metadata.*` - Component metadata
+- `trait.*` - Trait parameters and instance name
+- `parameters.*` - Component parameters
+- `environment.*` - Environment information
+
+### TraitPatch
+
+Defines modifications to existing resources generated by the ComponentType.
+
+| Field | Type | Required | Description |
+|--------------|---------------------------------------------|----------|------------------------------------------------------------------|
+| `forEach` | string | No | CEL expression for iterating over a list |
+| `var` | string | No | Variable name for `forEach` iterations (required if forEach set) |
+| `target` | [PatchTarget](#patchtarget) | Yes | Specifies which resource to patch |
+| `operations` | [[JSONPatchOperation](#jsonpatchoperation)] | Yes | List of JSONPatch operations to apply |
+
+### PatchTarget
+
+Specifies which Kubernetes resource to modify.
+
+| Field | Type | Required | Description |
+|-----------|--------|----------|---------------------------------------------------|
+| `group` | string | No | API group (empty for core resources) |
+| `version` | string | Yes | API version (e.g., "v1", "v1beta1") |
+| `kind` | string | Yes | Resource type (e.g., "Deployment", "StatefulSet") |
+| `where` | string | No | CEL expression to filter which resources to patch |
+
+### JSONPatchOperation
+
+Defines a modification using JSONPatch format (RFC 6902) with OpenChoreo extensions.
+
+| Field | Type | Required | Description |
+|---------|--------|----------|-------------------------------------------------------|
+| `op` | string | Yes | Operation: `add`, `replace`, `remove`, `mergeShallow` |
+| `path` | string | Yes | JSON Pointer to the field (RFC 6901) |
+| `value` | any | No | Value to set (not used for `remove`) |
+
+#### Supported Operations
+
+- **add**: Add a new field or array element
+- **replace**: Replace an existing field value
+- **remove**: Delete a field
+- **mergeShallow**: OpenChoreo extension for overlaying map keys
+
+#### Path Syntax
+
+Supports array filters for targeting specific elements:
+
+```
+/spec/containers/[?(@.name=='app')]/volumeMounts/-
+```
+
+## Examples
+
+### Persistent Volume Trait
+
+```yaml
+apiVersion: openchoreo.dev/v1alpha1
+kind: Trait
+metadata:
+ name: persistent-volume
+ namespace: default
+spec:
+ schema:
+ parameters:
+ volumeName: "string | required=true"
+ mountPath: "string | required=true"
+ containerName: "string | default=app"
+
+ envOverrides:
+ size: "string | default=10Gi"
+ storageClass: "string | default=standard"
+
+ creates:
+ - template:
+ apiVersion: v1
+ kind: PersistentVolumeClaim
+ metadata:
+ name: ${metadata.name}-${trait.instanceName}
+ namespace: ${metadata.namespace}
+ spec:
+ accessModes:
+ - ReadWriteOnce
+ storageClassName: ${trait.parameters.storageClass}
+ resources:
+ requests:
+ storage: ${trait.parameters.size}
+
+ patches:
+ - target:
+ group: apps
+ version: v1
+ kind: Deployment
+ operations:
+ - op: add
+ path: /spec/template/spec/containers/[?(@.name=='${trait.parameters.containerName}')]/volumeMounts/-
+ value:
+ name: ${trait.parameters.volumeName}
+ mountPath: ${trait.parameters.mountPath}
+ - op: add
+ path: /spec/template/spec/volumes/-
+ value:
+ name: ${trait.parameters.volumeName}
+ persistentVolumeClaim:
+ claimName: ${metadata.name}-${trait.instanceName}
+```
+
+### Sidecar Container Trait
+
+```yaml
+apiVersion: openchoreo.dev/v1alpha1
+kind: Trait
+metadata:
+ name: logging-sidecar
+ namespace: default
+spec:
+ schema:
+ parameters:
+ logPath: "string | default=/var/log/app"
+ sidecarImage: "string | default=fluent/fluent-bit:latest"
+
+ patches:
+ - target:
+ group: apps
+ version: v1
+ kind: Deployment
+ operations:
+ - op: add
+ path: /spec/template/spec/containers/-
+ value:
+ name: log-collector
+ image: ${trait.parameters.sidecarImage}
+ volumeMounts:
+ - name: logs
+ mountPath: ${trait.parameters.logPath}
+ - op: add
+ path: /spec/template/spec/volumes/-
+ value:
+ name: logs
+ emptyDir: {}
+```
+
+### Resource Limits Trait
+
+```yaml
+apiVersion: openchoreo.dev/v1alpha1
+kind: Trait
+metadata:
+ name: resource-limits
+ namespace: default
+spec:
+ schema:
+ envOverrides:
+ cpuLimit: "string | default=1000m"
+ memoryLimit: "string | default=512Mi"
+
+ patches:
+ - target:
+ group: apps
+ version: v1
+ kind: Deployment
+ operations:
+ - op: mergeShallow
+ path: /spec/template/spec/containers/[?(@.name=='main')]/resources
+ value:
+ limits:
+ cpu: ${trait.parameters.cpuLimit}
+ memory: ${trait.parameters.memoryLimit}
+```
+
+### Multi-Container Trait with forEach
+
+```yaml
+apiVersion: openchoreo.dev/v1alpha1
+kind: Trait
+metadata:
+ name: multi-volume
+ namespace: default
+spec:
+ schema:
+ parameters:
+ mounts: "array
.default})
+
+ :::tip
+ If any components remain in the `pending` state, wait a few minutes and run the following command to check their
+ status:
+
+ ```bash
+ ./check-status.sh
+ ```
+ :::
+