diff --git a/docusaurus.config.ts b/docusaurus.config.ts index 4ef0e08..df3e721 100644 --- a/docusaurus.config.ts +++ b/docusaurus.config.ts @@ -55,8 +55,11 @@ const config: Config = { 'classic', { docs: { - lastVersion: 'v0.10.x', + lastVersion: 'v0.11.x', versions: { + 'v0.11.x': { + label: 'v0.11.x', + }, 'v0.10.x': { label: 'v0.10.x', }, @@ -114,9 +117,9 @@ const config: Config = { themeConfig: { announcementBar: { - id: 'release_v0_10_0', + id: 'release_v0_11_0', content: - '🎉️ OpenChoreo v0.10.0 has been released! Explore what’s new. 🎉', + '🎉️ OpenChoreo v0.11.0 has been released! Explore what’s new. 🎉', isCloseable: true, }, algolia: { diff --git a/versioned_docs/version-v0.11.x/_constants.mdx b/versioned_docs/version-v0.11.x/_constants.mdx new file mode 100644 index 0000000..be5ac08 --- /dev/null +++ b/versioned_docs/version-v0.11.x/_constants.mdx @@ -0,0 +1,8 @@ +[//] # (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', + helmSource: 'oci://ghcr.io/openchoreo/helm-charts', +}; diff --git a/versioned_docs/version-v0.11.x/concepts/developer-abstractions.md b/versioned_docs/version-v0.11.x/concepts/developer-abstractions.md new file mode 100644 index 0000000..5633d31 --- /dev/null +++ b/versioned_docs/version-v0.11.x/concepts/developer-abstractions.md @@ -0,0 +1,134 @@ +--- +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 use a **ComponentType** reference to determine their deployment characteristics. This reference follows the +format `{workloadType}/{componentTypeName}`, such as `deployment/web-service` or `cronjob/data-processor`. This explicit +typing allows platform engineers to define multiple variations of deployment patterns for the same workload type, each +tuned for different use cases. + +The Component resource connects four essential elements: + +**ComponentType Reference** specifies which platform-defined template governs this component's deployment. The +ComponentType defines the available configuration schema, resource templates, and allowed workflows. This separation +of concerns means developers work with a simplified interface while platform engineers maintain control over +infrastructure patterns. + +**Parameters** provide the component-specific configuration values that conform to the schema defined in the +ComponentType. When a ComponentRelease is created, these parameter values are captured in the release snapshot. The +same values then apply wherever that release is deployed—if you deploy the same ComponentRelease to dev, staging, and +prod, the parameters are identical across all environments. To change parameter values, you update the Component and +create a new ComponentRelease. Environment-specific values (like resource limits or storage sizes) are handled +separately through `envOverrides` in ReleaseBinding resources. + +**Traits** enable composition of additional capabilities into the component. Each trait instance adds specific +functionality like persistent storage, caching, or monitoring. Traits can be instantiated multiple times with +different configurations using unique instance names. For example, a component might attach multiple persistent volume +traits for different storage needs, each with its own size, storage class, and mount configuration. Traits use the +same schema-driven approach as ComponentTypes, with parameters set in the Component and environment-specific overrides +applied through ReleaseBinding resources. + +**Workflow Configuration** optionally specifies how to build the component from source code. This references a +Workflow and provides the developer-configured schema values needed to execute builds. The workflow integration +enables automated container image creation triggered by code changes or manual developer actions. + +The component abstraction thus becomes a declarative specification that combines: +- A ComponentType that defines *how* to deploy +- Parameters that configure *what* to deploy +- Traits that compose *additional capabilities* +- A Workflow that defines *how to build* + +This composition-based approach enables developers to assemble complex applications from reusable building blocks +while the platform ensures consistency, governance, and operational best practices through the underlying ComponentType +and Trait templates. + +## 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. + +## ComponentWorkflowRun + +A **ComponentWorkflowRun** represents a runtime execution instance of a ComponentWorkflow - a specialized workflow type +designed specifically for building components. While ComponentWorkflows define the build template and schema, +ComponentWorkflowRuns represent actual build executions with specific parameter values and ownership tracking. + +ComponentWorkflowRuns bridge the gap between developer intent and CI/CD execution for component builds. Developers +create ComponentWorkflowRun resources to trigger builds, providing component ownership information, repository details, +and build parameters. The platform handles all the complexity of rendering the final workflow specification, +synchronizing secrets, and managing execution in the build plane. + +Each ComponentWorkflowRun captures three essential pieces of information: + +**Ownership Tracking** links the build execution to a specific component and project. This enables traceability, +allowing the platform to track which builds belong to which components and maintain build history per component. The +ownership information includes both project name and component name, ensuring proper audit trails and enabling +component-specific build operations. + +**System Parameters** provide the structured repository information required for build-specific platform features. These +parameters follow a fixed structure with `repository.url`, `repository.revision.branch`, `repository.revision.commit`, +and `repository.appPath` fields. This predictable structure enables the platform to support auto-builds triggered by +webhooks, manual build actions in the UI, build traceability linking images to source commits, and monorepo support by +identifying specific application paths within repositories. + +**Developer Parameters** provide values for the flexible configuration schema defined by the platform engineer in the +ComponentWorkflow. These might include build version numbers, test modes, resource allocations, timeout settings, +caching configurations, and retry limits. The schema validation ensures type correctness and constraint satisfaction +automatically. + +This abstraction provides a specialized interface for component builds, where developers interact with curated schemas +rather than complex CI/CD pipeline definitions. The separation of concerns allows platform engineers to control build +implementation and security policies through ComponentWorkflow templates while developers manage repository information +and build parameters through ComponentWorkflowRun instances. ComponentWorkflowRuns can be created manually for ad-hoc +builds or automatically by platform controllers in response to code changes, supporting both interactive development and +fully automated CI/CD pipelines while maintaining consistent execution patterns and governance specifically tailored for +component build operations. diff --git a/versioned_docs/version-v0.11.x/concepts/platform-abstractions.md b/versioned_docs/version-v0.11.x/concepts/platform-abstractions.md new file mode 100644 index 0000000..0f632d1 --- /dev/null +++ b/versioned_docs/version-v0.11.x/concepts/platform-abstractions.md @@ -0,0 +1,257 @@ +--- +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. + +## ReleaseBinding + +A **ReleaseBinding** connects a ComponentRelease to a specific Environment. This is what actually deploys a release to +a data plane—but it's more than just a reference. + +ReleaseBinding provides a way to override configuration for a specific environment. Values defined in the ComponentType +schema's `envOverrides` and Trait schema's `envOverrides` can be customized per environment through the ReleaseBinding. +This is where environment-specific differences reside: scaling in production versus development, resource limits, +storage classes, and so on—while the ComponentRelease itself remains unchanged. + +Once a ReleaseBinding is created, the ReleaseBinding controller renders the ComponentType and Trait templates with the +combined configuration, generates the necessary Kubernetes resources (Deployments, Services, ConfigMaps, etc.), and +produces a **Release** resource that is applied to the target data plane. + +## Component Types + +A **ComponentType** is a platform engineer-defined template that governs how components are deployed and managed in +OpenChoreo. It represents the bridge between developer intent and platform governance, encoding organizational +policies, best practices, and infrastructure patterns as reusable templates. + +ComponentTypes implement the platform's claim/class pattern at the component level. While developers create Components +that express their application requirements, platform engineers define ComponentTypes that specify how those +requirements should be fulfilled. This separation enables developers to focus on application logic while platform +engineers maintain control over infrastructure policies, resource limits, security configurations, and operational +standards. + +Each ComponentType is built around a specific **workload type** - the primary Kubernetes resource that will run the +application. OpenChoreo supports four fundamental workload types: + +- **deployment**: For long-running services that need continuous availability +- **statefulset**: For applications requiring stable network identities and persistent storage +- **cronjob**: For scheduled tasks that run at specific times or intervals +- **job**: For one-time or on-demand batch processing tasks + +The ComponentType uses a **schema-driven architecture** that defines what developers can configure when creating +components. This schema consists of two types of parameters: + +**Parameters** are configurations captured in the ComponentRelease and applied uniformly wherever that release is +deployed. These include settings like replica counts, image pull policies, and container ports. When you deploy the +same ComponentRelease to multiple environments, the parameter values are identical. To change parameters, you update +the Component and create a new ComponentRelease. + +**EnvOverrides** are configurations that can be overridden on a per-environment basis through ReleaseBinding resources. +These typically include resource allocations, scaling limits, and environment-specific policies. This flexibility +allows platform engineers to provide generous resources in production while constraining development environments to +optimize infrastructure costs. + +The schema uses an inline type definition syntax that makes configuration requirements explicit and self-documenting. +For example, `"integer | default=1"` declares an integer parameter with a default value, while +`"string | enum=Always,IfNotPresent,Never"` restricts a string to specific allowed values. This syntax supports +validation rules like minimum/maximum values, required fields, and enumerated choices. + +ComponentTypes define **resource templates** that generate the actual Kubernetes resources for components. Each +template uses CEL (Common Expression Language) expressions to dynamically generate resource manifests based on +component specifications. Templates can access component metadata, schema parameters, and workload specifications +through predefined variables like `${metadata.name}` and `${parameters.replicas}`. + +Templates support advanced patterns through conditional inclusion and iteration. The `includeWhen` field uses CEL +expressions to conditionally create resources based on configuration, enabling optional features like autoscaling or +ingress. The `forEach` field generates multiple resources from lists, useful for creating ConfigMaps from multiple +configuration files or managing multiple service dependencies. + +ComponentTypes can also restrict which **Workflows** developers can use for building components through the +`allowedWorkflows` field. This enables platform engineers to enforce build standards, ensure security scanning, or +mandate specific build tools for different component types. For instance, a web application ComponentType might only +allow Workflows that use approved frontend build tools and security scanners. + +This schema-driven approach ensures consistency across the platform while providing flexibility for different +application patterns. Platform engineers create ComponentTypes that encode organizational knowledge about how to run +applications securely and efficiently, while developers benefit from simplified configuration and automatic compliance +with platform standards. + +## Traits + +A **Trait** is a platform engineer-defined template that augments components with operational behavior without modifying +the ComponentType. Traits enable composable, reusable capabilities that can be attached to any component—such as +persistent storage, autoscaling, network policies, or sidecar injection. + +Traits use the same schema-driven approach as ComponentTypes, with `parameters` for static configuration and +`envOverrides` for environment-specific values. Developers attach Traits to their Components with instance-specific +parameters, while platform engineers can override environment-specific values through ReleaseBindings. + +Each Trait defines two types of operations: + +**Creates** generate new Kubernetes resources that don't exist in the base ComponentType. For example, a storage Trait +might create PersistentVolumeClaims, or a monitoring Trait might create ServiceMonitor resources. + +**Patches** modify existing resources generated by the ComponentType. Using JSON Patch operations with array filtering, +Traits can inject environment variables, add volume mounts, attach sidecar containers, or add labels and annotations +to existing resources. + +This separation between ComponentTypes (base deployment patterns) and Traits (composable capabilities) enables platform +engineers to define orthogonal concerns independently. Rather than creating separate ComponentTypes for every combination +of features, platform engineers define focused Traits that developers can mix and match as needed. + +## ComponentWorkflow + +A **ComponentWorkflow** is a platform engineer-defined template specifically designed for building components in +OpenChoreo. Unlike generic automation workflows, ComponentWorkflows enforce a structured schema for repository +information while providing flexibility for additional build configuration, enabling powerful build-specific platform +features like auto-builds, webhooks, and build traceability. + +ComponentWorkflows address the unique requirements of component builds that generic workflows cannot solve. Component +builds need to power manual build actions in the UI, integrate with Git webhooks for auto-builds, maintain build +traceability linking container images to source commits, and support monorepo structures by identifying specific +application paths. These features require the platform to reliably locate critical repository fields, which is only +possible with a predictable schema structure. + +Each ComponentWorkflow defines three key sections: + +**System Parameters Schema** enforces a required structured schema for repository information. This schema must follow +a specific structure with `repository.url`, `repository.revision.branch`, `repository.revision.commit`, and +`repository.appPath` fields, all of type string. Platform engineers can customize defaults, enums, and descriptions +within each field, but must maintain the field names, nesting structure, and types. This predictable structure enables +build-specific platform features to work reliably across all component workflows while still giving platform engineers +control over validation rules and default values. + +**Developer Parameters Schema** provides complete freedom for platform engineers to define additional build +configuration. This flexible schema can include any structure the platform engineer designs - build version numbers, +test modes, resource allocations, timeout settings, caching configurations, retry limits, and more. The schema supports +all types including integers, booleans, strings, arrays, and nested objects, with full validation through defaults, +minimums, maximums, and enums. This separation between required system parameters and flexible developer parameters +balances platform reliability with configuration freedom. + +**Run Template** contains the actual Kubernetes resource specification (typically an Argo Workflow) with template +variables for dynamic value injection. These expressions access context variables like `${metadata.workflowRunName}`, +`${metadata.componentName}`, `${metadata.projectName}`, and `${metadata.orgName}` for runtime information, system parameter values +through `${systemParameters.*}` for repository details, and developer parameter values through `${parameters.*}` for +custom configuration. Platform engineers can also hardcode platform-controlled parameters directly in the template, +such as builder images, registry URLs, security scanning settings, and organizational policies. + +ComponentTypes govern which ComponentWorkflows developers can use through the `allowedWorkflows` field. This enables +platform engineers to enforce build standards per component type, ensuring that web applications use approved frontend +build tools, backend services use appropriate security scanners, and different component types follow their specific +build requirements. + +Components reference ComponentWorkflows in their `workflow` field, providing the system parameters for repository +information and developer parameters for build configuration. The platform handles template rendering, secret +synchronization, and execution management in the build plane, with ComponentWorkflowRun resources tracking individual +build executions. + +The ComponentWorkflow abstraction thus provides a specialized interface for component builds that balances platform +needs with developer flexibility. Platform engineers control build implementation, security policies, and +infrastructure configurations while ensuring build-specific features work reliably. Developers get a simplified +interface for configuring builds without managing complex CI/CD pipeline definitions. The separation from generic +workflows makes clear that component builds have unique requirements deserving dedicated abstractions, while +maintaining the schema-driven approach that characterizes OpenChoreo's architecture. diff --git a/versioned_docs/version-v0.11.x/concepts/resource-relationships.md b/versioned_docs/version-v0.11.x/concepts/resource-relationships.md new file mode 100644 index 0000000..5e9df76 --- /dev/null +++ b/versioned_docs/version-v0.11.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. + +### ComponentType + +**ComponentTypes** define platform-level templates that govern how components are deployed. Each ComponentType +specifies a workload type (deployment, statefulset, cronjob, or job) and provides a schema for configurable +parameters. Platform engineers create ComponentTypes that encode organizational policies, resource templates, and +operational best practices. + +ComponentTypes serve as the platform's contract for component deployment. They define what developers can configure +through parameter schemas, what resources will be created through resource templates, and which workflows are allowed +for building components. By centralizing these definitions in ComponentTypes, platform teams ensure consistency across +all applications while maintaining control over infrastructure patterns. + +### Component to ComponentType + +**Components** reference a ComponentType using the format `{workloadType}/{componentTypeName}`. This relationship +establishes which template governs the component's deployment. The component provides parameter values that conform to +the schema defined in the ComponentType, and these parameters are validated automatically. + +The component-to-ComponentType relationship is fundamental to OpenChoreo's governance model. Components cannot be +created without referencing a valid ComponentType, ensuring all deployments follow platform standards. This +relationship also determines which resource templates will be used to generate the actual Kubernetes resources. + +### Trait Composition + +**Traits** attach additional capabilities to components through composition. Each component can instantiate multiple +traits, such as persistent storage, caching, or monitoring. Traits use the same schema-driven approach as +ComponentTypes, with parameters that can be overridden per environment through ReleaseBinding resources. + +Traits maintain an independent lifecycle from components but are applied together during deployment. This separation +enables platform engineers to define reusable capabilities that can be composed into different component types. The +trait relationship provides flexibility while maintaining governance through schema validation. + +### Workflow Integration + +**Workflows** define build and automation templates that components can reference through their workflow configuration. +ComponentTypes can restrict which workflows are allowed, ensuring components use appropriate build strategies. This +relationship between components, ComponentTypes, and Workflows enables platform teams to enforce build standards and +security policies. + +When a component references a Workflow, it provides schema values that configure the workflow execution. The Workflow +template uses these values along with platform-controlled parameters to generate the actual CI/CD pipeline. This +separation enables developers to trigger builds with simple configuration while platform engineers maintain control +over build infrastructure and security. + +### Component to WorkflowRun + +Components trigger **WorkflowRuns** through their workflow configuration to build container images. Each WorkflowRun +represents an execution instance of a Workflow template with specific parameter values. WorkflowRuns maintain a +relationship back to their originating component and the specific commit that triggered them. + +This relationship provides complete traceability from running containers back to source code. Platform operators can +trace any container image to the WorkflowRun that built it, which links to the component and ultimately to the source +repository and commit. This traceability is essential for debugging, compliance, and security auditing. + +### ComponentRelease and ReleaseBinding + +A **ComponentRelease** is an immutable snapshot of a component at a specific point in time. It captures the Component, +its Workload configuration, the selected ComponentType, and any attached Traits into a single versioned resource. This +snapshot works like a lock file—preserving the exact state so that the release remains stable and repeatable, even if +the original resources are later updated. + +To deploy a ComponentRelease to an environment, you create a **ReleaseBinding**. This resource binds the release to a +specific environment and provides environment-specific overrides for ComponentType and Trait parameters. The +ReleaseBinding controller renders the final Kubernetes manifests and produces a **Release** resource that is applied +to the target DataPlane. + +This relationship chain—Component → ComponentRelease → ReleaseBinding → Release—ensures complete governance while +enabling environment-specific customization. The immutable ComponentRelease supports a "create once, deploy many" +workflow, where the same release can be safely promoted across environments (dev → staging → prod) without drift. + +## 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 ComponentType +triggers reconciliation of all components that reference it, regenerating their deployments and releases with the new +template. 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 WorkflowRuns, ComponentReleases, ReleaseBindings, and Releases are cleaned up. These +cascading relationships ensure that resources are properly cleaned up without leaving orphaned objects. diff --git a/versioned_docs/version-v0.11.x/concepts/runtime-model.md b/versioned_docs/version-v0.11.x/concepts/runtime-model.md new file mode 100644 index 0000000..6f2ab3e --- /dev/null +++ b/versioned_docs/version-v0.11.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 Kgateway 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.11.x/getting-started/deploy-first-component.mdx b/versioned_docs/version-v0.11.x/getting-started/deploy-first-component.mdx new file mode 100644 index 0000000..6d22fcc --- /dev/null +++ b/versioned_docs/version-v0.11.x/getting-started/deploy-first-component.mdx @@ -0,0 +1,159 @@ +--- +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 (see [On Self-Hosted Kubernetes](./try-it-out/on-self-hosted-kubernetes.mdx) or the [Operations Guide](../operations/deployment-topology.mdx) for production setup) +- **kubectl** configured to access your cluster +- **kubectl context** set to your cluster (should be `k3d-openchoreo` if following the k3d setup) + +## Step 1: Verify Your Setup + +First, make sure you have set up OpenChoreo on your cluster following one of the installation guides. + +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. + + +{`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 +- **ReleaseBinding**: Deploys the component to the development environment +- **SecretReference**: Manages external secrets for the component + +## Step 3: Monitor the Deployment + +Check that all resources are created: + +```bash +kubectl get component,workload,releasebinding -A +``` + +Check the component status: + +```bash +kubectl get component greeter-service +``` + +Monitor the component deployment: + +```bash +kubectl get releasebinding greeter-service-development +``` + +## Step 4: Verify the Deployment + +Wait for the service to be ready (this may take 1-2 minutes). + +Check the actual Kubernetes deployment: + +```bash +kubectl get deployment -A | grep greeter +``` + +Verify pods are running: + +```bash +kubectl get pods -A | grep greeter +``` + +Check HTTP routes are configured: + +```bash +kubectl get httproute -A -o wide +``` + +## Step 5: Test Your Application + +Test the greeter service endpoint: + +```bash +curl http://development.openchoreoapis.localhost:19080/greeter-service/greeter/greet +``` + +You should receive a successful response: +```text +Hello, Stranger! +``` + +You can also test with a name parameter: +```bash +curl http://development.openchoreoapis.localhost:19080/greeter-service/greeter/greet?name=OpenChoreo +``` + +Expected output: +```text +Hello, OpenChoreo! +``` + +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. + +View the OpenChoreo resources: + +```bash +kubectl get component,workload,releasebinding -n default +``` + +Check the underlying Kubernetes resources: + +```bash +kubectl get deployment,pod,svc -A | grep greeter +``` + +View the HTTP routing configuration: + +```bash +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 +- **ReleaseBinding** - 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.11.x/getting-started/qsg-backstage-ui.png b/versioned_docs/version-v0.11.x/getting-started/qsg-backstage-ui.png new file mode 100644 index 0000000..8d4a1c5 Binary files /dev/null and b/versioned_docs/version-v0.11.x/getting-started/qsg-backstage-ui.png differ diff --git a/versioned_docs/version-v0.11.x/getting-started/qsg-install-status-success.png b/versioned_docs/version-v0.11.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.11.x/getting-started/qsg-install-status-success.png differ diff --git a/versioned_docs/version-v0.11.x/getting-started/quick-start-guide.mdx b/versioned_docs/version-v0.11.x/getting-started/quick-start-guide.mdx new file mode 100644 index 0000000..9097d0a --- /dev/null +++ b/versioned_docs/version-v0.11.x/getting-started/quick-start-guide.mdx @@ -0,0 +1,307 @@ +--- +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). + ::: + + :::tip Mac Users + For optimal compatibility and to avoid buildpack build issues, we recommend using [Colima](https://github.com/abiosoft/colima) with VZ and Rosetta support: + + ```bash + colima start --vm-type=vz --vz-rosetta --cpu 4 --memory 8 + ``` + ::: +
+ +
+
+
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.dockerTag}`} + + + 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: + + Installation Success Screenshot + + :::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 + ``` +
+ +
+
+
4
+
Access the Backstage UI
+
+ + Now that your web application is deployed, access the OpenChoreo Backstage UI to explore and manage your components: + + Access the UI at: http://openchoreo.localhost:8080/ + + Default login credentials: + - Username: `admin@openchoreo.dev` + - Password: `Admin@123` + + Backstage UI Screenshot + + + Take some time to explore the interface where you can: + - View your deployed components + - Monitor application status + - Access component catalogs + - Manage deployment pipelines + + :::note + To access advanced features like **CI/CD pipelines** (Build Plane) and **Observability** (Observability Plane) within the UI, you can enable them by including the following flags during installation: + + {`./install.sh --version ${versions.dockerTag} --with-build --with-observability`} + + ::: + +
+ +
+ + ### 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](/docs/reference/api/platform/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 + ``` + + #### 3. UI Architecture + + The Backstage UI is powered by the OpenChoreo Backstage plugin, providing a unified interface for managing your components and deployments. The authentication and user management is handled by Asgardio, a lightweight identity management platform that secures access to your OpenChoreo environment. + + :::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.dockerTag} --with-build`} + + ::: + + This demonstrates: + - Building container images from source + - Storing images in the integrated container registry + - Deploying the built image to the Data Plane + +
+ +
+
+
5
+
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.11.x/getting-started/try-it-out/on-managed-kubernetes.mdx b/versioned_docs/version-v0.11.x/getting-started/try-it-out/on-managed-kubernetes.mdx new file mode 100644 index 0000000..a4bbedc --- /dev/null +++ b/versioned_docs/version-v0.11.x/getting-started/try-it-out/on-managed-kubernetes.mdx @@ -0,0 +1,676 @@ +--- +title: On Managed Kubernetes +description: Try OpenChoreo on managed Kubernetes services (GKE, EKS, AKS) with automatic TLS using nip.io domains. +sidebar_position: 2 +--- + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; +import Link from '@docusaurus/Link'; +import {versions} from '../../_constants.mdx'; + +# On Managed Kubernetes + +Try OpenChoreo on managed Kubernetes services (GKE, EKS, AKS, etc.) with automatic TLS certificates. This guide uses [nip.io](https://nip.io) for free wildcard DNS based on your LoadBalancer IP. + +**What you'll get:** +- OpenChoreo with real TLS certificates (Let's Encrypt) +- Single cluster deployment +- Access via `*.nip.io` domains +- ~30 minutes to complete + +## Prerequisites + +- **Kubernetes 1.32+** cluster with at least 3 nodes (4 CPU, 8GB RAM each) +- **LoadBalancer** support (cloud provider or MetalLB) +- **Public IP** accessible from the internet (for Let's Encrypt HTTP-01 validation) +- **[kubectl](https://kubernetes.io/docs/tasks/tools/)** v1.32+ configured to access your cluster +- **[Helm](https://helm.sh/docs/intro/install/)** v3.12+ +- **cert-manager** installed in your cluster + +```bash +kubectl version +helm version --short +kubectl get nodes +kubectl auth can-i '*' '*' --all-namespaces +``` + +
+Install cert-manager with Gateway API support + +Install Gateway API CRDs (required for cert-manager to issue certificates via Gateway): + +```bash +kubectl apply -f "https://github.com/kubernetes-sigs/gateway-api/releases/download/v1.2.0/standard-install.yaml" +``` + +Install cert-manager with Gateway API support enabled: + +```bash +helm upgrade --install cert-manager oci://quay.io/jetstack/charts/cert-manager \ + --namespace cert-manager \ + --create-namespace \ + --set crds.enabled=true \ + --set config.apiVersion="controller.config.cert-manager.io/v1alpha1" \ + --set config.kind="ControllerConfiguration" \ + --set config.enableGatewayAPI=true +``` + +Wait for cert-manager to be ready: + +```bash +kubectl wait --for=condition=available deployment/cert-manager -n cert-manager --timeout=120s +``` + +
+ +--- + +## Step 1: Setup Control Plane + + +{`helm upgrade --install openchoreo-control-plane ${versions.helmSource}/openchoreo-control-plane \\ + --version ${versions.helmChart} \\ + --namespace openchoreo-control-plane \\ + --create-namespace \\ + --set global.baseDomain=placeholder.nip.io \\ + --set thunder.configuration.server.publicUrl=http://thunder.openchoreo.placeholder.nip.io \\ + --set thunder.configuration.gateClient.hostname=thunder.openchoreo.placeholder.nip.io`} + + +This does an initial deployment with placeholder values. We'll update it with the real domain once we know the LoadBalancer IP. + +This installs: + +- `controller-manager`: the controllers that reconcile OpenChoreo resources and manage the platform lifecycle. +- `openchoreo-api`: REST API server that the console and CLI talk to. +- `backstage`: the web console for managing your platform. +- `thunder`: built-in identity provider handling authentication and OAuth flows. +- `cluster-gateway`: accepts WebSocket connections from cluster-agents in remote planes. +- `kgateway`: gateway controller for routing external traffic to services. +- OpenChoreo CRDs: Organization, Project, Component, Environment, DataPlane, BuildPlane, and others that define the platform's API. + +The control plane is OpenChoreo's brain. In production, you'd typically run this in its own dedicated cluster, isolated from your workloads. + +For all available configuration options, see the [Control Plane Helm Reference](../../reference/helm/control-plane.mdx). + +**Get LoadBalancer IP** + + + + +Wait for LoadBalancer to get an external IP (press Ctrl+C once EXTERNAL-IP appears): + +```bash +kubectl get svc gateway-default -n openchoreo-control-plane -w +``` + +Get the IP address: + +```bash +CP_LB_IP=$(kubectl get svc gateway-default -n openchoreo-control-plane -o jsonpath='{.status.loadBalancer.ingress[0].ip}') +``` + + + + +EKS LoadBalancers are private by default and return a hostname instead of an IP. + +Make the LoadBalancer internet-facing: + +```bash +kubectl patch svc gateway-default -n openchoreo-control-plane \ + -p '{"metadata":{"annotations":{"service.beta.kubernetes.io/aws-load-balancer-scheme":"internet-facing"}}}' +``` + +Wait for the new LoadBalancer to be provisioned (this may take 1-2 minutes). Press Ctrl+C once EXTERNAL-IP (hostname) appears: + +```bash +kubectl get svc gateway-default -n openchoreo-control-plane -w +``` + +Get the hostname and resolve to IP: + +```bash +CP_LB_HOSTNAME=$(kubectl get svc gateway-default -n openchoreo-control-plane -o jsonpath='{.status.loadBalancer.ingress[0].hostname}') +CP_LB_IP=$(dig +short $CP_LB_HOSTNAME | head -1) +``` + + + + +**Configure Domain and TLS** + +Set domain variable (converts IP to nip.io format): + +```bash +export CP_DOMAIN="openchoreo.${CP_LB_IP//./-}.nip.io" +echo "Control Plane Domain: $CP_DOMAIN" +``` + +Create Issuer and Certificate: + +```bash +kubectl apply -f - < +{`helm upgrade --install openchoreo-control-plane ${versions.helmSource}/openchoreo-control-plane \\ + --version ${versions.helmChart} \\ + --namespace openchoreo-control-plane \\ + --reuse-values \\ + --set global.baseDomain=\${CP_DOMAIN} \\ + --set global.tls.enabled=true \\ + --set global.tls.secretName=control-plane-tls \\ + --set thunder.configuration.server.publicUrl=https://thunder.\${CP_DOMAIN} \\ + --set thunder.configuration.gateClient.hostname=thunder.\${CP_DOMAIN} \\ + --set thunder.configuration.gateClient.port=443 \\ + --set thunder.configuration.gateClient.scheme="https"`} + + +This upgrades the control plane with these settings: + +- `global.baseDomain`: the real nip.io domain based on your LoadBalancer IP. +- `global.tls.enabled` and `global.tls.secretName`: enables TLS using the certificate we just created. +- `thunder.configuration.*`: updates Thunder to use HTTPS on port 443. + +--- + +## Step 2: Setup Data Plane + + +{`helm upgrade --install openchoreo-data-plane ${versions.helmSource}/openchoreo-data-plane \\ + --version ${versions.helmChart} \\ + --namespace openchoreo-data-plane \\ + --set gateway.httpPort=19080 \\ + --set gateway.httpsPort=19443 \\ + --create-namespace`} + + +This installs the data plane into the `openchoreo-data-plane` namespace, with these settings: + +- `gateway.httpPort` and `gateway.httpsPort`: the ports where KGateway listens for traffic to your applications. + +This installs: + +- `cluster-agent`: maintains a WebSocket connection to the control plane's cluster-gateway. This is how the control plane sends deployment instructions to the data plane. +- `gateway`: KGateway with Envoy proxy that routes incoming traffic to your deployed applications. +- `fluent-bit`: collects logs from your workloads and forwards them to the observability plane. +- Gateway API CRDs: Gateway, HTTPRoute, and other resources for traffic routing. + +The data plane is where your workloads actually run. In this guide we're installing it in the same cluster as the control plane, but in production you'd typically have it in a completely separate cluster. This separation is intentional: your application code never runs alongside the control plane, and the control plane's credentials are never exposed to your workloads. + +For all available configuration options, see the [Data Plane Helm Reference](../../reference/helm/data-plane.mdx). + +**Get Gateway LoadBalancer IP** + + + + +Wait for LoadBalancer to get an external IP (press Ctrl+C once EXTERNAL-IP appears): + +```bash +kubectl get svc gateway-default -n openchoreo-data-plane -w +``` + +Get the IP address: + +```bash +DP_LB_IP=$(kubectl get svc gateway-default -n openchoreo-data-plane -o jsonpath='{.status.loadBalancer.ingress[0].ip}') +``` + + + + +Make the LoadBalancer internet-facing: + +```bash +kubectl patch svc gateway-default -n openchoreo-data-plane \ + -p '{"metadata":{"annotations":{"service.beta.kubernetes.io/aws-load-balancer-scheme":"internet-facing"}}}' +``` + +Wait for the new LoadBalancer to be provisioned (this may take 1-2 minutes). Press Ctrl+C once EXTERNAL-IP (hostname) appears: + +```bash +kubectl get svc gateway-default -n openchoreo-data-plane -w +``` + +Get the hostname and resolve to IP: + +```bash +DP_LB_HOSTNAME=$(kubectl get svc gateway-default -n openchoreo-data-plane -o jsonpath='{.status.loadBalancer.ingress[0].hostname}') +DP_LB_IP=$(dig +short $DP_LB_HOSTNAME | head -1) +``` + + + + +**Configure Domain** + +```bash +export DP_DOMAIN="apps.openchoreo.${DP_LB_IP//./-}.nip.io" +echo "Data Plane Domain: $DP_DOMAIN" +``` + +**Configure TLS** + +```bash +kubectl apply -f - < +{`helm upgrade --install openchoreo-data-plane ${versions.helmSource}/openchoreo-data-plane \\ + --version ${versions.helmChart} \\ + --namespace openchoreo-data-plane \\ + --reuse-values \\ + --set gateway.tls.hostname=\${DP_DOMAIN}`} + + +**Register with the Control Plane** + +```bash +CA_CERT=$(kubectl get secret cluster-agent-tls -n openchoreo-data-plane -o jsonpath='{.data.ca\.crt}' | base64 -d) +``` + +The control plane only accepts agent connections signed by a CA it recognizes. When you installed the data plane, cert-manager generated a CA and used it to sign the cluster-agent's client certificate. This command extracts that CA so you can tell the control plane about it. + +```bash +kubectl apply -f - < +{`helm upgrade --install openchoreo-build-plane ${versions.helmSource}/openchoreo-build-plane \\ + --version ${versions.helmChart} \\ + --namespace openchoreo-build-plane \\ + --create-namespace \\ + --set clusterAgent.enabled=true \\ + --set global.baseDomain=\${CP_DOMAIN} \\ + --set global.tls.enabled=true \\ + --set global.tls.secretName=registry-tls \\ + --set external-secrets.enabled=false`} + + +This installs the build plane with these settings: + +- `global.baseDomain`: used to construct the registry URL at `registry.`. +- `global.tls.enabled` and `global.tls.secretName`: enables TLS for the registry using the Let's Encrypt certificate. +- `clusterAgent.enabled`: enables the cluster-agent for communication with the control plane. + +This installs: + +- `cluster-agent`: connects to the control plane to receive build instructions. +- `argo-workflows`: executes the actual build pipelines as Kubernetes workflows. +- `registry`: a container registry that stores your built images. +- Argo Workflows CRDs: Workflow, WorkflowTemplate, and other resources for defining build pipelines. + +Like the data plane, the build plane could run in a completely separate cluster if you wanted to isolate your CI workloads. + +For all available configuration options, see the [Build Plane Helm Reference](../../reference/helm/build-plane.mdx). + +**Register with the Control Plane** + +```bash +BP_CA_CERT=$(kubectl get secret cluster-agent-tls -n openchoreo-build-plane -o jsonpath='{.data.ca\.crt}' | base64 -d) + +kubectl apply -f - < +{`helm upgrade --install openchoreo-observability-plane ${versions.helmSource}/openchoreo-observability-plane \\ + --version ${versions.helmChart} \\ + --namespace openchoreo-observability-plane \\ + --create-namespace \\ + --set openSearch.enabled=true \\ + --set openSearchCluster.enabled=false \\ + --set security.oidc.jwksUrl="https://thunder.\${CP_DOMAIN}/oauth2/jwks" \\ + --set security.oidc.tokenUrl="https://thunder.\${CP_DOMAIN}/oauth2/token" \\ + --set external-secrets.enabled=false \\ + --set clusterAgent.enabled=true \\ + --timeout 10m`} + + +This installs the observability plane with these settings: + +- `openSearch.enabled`: deploys OpenSearch for storing logs and traces. +- `openSearchCluster.enabled`: set to false to use the simpler single-node deployment instead of the operator-based cluster. +- `security.oidc.jwksUrl`: the JWKS endpoint for validating JWT tokens. This points to Thunder's JWKS endpoint (using HTTPS since we configured TLS) so the Observer API can authenticate requests. + +This installs: + +- `cluster-agent`: connects to the control plane. +- `opensearch`: stores logs and traces from your workloads. +- `observer`: REST API that abstracts OpenSearch. The console and other components query logs through this instead of talking to OpenSearch directly. +- `opentelemetry-collector`: receives traces and metrics from your applications. + +The observability plane collects logs, metrics, and traces from your data and build planes. Like the other planes, it could run in a completely separate cluster in production. + +For all available configuration options, see the [Observability Plane Helm Reference](../../reference/helm/observability-plane.mdx). + +**Register with the Control Plane** + +```bash +OP_CA_CERT=$(kubectl get secret cluster-agent-tls -n openchoreo-observability-plane -o jsonpath='{.data.ca\.crt}' | base64 -d) + +kubectl apply -f - <-.${DP_DOMAIN}` | +| Registry | `https://registry.${CP_DOMAIN}` (if Build Plane installed) | + +**Default credentials:** `admin@openchoreo.dev` / `Admin@123` + +:::info Two Different IPs +The Control Plane and Data Plane have separate LoadBalancer IPs. nip.io resolves based on the IP embedded in the hostname, so `openchoreo.1-2-3-4.nip.io` resolves to `1.2.3.4`. This means your console and your deployed apps can have completely different IPs, which is actually how you'd set things up in production with separate clusters. +::: + +--- + +## Moving to Production + +This guide provides a quick way to explore OpenChoreo. For production deployments, follow these guides to harden your setup: + +1. **Identity & Security**: Replace default credentials with a real Identity Provider. + - [Identity Configuration](../../operations/identity-configuration.mdx) (Google, Okta, etc.) + - [Secret Management](../../operations/secret-management.mdx) (Vault, AWS Secrets Manager) + +2. **Networking & Domains**: Move away from nip.io to your own domains. + - [Deployment Topology](../../operations/deployment-topology.mdx) (TLS certificates, Multi-region, Multi-cluster) + +3. **Infrastructure**: Scale out and isolate your planes. + - [Multi-Cluster Connectivity](../../operations/multi-cluster-connectivity.mdx) (Isolate Control Plane from Data Planes) + - [Observability](../../operations/observability-alerting.mdx) (Configure persistent OpenSearch and retention) + +## Next Steps + +1. [Deploy your first component](../deploy-first-component.mdx) to see OpenChoreo in action. +2. Start planning your production architecture with the [Deployment Topology](../../operations/deployment-topology.mdx) guide. + +--- + +## Cleanup + +Delete plane registrations: + +```bash +kubectl delete dataplane default -n default 2>/dev/null +kubectl delete buildplane default -n default 2>/dev/null +kubectl delete observabilityplane default -n default 2>/dev/null +``` + +Uninstall OpenChoreo components: + +```bash +helm uninstall openchoreo-observability-plane -n openchoreo-observability-plane 2>/dev/null +helm uninstall openchoreo-build-plane -n openchoreo-build-plane 2>/dev/null +helm uninstall openchoreo-data-plane -n openchoreo-data-plane +helm uninstall openchoreo-control-plane -n openchoreo-control-plane +helm uninstall cert-manager -n cert-manager +``` + +Delete namespaces: + +```bash +kubectl delete namespace openchoreo-control-plane openchoreo-data-plane openchoreo-build-plane openchoreo-observability-plane cert-manager 2>/dev/null +``` + +Delete CRDs: + +```bash +kubectl get crd -o name | grep -E '\.openchoreo\.dev$' | xargs -r kubectl delete +kubectl get crd -o name | grep -E '\.cert-manager\.io$' | xargs -r kubectl delete +``` + +--- + +## Troubleshooting + +### Certificate not issuing + +```bash +kubectl describe certificate control-plane-tls -n openchoreo-control-plane +kubectl get challenges -A +kubectl describe issuer letsencrypt-http01 -n openchoreo-control-plane +``` + +Common issues: +- LoadBalancer not publicly accessible (HTTP-01 validation requires public access) +- Firewall blocking port 80 +- Rate limits (Let's Encrypt has [rate limits](https://letsencrypt.org/docs/rate-limits/)) + +### Agent not connecting + +```bash +kubectl logs -n openchoreo-data-plane -l app=cluster-agent --tail=20 +kubectl logs -n openchoreo-control-plane -l app=cluster-gateway --tail=20 +``` + +Look for connection errors in the logs. Common issues: +- **PlaneID mismatch**: The `planeID` in the plane CR must match the `clusterAgent.planeId` Helm value +- CA certificate mismatch + +### Wildcard certificates with HTTP-01 validation + +HTTP-01 validation cannot be used for wildcard certificates (`*.domain.com`). The data plane gateway uses a wildcard hostname by default. + +Options: +- **Self-signed certificates:** Use the default self-signed issuer (what this guide does) +- **DNS-01 validation:** Configure a DNS provider for Let's Encrypt DNS-01 validation +- **Non-wildcard hostname:** Configure a specific hostname instead of wildcard diff --git a/versioned_docs/version-v0.11.x/getting-started/try-it-out/on-self-hosted-kubernetes.mdx b/versioned_docs/version-v0.11.x/getting-started/try-it-out/on-self-hosted-kubernetes.mdx new file mode 100644 index 0000000..f017adb --- /dev/null +++ b/versioned_docs/version-v0.11.x/getting-started/try-it-out/on-self-hosted-kubernetes.mdx @@ -0,0 +1,631 @@ +--- +title: On Self-Hosted Kubernetes +description: Run OpenChoreo on any self-hosted Kubernetes cluster - local machine, VM, or on-premise. Zero cloud costs. +sidebar_position: 1 +--- + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; +import Link from '@docusaurus/Link'; +import {versions} from '../../_constants.mdx'; + +# On Self-Hosted Kubernetes + +Try OpenChoreo on any self-hosted Kubernetes cluster, whether it's running on your laptop, a VM, or on-premise environment. This is the fastest way to explore OpenChoreo without cloud provider costs. + +**What you'll get:** +- Full OpenChoreo installation on your cluster +- All four planes: Control, Data, Build, and Observability +- Access via `.localhost` domains +- ~15-20 minutes to complete + +## Prerequisites + + + + +[k3d](https://k3d.io) runs k3s in Docker containers. + +- **Docker** v26.0+ with at least **8 GB RAM** and **4 CPU** cores allocated +- **Disk space**: ~10 GB free +- **[k3d](https://k3d.io/stable/#installation)** v5.8+ +- **[kubectl](https://kubernetes.io/docs/tasks/tools/)** v1.32+ +- **[Helm](https://helm.sh/docs/intro/install/)** v3.12+ + +```bash +docker --version && docker info > /dev/null +k3d --version +kubectl version --client +helm version --short +``` + +:::tip Mac Users +For optimal compatibility and to avoid buildpack build issues, we recommend using [Colima](https://github.com/abiosoft/colima) with VZ and Rosetta support: + +```bash +colima start --vm-type=vz --vz-rosetta --cpu 4 --memory 8 +``` +::: + +:::note Colima Users +Set `K3D_FIX_DNS=0` when creating clusters to avoid DNS issues. See [k3d-io/k3d#1449](https://github.com/k3d-io/k3d/issues/1449). +::: + +**Create Cluster** + + +{`curl -s https://raw.githubusercontent.com/openchoreo/openchoreo/${versions.githubRef}/install/k3d/single-cluster/config.yaml | k3d cluster create --config=-`} + + +This creates a cluster named `openchoreo` with port mappings for Control Plane (8080/8443), Data Plane (19080/19443), and Build Plane (10081). Your kubectl context is automatically set to `k3d-openchoreo`. + +:::note Generate machine id (Required if Observability will be enabled) + +Fluent Bit (used for observability log collection) requires a unique Machine ID (/etc/machine-id) to start. By default, k3d node containers do not generate this file. +If you are enabling observability, you must manually generate this ID on every node in your cluster before installation: + +```bash +docker exec sh -c "cat /proc/sys/kernel/random/uuid | tr -d '-' > /etc/machine-id" +``` + +For example, to generate the machine ID for the k3d-openchoreo-op-server-0 node: + +```bash +docker exec k3d-openchoreo-op-server-0 sh -c "cat /proc/sys/kernel/random/uuid | tr -d '-' > /etc/machine-id" +``` + +::: + +**Install cert-manager** + +```bash +helm upgrade --install cert-manager oci://quay.io/jetstack/charts/cert-manager \ + --namespace cert-manager \ + --create-namespace \ + --set crds.enabled=true +``` + +Wait for cert-manager to be ready: + +```bash +kubectl wait --for=condition=available deployment/cert-manager -n cert-manager --timeout=120s +``` + + + + +- **Kubernetes 1.32+** cluster with at least **8 GB RAM** and **4 CPU** cores +- **[kubectl](https://kubernetes.io/docs/tasks/tools/)** v1.32+ configured to access your cluster +- **[Helm](https://helm.sh/docs/intro/install/)** v3.12+ +- **cert-manager** installed in your cluster + +:::note Rancher Desktop Users +Use **containerd** as the container runtime. If you plan to use the Build Plane, configure your runtime to allow HTTP registries before proceeding—see the note in [Step 3: Setup Build Plane](#step-3-setup-build-plane-optional). +::: + +```bash +kubectl version +helm version --short +kubectl get nodes +kubectl auth can-i '*' '*' --all-namespaces +``` + +**Note Your Ingress Configuration** + +Check if you have an ingress controller: + +```bash +kubectl get ingressclass +``` + +Common configurations: +- **Rancher Desktop**: Built-in Traefik on ports 80/443, class name `traefik` +- **Docker Desktop**: No default ingress +- **OrbStack**: Built-in ingress on ports 80/443 + +:::warning Free Up Ports 80/443 +OpenChoreo's control plane gateway needs to bind to ports 80/443. If you have Traefik or another ingress controller running on these ports, you must either: + +- Disable it (e.g., for Rancher Desktop: disable Traefik in Preferences → Kubernetes) +- Configure it to use different ports + +You can verify port availability with: + +```bash +# Check if anything is listening on port 80 +lsof -i :80 +``` + +::: + + + + +--- + +## Step 1: Setup Control Plane + +:::note macOS Users +Due to Rosetta emulation issues, macOS users (Rancher Desktop, Docker Desktop, k3d, kind, or Colima) should add `--set gateway.envoy.mountTmpVolume=true`. Non-macOS users can omit this flag if needed. +::: + + + + + {`helm upgrade --install openchoreo-control-plane ${versions.helmSource}/openchoreo-control-plane \\ + --version ${versions.helmChart} \\ + --namespace openchoreo-control-plane \\ + --create-namespace \\ + --set global.baseDomain=openchoreo.localhost \\ + --set global.port=":8080" \\ + --set gateway.httpPort=80 \\ + --set gateway.httpsPort=443 \\ + --set thunder.configuration.server.publicUrl=http://thunder.openchoreo.localhost:8080 \\ + --set thunder.configuration.gateClient.hostname=thunder.openchoreo.localhost \\ + --set thunder.configuration.gateClient.port=8080 \\ + --set thunder.configuration.gateClient.scheme="http" \\ + --set gateway.envoy.mountTmpVolume=true`} + + + + + + + {`helm upgrade --install openchoreo-control-plane ${versions.helmSource}/openchoreo-control-plane \\ + --version ${versions.helmChart} \\ + --namespace openchoreo-control-plane \\ + --create-namespace \\ + --set global.baseDomain=openchoreo.localhost \\ + --set global.port=":80" \\ + --set gateway.httpPort=80 \\ + --set gateway.httpsPort=443 \\ + --set thunder.configuration.server.publicUrl=http://thunder.openchoreo.localhost:80 \\ + --set thunder.configuration.gateClient.hostname=thunder.openchoreo.localhost \\ + --set thunder.configuration.gateClient.port=80 \\ + --set thunder.configuration.gateClient.scheme="http" \\ + --set gateway.envoy.mountTmpVolume=true`} + + + + + +This installs the control plane into the `openchoreo-control-plane` namespace, with these settings: + +- `global.baseDomain`: the base domain for all services. The console will be at `openchoreo.localhost`, the API at `api.openchoreo.localhost`. +- `global.port`: appended to URLs since we're using non-standard port 8080. +- `gateway.httpPort` and `gateway.httpsPort`: the ports where KGateway listens for incoming traffic. +- `thunder.configuration.*`: configures Thunder, the built-in identity provider. These settings tell Thunder where it's accessible and how to reach the API gateway. + +This installs: + +- `controller-manager`: the controllers that reconcile OpenChoreo resources and manage the platform lifecycle. +- `openchoreo-api`: REST API server that the console and CLI talk to. +- `backstage`: the web console for managing your platform. +- `thunder`: built-in identity provider handling authentication and OAuth flows. +- `cluster-gateway`: accepts WebSocket connections from cluster-agents in remote planes. +- `kgateway`: gateway controller for routing external traffic to services. +- OpenChoreo CRDs: Organization, Project, Component, Environment, DataPlane, BuildPlane, and others that define the platform's API. + +The control plane is OpenChoreo's brain. In production, you'd typically run this in its own dedicated cluster, isolated from your workloads. + +For all available configuration options, see the [Control Plane Helm Reference](../../reference/helm/control-plane.mdx). + +```bash +kubectl wait -n openchoreo-control-plane --for=condition=available --timeout=300s deployment --all +kubectl wait -n openchoreo-control-plane --for=condition=complete job --all +``` + +Create a Certificate for Gateway TLS: + +```bash +kubectl apply -f - < + {`helm upgrade --install openchoreo-data-plane ${versions.helmSource}/openchoreo-data-plane \\ + --version ${versions.helmChart} \\ + --namespace openchoreo-data-plane \\ + --create-namespace \\ + --set gateway.httpPort=19080 \\ + --set gateway.httpsPort=19443 \\ + --set external-secrets.enabled=true \\ + --set gatewayController.enabled=false \\ + --set gateway.envoy.mountTmpVolume=true \\ + --set gateway.selfSignedIssuer.enabled=false`} + + +This installs the data plane into the `openchoreo-data-plane` namespace, with these settings: + +- `gateway.httpPort` and `gateway.httpsPort`: the ports where KGateway listens for traffic to your applications. We use 19080/19443 to keep it distinct from the control plane's ports. +- `external-secrets.enabled`: installs the External Secrets Operator for syncing secrets from external stores. +- `gateway.envoy.mountTmpVolume`: fixes Envoy crashes on macOS. Non-macOS users can omit this flag. + +This installs: + +- `cluster-agent`: maintains a WebSocket connection to the control plane's cluster-gateway. This is how the control plane sends deployment instructions to the data plane. +- `gateway`: KGateway with Envoy proxy that routes incoming traffic to your deployed applications. +- `fluent-bit`: collects logs from your workloads and forwards them to the observability plane. +- `external-secrets`: syncs secrets from external secret stores like Vault or AWS Secrets Manager. +- Gateway API CRDs: Gateway, HTTPRoute, and other resources for traffic routing. + +The data plane is where your workloads actually run. In this guide we're installing it in the same cluster as the control plane, but in production you'd typically have it in a completely separate cluster. This separation is intentional: your application code never runs alongside the control plane, and the control plane's credentials are never exposed to your workloads. + +For all available configuration options, see the [Data Plane Helm Reference](../../reference/helm/data-plane.mdx). + +**Create a Certificate for Gateway TLS** + +```bash +kubectl apply -f - < + + + +{`helm upgrade --install openchoreo-build-plane ${versions.helmSource}/openchoreo-build-plane \\ + --version ${versions.helmChart} \\ + --namespace openchoreo-build-plane \\ + --create-namespace \\ + --set external-secrets.enabled=false \\ + --set global.defaultResources.registry.endpoint=host.k3d.internal:10082 \\ + --set registry.service.type=LoadBalancer`} + + +This installs the build plane with these settings: + +- `global.defaultResources.registry.endpoint`: the address where built images are pushed and pulled. `host.k3d.internal` is a special hostname that k3d nodes can resolve to the host machine. +- `registry.service.type`: exposes the registry via LoadBalancer so it's accessible from outside the cluster. + +This installs: + +- `cluster-agent`: connects to the control plane to receive build instructions. +- `argo-workflows`: executes the actual build pipelines as Kubernetes workflows. +- `registry`: a container registry that stores your built images. +- Argo Workflows CRDs: Workflow, WorkflowTemplate, and other resources for defining build pipelines. + +For all available configuration options, see the [Build Plane Helm Reference](../../reference/helm/build-plane.mdx). + + + + + +{`helm upgrade --install openchoreo-build-plane ${versions.helmSource}/openchoreo-build-plane \\ + --version ${versions.helmChart} \\ + --namespace openchoreo-build-plane \\ + --create-namespace \\ + --set external-secrets.enabled=false \\ + --set global.defaultResources.registry.endpoint= \\ + --set registry.service.type=LoadBalancer \\ + --set registry.service.port=10082`} + + +This installs the build plane with these settings: + +- `global.defaultResources.registry.endpoint`: the address where built images are pushed and pulled. This needs to be accessible from both the build pods (for pushing) and the kubelet (for pulling). Common values are `host.docker.internal:10082` or your node's IP address. +- `registry.service.type` and `registry.service.port`: exposes the registry via LoadBalancer. + +This installs: + +- `cluster-agent`: connects to the control plane to receive build instructions. +- `argo-workflows`: executes the actual build pipelines as Kubernetes workflows. +- `registry`: a container registry that stores your built images. +- Argo Workflows CRDs: Workflow, WorkflowTemplate, and other resources for defining build pipelines. + +For all available configuration options, see the [Build Plane Helm Reference](../../reference/helm/build-plane.mdx). + +:::note HTTP Registry Access +The Build Plane deploys an HTTP container registry. Container runtimes default to HTTPS for registries. If image pulls fail with "http: server gave HTTP response to HTTPS client", configure your container runtime to allow HTTP for this registry. For Rancher Desktop users, see [Configuring Private Registries](https://docs.rancherdesktop.io/how-to-guides/mirror-private-registry/). +::: + + + + +**Register with the Control Plane** + +```bash +BP_CA_CERT=$(kubectl get secret cluster-agent-tls -n openchoreo-build-plane -o jsonpath='{.data.ca\.crt}' | base64 -d) + +kubectl apply -f - < +{`helm upgrade --install openchoreo-observability-plane ${versions.helmSource}/openchoreo-observability-plane \\ + --version ${versions.helmChart} \\ + --namespace openchoreo-observability-plane \\ + --create-namespace \\ + --set openSearch.enabled=true \\ + --set openSearchCluster.enabled=false \\ + --set security.oidc.jwksUrl="http://thunder-service.openchoreo-control-plane.svc.cluster.local:8090/oauth2/jwks" \\ + --set security.oidc.tokenUrl="http://thunder-service.openchoreo-control-plane.svc.cluster.local:8090/oauth2/token" \\ + --set external-secrets.enabled=false \\ + --timeout 10m`} + + +This installs the observability plane with these settings: + +- `openSearch.enabled`: deploys OpenSearch for storing logs and traces. +- `openSearchCluster.enabled`: set to false to use the simpler single-node deployment instead of the operator-based cluster. +- `security.oidc.jwksUrl`: the JWKS endpoint for validating JWT tokens. This points to Thunder's JWKS endpoint so the Observer API can authenticate requests. + +This installs: + +- `cluster-agent`: connects to the control plane. +- `opensearch`: stores logs and traces from your workloads. +- `observer`: REST API that abstracts OpenSearch. The console and other components query logs through this instead of talking to OpenSearch directly. +- `opentelemetry-collector`: receives traces and metrics from your applications. +- `prometheus`: collects metrics from your workloads (via kube-prometheus-stack). + +The observability plane collects logs, metrics, and traces from your data and build planes. Like the other planes, it could run in a completely separate cluster in production. + +For all available configuration options, see the [Observability Plane Helm Reference](../../reference/helm/observability-plane.mdx). + +**Register with the Control Plane** + +```bash +OP_CA_CERT=$(kubectl get secret cluster-agent-tls -n openchoreo-observability-plane -o jsonpath='{.data.ca\.crt}' | base64 -d) + +kubectl apply -f - < +{`helm upgrade --install openchoreo-observability-plane ${versions.helmSource}/openchoreo-observability-plane \\ + --version ${versions.helmChart} \\ + --namespace openchoreo-observability-plane \\ + --reuse-values \\ + --set fluent-bit.enabled=true \\ + --timeout 10m`} + + +--- + +## Access OpenChoreo + +| Service | URL | +|---------|-----| +| Console | `http://openchoreo.localhost:8080` | +| API | `http://api.openchoreo.localhost:8080` | +| Deployed Apps | `http://.openchoreoapis.localhost:19080//...` | + +**Default credentials:** `admin@openchoreo.dev` / `Admin@123` + +:::tip Remote Cluster Access +If your cluster is running on a remote VM or server, use SSH tunneling to access OpenChoreo from your local machine: + +```bash +ssh -L 8080:localhost:8080 \ + -L 8443:localhost:8443 \ + -L 19080:localhost:19080 \ + -L 19443:localhost:19443 \ + user@remote-host +``` + +This forwards the Control Plane UI (8080/8443) and Data Plane Gateway (19080/19443) to your local machine. Keep this SSH session open and access OpenChoreo via `http://openchoreo.localhost:8080` in your local browser. +::: + +--- + +## Moving to Production + +This guide provides a quick way to explore OpenChoreo. For production deployments, follow these guides to harden your setup: + +1. **Identity & Security**: Replace default credentials with a real Identity Provider. + - [Identity Configuration](../../operations/identity-configuration.mdx) (Google, Okta, etc.) + - [Secret Management](../../operations/secret-management.mdx) (Vault, AWS Secrets Manager) + +2. **Networking & Domains**: Move away from localhost to your own domains. + - [Deployment Topology](../../operations/deployment-topology.mdx) (TLS certificates, Multi-region, Multi-cluster) + +3. **Infrastructure**: Scale out and isolate your planes. + - [Multi-Cluster Connectivity](../../operations/multi-cluster-connectivity.mdx) (Isolate Control Plane from Data Planes) + - [Observability](../../operations/observability-alerting.mdx) (Configure persistent OpenSearch and retention) + +## Next Steps + +1. [Deploy your first component](../deploy-first-component.mdx) to see OpenChoreo in action. +2. Explore the sample applications. + +--- + +## Cleanup + +Uninstall OpenChoreo components: + +```bash +helm uninstall openchoreo-observability-plane -n openchoreo-observability-plane 2>/dev/null +helm uninstall openchoreo-build-plane -n openchoreo-build-plane 2>/dev/null +helm uninstall openchoreo-data-plane -n openchoreo-data-plane +helm uninstall openchoreo-control-plane -n openchoreo-control-plane +helm uninstall cert-manager -n cert-manager +``` + +Delete namespaces and plane registrations: + +```bash +kubectl delete dataplane default -n default 2>/dev/null +kubectl delete buildplane default -n default 2>/dev/null +kubectl delete observabilityplane default -n default 2>/dev/null +kubectl delete namespace openchoreo-control-plane openchoreo-data-plane openchoreo-build-plane openchoreo-observability-plane cert-manager 2>/dev/null +``` + +If you created a k3d cluster for this guide: + +```bash +k3d cluster delete openchoreo +``` + +--- + +## Troubleshooting + +### Pods stuck in Pending + +```bash +kubectl describe pod -n +``` + +Common causes: +- Insufficient resources (increase RAM/CPU allocation) +- PVC issues (check storage provisioner) + +### Agent not connecting + +```bash +kubectl logs -n openchoreo-data-plane -l app=cluster-agent --tail=20 +kubectl logs -n openchoreo-control-plane -l app=cluster-gateway --tail=20 +``` + +Common issues: +- DataPlane/BuildPlane CR not created +- **PlaneID mismatch**: The `planeID` in the plane CR must match the `clusterAgent.planeId` Helm value +- CA certificate mismatch +- Network connectivity between namespaces + +### Gateway pods crash on macOS + +If you see "Failed to create temporary file" errors: + +```bash +helm upgrade openchoreo-data-plane ... --set gateway.envoy.mountTmpVolume=true +``` diff --git a/versioned_docs/version-v0.11.x/integrating-with-openchoreo/ci-integration.md b/versioned_docs/version-v0.11.x/integrating-with-openchoreo/ci-integration.md new file mode 100644 index 0000000..cab5ae3 --- /dev/null +++ b/versioned_docs/version-v0.11.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.11.x/integrating-with-openchoreo/gitops.md b/versioned_docs/version-v0.11.x/integrating-with-openchoreo/gitops.md new file mode 100644 index 0000000..f24f5a0 --- /dev/null +++ b/versioned_docs/version-v0.11.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.11.x/learn-from-examples/examples-catalog.mdx b/versioned_docs/version-v0.11.x/learn-from-examples/examples-catalog.mdx new file mode 100644 index 0000000..90bc484 --- /dev/null +++ b/versioned_docs/version-v0.11.x/learn-from-examples/examples-catalog.mdx @@ -0,0 +1,187 @@ +--- +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 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 +OpenChoreo uses a flexible ComponentType architecture where platform engineers define templates and developers create components from these templates. + +### Understanding ComponentTypes + +OpenChoreo provides a **ComponentType** abstraction that allows platform engineers to define reusable application templates with: +- Workload types (Deployment, StatefulSet, CronJob, Job, Proxy) +- Configurable parameters and environment overrides +- Kubernetes resource templates with CEL expressions + +Developers create **Component** resources that reference these ComponentTypes, providing a clean separation between platform governance and developer intent. + +### Default ComponentTypes + +OpenChoreo ships with three default ComponentTypes out of the box: + +- **`deployment/service`** – Backend services and APIs + - Configurable replicas, port, resources, and image pull policy + - Includes Deployment, Service, and optional HTTPRoute resources + - Supports environment-specific overrides + +- **`deployment/web-application`** – Frontend or full-stack web applications + - Always exposed via HTTPRoute with dedicated subdomain + - Configurable replicas, port, resources, and image pull policy + +- **`cronjob/scheduled-task`** – Time-based batch jobs and background tasks + - Configurable cron schedule, concurrency policy, and resource limits + - Environment-specific schedules for different deployment stages + +### ComponentType Examples + +Learn how to work with ComponentTypes and create custom component definitions: + +- **HTTP Service Component** – Custom ComponentType for HTTP services with routing +- **Web Application Component** – ComponentType optimized for web applications +- **Component with Configurations** – Managing Configs and Secrets with components +- **Component with Traits** – Composing reusable traits into components + +### Application Examples by Source Type + +Examples demonstrating how to deploy components using the default ComponentTypes: + +#### Built from Source + +- **Services** – Backend services & APIs built from source code + - Go Service with Docker - Go Service using Docker build + - Go Service with Buildpacks - Go Service using Google Cloud Buildpacks + - Ballerina Service - Ballerina service using Ballerina Buildpack + +- **Web Applications** – Frontend or full-stack applications built from source code + - React SPA - SPA web application + +#### Deployed from Pre-built Images + +- **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 Workflow 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 + +- **ComponentType Architecture** – Platform engineer templates and developer components with clean separation of concerns +- **Configuration Management** – Environment-specific configs and secrets using Workload resources +- **Trait Composition** – Reusable traits that extend component functionality +- **Workflow Integration for CI** – Components with integrated Workflow resources for CI/CD automation + +## 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 CI 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 +- Custom workflows + +--- + +## 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.11.x/operations/api-management.mdx b/versioned_docs/version-v0.11.x/operations/api-management.mdx new file mode 100644 index 0000000..38c1d7b --- /dev/null +++ b/versioned_docs/version-v0.11.x/operations/api-management.mdx @@ -0,0 +1,460 @@ +--- +title: API Management +description: Platform engineer guide to configure API management in OpenChoreo with vendor options and trait-based integration. +sidebar_position: 6 +--- + +import CodeBlock from "@theme/CodeBlock"; +import { versions } from "../_constants.mdx"; + +# API Management + +This guide is for platform engineers who need to configure and manage API Management capabilities in OpenChoreo. Learn how to enable the default [WSO2 API Platform](https://github.com/wso2/api-platform) and integrate external API management vendors. + +## Overview + +OpenChoreo provides a flexible, trait-based API Management architecture that supports: + +- **Default Integration**: WSO2 API Platform for out-of-the-box API management +- **Vendor Flexibility**: Integrate any API management solution through OpenChoreo custom traits +- **Declarative Configuration**: Manage API configuration as Kubernetes resources +- **Multi-Tenancy**: Isolated API management per environment or organization + +## Architecture + +OpenChoreo's API Management is built on three key components: + +1. **API Gateway**: Default WSO2 API Platform gateway, can integrate external vendors +2. **API Configuration Trait**: Declarative trait that components use to enable API management (default api-configuration trait for WSO2 API Platform or any platform engineer defined traits) +3. **Identity Provider Integration**: OAuth2/JWT token validation (Thunder IDP or any external IDP) + +### How It Works + +``` +Component + API Trait + ↓ + ReleaseBinding (applies trait) + ↓ + Release (renders API config) + ↓ + Data Plane (enforces policies via gateway) +``` + +When a component includes an API management trait, OpenChoreo: + +- Generates API gateway configuration resources based on the trait template +- Configures gateway policies like authentication and rate limiting +- Routes traffic through the configured API gateway layer + +## Prerequisites + +- OpenChoreo control plane and data plane installed +- Cluster admin access for CRD installation +- Helm 3.12+ for chart installation +- Understanding of OpenChoreo traits and component model + +## WSO2 API Platform (Default) + +OpenChoreo includes native integration with [WSO2 API Platform](https://github.com/wso2/api-platform), providing enterprise-grade API management out of the box. + +### Installation + +The API Platform module is **disabled by default** and must be explicitly enabled during data plane installation. + +#### During Initial Data Plane Installation + +Enable the API Platform module using Helm values: + + + {`helm upgrade --install openchoreo-data-plane ${versions.helmSource}/openchoreo-data-plane \\ + --version ${versions.helmChart} \\ + --namespace openchoreo-data-plane \\ + --create-namespace \\ + --set gateway.httpPort=19080 \\ + --set gateway.httpsPort=19443 \\ + --set external-secrets.enabled=true \\ + --set gateway.envoy.mountTmpVolume=true \\ + --set api-platform.enabled=true`} + + +#### Adding to Existing Data Plane + +If OpenChoreo is already installed: + +**Step 1**: Install API Platform CRDs + +```bash +kubectl apply --server-side \ + -f https://raw.githubusercontent.com/wso2/api-platform/gateway-operator-v0.1.0/kubernetes/helm/operator-helm-chart/crds/api.api-platform.wso2.com_apiconfigurations.yaml \ + -f https://raw.githubusercontent.com/wso2/api-platform/gateway-operator-v0.1.0/kubernetes/helm/operator-helm-chart/crds/api.api-platform.wso2.com_gatewayconfigurations.yaml +``` + +**Step 2**: Upgrade data plane with API Platform enabled + + + {`helm upgrade --install openchoreo-data-plane ${versions.helmSource}/openchoreo-data-plane \\ + --version ${versions.helmChart} \\ + --namespace openchoreo-data-plane \\ + --reuse-values \\ + --set api-platform.enabled=true`} + + +### Verify Installation + +Confirm all API Platform components are running: + +```bash +kubectl get pods -n openchoreo-data-plane --selector="app.kubernetes.io/instance=api-platform-default-gateway" +``` + +Expected output: + +``` +NAME READY STATUS RESTARTS AGE +api-platform-default-gateway-controller-6d574f8478-skd8n 1/1 Running 0 2m +api-platform-default-gateway-policy-engine-6ccc5f76b4-m87f7 1/1 Running 0 2m +api-platform-default-gateway-router-55cd96cfc9-njf56 1/1 Running 0 2m +``` + +### Configuration Options + +The WSO2 API Platform module supports extensive configuration via Helm values: + +```yaml +api-platform: + enabled: false + gateway: + helm: + chartName: "oci://ghcr.io/wso2/api-platform/helm-charts/gateway" + values: + gateway: + config: + policy_configurations: + JWTAuth_v010: + KeyManagers: + - name: ThunderKeyManager + issuer: thunder + jwks: + remote: + uri: http://thunder-service.openchoreo-control-plane:8090/oauth2/jwks + skipTlsVerify: true + JwksCacheTtl: "5m" + JwksFetchTimeout: "5s" + JwksFetchRetryCount: 3 + JwksFetchRetryInterval: "2s" + AllowedAlgorithms: + - RS256 + - ES256 + Leeway: "30s" + AuthHeaderScheme: Bearer + HeaderName: Authorization + OnFailureStatusCode: 401 + ErrorMessageFormat: json + ErrorMessage: "Authentication failed." + ValidateIssuer: true +``` + +### API Configuration Trait Reference + +The `api-configuration` trait is the primary way components enable API management with WSO2 API Platform. + +#### Trait Schema + +```yaml +apiVersion: openchoreo.dev/v1alpha1 +kind: Component +metadata: + name: my-service +spec: + traits: + - name: api-configuration + instanceName: my-api # Unique name for this API instance + parameters: + # Required parameters + apiName: string # API identifier + apiVersion: string # API version (e.g., v1.0, v2.0) + context: string # API context path (e.g., /my-api/v1.0) + upstreamPort: integer # Target service port (typically 80) + + # Optional parameters + policies: # Authentication and security policies + - name: string # Policy name (e.g., JwtAuthentication) + version: string # Policy version (e.g., v0.1.0) + parameters: object # Policy-specific configuration + operations: # By default operations are /* for GET, POST, PATCH, PUT, DELETE, OPTIONS + - method: string # HTTP method (GET, POST, PUT, DELETE, PATCH, OPTIONS) + path: string # API path pattern (e.g., /books, /*) +``` + +## External API Management Vendors + +OpenChoreo's trait-based architecture allows integration with any API management solution. You can create custom traits that integrate with vendors like Kong, Apigee, AWS API Gateway, or Azure API Management. + +### Integration Architecture + +External API management integration works through OpenChoreo traits: + +``` +Component + Custom API Trait + ↓ + Trait Template (your implementation) + ↓ + Vendor-Specific Resources (ConfigMaps, Secrets, CRDs) + ↓ + External API Gateway +``` + +### Creating a Custom API Management Trait + +Custom traits allow you to define how OpenChoreo components integrate with your API management solution. The trait structure follows the same pattern as the default `api-configuration` trait. + +#### Example: Kong Gateway Integration + +```yaml +apiVersion: openchoreo.dev/v1alpha1 +kind: Trait +metadata: + name: kong-api-management + namespace: default +spec: + schema: + types: + Plugin: + name: "string" + config: "map" + + parameters: + # Developer-facing parameters + apiName: "string | required" + apiVersion: "string | default=v1.0" + context: "string | required" # API context path + upstreamPort: "integer | default=80" + plugins: + "array | default=[]" + # Example: + # - name: jwt + # config: + # claims_to_verify: ["exp"] + # - name: rate-limiting + # config: + # minute: 100 + + envOverrides: + # Platform engineers can override per environment + kongGateway: + "string | default=kong-gateway" + # Kong gateway service name + + creates: + # Create KongPlugin resources for each plugin + - forEach: ${parameters.plugins} + var: plugin + template: + apiVersion: configuration.konghq.com/v1 + kind: KongPlugin + metadata: + name: ${metadata.name}-${plugin.name} + namespace: ${metadata.namespace} + plugin: ${plugin.name} + config: ${plugin.config} + + # Create KongIngress resource + - template: + apiVersion: configuration.konghq.com/v1 + kind: KongIngress + metadata: + name: ${metadata.name}-ingress + namespace: ${metadata.namespace} + route: + paths: + - ${parameters.context} + upstream: + targets: + - target: ${metadata.componentName}.${metadata.namespace}:${parameters.upstreamPort} + + patches: + # Patch Ingress to use Kong plugins + - target: + group: networking.k8s.io + version: v1 + kind: Ingress + operations: + - op: add + path: /metadata/annotations/konghq.com~1plugins + value: ${join(map(parameters.plugins, "plugin", "${metadata.name}-${plugin.name}"), ",")} +``` + +Components can use this trait: + +```yaml +apiVersion: openchoreo.dev/v1alpha1 +kind: Component +metadata: + name: my-service +spec: + traits: + - name: kong-api-management + parameters: + apiName: my-api + apiVersion: v2.0 + context: /my-api/v2.0 + plugins: + - name: jwt + config: + claims_to_verify: + - exp + - name: rate-limiting + config: + minute: 100 +``` + +#### Example: Apigee Integration + +For Apigee integration, create a trait that generates Apigee proxy configurations: + +```yaml +apiVersion: openchoreo.dev/v1alpha1 +kind: Trait +metadata: + name: apigee-api-management + namespace: default +spec: + schema: + types: + Policy: + name: "string" + config: "map" + + parameters: + # Developer-facing parameters + apiName: "string | required" + apiVersion: "string | default=v1.0" + context: "string | required" # API base path + upstreamPort: "integer | default=80" + policies: + "array | default=[]" + # Example: + # - name: VerifyAPIKey + # - name: SpikeArrest + # config: + # rate: 100pm + + envOverrides: + # Platform engineers can override per environment + apigeeOrg: "string | required" + apigeeEnv: "string | required" + # Apigee organization and environment + + creates: + # Create ConfigMap with Apigee proxy configuration + - template: + apiVersion: v1 + kind: ConfigMap + metadata: + name: ${metadata.name}-apigee-config + namespace: ${metadata.namespace} + data: + proxy.xml: | + + /${parameters.context} + + + http://${metadata.componentName}.${metadata.namespace}:${parameters.upstreamPort} + + + + ${join(map(parameters.policies, "policy", ""), "\n")} + + + + # Create ApigeeDeployment resource (using Apigee CRD) + - template: + apiVersion: apigee.cloud.google.com/v1alpha1 + kind: ApigeeDeployment + metadata: + name: ${metadata.name}-deployment + namespace: ${metadata.namespace} + spec: + organization: ${envOverrides.apigeeOrg} + environment: ${envOverrides.apigeeEnv} + apiProxyConfigMap: ${metadata.name}-apigee-config +``` + +Components select the appropriate trait based on deployment target. + +## Troubleshooting + +### API Platform Pods Not Running + +Check pod status and logs: + +```bash +kubectl get pods -n openchoreo-data-plane -l app.kubernetes.io/instance=api-platform-default-gateway +kubectl logs -n openchoreo-data-plane -l app.kubernetes.io/instance=api-platform-default-gateway +``` + +## Production Considerations + +### External Identity Provider + +For production environments, configure an external OAuth2 provider like Okta: + +```yaml +api-platform: + enabled: true + gateway: + values: + gateway: + config: + policy_configurations: + JWTAuth_v010: + KeyManagers: + - name: OktaKeyManager + issuer: https://your-domain.okta.com/oauth2/default + jwks: + remote: + uri: https://your-domain.okta.com/oauth2/default/v1/keys + skipTlsVerify: false + JwksCacheTtl: "5m" + JwksFetchTimeout: "5s" + ValidateIssuer: true + AllowedAlgorithms: + - RS256 + HeaderName: Authorization + AuthHeaderScheme: Bearer +``` + +## Summary + +You've successfully: + +- Enabled the API Platform module in OpenChoreo +- Explored OpenChoreo Traits for advanced API management use cases +- Explored IDP Configuration for production use cases + +Your APIs are now protected with enterprise-grade security and access control—all managed declaratively through OpenChoreo! + +## Next Steps + +- [Learn about OpenChoreo Traits](../reference/api/platform/trait.md) +- [Securing APIs with OAuth2 Security](../use-cases/api-management.mdx) +- [Set up Observability and Alerting](./observability-alerting.mdx) + +## Clean Up + +To disable API Management for a component, remove the trait: + +```bash +kubectl patch component greeter-service --type=json \ + -p='[{"op": "remove", "path": "/spec/traits"}]' +``` + +To uninstall the API Platform module: + + + {`helm upgrade openchoreo-data-plane ${versions.helmSource}/openchoreo-data-plane \\ + --version ${versions.helmChart} \\ + --namespace openchoreo-data-plane \\ + --reuse-values \\ + --set api-platform.enabled=false`} + diff --git a/versioned_docs/version-v0.11.x/operations/auto-build.mdx b/versioned_docs/version-v0.11.x/operations/auto-build.mdx new file mode 100644 index 0000000..d3031f2 --- /dev/null +++ b/versioned_docs/version-v0.11.x/operations/auto-build.mdx @@ -0,0 +1,131 @@ +--- +title: Auto Build +description: Configure automatic builds when code is pushed to your Git repository. +sidebar_position: 8 +--- + +# Auto Build + +Auto Build enables automatic component builds when code is pushed to a Git repository. Instead of manually triggering builds, you can configure components to build automatically whenever changes are pushed to the repository. + +## Prerequisites + +Before configuring auto-build, ensure you have: + +1. OpenChoreo installed and running +2. Build plane installed in your OpenChoreo cluster +3. A Component created in OpenChoreo pointing to a Git repository +4. Access to create webhooks in your Git repository + +## Configuration + +### Step 1: Create the Webhook Secret + +Create a Kubernetes secret to store the webhook secret that will be used to validate incoming webhooks: + +```bash +# Generate a random secret +WEBHOOK_SECRET=$(openssl rand -hex 32) +echo "Your webhook secret: $WEBHOOK_SECRET" + +# Create the Kubernetes secret +kubectl create secret generic git-webhook-secrets \ + -n openchoreo-control-plane \ + --from-literal=github-secret="$WEBHOOK_SECRET" + +# Verify the secret was created +kubectl get secret git-webhook-secrets -n openchoreo-control-plane +``` + +:::warning Important +Save the `$WEBHOOK_SECRET` value. You will need it when configuring the webhook in your Git provider. +::: + +### Step 2: Enable Auto-Build on Your Component + +Update your Component to enable auto-build by adding `autoBuild: true`: + +```yaml +apiVersion: openchoreo.dev/v1alpha1 +kind: Component +metadata: + name: patient-management-service +spec: + owner: + projectName: default + componentType: deployment/service + autoBuild: true # Enable auto-build + autoDeploy: true + workflow: + name: ballerina-buildpack + systemParameters: + repository: + url: "https://github.com/openchoreo/sample-workloads" + revision: + branch: "main" + appPath: "/service-ballerina-patient-management" + + parameters: + exposed: true + replicas: 1 + port: 9090 + resources: + requests: + cpu: "100m" + memory: "256Mi" + limits: + cpu: "500m" + memory: "512Mi" +``` + +Apply the component: + +```bash +kubectl apply -f component.yaml +``` + +### Step 3: Configure the Webhook in Your Git Provider + +Create a webhook in your Git provider that points to OpenChoreo's webhook endpoint. The following example shows how to configure this in GitHub: + +1. Go to your repository +2. Navigate to **Settings** > **Webhooks** > **Add webhook** +3. Configure the webhook: + +| Field | Value | +|-------|-------| +| **Payload URL** | `https:///api/v1/webhooks/github` | +| **Content type** | `application/json` | +| **Secret** | The `$WEBHOOK_SECRET` you generated in Step 1 | +| **Which events** | Select "Just the push event" | +| **Active** | Checked | + +4. Click **Add webhook** + +GitHub will send a test ping event. You should see a green checkmark if the webhook was delivered successfully. + + + +### Step 4: Test Auto-Build + +Make a change to a file within your component's appPath, commit it, and push to your repository. This should trigger an automatic build. + +Check if a build was triggered: + +```bash +kubectl get componentworkflowrun +``` + +## Local Development Testing + +For local testing with a development cluster, you can use ngrok to expose your local OpenChoreo instance to receive webhooks from your Git provider: + +```bash +ngrok http --host-header=api.openchoreo.localhost 8080 +``` + +Use the ngrok HTTPS URL as your webhook payload URL: + +``` +https://abc123xyz.ngrok-free.app/api/v1/webhooks/github +``` diff --git a/versioned_docs/version-v0.11.x/operations/backstage-configuration.mdx b/versioned_docs/version-v0.11.x/operations/backstage-configuration.mdx new file mode 100644 index 0000000..3dc1f3b --- /dev/null +++ b/versioned_docs/version-v0.11.x/operations/backstage-configuration.mdx @@ -0,0 +1,519 @@ +--- +title: Backstage Configuration +description: Customize and configure Backstage, OpenChoreo's developer portal. +sidebar_position: 4 +--- + +import CodeBlock from '@theme/CodeBlock'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import {versions} from '../_constants.mdx'; + +# Backstage Configuration + +OpenChoreo uses [Backstage](https://backstage.io/) as its developer portal, providing a unified interface for managing organizations, projects, components, and deployments. This guide covers configuration options for customizing Backstage in your OpenChoreo deployment. + +Backstage configuration is done via Helm values in the Control Plane chart. + +## Core Configuration + +**Console/UI URL:** + +```yaml +backstage: + appConfig: + app: + baseUrl: "https://console.example.com" + backend: + baseUrl: "https://console.example.com" +``` + +**OpenChoreo API URL:** + +```yaml +openchoreoApi: + ingress: + enabled: true + hosts: + - host: api.example.com + paths: + - path: / +``` + +## Authentication + +By default, OpenChoreo configures Thunder as the identity provider for Backstage with a pre-configured OAuth client for testing purposes. If you want to integrate an external identity provider instead, create an OAuth 2.0 client with the following requirements: + +**OAuth Client Requirements:** + +1. **Grant Types**: The OAuth client must support both: + - `authorization_code` - For user authentication and login flows + - `client_credentials` - For service-to-service authentication + +2. **Token Format**: Configure the client to issue **JWT tokens** (not opaque tokens) + +3. **Redirect URLs**: Add the Backstage callback URL: + - `:///api/auth/openchoreo-auth/handler/frame` + - Replace `` with `http` or `https` and `` with your actual Backstage domain + +**Helm Configuration:** + +Once you have created the OAuth client, configure Backstage with the client credentials: + + +{`helm upgrade --install openchoreo-control-plane ${versions.helmSource}/openchoreo-control-plane \\ + --version ${versions.helmChart} \\ + --namespace openchoreo-control-plane \\ + --reuse-values \\ + --set backstage.auth.clientId="your-client-id" \\ + --set backstage.auth.clientSecret="your-client-secret" \\ + --set backstage.auth.redirectUrls\\[0\\]=":///api/auth/openchoreo-auth/handler/frame"`} + + +See [Identity Provider Configuration](./identity-configuration.mdx) for detailed setup instructions. + +## Feature Flags + +```yaml +backstage: + features: + workflows: + enabled: true # Requires Build Plane + observability: + enabled: true # Requires Observability Plane +``` + +## Resource Configuration + +```yaml +backstage: + replicas: 1 + resources: + limits: + cpu: 2000m + memory: 2Gi + requests: + cpu: 200m + memory: 256Mi + + autoscaling: + enabled: false + minReplicas: 1 + maxReplicas: 5 +``` + +## Environment Variables + +Add custom environment variables to the Backstage deployment: + +```yaml +backstage: + env: + - name: NODE_ENV + value: production + - name: LOG_LEVEL + value: info + - name: PORT + value: "7007" +``` + +### Commonly Used Variables + +| Variable | Description | Default | +|----------|-------------|---------| +| `NODE_ENV` | Node.js environment | `production` | +| `LOG_LEVEL` | Logging verbosity | `info` | +| `PORT` | HTTP server port | `7007` | +| `OPENCHOREO_API_URL` | OpenChoreo API endpoint | Auto-configured | +| `THUNDER_BASE_URL` | Thunder IdP URL | Auto-configured | + +## Ingress Configuration + +```yaml +backstage: + ingress: + enabled: true + className: "your-ingress-class" + hosts: + - host: console.example.com + paths: + - path: / + tls: + - secretName: console-tls + hosts: + - console.example.com +``` + +## Service Configuration + +```yaml +backstage: + service: + type: ClusterIP + port: 7007 +``` + +## OpenChoreo API Integration + +Backstage communicates with the OpenChoreo API for backend operations: + +```yaml +backstage: + openchoreoApi: + url: "" # Auto-configured to internal service URL +``` + +The API URL defaults to `http://{release-name}-api.{namespace}.svc.cluster.local:8080/api/v1`. + +## Backend Secret + +For session encryption (should be stable across restarts): + +```yaml +backstage: + backendSecret: "your-32-character-secret-here" +``` + +## Database Configuration + +Backstage requires a database to store catalog entities, user settings, and plugin data. OpenChoreo supports two database backends: + +| Backend | Use Case | Persistence | Scalability | +|---------|----------|-------------|-------------| +| SQLite (default) | Development, single-replica | Optional (emptyDir or PVC) | Single replica only | +| PostgreSQL | Production, multi-replica | External database | Horizontal scaling | + +### Default Configuration (SQLite) + +By default, Backstage uses SQLite with an `emptyDir` volume, which means data is lost when the pod restarts: + +```yaml +backstage: + database: + type: sqlite + sqlite: + persistence: + enabled: false # Uses emptyDir (data lost on restart) +``` + +### SQLite with Persistence + +For development environments where you want data to persist across restarts but don't need horizontal scaling: + +```yaml +backstage: + database: + type: sqlite + sqlite: + mountPath: /app/.config/backstage + persistence: + enabled: true + size: 1Gi + storageClassName: "" # Uses default storage class + accessMode: ReadWriteOnce +``` + +:::warning +SQLite locks the database file, preventing multiple Backstage replicas from running simultaneously. For high-availability deployments, use PostgreSQL. +::: + +### PostgreSQL for Production + +For production deployments requiring high availability and data durability, configure an external PostgreSQL database. + +#### Prerequisites + +1. **Provision a PostgreSQL Database**: Use a managed service (AWS RDS, Google Cloud SQL, Azure Database for PostgreSQL) or a self-hosted PostgreSQL instance +2. **Create a Database**: Create a database for Backstage (e.g., `backstage`) +3. **Create a Database User**: Create a user with full access to the database + +Backstage automatically creates per-plugin databases (e.g., `backstage_plugin_catalog`, `backstage_plugin_auth`) using the provided credentials. + +#### Helm Configuration + + + + +For managed PostgreSQL services or external databases: + + +{`helm upgrade --install openchoreo-control-plane ${versions.helmSource}/openchoreo-control-plane \\ + --version ${versions.helmChart} \\ + --namespace openchoreo-control-plane \\ + --reuse-values \\ + --set backstage.database.type=postgresql \\ + --set backstage.database.postgresql.host="postgres.example.com" \\ + --set backstage.database.postgresql.port=5432 \\ + --set backstage.database.postgresql.user="backstage" \\ + --set backstage.database.postgresql.password="your-secure-password" \\ + --set backstage.database.postgresql.database="backstage"`} + + + + + +For PostgreSQL running within the same Kubernetes cluster: + + +{`helm upgrade --install openchoreo-control-plane ${versions.helmSource}/openchoreo-control-plane \\ + --version ${versions.helmChart} \\ + --namespace openchoreo-control-plane \\ + --reuse-values \\ + --set backstage.database.type=postgresql \\ + --set backstage.database.postgresql.host="postgres.your-namespace.svc.cluster.local" \\ + --set backstage.database.postgresql.port=5432 \\ + --set backstage.database.postgresql.user="backstage" \\ + --set backstage.database.postgresql.password="your-secure-password" \\ + --set backstage.database.postgresql.database="backstage"`} + + + + + +Using a values file for better secret management: + +```yaml +# backstage-db-values.yaml +backstage: + database: + type: postgresql + postgresql: + host: "postgres.example.com" + port: 5432 + user: "backstage" + password: "your-secure-password" # Consider using external secrets + database: "backstage" +``` + + +{`helm upgrade --install openchoreo-control-plane ${versions.helmSource}/openchoreo-control-plane \\ + --version ${versions.helmChart} \\ + --namespace openchoreo-control-plane \\ + --reuse-values \\ + -f backstage-db-values.yaml`} + + + + + +#### PostgreSQL Configuration Reference + +| Parameter | Description | Default | +|-----------|-------------|---------| +| `backstage.database.type` | Database backend (`sqlite` or `postgresql`) | `sqlite` | +| `backstage.database.postgresql.host` | PostgreSQL server hostname | `""` | +| `backstage.database.postgresql.port` | PostgreSQL server port | `5432` | +| `backstage.database.postgresql.user` | Database username | `backstage` | +| `backstage.database.postgresql.password` | Database password | `""` | +| `backstage.database.postgresql.database` | Database name | `backstage` | + +#### Verifying PostgreSQL Connection + +After deploying with PostgreSQL, verify the connection: + +```bash +# Check Backstage pod is running +kubectl get pods -n openchoreo-control-plane -l app.kubernetes.io/component=backstage + +# Verify database environment variables +kubectl exec -n openchoreo-control-plane deployment/openchoreo-ui -- env | grep -E "DATABASE|POSTGRES" + +# Check logs for database connection errors +kubectl logs -n openchoreo-control-plane deployment/openchoreo-ui | head -50 +``` + +If PostgreSQL is configured correctly, Backstage will create per-plugin databases automatically: + +```bash +# List databases created by Backstage (run against your PostgreSQL instance) +psql -U backstage -d backstage -c "\l" | grep backstage_plugin +``` + +Expected output shows databases like `backstage_plugin_catalog`, `backstage_plugin_auth`, etc. + +## Health Checks + +Backstage health checks are pre-configured: + +| Check | Endpoint | Default | +|-------|----------|---------| +| Liveness | `/healthcheck` | Enabled | +| Readiness | `/healthcheck` | Enabled | + +## Example Configurations + + + + +```yaml +backstage: + enabled: true + replicas: 1 + baseUrl: "http://localhost:7007" + ingress: + enabled: true + hosts: + - host: localhost + paths: + - path: / + resources: + limits: + cpu: 1000m + memory: 1Gi + requests: + cpu: 100m + memory: 256Mi + features: + workflows: + enabled: true + observability: + enabled: true +``` + + + + +```yaml +backstage: + enabled: true + replicas: 2 + baseUrl: "https://console.example.com" + backendSecret: "your-production-secret-32chars!" + + # PostgreSQL for production (required for multi-replica) + database: + type: postgresql + postgresql: + host: "postgres.example.com" + port: 5432 + user: "backstage" + password: "your-secure-password" + database: "backstage" + + ingress: + enabled: true + hosts: + - host: console.example.com + paths: + - path: / + tls: + - secretName: console-tls + hosts: + - console.example.com + + resources: + limits: + cpu: 2000m + memory: 2Gi + requests: + cpu: 500m + memory: 512Mi + + autoscaling: + enabled: true + minReplicas: 2 + maxReplicas: 5 + targetCPUUtilizationPercentage: 70 + + features: + workflows: + enabled: true + observability: + enabled: true +``` + + + + +For headless deployments where only the API is needed: + +```yaml +backstage: + enabled: false + +# Security can also be disabled for development +security: + enabled: false +``` + + + + +## Troubleshooting + +### Backstage Not Loading + +Check pod status and logs: + +```bash +kubectl get pods -n openchoreo-control-plane -l app.kubernetes.io/name=backstage +kubectl logs -n openchoreo-control-plane deployment/backstage +``` + +### Authentication Issues + +Verify OAuth configuration: + +```bash +# Check Backstage environment variables +kubectl exec -n openchoreo-control-plane deployment/backstage -- env | grep -E "(AUTH|THUNDER)" + +# Check Thunder is running +kubectl get pods -n openchoreo-control-plane -l app.kubernetes.io/name=thunder +``` + +### API Connection Errors + +Verify OpenChoreo API is accessible: + +```bash +# Check API pod +kubectl get pods -n openchoreo-control-plane -l app.kubernetes.io/name=openchoreo-api + +# Test API from Backstage pod +kubectl exec -n openchoreo-control-plane deployment/backstage -- \ + curl -s http://openchoreo-control-plane-api:8080/api/v1/health +``` + +### Database Connection Issues + +If Backstage fails to start with database errors: + +**For SQLite errors:** + +```bash +# Check if the pod has write access to the database directory +kubectl exec -n openchoreo-control-plane deployment/openchoreo-ui -- ls -la /app/.config/backstage + +# Check for SQLite-specific errors in logs +kubectl logs -n openchoreo-control-plane deployment/openchoreo-ui | grep -i "sqlite\|database" +``` + +**For PostgreSQL errors:** + +```bash +# Verify PostgreSQL environment variables are set +kubectl exec -n openchoreo-control-plane deployment/openchoreo-ui -- env | grep POSTGRES + +# Test PostgreSQL connectivity from the pod +kubectl exec -n openchoreo-control-plane deployment/openchoreo-ui -- \ + nc -zv 5432 + +# Check for connection errors in logs +kubectl logs -n openchoreo-control-plane deployment/openchoreo-ui | grep -i "postgres\|connection\|ECONNREFUSED" +``` + +**Common issues:** + +| Error | Cause | Solution | +|-------|-------|----------| +| `ECONNREFUSED` | PostgreSQL not reachable | Verify hostname, port, and network policies | +| `password authentication failed` | Invalid credentials | Check `backstage.database.postgresql.password` | +| `database does not exist` | Missing database | Create the database on PostgreSQL server | +| `connection.filename is not supported` | Outdated Backstage image | Upgrade to latest control plane chart | + +## Next Steps + +- [Identity Provider Configuration](./identity-configuration.mdx): Configure an external IdP +- [Deployment Topology](./deployment-topology.mdx): Set up organizations and environments +- [Helm Charts Reference](/docs/reference/helm/control-plane.mdx): Complete Backstage configuration options diff --git a/versioned_docs/version-v0.11.x/operations/cluster-agent-rbac.mdx b/versioned_docs/version-v0.11.x/operations/cluster-agent-rbac.mdx new file mode 100644 index 0000000..12b165d --- /dev/null +++ b/versioned_docs/version-v0.11.x/operations/cluster-agent-rbac.mdx @@ -0,0 +1,270 @@ +--- +title: Cluster Agent RBAC Configuration +description: Configure additional permissions for the cluster agent to manage custom resources. +sidebar_position: 7 +--- + +# Cluster Agent RBAC Configuration + +The cluster agent in OpenChoreo's data plane, build plane, and observability plane requires specific Kubernetes permissions to manage resources. By default, the cluster agent has permissions to manage OpenChoreo's built-in custom resources. However, if you need the cluster agent to manage additional custom resources (CRDs) that are not provided by OpenChoreo, you must grant additional RBAC permissions. + +## Overview + +The cluster agent uses a Kubernetes service account to interact with the Kubernetes API. The permissions are defined in a `ClusterRole` and bound to the service account via a `ClusterRoleBinding`. + +:::warning Check Your Service Account Name and Namespace +Both the service account name and namespace can be customized via Helm values during installation. The default values are listed in the [Service Account Names](#service-account-names-by-plane) section below, but if you've overridden them in your Helm configuration, you must use your actual service account name and namespace when creating the ClusterRoleBinding. +::: + +## When to Configure Additional Permissions + +You need to configure additional RBAC permissions if: + +- You're deploying components that use third-party custom resources (e.g., Istio VirtualServices, Knative Services, etc.) +- Your workloads require the cluster agent to create, update, or manage CRDs that are not part of the OpenChoreo installation +- You receive permission errors in cluster agent logs indicating missing RBAC privileges + +## Configuring Additional Permissions + +### Step 1: Identify Required Permissions + +First, identify the custom resources and API groups that need to be accessible to the cluster agent. Check the cluster agent logs for permission errors: + +```bash +# For data plane (replace namespace if you customized it during installation) +kubectl logs -n openchoreo-data-plane -l app=cluster-agent --tail=50 + +# For build plane (replace namespace if you customized it during installation) +kubectl logs -n openchoreo-build-plane -l app=cluster-agent --tail=50 + +# For observability plane (replace namespace if you customized it during installation) +kubectl logs -n openchoreo-observability-plane -l app=cluster-agent --tail=50 +``` + +Look for errors like: +``` +error: failed to create resource: customresources.example.com is forbidden: +User "system:serviceaccount:openchoreo-data-plane:cluster-agent-dataplane" +cannot create resource "customresources" in API group "example.com" +``` + +### Step 2: Create Additional ClusterRole + +Create a new `ClusterRole` with the required permissions. This keeps your custom permissions separate from the default OpenChoreo ClusterRole, making upgrades easier. + +:::tip +Ensure you use standard ASCII spaces for YAML indentation. Copy-pasting may introduce non-breaking spaces that cause kubectl parsing errors. +::: + +```yaml title="cluster-agent-custom-permissions.yaml" +apiVersion: rbac.authorization.k8s.io/v1 +kind: ClusterRole +metadata: + name: cluster-agent-custom-permissions +rules: + # Example: Add permissions for a custom CRD + - apiGroups: ["example.com"] + resources: ["customresources"] + verbs: ["get", "list", "watch", "create", "update", "patch", "delete"] + + # Example: Add permissions for Istio resources + - apiGroups: ["networking.istio.io"] + resources: ["virtualservices", "destinationrules", "gateways"] + verbs: ["get", "list", "watch", "create", "update", "patch", "delete"] + + # Add more rules as needed for your custom resources +``` + +### Step 3: Create ClusterRoleBinding + +Bind the new `ClusterRole` to the cluster agent service account. + +:::important Verify Service Account Name and Namespace +Before creating the ClusterRoleBinding, verify the actual service account name and namespace used in your installation. If you've customized these via Helm values, replace the default values below with your actual values. See [Service Account Names](#service-account-names-by-plane) for how to find your actual service account name and namespace. +::: + +:::tip +Ensure you use standard ASCII spaces for YAML indentation. Copy-pasting may introduce non-breaking spaces that cause kubectl parsing errors. +::: + +```yaml title="cluster-agent-custom-binding.yaml" +apiVersion: rbac.authorization.k8s.io/v1 +kind: ClusterRoleBinding +metadata: + name: cluster-agent-custom-permissions +roleRef: + apiGroup: rbac.authorization.k8s.io + kind: ClusterRole + name: cluster-agent-custom-permissions +subjects: + # For data plane (default values shown) + # Replace with your actual service account name and namespace if customized + - kind: ServiceAccount + name: cluster-agent-dataplane + namespace: openchoreo-data-plane + + # Uncomment if you need the same permissions for build plane + # - kind: ServiceAccount + # name: cluster-agent-buildplane + # namespace: openchoreo-build-plane + + # Uncomment if you need the same permissions for observability plane + # - kind: ServiceAccount + # name: cluster-agent-observabilityplane + # namespace: openchoreo-observability-plane +``` + +### Step 4: Apply the Configuration + +Apply both resources to your cluster: + +```bash +kubectl apply -f cluster-agent-custom-permissions.yaml +kubectl apply -f cluster-agent-custom-binding.yaml +``` + +### Step 5: Verify Permissions + +Verify that the service account now has the required permissions: + +```bash +# Check if the service account can perform the action +# Replace namespace and service account name with your actual values if customized +kubectl auth can-i create customresources.example.com \ + --as=system:serviceaccount:openchoreo-data-plane:cluster-agent-dataplane + +# Should output: yes +``` + +## Service Account Names by Plane + +The **default** values used by the cluster agent in each plane are: + +| Plane | Default Namespace | Default Service Account Name | Helm Value Paths | +|-------|-------------------|------------------------------|------------------| +| Data Plane | `openchoreo-data-plane` | `cluster-agent-dataplane` | Namespace: Helm `--namespace` flag
Service Account: `clusterAgent.serviceAccount.name` | +| Build Plane | `openchoreo-build-plane` | `cluster-agent-buildplane` | Namespace: Helm `--namespace` flag
Service Account: `clusterAgent.serviceAccount.name` | +| Observability Plane | `openchoreo-observability-plane` | `cluster-agent-observabilityplane` | Namespace: Helm `--namespace` flag
Service Account: `clusterAgent.serviceAccount.name` | + +:::tip Finding Your Actual Service Account Name and Namespace +If you're unsure of the service account name or namespace in your installation, you can find them by running: + +```bash +# List all cluster-agent deployments across namespaces +kubectl get deployment -A -l app=cluster-agent + +# For a specific namespace (replace with your actual namespace) +kubectl get deployment cluster-agent -n -o jsonpath='{.spec.template.spec.serviceAccountName}' +``` + +Examples for default namespaces: +```bash +# For data plane +kubectl get deployment cluster-agent -n openchoreo-data-plane -o jsonpath='{.spec.template.spec.serviceAccountName}' + +# For build plane +kubectl get deployment cluster-agent -n openchoreo-build-plane -o jsonpath='{.spec.template.spec.serviceAccountName}' + +# For observability plane +kubectl get deployment cluster-agent -n openchoreo-observability-plane -o jsonpath='{.spec.template.spec.serviceAccountName}' +``` +::: + +## Example: Adding Permissions for Common CRDs + +:::tip YAML Indentation +All examples below use standard ASCII spaces for indentation. When copying these examples, ensure your text editor doesn't introduce non-breaking spaces or tabs. +::: + +### Cert-Manager Certificates + +```yaml +apiVersion: rbac.authorization.k8s.io/v1 +kind: ClusterRole +metadata: + name: cluster-agent-cert-manager +rules: + - apiGroups: ["cert-manager.io"] + resources: ["certificates", "issuers", "clusterissuers"] + verbs: ["get", "list", "watch", "create", "update", "patch", "delete"] +``` + +### Prometheus ServiceMonitors + +```yaml +apiVersion: rbac.authorization.k8s.io/v1 +kind: ClusterRole +metadata: + name: cluster-agent-prometheus +rules: + - apiGroups: ["monitoring.coreos.com"] + resources: ["servicemonitors", "prometheusrules"] + verbs: ["get", "list", "watch", "create", "update", "patch", "delete"] +``` + +### External Secrets Operator + +```yaml +apiVersion: rbac.authorization.k8s.io/v1 +kind: ClusterRole +metadata: + name: cluster-agent-external-secrets +rules: + - apiGroups: ["external-secrets.io"] + resources: ["externalsecrets", "secretstores", "clustersecretstores"] + verbs: ["get", "list", "watch", "create", "update", "patch", "delete"] +``` + +## Best Practices + +1. **Principle of Least Privilege**: Only grant the minimum permissions required for your use case. Avoid using wildcards (`*`) for `apiGroups`, `resources`, or `verbs` unless absolutely necessary. + +2. **Separate ClusterRoles**: Keep custom permissions in separate `ClusterRole` resources rather than modifying the default OpenChoreo ClusterRole. This prevents your changes from being overwritten during Helm upgrades. + +3. **Documentation**: Document which custom resources require additional permissions and why, to help with troubleshooting and maintenance. + +4. **Version Control**: Store your RBAC configuration files in version control alongside your OpenChoreo deployment manifests. + +5. **Testing**: Test permission changes in a non-production environment first to ensure they work as expected and don't grant excessive privileges. + +## Troubleshooting + +### Permission Denied Errors Persist + +If you continue to see permission errors after applying the ClusterRole and ClusterRoleBinding: + +1. Verify the ClusterRoleBinding references the correct service account name and namespace +2. Check that the ClusterRole includes the specific resource and verb that's failing +3. Use `kubectl auth can-i` to verify permissions are correctly configured +4. Wait a few seconds and retry - RBAC changes are effective immediately but the cluster agent may need to retry the failed operation + +### Finding the Correct API Group + +If you're unsure of the API group for a custom resource: + +```bash +# List all CRDs and their API groups +kubectl get crds -o custom-columns=NAME:.metadata.name,GROUP:.spec.group + +# Get details about a specific CRD +kubectl get crd -o yaml +``` + +### Checking Current Permissions + +To see all permissions currently granted to a service account: + +```bash +# For data plane cluster agent +kubectl describe clusterrolebinding | grep -A 10 cluster-agent-dataplane + +# View the ClusterRole permissions +kubectl describe clusterrole +``` + +## Related Documentation + +- [Kubernetes RBAC Documentation](https://kubernetes.io/docs/reference/access-authn-authz/rbac/) +- [Secret Management](./secret-management.mdx) - For managing secrets with External Secrets Operator +- [Data Plane Helm Chart Reference](../reference/helm/data-plane.mdx) + diff --git a/versioned_docs/version-v0.11.x/operations/deployment-topology.mdx b/versioned_docs/version-v0.11.x/operations/deployment-topology.mdx new file mode 100644 index 0000000..67622ef --- /dev/null +++ b/versioned_docs/version-v0.11.x/operations/deployment-topology.mdx @@ -0,0 +1,403 @@ +--- +title: Deployment Topology +description: Prerequisites and deployment topology for OpenChoreo in production. +sidebar_position: 1 +--- + +# Deployment Topology + +OpenChoreo uses a multi-plane architecture that separates concerns between control, runtime, build, and observability. This guide covers the prerequisites, topology options, and how planes connect. + +## Prerequisites + +Before deploying OpenChoreo to production, ensure your environment meets the following requirements. + +### Kubernetes Cluster + +| Requirement | Specification | +|-------------|---------------| +| Kubernetes Version | 1.32 or later | +| Node Count | Minimum 3 nodes (for high availability) | +| Node Resources | 4 CPU cores, 8 GB RAM per node (minimum) | +| RBAC | Enabled | +| LoadBalancer | Required for external access | +| Storage Classes | At least one default StorageClass for PersistentVolumeClaims | + +:::note +For development or testing, a single-node cluster with 8 GB RAM and 4 CPU cores is sufficient. Production deployments should use a multi-node cluster with appropriate resource allocation. +::: + +### Required Tools + +Install the following tools on your workstation: + +| Tool | Version | Notes | +|------|---------|-------| +| [kubectl](https://kubernetes.io/docs/tasks/tools/) | 1.32+ | Kubernetes CLI | +| [Helm](https://helm.sh/docs/intro/install/) | 3.12+ | Package manager | +| [cert-manager](https://cert-manager.io/docs/installation/) | 1.12+ | Required on all clusters where OpenChoreo planes are deployed | + +### LoadBalancer Requirements + +OpenChoreo services require LoadBalancer with the ability to dynamically assign IPs. In production, each plane exposing services on port 443 needs a separate IP address (since multiple services cannot share the same IP:port combination). + +If only a single IP is available, ports can be customized per service. Refer to the [Helm Charts Reference](/docs/reference/helm/control-plane.mdx) for port configuration options. + +#### IPs and Ports by Plane + +**Control Plane:** + +| Port | Purpose | +|------|---------| +| 443 | Backstage UI, OpenChoreo API, Identity Provider | +| 80 | HTTP to HTTPS redirect (optional) | + +**Data Plane:** + +| Port | Purpose | +|------|---------| +| 443 | Application endpoints, deployment invocations | +| 80 | HTTP to HTTPS redirect (optional) | + +**Build Plane (Optional):** + +- No inbound ports required +- Only outbound connectivity needed (to Control Plane, container registry) + +**Observability Plane (Optional):** + +| Port | Purpose | +|------|---------| +| 443 | OpenSearch ingestion endpoint | + +### Domain Requirements + +Each plane requires its own domain(s). These do not need to share a common base domain - configure each independently as needed. + +| Plane | Domains Required | +|-------|------------------| +| Control Plane | Console UI domain, API domain, Identity Provider domain | +| Data Plane | Application endpoints domain (wildcard for dynamic apps) | +| Build Plane (Optional) | No external domain required | +| Observability Plane (Optional) | OpenSearch/ingestion endpoint domain | + +Refer to the [Helm Charts Reference](/docs/reference/helm/control-plane.mdx) for domain configuration options. + +### TLS Certificate Requirements + +| Plane | Certificate Type | Domains | +|-------|-----------------|---------| +| Control Plane | Standard (SAN) | Console, API, Identity Provider | +| Data Plane | Wildcard | `*.{apps-domain}` for application endpoints | +| Build Plane (Optional) | None required (internal only) | +| Observability Plane (Optional) | Standard | Ingestion endpoint | + +Use [cert-manager](https://cert-manager.io/) to automatically provision and renew certificates, or bring your own certificates. + +### Resource Requirements + +#### Control Plane + +| Component | CPU Request | CPU Limit | Memory Request | Memory Limit | +|-----------|-------------|-----------|----------------|--------------| +| Backstage | 200m | 2000m | 256Mi | 2Gi | +| OpenChoreo API | 100m | 500m | 256Mi | 512Mi | +| Controller Manager | 100m | 500m | 128Mi | 512Mi | +| Cluster Gateway | 100m | 500m | 128Mi | 256Mi | + +#### Data Plane + +| Component | CPU Request | CPU Limit | Memory Request | Memory Limit | +|-----------|-------------|-----------|----------------|--------------| +| KGateway Controller | 100m | 200m | 128Mi | 256Mi | +| Cluster Agent | 50m | 100m | 128Mi | 256Mi | + +#### Build Plane (Optional) + +| Component | CPU Request | CPU Limit | Memory Request | Memory Limit | +|-----------|-------------|-----------|----------------|--------------| +| Argo Workflows Controller | 25m | 50m | 32Mi | 64Mi | +| Cluster Agent | 50m | 100m | 128Mi | 256Mi | + +#### Observability Plane (Optional) + +| Component | CPU Request | CPU Limit | Memory Request | Memory Limit | +|-----------|-------------|-----------|----------------|--------------| +| OpenSearch (per node) | 100m | 1000m | 1Gi | 1Gi | +| Observer | 100m | 200m | 128Mi | 200Mi | +| Cluster Agent | 50m | 100m | 128Mi | 256Mi | + +### Storage Requirements + +| Plane | Component | Default Size | +|-------|-----------|--------------| +| Control Plane | Database | 500Mi | +| Build Plane (Optional) | Container Registry | 10Gi | +| Build Plane (Optional) | Podman Cache | 10Gi | +| Observability Plane (Optional) | OpenSearch (per data node) | 5Gi | + +:::note +OpenSearch storage requirements grow with log retention. For production with extended retention, increase `openSearchCluster.nodePools.data.diskSize` accordingly. +::: + +### Pre-Installation Checklist + +Before proceeding with installation: + +- [ ] Kubernetes cluster meets version and resource requirements +- [ ] `kubectl` and `helm` are installed and configured +- [ ] LoadBalancer service type is available +- [ ] Storage class is configured for PersistentVolumeClaims +- [ ] Domains are registered and DNS is configurable +- [ ] TLS certificate strategy is determined (cert-manager or bring your own) +- [ ] Network connectivity between clusters is verified (for multi-cluster) +- [ ] Required ports are accessible through firewalls + +## Architecture Overview + +| Plane | Required | Purpose | +|-------|----------|---------| +| Control Plane | Yes | Central management, API, UI | +| Data Plane | Yes | Application runtime | +| Build Plane | No | CI/CD workflows | +| Observability Plane | No | Logging and monitoring | + +### Resource Hierarchy + +``` +Organization +├── Environment +│ └── references → DataPlane +├── DataPlane +│ └── references → ObservabilityPlane (optional) +├── BuildPlane +│ └── references → ObservabilityPlane (optional) +└── ObservabilityPlane +``` + +### Cluster Agent Connectivity + +OpenChoreo planes communicate via **Cluster Agents** using WebSocket connections. The agent runs in each remote plane and establishes an outbound connection to the Control Plane's Cluster Gateway. + +**Single-Cluster Mode:** +Communication happens via Kubernetes ClusterIP services - no external networking required between planes. + +**Multi-Cluster Mode:** +Each plane's cluster agent connects outbound to the Control Plane. Only the Control Plane needs to be reachable from other clusters. + +``` +┌─────────────────────────────────────────────────────────────────────────────┐ +│ Control Plane Cluster │ +│ ┌─────────────────────┐ │ +│ │ Cluster Gateway │ │ +│ │ (wss://:8443) │ │ +│ └──────────▲──────────┘ │ +└───────────────────────────────────┼─────────────────────────────────────────┘ + │ + ┌───────────────────────┼───────────────────────┐ + │ │ │ + │ WebSocket │ WebSocket │ WebSocket + │ (outbound) │ (outbound) │ (outbound) + │ │ │ +┌───────────┴───────────┐ ┌─────────┴────────┐ ┌────────────┴────────────────┐ +│ Data Plane Cluster │ │ Build Plane │ │ Observability Plane Cluster │ +│ ┌─────────────────┐ │ │ Cluster │ │ (Optional) │ +│ │ Cluster Agent │ │ │ (Optional) │ │ ┌─────────────────┐ │ +│ └─────────────────┘ │ │ ┌─────────────┐ │ │ │ Cluster Agent │ │ +└───────────────────────┘ │ │Cluster Agent│ │ │ └─────────────────┘ │ + │ └─────────────┘ │ └─────────────────────────────┘ + └──────────────────┘ +``` + +## Deployment Workflow (Order of Operations) + +When building your production environment, follow this general sequence to ensure dependencies are met: + +1. **Control Plane Setup**: + - Deploy the `openchoreo-control-plane` chart + - Configure TLS certificates for the Console, API, and IdP + - **Crucial**: Configure the **Cluster Gateway** ingress and certificate - this is the entry point for all other planes + +2. **Establish Trust** (Multi-Cluster Only): + - Extract the Cluster Gateway CA certificate from the Control Plane + - This CA is required by all other planes to verify the Control Plane's identity + - See [Multi-Cluster Connectivity](./multi-cluster-connectivity.mdx) for detailed steps + +3. **Observability Plane (Recommended First)**: + - Deploy the `openchoreo-observability-plane` chart + - Register it with the Control Plane using the `ObservabilityPlane` CRD + - This allows subsequent planes to immediately start sending logs and metrics + +4. **Data Plane(s)**: + - Deploy the `openchoreo-data-plane` chart + - Configure the ingress/gateway for your application workloads (`*.apps.example.com`) + - Register with the Control Plane using the `DataPlane` CRD + - Link to Observability Plane (if deployed) + +5. **Build Plane (Optional)**: + - Deploy the `openchoreo-build-plane` chart + - Configure the **Container Registry** ingress - this is critical for the Control Plane to read image metadata + - Register with the Control Plane using the `BuildPlane` CRD + +## Common Topologies + +### Single-Cluster + +All planes run in the same Kubernetes cluster with namespace isolation. Communication happens via Kubernetes ClusterIP services. + +``` +┌─────────────────────────────────────────────────────────────┐ +│ Single Kubernetes Cluster │ +├─────────────────┬─────────────────┬─────────────────────────┤ +│ Control Plane │ Data Plane │ Build & Observability │ +│ Namespace │ Namespace │ Namespaces │ +└─────────────────┴─────────────────┴─────────────────────────┘ +``` + +### Multi-Cluster + +Separate clusters provide isolation and independent scaling. Cluster agents establish outbound WebSocket connections to the Control Plane. + +``` +┌──────────────────┐ ┌──────────────────┐ +│ Control Plane │◀────│ Data Plane │ +│ Cluster │ │ Cluster │ +└────────┬─────────┘ └──────────────────┘ + │ + │ ┌──────────────────┐ + │◀──────────────│ Build Plane │ + │ │ Cluster │ + │ └──────────────────┘ + │ + │ ┌──────────────────┐ + └───────────────│ Observability │ + │ Cluster │ + └──────────────────┘ +``` + +For multi-cluster setup instructions, see [Multi-Cluster Connectivity](./multi-cluster-connectivity.mdx). + +### Multi-Region + +Central Control Plane with Data Planes across regions. Each Data Plane has a unique `gateway.publicVirtualHost` (e.g., `us.apps.example.com`, `eu.apps.example.com`). + +``` + ┌──────────────────┐ + │ Control Plane │ + │ (Central) │ + └────────┬─────────┘ + │ + ┌───────────────────┼───────────────────┐ + ▼ ▼ ▼ +┌──────────────────┐ ┌──────────────────┐ ┌──────────────────┐ +│ Data Plane US │ │ Data Plane EU │ │ Data Plane APAC │ +└──────────────────┘ └──────────────────┘ └──────────────────┘ +``` + +## Plane Resources + +### Organizations + +An **Organization** is the top-level tenant resource. All other OpenChoreo resources (Environment, DataPlane, BuildPlane, ObservabilityPlane) are namespaced within an organization. + +A default organization (`default-organization`) is created during installation. + +For complete configuration options, see the [Organization API Reference](/docs/reference/api/platform/organization). + +### Environments + +An **Environment** represents a deployment stage (development, staging, production) bound to a specific DataPlane. + +Key considerations: +- The `dataPlaneRef` is **immutable** - to change the DataPlane, delete and recreate the Environment +- The `gateway.dnsPrefix` determines the subdomain for deployed applications + +For complete configuration options, see the [Environment API Reference](/docs/reference/api/platform/environment). + +### DataPlane + +A **DataPlane** defines where application workloads run. It requires: +- Cluster agent configuration with CA certificate for authentication +- Gateway configuration with public virtual host for application endpoints + +For complete configuration options and examples, see the [DataPlane API Reference](/docs/reference/api/platform/dataplane). + +### BuildPlane (Optional) + +A **BuildPlane** provides infrastructure for CI/CD workflows. When enabled: +- Requires cluster agent configuration with CA certificate +- Can reference an ObservabilityPlane for build logs + +For complete configuration options, see the [BuildPlane API Reference](/docs/reference/api/platform/buildplane). + +### ObservabilityPlane (Optional) + +An **ObservabilityPlane** provides logging and monitoring infrastructure. Key fields: +- `observerURL`: The Observer service endpoint +- `agent`: Cluster agent configuration for communication + +Both DataPlane and BuildPlane can reference an ObservabilityPlane via `observabilityPlaneRef`. + +## Linking Planes + +Planes reference each other in their spec to form a logical topology. + +| Resource | Reference Field | Target | +|----------|----------------|--------| +| Environment | `dataPlaneRef` | DataPlane | +| DataPlane | `observabilityPlaneRef` | ObservabilityPlane | +| DataPlane | `secretStoreRef` | ClusterSecretStore | +| BuildPlane | `observabilityPlaneRef` | ObservabilityPlane | + +For detailed instructions on registering planes and establishing trust between clusters, see [Multi-Cluster Connectivity](./multi-cluster-connectivity.mdx). + +## Verifying Resources + +```bash +kubectl get organizations +kubectl get environments -n +kubectl get dataplanes -n +kubectl get buildplanes -n +kubectl get observabilityplanes -n +``` + +## Troubleshooting + +### Agent Connection Issues + +```bash +# Check agent pod status +kubectl get pods -n openchoreo-data-plane -l app.kubernetes.io/name=cluster-agent + +# View agent logs +kubectl logs -n openchoreo-data-plane deployment/cluster-agent +``` + +### Environment Not Ready + +```bash +# Check environment conditions +kubectl describe environment -n + +# Verify referenced DataPlane exists +kubectl get dataplane -n +``` + +### Plane Status Not Updating + +```bash +# Check controller-manager logs +kubectl logs -n openchoreo-control-plane deployment/controller-manager + +# View plane conditions +kubectl get dataplane -n -o jsonpath='{.status.conditions}' +``` + +## Related Documentation + +- [DataPlane API Reference](/docs/reference/api/platform/dataplane) +- [BuildPlane API Reference](/docs/reference/api/platform/buildplane) +- [Environment API Reference](/docs/reference/api/platform/environment) +- [Organization API Reference](/docs/reference/api/platform/organization) +- [Multi-Cluster Connectivity](./multi-cluster-connectivity.mdx) - Step-by-step multi-cluster setup +- [Secret Management](./secret-management.mdx) - External secret store integration diff --git a/versioned_docs/version-v0.11.x/operations/gitops/fluxcd/getting-started.mdx b/versioned_docs/version-v0.11.x/operations/gitops/fluxcd/getting-started.mdx new file mode 100644 index 0000000..2d9f21a --- /dev/null +++ b/versioned_docs/version-v0.11.x/operations/gitops/fluxcd/getting-started.mdx @@ -0,0 +1,234 @@ +--- +title: Getting Started with FluxCD +description: Learn how to configure FluxCD with OpenChoreo for GitOps-based deployments. +sidebar_position: 1 +--- + +# Getting Started with FluxCD + +This guide walks you through configuring FluxCD with OpenChoreo to enable GitOps-based management of your platform and application resources. + +## Overview + +[FluxCD](https://fluxcd.io/) is a set of continuous delivery tools that keeps Kubernetes clusters in sync with configuration sources like Git repositories. For OpenChoreo integration, we use Flux's **kustomize-controller** to automatically apply OpenChoreo resources from Git to your cluster. + +When combined with OpenChoreo, FluxCD enables you to: + +- **Declaratively manage OpenChoreo resources** - Store your Projects, Components, Workloads, and other resources in Git +- **Automate deployments** - Changes pushed to Git are automatically applied to your cluster +- **Maintain audit trails** - Git history provides a complete record of all changes +- **Enable GitOps workflows** - Use pull requests for review and approval before changes are applied + +## Prerequisites + +Before you begin, ensure you have: + +- An OpenChoreo installation (see "Get Started" section for installation options) +- FluxCD installed in your cluster - refer to the [official FluxCD installation documentation](https://fluxcd.io/flux/installation/) for setup instructions +- A Git repository for storing your OpenChoreo manifests + +## Flux Resources Overview + +To sync OpenChoreo resources from Git, you need two types of Flux resources: + +| Resource | Purpose | +|----------|---------| +| **GitRepository** | Defines the Git repository source that Flux monitors for changes | +| **Kustomization** | Defines which path in the repository to apply and how to reconcile resources | + +## Configuring Flux for OpenChoreo + +### Step 1: Create a GitRepository + +Create a `GitRepository` resource that points to your OpenChoreo configuration repository: + +```yaml +apiVersion: source.toolkit.fluxcd.io/v1 +kind: GitRepository +metadata: + name: openchoreo-gitops + namespace: flux-system +spec: + interval: 1m + url: https://github.com// + ref: + branch: main +``` + +For private repositories, add a secret reference: + +```yaml +spec: + secretRef: + name: git-credentials +``` + +### Step 2: Create Kustomizations + +Create `Kustomization` resources to sync different parts of your repository. We recommend using dependencies to ensure resources are created in the correct order. + +**Organization and Namespace:** + +```yaml +apiVersion: kustomize.toolkit.fluxcd.io/v1 +kind: Kustomization +metadata: + name: openchoreo-namespace-org + namespace: flux-system +spec: + interval: 10m + path: ./organization + prune: true + sourceRef: + kind: GitRepository + name: openchoreo-gitops +``` + +**Platform Resources** (DataPlanes, Environments, ComponentTypes, etc.): + +```yaml +apiVersion: kustomize.toolkit.fluxcd.io/v1 +kind: Kustomization +metadata: + name: openchoreo-platform + namespace: flux-system +spec: + interval: 5m + path: ./platform + prune: true + sourceRef: + kind: GitRepository + name: openchoreo-gitops + dependsOn: + - name: openchoreo-namespace-org +``` + + + +**Projects and Components:** + +```yaml +apiVersion: kustomize.toolkit.fluxcd.io/v1 +kind: Kustomization +metadata: + name: openchoreo-projects + namespace: flux-system +spec: + interval: 5m + path: ./projects + prune: true + sourceRef: + kind: GitRepository + name: openchoreo-gitops + dependsOn: + - name: openchoreo-namespace-org +``` + +:::tip Flexible Kustomization Patterns +The Kustomization structure above follows the [Mono Repository](../overview.md#mono-repository) pattern, but you can define Kustomizations to match your team's workflow and repository structure. OpenChoreo's resource model works with any pattern. Common alternatives include: + +| Pattern | Description | Use Case | +|---------|-------------|----------| +| **Per Project** | One Kustomization per Project directory | Team-based ownership where each team manages their own Project | +| **Per Component** | One Kustomization per Component | Fine-grained control over individual Component deployments | +| **Per Environment** | Separate Kustomizations for dev, staging, prod | Environment-based promotion workflows with different sync intervals | +| **Per Repository** | Single Kustomization for the entire repository | Simple setups with few resources | + +For example, a per-project pattern might have Kustomizations like `project-a`, `project-b`, each pointing to `./projects/project-a`, `./projects/project-b`. Choose the granularity that best fits your organizational structure and deployment requirements. +::: + +### Step 3: Apply Flux Resources + +Apply the Flux resources to your cluster: + +```bash +kubectl apply -f flux/gitrepository.yaml +kubectl apply -f flux/namespace-org-kustomization.yaml +kubectl apply -f flux/platform-kustomization.yaml +kubectl apply -f flux/projects-kustomization.yaml +``` + +## Resource Dependencies + +The `dependsOn` field ensures resources are created in the correct order. Both platform and projects depend on the namespace and organization being created first, but can sync in parallel with each other: + +```text +GitRepository (openchoreo-gitops) + │ + ▼ +Kustomization (openchoreo-namespace-org) → Organization, Namespace + │ + ├───────────────────┐ + ▼ ▼ +Kustomization Kustomization +(openchoreo-platform) (openchoreo-projects) + │ │ + ▼ ▼ +ComponentTypes, Projects, Components, +Traits, DataPlanes, Workloads, Releases, +Environments ReleaseBindings +``` + +## Verification + +### Check Flux Resources + +```bash +# Check GitRepository sync status +kubectl get gitrepository -n flux-system + +# Check Kustomization status +kubectl get kustomization -n flux-system +``` + +### Check OpenChoreo Resources + +```bash +# Verify platform resources +kubectl get organizations +kubectl get componenttypes,traits,dataplanes,environments -n + +# Verify application resources +kubectl get projects,components,workloads -n +``` + +## Making Changes + +### Adding New Resources + +1. Add your resource YAML files to the appropriate directory in your Git repository +2. Commit and push to the repository +3. Flux automatically discovers and syncs the changes based on the configured interval + +### Force Immediate Sync + +To trigger an immediate reconciliation: + +```bash +kubectl annotate gitrepository -n flux-system openchoreo-gitops \ + reconcile.fluxcd.io/requestedAt="$(date +%s)" --overwrite + +kubectl annotate kustomization -n flux-system openchoreo-platform \ + reconcile.fluxcd.io/requestedAt="$(date +%s)" --overwrite +``` + +## Troubleshooting + +### View Flux Controller Logs + +```bash +# Source controller logs (Git operations) +kubectl logs -n flux-system deploy/source-controller + +# Kustomize controller logs (resource application) +kubectl logs -n flux-system deploy/kustomize-controller +``` + +### Check Resource Status + +```bash +kubectl describe gitrepository -n flux-system openchoreo-gitops +kubectl describe kustomization -n flux-system openchoreo-platform +``` + +For more details on FluxCD configuration options, refer to the [official FluxCD documentation](https://fluxcd.io/flux/). diff --git a/versioned_docs/version-v0.11.x/operations/gitops/overview.md b/versioned_docs/version-v0.11.x/operations/gitops/overview.md new file mode 100644 index 0000000..34d26b8 --- /dev/null +++ b/versioned_docs/version-v0.11.x/operations/gitops/overview.md @@ -0,0 +1,396 @@ +--- +title: Overview +description: Learn how to use GitOps principles with OpenChoreo for declarative, versioned, and auditable infrastructure and application management. +sidebar_position: 1 +--- + +# 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 + +OpenChoreo implements GitOps through four core principles: + +1. **Declarative Configuration**: All system state is described through OpenChoreo CRDs and YAML manifests +2. **Version Control**: Platform and application configurations can be stored in Git repositories +3. **Automated Deployment**: Changes can be automatically reconciled by Kubernetes controllers and GitOps operators +4. **Continuous Monitoring**: The system continuously reconciles desired vs actual state with drift detection + +## Repository Organization Patterns + +OpenChoreo is designed to work with any repository structure by adhering to core GitOps principles. Choose the pattern that best fits your organization's size, team structure, and governance requirements. + +### Mono Repository + +A single repository containing all OpenChoreo resources - ideal for smaller teams or organizations where platform and development teams work closely together. + +```text +. +├── organization/ # organization and namespace +│ ├── namespace.yaml +│ └── organization.yaml +│ +├── platform/ # platform-level resources (managed by platform team) +│ ├── infrastructure/ +│ │ ├── dataplanes/ +│ │ │ ├── non-prod-dataplane.yaml +│ │ │ └── prod-dataplane.yaml +│ │ ├── deployment-pipelines/ +│ │ │ ├── fast-track-pipeline.yaml +│ │ │ └── standard-pipeline.yaml +│ │ └── environments/ +│ │ ├── dev-environment.yaml +│ │ ├── staging-environment.yaml +│ │ └── prod-environment.yaml +│ ├── component-types/ +│ │ ├── http-service.yaml +│ │ ├── scheduled-task.yaml +│ │ └── web-app.yaml +│ ├── traits/ +│ │ ├── emptydir-volume.yaml +│ │ └── persistent-volume.yaml +│ └── secret-references/ # secret-references defined by platform team +│ └── database-secret-reference.yaml +│ +└── projects/ # application resources (managed by development teams) + └── / + ├── project.yaml + └── components/ + └── / + ├── component.yaml + ├── workload.yaml + ├── releases/ + │ └── --.yaml + └── release-bindings/ + ├── -development.yaml + └── -staging.yaml +``` + +### Multi Repository + +Separate repositories for platform configuration and application resources. This pattern is recommended for larger organizations where platform teams and development teams have different access controls, approval workflows, and release cadences. + +**Platform Configuration Repository** - Managed by platform engineers: + +```text +. +├── organization/ +│ ├── namespace.yaml +│ └── organization.yaml +│ +├── infrastructure/ +│ ├── dataplanes/ +│ │ ├── non-prod-dataplane.yaml +│ │ └── prod-dataplane.yaml +│ ├── deployment-pipelines/ +│ │ ├── fast-track-pipeline.yaml +│ │ └── standard-pipeline.yaml +│ └── environments/ +│ ├── dev-environment.yaml +│ ├── staging-environment.yaml +│ └── prod-environment.yaml +│ +├── component-types/ +│ ├── http-service.yaml +│ ├── scheduled-task.yaml +│ └── web-app.yaml +│ +├── traits/ +│ ├── emptydir-volume.yaml +│ └── persistent-volume.yaml +│ +└── secret-references/ + └── database-secret-reference.yaml +``` + +**Application Repository** - Managed by development teams: + +```text +. +└── projects/ + └── / + ├── project.yaml + └── components/ + └── / + ├── component.yaml + ├── workload.yaml + ├── releases/ + │ └── --.yaml + └── release-bindings/ + ├── -development.yaml + └── -staging.yaml +``` + +**Benefits of Multi Repository:** + +- **Clear ownership boundaries** - Platform teams control infrastructure; development teams control applications +- **Independent access controls** - Different permissions and approval workflows per repository +- **Separate release cadences** - Platform changes can be reviewed and deployed independently from application changes +- **Reduced blast radius** - Changes to one repository don't affect the other +- **Easier compliance and auditing** - Clear separation for regulatory requirements + +:::tip Flexible Repository Structures +The patterns above are common starting points, but OpenChoreo is designed to work with **any repository structure** that fits your organization's needs. Since OpenChoreo reconciles resources based on their content rather than their location, you have complete flexibility in how you organize your Git repositories. Other patterns you might consider: + +- **Repository per Project** - Each development team owns their Project in a dedicated repository +- **Repository per Component** - Individual Components managed in separate repositories for maximum isolation +- **Separate ReleaseBindings repository** - Keep ReleaseBindings in a dedicated repository for centralized deployment control +- **Environment-based repositories** - Separate repositories for production vs non-production configurations +- **Hybrid approaches** - Combine patterns based on team structure and security requirements + +Choose the structure that aligns with your organization's governance policies, team boundaries, and operational workflows. +::: + +## Best Practices + +### Repository Organization + +OpenChoreo's declarative nature means it works with any repository structure - resources are reconciled based on their content, not their location. However, following consistent patterns provides significant benefits: + +**Choose the right repository strategy** + +- Use a **mono repository** for smaller teams or when platform and development teams collaborate closely +- Use **multi repository** for larger organizations requiring strict access controls and independent workflows +- See [Repository Organization Patterns](#repository-organization-patterns) for detailed structures + +**Use consistent directory structures** + +While OpenChoreo doesn't enforce directory layouts, consistent organization helps teams: +- Quickly locate resources across projects +- Onboard new team members faster +- Apply automation and tooling uniformly + +### Configuration Management + +**OpenChoreo handles resource dependencies automatically** + +OpenChoreo resources don't require specific ordering or dependency management. The controllers reconcile resources based on their relationships, not their application order. + +**OpenChoreo supports multiple Environments natively** + +Unlike traditional Kubernetes GitOps where you need separate branches or Kustomize overlays per environment, OpenChoreo handles multi-environment deployments through its built-in resources ([`Environment`](../../reference/api/platform/environment.md), [`ComponentRelease`](../../reference/api/runtime/componentrelease.md), [`ReleaseBinding`](../../reference/api/platform/releasebinding.md)). You define your Component once and use **ReleaseBindings** to deploy it across Environments. + +**Consider Kustomize for operational concerns (optional)** + +While not required for environment management, tools like Kustomize can still be useful for operational tasks such as injecting namespaces or adding common labels: + +```yaml +# kustomization.yaml +apiVersion: kustomize.config.k8s.io/v1beta1 +kind: Kustomization +namespace: my-org # inject namespace for all resources +commonLabels: + managed-by: gitops +resources: + - project.yaml + - components/ +``` + +### Version Control Practices + +- **Use pull requests for all changes** - Enable code review and maintain audit trails +- **Implement branch protection** - Require reviews for changes affecting production Environments +- **Tag releases** - Use semantic versioning for traceability and rollback capabilities +- **Write meaningful commit messages** - Document the intent behind configuration changes + +### Security Practices + +- **Never commit plaintext secrets** - Use SecretReference resources to reference external secret stores +- **Define Code Owners** - Use a `CODEOWNERS` file to protect critical files and directories by requiring review from designated owners before merging changes. + +## Secrets Management + +OpenChoreo integrates with the [External Secrets Operator (ESO)](https://external-secrets.io/) to provide secure, GitOps-friendly secrets management. Platform teams can define [SecretReference](../../../reference/api/platform/secretreference) resources to bring in secrets from external secret stores. For complete setup instructions and provider configuration, see the [Secret Management](../secret-management.mdx) guide. + +### Organize Secrets + +SecretReference resources are defined at the platform level and managed by the platform team: + +| Directory Location | Use Case | +|-------------------|----------| +| `platform/secret-references/` | Infrastructure and application secrets: container registry credentials, database credentials, API keys, service tokens | + +This centralized approach enables: +- **Clear ownership**: Platform team manages all secrets through SecretReference resources +- **Consistent security**: Unified access controls and audit policies +- **Simplified governance**: Single location for secret management across all Projects and Components + +### Using Secrets in Workloads + +Reference secrets in your Workload definitions using `secretRef`: + +```yaml +apiVersion: openchoreo.dev/v1alpha1 +kind: Workload +metadata: + name: my-app-workload +spec: + containers: + main: + image: "my-app:latest" + env: + - key: DATABASE_PASSWORD + valueFrom: + secretRef: + name: database-secret # SecretReference name + key: password # Key defined in SecretReference + - key: DATABASE_USERNAME + valueFrom: + secretRef: + name: database-secret + key: username + files: + - key: api-token + mountPath: /secrets + valueFrom: + secretRef: + name: api-secret + key: token +``` + +### DataPlane Secret Store Configuration + +Each DataPlane can be configured with a ClusterSecretStore reference that ESO uses to connect to your external secrets provider: + +```yaml +apiVersion: openchoreo.dev/v1alpha1 +kind: DataPlane +metadata: + name: production-dataplane +spec: + secretStoreRef: + name: vault-secret-store # ClusterSecretStore in the DataPlane cluster + # ... other configuration +``` + +### Supported External Secret Providers + +OpenChoreo works with any provider supported by the External Secrets Operator: + +| Provider | Use Case | +|----------|----------| +| **HashiCorp Vault** | Enterprise secrets management with dynamic secrets | +| **AWS Secrets Manager** | AWS-native secrets for cloud workloads | +| **Google Secret Manager** | GCP-native secrets management | +| **Azure Key Vault** | Azure-native secrets and key management | +| **Kubernetes Secrets** | For development or single-cluster setups | + +### Security Best Practices + +- **Never commit plaintext secrets** - Always use SecretReference resources +- **Use Environment-specific secret paths** - Organize secrets by Environment (e.g., `dev/database`, `prod/database`) +- **Set appropriate refresh intervals** - Balance freshness with API rate limits +- **Implement least-privilege access** - Configure secret store access per Environment +- **Audit secret access** - Enable logging on your external secrets provider + +## Deployment Strategy + +OpenChoreo uses a two-resource model for deployments that enables GitOps-friendly, Environment-aware releases. + +### Release and ReleaseBinding + +| Resource | Purpose | +|----------|---------| +| **ComponentRelease** | Immutable snapshot of a Component version (workload, traits, configurations) | +| **ReleaseBinding** | Binds a ComponentRelease to an Environment with optional overrides | + +This separation allows the same ComponentRelease to be deployed across multiple Environments with Environment-specific configurations: + +```yaml +apiVersion: openchoreo.dev/v1alpha1 +kind: ReleaseBinding +metadata: + name: my-service-production +spec: + owner: + project: my-project + component: my-service + environment: production + releaseName: my-service-v1.2.0 + workloadOverrides: + containers: + main: + env: + - key: LOG_LEVEL + value: warn +``` + +:::note Upcoming Feature +A CLI tool for managing GitOps repositories is planned for an upcoming release. This will simplify common operations such as creating ComponentReleases, automating promotions via GitHub Actions, and managing ReleaseBindings across Environments. +::: + +### Health Monitoring + +OpenChoreo tracks resource health with five states: + +| State | Description | +|-------|-------------| +| **Healthy** | Resource is operating normally | +| **Progressing** | Resource is transitioning (scaling, updating) | +| **Degraded** | Resource has errors (CrashLoopBackOff, failed replicas) | +| **Suspended** | Resource is intentionally paused | +| **Unknown** | Health cannot be determined | + +The Release controller monitors Deployments, StatefulSets, Jobs, CronJobs, and other resources, updating status in real-time. + +### Rollback + +OpenChoreo implements rollback through Git and resource lifecycle: + +- **Git-based rollback**: Update the ReleaseBinding to reference a previous ComponentRelease +- **Automatic cleanup**: When a ReleaseBinding is deleted or updated to deploy a new ComponentRelease, OpenChoreo automatically handles the cleanup of old resources in the DataPlane + +```yaml +# Rollback by updating ReleaseBinding to previous version +spec: + releaseName: my-service-v1.1.0 # Previous stable version +``` + +### Best Practices + +- **Create immutable ComponentReleases** for each version to enable reliable rollbacks +- **Use ReleaseBinding overrides** for Environment-specific configurations instead of duplicating ComponentReleases +- **Monitor health status** through ReleaseBinding conditions before promoting to next Environment +- **Maintain audit trails** through Git history - all deployment changes are tracked as commits + +## Monitoring and Observability + +### GitOps Tool Monitoring + +When using GitOps operators like FluxCD or ArgoCD, you can leverage their built-in monitoring capabilities: + +- **Sync status**: Monitor repository synchronization state and reconciliation loops +- **Drift detection**: Track when actual cluster state diverges from Git-defined state +- **Reconciliation metrics**: Observe controller performance and error rates +- **Event logging**: Capture detailed logs of all Git operations and resource updates + +Each GitOps tool provides its own metrics and dashboards. Refer to your tool's documentation for specific monitoring setup: +- [FluxCD Monitoring](https://fluxcd.io/flux/monitoring/) +- [ArgoCD Metrics](https://argo-cd.readthedocs.io/en/stable/operator-manual/metrics/) + +### OpenChoreo Resource Monitoring + +OpenChoreo tracks the health of deployed resources through ReleaseBinding status conditions. You can monitor: + +- **ReleaseSynced**: Whether the Release was successfully created/updated +- **ResourcesReady**: Whether all resources in the DataPlane are healthy +- **Ready**: Overall readiness of the deployment + +Use `kubectl` to check deployment status: + +```bash +kubectl get releasebindings -A -o wide +kubectl describe releasebinding -n +``` + +:::note Upcoming Feature +OpenChoreo will introduce built-in observability rules in an upcoming release, enabling you to define GitOps-related alerting and monitoring rules directly through OpenChoreo resources. This will provide unified visibility across your deployments without requiring separate monitoring configuration for each GitOps tool. +::: + + +## Next Steps + +Get started on GitOps with OpenChoreo: + +- [FluxCD Getting Started](./fluxcd/getting-started.mdx) - Set up FluxCD with OpenChoreo diff --git a/versioned_docs/version-v0.11.x/operations/identity-configuration.mdx b/versioned_docs/version-v0.11.x/operations/identity-configuration.mdx new file mode 100644 index 0000000..fc18926 --- /dev/null +++ b/versioned_docs/version-v0.11.x/operations/identity-configuration.mdx @@ -0,0 +1,286 @@ +--- +title: Identity Provider Configuration +description: Configure identity providers for OpenChoreo. +sidebar_position: 3 +--- + +import CodeBlock from '@theme/CodeBlock'; +import {versions} from '../_constants.mdx'; + +# Identity Provider Configuration + +OpenChoreo supports standard OAuth2/OIDC compliant identity providers for user management and authentication. This guide covers the default identity provider setup and how to integrate your own OAuth2/OIDC compliant identity provider. + +## Overview + +OpenChoreo's authentication system supports: + +- **Flexible OAuth2/OIDC compliant identity provider configuration** for secure authentication +- **User and service account identity management** for different access patterns +- **JWT-based token validation** with audience claim verification +- **Multi-plane authentication** with consistent identity management across different OpenChoreo planes + +The identity provider configuration is managed through helm chart values during installation. + +## Default Identity Provider + +OpenChoreo ships with **Asgardeo Thunder** as the default identity provider. Thunder is a lightweight, OAuth2/OIDC compliant identity management platform that enables quick setup for development and testing environments. + +### Features + +Thunder provides out-of-the-box: + +- OAuth2 and OIDC compliant authentication flows +- User and service account identity management +- JWT token issuance and validation +- Pre-configured OAuth applications for OpenChoreo components + +### Trying Out Thunder + +Thunder includes a developer portal where you can manage users, applications, and OAuth clients. After deploying OpenChoreo, access the Thunder admin portal to configure additional identity settings: + +**Access Thunder Developer Portal:** +- URL: `/develop` +- Default credentials: + - Username: `admin` + - Password: `admin` + +:::note +The default Thunder credentials are intended for development and testing. For production deployments, configure your own OAuth2/OIDC compliant identity provider as described in the next section. +::: + +## Production Database Setup + +The default OpenChoreo installation uses an embedded SQLite database for Thunder, which is **not suitable for production** high-availability (HA) deployments. SQLite locks the database file, preventing multiple replicas of the Identity Provider from running simultaneously. + +For production, you should configure an external PostgreSQL database to enable horizontal scaling and data durability. + +### Configuring PostgreSQL + +1. **Provision a PostgreSQL Database**: Use a managed service (RDS, Cloud SQL, Azure Database) or a self-hosted PostgreSQL cluster +2. **Create Databases**: Create three separate databases: + - `thunderdb` - Identity data + - `runtimedb` - Runtime/session data + - `userdb` - User data +3. **Create a Database User**: Create a user with access to these databases + +**Helm Configuration:** + +Update your Helm values to point Thunder to your PostgreSQL instance: + +```yaml +thunder: + configuration: + database: + identity: + type: postgres + host: "postgres.example.com" + port: "5432" + name: "thunderdb" + username: "asgthunder" + password: "your-secure-password" + sslmode: "require" + runtime: + type: postgres + host: "postgres.example.com" + port: "5432" + name: "runtimedb" + username: "asgthunder" + password: "your-secure-password" + sslmode: "require" + user: + type: postgres + host: "postgres.example.com" + port: "5432" + name: "userdb" + username: "asgthunder" + password: "your-secure-password" + sslmode: "require" +``` + +:::tip Secret Management +Avoid hardcoding passwords in `values.yaml`. Use Kubernetes Secrets or External Secrets Operator to inject these values. See [Secret Management](./secret-management.mdx) for details. +::: + +## Integrating Your Identity Provider + +OpenChoreo allows you to integrate your own OAuth2/OIDC compliant identity provider for production environments. This enables you to leverage your organization's existing identity management infrastructure for user authentication and service account management. + +### Prerequisites + +Before integrating your identity provider, ensure you have: + +1. An OAuth2/OIDC compliant identity provider accessible from your cluster +2. The following endpoints from your identity provider: + - OIDC Discovery endpoint (`.well-known/openid-configuration`) + - Authorization endpoint + - Token endpoint + - JWKS (JSON Web Key Set) endpoint +3. Knowledge of your provider's issuer and audience claim values + +### Configuration Steps + +OpenChoreo requires identity provider configuration across multiple planes. The following sections describe how to configure each plane during installation. + +#### Control Plane Configuration + +The Control Plane requires identity provider configuration for authenticating API requests and managing user sessions. Configure your identity provider's OIDC settings and disable the default Thunder identity provider: + + +{`helm upgrade --install openchoreo-control-plane ${versions.helmSource}/openchoreo-control-plane \\ + --version ${versions.helmChart} \\ + --namespace openchoreo-control-plane \\ + --create-namespace \\ + --reuse-values \\ + --set thunder.enabled=false \\ + --set security.enabled=true \\ + --set security.oidc.issuer="https://your-idp.example.com" \\ + --set security.oidc.wellKnownEndpoint="https://your-idp.example.com/.well-known/openid-configuration" \\ + --set security.oidc.jwksUrl="https://your-idp.example.com/.well-known/jwks.json" \\ + --set security.oidc.authorizationUrl="https://your-idp.example.com/oauth2/authorize" \\ + --set security.oidc.tokenUrl="https://your-idp.example.com/oauth2/token"`} + + +**Configuration Parameters:** + +- `security.oidc.issuer`: OIDC issuer URL (must match the `iss` claim in JWT tokens) +- `security.oidc.wellKnownEndpoint`: URL to OIDC provider's well-known configuration endpoint +- `security.oidc.jwksUrl`: URL to provider's JWKS endpoint for token signature verification +- `security.oidc.authorizationUrl`: Authorization endpoint for initiating login flow +- `security.oidc.tokenUrl`: Token exchange endpoint for obtaining access tokens +- `security.jwt.audience`: (Optional) Expected audience claim value in JWT tokens. When configured, audience validation is enabled. + +**Optional: JWT Audience Validation** + +If your identity provider includes an audience claim in JWT tokens, you can enable audience validation: + + +{`--set security.jwt.audience="your-audience-value"`} + + +:::note +Audience validation is only performed when `security.jwt.audience` is configured. The value must match the audience claim (`aud`) in the JWT tokens issued by your identity provider. +::: + +#### Observability Plane Configuration + +The Observability Plane validates JWT tokens when querying logs and metrics through the Observer API. Configure your identity provider's OIDC settings: + + +{`helm upgrade --install openchoreo-observability-plane ${versions.helmSource}/openchoreo-observability-plane \\ + --version ${versions.helmChart} \\ + --namespace openchoreo-observability-plane \\ + --create-namespace \\ + --reuse-values \\ + --set security.oidc.issuer="https://your-idp.example.com" \\ + --set security.oidc.jwksUrl="https://your-idp.example.com/.well-known/jwks.json"`} + + +**Configuration Parameters:** + +- `security.oidc.issuer`: OIDC issuer URL (must match the `iss` claim in JWT tokens) +- `security.oidc.jwksUrl`: URL to provider's JWKS endpoint for token signature verification +- `security.jwt.audience`: (Optional) Expected audience claim value in JWT tokens. When configured, audience validation is enabled. +- `security.oidc.jwksUrlTlsInsecureSkipVerify`: (Optional) Skip TLS certificate verification for JWKS endpoint + +**Optional: JWT Audience Validation** + +If your identity provider includes an audience claim in JWT tokens, you can enable audience validation: + + +{`--set security.jwt.audience="your-audience-value"`} + + +**Optional: Skip TLS Verification** + +For development or testing environments where your identity provider uses self-signed certificates, you can skip TLS verification: + + +{`--set security.oidc.jwksUrlTlsInsecureSkipVerify="true"`} + + +:::warning +Only use `jwksUrlTlsInsecureSkipVerify="true"` in development or testing environments. For production deployments, ensure your identity provider uses valid TLS certificates. +::: + +## OAuth Client Configurations + +After integrating your identity provider, configure OAuth applications/clients for OpenChoreo components that require authentication. Each component needs specific redirect URIs and scopes configured in your identity provider. + +### Required OAuth Clients + +The following components require OAuth client configuration: + +**Backstage (Developer Portal):** +- For configuration steps, refer to the [Backstage Configuration](./backstage-configuration.mdx#authentication) guide + +**RCA Agent:** +- For configuration steps, refer to the [RCA Agent Configuration](./rca-agent.mdx#authentication) guide + +:::tip +Store sensitive values like client secrets using Kubernetes secrets rather than directly in helm values. Refer to the [Secret Management](./secret-management.mdx) guide for best practices. +::: + +## Obtaining Identity Provider Configuration + +Most OAuth2/OIDC compliant identity providers expose their configuration through a well-known endpoint. You can typically find all required URLs by accessing: + +``` +https://your-idp.example.com/.well-known/openid-configuration +``` + +This endpoint returns a JSON document containing: +- `issuer`: The issuer identifier +- `authorization_endpoint`: Authorization URL +- `token_endpoint`: Token URL +- `jwks_uri`: JWKS URL + +Refer to your identity provider's documentation for specific instructions on: +- Obtaining the well-known configuration endpoint +- Creating OAuth applications/clients +- Configuring redirect URIs +- Managing client credentials +- Setting up user groups and roles + +## Verification + +After configuring your identity provider, verify the setup: + +1. **Check Control Plane logs** for any authentication configuration errors: + + ```bash + kubectl logs -n openchoreo-control-plane --tail=50 + ``` + +2. **Test authentication flow** by accessing the Backstage UI and verifying you're redirected to your identity provider's login page + +3. **Verify token validation** by making authenticated API requests and checking that tokens are properly validated + +## Troubleshooting + +### Common Issues + +**Login redirect fails:** +- Verify redirect URIs in your OAuth application match exactly (including protocol and port) +- Check that authorization and token URLs are accessible from the cluster +- Ensure DNS resolution works for your identity provider endpoints + +**Token validation errors:** +- Ensure the `issuer` value matches the `iss` claim in JWT tokens +- Verify the JWKS URL is accessible and returns valid public keys +- Confirm the `audience` claim in tokens matches the configured value + +**Connection timeouts:** +- Verify network connectivity from the cluster to your identity provider +- Check firewall rules and network policies +- Ensure TLS certificates are valid and trusted + +For additional support, refer to the [OpenChoreo GitHub issues](https://github.com/openchoreo/openchoreo/issues) or join the [Discord community](https://discord.com/invite/asqDFC8suT). + +## Next Steps + +After configuring your identity provider: + +- [Configure Backstage](./backstage-configuration.mdx#authentication) OAuth client for the Backstage Portal +- [Set up Secret Management](./secret-management.mdx) for secure credential storage +- Review the [Control Plane](../reference/helm/control-plane.mdx) and [Observability Plane](../reference/helm/observability-plane.mdx) Helm references for all available configuration options diff --git a/versioned_docs/version-v0.11.x/operations/multi-cluster-connectivity.mdx b/versioned_docs/version-v0.11.x/operations/multi-cluster-connectivity.mdx new file mode 100644 index 0000000..153c6d4 --- /dev/null +++ b/versioned_docs/version-v0.11.x/operations/multi-cluster-connectivity.mdx @@ -0,0 +1,300 @@ +--- +title: Multi-Cluster Connectivity +description: Configure secure mTLS communication between OpenChoreo planes in multi-cluster deployments. +sidebar_position: 5 +--- + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + +# Multi-Cluster Connectivity + +When deploying OpenChoreo across multiple Kubernetes clusters (e.g., separate Control Plane and Data Plane clusters), you must explicitly establish trust between them. This guide covers the step-by-step process of exchanging certificates to secure the WebSocket connection between planes. + +## Overview + +The OpenChoreo Control Plane runs a **Cluster Gateway** that listens for incoming WebSocket connections from remote planes (Data Plane, Build Plane, Observability Plane). This connection is secured using **Mutual TLS (mTLS)**. + +1. **Server Trust:** The remote plane must trust the Control Plane's CA certificate to verify the Cluster Gateway's identity. +2. **Client Authentication:** The remote plane's **Cluster Agent** generates its own client certificate using a local self-signed issuer. This certificate must be registered with the Control Plane to allow the connection. + +:::note +In multi-cluster deployments, the agent's client certificate is self-signed because the Control Plane's CA private key cannot be shared across clusters. The Control Plane trusts the agent by explicitly registering the agent's certificate in the DataPlane/BuildPlane/ObservabilityPlane CRD. +::: + +## Prerequisites + +- **Control Plane** installed in a primary cluster +- **Remote Cluster** (Data, Build, or Observability) where the remote plane will be installed +- `kubectl` context configured for both clusters +- **cert-manager** installed on both clusters (Control Plane for gateway certificate, remote cluster for agent certificate) + +## Step 0: Configure Cluster Gateway DNS Names + +Before extracting the CA, ensure the Control Plane's Cluster Gateway certificate includes your public DNS name. By default, the certificate only includes internal cluster DNS names. + +When installing or upgrading the Control Plane, add your public DNS name: + +```bash +helm upgrade --install openchoreo-control-plane oci://ghcr.io/openchoreo/helm-charts/openchoreo-control-plane \ + --namespace openchoreo-control-plane \ + # ... other values ... + --set "clusterGateway.tls.dnsNames[0]=cluster-gateway.openchoreo-control-plane.svc" \ + --set "clusterGateway.tls.dnsNames[1]=cluster-gateway.openchoreo-control-plane.svc.cluster.local" \ + --set "clusterGateway.tls.dnsNames[2]=cluster-gateway.openchoreo.${DOMAIN}" +``` + +Or in a values file: + +```yaml +clusterGateway: + tls: + dnsNames: + - cluster-gateway.openchoreo-control-plane.svc + - cluster-gateway.openchoreo-control-plane.svc.cluster.local + - cluster-gateway.openchoreo.example.com # Your public DNS name +``` + +:::warning +The `serverUrl` hostname in Step 2 must match one of the DNS names in the Cluster Gateway certificate. If not, TLS verification will fail with a certificate error. +::: + +## Step 1: Extract Control Plane CA + +The Control Plane generates a Certificate Authority (CA) used to sign the Cluster Gateway's serving certificate. Remote planes need this CA to verify they are connecting to the authentic Control Plane. + +Run this command against your **Control Plane cluster**: + +```bash +# Set your Control Plane context and namespace +export CP_CONTEXT="my-control-plane-cluster" +export CP_NAMESPACE="openchoreo-control-plane" + +# Extract the CA certificate from the ConfigMap +export CP_CA_CERT=$(kubectl --context $CP_CONTEXT get configmap cluster-gateway-ca \ + -n $CP_NAMESPACE -o jsonpath='{.data.ca\.crt}') + +# Verify the output (should start with -----BEGIN CERTIFICATE-----) +echo "$CP_CA_CERT" | head -n 5 +``` + +:::warning +Ensure you extract the CA from the `cluster-gateway-ca` **ConfigMap**, not the TLS Secret. The ConfigMap contains the public CA certificate in plain text, which is what the Helm chart expects. +::: + +## Step 2: Install Remote Plane with CA + +When installing a remote plane (e.g., Data Plane), pass the extracted CA certificate to the Helm chart. This configures the Cluster Agent to trust your Control Plane and use a locally-generated client certificate. + +**Example: Data Plane Installation** + +First, save the extracted CA certificate to a file: + +```bash +# Save the CA certificate to a file +echo "$CP_CA_CERT" > ./server-ca.crt +``` + +Then install the Data Plane: + +```bash +# Set your Data Plane context +export DP_CONTEXT="my-data-plane-cluster" +export DOMAIN="example.com" + +helm upgrade --install openchoreo-data-plane oci://ghcr.io/openchoreo/helm-charts/openchoreo-data-plane \ + --version \ + --kube-context $DP_CONTEXT \ + --namespace openchoreo-data-plane \ + --create-namespace \ + --set clusterAgent.enabled=true \ + --set clusterAgent.serverUrl="wss://cluster-gateway.openchoreo.${DOMAIN}/ws" \ + --set clusterAgent.tls.enabled=true \ + --set clusterAgent.tls.generateCerts=true \ + --set-file clusterAgent.tls.serverCAValue=./server-ca.crt \ + --set clusterAgent.tls.caSecretName="" \ + --set clusterAgent.tls.caSecretNamespace="" +``` + +### Key Parameters + +| Parameter | Description | +|-----------|-------------| +| `clusterAgent.serverUrl` | The public WebSocket URL of your Control Plane's Cluster Gateway (e.g., `wss://cluster-gateway.openchoreo.example.com/ws`) | +| `clusterAgent.tls.generateCerts` | Set to `true` to generate client certificates locally instead of copying from control plane | +| `clusterAgent.tls.serverCAValue` | The CA certificate file from Step 1. Used to verify the Cluster Gateway's identity. Use `--set-file` for proper PEM formatting. | +| `clusterAgent.tls.caSecretName` | Set to empty (`""`) to use a self-signed issuer for generating the agent's client certificate | +| `clusterAgent.tls.caSecretNamespace` | Set to empty (`""`) along with `caSecretName` | + +:::info Why self-signed client certificates? +In multi-cluster deployments, the remote plane cannot access the Control Plane's CA private key (only the public certificate is available). Therefore, the agent generates its own client certificate using a local self-signed issuer. This certificate is then registered with the Control Plane in Step 4, establishing mutual trust. +::: + +## Step 3: Extract Agent Client Certificate + +After the remote plane is installed, its `cert-manager` will generate a client certificate for the Cluster Agent. You need to extract this certificate to register the plane. + +Run this command against your **Remote Cluster** (Data/Build/Observability): + +```bash +# Set your Remote Plane context and namespace +export REMOTE_CONTEXT="my-data-plane-cluster" +export REMOTE_NAMESPACE="openchoreo-data-plane" + +# Wait for the certificate to be ready +kubectl --context $REMOTE_CONTEXT wait --for=condition=Ready \ + certificate/cluster-agent-dataplane-tls -n $REMOTE_NAMESPACE --timeout=120s + +# Extract the agent's client certificate +export AGENT_CERT=$(kubectl --context $REMOTE_CONTEXT get secret cluster-agent-tls \ + -n $REMOTE_NAMESPACE -o jsonpath='{.data.tls\.crt}' | base64 -d) + +# Verify the output (should start with -----BEGIN CERTIFICATE-----) +echo "$AGENT_CERT" | head -n 5 +``` + +:::tip +If the certificate is not ready, check the cert-manager logs and the Certificate resource status: +```bash +kubectl --context $REMOTE_CONTEXT describe certificate cluster-agent-dataplane-tls -n $REMOTE_NAMESPACE +``` +::: + +## Step 4: Register Plane in Control Plane + +Finally, register the remote plane by creating the appropriate CRD (`DataPlane`, `BuildPlane`, or `ObservabilityPlane`) in the Control Plane cluster. You must embed the `AGENT_CERT` extracted in Step 3. + +**Example: Registering a Data Plane** + +```bash +# Create the DataPlane resource in the Control Plane +cat < \ + --kube-context $REMOTE_CONTEXT \ + --namespace openchoreo-build-plane \ + --create-namespace \ + --set clusterAgent.enabled=true \ + --set clusterAgent.serverUrl="wss://cluster-gateway.openchoreo.${DOMAIN}/ws" \ + --set clusterAgent.tls.enabled=true \ + --set clusterAgent.tls.generateCerts=true \ + --set-file clusterAgent.tls.serverCAValue=./server-ca.crt \ + --set clusterAgent.tls.caSecretName="" \ + --set clusterAgent.tls.caSecretNamespace="" +``` + +### Observability Plane + +```bash +helm upgrade --install openchoreo-observability-plane oci://ghcr.io/openchoreo/helm-charts/openchoreo-observability-plane \ + --version \ + --kube-context $REMOTE_CONTEXT \ + --namespace openchoreo-observability-plane \ + --create-namespace \ + --set clusterAgent.enabled=true \ + --set clusterAgent.serverUrl="wss://cluster-gateway.openchoreo.${DOMAIN}/ws" \ + --set clusterAgent.tls.enabled=true \ + --set clusterAgent.tls.generateCerts=true \ + --set-file clusterAgent.tls.serverCAValue=./server-ca.crt \ + --set clusterAgent.tls.caSecretName="" \ + --set clusterAgent.tls.caSecretNamespace="" +``` + +## Troubleshooting + +### Certificate Not Ready + +If the certificate fails to become ready: + +```bash +# Check certificate status +kubectl describe certificate cluster-agent-dataplane-tls -n openchoreo-data-plane + +# Check cert-manager logs +kubectl logs -n cert-manager deployment/cert-manager +``` + +Common issues: +- **Issuer not found**: Ensure the Helm chart completed successfully and the self-signed issuer was created +- **Permission denied**: Check that cert-manager has permissions to create secrets in the namespace + +### Agent Cannot Connect + +If the agent fails to connect to the Control Plane: + +```bash +# Check agent logs for connection errors +kubectl logs -n openchoreo-data-plane -l app=cluster-agent + +# Verify the server CA ConfigMap exists +kubectl get configmap cluster-gateway-ca -n openchoreo-data-plane +``` + +Common issues: +- **Certificate verification failed**: Ensure `serverCAValue` contains the correct CA certificate from the Control Plane +- **Connection refused**: Verify the `serverUrl` is accessible from the remote cluster and the Cluster Gateway ingress is properly configured + +### TLS Certificate Error (x509: certificate is valid for X, not Y) + +If you see an error like `x509: certificate is valid for cluster-gateway.openchoreo-control-plane.svc, not cluster-gateway.openchoreo.example.com`: + +The Cluster Gateway's server certificate doesn't include your public DNS name. Update the Control Plane with the correct DNS names (see Step 0): + +```bash +# Check current certificate DNS names +kubectl get certificate cluster-gateway-tls -n openchoreo-control-plane -o jsonpath='{.spec.dnsNames}' + +# After updating the Helm values, the certificate will be re-issued +# You may need to delete the old certificate to force regeneration +kubectl delete certificate cluster-gateway-tls -n openchoreo-control-plane +``` + +After updating, re-extract the CA certificate (Step 1) as the certificate may have been regenerated. + +### Agent Certificate Not Trusted + +If the Control Plane rejects the agent's connection: + +```bash +# Check Control Plane controller-manager logs +kubectl logs -n openchoreo-control-plane deployment/controller-manager +``` + +Ensure the DataPlane/BuildPlane/ObservabilityPlane CRD has the correct agent certificate in `spec.agent.clientCA.value` diff --git a/versioned_docs/version-v0.11.x/operations/observability-alerting.mdx b/versioned_docs/version-v0.11.x/operations/observability-alerting.mdx new file mode 100644 index 0000000..6be2eda --- /dev/null +++ b/versioned_docs/version-v0.11.x/operations/observability-alerting.mdx @@ -0,0 +1,522 @@ +--- +title: Observability & Alerting +description: Configure logging, metrics, tracing, and alerting for OpenChoreo. +sidebar_position: 9 +--- + +import CodeBlock from '@theme/CodeBlock'; +import {versions} from '../_constants.mdx'; + +# Observability & Alerting + +OpenChoreo provides an optional observability plane, which consists of a comprehensive observability stack for monitoring applications deployed on the platform. + +This guide covers how to configure and use logging, metrics, traces, and alerting capabilities. + +## Overview + +OpenChoreo's default observability architecture consists of: + +| Pillar | Components | +|--------|-----------| +| **Logs** | Fluent Bit as the log collector and OpenSearch as the log storage | +| **Metrics** | Prometheus to collect and store metrics| +| **Traces** | OpenTelemetry Collector as the trace collector and processor, and OpenSearch as the trace storage | +| **Alerting** | Prometheus Alertmanager for metric alerts, and OpenSearch Alerting for log alerts | + +All observability data is accessible through the **Observer API**, which provides a unified interface for querying logs, metrics, and traces. + +## Architecture + +### Single-Cluster Setup + +In single-cluster mode, all planes run in the same Kubernetes cluster. +Observability data is collected directly from the data planes and build plane +via the agents deployed in the observability plane. + +```mermaid +--- +config: + layout: elk +--- +flowchart LR + subgraph OP["Observability Plane"] + direction LR + FluentBit["Fluent Bit
(Collect logs)"] + OpenSearch["OpenSearch
(Store logs & traces)"] + OTel["OpenTelemetry Collector
(Collect traces)"] + ObserverAPI["Observer API"] + OSAlerting["OpenSearch Alerting"] + PAM["Prometheus Alertmanager"] + Prometheus["Prometheus
(Collect & store metrics)"] + end + FluentBit -- Publish logs --> OpenSearch + OTel -- Publish traces --> OpenSearch + ObserverAPI -- Query logs/traces --> OpenSearch + ObserverAPI -- Query metrics --> Prometheus + OUT1(["Backstage/CLI/MCP"]) -- Query logs, metrics, traces --> ObserverAPI + ObserverAPI -- Send alert notifications --> OUT2(["Alert Channels (SMTP, Slack)"]) + OSAlerting -. Notify log alerts .-> ObserverAPI + PAM -. Notify metric alerts .-> ObserverAPI +``` + +### Multi-Cluster Setup + +In multi-cluster mode, the observability plane runs on a dedicated cluster. +Data planes and build plane deploy local collectors that publish observability data +to the observability plane through gateway ingress. + +```mermaid +--- +config: + layout: elk +--- +flowchart BT + subgraph ObservabilityPlane["Observability Plane Cluster"] + direction TB + Prometheus["Prometheus
(Store metrics)"] + OpenSearch["OpenSearch
(Store logs & traces)"] + OTelCollector["OpenTelemetry Collector
(Process traces)"] + ObserverAPI["Observer API"] + GatewayIngress["Gateway Ingress
(Receives logs, metrics,
traces from other planes)"] + OSAlerting["OpenSearch Alerting"] + PAM["Prometheus Alertmanager"] + end + subgraph DataPlane["Data Plane Cluster"] + direction LR + OTelDP["OpenTelemetry Collector
(Collect traces)"] + FluentBitDP["Fluent Bit
(Collect logs)"] + PrometheusAgentDP["Prometheus Agent
(Collect metrics)"] + end + subgraph BuildPlane["Build Plane Cluster"] + FluentBitBP["Fluent Bit
(Collect logs)"] + end + GatewayIngress -.-> Prometheus & OpenSearch & OTelCollector + OTelCollector -.-> OpenSearch + ObserverAPI -- Query logs/traces --> OpenSearch + ObserverAPI -- Query metrics --> Prometheus + OSAlerting -. Notify log alerts .-> ObserverAPI + PAM -. Notify metric alerts .-> ObserverAPI + ObserverAPI -- Send alert notifications --> AlertChannels(["Alert Channels (SMTP, Slack)"]) + DataPlane -- Publish logs, metrics, traces --> GatewayIngress + BuildPlane -- Publish logs --> GatewayIngress + BackstageClient(["Backstage/CLI/MCP"]) -- Query logs, metrics, traces --> ObserverAPI +``` + +In this setup: +- **Data Plane** deploys Fluent Bit to collect logs, Prometheus Agent to collect metrics, and OpenTelemetry Collector to collect traces +- **Build Plane** deploys Fluent Bit to collect build logs +- All collectors publish data to the **Gateway** in the Observability Plane +- The **Observer API** queries OpenSearch and Prometheus to serve unified observability data + +For detailed multi-cluster setup instructions, see [Multi-Cluster Connectivity](./multi-cluster-connectivity.mdx). + +## Prerequisites + +- OpenChoreo control plane installed +- Data plane and build plane (optional) installed to observe +- Observability plane installed (see [Installation](#installing-the-observability-plane)) + +### Resource Requirements + +| Component | CPU Request | CPU Limit | Memory Request | Memory Limit | +|-----------|-------------|-----------|----------------|--------------| +| OpenSearch (per node) | 100m | 1000m | 1Gi | 1Gi | +| Observer | 100m | 200m | 128Mi | 200Mi | +| Prometheus | 100m | 200m | 128Mi | 256Mi | +| Fluent Bit | 100m | 200m | 128Mi | 256Mi | +| OpenTelemetry Collector | 50m | 100m | 100Mi | 200Mi | + +## Installing the Observability Plane + +Refer to [Getting Started](../getting-started/try-it-out/on-self-hosted-kubernetes.mdx#step-4-setup-observability-plane-optional) +or [Multi-Cluster Connectivity](./multi-cluster-connectivity.mdx#observability-plane) +for instructions on installing the observability plane in single-cluster or multi-cluster mode. + +--- + +## Observability + +### Logs + +OpenChoreo collects container logs using **Fluent Bit** and stores them in **OpenSearch**. +By default, logs are collected from all containers in the cluster, except for the Fluent Bit containers. +Collected logs are enriched with Kubernetes metadata to support querying by OpenChoreo labels. + +#### Log Collection Configuration + +The Fluent Bit configuration can be customized via Helm values: + +```yaml +fluent-bit: + enabled: true + config: + inputs: | + [INPUT] + Name tail + Path /var/log/containers/*.log + Tag kube.* + # ... additional configuration + filters: | + [FILTER] + Name kubernetes + Match kube.* + Merge_Log On + outputs: | + [OUTPUT] + Name opensearch + Host opensearch + Port 9200 + Match kube.* +``` + +#### Logs Retention Configuration + +Collected logs are retained for a default of 30 days and can be configured as required. + +#### Querying Logs + +The Observer API provides a REST API for querying logs of a specific OpenChoreo component. +This can be accessed via the Backstage portal, OpenChoreo CLI or OpenChoreo MCP server. +Observer handles the authentication and authorization based on OpenChoreo user identity. + +--- + +### Metrics + +OpenChoreo collects metrics using **Prometheus** and **kube-state-metrics**. The metrics stack provides: + +- Container resource metrics (CPU, memory) +- HTTP request metrics (when instrumented via Hubble with Cilium CNI) + +#### Available Metrics + +| Metric Type | Description | Source | +|-------------|-------------|--------| +| CPU Usage | Container CPU utilization | cAdvisor | +| Memory Usage | Container memory consumption | cAdvisor | +| HTTP Requests | Request counts, latency | Hubble (Requires Cilium CNI) | + +#### Querying Metrics + +The Observer API provides a REST API for querying metrics of a specific OpenChoreo component. +This can be accessed via the Backstage portal, OpenChoreo CLI or OpenChoreo MCP server. +Observer handles the authentication and authorization based on OpenChoreo user identity. + +--- + +### Traces + +OpenChoreo supports distributed tracing using **OpenTelemetry**. +The OpenTelemetry Collector receives traces via OTLP, enriches them with Kubernetes metadata, +applies sampling policies, and exports them to OpenSearch. + +#### Trace Pipeline + +The OpenTelemetry Collector processes traces through the following pipeline: + +1. **Receivers**: Accepts traces via OTLP protocol (gRPC on port 4317, HTTP on port 4318) +2. **Processors**: + - `k8sattributes`: Enriches traces with OpenChoreo labels + - `tail_sampling`: Applies rate limiting to control trace volume +3. **Exporters**: Sends processed traces to OpenSearch (index: `otel-traces-*`) + +#### Instrumenting Applications + +Applications must be instrumented to send traces to the OpenTelemetry Collector. Configure your application to send OTLP traces to one of the following endpoints: + +| Protocol | Endpoint | +|----------|----------| +| HTTP | `http://opentelemetry-collector.openchoreo-observability-plane.svc.cluster.local:4318/v1/traces` | +| gRPC | `opentelemetry-collector.openchoreo-observability-plane.svc.cluster.local:4317` | + +**Example: OpenTelemetry SDK Configuration (Go)** + +```go +import ( + "go.opentelemetry.io/otel" + "go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracehttp" +) + +exporter, _ := otlptracehttp.New(ctx, + otlptracehttp.WithEndpoint("opentelemetry-collector.openchoreo-observability-plane:4318"), + otlptracehttp.WithInsecure(), +) +``` + +#### Trace Sampling Configuration + +The OpenTelemetry Collector uses tail-based sampling to control the volume of traces stored. Configure sampling via Helm values: + +```yaml +opentelemetryCollectorCustomizations: + tailSampling: + decisionWait: 10s # Time to wait before making sampling decision + numTraces: 100 # Number of traces to keep in memory + expectedNewTracesPerSec: 10 # Expected new traces per second + spansPerSecond: 10 # Maximum spans per second rate limit + decisionCache: + sampledCacheSize: 10000 + nonSampledCacheSize: 1000 +``` + +#### Querying Traces + +The Observer API provides a REST API for querying traces of a specific OpenChoreo project. +This can be accessed via the Backstage portal, OpenChoreo CLI or OpenChoreo MCP server. +Observer handles the authentication and authorization based on OpenChoreo user identity. + +--- + +## Alerting + +OpenChoreo provides alerting based on logs and resource usage metrics. +Alert rules are defined as traits on components and are automatically created for each environment by the control plane during component releases. +Alert notifications are configured as notification channels and are sent through the notification channel when an alert is triggered. + +### Alert Rule Configuration + +OpenChoreo ships a default trait named `observability-alertrule` that can be used to define alert rules on components. +Platform engineers can define their own traits to create custom alert rules as required. + +```yaml +traits: + - name: observability-alertrule + instanceName: high-error-rate-log-alert + parameters: + description: "Triggered when error logs count exceeds 50 in 5 minutes." + severity: "critical" + source: + type: "log" + query: "status:error" + condition: + window: 5m + interval: 1m + operator: gt + threshold: 50 +``` + +Override the environment-specific parameters for the alert rule in the `ReleaseBinding` CR. + +```yaml +spec: + traitOverrides: + high-error-rate-log-alert: + enabled: true + enableAiRootCauseAnalysis: false + notificationChannel: devops-email-notifications +``` + +### Alert Source Types + +| Type | Description | Use Case | +|------|-------------|----------| +| `log` | Log-based alerting | Error patterns, specific log messages | +| `metric` | Metric-based alerting | Resource utilization (CPU, memory) | + +### Alert Condition Operators + +| Operator | Description | +|----------|-------------| +| `gt` | Greater than | +| `lt` | Less than | +| `gte` | Greater than or equal | +| `lte` | Less than or equal | +| `eq` | Equal to | + +### Notification Channels + +Configure notification channels to receive alerts. +Platform Engineers can configure notification channels per environment. +The first notification channel created in an environment is marked as the default channel. +The default channel is used by alert rules that don't specify a channel. + +```yaml +apiVersion: openchoreo.dev/v1alpha1 +kind: ObservabilityAlertsNotificationChannel +metadata: + name: my-notification-channel + namespace: default-organization +spec: + environment: development + isEnvDefault: true + type: email + config: + from: alerts@example.com + to: + - team@example.com + - oncall@example.com + smtp: + host: smtp.example.com + port: 587 + auth: + username: + secretKeyRef: + name: smtp-credentials + key: username + password: + secretKeyRef: + name: smtp-credentials + key: password + tls: + insecureSkipVerify: false + template: + subject: "[${alertSeverity}] ${alertName} Triggered" + body: | + Alert: ${alertName} + Severity: ${alertSeverity} + Time: ${alertTimestamp} + Description: ${alertDescription} + Component: ${component} + Project: ${project} + Environment: ${environment} +``` + +### AI-Powered Root Cause Analysis + +When `enableAiRootCauseAnalysis` is enabled on an alert rule, OpenChoreo's RCA Agent automatically analyzes the alert and generates a root cause analysis report. + +See [RCA Agent](./rca-agent.mdx) for configuration details. + +--- + +## Viewing Observability Data + +### OpenSearch Dashboards + +Enable OpenSearch Dashboards for visual exploration of logs and traces: + + +{`helm upgrade --install openchoreo-observability-plane ${versions.helmSource}/openchoreo-observability-plane \\ + --version ${versions.helmChart} \\ + --namespace openchoreo-observability-plane \\ + --reuse-values \\ + --set openSearchCluster.dashboards.enable=true`} + + +Port-forward OpenSearch Dashboards to view logs and traces: + +```bash +kubectl port-forward svc/opensearch-dashboards 5601:5601 -n openchoreo-observability-plane +``` + +Open `http://localhost:5601` in your browser to access OpenSearch Dashboards. + +### Grafana + +Enable Grafana for metrics visualization: + + +{`helm upgrade --install openchoreo-observability-plane ${versions.helmSource}/openchoreo-observability-plane \\ + --version ${versions.helmChart} \\ + --namespace openchoreo-observability-plane \\ + --reuse-values \\ + --set prometheus.grafana.enabled=true`} + + +Port-forward Grafana to view metrics: + +```bash +kubectl port-forward svc/grafana 5000:80 -n openchoreo-observability-plane +``` + +Open `http://localhost:5000` in your browser to access Grafana. + +Default credentials: `admin` / `admin` + +--- + +## Configuration Reference + +### Key Helm Values + +| Value | Default | Description | +|-------|---------|-------------| +| `fluent-bit.enabled` | `true` | Enable log collection | +| `prometheus.enabled` | `true` | Enable metrics collection | +| `opentelemetry-collector.enabled` | `true` | Enable OpenTelemetry Collector for traces | +| `openSearch.enabled` | `false` | Enable OpenSearch single node mode | +| `openSearchCluster.enabled` | `true` | Enable OpenSearch HA mode | +| `openSearchCluster.dashboards.enable` | `false` | Enable OpenSearch Dashboards for HA mode | +| `prometheus.grafana.enabled` | `true` | Enable Grafana | +| `rca.enabled` | `false` | Enable AI RCA Agent | + +For complete configuration options, see the [Observability Plane Helm Reference](/docs/reference/helm/observability-plane). + +--- + +## Troubleshooting + +### Logs Not Appearing + +1. Verify Fluent Bit is running: + + ```bash + kubectl get pods -n openchoreo-observability-plane -l app.kubernetes.io/name=fluent-bit + ``` + +2. Check Fluent Bit logs: + + ```bash + kubectl logs -n openchoreo-observability-plane -l app.kubernetes.io/name=fluent-bit + ``` + +3. Verify OpenSearch is healthy: + + ```bash + kubectl get pods -n openchoreo-observability-plane -l app=opensearch + ``` + +### Metrics Not Available + +1. Verify Prometheus is running: + + ```bash + kubectl get pods -n openchoreo-observability-plane -l app.kubernetes.io/name=prometheus + ``` + +2. Check if ServiceMonitors are being discovered: + + ```bash + kubectl get servicemonitors --all-namespaces + ``` + +### Traces Not Appearing + +1. Verify OpenTelemetry Collector is running: + + ```bash + kubectl get pods -n openchoreo-observability-plane -l app.kubernetes.io/name=opentelemetry-collector + ``` + +2. Check OpenTelemetry Collector logs for errors: + + ```bash + kubectl logs -n openchoreo-observability-plane -l app.kubernetes.io/name=opentelemetry-collector + ``` + +3. Verify your application is configured to send traces to the correct endpoint (port 4317 for gRPC, port 4318 for HTTP). + +### Alert Not Firing + +1. Verify the alert rule status after a component is deployed: + + ```bash + kubectl get observabilityalertrules -n + kubectl describe observabilityalertrule -n + ``` + +2. Check the Observer logs for alert processing errors: + + ```bash + kubectl logs -n openchoreo-observability-plane deployment/observer + ``` + +--- + +## Related Documentation + +- [RCA Agent](./rca-agent.mdx) - AI-powered root cause analysis +- [Deployment Topology](./deployment-topology.mdx) - Multi-plane architecture overview +- [Multi-Cluster Connectivity](./multi-cluster-connectivity.mdx) - Connecting planes across clusters +- [Observability Plane Helm Reference](/docs/reference/helm/observability-plane) - Complete Helm configuration options diff --git a/versioned_docs/version-v0.11.x/operations/rca-agent.mdx b/versioned_docs/version-v0.11.x/operations/rca-agent.mdx new file mode 100644 index 0000000..cbcba2e --- /dev/null +++ b/versioned_docs/version-v0.11.x/operations/rca-agent.mdx @@ -0,0 +1,84 @@ +--- +title: RCA Agent +description: Configure the Root Cause Analysis (RCA) Agent in OpenChoreo. +sidebar_position: 10 +--- + +import CodeBlock from '@theme/CodeBlock'; +import {versions} from '../_constants.mdx'; + +# RCA Agent + +The RCA (Root Cause Analysis) Agent is an AI-powered component that analyzes logs, metrics, and traces from your OpenChoreo deployments to generate reports with likely root causes of issues. It integrates with Large Language Models (LLMs) to provide intelligent analysis and actionable insights. + +:::note +AI-generated analysis may contain errors. Always verify the findings before taking action. +::: + +## Prerequisites + +Before enabling the RCA Agent, ensure the following: + +- OpenChoreo Observability Plane installed +- An LLM API key +- [Alerting configured](./observability-alerting.mdx) for your components with `enableAiRootCauseAnalysis` enabled. + +:::tip +For best results, we recommend using the latest models from [OpenAI](https://platform.openai.com/) or [Anthropic](https://console.anthropic.com/). +::: + +:::note +Enable automatic RCA only for critical alerts to manage LLM costs. For less critical alerts, you can trigger RCA analysis manually when needed. +::: + +## LLM Configuration + +The RCA Agent requires an LLM provider to perform root cause analysis. Configure the model name and API key: + +**Configuration Parameters:** + +- `rca.llm.modelName`: LLM model name (e.g., `gpt-5`, `claude-sonnet-4-5`, `gemini-2.0-flash`) +- `rca.llm.apiKey`: API key for the LLM provider + +## Enabling the RCA Agent + +To enable the RCA Agent, set `rca.enabled=true` and configure the LLM configuration when installing or upgrading the Observability Plane: + + +{`helm upgrade --install openchoreo-observability-plane ${versions.helmSource}/openchoreo-observability-plane \\ + --version ${versions.helmChart} \\ + --namespace openchoreo-observability-plane \\ + --reuse-values \\ + --set rca.enabled=true \\ + --set rca.llm.modelName= \\ + --set rca.llm.apiKey=`} + + +## Using an External Identity Provider + +By default, OpenChoreo configures Thunder as the identity provider for the RCA Agent with a pre-configured OAuth client for testing purposes. If you are using an external identity provider, create an OAuth 2.0 client that supports the `client_credentials` grant type for service-to-service authentication. + +Once you have created the OAuth client, enable the RCA Agent with the OAuth credentials: + + +{`helm upgrade --install openchoreo-observability-plane ${versions.helmSource}/openchoreo-observability-plane \\ + --version ${versions.helmChart} \\ + --namespace openchoreo-observability-plane \\ + --reuse-values \\ + --set rca.enabled=true \\ + --set security.oidc.tokenUrl= \\ + --set rca.oauth.clientId= \\ + --set rca.oauth.clientSecret= \\ + --set rca.llm.modelName= \\ + --set rca.llm.apiKey=`} + + +See [Identity Provider Configuration](./identity-configuration.mdx) for detailed setup instructions. + +## Verifying the Installation + +Check that the RCA Agent pod is running: + +```bash +kubectl get pods -n openchoreo-observability-plane -l app.kubernetes.io/component=ai-rca-agent +``` diff --git a/versioned_docs/version-v0.11.x/operations/secret-management.mdx b/versioned_docs/version-v0.11.x/operations/secret-management.mdx new file mode 100644 index 0000000..a3b89f9 --- /dev/null +++ b/versioned_docs/version-v0.11.x/operations/secret-management.mdx @@ -0,0 +1,175 @@ +--- +title: Secret Management +description: Manage secrets and sensitive configuration in OpenChoreo. +sidebar_position: 8 +--- + +# Secret Management + +OpenChoreo integrates with [External Secrets Operator (ESO)](https://external-secrets.io/) to synchronize secrets from external secret stores into Kubernetes. This integration allows you to: + +- **Bring your own secret store**: Use any ESO-supported backend (HashiCorp Vault, AWS Secrets Manager, Azure Key Vault, GCP Secret Manager, and [many more](https://external-secrets.io/latest/provider/)) +- **Use existing External Secrets setup**: If you already have ESO deployed, OpenChoreo can work with your existing `ClusterSecretStore` configurations +- **Centralized secret management**: Manage all secrets in your preferred external store and let ESO sync them to Kubernetes + +## Enabling External Secrets Operator + +ESO is included as an optional dependency in the plane Helm charts. Enable it by setting `external-secrets.enabled: true` in your values: + +**Data Plane:** + +```yaml +external-secrets: + enabled: true +``` + +**Build Plane (if needed):** + +```yaml +external-secrets: + enabled: true +``` + +**Observability Plane (if needed):** + +```yaml +external-secrets: + enabled: true +``` + +:::tip Single vs. Multi-Cluster +For single-cluster deployments, you typically only need ESO enabled in one plane (usually the Data Plane). For multi-cluster deployments, enable ESO in each cluster where you need secret synchronization. +::: + +## Using Your Existing External Secrets Setup + +If you already have External Secrets Operator deployed in your cluster with a configured `ClusterSecretStore`, you can skip enabling ESO in the OpenChoreo charts and simply reference your existing store. + +Configure your DataPlane to use your existing SecretStore: + +```yaml +apiVersion: openchoreo.dev/v1alpha1 +kind: DataPlane +metadata: + name: default + namespace: my-organization +spec: + secretStoreRef: + name: your-existing-secret-store + # ... other configuration +``` + +## Configuring a ClusterSecretStore + +To connect ESO to your secret backend, create a `ClusterSecretStore` resource. For provider-specific configuration (authentication methods, endpoints, etc.), refer to the official ESO provider documentation: + +- **[HashiCorp Vault](https://external-secrets.io/latest/provider/hashicorp-vault/)** +- **[AWS Secrets Manager](https://external-secrets.io/latest/provider/aws-secrets-manager/)** +- **[GCP Secret Manager](https://external-secrets.io/latest/provider/google-secrets-manager/)** +- **[Azure Key Vault](https://external-secrets.io/latest/provider/azure-key-vault/)** +- **[All Supported Providers](https://external-secrets.io/latest/provider/)** + +**Example structure:** + +```yaml +apiVersion: external-secrets.io/v1 +kind: ClusterSecretStore +metadata: + name: my-secret-store +spec: + provider: + # Provider-specific configuration + # See: https://external-secrets.io/latest/provider/ +``` + +## Development Setup (Fake Provider) + +For development and testing, you can use the built-in fake provider which defines static secrets directly in your Helm values: + +```yaml +external-secrets: + enabled: true + +fakeSecretStore: + enabled: true + name: default + secrets: + - key: github-pat + value: "development-token" + - key: docker-username + value: "dev-user" + - key: docker-password + value: "dev-password" +``` + +:::warning +The fake provider is for development only. Never use it in production environments. +::: + +## Creating ExternalSecrets + +Create `ExternalSecret` resources to sync specific secrets from your backend. For complete documentation on ExternalSecret configuration, see the [ESO documentation](https://external-secrets.io/latest/api/externalsecret/). + +**Example:** + +```yaml +apiVersion: external-secrets.io/v1 +kind: ExternalSecret +metadata: + name: app-secrets + namespace: my-app +spec: + refreshInterval: 1h + secretStoreRef: + name: my-secret-store + kind: ClusterSecretStore + target: + name: app-secrets + creationPolicy: Owner + data: + - secretKey: database-url + remoteRef: + key: my-app/database + property: url +``` + +## Platform Secrets + +These secrets are used by OpenChoreo infrastructure components: + +| Secret | Purpose | Plane | +|--------|---------|-------| +| `backstage-backend-secret` | Backstage session encryption | Control | +| `thunder-client-secret` | OAuth client secret | Control | +| `cluster-gateway-ca` | Root CA for plane communication | Control | +| `cluster-agent-tls` | Agent mTLS certificates | All | +| `registry-credentials` | Container registry auth | Build/Data | + +## Troubleshooting + +### Check ExternalSecret Status + +```bash +kubectl get externalsecret -A +kubectl describe externalsecret -n +``` + +### Check ClusterSecretStore Status + +```bash +kubectl get clustersecretstore +kubectl describe clustersecretstore +``` + +### Check ESO Logs + +```bash +kubectl logs -n deployment/external-secrets +``` + +For detailed troubleshooting guidance, see the [ESO troubleshooting documentation](https://external-secrets.io/latest/guides/troubleshooting/). + +## Next Steps + +- [Deployment Topology](./deployment-topology.mdx): Configure SecretStore references in planes +- [External Secrets Operator Documentation](https://external-secrets.io/): Complete ESO reference diff --git a/versioned_docs/version-v0.11.x/operations/upgrades.mdx b/versioned_docs/version-v0.11.x/operations/upgrades.mdx new file mode 100644 index 0000000..5b70869 --- /dev/null +++ b/versioned_docs/version-v0.11.x/operations/upgrades.mdx @@ -0,0 +1,132 @@ +--- +title: Upgrades +description: How to upgrade OpenChoreo components to newer versions. +sidebar_position: 1 +--- + +import CodeBlock from '@theme/CodeBlock'; +import {versions} from '../_constants.mdx'; + +# Upgrading OpenChoreo + +This guide covers how to upgrade OpenChoreo components to newer versions. + +## Before You Upgrade + +1. **Review release notes** for the target version +2. **Backup critical data** (see below) +3. **Test in non-production** environment first +4. **Plan for downtime** if required by the release notes + +## Backup Recommendations + +Before upgrading, consider backing up: + +- **OpenChoreo CRDs and resources**: Organizations, Projects, Components, etc. +- **OpenSearch data** (if using Observability Plane) +- **Container registry data** (if using Build Plane) + +```bash +# Export OpenChoreo resources +kubectl get organizations,projects,components,dataplanes,buildplanes -A -o yaml > openchoreo-backup.yaml +``` + +## Upgrade Process + +### Single Cluster Deployment + +Upgrade each plane in order: + +**1. Control Plane** + + +{`helm upgrade openchoreo-control-plane ${versions.helmSource}/openchoreo-control-plane \\ + --version ${versions.helmChart} \\ + --namespace openchoreo-control-plane \\ + --reuse-values`} + + +Wait for pods to be ready: + +```bash +kubectl rollout status deployment -n openchoreo-control-plane +``` + +**2. Data Plane** + + +{`helm upgrade openchoreo-data-plane ${versions.helmSource}/openchoreo-data-plane \\ + --version ${versions.helmChart} \\ + --namespace openchoreo-data-plane \\ + --reuse-values`} + + +**3. Build Plane (if installed)** + + +{`helm upgrade openchoreo-build-plane ${versions.helmSource}/openchoreo-build-plane \\ + --version ${versions.helmChart} \\ + --namespace openchoreo-build-plane \\ + --reuse-values`} + + +**4. Observability Plane (if installed)** + + +{`helm upgrade openchoreo-observability-plane ${versions.helmSource}/openchoreo-observability-plane \\ + --version ${versions.helmChart} \\ + --namespace openchoreo-observability-plane \\ + --reuse-values`} + + +### Multi Cluster Deployment + +Follow the same order, but use `--kube-context` for each cluster: + +```bash +helm upgrade openchoreo-control-plane ... --kube-context $CP_CONTEXT +helm upgrade openchoreo-data-plane ... --kube-context $DP_CONTEXT +helm upgrade openchoreo-build-plane ... --kube-context $BP_CONTEXT +helm upgrade openchoreo-observability-plane ... --kube-context $OP_CONTEXT +``` + +## Verifying the Upgrade + +```bash +# Check helm releases +helm list -A + +# Check pod versions +kubectl get pods -n openchoreo-control-plane -o jsonpath='{.items[*].spec.containers[*].image}' + +# Check CRD versions +kubectl get crds | grep openchoreo +``` + +## Rollback + +If issues occur, rollback to the previous release: + +```bash +# List release history +helm history openchoreo-control-plane -n openchoreo-control-plane + +# Rollback to previous revision +helm rollback openchoreo-control-plane -n openchoreo-control-plane +``` + +## Version Compatibility + +| OpenChoreo Version | Kubernetes Version | Helm Version | +|--------------------|-------------------|--------------| +| 0.7.x | 1.32+ | 3.12+ | +| 0.6.x | 1.31+ | 3.12+ | +| 0.5.x | 1.30+ | 3.12+ | + +## Getting Help + +If you encounter issues during upgrade: + +1. Check the [FAQ](../reference/faq.md) +2. Review pod logs for errors +3. Open an issue on [GitHub](https://github.com/openchoreo/openchoreo/issues) diff --git a/versioned_docs/version-v0.11.x/overview/architecture.mdx b/versioned_docs/version-v0.11.x/overview/architecture.mdx new file mode 100644 index 0000000..267d418 --- /dev/null +++ b/versioned_docs/version-v0.11.x/overview/architecture.mdx @@ -0,0 +1,132 @@ +--- +title: Architecture +description: Explore how OpenChoreo is architected across control, data, CI, and observability planes, and how these components work together to deliver a comprehensive Internal Developer Platform. +--- + +import PlatformAPIDiagram from '../resources/openchoreo-platform-abstractions.png'; +import DeveloperAPIDiagram from '../resources/openchoreo-development-abstractions.png'; +import CellRuntimeDiagram from '../resources/openchoreo-cell-runtime-view.png'; + +# OpenChoreo Architecture +OpenChoreo is architected as a modular, Kubernetes-native control plane that integrates deeply with other open-source projects to provide a comprehensive, extensible Internal Developer Platform (IDP). + +The Control Plane acts as the orchestrator, transforming high-level platform and developer intent into actionable workloads deployed across Data Planes, while wiring them into the Observability Plane for visibility. + +The diagram below illustrates how these components interact. + +![](../resources/openchoreo_components.svg) + +Each plane in OpenChoreo operates as a distinct functional unit, with its own lifecycle, scaling behavior, and security boundaries. Together, these planes and supporting interfaces form the core components of the platform: +- [Control Plane](#control-plane) +- [Developer API](#developer-api) +- [Platform API](#platform-api) +- [Data Plane](#data-plane) +- [CI Plane](#ci-plane) +- [Observability Plane](#observability-plane) + +## Control Plane + +The brain of OpenChoreo. It watches developer- and platform-defined CRDs, validates and processes them, and coordinates activities across other planes. It translates intent such as "deploy this component" or "connect these services" into 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. + +![](../resources/openchoreo-diagram-v1-with-borders.png) + + +This view illustrates the full path from source code and platform configuration through build, deployment, API exposure, and runtime observability — all orchestrated by OpenChoreo. + +## Deployment Topologies +OpenChoreo supports multiple deployment patterns to suit different organizational needs, from local development to large-scale, multi-cluster production setups. +- In development or testing setups, all planes can be deployed into a single Kubernetes cluster using namespace isolation. +- In production environments, each plane is typically deployed in a separate cluster for scalability, fault tolerance, and security. +- Hybrid topologies are also supported, allowing teams to co-locate certain planes (e.g., Control + CI) for cost or operational efficiency. diff --git a/versioned_docs/version-v0.11.x/overview/what-is-openchoreo.mdx b/versioned_docs/version-v0.11.x/overview/what-is-openchoreo.mdx new file mode 100644 index 0000000..df61d61 --- /dev/null +++ b/versioned_docs/version-v0.11.x/overview/what-is-openchoreo.mdx @@ -0,0 +1,66 @@ +--- +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, Kgateway, 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. **Try It Out** - [On Self-Hosted Kubernetes](../getting-started/try-it-out/on-self-hosted-kubernetes.mdx) or [On Managed Kubernetes](../getting-started/try-it-out/on-managed-kubernetes.mdx) +4. **[Operations Guide](../operations/deployment-topology.mdx)** - Configure OpenChoreo for production +5. **[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.11.x/reference/api/application/build.md b/versioned_docs/version-v0.11.x/reference/api/application/build.md new file mode 100644 index 0000000..257cf7a --- /dev/null +++ b/versioned_docs/version-v0.11.x/reference/api/application/build.md @@ -0,0 +1,164 @@ +--- +title: Build API Reference +--- + +# Build + +:::warning Deprecated +The Build resource is deprecated as of OpenChoreo v0.4.0 and will be removed in a future release. +Use [WorkflowRun](workflowrun.md) in combination with [Workflow](../platform/workflow.md) for a more flexible and powerful workflow execution system. +::: + +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.11.x/reference/api/application/component.md b/versioned_docs/version-v0.11.x/reference/api/application/component.md new file mode 100644 index 0000000..b8d56e5 --- /dev/null +++ b/versioned_docs/version-v0.11.x/reference/api/application/component.md @@ -0,0 +1,168 @@ +--- +title: Component API Reference +--- + +# Component + +A Component represents a deployable unit of an application in OpenChoreo. It serves as the core abstraction that +references a platform-defined ComponentType (in `{workloadType}/{componentTypeName}` format) 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 | +| `componentType` | string | Yes | - | componentType in the format `{workloadType}/{componentTypeName}` (e.g., `deployment/web-app`). See [ComponentType](#componenttype-reference). | +| `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 Reference + +The `componentType` string points to a platform-defined ComponentType using the format `{workloadType}/{componentTypeName}`. +Examples: `deployment/service`, `cronjob/scheduled-task`, `deployment/web-application`. See [ComponentType](../platform/componenttype.md) +for details. + +### 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 + componentType: deployment/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 + componentType: deployment/web-app + 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.11.x/reference/api/application/componentdeployment.md b/versioned_docs/version-v0.11.x/reference/api/application/componentdeployment.md new file mode 100644 index 0000000..6d3f37a --- /dev/null +++ b/versioned_docs/version-v0.11.x/reference/api/application/componentdeployment.md @@ -0,0 +1,301 @@ +--- +title: ComponentDeployment API Reference (Deprecated) +--- + +# ComponentDeployment (Deprecated) + +:::warning Deprecated +ComponentDeployment has been replaced by [ReleaseBinding](../platform/releasebinding.md). Please use ReleaseBinding for new deployments. +::: + +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.11.x/reference/api/application/componentworkflowrun.md b/versioned_docs/version-v0.11.x/reference/api/application/componentworkflowrun.md new file mode 100644 index 0000000..5a9ee8a --- /dev/null +++ b/versioned_docs/version-v0.11.x/reference/api/application/componentworkflowrun.md @@ -0,0 +1,336 @@ +--- +title: ComponentWorkflowRun API Reference +--- + +# ComponentWorkflowRun + +A ComponentWorkflowRun represents a runtime execution instance of a ComponentWorkflow - a specialized workflow type +designed specifically for building components. ComponentWorkflowRuns bridge the gap between developer intent and CI/CD +execution for component builds, providing ownership tracking, structured repository information, and flexible build +parameters. + +:::note +ComponentWorkflowRuns currently support Argo Workflow-based workflows only. +::: + +## API Version + +`openchoreo.dev/v1alpha1` + +## Resource Definition + +### Metadata + +ComponentWorkflowRuns are namespace-scoped resources that must be created within an Organization's namespace. + +```yaml +apiVersion: openchoreo.dev/v1alpha1 +kind: ComponentWorkflowRun +metadata: + name: + namespace: # Organization namespace +``` + +### Spec Fields + +| Field | Type | Required | Default | Description | +|------------|-------------------------------------------------------------|----------|---------|---------------------------------------------------------------------------------------------| +| `owner` | [ComponentWorkflowOwner](#componentworkflowowner) | Yes | - | Owner information identifying the Component and Project for this build | +| `workflow` | [ComponentWorkflowRunConfig](#componentworkflowrunconfig) | Yes | - | Workflow configuration referencing the ComponentWorkflow and providing parameter values | + +### ComponentWorkflowOwner + +Owner information links the build execution to a specific component and project, enabling traceability and build +history tracking. + +| Field | Type | Required | Default | Description | +|-----------------|--------|----------|---------|---------------------------------------| +| `projectName` | string | Yes | - | Name of the project (min length: 1) | +| `componentName` | string | Yes | - | Name of the component (min length: 1) | + +### ComponentWorkflowRunConfig + +| Field | Type | Required | Default | Description | +|--------------------|--------|----------|---------|--------------------------------------------------------------------------------------------------| +| `name` | string | Yes | - | Name of the ComponentWorkflow CR to use for this execution (min length: 1) | +| `systemParameters` | object | Yes | - | Repository information following the required structure (url, revision.branch, revision.commit, appPath) | +| `parameters` | object | No | - | Developer-provided values conforming to the flexible parameter schema defined in the ComponentWorkflow | + +#### System Parameters Structure + +System parameters must follow this required structure: + +```yaml +systemParameters: + repository: + url: string # Required: Git repository URL (must start with http:// or https://) + revision: + branch: string # Required: Git branch name + commit: string # Optional: Specific commit SHA (7-40 hex characters) + appPath: string # Required: Path to application code within repository +``` + +#### Parameters + +The `parameters` field contains flexible configuration that matches the developer parameters schema defined in the +referenced ComponentWorkflow. These values are validated against the ComponentWorkflow's parameter schema. + +### Status Fields + +| Field | Type | Default | Description | +|------------------|---------------------------------------------------|---------|-------------------------------------------------------------| +| `conditions` | []Condition | [] | Standard Kubernetes conditions tracking execution state | +| `imageStatus` | [ComponentWorkflowImage](#componentworkflowimage) | - | Information about the built container image | +| `runReference` | [ResourceReference](#resourcereference) | - | Reference to the workflow execution resource in build plane | +| `resources` | [][ResourceReference](#resourcereference) | - | References to additional resources created in build plane (for cleanup) | + +#### ComponentWorkflowImage + +| Field | Type | Default | Description | +|---------|--------|---------|-----------------------------------------------------------------------| +| `image` | string | "" | Fully qualified image name (e.g., registry.example.com/myapp:v1.0.0) | + +#### ResourceReference + +| Field | Type | Default | Description | +|--------------|--------|---------|-----------------------------------------------------------------| +| `apiVersion` | string | "" | API version of the resource (e.g., "v1", "apps/v1") | +| `kind` | string | "" | Kind of the resource (e.g., "Secret", "ConfigMap", "Workflow") | +| `name` | string | "" | Name of the resource in the build plane cluster | +| `namespace` | string | "" | Namespace of the resource in the build plane cluster | + +#### Condition Types + +ComponentWorkflowRun resources use the following condition types to track execution state: + +- `WorkflowCompleted` - Indicates if the workflow has completed (successfully or with failure) +- `WorkflowRunning` - Indicates if the workflow is currently executing in the build plane +- `WorkflowSucceeded` - Indicates if the workflow execution completed successfully +- `WorkflowFailed` - Indicates if the workflow execution failed or errored +- `WorkloadUpdated` - Indicates if the Workload CR was successfully created/updated after workflow success + +#### Condition Reasons + +Common reasons used in ComponentWorkflowRun conditions: + +- `WorkflowPending` - Workflow has not been initiated yet +- `WorkflowRunning` - Workflow is currently executing +- `WorkflowSucceeded` - Workflow completed successfully +- `WorkflowFailed` - Workflow execution failed +- `WorkloadUpdated` - Workload CR successfully created/updated +- `WorkloadUpdateFailed` - Failed to create/update Workload CR + +## Examples + +### Google Cloud Buildpacks ComponentWorkflowRun + +```yaml +apiVersion: openchoreo.dev/v1alpha1 +kind: ComponentWorkflowRun +metadata: + name: reading-list-service-build-01 + namespace: default +spec: + owner: + projectName: "default" + componentName: "reading-list-service" + + workflow: + name: google-cloud-buildpacks + + systemParameters: + repository: + url: "https://github.com/openchoreo/sample-workloads" + revision: + branch: "main" + commit: "a1b2c3d4e5f6" + appPath: "/service-go-reading-list" + + parameters: + version: 1 + testMode: "integration" + command: ["npm", "run", "build"] + args: ["--production", "--verbose"] + resources: + cpuCores: 2 + memoryGb: 4 + timeout: "45m" + cache: + enabled: true + paths: ["/root/.npm", "/root/.cache"] + limits: + maxRetries: 5 + maxDurationMinutes: 90 +``` + +### Docker Build ComponentWorkflowRun + +```yaml +apiVersion: openchoreo.dev/v1alpha1 +kind: ComponentWorkflowRun +metadata: + name: customer-service-build-1 + namespace: default +spec: + owner: + projectName: my-project + componentName: customer-service + + workflow: + name: docker + + systemParameters: + repository: + url: "https://github.com/myorg/customer-service" + revision: + branch: "main" + commit: "abc123def456" + appPath: "." + + parameters: + docker: + context: "." + filePath: "./Dockerfile" + buildArgs: ["ENV=production", "VERSION=1.0.0"] +``` + +### ComponentWorkflowRun with Latest Commit + +```yaml +apiVersion: openchoreo.dev/v1alpha1 +kind: ComponentWorkflowRun +metadata: + name: frontend-build-latest + namespace: default +spec: + owner: + projectName: ecommerce + componentName: frontend-app + + workflow: + name: google-cloud-buildpacks + + systemParameters: + repository: + url: "https://github.com/myorg/frontend-app" + revision: + branch: "develop" + # No commit specified - will use latest from branch + appPath: "./webapp" + + parameters: + version: 2 + testMode: "unit" + resources: + cpuCores: 4 + memoryGb: 8 +``` + +### Minimal ComponentWorkflowRun Using Defaults + +```yaml +apiVersion: openchoreo.dev/v1alpha1 +kind: ComponentWorkflowRun +metadata: + name: simple-build + namespace: default +spec: + owner: + projectName: demo + componentName: hello-world + + workflow: + name: docker + + systemParameters: + repository: + url: "https://github.com/myorg/hello-world" + revision: + branch: "main" + appPath: "." + # Uses default values for parameters from ComponentWorkflow schema +``` + +## Status Example + +After successful execution, a ComponentWorkflowRun status might look like: + +```yaml +status: + conditions: + - type: WorkflowCompleted + status: "True" + lastTransitionTime: "2024-01-15T10:30:00Z" + reason: WorkflowSucceeded + message: Workflow has completed successfully + observedGeneration: 1 + - type: WorkflowRunning + status: "False" + lastTransitionTime: "2024-01-15T10:29:30Z" + reason: WorkflowRunning + message: Argo Workflow running has completed + observedGeneration: 1 + - type: WorkflowSucceeded + status: "True" + lastTransitionTime: "2024-01-15T10:30:00Z" + reason: WorkflowSucceeded + message: Workflow completed successfully + observedGeneration: 1 + - type: WorkloadUpdated + status: "True" + lastTransitionTime: "2024-01-15T10:30:15Z" + reason: WorkloadUpdated + message: Workload CR created/updated successfully + observedGeneration: 1 + imageStatus: + image: gcr.io/openchoreo-dev/images/default-reading-list-service-image:v1-a1b2c3d4 + runReference: + apiVersion: argoproj.io/v1alpha1 + kind: Workflow + name: reading-list-service-build-01 + namespace: openchoreo-ci-default + resources: + - apiVersion: external-secrets.io/v1 + kind: ExternalSecret + name: reading-list-service-build-01-git-secret + namespace: openchoreo-ci-default +``` + +## Build-Specific Platform Features + +The structured system parameters in ComponentWorkflowRun enable several build-specific platform features: + +### Manual Build Actions +The UI can offer actions like "build from latest commit" or "build from specific commit" by reliably locating +repository URL, branch, and commit fields. + +### Auto-Build / Webhook Integration +Automated builds triggered by Git push events use: +- `repository.url` and `repository.appPath` - To map webhook events to the correct component +- `repository.revision.commit` - To trigger builds with the correct commit SHA +- `repository.revision.branch` - To filter events by branch + +### Build Traceability +Tracking which Git repository, branch, and commit produced each container image enables: +- Debugging production issues +- Compliance and audit trails +- Rollback to specific code versions + +### Monorepo Support +The `repository.appPath` field identifies specific application paths within a repository, enabling multiple components +to be built from different paths in the same repository. + +## Annotations + +ComponentWorkflowRuns support the following annotations: + +| Annotation | Description | +|-------------------------------|--------------------------------------------------| +| `openchoreo.dev/display-name` | Human-readable name for UI display | +| `openchoreo.dev/description` | Detailed description of the component workflow run | + +## Related Resources + +- [ComponentWorkflow](../platform/componentworkflow.md) - Template definitions for component workflow execution +- [Component](./component.md) - Components that reference ComponentWorkflows +- [ComponentType](../platform/componenttype.md) - Can restrict allowed component workflows diff --git a/versioned_docs/version-v0.11.x/reference/api/application/project.md b/versioned_docs/version-v0.11.x/reference/api/application/project.md new file mode 100644 index 0000000..a7f61ab --- /dev/null +++ b/versioned_docs/version-v0.11.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.11.x/reference/api/application/scheduledtask.md b/versioned_docs/version-v0.11.x/reference/api/application/scheduledtask.md new file mode 100644 index 0000000..18f9095 --- /dev/null +++ b/versioned_docs/version-v0.11.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.11.x/reference/api/application/service.md b/versioned_docs/version-v0.11.x/reference/api/application/service.md new file mode 100644 index 0000000..b3d04f6 --- /dev/null +++ b/versioned_docs/version-v0.11.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.11.x/reference/api/application/webapplication.md b/versioned_docs/version-v0.11.x/reference/api/application/webapplication.md new file mode 100644 index 0000000..698dcd3 --- /dev/null +++ b/versioned_docs/version-v0.11.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.11.x/reference/api/application/workflowrun.md b/versioned_docs/version-v0.11.x/reference/api/application/workflowrun.md new file mode 100644 index 0000000..9291798 --- /dev/null +++ b/versioned_docs/version-v0.11.x/reference/api/application/workflowrun.md @@ -0,0 +1,239 @@ +--- +title: WorkflowRun API Reference +--- + +# WorkflowRun + +:::warning Deprecated +The WorkflowRun resource is deprecated for component builds and will be removed in a future release. Use +[ComponentWorkflowRun](./componentworkflowrun.md) instead for building components. ComponentWorkflowRun provides +required ownership tracking and structured repository information needed for build-specific platform features like +auto-builds, webhooks, and build traceability. + +Generic Workflow Run resources will still be used for non-component automation tasks (Terraform, ETL pipelines, database +migrations, etc.) in the future. +::: + +A WorkflowRun represents a runtime execution instance of a Workflow in OpenChoreo. While Workflows define the template +and schema for what can be executed, WorkflowRuns represent actual executions with specific parameter values and +context. WorkflowRuns bridge the gap between developer intent and CI/CD execution, providing a simplified interface +for triggering builds, tests, and automation tasks. + +:::note +WorkflowRuns currently support Argo Workflow-based workflows only. +::: + +## API Version + +`openchoreo.dev/v1alpha1` + +## Resource Definition + +### Metadata + +WorkflowRuns are namespace-scoped resources that must be created within an Organization's namespace. + +```yaml +apiVersion: openchoreo.dev/v1alpha1 +kind: WorkflowRun +metadata: + name: + namespace: # Organization namespace +``` + +### Spec Fields + +| Field | Type | Required | Default | Description | +|------------|-----------------------------------|----------|---------|--------------------------------------------------------------------------------| +| `owner` | [WorkflowOwner](#workflowowner) | No | - | Optional owner information identifying the Component that triggered this run | +| `workflow` | [WorkflowConfig](#workflowconfig) | Yes | - | Workflow configuration referencing the Workflow CR and providing schema values | + +### WorkflowOwner + +Owner information is optional and used for component-bound workflows to establish the relationship between builds +and components. + +| Field | Type | Required | Default | Description | +|-----------------|--------|----------|---------|---------------------------------------| +| `projectName` | string | Yes | - | Name of the project (min length: 1) | +| `componentName` | string | Yes | - | Name of the component (min length: 1) | + +### WorkflowConfig + +| Field | Type | Required | Default | Description | +|----------|--------|----------|---------|-----------------------------------------------------------------------------------| +| `name` | string | Yes | - | Name of the Workflow CR to use for this execution (min length: 1) | +| `schema` | object | No | - | Developer-provided values conforming to the schema defined in the Workflow CR | + +The `schema` field contains nested configuration that matches the schema structure defined in the referenced Workflow. + +### Status Fields + +| Field | Type | Default | Description | +|------------------|---------------------------------------------|---------|-------------------------------------------------------------| +| `conditions` | []Condition | [] | Standard Kubernetes conditions tracking execution state | +| `imageStatus` | [WorkflowImage](#workflowimage) | - | Information about the built image (for build workflows) | +| `runReference` | [WorkflowRunReference](#workflowrunreference) | - | Reference to the workflow execution resource in build plane | + +#### WorkflowImage + +| Field | Type | Default | Description | +|---------|--------|---------|-----------------------------------------------------------------------| +| `image` | string | "" | Fully qualified image name (e.g., registry.example.com/myapp:v1.0.0) | + +#### WorkflowRunReference + +| Field | Type | Default | Description | +|-------------|--------|---------|----------------------------------------------------------------| +| `name` | string | "" | Name of the workflow run resource in the target cluster | +| `namespace` | string | "" | Namespace of the workflow run resource in the target cluster | + +#### Condition Types + +Common condition types for WorkflowRun resources: + +- `Ready` - Indicates if the workflow run has completed successfully +- `Running` - Indicates if the workflow is currently executing +- `Failed` - Indicates if the workflow execution failed + +## Examples + +### Docker Build WorkflowRun + +```yaml +apiVersion: openchoreo.dev/v1alpha1 +kind: WorkflowRun +metadata: + name: customer-service-build-1 + namespace: default +spec: + owner: + projectName: my-project + componentName: customer-service + workflow: + name: docker + schema: + repository: + url: https://github.com/myorg/customer-service + revision: + branch: main + commit: abc123 + appPath: . + secretRef: github-credentials + docker: + context: . + filePath: ./Dockerfile +``` + +### Google Cloud Buildpacks WorkflowRun + +```yaml +apiVersion: openchoreo.dev/v1alpha1 +kind: WorkflowRun +metadata: + name: frontend-build-v2 + namespace: default +spec: + owner: + projectName: ecommerce + componentName: frontend-app + workflow: + name: google-cloud-buildpacks + schema: + repository: + url: https://github.com/myorg/frontend-app + revision: + branch: develop + commit: def456 + appPath: ./webapp + secretRef: reading-list-repo-credentials-dev + version: 2 + testMode: unit + resources: + cpuCores: 2 + memoryGb: 4 + timeout: "45m" + cache: + enabled: true + paths: + - /root/.cache + - /workspace/node_modules + limits: + maxRetries: 2 + maxDurationMinutes: 60 +``` + +### Standalone WorkflowRun (No Component Owner) + +```yaml +apiVersion: openchoreo.dev/v1alpha1 +kind: WorkflowRun +metadata: + name: integration-test-run + namespace: default +spec: + workflow: + name: integration-tests + schema: + repository: + url: https://github.com/myorg/test-suite + branch: main + secretRef: test-repo-credentials + testSuite: smoke + environment: staging +``` + +### WorkflowRun with Minimal Schema + +```yaml +apiVersion: openchoreo.dev/v1alpha1 +kind: WorkflowRun +metadata: + name: simple-build + namespace: default +spec: + owner: + projectName: demo + componentName: hello-world + workflow: + name: docker + schema: + repository: + url: https://github.com/myorg/hello-world + secretRef: github-token + # Uses default values for other fields from Workflow schema +``` + +## Status Example + +After execution, a WorkflowRun status might look like: + +```yaml +status: + conditions: + - type: Ready + status: "True" + lastTransitionTime: "2024-01-15T10:30:00Z" + reason: WorkflowSucceeded + message: Workflow execution completed successfully + imageStatus: + image: gcr.io/openchoreo-dev/images/my-project-customer-service-image:v1 + runReference: + name: customer-service-build-1-abc12 + namespace: openchoreo-ci-default +``` + +## Annotations + +WorkflowRuns support the following annotations: + +| Annotation | Description | +|-------------------------------|------------------------------------------| +| `openchoreo.dev/display-name` | Human-readable name for UI display | +| `openchoreo.dev/description` | Detailed description of the workflow run | + +## Related Resources + +- [Workflow](../platform/workflow.md) - Template definitions for workflow execution +- [Component](./component.md) - Components that can trigger WorkflowRuns +- [ComponentType](../platform/componenttype.md) - Can restrict allowed workflows diff --git a/versioned_docs/version-v0.11.x/reference/api/application/workload.md b/versioned_docs/version-v0.11.x/reference/api/application/workload.md new file mode 100644 index 0000000..166df09 --- /dev/null +++ b/versioned_docs/version-v0.11.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 secretRef is not set) | +| `secretRef` | [secretRef](#secretref) | 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 secretRef is not set) | +| `secretRef` | [secretRef](#secretref) | No | - | Reference to a secret key (required if value is not set) | + +### secretRef + +| 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 + secretRef: + name: git-secrets + key: pat + files: + - key: ssl.pem + mountPath: /tmp + secretRef: + 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.11.x/reference/api/platform/buildplane.md b/versioned_docs/version-v0.11.x/reference/api/platform/buildplane.md new file mode 100644 index 0000000..43fdcc7 --- /dev/null +++ b/versioned_docs/version-v0.11.x/reference/api/platform/buildplane.md @@ -0,0 +1,297 @@ +--- +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. + +OpenChoreo uses **agent-based communication** where the control plane communicates with the build cluster through a WebSocket agent running in the BuildPlane cluster. The cluster agent establishes a secure WebSocket connection to the control plane's cluster gateway. + +## 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 | +|---------------------------|-------------------------------------------|----------|---------|------------------------------------------------------------------------------------------------------| +| `planeID` | string | No | default-buildplane | Identifies the logical plane this CR connects to. Must match `clusterAgent.planeId` Helm value. | +| `clusterAgent` | [ClusterAgentConfig](#clusteragentconfig) | Yes | - | Configuration for cluster agent-based communication | +| `secretStoreRef` | [SecretStoreRef](#secretstoreref) | No | - | Reference to External Secrets Operator ClusterSecretStore in the BuildPlane | +| `observabilityPlaneRef` | string | No | - | Name of the ObservabilityPlane resource for monitoring and logging | + +### PlaneID + +The `planeID` identifies the logical plane this BuildPlane CR connects to. Multiple BuildPlane CRs can share the same `planeID` to connect to the same physical cluster while maintaining separate configurations for multi-tenancy scenarios. + +**Validation Rules:** +- Maximum length: 63 characters +- Pattern: `^[a-z0-9]([-a-z0-9]*[a-z0-9])?$` (lowercase alphanumeric, hyphens allowed) +- Examples: `"shared-builder"`, `"ci-cluster"`, `"us-west-2"` + +:::important PlaneID Consistency +The `planeID` in the BuildPlane CR must match the `clusterAgent.planeId` Helm value configured during build plane installation. If not specified, it defaults to the CR name for backwards compatibility. +::: + +### ClusterAgentConfig + +Configuration for cluster agent-based communication with the build cluster. The cluster agent establishes a WebSocket connection to the control plane's cluster gateway. + +| Field | Type | Required | Default | Description | +|------------|-------------------------|----------|---------|------------------------------------------------------------------------------| +| `clientCA` | [ValueFrom](#valuefrom) | Yes | - | CA certificate to verify the agent's client certificate (base64-encoded PEM) | + +### SecretStoreRef + +Reference to an External Secrets Operator ClusterSecretStore. + +| Field | Type | Required | Default | Description | +|--------|--------|----------|---------|---------------------------------------------------| +| `name` | string | Yes | - | Name of the ClusterSecretStore in the BuildPlane | + +### ValueFrom + +Common pattern for referencing secrets or providing inline values. Either `secretRef` or `value` should be specified. + +| Field | Type | Required | Default | Description | +|-------------|---------------------------------------------|----------|---------|----------------------------------------------------------| +| `secretRef` | [SecretKeyReference](#secretkeyreference) | No | - | Reference to a secret key | +| `value` | string | No | - | Inline value (not recommended for sensitive data) | + +### SecretKeyReference + +Reference to a specific key in a Kubernetes secret. + +| Field | Type | Required | Default | Description | +|-------------|--------|----------|---------------------------|--------------------------------------------------------------| +| `name` | string | Yes | - | Name of the secret | +| `namespace` | string | No | Same as parent resource | Namespace of the secret | +| `key` | string | Yes | - | Key within the secret | + +### 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 | + +## Getting the Agent CA Certificate + +The cluster agent automatically generates its CA certificate when deployed to the build plane cluster. This certificate is used by the control plane to verify the identity of the build plane agent during mTLS authentication. + +### Extracting the CA Certificate + +You can extract the CA certificate using: + +```bash +# For multi-cluster setups, specify the build plane cluster context +kubectl --context get secret cluster-agent-tls \ + -n openchoreo-build-plane \ + -o jsonpath='{.data.ca\.crt}' | base64 -d + +# Example for k3d multi-cluster setup: +kubectl --context k3d-openchoreo-bp get secret cluster-agent-tls \ + -n openchoreo-build-plane \ + -o jsonpath='{.data.ca\.crt}' | base64 -d +``` + +:::important +In multi-cluster setups, you **must** specify the `--context` flag to target the build plane cluster, not the control plane cluster. The `cluster-agent-tls` secret exists in the build plane cluster where the agent is deployed. +::: + +### Adding the Certificate to the BuildPlane CR + +You can add the CA certificate to the BuildPlane CR in two ways: + +**Option 1: Inline value (for testing/development)** + +```bash +# Extract the CA certificate from the build plane cluster +BP_CA_CERT=$(kubectl --context get secret cluster-agent-tls \ + -n openchoreo-build-plane \ + -o jsonpath='{.data.ca\.crt}' | base64 -d) + +# Create BuildPlane in the control plane with inline CA certificate +kubectl --context apply -f - < get secret cluster-agent-tls \ + -n openchoreo-build-plane \ + -o jsonpath='{.data.ca\.crt}' | base64 -d > /tmp/buildplane-ca.crt + +# Create a secret in the control plane cluster +kubectl --context create secret generic buildplane-agent-ca \ + --from-file=ca.crt=/tmp/buildplane-ca.crt \ + -n my-org + +# Create BuildPlane in the control plane referencing the secret +kubectl --context apply -f - < + namespace: # Organization namespace +``` + +### Spec Fields + +| Field | Type | Required | Default | Description | +|--------------------|---------------------------------------------|----------|---------|----------------------------------------------------------------------| +| `workloadType` | string | Yes | - | Primary workload type: `deployment`, `statefulset`, `cronjob`, `job` | +| `allowedWorkflows` | []string | No | [] | Names of 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 | Yes | - | Parameters that can be overridden per environment (Must have defaults) | + +#### Parameter Schema Syntax + +Parameters use inline schema syntax with a single pipe after the type; constraints are space-separated: + +``` +fieldName: "type | default=value enum=val1,val2" +``` + +Supported types: `string`, `integer`, `boolean`, `array`, custom type references + +**Example:** + +```yaml +schema: + types: + ResourceRequirements: + requests: "ResourceQuantity | default={}" + limits: "ResourceQuantity | default={}" + ResourceQuantity: + cpu: "string | default=100m" + memory: "string | default=256Mi" + + parameters: + replicas: "integer | default=1" + imagePullPolicy: "string | default=IfNotPresent" + port: "integer | default=80" + exposed: "boolean | default=false" + containerName: "string | default=main" + + envOverrides: + resources: "ResourceRequirements | default={}" +``` + +### 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 the following context variables: + +##### metadata + +Platform-computed metadata for resource generation: + +| Field | Type | Description | +|-------|------|-------------| +| `metadata.name` | string | Base name for generated resources (e.g., `my-service-dev-a1b2c3d4`) | +| `metadata.namespace` | string | Target namespace for resources | +| `metadata.componentName` | string | Name of the component | +| `metadata.componentUID` | string | Unique identifier of the component | +| `metadata.projectName` | string | Name of the project | +| `metadata.projectUID` | string | Unique identifier of the project | +| `metadata.environmentName` | string | Name of the environment (e.g., `development`, `production`) | +| `metadata.environmentUID` | string | Unique identifier of the environment | +| `metadata.dataPlaneName` | string | Name of the data plane | +| `metadata.dataPlaneUID` | string | Unique identifier of the data plane | +| `metadata.labels` | map | Common labels to add to all resources | +| `metadata.annotations` | map | Common annotations to add to all resources | +| `metadata.podSelectors` | map | Platform-injected selectors for pod identity (use in Deployment/Service selectors) | + +##### parameters + +Component parameters from `Component.spec.parameters` with schema defaults applied. Use for static configuration that doesn't change across environments. + +##### envOverrides + +Environment-specific overrides from `ReleaseBinding.spec.componentTypeEnvOverrides` with schema defaults applied. Use for values that vary per environment (resources, replicas, etc.). + +##### workload + +Workload specification from the Workload resource: + +| Field | Type | Description | +|-------|------|-------------| +| `workload.containers` | map | Map of container configurations keyed by container name | +| `workload.containers[parameters.containerName].image` | string | Container image | +| `workload.containers[parameters.containerName].command` | []string | Container command | +| `workload.containers[parameters.containerName].args` | []string | Container arguments | + +##### configurations + +Configuration and secret references extracted from workload, keyed by container name: + +| Field | Type | Description | +|-------|------|-------------| +| `configurations[parameters.containerName].configs.envs` | []object | Environment variable configs (each has `name`, `value`) | +| `configurations[parameters.containerName].configs.files` | []object | File configs (each has `name`, `mountPath`, `value`) | +| `configurations[parameters.containerName].secrets.envs` | []object | Secret env vars (each has `name`, `value`, `remoteRef`) | +| `configurations[parameters.containerName].secrets.files` | []object | Secret files (each has `name`, `mountPath`, `remoteRef`) | + +The `remoteRef` object contains: `key`, `property` (optional), `version` (optional). + +**Configuration Helper Functions:** + +The `configurations` object provides several helper methods to simplify working with container configurations. See [Configuration Helpers](../../cel/configuration-helpers.md) for detailed documentation on these functions: + +- `configurations.toContainerEnvFrom(containerName)` - Generate envFrom array for a container +- `configurations.toConfigEnvsByContainer()` - List config environment variables by container +- `configurations.toSecretEnvsByContainer()` - List secret environment variables by container +- `configurations.toConfigFileList()` - Flatten all config files into a single list +- `configurations.toSecretFileList()` - Flatten all secret files into a single list +- `configurations.toContainerVolumeMounts(containerName)` - Generate volumeMounts for a container +- `configurations.toVolumes()` - Generate volumes array for all containers + +##### dataplane + +Data plane configuration: + +| Field | Type | Description | +|-------|------|-------------| +| `dataplane.secretStore` | string | Name of the ClusterSecretStore for external secrets | +| `dataplane.publicVirtualHost` | string | Public virtual host for external access | + +##### Helper Functions + +| Function | Description | +|----------|-------------| +| `oc_generate_name(args...)` | Generate valid Kubernetes names with hash suffix for uniqueness | +| `oc_hash(string)` | Generate 8-character FNV-32a hash from input string | +| `oc_merge(map1, map2, ...)` | Shallow merge maps (later maps override earlier ones) | +| `oc_omit()` | Remove field/key from output when used in conditional expressions | + +For a comprehensive guide to configuration helper functions, see the [Configuration Helpers](../../cel/configuration-helpers.md). + +## 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} + 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}-${metadata.environmentName}.${dataplane.publicVirtualHost} + 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" + 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 + + schema: + parameters: + containerName: "string | default=main" + + resources: + - id: deployment + template: + # ... deployment spec ... + + - id: file-config + includeWhen: ${has(configurations[parameters.containerName].configs.files) && configurations[parameters.containerName].configs.files.size() > 0} + forEach: ${configurations[parameters.containerName].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 + +- [Configuration Helpers](../../cel/configuration-helpers.md) - Configuration helper functions reference +- [Component](../application/component.md) - Uses ComponentTypes for deployment +- [ReleaseBinding](releasebinding.md) - Binds a ComponentRelease to an environment with parameter overrides +- [Trait](trait.md) - Adds cross-cutting concerns to components using ComponentTypes diff --git a/versioned_docs/version-v0.11.x/reference/api/platform/componentworkflow.md b/versioned_docs/version-v0.11.x/reference/api/platform/componentworkflow.md new file mode 100644 index 0000000..6b264e7 --- /dev/null +++ b/versioned_docs/version-v0.11.x/reference/api/platform/componentworkflow.md @@ -0,0 +1,407 @@ +--- +title: ComponentWorkflow API Reference +--- + +# ComponentWorkflow + +A ComponentWorkflow is a platform engineer-defined template specifically designed for building components in OpenChoreo. +ComponentWorkflows enforce a structured schema for repository information while providing +flexibility for additional build configuration. This enables powerful build-specific platform features like auto-builds, +webhooks, build traceability, and monorepo support. + +## API Version + +`openchoreo.dev/v1alpha1` + +## Resource Definition + +### Metadata + +ComponentWorkflows are namespace-scoped resources that must be created within an Organization's namespace. + +```yaml +apiVersion: openchoreo.dev/v1alpha1 +kind: ComponentWorkflow +metadata: + name: + namespace: # Organization namespace +``` + +### Spec Fields + +| Field | Type | Required | Default | Description | +|---------------|---------------------------------------------------------|----------|---------|----------------------------------------------------------------------------------------------| +| `schema` | [ComponentWorkflowSchema](#schema) | Yes | - | Parameter schemas including required system parameters and flexible developer parameters | +| `runTemplate` | object | Yes | - | Kubernetes resource template (typically Argo Workflow) with CEL expressions for runtime evaluation | +| `resources` | [][ComponentWorkflowResource](#componentworkflowresource) | No | - | Additional Kubernetes resources to be created alongside the workflow (e.g., ExternalSecrets, ConfigMaps) | + +### Schema + +The schema field defines parameter schemas for the ComponentWorkflow: + +| Field | Type | Required | Default | Description | +|--------------------|--------|----------|---------|-----------------------------------------------------------------------| +| `types` | object | No | - | Reusable type definitions that can be referenced in schema fields | +| `systemParameters` | object | Yes | - | Required structured schema for repository information | +| `parameters` | object | No | - | Flexible PE-defined schema for additional build configuration | + +#### System Parameters Schema (Required) + +System parameters follow a fixed structure required for build-specific platform features. Platform engineers can +customize defaults, enums, and descriptions, but must maintain the field structure. + +**Required Structure:** + +```yaml +schema: + systemParameters: + repository: + url: 'string | description="Git repository URL"' + revision: + branch: 'string | default=main description="Git branch"' + commit: 'string | description="Commit SHA (optional)"' + appPath: 'string | default=. description="Application path"' +``` + +**Field Constraints:** +- Field names must match exactly: `url`, `revision.branch`, `revision.commit`, `appPath` +- All fields must be of type `string` +- Platform Engineers can customize: defaults, enums, descriptions, validation rules +- Platform Engineers cannot change: field names, nesting structure, or types + +#### Developer Parameters Schema (Flexible) + +Developer parameters provide complete freedom for platform engineers to define additional build configuration using +the same inline type definition syntax as ComponentType: + +``` +"type | default=value enum=val1,val2 minimum=N maximum=N" +``` + +Supported types: `string`, `integer`, `boolean`, `array`, nested objects + +**Example:** + +```yaml +schema: + parameters: + version: integer | default=1 description="Build version" + testMode: string | enum=unit,integration,none default=unit + resources: + cpuCores: integer | default=1 minimum=1 maximum=8 + memoryGb: integer | default=2 minimum=1 maximum=32 + cache: + enabled: boolean | default=true + paths: '[]string | default=["/root/.cache"]' +``` + +#### Types (Optional Reusable Type Definitions) + +The optional `types` field allows platform engineers to define reusable type definitions that can be referenced in the parameter schema, similar to ComponentType: + +```yaml +schema: + types: + Endpoint: + name: string + port: integer + type: string | enum=REST,HTTP,TCP,UDP + ResourceLimit: + cpu: string | default=1000m + memory: string | default=1Gi + + parameters: + endpoints: '[]Endpoint | default=[]' + limits: ResourceLimit + buildArgs: '[]string | default=[]' +``` + +## CEL Variables in Run Templates + +ComponentWorkflow run templates support CEL expressions with access to: + +| Variable | Description | +|-------------------------------|--------------------------------------------------------------| +| `${metadata.workflowRunName}` | ComponentWorkflowRun CR name (the execution instance) | +| `${metadata.componentName}` | Component name | +| `${metadata.projectName}` | Project name | +| `${metadata.orgName}` | Organization name (namespace) | +| `${systemParameters.*}` | Repository information from system parameters | +| `${parameters.*}` | Developer-provided values from the flexible parameter schema | + +### ComponentWorkflowResource + +Additional Kubernetes resources that should be created alongside the workflow execution. These resources are typically used for secrets, configuration, or other supporting resources needed during the build. + +| Field | Type | Required | Default | Description | +|------------|--------|----------|---------|----------------------------------------------------------------------------------| +| `id` | string | Yes | - | Unique identifier for this resource within the ComponentWorkflow (min length: 1) | +| `template` | object | Yes | - | Kubernetes resource template with CEL expressions (same variables as runTemplate) | + +**Common Use Cases:** +- **ExternalSecrets**: Fetch git tokens or credentials from secret stores +- **ConfigMaps**: Provide build-time configuration +- **Secrets**: Store sensitive data needed during build + +**Resource Lifecycle:** +- Resources are created in the build plane before the workflow execution begins +- Resource references are tracked in the ComponentWorkflowRun status for cleanup +- When a ComponentWorkflowRun is deleted, the controller automatically cleans up all associated resources + +**Example:** +```yaml +resources: + - id: git-secret + template: + apiVersion: external-secrets.io/v1 + kind: ExternalSecret + metadata: + name: ${metadata.workflowRunName}-git-secret + namespace: openchoreo-ci-${metadata.orgName} + spec: + refreshInterval: 15s + secretStoreRef: + name: default + kind: ClusterSecretStore + target: + name: ${metadata.workflowRunName}-git-secret + creationPolicy: Owner + data: + - secretKey: git-token + remoteRef: + key: git-token +``` + +## Examples + +### Google Cloud Buildpacks ComponentWorkflow + +```yaml +apiVersion: openchoreo.dev/v1alpha1 +kind: ComponentWorkflow +metadata: + name: google-cloud-buildpacks + namespace: default + annotations: + openchoreo.dev/description: "Google Cloud Buildpacks workflow for containerized builds" +spec: + schema: + # Required system parameters with fixed structure + systemParameters: + repository: + url: 'string | description="Git repository URL for the component source code"' + revision: + branch: 'string | default=main description="Git branch to build from"' + commit: 'string | description="Specific commit SHA to build (optional, defaults to latest)"' + appPath: 'string | default=. description="Path to the application code within the repository"' + + # Flexible developer parameters + parameters: + version: integer | default=1 description="Build version number for image tagging" + testMode: string | enum=unit,integration,none default=unit description="Test mode to execute" + command: '[]string | default=[] description="Custom command to override the default entrypoint"' + args: '[]string | default=[] description="Custom arguments to pass to the command"' + resources: + cpuCores: integer | default=1 minimum=1 maximum=8 description="Number of CPU cores" + memoryGb: integer | default=2 minimum=1 maximum=32 description="Amount of memory in GB" + timeout: string | default="30m" description="Build timeout duration (e.g., 30m, 1h)" + cache: + enabled: boolean | default=true description="Enable build cache" + paths: '[]string | default=["/root/.cache"] description="Paths to cache between builds"' + limits: + maxRetries: integer | default=3 minimum=0 maximum=10 description="Maximum retry attempts" + maxDurationMinutes: integer | default=60 minimum=5 maximum=240 description="Maximum duration" + + runTemplate: + apiVersion: argoproj.io/v1alpha1 + kind: Workflow + metadata: + name: ${metadata.workflowRunName} + namespace: openchoreo-ci-${metadata.orgName} + spec: + arguments: + parameters: + # Context variables + - name: component-name + value: ${metadata.componentName} + - name: project-name + value: ${metadata.projectName} + # System parameters + - name: git-repo + value: ${systemParameters.repository.url} + - name: branch + value: ${systemParameters.repository.revision.branch} + - name: commit + value: ${systemParameters.repository.revision.commit} + - name: app-path + value: ${systemParameters.repository.appPath} + # Developer parameters + - name: version + value: ${parameters.version} + - name: test-mode + value: ${parameters.testMode} + - name: cpu-cores + value: ${parameters.resources.cpuCores} + - name: memory-gb + value: ${parameters.resources.memoryGb} + # PE-controlled hardcoded parameters + - name: builder-image + value: gcr.io/buildpacks/builder@sha256:5977b4bd47d3e9ff729eefe9eb99d321d4bba7aa3b14986323133f40b622aef1 + - name: registry-url + value: gcr.io/openchoreo-dev/images + - name: security-scan-enabled + value: "true" + - name: image-name + value: ${metadata.projectName}-${metadata.componentName}-image + - name: image-tag + value: v${parameters.version} + serviceAccountName: workflow-sa + workflowTemplateRef: + clusterScope: true + name: google-cloud-buildpacks +``` + +### Docker Build ComponentWorkflow + +```yaml +apiVersion: openchoreo.dev/v1alpha1 +kind: ComponentWorkflow +metadata: + name: docker + namespace: default + annotations: + openchoreo.dev/description: "Docker build workflow using Dockerfile" +spec: + schema: + systemParameters: + repository: + url: 'string | description="Git repository URL"' + revision: + branch: 'string | default=main description="Git branch"' + commit: 'string | description="Commit SHA (optional)"' + appPath: 'string | default=. description="Application path"' + + parameters: + docker: + context: string | default=. description="Docker build context path" + filePath: string | default=./Dockerfile description="Path to Dockerfile" + buildArgs: '[]string | default=[] description="Docker build arguments"' + + runTemplate: + apiVersion: argoproj.io/v1alpha1 + kind: Workflow + metadata: + name: ${metadata.workflowRunName} + namespace: openchoreo-ci-${metadata.orgName} + spec: + arguments: + parameters: + - name: component-name + value: ${metadata.componentName} + - name: project-name + value: ${metadata.projectName} + - name: git-repo + value: ${systemParameters.repository.url} + - name: branch + value: ${systemParameters.repository.revision.branch} + - name: commit + value: ${systemParameters.repository.revision.commit} + - name: app-path + value: ${systemParameters.repository.appPath} + - name: docker-context + value: ${parameters.docker.context} + - name: dockerfile-path + value: ${parameters.docker.filePath} + - name: registry-url + value: gcr.io/openchoreo-dev/images + - name: image-name + value: ${metadata.projectName}-${metadata.componentName}-image + serviceAccountName: workflow-sa + workflowTemplateRef: + clusterScope: true + name: docker + + # Additional resources needed for the workflow + resources: + - id: git-secret + template: + apiVersion: external-secrets.io/v1 + kind: ExternalSecret + metadata: + name: ${metadata.workflowRunName}-git-secret + namespace: openchoreo-ci-${metadata.orgName} + spec: + refreshInterval: 15s + secretStoreRef: + name: default + kind: ClusterSecretStore + target: + name: ${metadata.workflowRunName}-git-secret + creationPolicy: Owner + data: + - secretKey: git-token + remoteRef: + key: git-token +``` + +## ComponentType Integration + +ComponentTypes can restrict which ComponentWorkflows developers can use through the `allowedWorkflows` field: + +```yaml +apiVersion: openchoreo.dev/v1alpha1 +kind: ComponentType +metadata: + name: service +spec: + workloadType: deployment + allowedWorkflows: + - google-cloud-buildpacks + - docker +``` + +## Component Integration + +Components reference ComponentWorkflows in their workflow configuration: + +```yaml +apiVersion: openchoreo.dev/v1alpha1 +kind: Component +metadata: + name: reading-list-service +spec: + componentType: deployment/service + + workflow: + name: google-cloud-buildpacks + + systemParameters: + repository: + url: "https://github.com/openchoreo/sample-workloads" + revision: + branch: "main" + commit: "" + appPath: "/service-go-reading-list" + + parameters: + version: 1 + testMode: "integration" + resources: + cpuCores: 2 + memoryGb: 4 +``` + +## Annotations + +ComponentWorkflows support the following annotations: + +| Annotation | Description | +|-------------------------------|----------------------------------------------| +| `openchoreo.dev/display-name` | Human-readable name for UI display | +| `openchoreo.dev/description` | Detailed description of the ComponentWorkflow | + +## Related Resources + +- [ComponentWorkflowRun](../application/componentworkflowrun.md) - Runtime execution instances of ComponentWorkflows +- [ComponentType](./componenttype.md) - Can restrict allowed component workflows via `allowedWorkflows` +- [Component](../application/component.md) - References ComponentWorkflows for building diff --git a/versioned_docs/version-v0.11.x/reference/api/platform/dataplane.md b/versioned_docs/version-v0.11.x/reference/api/platform/dataplane.md new file mode 100644 index 0000000..61530cd --- /dev/null +++ b/versioned_docs/version-v0.11.x/reference/api/platform/dataplane.md @@ -0,0 +1,351 @@ +--- +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 via a cluster agent and gateway settings for routing traffic to applications. + +OpenChoreo uses **agent-based communication** where the control plane communicates with the downstream cluster through a WebSocket agent running in the DataPlane cluster. The cluster agent establishes a secure WebSocket connection to the control plane's cluster gateway. + +## 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 | +|---------------------------|---------------------------------------|----------|---------|------------------------------------------------------------------------------------------------------| +| `planeID` | string | No | default-dataplane | Identifies the logical plane this CR connects to. Must match `clusterAgent.planeId` Helm value. | +| `clusterAgent` | [ClusterAgentConfig](#clusteragentconfig) | Yes | - | Configuration for cluster agent-based communication | +| `gateway` | [GatewaySpec](#gatewayspec) | Yes | - | API gateway configuration for this DataPlane | +| `imagePullSecretRefs` | []string | No | - | References to SecretReference resources for image pull secrets | +| `secretStoreRef` | [SecretStoreRef](#secretstoreref) | No | - | Reference to External Secrets Operator ClusterSecretStore in the DataPlane | +| `observabilityPlaneRef` | string | No | - | Name of the ObservabilityPlane resource for monitoring and logging | + +### PlaneID + +The `planeID` identifies the logical plane this DataPlane CR connects to. Multiple DataPlane CRs can share the same `planeID` to connect to the same physical cluster while maintaining separate configurations for multi-tenancy scenarios. + +**Validation Rules:** +- Maximum length: 63 characters +- Pattern: `^[a-z0-9]([-a-z0-9]*[a-z0-9])?$` (lowercase alphanumeric, hyphens allowed) +- Examples: `"prod-cluster"`, `"shared-dataplane"`, `"us-east-1"` + +:::important PlaneID Consistency +The `planeID` in the DataPlane CR must match the `clusterAgent.planeId` Helm value configured during data plane installation. If not specified, it defaults to the CR name for backwards compatibility. +::: + +### ClusterAgentConfig + +Configuration for cluster agent-based communication with the downstream cluster. The cluster agent establishes a WebSocket connection to the control plane's cluster gateway. + +| Field | Type | Required | Default | Description | +|------------|-------------------------|----------|---------|------------------------------------------------------------------------------| +| `clientCA` | [ValueFrom](#valuefrom) | Yes | - | CA certificate to verify the agent's client certificate (base64-encoded PEM) | + +### GatewaySpec + +Gateway configuration for the DataPlane. + +| Field | Type | Required | Default | Description | +|---------------------------|--------|----------|---------|---------------------------------------------------------| +| `publicVirtualHost` | string | Yes | - | Public virtual host for external traffic | +| `organizationVirtualHost` | string | Yes | - | Organization-specific virtual host for internal traffic | + +### SecretStoreRef + +Reference to an External Secrets Operator ClusterSecretStore. + +| Field | Type | Required | Default | Description | +|--------|--------|----------|---------|---------------------------------------------------| +| `name` | string | Yes | - | Name of the ClusterSecretStore in the DataPlane | + +### ValueFrom + +Common pattern for referencing secrets or providing inline values. Either `secretRef` or `value` should be specified. + +| Field | Type | Required | Default | Description | +|-------------|---------------------------------------------|----------|---------|----------------------------------------------------------| +| `secretRef` | [SecretKeyReference](#secretkeyreference) | No | - | Reference to a secret key | +| `value` | string | No | - | Inline value (not recommended for sensitive data) | + +### SecretKeyReference + +Reference to a specific key in a Kubernetes secret. + +| Field | Type | Required | Default | Description | +|-------------|--------|----------|---------------------------|--------------------------------------------------------------| +| `name` | string | Yes | - | Name of the secret | +| `namespace` | string | No | Same as parent resource | Namespace of the secret | +| `key` | string | Yes | - | Key within the secret | + +### 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 + +## Getting the Agent CA Certificate + +The cluster agent automatically generates its CA certificate when deployed to the data plane cluster. This certificate is used by the control plane to verify the identity of the data plane agent during mTLS authentication. + +### Extracting the CA Certificate + +You can extract the CA certificate using: + +```bash +# For multi-cluster setups, specify the data plane cluster context +kubectl --context get secret cluster-agent-tls \ + -n openchoreo-data-plane \ + -o jsonpath='{.data.ca\.crt}' | base64 -d + +# Example for k3d multi-cluster setup: +kubectl --context k3d-openchoreo-dp get secret cluster-agent-tls \ + -n openchoreo-data-plane \ + -o jsonpath='{.data.ca\.crt}' | base64 -d +``` + +:::important +In multi-cluster setups, you **must** specify the `--context` flag to target the data plane cluster, not the control plane cluster. The `cluster-agent-tls` secret exists in the data plane cluster where the agent is deployed. +::: + +### Adding the Certificate to the DataPlane CR + +You can add the CA certificate to the DataPlane CR in two ways: + +**Option 1: Inline value (for testing/development)** + +```bash +# Extract the CA certificate from the data plane cluster +CA_CERT=$(kubectl --context get secret cluster-agent-tls \ + -n openchoreo-data-plane \ + -o jsonpath='{.data.ca\.crt}' | base64 -d) + +# Create DataPlane in the control plane with inline CA certificate +kubectl --context apply -f - < get secret cluster-agent-tls \ + -n openchoreo-data-plane \ + -o jsonpath='{.data.ca\.crt}' | base64 -d > /tmp/dataplane-ca.crt + +# Create a secret in the control plane cluster +kubectl --context create secret generic dataplane-agent-ca \ + --from-file=ca.crt=/tmp/dataplane-ca.crt \ + -n my-org + +# Create DataPlane in the control plane referencing the secret +kubectl --context apply -f - < + 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.11.x/reference/api/platform/environment.md b/versioned_docs/version-v0.11.x/reference/api/platform/environment.md new file mode 100644 index 0000000..5f2c576 --- /dev/null +++ b/versioned_docs/version-v0.11.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.11.x/reference/api/platform/observabilityalertrule.md b/versioned_docs/version-v0.11.x/reference/api/platform/observabilityalertrule.md new file mode 100644 index 0000000..7781c33 --- /dev/null +++ b/versioned_docs/version-v0.11.x/reference/api/platform/observabilityalertrule.md @@ -0,0 +1,172 @@ +--- +title: ObservabilityAlertRule API Reference +--- + +# ObservabilityAlertRule + +An `ObservabilityAlertRule` defines a rule for monitoring runtime observability data (metrics or logs) and triggering alerts when specific conditions are met. + +:::tip Generated Resources +`ObservabilityAlertRule` resources are typically **generated automatically** by the OpenChoreo control plane during component releases. They are derived from the alert definitions specified in a component's traits. +::: + +## Usage Recommendation + +You should **not** create `ObservabilityAlertRule` resources manually. Instead, you should define alert rules using a `Trait` (either from the default `observability-alertrule` trait or a custom trait) within your component definition. This ensures that the alert rules are properly scoped to your component and managed as part of its lifecycle across different environments. + +### Example: Defining Alerts as Traits + +In your `Component` CR, add the alert rule as a trait (using the default `observability-alertrule` trait): + +```yaml +apiVersion: openchoreo.dev/v1alpha1 +kind: Component +metadata: + name: my-service +spec: + # ... other component fields ... + traits: + - name: observability-alertrule + instanceName: high-error-rate-log-alert + parameters: + description: "Triggered when error logs count exceeds 50 in 5 minutes." + severity: "critical" + source: + type: "log" + query: "status:error" + condition: + window: 5m + interval: 1m + operator: gt + threshold: 50 +``` +Override the environment-specific parameters for the alert rule in the `ReleaseBinding` CR. + +```yaml +apiVersion: openchoreo.dev/v1alpha1 +kind: ReleaseBinding +metadata: + name: my-service-production + namespace: default +spec: + owner: + projectName: default + componentName: my-service + environment: production + + traitOverrides: + high-error-rate-log-alert: + enabled: true + enableAiRootCauseAnalysis: false + notificationChannel: devops-email-notifications +``` + +The control plane will then generate the corresponding `ObservabilityAlertRule` resource for each environment where this component is released. + +## API Version + +`openchoreo.dev/v1alpha1` + +## Resource Definition + +### Metadata + +`ObservabilityAlertRule` resources are namespace-scoped and typically created within the project-environment namespace. + +```yaml +apiVersion: openchoreo.dev/v1alpha1 +kind: ObservabilityAlertRule +metadata: + name: + namespace: +``` + +### Spec Fields + +| Field | Type | Required | Description | +|-----------------------------|-------------------------------------------|----------|-----------------------------------------------------------------------------| +| `name` | string | Yes | Unique identifier for the alert rule | +| `description` | string | No | A human-friendly summary of the alert rule | +| `severity` | [AlertSeverity](#alertseverity) | No | Describes how urgent the alert is (`info`, `warning`, `critical`) | +| `enabled` | boolean | No | Toggles whether this alert rule should be evaluated. Defaults to `true` | +| `enableAiRootCauseAnalysis` | boolean | No | Allows an attached AI engine to perform root cause analysis and generate a report when the alert is triggered | +| `notificationChannel` | string | Yes | Name of the [ObservabilityAlertsNotificationChannel](./observabilityalertsnotificationchannel.md) to notify | +| `source` | [AlertSource](#alertsource) | Yes | Specifies the observability source type (log or metrics) and query that drives the rule | +| `condition` | [AlertCondition](#alertcondition) | Yes | Controls when an alert should be triggered based on the source data | + +### AlertSeverity + +| Value | Description | +|------------|-------------------------| +| `info` | Informational alerts | +| `warning` | Warning-level alerts | +| `critical` | Critical alerts | + +### AlertSource + +Specifies where and how events are pulled for evaluation. + +| Field | Type | Required | Description | +|----------|-------------------------------------|----------|--------------------------------------------------------------| +| `type` | [AlertSourceType](#alertsourcetype) | Yes | The telemetry source type (`log`, `metrics`) | +| `query` | string | No | The query for log-based alerting (e.g., `status:error`) | +| `metric` | string | No | The metric name for metrics-based alerting (e.g., `cpu, memory`) | + +### AlertSourceType + +| Value | Description | +|-----------|------------------------| +| `log` | Log-based alerting (Powered by OpenSearch) | +| `metrics` | Usage metrics-based alerting (Powered by Prometheus) | + +### AlertCondition + +Represents the conditions under which an alert should be triggered. + +| Field | Type | Required | Description | +|-------------|-----------------------------------------------|----------|--------------------------------------------------------------| +| `window` | duration | Yes | The time window aggregated before comparison (e.g., `5m`) | +| `interval` | duration | Yes | How often the alert rule is evaluated (e.g., `1m`) | +| `operator` | [AlertConditionOperator](#alertconditionoperator) | Yes | Comparison operator used for evaluation | +| `threshold` | integer | Yes | Trigger value for the configured operator | + +### AlertConditionOperator + +| Value | Description | +|-------|--------------------------------------------------| +| `gt` | Greater than threshold | +| `lt` | Less than threshold | +| `gte` | Greater than or equal to threshold | +| `lte` | Less than or equal to threshold | +| `eq` | Equals the threshold | + +## Examples + +### Log-based Alert Rule + +```yaml +apiVersion: openchoreo.dev/v1alpha1 +kind: ObservabilityAlertRule +metadata: + name: error-logs-alert + namespace: my-project-production +spec: + name: Error Logs Detected + description: Triggered when more than 10 error logs are detected in 1 minute. + severity: critical + notificationChannel: devops-email-notifications + source: + type: log + query: 'status: "error"' + condition: + window: 1m + interval: 1m + operator: gt + threshold: 10 +``` + +## Related Resources + +- [ObservabilityPlane](./observabilityplane.md) - The infrastructure layer providing observability data +- [ObservabilityAlertsNotificationChannel](./observabilityalertsnotificationchannel.md) - Destinations for alert notifications +- [Trait](./trait.md) - Alert rules can be defined as traits on components diff --git a/versioned_docs/version-v0.11.x/reference/api/platform/observabilityalertsnotificationchannel.md b/versioned_docs/version-v0.11.x/reference/api/platform/observabilityalertsnotificationchannel.md new file mode 100644 index 0000000..2d71e7f --- /dev/null +++ b/versioned_docs/version-v0.11.x/reference/api/platform/observabilityalertsnotificationchannel.md @@ -0,0 +1,148 @@ +--- +title: ObservabilityAlertsNotificationChannel API Reference +--- + +# ObservabilityAlertsNotificationChannel + +An `ObservabilityAlertsNotificationChannel` defines a destination for alert notifications. These resources are **environment-bound**, meaning each channel is associated with a specific OpenChoreo environment. + +:::tip Default Notification Channel +In each environment, one `ObservabilityAlertsNotificationChannel` can be marked as the **default**. If an [ObservabilityAlertRule](./observabilityalertrule.md) is created without explicitly specifying a `notificationChannel`, it will automatically use the default channel for that environment. +::: + +Currently, only email notifications are supported, but other types such as Slack or Webhooks will be added in the future. + +## API Version + +`openchoreo.dev/v1alpha1` + +## Resource Definition + +### Metadata + +`ObservabilityAlertsNotificationChannel` resources are namespace-scoped. + +```yaml +apiVersion: openchoreo.dev/v1alpha1 +kind: ObservabilityAlertsNotificationChannel +metadata: + name: + namespace: +``` + +### Spec Fields + +| Field | Type | Required | Description | +|----------------|---------------------------------------------|----------|-----------------------------------------------------------------------------| +| `environment` | string | Yes | Name of the OpenChoreo environment this channel belongs to (Immutable) | +| `isEnvDefault` | boolean | No | If `true`, this is the default channel for the environment. Default channels are used by alert rules that don't specify a channel. Defaults to `false`. First channel created in an environment will be marked as the default | +| `type` | [NotificationChannelType](#notificationchanneltype) | Yes | The type of notification channel (currently only `email`) | +| `config` | [NotificationChannelConfig](#notificationchannelconfig) | Yes | Channel-specific configuration | + +### NotificationChannelType + +| Value | Description | +|---------|---------------------------| +| `email` | Email notification channel | + +Other notification channel types (e.g., Slack, Webhooks) will be added in the future. + +### NotificationChannelConfig + +For `type: email`, the configuration includes the following fields: + +| Field | Type | Required | Description | +|------------|-------------------------------|----------|-------------------------------------------------------| +| `from` | string | Yes | The sender email address | +| `to` | string[] | Yes | List of recipient email addresses (minimum 1) | +| `smtp` | [SMTPConfig](#smtpconfig) | Yes | SMTP server configuration | +| `template` | [EmailTemplate](#emailtemplate) | No | Email subject and body templates using CEL expressions | + +### SMTPConfig + +| Field | Type | Required | Description | +|----------------------|-------------------------------|----------|---------------------------------------------------------------------| +| `host` | string | Yes | SMTP server hostname | +| `port` | integer | Yes | SMTP server port | +| `auth` | [SMTPAuth](#smtpauth) | No | SMTP authentication credentials | +| `tls` | [SMTPTLSConfig](#smtptlsconfig) | No | TLS configuration for SMTP | + +### SMTPAuth + +| Field | Type | Required | Description | +|------------|-------------------------------|----------|----------------------------------------------------------| +| `username` | [SecretValueFrom](#secretvaluefrom) | No | Username for SMTP authentication (inline or secret ref) | +| `password` | [SecretValueFrom](#secretvaluefrom) | No | Password for SMTP authentication (inline or secret ref) | + +### SMTPTLSConfig + +| Field | Type | Required | Description | +|----------------------|---------|----------|-----------------------------------------------------------------------------| +| `insecureSkipVerify` | boolean | No | If `true`, skips TLS certificate verification (not recommended for production) | + +### EmailTemplate + +Defines the email template using CEL expressions. + +| Field | Type | Required | Description | +|-----------|--------|----------|-----------------------------------------------------------------------------| +| `subject` | string | Yes | CEL expression for the email subject (e.g., `"[${alert.severity}] - ${alert.name} Triggered"`) | +| `body` | string | Yes | CEL expression for the email body | + +### SecretValueFrom + +Defines how to obtain a secret value. + +| Field | Type | Required | Description | +|----------------|------------------|----------|-------------------------------------------------| +| `secretKeyRef` | [SecretKeyRef](#secretkeyref) | No | Reference to a key in a Kubernetes secret | + +### SecretKeyRef + +| Field | Type | Required | Description | +|-------------|--------|----------|-------------------------| +| `name` | string | Yes | Name of the secret | +| `namespace` | string | Yes | Namespace of the secret | +| `key` | string | Yes | Key within the secret | + +## Examples + +### Email Notification Channel + +```yaml +apiVersion: openchoreo.dev/v1alpha1 +kind: ObservabilityAlertsNotificationChannel +metadata: + name: prod-email-notifications + namespace: my-org +spec: + environment: production + isEnvDefault: true + type: email + config: + from: "alerts@example.com" + to: + - "admin@example.com" + - "devops@example.com" + smtp: + host: "smtp.example.com" + port: 587 + auth: + username: + secretKeyRef: + name: smtp-credentials + key: username + password: + secretKeyRef: + name: smtp-credentials + key: password + template: + subject: "[OpenChoreo] ${alert.severity}: ${alert.name}" + body: "Alert ${alert.name} triggered at ${alert.startsAt}.\n\nDescription: ${alert.description}" +``` + +## Related Resources + +- [ObservabilityAlertRule](./observabilityalertrule.md) - Rules that trigger notifications to these channels +- [Environment](./environment.md) - Notification channels are environment-specific +- [ObservabilityPlane](./observabilityplane.md) - Provides the underlying observability infrastructure diff --git a/versioned_docs/version-v0.11.x/reference/api/platform/observabilityplane.md b/versioned_docs/version-v0.11.x/reference/api/platform/observabilityplane.md new file mode 100644 index 0000000..7ac4a65 --- /dev/null +++ b/versioned_docs/version-v0.11.x/reference/api/platform/observabilityplane.md @@ -0,0 +1,300 @@ +--- +title: ObservabilityPlane API Reference +--- + +# ObservabilityPlane + +An ObservabilityPlane represents the infrastructure layer responsible for collecting, storing, and analyzing observability data (metrics, logs, and traces) from OpenChoreo workloads. It provides centralized monitoring and logging capabilities for applications deployed across DataPlanes and build processes running on BuildPlanes. + +OpenChoreo uses **agent-based communication** where the control plane communicates with the observability cluster through a WebSocket agent running in the ObservabilityPlane cluster. The cluster agent establishes a secure WebSocket connection to the control plane's cluster gateway. + +## API Version + +`openchoreo.dev/v1alpha1` + +## Resource Definition + +### Metadata + +ObservabilityPlanes are namespace-scoped resources that must be created within an Organization's namespace. + +```yaml +apiVersion: openchoreo.dev/v1alpha1 +kind: ObservabilityPlane +metadata: + name: + namespace: # Organization namespace +``` + +### Spec Fields + +| Field | Type | Required | Default | Description | +|---------------------------|-------------------------------------------|----------|---------|------------------------------------------------------------------------------------------------------| +| `planeID` | string | No | default-observabilityplane | Identifies the logical plane this CR connects to. Must match `clusterAgent.planeId` Helm value. | +| `clusterAgent` | [ClusterAgentConfig](#clusteragentconfig) | Yes | - | Configuration for cluster agent-based communication | +| `observerURL` | string | Yes | - | Base URL of the Observer API in the observability plane cluster | + +### PlaneID + +The `planeID` identifies the logical plane this ObservabilityPlane CR connects to. Multiple ObservabilityPlane CRs can share the same `planeID` to connect to the same physical cluster while maintaining separate configurations for multi-tenancy scenarios. + +**Validation Rules:** +- Maximum length: 63 characters +- Pattern: `^[a-z0-9]([-a-z0-9]*[a-z0-9])?$` (lowercase alphanumeric, hyphens allowed) +- Examples: `"shared-obs"`, `"monitoring-cluster"`, `"eu-central-1"` + +:::important PlaneID Consistency +The `planeID` in the ObservabilityPlane CR must match the `clusterAgent.planeId` Helm value configured during observability plane installation. If not specified, it defaults to the CR name for backwards compatibility. +::: + +### ClusterAgentConfig + +Configuration for cluster agent-based communication with the observability cluster. The cluster agent establishes a WebSocket connection to the control plane's cluster gateway. + +| Field | Type | Required | Default | Description | +|------------|-------------------------|----------|---------|------------------------------------------------------------------------------| +| `clientCA` | [ValueFrom](#valuefrom) | Yes | - | CA certificate to verify the agent's client certificate (base64-encoded PEM) | + +### ObserverURL + +The base URL of the Observer API service running in the observability plane cluster. This API is used by the control plane to query logs, metrics, and traces. + +**Format:** `http://observer..svc.cluster.local:` + +**Example:** `http://observer.openchoreo-observability-plane.svc.cluster.local:8080` + +:::tip In-Cluster Communication +The Observer API is typically accessed via in-cluster DNS. The URL should point to the Observer service within the observability plane cluster using the Kubernetes service DNS format. +::: + +### ValueFrom + +Common pattern for referencing secrets or providing inline values. Either `secretRef` or `value` should be specified. + +| Field | Type | Required | Default | Description | +|-------------|---------------------------------------------|----------|---------|----------------------------------------------------------| +| `secretRef` | [SecretKeyReference](#secretkeyreference) | No | - | Reference to a secret key | +| `value` | string | No | - | Inline value (not recommended for sensitive data) | + +### SecretKeyReference + +Reference to a specific key in a Kubernetes secret. + +| Field | Type | Required | Default | Description | +|-------------|--------|----------|---------------------------|--------------------------------------------------------------| +| `name` | string | Yes | - | Name of the secret | +| `namespace` | string | No | Same as parent resource | Namespace of the secret | +| `key` | string | Yes | - | Key within the secret | + +## Getting the Agent CA Certificate + +The cluster agent automatically generates its CA certificate when deployed to the observability plane cluster. This certificate is used by the control plane to verify the identity of the observability plane agent during mTLS authentication. + +### Extracting the CA Certificate + +You can extract the CA certificate using: + +```bash +# For multi-cluster setups, specify the observability plane cluster context +kubectl --context get secret cluster-agent-tls \ + -n openchoreo-observability-plane \ + -o jsonpath='{.data.ca\.crt}' | base64 -d + +# Example for k3d multi-cluster setup: +kubectl --context k3d-openchoreo-op get secret cluster-agent-tls \ + -n openchoreo-observability-plane \ + -o jsonpath='{.data.ca\.crt}' | base64 -d +``` + +:::important +In multi-cluster setups, you **must** specify the `--context` flag to target the observability plane cluster, not the control plane cluster. The `cluster-agent-tls` secret exists in the observability plane cluster where the agent is deployed. +::: + +### Adding the Certificate to the ObservabilityPlane CR + +You can add the CA certificate to the ObservabilityPlane CR in two ways: + +**Option 1: Inline value (for testing/development)** + +```bash +# Extract the CA certificate from the observability plane cluster +OP_CA_CERT=$(kubectl --context get secret cluster-agent-tls \ + -n openchoreo-observability-plane \ + -o jsonpath='{.data.ca\.crt}' | base64 -d) + +# Create ObservabilityPlane in the control plane with inline CA certificate +kubectl --context apply -f - < get secret cluster-agent-tls \ + -n openchoreo-observability-plane \ + -o jsonpath='{.data.ca\.crt}' | base64 -d > /tmp/observabilityplane-ca.crt + +# Create a secret in the control plane cluster +kubectl --context create secret generic observabilityplane-agent-ca \ + --from-file=ca.crt=/tmp/observabilityplane-ca.crt \ + -n my-org + +# Create ObservabilityPlane in the control plane referencing the secret +kubectl --context apply -f - < -n --type merge \ + -p '{"spec":{"observabilityPlaneRef":""}}' +``` + +Example: +```bash +kubectl patch dataplane production-dataplane -n my-org --type merge \ + -p '{"spec":{"observabilityPlaneRef":"production-observability"}}' +``` + +### Linking a BuildPlane + +```bash +kubectl patch buildplane -n --type merge \ + -p '{"spec":{"observabilityPlaneRef":""}}' +``` + +Example: +```bash +kubectl patch buildplane production-buildplane -n my-org --type merge \ + -p '{"spec":{"observabilityPlaneRef":"production-observability"}}' +``` + +## Annotations + +ObservabilityPlanes support the following annotations: + +| Annotation | Description | +|-------------------------------|-------------------------------------------------| +| `openchoreo.dev/display-name` | Human-readable name for UI display | +| `openchoreo.dev/description` | Detailed description of the ObservabilityPlane | + +## Related Resources + +- [DataPlane](./dataplane.md) - Can reference ObservabilityPlane for monitoring +- [BuildPlane](./buildplane.md) - Can reference ObservabilityPlane for build job monitoring +- [Organization](./organization.md) - Organizational context for ObservabilityPlanes +- [ObservabilityAlertRule](./observabilityalertrule.md) - Defines alerting rules for the plane +- [ObservabilityAlertsNotificationChannel](./observabilityalertsnotificationchannel.md) - Defines notification destinations for alerts diff --git a/versioned_docs/version-v0.11.x/reference/api/platform/organization.md b/versioned_docs/version-v0.11.x/reference/api/platform/organization.md new file mode 100644 index 0000000..e14c3ee --- /dev/null +++ b/versioned_docs/version-v0.11.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.11.x/reference/api/platform/releasebinding.md b/versioned_docs/version-v0.11.x/reference/api/platform/releasebinding.md new file mode 100644 index 0000000..e883518 --- /dev/null +++ b/versioned_docs/version-v0.11.x/reference/api/platform/releasebinding.md @@ -0,0 +1,320 @@ +--- +title: ReleaseBinding API Reference +--- + +# ReleaseBinding + +A ReleaseBinding represents an environment-specific deployment of a Component. It binds a specific release to an environment and 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 + +ReleaseBindings are namespace-scoped resources created in the same namespace as the Component they deploy. + +```yaml +apiVersion: openchoreo.dev/v1alpha1 +kind: ReleaseBinding +metadata: + name: - + namespace: +``` + +### Spec Fields + +| Field | Type | Required | Default | Description | +|-----------------------------|---------------------------------------------|----------|---------|--------------------------------------------------------------| +| `owner` | [ReleaseBindingOwner](#releasebindingowner) | Yes | - | Identifies the component this release binding applies to | +| `environment` | string | Yes | - | Name of the environment (must match an Environment CR) | +| `releaseName` | string | Yes | - | Name of the ComponentRelease to bind to this environment | +| `componentTypeEnvOverrides` | object | No | - | Overrides for ComponentType `envOverrides` parameters | +| `traitOverrides` | map[string]object | No | - | Environment-specific trait parameter overrides | +| `workloadOverrides` | [WorkloadOverride](#workloadoverride) | No | - | Overrides for workload configurations | + +### ReleaseBindingOwner + +Identifies which component this release binding 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 | + +### WorkloadOverride + +Environment-specific configuration overrides for the workload. + +| Field | Type | Required | Description | +|--------------|----------------------------------------------------|----------|------------------------------------------------------| +| `containers` | map[string][ContainerOverride](#containeroverride) | No | Container-specific overrides keyed by container name | + +#### ContainerOverride + +| Field | Type | Required | Description | +|---------|-----------------------|----------|--------------------------------| +| `env` | [[EnvVar](#envvar)] | No | Environment variable overrides | +| `files` | [[FileVar](#filevar)] | No | File configuration overrides | + +#### EnvVar + +| Field | Type | Required | Description | +|-------------|-------------------------|----------|-------------------------------| +| `key` | string | Yes | Environment variable name | +| `value` | string | No | Plain text value | +| `secretRef` | [SecretRef](#secretref) | No | Reference to a secret value | + +#### SecretRef + +| Field | Type | Required | Description | +|--------|--------|----------|--------------------------------| +| `name` | string | Yes | Name of the SecretReference CR | +| `key` | string | Yes | Key within the secret | + +#### FileVar + +| Field | Type | Required | Description | +|-------------|-------------------------|----------|----------------------------| +| `key` | string | Yes | File name | +| `mountPath` | string | Yes | Mount path in container | +| `value` | string | No | Plain text file content | +| `secretRef` | [SecretRef](#secretref) | No | Reference to a secret file | + +### Status Fields + +| Field | Type | Default | Description | +|--------------|-------------|---------|--------------------------------------------------------------| +| `conditions` | []Condition | [] | Standard Kubernetes conditions tracking ReleaseBinding state | + +#### Condition Types + +Common condition types for ReleaseBinding resources: + +- `Ready` - Indicates if the release binding is ready +- `Deployed` - Indicates if resources have been deployed successfully +- `Synced` - Indicates if the deployment is in sync with the component definition + +## Examples + +### Basic ReleaseBinding + +```yaml +apiVersion: openchoreo.dev/v1alpha1 +kind: ReleaseBinding +metadata: + name: my-service-production + namespace: default +spec: + owner: + projectName: default + componentName: my-service + + environment: production + releaseName: my-service-v1 +``` + +### ReleaseBinding with Parameter Overrides + +Override ComponentType `envOverrides` parameters for production: + +```yaml +apiVersion: openchoreo.dev/v1alpha1 +kind: ReleaseBinding +metadata: + name: my-service-production + namespace: default +spec: + owner: + projectName: default + componentName: my-service + + environment: production + releaseName: my-service-v1 + + componentTypeEnvOverrides: + resources: + requests: + cpu: "500m" + memory: "1Gi" + limits: + cpu: "2000m" + memory: "4Gi" +``` + +### ReleaseBinding with Trait Overrides + +Override trait parameters for a specific environment: + +```yaml +apiVersion: openchoreo.dev/v1alpha1 +kind: ReleaseBinding +metadata: + name: my-service-production + namespace: default +spec: + owner: + projectName: default + componentName: my-service + + environment: production + releaseName: my-service-v1 + + traitOverrides: + data-storage: # instanceName of the trait attachment + size: 100Gi + storageClass: production-ssd + iops: 3000 +``` + +### ReleaseBinding with Workload Overrides + +Override workload environment variables and files: + +```yaml +apiVersion: openchoreo.dev/v1alpha1 +kind: ReleaseBinding +metadata: + name: my-service-production + namespace: default +spec: + owner: + projectName: default + componentName: my-service + + environment: production + releaseName: my-service-v1 + + workloadOverrides: + containers: + app: + env: + - key: LOG_LEVEL + value: "error" + - key: CACHE_TTL + value: "3600" + + files: + - key: config.yaml + mountPath: /etc/app + value: | + database: + host: prod-db.example.com + port: 5432 + cache: + enabled: true +``` + +### Complete ReleaseBinding Example + +Combining all override types: + +```yaml +apiVersion: openchoreo.dev/v1alpha1 +kind: ReleaseBinding +metadata: + name: my-service-production + namespace: default +spec: + owner: + projectName: default + componentName: my-service + + environment: production + releaseName: my-service-v1 + + # Override ComponentType envOverrides + componentTypeEnvOverrides: + 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 + workloadOverrides: + containers: + app: + env: + - key: LOG_LEVEL + value: "info" + - key: MAX_CONNECTIONS + value: "1000" +``` + +## Usage + +ReleaseBindings 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 release bindings: + +```bash +# List all release bindings +kubectl get releasebindings + +# Get release bindings for a specific component +kubectl get releasebinding -l openchoreo.dev/component=my-service + +# View release binding details +kubectl describe releasebinding 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. **ReleaseBinding overrides** - Environment-specific values in ReleaseBinding + +Example: + +```yaml +# ComponentType defines: replicas default=1 +# Component sets: replicas=3 +# ReleaseBinding (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](../application/component.md) - Defines the component being deployed +- [ComponentRelease](../runtime/componentrelease.md) - Immutable snapshot that ReleaseBinding references for deployment +- [Environment](environment.md) - Defines the target environment +- [ComponentType](componenttype.md) - Defines available parameters for override +- [Trait](trait.md) - Traits whose parameters can be overridden diff --git a/versioned_docs/version-v0.11.x/reference/api/platform/scheduledtaskclass.md b/versioned_docs/version-v0.11.x/reference/api/platform/scheduledtaskclass.md new file mode 100644 index 0000000..759327b --- /dev/null +++ b/versioned_docs/version-v0.11.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.11.x/reference/api/platform/secretreference.md b/versioned_docs/version-v0.11.x/reference/api/platform/secretreference.md new file mode 100644 index 0000000..bfde2da --- /dev/null +++ b/versioned_docs/version-v0.11.x/reference/api/platform/secretreference.md @@ -0,0 +1,244 @@ +--- +title: SecretReference API Reference +--- + +# SecretReference + +A SecretReference defines a mapping between external secret store entries and Kubernetes Secrets. It allows platform +engineers to declaratively specify how secrets from external providers (like HashiCorp Vault, AWS Secrets Manager, etc.) +should be synchronized into Kubernetes Secrets for use by applications. + +## API Version + +`openchoreo.dev/v1alpha1` + +## Resource Definition + +### Metadata + +SecretReferences are namespace-scoped resources that should be created within an Organization's namespace. + +```yaml +apiVersion: openchoreo.dev/v1alpha1 +kind: SecretReference +metadata: + name: + namespace: # Organization namespace +``` + +### Spec Fields + +| Field | Type | Required | Default | Description | +|-------------------|---------------------------------------|----------|---------|----------------------------------------------------------------| +| `template` | [SecretTemplate](#secrettemplate) | Yes | - | Defines the structure of the resulting Kubernetes Secret | +| `data` | [][SecretDataSource](#secretdatasource) | Yes | - | Mapping of secret keys to external secret references (min: 1) | +| `refreshInterval` | [duration](https://pkg.go.dev/k8s.io/apimachinery/pkg/apis/meta/v1#Duration) | No | `1h` | How often to reconcile/refresh the secret from external stores | + +### SecretTemplate + +Defines the structure and metadata of the resulting Kubernetes Secret. + +| Field | Type | Required | Default | Description | +|------------|-----------------------------------|----------|----------|----------------------------------------------------| +| `type` | string | No | `Opaque` | Type of the Kubernetes Secret | +| `metadata` | [SecretMetadata](#secretmetadata) | No | - | Additional metadata to add to the generated secret | + +#### Supported Secret Types + +- `Opaque` - Arbitrary user-defined data (default) +- `kubernetes.io/dockerconfigjson` - Docker registry credentials +- `kubernetes.io/dockercfg` - Legacy Docker registry credentials +- `kubernetes.io/basic-auth` - Basic authentication credentials +- `kubernetes.io/ssh-auth` - SSH authentication credentials +- `kubernetes.io/tls` - TLS certificate and key +- `bootstrap.kubernetes.io/token` - Bootstrap token data + +### SecretMetadata + +Additional metadata to add to the generated Kubernetes Secret. + +| Field | Type | Required | Default | Description | +|---------------|-------------------|----------|---------|-----------------------------------| +| `annotations` | map[string]string | No | - | Annotations to add to the secret | +| `labels` | map[string]string | No | - | Labels to add to the secret | + +### SecretDataSource + +Maps a key in the Kubernetes Secret to a value from an external secret store. + +| Field | Type | Required | Default | Description | +|-------------|-----------------------------------|----------|---------|--------------------------------------------------| +| `secretKey` | string | Yes | - | Key name in the resulting Kubernetes Secret | +| `remoteRef` | [RemoteReference](#remotereference) | Yes | - | Reference to the external secret location | + +### RemoteReference + +Points to a specific secret in an external secret store. + +| Field | Type | Required | Default | Description | +|------------|--------|----------|---------|------------------------------------------------------------------| +| `key` | string | Yes | - | Path in the external secret store (e.g., `secret/data/github/pat`) | +| `property` | string | No | - | Specific field within the secret (e.g., `token`) | +| `version` | string | No | - | Version of the secret to fetch (provider-specific) | + +### Status Fields + +| Field | Type | Default | Description | +|-------------------|----------------------------------------------------------------------------------|---------|--------------------------------------------------------| +| `conditions` | [][Condition](https://pkg.go.dev/k8s.io/apimachinery/pkg/apis/meta/v1#Condition) | [] | Standard Kubernetes conditions tracking the sync state | +| `lastRefreshTime` | [Time](https://pkg.go.dev/k8s.io/apimachinery/pkg/apis/meta/v1#Time) | - | When the secret reference was last processed/refreshed | +| `secretStores` | [][SecretStoreReference](#secretstorereference) | [] | Tracks which secret stores are using this reference | + +#### SecretStoreReference + +Tracks where this SecretReference is being used. + +| Field | Type | Description | +|-------------|--------|----------------------------------------------------| +| `name` | string | Name of the secret store | +| `namespace` | string | Namespace where the ExternalSecret was created | +| `kind` | string | Kind of resource (ExternalSecret, ClusterExternalSecret) | + +#### Condition Types + +Common condition types for SecretReference resources: + +- `Ready` - Indicates if the secret has been successfully synchronized +- `SecretSynced` - Indicates if the secret data has been fetched from the external store + +## Examples + +### Basic Opaque Secret + +```yaml +apiVersion: openchoreo.dev/v1alpha1 +kind: SecretReference +metadata: + name: github-credentials + namespace: default +spec: + template: + type: Opaque + data: + - secretKey: token + remoteRef: + key: secret/data/github/pat + property: token +``` + +### Docker Registry Credentials + +```yaml +apiVersion: openchoreo.dev/v1alpha1 +kind: SecretReference +metadata: + name: docker-registry-creds + namespace: default +spec: + template: + type: kubernetes.io/dockerconfigjson + metadata: + labels: + app: my-service + data: + - secretKey: .dockerconfigjson + remoteRef: + key: secret/data/docker/registry + property: config + refreshInterval: 30m +``` + +### TLS Certificate + +```yaml +apiVersion: openchoreo.dev/v1alpha1 +kind: SecretReference +metadata: + name: api-tls-cert + namespace: default +spec: + template: + type: kubernetes.io/tls + metadata: + annotations: + cert-manager.io/common-name: api.example.com + data: + - secretKey: tls.crt + remoteRef: + key: secret/data/certs/api + property: certificate + - secretKey: tls.key + remoteRef: + key: secret/data/certs/api + property: private_key +``` + +### Database Credentials with Version + +```yaml +apiVersion: openchoreo.dev/v1alpha1 +kind: SecretReference +metadata: + name: database-credentials + namespace: default +spec: + template: + type: Opaque + metadata: + labels: + app: backend + component: database + data: + - secretKey: username + remoteRef: + key: secret/data/db/postgres + property: username + version: "2" + - secretKey: password + remoteRef: + key: secret/data/db/postgres + property: password + version: "2" + refreshInterval: 15m +``` + +### Multiple Secrets from Different Paths + +```yaml +apiVersion: openchoreo.dev/v1alpha1 +kind: SecretReference +metadata: + name: app-secrets + namespace: default +spec: + template: + type: Opaque + data: + - secretKey: API_KEY + remoteRef: + key: secret/data/external-api/credentials + property: api_key + - secretKey: JWT_SECRET + remoteRef: + key: secret/data/auth/jwt + property: secret + - secretKey: ENCRYPTION_KEY + remoteRef: + key: secret/data/encryption/keys + property: primary + refreshInterval: 1h +``` + +## Annotations + +SecretReferences support the following annotations: + +| Annotation | Description | +|-------------------------------|-----------------------------------------------| +| `openchoreo.dev/display-name` | Human-readable name for UI display | +| `openchoreo.dev/description` | Detailed description of the secret reference | + +## Related Resources + +- [Workload](../application/workload.md) - References SecretReference for injecting secrets into deployments +- [ReleaseBinding](./releasebinding.md) - References SecretReference for environment-specific secret configuration diff --git a/versioned_docs/version-v0.11.x/reference/api/platform/serviceclass.md b/versioned_docs/version-v0.11.x/reference/api/platform/serviceclass.md new file mode 100644 index 0000000..56f72cc --- /dev/null +++ b/versioned_docs/version-v0.11.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.11.x/reference/api/platform/trait.md b/versioned_docs/version-v0.11.x/reference/api/platform/trait.md new file mode 100644 index 0000000..cc6ea06 --- /dev/null +++ b/versioned_docs/version-v0.11.x/reference/api/platform/trait.md @@ -0,0 +1,403 @@ +--- +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: a single pipe after the type, then space-separated constraints: + +``` +fieldName: "type | default=value enum=val1,val2" +``` + +**Example:** + +```yaml +schema: + parameters: + volumeName: "string" + mountPath: "string" + 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 | Default | Description | +|---------------|--------|----------|-------------|---------------------------------------------------| +| `targetPlane` | string | No | `dataplane` | Target plane: `dataplane` or `observabilityplane` | +| `template` | object | Yes | - | Kubernetes resource template with CEL expressions | + +CEL expressions in trait templates have access to the following context variables: + +##### metadata + +Platform-computed metadata for resource generation (same as ComponentType): + +| Field | Type | Description | +|-------|------|-------------| +| `metadata.name` | string | Base name for generated resources (e.g., `my-service-dev-a1b2c3d4`) | +| `metadata.namespace` | string | Target namespace for resources | +| `metadata.componentName` | string | Name of the component | +| `metadata.componentUID` | string | Unique identifier of the component | +| `metadata.projectName` | string | Name of the project | +| `metadata.projectUID` | string | Unique identifier of the project | +| `metadata.environmentName` | string | Name of the environment (e.g., `development`, `production`) | +| `metadata.environmentUID` | string | Unique identifier of the environment | +| `metadata.dataPlaneName` | string | Name of the data plane | +| `metadata.dataPlaneUID` | string | Unique identifier of the data plane | +| `metadata.labels` | map | Common labels to add to all resources | +| `metadata.annotations` | map | Common annotations to add to all resources | +| `metadata.podSelectors` | map | Platform-injected selectors for pod identity | + +##### trait + +Trait-specific metadata: + +| Field | Type | Description | +|-------|------|-------------| +| `trait.name` | string | Name of the trait (e.g., `persistent-volume`) | +| `trait.instanceName` | string | Unique instance name within the component (e.g., `data-storage`) | + +##### parameters + +Trait instance parameters from `Component.spec.traits[].parameters` with schema defaults applied. Use for static configuration that doesn't change across environments. + +##### envOverrides + +Environment-specific overrides from `ReleaseBinding.spec.traitOverrides[instanceName]` with schema defaults applied. Use for values that vary per environment. + +##### dataplane + +Data plane configuration: + +| Field | Type | Description | +|-------|------|-------------| +| `dataplane.secretStore` | string | Name of the ClusterSecretStore for external secrets | +| `dataplane.publicVirtualHost` | string | Public virtual host for external access | + +##### Helper Functions + +| Function | Description | +|----------|-------------| +| `oc_generate_name(args...)` | Generate valid Kubernetes names with hash suffix for uniqueness | +| `oc_hash(string)` | Generate 8-character FNV-32a hash from input string | +| `oc_merge(map1, map2, ...)` | Shallow merge maps (later maps override earlier ones) | +| `oc_omit()` | Remove field/key from output when used in conditional expressions | + +### TraitPatch + +Defines modifications to existing resources generated by the ComponentType. + +| Field | Type | Required | Default | 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 | +| `targetPlane` | string | No | `dataplane` | Target plane: `dataplane` or `observabilityplane` | +| `operations` | [[JSONPatchOperation](#jsonpatchoperation)] | Yes | - | List of JSONPatch operations to apply | + +### PatchTarget + +Specifies which Kubernetes resource to modify. + +| Field | Type | Required | Description | +|-----------|--------|----------|--------------------------------------------------------------------------| +| `group` | string | Yes | API group (e.g., `apps`, `batch`). Use empty string `""` 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` | +| `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 + +#### 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" + mountPath: "string" + 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: ${envOverrides.storageClass} + resources: + requests: + storage: ${envOverrides.size} + + patches: + - target: + group: apps + version: v1 + kind: Deployment + operations: + - op: add + path: /spec/template/spec/containers[?(@.name=='${parameters.containerName}')]/volumeMounts/- + value: + name: ${parameters.volumeName} + mountPath: ${parameters.mountPath} + - op: add + path: /spec/template/spec/volumes/- + value: + name: ${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: ${parameters.sidecarImage} + volumeMounts: + - name: logs + mountPath: ${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: add + path: /spec/template/spec/containers[?(@.name=='main')]/resources/limits/cpu + value: ${envOverrides.cpuLimit} + - op: add + path: /spec/template/spec/containers[?(@.name=='main')]/resources/limits/memory + value: ${envOverrides.memoryLimit} +``` + +### Multi-Container Trait with forEach + +```yaml +apiVersion: openchoreo.dev/v1alpha1 +kind: Trait +metadata: + name: multi-volume + namespace: default +spec: + schema: + types: + Mount: + name: "string" + path: "string" + parameters: + mounts: "[]Mount" + + patches: + - target: + group: apps + version: v1 + kind: Deployment + forEach: ${parameters.mounts} + var: mount + operations: + - op: add + path: /spec/template/spec/volumes/- + value: + name: ${mount.name} + emptyDir: {} + - op: add + path: /spec/template/spec/containers[?(@.name=='app')]/volumeMounts/- + value: + name: ${mount.name} + mountPath: ${mount.path} +``` + +## Usage + +Developers attach traits to components in the Component specification: + +```yaml +apiVersion: openchoreo.dev/v1alpha1 +kind: Component +metadata: + name: my-service +spec: + componentType: deployment/service + + traits: + - name: persistent-volume + instanceName: data-storage + parameters: + volumeName: data + mountPath: /var/data + containerName: app +``` + +Platform engineers can set trait `envOverrides` in ReleaseBinding: + +```yaml +apiVersion: openchoreo.dev/v1alpha1 +kind: ReleaseBinding +metadata: + name: my-service-production + namespace: default +spec: + environment: production + owner: + componentName: my-service + projectName: default + + traitOverrides: + data-storage: # keyed by instanceName + size: 100Gi + storageClass: production-ssd +``` + +## Best Practices + +1. **Single Responsibility**: Each trait should address one cross-cutting concern +2. **Naming**: Use descriptive names that indicate the capability being added +3. **Parameters**: Provide sensible defaults for all non-required parameters +4. **Target Specificity**: Use `where` clauses when needed to avoid unintended modifications +5. **Testing**: Test traits with different ComponentTypes to ensure compatibility +6. **Documentation**: Document which ComponentTypes a trait is designed to work with +7. **Idempotency**: Ensure traits can be safely applied multiple times + +## Trait vs ComponentType + +| Aspect | ComponentType | Trait | +|--------------|------------------------------------|----------------------------------------------------------| +| Purpose | Defines core deployment pattern | Adds cross-cutting concerns | +| Scope | One per component | Multiple can be attached to one component | +| Resources | Creates primary workload resources | Creates supplementary resources or patches existing ones | +| Modification | Determines base resource structure | Modifies or extends ComponentType resources | +| Examples | Service, WebApp, ScheduledTask | Persistent Storage, Logging, Security | + +## Related Resources + +- [ComponentType](componenttype.md) - Defines the base deployment pattern +- [Component](../application/component.md) - Attaches traits to components +- [ReleaseBinding](releasebinding.md) - Binds a ComponentRelease to an environment with trait parameter overrides diff --git a/versioned_docs/version-v0.11.x/reference/api/platform/webapplicationclass.md b/versioned_docs/version-v0.11.x/reference/api/platform/webapplicationclass.md new file mode 100644 index 0000000..5dcba97 --- /dev/null +++ b/versioned_docs/version-v0.11.x/reference/api/platform/webapplicationclass.md @@ -0,0 +1,93 @@ +--- +title: WebApplicationClass API Reference (Deprecated) +--- + +# WebApplicationClass + +:::warning Deprecated +WebApplicationClass 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 WebApplicationClass is a platform-level template that provides governance and standardization for WebApplication +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 +WebApplications (claims) that reference these classes. + +## API Version + +`openchoreo.dev/v1alpha1` + +## Resource Definition + +### Metadata + +WebApplicationClasses are namespace-scoped resources that must be created within an Organization's namespace. + +```yaml +apiVersion: openchoreo.dev/v1alpha1 +kind: WebApplicationClass +metadata: + name: + namespace: # Organization namespace +``` + +### Spec Fields + +| Field | Type | Required | Default | Description | +|----------------------|------------------------------------------------------------------------------------------------------------------------------------------|----------|---------|----------------------------------------------------------------------------| +| `deploymentTemplate` | DeploymentSpec | No | - | Kubernetes Deployment specification template for web application workloads | +| `serviceTemplate` | ServiceSpec | No | - | Kubernetes Service specification template for web application networking | + +## Examples + +### Basic WebApplicationClass + +```yaml +apiVersion: openchoreo.dev/v1alpha1 +kind: WebApplicationClass +metadata: + name: standard-webapp + namespace: default +spec: + deploymentTemplate: + replicas: 3 + selector: + matchLabels: + app: webapp + template: + spec: + containers: + - name: main + resources: + requests: + memory: "256Mi" + cpu: "200m" + limits: + memory: "1Gi" + cpu: "1000m" + serviceTemplate: + type: ClusterIP + ports: + - port: 80 + targetPort: 8080 + protocol: TCP +``` + +## Annotations + +WebApplicationClasses support the following annotations: + +| Annotation | Description | +|-------------------------------|-------------------------------------------------| +| `openchoreo.dev/display-name` | Human-readable name for UI display | +| `openchoreo.dev/description` | Detailed description of the WebApplicationClass | + +## Related Resources + +- [WebApplication](../application/webapplication.md) - WebApplication resources that reference + WebApplicationClasses +- [WebApplicationBinding](../runtime/webapplicationbinding.md) - Environment-specific web application + instances +- [Organization](./organization.md) - Contains WebApplicationClass definitions diff --git a/versioned_docs/version-v0.11.x/reference/api/platform/workflow.md b/versioned_docs/version-v0.11.x/reference/api/platform/workflow.md new file mode 100644 index 0000000..6f67bd3 --- /dev/null +++ b/versioned_docs/version-v0.11.x/reference/api/platform/workflow.md @@ -0,0 +1,264 @@ +--- +title: Workflow API Reference +--- + +# Workflow + +:::warning Deprecated +The Workflow resource is deprecated for component builds and will be removed in a future release. Use +[ComponentWorkflow](./componentworkflow.md) instead for building components. ComponentWorkflow provides a structured +schema for repository information required for build-specific platform features like auto-builds, webhooks, and build +traceability. + +Generic Workflow resources will still be used for non-component automation tasks (Terraform, ETL pipelines, database +migrations, etc.) in the future. +::: + +A Workflow is a platform engineer-defined template for executing build, test, and automation tasks in OpenChoreo. +Workflows provide a schema-driven interface that separates developer-facing parameters from platform-controlled +configurations, integrating with Argo Workflows to provide Kubernetes-native CI/CD execution. + +## API Version + +`openchoreo.dev/v1alpha1` + +## Resource Definition + +### Metadata + +Workflows are namespace-scoped resources that must be created within an Organization's namespace. + +```yaml +apiVersion: openchoreo.dev/v1alpha1 +kind: Workflow +metadata: + name: + namespace: # Organization namespace +``` + +### Spec Fields + +| Field | Type | Required | Default | Description | +|------------|--------|----------|---------|----------------------------------------------------------------------------------------------------| +| `schema` | object | No | - | Developer-facing parameters that can be configured when creating a WorkflowRun instance | +| `resource` | object | Yes | - | Kubernetes resource (typically Argo Workflow) with CEL expressions in `${...}` for runtime evaluation | + +### Schema + +The schema field uses the same inline type definition syntax as ComponentType: + +``` +"type | default=value enum=val1,val2 minimum=1 maximum=10" +``` + +Schemas are nested map structures where keys are field names and values are either nested maps or type definition strings. + +## CEL Variables in Resource Templates + +Workflow resource templates support CEL expressions with access to: + +| Variable | Description | +|---------------------------|---------------------------------------------------------------------| +| `${ctx.workflowRunName}` | WorkflowRun CR name (the execution instance) | +| `${ctx.componentName}` | Component name (only accessible for component-bound workflows) | +| `${ctx.projectName}` | Project name (only accessible for component-bound workflows) | +| `${ctx.orgName}` | Organization name (namespace) | +| `${ctx.timestamp}` | Unix timestamp | +| `${ctx.uuid}` | Short UUID (8 characters) | +| `${schema.*}` | Developer-provided values from the schema | + +## Examples + +### Docker Build Workflow + +```yaml +apiVersion: openchoreo.dev/v1alpha1 +kind: Workflow +metadata: + name: docker + namespace: default + annotations: + openchoreo.dev/description: "Docker build workflow for containerized builds using Dockerfile" +spec: + schema: + repository: + url: string + revision: + branch: string | default=main + commit: string | default="" + appPath: string | default=. + secretRef: string + docker: + context: string | default=. + filePath: string | default=./Dockerfile + + resource: + apiVersion: argoproj.io/v1alpha1 + kind: Workflow + metadata: + name: ${ctx.workflowRunName} + namespace: openchoreo-ci-${ctx.orgName} + spec: + arguments: + parameters: + - name: component-name + value: ${ctx.componentName} + - name: project-name + value: ${ctx.projectName} + - name: git-repo + value: ${schema.repository.url} + - name: branch + value: ${schema.repository.revision.branch} + - name: commit + value: ${schema.repository.revision.commit} + - name: app-path + value: ${schema.repository.appPath} + - name: docker-context + value: ${schema.docker.context} + - name: dockerfile-path + value: ${schema.docker.filePath} + # PE-controlled hardcoded parameters + - name: registry-url + value: gcr.io/openchoreo-dev/images + - name: build-timeout + value: "30m" + - name: image-name + value: ${ctx.projectName}-${ctx.componentName}-image + - name: image-tag + value: v1 + serviceAccountName: workflow-sa + workflowTemplateRef: + clusterScope: true + name: docker +``` + +### Google Cloud Buildpacks Workflow + +```yaml +apiVersion: openchoreo.dev/v1alpha1 +kind: Workflow +metadata: + name: google-cloud-buildpacks + namespace: default + annotations: + openchoreo.dev/description: "Google Cloud Buildpacks workflow for containerized builds" +spec: + schema: + repository: + url: string + revision: + branch: string | default=main + commit: string | default=HEAD + appPath: string | default=. + secretRef: string | enum=["reading-list-repo-credentials-dev","payments-repo-credentials-dev"] + version: integer | default=1 + testMode: string | enum=["unit", "integration", "none"] default=unit + command: '[]string | default=[]' + args: "[]string | default=[]" + resources: + cpuCores: integer | default=1 minimum=1 maximum=8 + memoryGb: integer | default=2 minimum=1 maximum=32 + timeout: string | default="30m" + cache: + enabled: boolean | default=true + paths: '[]string | default=["/root/.cache"]' + limits: + maxRetries: integer | default=3 minimum=0 maximum=10 + maxDurationMinutes: integer | default=60 minimum=5 maximum=240 + + secrets: + - ${schema.repository.secretRef} + + resource: + apiVersion: argoproj.io/v1alpha1 + kind: Workflow + metadata: + name: ${ctx.workflowRunName} + namespace: openchoreo-ci-${ctx.orgName} + spec: + arguments: + parameters: + - name: component-name + value: ${ctx.componentName} + - name: project-name + value: ${ctx.projectName} + - name: git-repo + value: ${schema.repository.url} + - name: branch + value: ${schema.repository.revision.branch} + - name: version + value: ${schema.version} + - name: test-mode + value: ${schema.testMode} + - name: cpu-cores + value: ${schema.resources.cpuCores} + - name: memory-gb + value: ${schema.resources.memoryGb} + # PE-controlled hardcoded parameters + - name: builder-image + value: gcr.io/buildpacks/builder@sha256:5977b4bd47d3e9ff729eefe9eb99d321d4bba7aa3b14986323133f40b622aef1 + - name: registry-url + value: gcr.io/openchoreo-dev/images + - name: security-scan-enabled + value: "true" + - name: image-name + value: ${ctx.projectName}-${ctx.componentName}-image + - name: image-tag + value: v${schema.version} + serviceAccountName: workflow-sa + workflowTemplateRef: + clusterScope: true + name: google-cloud-buildpacks +``` + +### Simple Test Workflow + +```yaml +apiVersion: openchoreo.dev/v1alpha1 +kind: Workflow +metadata: + name: unit-tests + namespace: default +spec: + schema: + repository: + url: string | required=true + branch: string | default=main + secretRef: string + testCommand: string | default="npm test" + + resource: + apiVersion: argoproj.io/v1alpha1 + kind: Workflow + metadata: + name: ${ctx.workflowRunName} + namespace: openchoreo-ci-${ctx.orgName} + spec: + entrypoint: run-tests + arguments: + parameters: + - name: repo-url + value: ${schema.repository.url} + - name: branch + value: ${schema.repository.branch} + - name: test-command + value: ${schema.testCommand} + templates: + - name: run-tests + # ... test execution steps +``` + +## Annotations + +Workflows support the following annotations: + +| Annotation | Description | +|-------------------------------|--------------------------------------| +| `openchoreo.dev/display-name` | Human-readable name for UI display | +| `openchoreo.dev/description` | Detailed description of the Workflow | + +## Related Resources + +- [WorkflowRun](../application/workflowrun.md) - Runtime execution instances of Workflows +- [ComponentType](./componenttype.md) - Can restrict allowed workflows via `allowedWorkflows` +- [Component](../application/component.md) - Can reference workflows for building diff --git a/versioned_docs/version-v0.11.x/reference/api/runtime/componentrelease.md b/versioned_docs/version-v0.11.x/reference/api/runtime/componentrelease.md new file mode 100644 index 0000000..67ab8e7 --- /dev/null +++ b/versioned_docs/version-v0.11.x/reference/api/runtime/componentrelease.md @@ -0,0 +1,235 @@ +--- +title: ComponentRelease API Reference +--- + +# ComponentRelease + +A ComponentRelease represents an immutable snapshot of a component's configuration at a specific point in time in OpenChoreo. It captures the complete component specification including the ComponentType, Traits, parameters, and Workload template with the built image. ComponentReleases ensure reproducibility and enable rollback by preserving the exact state of a component when it was released. + +## API Version + +`openchoreo.dev/v1alpha1` + +## Resource Definition + +### Metadata + +ComponentReleases are namespace-scoped resources that must be created within an Organization's namespace. + +```yaml +apiVersion: openchoreo.dev/v1alpha1 +kind: ComponentRelease +metadata: + name: + namespace: # Organization namespace +``` + +### Spec Fields + +| Field | Type | Required | Default | Description | +|--------------------|---------------------------------------------------------------------------------|----------|---------|-----------------------------------------------------------------------| +| `owner` | [ComponentReleaseOwner](#componentreleaseowner) | Yes | - | Ownership information linking the release to a project and component | +| `componentType` | [ComponentTypeSpec](../platform/componenttype.md#spec-fields) | Yes | - | Immutable snapshot of the ComponentType at release time | +| `traits` | map[string][TraitSpec](../platform/trait.md#spec-fields) | No | {} | Immutable snapshot of trait specifications at release time | +| `componentProfile` | [ComponentProfile](#componentprofile) | Yes | - | Immutable snapshot of parameter values and trait configurations | +| `workload` | [WorkloadTemplateSpec](#workloadtemplatespec) | Yes | - | Immutable snapshot of the workload specification with the built image | + +### ComponentReleaseOwner + +| Field | Type | Required | Default | Description | +|-----------------|--------|----------|---------|------------------------------------------------------| +| `projectName` | string | Yes | - | Name of the project that owns this component release | +| `componentName` | string | Yes | - | Name of the component this release belongs to | + +### ComponentProfile + +ComponentProfile contains the frozen parameter values and trait configurations at the time of release. + +| Field | Type | Required | Default | Description | +|--------------|-----------------------------------------------------------------------------------------|----------|---------|-------------------------------------------------------------------| +| `parameters` | [runtime.RawExtension](https://pkg.go.dev/k8s.io/apimachinery/pkg/runtime#RawExtension) | No | - | Merged schema of parameters + envOverrides from the ComponentType | +| `traits` | [[ComponentTrait](#componenttrait)] | No | [] | Trait instances with their configurations | + +### ComponentTrait + +| Field | Type | Required | Default | Description | +|----------------|-----------------------------------------------------------------------------------------|----------|---------|----------------------------------------------------------------| +| `name` | string | Yes | - | Name of the Trait resource | +| `instanceName` | string | Yes | - | Unique identifier for this trait instance within the component | +| `parameters` | [runtime.RawExtension](https://pkg.go.dev/k8s.io/apimachinery/pkg/runtime#RawExtension) | No | - | Trait parameter values conforming to the trait's schema | + +### WorkloadTemplateSpec + +The WorkloadTemplateSpec contains the complete workload specification with the built container image. + +| Field | Type | Required | Default | Description | +|---------------|--------------------------------------------------------------------------------|----------|---------|-----------------------------------------------------------------------------------------------------| +| `containers` | map[string][Container](../application/workload.md#container) | Yes | - | Container specifications keyed by container name. Must have at least one container with key "main" | +| `endpoints` | map[string][WorkloadEndpoint](../application/workload.md#workloadendpoint) | No | {} | Network endpoints for port exposure keyed by endpoint name | +| `connections` | map[string][WorkloadConnection](../application/workload.md#workloadconnection) | No | {} | Connections to internal/external resources keyed by connection name. Supports template variables | + +### Status Fields + +Currently, ComponentRelease does not have any status fields defined. + +## Examples + +### Basic ComponentRelease for a Service Component + +```yaml +apiVersion: openchoreo.dev/v1alpha1 +kind: ComponentRelease +metadata: + name: customer-service-v1.0.0 + namespace: default +spec: + owner: + projectName: my-project + componentName: customer-service + componentType: + workloadType: deployment + schema: + parameters: + runtime: + port: "integer | default=8080" + resources: + - id: deployment + template: + apiVersion: apps/v1 + kind: Deployment + metadata: + name: "${metadata.name}" + spec: + replicas: 1 + template: + spec: + containers: + - name: main + image: "${spec.workload.containers.main.image}" + ports: + - containerPort: "${spec.parameters.runtime.port}" + componentProfile: + parameters: + runtime: + port: 8080 + workload: + containers: + main: + image: myregistry/customer-service@sha256:abc123... + env: + - key: LOG_LEVEL + value: info + endpoints: + api: + type: REST + port: 8080 +``` + +### ComponentRelease with Traits + +```yaml +apiVersion: openchoreo.dev/v1alpha1 +kind: ComponentRelease +metadata: + name: order-service-v2.1.0 + namespace: default +spec: + owner: + projectName: my-project + componentName: order-service + componentType: + workloadType: deployment + schema: + parameters: + runtime: + replicas: "integer | default=1" + resources: + - id: deployment + template: + apiVersion: apps/v1 + kind: Deployment + metadata: + name: "${metadata.name}" + spec: + replicas: "${spec.parameters.runtime.replicas}" + traits: + persistent-volume: + schema: + parameters: + volumeName: "string | required=true" + mountPath: "string | required=true" + envOverrides: + size: "string | default=10Gi" + patches: + - target: + id: deployment + operations: + - op: add + path: /spec/template/spec/volumes/- + value: + name: "${spec.traits.volumeName}" + componentProfile: + parameters: + runtime: + replicas: 3 + traits: + - name: persistent-volume + instanceName: data-volume + parameters: + volumeName: data + mountPath: /var/data + size: 20Gi + workload: + containers: + main: + image: myregistry/order-service@sha256:def456... + env: + - key: DATA_DIR + value: /var/data + endpoints: + order-api: + type: REST + port: 8080 + connections: + database: + type: api + params: + projectName: my-project + componentName: postgres-db + endpoint: tcp-endpoint + inject: + env: + - name: DATABASE_HOST + value: "{{ .host }}" + - name: DATABASE_PORT + value: "{{ .port }}" +``` + +## Immutability + +ComponentRelease is designed to be immutable once created. All spec fields have validation rules that prevent modifications after creation: + +- `spec.componentType` - Immutable +- `spec.traits` - Immutable +- `spec.componentProfile` - Immutable +- `spec.workload` - Immutable + +This ensures that a ComponentRelease always represents the exact state of the component at a specific point in time, enabling reliable rollbacks and auditing. + +## Annotations + +ComponentReleases support the following annotations: + +| Annotation | Description | +|-------------------------------|----------------------------------------------------| +| `openchoreo.dev/display-name` | Human-readable name for UI display | +| `openchoreo.dev/description` | Detailed description of the component release | +| `openchoreo.dev/version` | Semantic version or tag for this release | + +## Related Resources + +- [Component](../application/component.md) - Components that ComponentReleases are created from +- [ComponentType](../platform/componenttype.md) - Component type definitions captured in releases +- [Trait](../platform/trait.md) - Trait specifications captured in releases +- [Workload](../application/workload.md) - Workload specifications captured in releases +- [ReleaseBinding](../platform/releasebinding.md) - Binds a ComponentRelease to a target environment for deployment \ No newline at end of file diff --git a/versioned_docs/version-v0.11.x/reference/api/runtime/release.md b/versioned_docs/version-v0.11.x/reference/api/runtime/release.md new file mode 100644 index 0000000..9046c2b --- /dev/null +++ b/versioned_docs/version-v0.11.x/reference/api/runtime/release.md @@ -0,0 +1,163 @@ +--- +title: Release API Reference +--- + +# Release + +A Release represents the actual deployment of application resources to a data plane environment in OpenChoreo. It is +created by binding resources (ServiceBinding, WebApplicationBinding, ScheduledTaskBinding) and contains the complete +set of Kubernetes resources that need to be applied to the target environment. Releases manage the lifecycle and health +monitoring of deployed resources. + +## API Version + +`openchoreo.dev/v1alpha1` + +## Resource Definition + +### Metadata + +Releases are namespace-scoped resources that must be created within an Organization's namespace. + +```yaml +apiVersion: openchoreo.dev/v1alpha1 +kind: Release +metadata: + name: + namespace: # Organization namespace +``` + +### Spec Fields + +| Field | Type | Required | Default | Description | +|-----------------------|-------------------------------|----------|---------|----------------------------------------------------------------------| +| `owner` | [ReleaseOwner](#releaseowner) | Yes | - | Ownership information linking the release to a project and component | +| `environmentName` | string | Yes | - | Name of the target environment for this release | +| `resources` | [[Resource](#resource)] | No | [] | List of Kubernetes resources to apply to the data plane | +| `interval` | Duration | No | 5m | Watch interval for resources when stable | +| `progressingInterval` | Duration | No | 10s | Watch interval for resources when transitioning | + +### ReleaseOwner + +| Field | Type | Required | Default | Description | +|-----------------|--------|----------|---------|----------------------------------------------| +| `projectName` | string | Yes | - | Name of the project that owns this release | +| `componentName` | string | Yes | - | Name of the component that owns this release | + +### Resource + +| Field | Type | Required | Default | Description | +|----------|----------------------|----------|---------|----------------------------------------------------------| +| `id` | string | Yes | - | Unique identifier for the resource | +| `object` | runtime.RawExtension | Yes | - | Complete Kubernetes resource definition in raw JSON/YAML | + +### Status Fields + +| Field | Type | Default | Description | +|--------------|-------------------------------------|---------|-------------------------------------------------------------------------| +| `resources` | [[ResourceStatus](#resourcestatus)] | [] | List of resources that have been successfully applied to the data plane | +| `conditions` | [[Condition](#conditions)] | [] | Conditions tracking the release state | + +### ResourceStatus + +| Field | Type | Default | Description | +|--------------------|-------------------------------|---------|----------------------------------------------------------| +| `id` | string | - | Corresponds to the resource ID in spec.resources | +| `group` | string | "" | API group of the resource (e.g., "apps", "batch") | +| `version` | string | - | API version of the resource (e.g., "v1", "v1beta1") | +| `kind` | string | - | Type of the resource (e.g., "Deployment", "Service") | +| `name` | string | - | Name of the resource in the data plane | +| `namespace` | string | "" | Namespace of the resource in the data plane | +| `status` | runtime.RawExtension | - | Entire .status field of the resource from the data plane | +| `healthStatus` | [HealthStatus](#healthstatus) | - | Health of the resource in the data plane | +| `lastObservedTime` | Time | - | Last time the status was observed | + +### HealthStatus + +| Value | Description | +|---------------|----------------------------------------------------------------------------------| +| `Unknown` | Health of the resource is not known | +| `Progressing` | Resource is in a transitioning state to become healthy | +| `Healthy` | Resource is healthy and operating as expected | +| `Suspended` | Resource is intentionally paused (e.g., CronJob, Deployment with paused rollout) | +| `Degraded` | Resource is not healthy and not operating as expected | + +### Conditions + +Releases report their state through standard Kubernetes conditions. The following condition types are used: + +| Type | Description | +|--------------|-----------------------------------------------------------------------------------------------| +| `Finalizing` | Indicates the Release is being deleted and resources are being cleaned up from the data plane | + +## Examples + +### Basic Release with Deployment and Service + +```yaml +apiVersion: openchoreo.dev/v1alpha1 +kind: Release +metadata: + name: customer-service-prod-release + namespace: default +spec: + owner: + projectName: my-project + componentName: customer-service + environmentName: production + interval: 5m + progressingInterval: 10s + resources: + - id: deployment + object: + apiVersion: apps/v1 + kind: Deployment + metadata: + name: customer-service + namespace: prod-data-plane + spec: + replicas: 3 + selector: + matchLabels: + app: customer-service + template: + metadata: + labels: + app: customer-service + spec: + containers: + - name: main + image: myregistry/customer-service:v1.0.0 + ports: + - containerPort: 8080 + - id: service + object: + apiVersion: v1 + kind: Service + metadata: + name: customer-service + namespace: prod-data-plane + spec: + selector: + app: customer-service + ports: + - port: 80 + targetPort: 8080 +``` + +## Annotations + +Releases support the following annotations: + +| Annotation | Description | +|-------------------------------|-------------------------------------| +| `openchoreo.dev/display-name` | Human-readable name for UI display | +| `openchoreo.dev/description` | Detailed description of the release | + +## Related Resources + +- [ServiceBinding](./servicebinding.md) - Creates releases for services +- [WebApplicationBinding](./webapplicationbinding.md) - Creates releases for web applications +- [ScheduledTaskBinding](./scheduledtaskbinding.md) - Creates releases for scheduled tasks +- [Environment](../platform/environment.md) - Target environments for releases +- [DataPlane](../platform/dataplane.md) - Data planes where resources are deployed diff --git a/versioned_docs/version-v0.11.x/reference/api/runtime/scheduledtaskbinding.md b/versioned_docs/version-v0.11.x/reference/api/runtime/scheduledtaskbinding.md new file mode 100644 index 0000000..67b3823 --- /dev/null +++ b/versioned_docs/version-v0.11.x/reference/api/runtime/scheduledtaskbinding.md @@ -0,0 +1,108 @@ +--- +title: ScheduledTaskBinding API Reference +--- + +# ScheduledTaskBinding + +A ScheduledTaskBinding represents the deployment of a ScheduledTask to a specific Environment in OpenChoreo. It binds a +ScheduledTask component to an environment, creating the actual runtime instances for scheduled jobs. +ScheduledTaskBindings +contain environment-specific configurations including the workload specification and scheduling parameters. They control +the lifecycle of the deployed scheduled task. + +## API Version + +`openchoreo.dev/v1alpha1` + +## Resource Definition + +### Metadata + +ScheduledTaskBindings are namespace-scoped resources that must be created within an Organization's namespace. + +```yaml +apiVersion: openchoreo.dev/v1alpha1 +kind: ScheduledTaskBinding +metadata: + name: + namespace: # Organization namespace +``` + +### Spec Fields + +| Field | Type | Required | Default | Description | +|----------------|-----------------------------------------------|----------|-----------|-----------------------------------------------------------------------| +| `owner` | [ScheduledTaskOwner](#scheduledtaskowner) | Yes | - | Ownership information linking the binding to a project and component | +| `environment` | string | Yes | - | Target environment for this binding | +| `className` | string | No | "default" | Name of the ScheduledTaskClass that provides deployment configuration | +| `workloadSpec` | [WorkloadTemplateSpec](#workloadtemplatespec) | Yes | - | Workload specification for this environment | +| `releaseState` | [ReleaseState](#releasestate) | No | "Active" | Controls the deployment state of the release | + +### ScheduledTaskOwner + +| Field | Type | Required | Default | Description | +|-----------------|--------|----------|---------|-------------------------------------------------------------| +| `projectName` | string | Yes | - | Name of the project that owns this scheduled task binding | +| `componentName` | string | Yes | - | Name of the component that owns this scheduled task binding | + +### WorkloadTemplateSpec + +The WorkloadTemplateSpec contains the same fields as the Workload spec, allowing environment-specific configuration. + +| Field | Type | Required | Default | Description | +|---------------|--------------------------------------------------------------------------------|----------|---------|--------------------------------------------------------------------------------------------------------| +| `containers` | map[string][Container](../application/workload.md#container) | Yes | - | Container specifications keyed by container name. Must have at least one container with the key "main" | +| `endpoints` | map[string][WorkloadEndpoint](../application/workload.md#workloadendpoint) | No | {} | Network endpoints for port exposure keyed by endpoint name | +| `connections` | map[string][WorkloadConnection](../application/workload.md#workloadconnection) | No | {} | Connections to internal/external resources keyed by connection name | + +### ReleaseState + +| Value | Description | +|------------|---------------------------------------------------| +| `Active` | Resources are deployed normally to the data plane | +| `Suspend` | Resources are suspended (scheduled job is paused) | +| `Undeploy` | Resources are removed from the data plane | + +## Examples + +### Basic ScheduledTaskBinding + +```yaml +apiVersion: openchoreo.dev/v1alpha1 +kind: ScheduledTaskBinding +metadata: + name: data-cleanup-prod-binding + namespace: default +spec: + owner: + projectName: my-project + componentName: data-cleanup + environment: production + className: default + workloadSpec: + containers: + main: + image: myregistry/data-cleanup:v1.2.0 + env: + - key: RETENTION_DAYS + value: "30" + - key: LOG_LEVEL + value: info +``` + +## Annotations + +ScheduledTaskBindings 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 binding | + +## Related Resources + +- [ScheduledTask](../application/scheduledtask.md) - ScheduledTask resources that ScheduledTaskBindings + deploy +- [Environment](../platform/environment.md) - Environments where scheduled tasks are bound +- [Release](./release.md) - Releases created by ScheduledTaskBindings +- [Workload](../application/workload.md) - Workload specifications used in bindings diff --git a/versioned_docs/version-v0.11.x/reference/api/runtime/servicebinding.md b/versioned_docs/version-v0.11.x/reference/api/runtime/servicebinding.md new file mode 100644 index 0000000..125eadc --- /dev/null +++ b/versioned_docs/version-v0.11.x/reference/api/runtime/servicebinding.md @@ -0,0 +1,196 @@ +--- +title: ServiceBinding API Reference +--- + +# ServiceBinding + +A ServiceBinding represents the deployment of a Service to a specific Environment in OpenChoreo. It binds a Service +component to an environment, creating the actual runtime instances. ServiceBindings contain environment-specific +configurations including the workload specification and API configurations. They control the lifecycle of the +deployed service. + +## API Version + +`openchoreo.dev/v1alpha1` + +## Resource Definition + +### Metadata + +ServiceBindings are namespace-scoped resources that must be created within an Organization's namespace. + +```yaml +apiVersion: openchoreo.dev/v1alpha1 +kind: ServiceBinding +metadata: + name: + namespace: # Organization namespace +``` + +### Spec Fields + +| Field | Type | Required | Default | Description | +|----------------|-----------------------------------------------|----------|-----------|--------------------------------------------------------------------------------| +| `owner` | [ServiceOwner](#serviceowner) | Yes | - | Ownership information linking the binding to a project and component | +| `environment` | string | Yes | - | Target environment for this binding | +| `className` | string | No | "default" | Name of the ServiceClass that provides deployment configuration | +| `workloadSpec` | [WorkloadTemplateSpec](#workloadtemplatespec) | Yes | - | Workload specification for this environment | +| `apis` | map[string][ServiceAPI](#serviceapi) | No | {} | API configuration for endpoints. Keys must match endpoint keys in the workload | +| `releaseState` | [ReleaseState](#releasestate) | No | "Active" | Controls the deployment state of the release | + +### ServiceOwner + +| Field | Type | Required | Default | Description | +|-----------------|--------|----------|---------|------------------------------------------------------| +| `projectName` | string | Yes | - | Name of the project that owns this service binding | +| `componentName` | string | Yes | - | Name of the component that owns this service binding | + +### WorkloadTemplateSpec + +The WorkloadTemplateSpec contains the same fields as the Workload spec, allowing environment-specific configuration. + +| Field | Type | Required | Default | Description | +|---------------|--------------------------------------------------------------------------------|----------|---------|----------------------------------------------------------------------------------------------------------------------------------| +| `containers` | map[string][Container](../application/workload.md#container) | Yes | - | Container specifications keyed by container name. Must have at least one container with the key "main" | +| `endpoints` | map[string][WorkloadEndpoint](../application/workload.md#workloadendpoint) | No | {} | Network endpoints for port exposure keyed by endpoint name | +| `connections` | map[string][WorkloadConnection](../application/workload.md#workloadconnection) | No | {} | Connections to internal/external resources keyed by connection name. Supports template variables provided by the connection type | + +### ServiceAPI + +| Field | Type | Required | Default | Description | +|-------------|--------------------------------------------------------|----------|-----------|----------------------------------------| +| `className` | string | No | "default" | API class name for management policies | +| `type` | [EndpointType](../application/service.md#endpointtype) | Yes | - | Type of the API endpoint | +| `rest` | [RESTEndpoint](../application/service.md#restendpoint) | No | - | REST-specific endpoint configuration | + +### ReleaseState + +| Value | Description | +|------------|----------------------------------------------------| +| `Active` | Resources are deployed normally to the data plane | +| `Suspend` | Resources are suspended (scaled to zero or paused) | +| `Undeploy` | Resources are removed from the data plane | + +### Status Fields + +| Field | Type | Default | Description | +|--------------|-------------------------------------|---------|-----------------------------------------------------------| +| `conditions` | []Condition | [] | Standard Kubernetes conditions tracking the binding state | +| `endpoints` | [[EndpointStatus](#endpointstatus)] | [] | Status information for each endpoint | + +### EndpointStatus + +| Field | Type | Default | Description | +|----------------|--------------------------------------------------------|---------|-----------------------------------------------| +| `name` | string | "" | Endpoint identifier matching spec.endpoints | +| `type` | [EndpointType](../application/service.md#endpointtype) | "" | Type of the endpoint | +| `project` | [EndpointAccess](#endpointaccess) | - | Access info for project-level visibility | +| `organization` | [EndpointAccess](#endpointaccess) | - | Access info for organization-level visibility | +| `public` | [EndpointAccess](#endpointaccess) | - | Access info for public visibility | + +### EndpointAccess + +| Field | Type | Default | Description | +|------------|--------|---------|-------------------------------------------------------------------------------------| +| `host` | string | "" | Hostname or service name | +| `port` | int32 | 0 | Port number | +| `scheme` | string | "" | Connection scheme (http, https, grpc, tcp) | +| `basePath` | string | "" | Base URL path (for HTTP-based endpoints) | +| `uri` | string | "" | Computed URI for connecting to the endpoint (e.g., https://api.example.com:8080/v1) | + +## Examples + +### Basic ServiceBinding + +```yaml +apiVersion: openchoreo.dev/v1alpha1 +kind: ServiceBinding +metadata: + name: customer-service-prod-binding + namespace: default +spec: + owner: + projectName: my-project + componentName: customer-service + environment: production + className: default + workloadSpec: + containers: + main: + image: myregistry/customer-service:v1.0.0 + env: + - key: LOG_LEVEL + value: info + - key: DB_HOST + value: prod-db.example.com + endpoints: + api: + type: REST + port: 8080 +``` + +### ServiceBinding with API Configuration + +```yaml +apiVersion: openchoreo.dev/v1alpha1 +kind: ServiceBinding +metadata: + name: order-service-staging-binding + namespace: default +spec: + owner: + projectName: my-project + componentName: order-service + environment: staging + className: production-service + workloadSpec: + containers: + main: + image: myregistry/order-service:v2.1.0-rc1 + env: + - key: ENVIRONMENT + value: staging + endpoints: + order-api: + type: REST + port: 8080 + connections: + database: + type: api + params: + projectName: my-project + componentName: postgres-db + endpoint: tcp-endpoint + inject: + env: + - name: DATABASE_HOST + value: "{{ .host }}" + - name: DATABASE_PORT + value: "{{ .port }}" + apis: + order-api: + className: default + type: REST + rest: + backend: + port: 8080 + basePath: /api/v1 + exposeLevels: + - Organization +``` + +## Annotations + +ServiceBindings support the following annotations: + +| Annotation | Description | +|-------------------------------|---------------------------------------------| +| `openchoreo.dev/display-name` | Human-readable name for UI display | +| `openchoreo.dev/description` | Detailed description of the service binding | + +## Related Resources + +- [Service](../application/service.md) - Service resources that ServiceBindings deploy +- [Environment](../platform/environment.md) - Environments where services are bound +- [Release](./release.md) - Releases created by ServiceBindings +- [Workload](../application/workload.md) - Workload specifications used in bindings diff --git a/versioned_docs/version-v0.11.x/reference/api/runtime/webapplicationbinding.md b/versioned_docs/version-v0.11.x/reference/api/runtime/webapplicationbinding.md new file mode 100644 index 0000000..6e431d1 --- /dev/null +++ b/versioned_docs/version-v0.11.x/reference/api/runtime/webapplicationbinding.md @@ -0,0 +1,188 @@ +--- +title: WebApplicationBinding API Reference +--- + +# WebApplicationBinding + +A WebApplicationBinding represents the deployment of a WebApplication to a specific Environment in OpenChoreo. It binds +a WebApplication component to an environment, creating the actual runtime instances. WebApplicationBindings contain +environment-specific configurations including the workload specification. They control the lifecycle of the deployed +web application. + +## API Version + +`openchoreo.dev/v1alpha1` + +## Resource Definition + +### Metadata + +WebApplicationBindings are namespace-scoped resources that must be created within an Organization's namespace. + +```yaml +apiVersion: openchoreo.dev/v1alpha1 +kind: WebApplicationBinding +metadata: + name: + namespace: # Organization namespace +``` + +### Spec Fields + +| Field | Type | Required | Default | Description | +|----------------|-----------------------------------------------|----------|-----------|------------------------------------------------------------------------| +| `owner` | [WebApplicationOwner](#webapplicationowner) | Yes | - | Ownership information linking the binding to a project and component | +| `environment` | string | Yes | - | Target environment for this binding | +| `className` | string | No | "default" | Name of the WebApplicationClass that provides deployment configuration | +| `workloadSpec` | [WorkloadTemplateSpec](#workloadtemplatespec) | Yes | - | Workload specification for this environment | +| `releaseState` | [ReleaseState](#releasestate) | No | "Active" | Controls the deployment state of the release | + +### WebApplicationOwner + +| Field | Type | Required | Default | Description | +|-----------------|--------|----------|---------|--------------------------------------------------------------| +| `projectName` | string | Yes | - | Name of the project that owns this web application binding | +| `componentName` | string | Yes | - | Name of the component that owns this web application binding | + +### WorkloadTemplateSpec + +The WorkloadTemplateSpec contains the same fields as the Workload spec, allowing environment-specific configuration. + +| Field | Type | Required | Default | Description | +|---------------|--------------------------------------------------------------------------------|----------|---------|----------------------------------------------------------------------------------------------------------------------------------| +| `containers` | map[string][Container](../application/workload.md#container) | Yes | - | Container specifications keyed by container name. Must have at least one container with the key "main" | +| `endpoints` | map[string][WorkloadEndpoint](../application/workload.md#workloadendpoint) | No | {} | Network endpoints for port exposure keyed by endpoint name | +| `connections` | map[string][WorkloadConnection](../application/workload.md#workloadconnection) | No | {} | Connections to internal/external resources keyed by connection name. Supports template variables provided by the connection type | + +### ReleaseState + +| Value | Description | +|------------|----------------------------------------------------| +| `Active` | Resources are deployed normally to the data plane | +| `Suspend` | Resources are suspended (scaled to zero or paused) | +| `Undeploy` | Resources are removed from the data plane | + +### Status Fields + +| Field | Type | Default | Description | +|--------------|-------------------------------------|---------|-----------------------------------------------------------| +| `conditions` | []Condition | [] | Standard Kubernetes conditions tracking the binding state | +| `endpoints` | [[EndpointStatus](#endpointstatus)] | [] | Status information for each endpoint | + +### EndpointStatus + +| Field | Type | Default | Description | +|----------------|-----------------------------------|---------|-----------------------------------------------| +| `name` | string | "" | Endpoint identifier matching spec.endpoints | +| `type` | string | "" | Type of the endpoint | +| `project` | [EndpointAccess](#endpointaccess) | - | Access info for project-level visibility | +| `organization` | [EndpointAccess](#endpointaccess) | - | Access info for organization-level visibility | +| `public` | [EndpointAccess](#endpointaccess) | - | Access info for public visibility | + +### EndpointAccess + +| Field | Type | Default | Description | +|------------|--------|---------|-------------------------------------------------------------------------------------| +| `host` | string | "" | Hostname or service name | +| `port` | int32 | 0 | Port number | +| `scheme` | string | "" | Connection scheme (http, https) | +| `basePath` | string | "" | Base URL path (for HTTP-based endpoints) | +| `uri` | string | "" | Computed URI for connecting to the endpoint (e.g., https://api.example.com:8080/v1) | + +## Examples + +### Basic WebApplicationBinding + +```yaml +apiVersion: openchoreo.dev/v1alpha1 +kind: WebApplicationBinding +metadata: + name: frontend-app-prod-binding + namespace: default +spec: + owner: + projectName: my-project + componentName: frontend + environment: production + className: default + workloadSpec: + containers: + main: + image: myregistry/frontend:v2.0.0 + env: + - key: API_URL + value: https://api.production.example.com + - key: ENVIRONMENT + value: production + endpoints: + http: + type: HTTP + port: 3000 +``` + +### WebApplicationBinding with Connections + +```yaml +apiVersion: openchoreo.dev/v1alpha1 +kind: WebApplicationBinding +metadata: + name: admin-dashboard-staging-binding + namespace: default +spec: + owner: + projectName: my-project + componentName: admin-ui + environment: staging + className: production-webapp + workloadSpec: + containers: + main: + image: myregistry/admin-dashboard:v1.5.0-rc2 + env: + - key: LOG_LEVEL + value: debug + endpoints: + web: + type: HTTP + port: 8080 + connections: + backend-api: + type: api + params: + projectName: my-project + componentName: admin-backend + endpoint: http-endpoint + inject: + env: + - name: BACKEND_URL + value: "{{ .host }}:{{ .port }}" + auth-service: + type: api + params: + projectName: my-project + componentName: auth-service + endpoint: http-endpoint + inject: + env: + - name: AUTH_HOST + value: "{{ .host }}" + - name: AUTH_PORT + value: "{{ .port }}" +``` + +## Annotations + +WebApplicationBindings 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 binding | + +## Related Resources + +- [WebApplication](../application/webapplication.md) - WebApplication resources that + WebApplicationBindings deploy +- [Environment](../platform/environment.md) - Environments where web applications are bound +- [Release](./release.md) - Releases created by WebApplicationBindings +- [Workload](../application/workload.md) - Workload specifications used in bindings diff --git a/versioned_docs/version-v0.11.x/reference/cel/built-in-functions.md b/versioned_docs/version-v0.11.x/reference/cel/built-in-functions.md new file mode 100644 index 0000000..838a156 --- /dev/null +++ b/versioned_docs/version-v0.11.x/reference/cel/built-in-functions.md @@ -0,0 +1,181 @@ +--- +title: Built-in Functions +description: OpenChoreo CEL built-in functions for templates +--- + +# Built-in Functions + +OpenChoreo provides several built-in CEL functions for common operations in ComponentType and Trait templates. + +## oc_omit() + +Removes fields from output. Has two distinct behaviors depending on usage context. + +### Field-level Omission + +When used as a standalone value, removes the entire YAML key from the template: + +```yaml +resources: + limits: + memory: ${parameters.memoryLimit} + cpu: ${has(parameters.cpuLimit) ? parameters.cpuLimit : oc_omit()} + # When cpuLimit is missing, the entire 'cpu:' line is removed + +metadata: + name: ${metadata.name} + annotations: ${has(parameters.annotations) ? parameters.annotations : oc_omit()} + # When annotations is missing, the entire 'annotations:' key is removed +``` + +### Expression-level Omission + +When used inside a CEL map expression, removes the key from the map: + +```yaml +# Use CEL's optional key syntax for simple optional fields +container: | + ${{ + "image": parameters.image, + ?"cpu": parameters.?cpu, + ?"memory": parameters.?memory + }} + # Keys are only included if the value exists + +# Use oc_omit() when conditional logic is involved +container: | + ${{ + "image": parameters.image, + "cpu": parameters.cpuLimit > 0 ? parameters.cpuLimit : oc_omit(), + "debug": parameters.environment == "dev" ? true : oc_omit() + }} + # Keys are conditionally included based on logic, not just existence +``` + +## oc_merge(base, override, ...) + +Shallow merge two or more maps. Later maps override earlier ones for conflicting keys. + +**Parameters:** +- `base` - Base map +- `override` - Map to merge (overrides base) +- `...` - Additional maps (optional) + +**Returns:** Merged map + +```yaml +# Merge default and custom labels +labels: | + ${oc_merge({"app": metadata.name, "version": "v1"}, parameters.customLabels)} + +# Merge multiple maps (later maps take precedence) +config: ${oc_merge(defaults, layer1, layer2, layer3)} + +# Common pattern: merge platform labels with user labels +metadata: + labels: ${oc_merge(metadata.labels, parameters.customLabels)} +``` + +## oc_generate_name(...args) + +Generate valid Kubernetes resource names with a hash suffix for uniqueness. Converts input to lowercase, replaces invalid characters with hyphens, and appends an 8-character hash. + +**Parameters:** +- `...args` - One or more strings to combine into a name + +**Returns:** Kubernetes-compliant name string (lowercase, alphanumeric, hyphens, max 63 chars) + +```yaml +# Create ConfigMap name with hash +name: ${oc_generate_name(metadata.name, "config", parameters.environment)} +# Result: "myapp-config-prod-a1b2c3d4" + +# Handle special characters automatically +name: ${oc_generate_name("My_App", "Service!")} +# Result: "my-app-service-e5f6g7h8" + +# Single argument also gets hash +name: ${oc_generate_name("Hello World!")} +# Result: "hello-world-7f83b165" +``` + +**Notes:** +- The hash is deterministic: same inputs always produce the same output +- Useful for generating unique names for resources created in `forEach` loops +- Ensures names comply with Kubernetes naming requirements + +## oc_hash(string) + +Generate an 8-character FNV-32a hash from an input string. Useful for creating unique identifiers or suffixes. + +**Parameters:** +- `string` - Input string to hash + +**Returns:** 8-character hexadecimal hash string + +```yaml +# Generate hash for volume name uniqueness +volumeName: main-file-mount-${oc_hash(config.mountPath + "/" + config.name)} + +# Use in resource naming +suffix: ${oc_hash(parameters.uniqueKey)} +``` + +**Notes:** +- Hash is deterministic: same input always produces the same output +- Used internally by `oc_generate_name()` to create the hash suffix + +## Usage Examples + +### Complete ComponentType Example + +```yaml +apiVersion: openchoreo.dev/v1alpha1 +kind: ComponentType +metadata: + name: web-service +spec: + workloadType: deployment + + schema: + parameters: + port: "integer | default=8080" + customLabels: "map | default={}" + cpuLimit: "string" + + resources: + - id: deployment + template: + apiVersion: apps/v1 + kind: Deployment + metadata: + name: ${metadata.name} + # Merge platform labels with custom labels + labels: ${oc_merge(metadata.labels, parameters.customLabels)} + spec: + template: + spec: + containers: + - name: app + image: ${workload.containers["main"].image} + resources: + limits: + # Only include cpu if specified + cpu: ${has(parameters.cpuLimit) ? parameters.cpuLimit : oc_omit()} + + # Generate ConfigMaps with unique names + - id: configs + forEach: ${parameters.configFiles} + var: config + template: + apiVersion: v1 + kind: ConfigMap + metadata: + name: ${oc_generate_name(metadata.name, config.name)} +``` + +## Related Resources + +- [Context Variables](./context-variables.md) - Variables available in templates +- [Configuration Helpers](./configuration-helpers.md) - Helper functions for configurations +- [Templating Syntax](../../user-guide/component-types/templating-syntax.md) - Expression syntax and resource control diff --git a/versioned_docs/version-v0.11.x/reference/cel/configuration-helpers.md b/versioned_docs/version-v0.11.x/reference/cel/configuration-helpers.md new file mode 100644 index 0000000..8872a31 --- /dev/null +++ b/versioned_docs/version-v0.11.x/reference/cel/configuration-helpers.md @@ -0,0 +1,538 @@ +--- +title: Configuration Helpers +--- + +# Configuration Helper Functions + +Configuration helpers are CEL extension functions that provide convenient methods to work with the `configurations` object in your templates. They help reduce boilerplate code and make templates more readable and maintainable. + +## Overview + +These helpers simplify working with container configurations, environment variables, and file mounts. All configuration helper functions are available on the `configurations` context object when working with ComponentType templates. + +## Helper Functions Reference + +### toContainerEnvFrom(containerName) + +Generates an `envFrom` array for a single container configuration, creating `configMapRef` and `secretRef` entries based on available environment variables. + +**Parameters:** +- `containerName` - Name of the container (string) + +**Returns:** List of envFrom entries, each containing either: + +| Field | Type | Description | +|-------|------|-------------| +| `configMapRef` | map | Reference to ConfigMap (only present if container has config envs) | +| `secretRef` | map | Reference to Secret (only present if container has secret envs) | + +**Examples:** + +```yaml +# Using helper function +spec: + template: + spec: + containers: + - name: main + image: myapp:latest + envFrom: ${configurations.toContainerEnvFrom("main")} + +# Equivalent manual implementation +envFrom: | + ${(has(configurations["main"].configs.envs) && configurations["main"].configs.envs.size() > 0 ? + [{ + "configMapRef": { + "name": oc_generate_name(metadata.name, "env-configs") + } + }] : []) + + (has(configurations["main"].secrets.envs) && configurations["main"].secrets.envs.size() > 0 ? + [{ + "secretRef": { + "name": oc_generate_name(metadata.name, "env-secrets") + } + }] : [])} + +# Dynamic container name from parameters +envFrom: ${configurations.toContainerEnvFrom(parameters.containerName)} + +# Combine with additional envFrom entries +envFrom: | + ${configurations.toContainerEnvFrom("main") + + [{"configMapRef": {"name": "external-config"}}]} +``` + +### toConfigEnvsByContainer() + +Generates a list of objects for creating ConfigMaps from environment variables. Each object contains the container name, generated resource name, and environment variables. + +**Parameters:** None + +**Returns:** List of objects, each containing: + +| Field | Type | Description | +|-------|------|-------------| +| `container` | string | Name of the container | +| `resourceName` | string | Generated ConfigMap name (componentName-environmentName-containerName-env-configs-hash) | +| `envs` | array | List of environment variable objects with `name` and `value` | + +**Examples:** + +```yaml +# Using helper function +- id: env-config + forEach: ${configurations.toConfigEnvsByContainer()} + var: envConfig + template: + apiVersion: v1 + kind: ConfigMap + metadata: + name: ${envConfig.resourceName} + namespace: ${metadata.namespace} + data: | + ${envConfig.envs.transformMapEntry(index, env, {env.name: env.value})} + +# Equivalent manual implementation +- id: env-config + forEach: | + ${configurations.transformList(containerName, cfg, + { + "container": containerName, + "resourceName": oc_generate_name(metadata.name, containerName, "env-configs"), + "envs": cfg.configs.envs + } + )} + var: envConfig + template: + apiVersion: v1 + kind: ConfigMap + metadata: + name: ${envConfig.resourceName} + namespace: ${metadata.namespace} + data: | + ${envConfig.envs.transformMapEntry(index, env, {env.name: env.value})} +``` + +**Notes:** +- Only returns entries for containers that have config environment variables +- Skips containers with no config envs or only secret envs +- Generated resource names include container name and a hash for uniqueness + +### toSecretEnvsByContainer() + +Generates a list of objects for creating ExternalSecrets from secret environment variables. Each object contains the container name, generated resource name, and secret environment variables. + +**Parameters:** None + +**Returns:** List of objects, each containing: + +| Field | Type | Description | +|-------|------|-------------| +| `container` | string | Name of the container | +| `resourceName` | string | Generated ExternalSecret name (componentName-environmentName-containerName-env-secrets-hash) | +| `envs` | array | List of secret environment variable objects with `name` and `remoteRef` | + +**Examples:** + +```yaml +# Using helper function +- id: secret-env-external + forEach: ${configurations.toSecretEnvsByContainer()} + var: secretEnv + template: + apiVersion: external-secrets.io/v1 + kind: ExternalSecret + metadata: + name: ${secretEnv.resourceName} + namespace: ${metadata.namespace} + spec: + refreshInterval: 15s + secretStoreRef: + name: ${dataplane.secretStore} + kind: ClusterSecretStore + target: + name: ${secretEnv.resourceName} + creationPolicy: Owner + data: | + ${secretEnv.envs.map(secret, { + "secretKey": secret.name, + "remoteRef": { + "key": secret.remoteRef.key, + "property": has(secret.remoteRef.property) ? secret.remoteRef.property : oc_omit() + } + })} + +# Equivalent manual implementation +- id: secret-env-external + forEach: | + ${configurations.transformList(containerName, cfg, + { + "container": containerName, + "resourceName": oc_generate_name(metadata.name, containerName, "env-secrets"), + "envs": cfg.secrets.envs + } + )} + var: secretEnv + template: + apiVersion: external-secrets.io/v1 + kind: ExternalSecret + metadata: + name: ${secretEnv.resourceName} + namespace: ${metadata.namespace} + spec: + refreshInterval: 15s + secretStoreRef: + name: ${dataplane.secretStore} + kind: ClusterSecretStore + target: + name: ${secretEnv.resourceName} + creationPolicy: Owner + data: | + ${secretEnv.envs.map(secret, { + "secretKey": secret.name, + "remoteRef": { + "key": secret.remoteRef.key, + "property": has(secret.remoteRef.property) ? secret.remoteRef.property : oc_omit() + } + })} +``` + +**Notes:** +- Only returns entries for containers that have secret environment variables +- Skips containers with no secret envs or only config envs +- Generated resource names include container name and a hash for uniqueness + +### toConfigFileList() + +Flattens `configs.files` from all containers into a single list. Each file includes a generated `resourceName` for creating ConfigMaps. + +**Parameters:** None + +**Returns:** List of file objects, each containing: + +| Field | Type | Description | +|-------|------|-------------| +| `name` | string | File name | +| `mountPath` | string | Mount path | +| `value` | string | File content (empty string if using remoteRef) | +| `resourceName` | string | Generated Kubernetes-compliant resource name (componentName-environmentName-containerName-config-fileName) | +| `remoteRef` | map | Remote reference (only present if the file uses a secret reference) | + +**Examples:** + +```yaml +# Generate a ConfigMap for each config file +- id: file-configs + forEach: ${configurations.toConfigFileList()} + var: config + template: + apiVersion: v1 + kind: ConfigMap + metadata: + name: ${config.resourceName} + namespace: ${metadata.namespace} + data: + ${config.name}: | + ${config.value} +``` + +**Equivalent CEL expression:** + +If you need additional fields (e.g., `container` name) or different behavior, use the underlying data directly: + +```yaml +forEach: | + ${configurations.transformList(containerName, cfg, + cfg.configs.files.map(f, oc_merge(f, { + "container": containerName, + "resourceName": oc_generate_name(metadata.name, containerName, "config", f.name.replace(".", "-")) + })) + ).flatten()} +``` + +### toSecretFileList() + +Flattens `secrets.files` from all containers into a single list. Each file includes a generated `resourceName` for creating Secrets or ExternalSecrets. + +**Parameters:** None + +**Returns:** List of file objects, each containing: + +| Field | Type | Description | +|-------|------|-------------| +| `name` | string | File name | +| `mountPath` | string | Mount path | +| `value` | string | File content (empty string if using remoteRef) | +| `resourceName` | string | Generated Kubernetes-compliant resource name (componentName-environmentName-containerName-secret-fileName) | +| `remoteRef` | map | Remote reference (only present if the file uses a secret reference) | + +**Examples:** + +```yaml +# Generate ExternalSecrets for secret files +- id: file-secrets + forEach: ${configurations.toSecretFileList()} + var: secret + includeWhen: ${has(secret.remoteRef)} + template: + apiVersion: external-secrets.io/v1beta1 + kind: ExternalSecret + metadata: + name: ${secret.resourceName} + namespace: ${metadata.namespace} + spec: + secretStoreRef: + name: ${dataplane.secretStore} + kind: ClusterSecretStore + target: + name: ${secret.resourceName} + creationPolicy: Owner + data: + - secretKey: ${secret.name} + remoteRef: + key: ${secret.remoteRef.key} + property: ${secret.remoteRef.property} + +# Generate Secrets for files with inline values +- id: inline-file-secrets + forEach: ${configurations.toSecretFileList()} + var: secret + includeWhen: ${!has(secret.remoteRef) && secret.value != ""} + template: + apiVersion: v1 + kind: Secret + metadata: + name: ${secret.resourceName} + namespace: ${metadata.namespace} + data: + ${secret.name}: ${base64.encode(secret.value)} +``` + +**Equivalent CEL expression:** + +```yaml +forEach: | + ${configurations.transformList(containerName, cfg, + cfg.secrets.files.map(f, oc_merge(f, { + "container": containerName, + "resourceName": oc_generate_name(metadata.name, containerName, "secret", f.name.replace(".", "-")) + })) + ).flatten()} +``` + +### toContainerVolumeMounts(containerName) + +Generates a `volumeMounts` array for a single container's config and secret files. + +**Parameters:** +- `containerName` - Name of the container (string) + +**Returns:** List of volumeMount entries, each containing: + +| Field | Type | Description | +|-------|------|-------------| +| `name` | string | Volume name (containerName-file-mount-hash format) | +| `mountPath` | string | Full mount path (mountPath + "/" + filename) | +| `subPath` | string | Filename to mount as subPath | + +**Examples:** + +```yaml +# Using helper function +spec: + template: + spec: + containers: + - name: main + image: myapp:latest + volumeMounts: ${configurations.toContainerVolumeMounts("main")} + +# Equivalent manual implementation +volumeMounts: | + ${has(configurations["main"].configs.files) && configurations["main"].configs.files.size() > 0 || has(configurations["main"].secrets.files) && configurations["main"].secrets.files.size() > 0 ? + (has(configurations["main"].configs.files) && configurations["main"].configs.files.size() > 0 ? + configurations["main"].configs.files.map(f, { + "name": "main-file-mount-"+oc_hash(f.mountPath+"/"+f.name), + "mountPath": f.mountPath+"/"+f.name , + "subPath": f.name + }) : []) + + (has(configurations["main"].secrets.files) && configurations["main"].secrets.files.size() > 0 ? + configurations["main"].secrets.files.map(f, { + "name": "main-file-mount-"+oc_hash(f.mountPath+"/"+f.name), + "mountPath": f.mountPath+"/"+f.name, + "subPath": f.name + }) : []) + : oc_omit()} + +# Dynamic container name +volumeMounts: ${configurations.toContainerVolumeMounts(parameters.containerName)} + +# Combine with additional volume mounts +volumeMounts: | + ${configurations.toContainerVolumeMounts("main") + + [{"name": "cache", "mountPath": "/cache"}]} +``` + +### toVolumes() + +Generates a `volumes` array for all containers' config and secret files. + +**Parameters:** None + +**Returns:** List of volume entries, each containing: + +| Field | Type | Description | +|-------|------|-------------| +| `name` | string | Volume name (generated using hash of mountPath and filename) | +| `configMap` | map | ConfigMap volume source (only present for config files) | +| `secret` | map | Secret volume source (only present for secret files) | + +**Examples:** + +```yaml +# Using helper function +spec: + template: + spec: + containers: + - name: main + image: myapp:latest + volumeMounts: ${configurations.toContainerVolumeMounts("main")} + volumes: ${configurations.toVolumes()} + +# Equivalent manual implementation +volumes: | + ${has(configurations["main"].configs.files) && configurations["main"].configs.files.size() > 0 || has(configurations["main"].secrets.files) && configurations["main"].secrets.files.size() > 0 ? + (has(configurations["main"].configs.files) && configurations["main"].configs.files.size() > 0 ? + configurations["main"].configs.files.map(f, { + "name": "file-mount-"+oc_hash(f.mountPath+"/"+f.name), + "configMap": { + "name": oc_generate_name(metadata.name, "config", f.name).replace(".", "-") + } + }) : []) + + (has(configurations["main"].secrets.files) && configurations["main"].secrets.files.size() > 0 ? + configurations["main"].secrets.files.map(f, { + "name": "file-mount-"+oc_hash(f.mountPath+"/"+f.name), + "secret": { + "secretName": oc_generate_name(metadata.name, "secret", f.name).replace(".", "-") + } + }) : []) + : oc_omit()} + +# Combine with inline volumes +volumes: | + ${configurations.toVolumes() + + [{"name": "extra-volume", "emptyDir": {}}]} +``` + +## Common Usage Patterns + +### Complete Deployment with Configurations + +```yaml +spec: + workloadType: deployment + 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: ${oc_merge(metadata.labels, metadata.podSelectors)} + spec: + containers: + - name: main + image: ${workload.containers.main.image} + envFrom: ${configurations.toContainerEnvFrom("main")} + volumeMounts: ${configurations.toContainerVolumeMounts("main")} + volumes: ${configurations.toVolumes()} + + # Generate ConfigMaps for environment variables + - id: env-configs + forEach: ${configurations.toConfigEnvsByContainer()} + var: envConfig + template: + apiVersion: v1 + kind: ConfigMap + metadata: + name: ${envConfig.resourceName} + namespace: ${metadata.namespace} + data: | + ${envConfig.envs.transformMapEntry(i, e, {e.name: e.value})} + + # Generate ExternalSecrets for secret environment variables + - id: env-secrets + forEach: ${configurations.toSecretEnvsByContainer()} + var: secretEnv + template: + apiVersion: external-secrets.io/v1 + kind: ExternalSecret + metadata: + name: ${secretEnv.resourceName} + namespace: ${metadata.namespace} + spec: + refreshInterval: 15s + secretStoreRef: + name: ${dataplane.secretStore} + kind: ClusterSecretStore + target: + name: ${secretEnv.resourceName} + creationPolicy: Owner + data: | + ${secretEnv.envs.map(e, { + "secretKey": e.name, + "remoteRef": { + "key": e.remoteRef.key, + "property": has(e.remoteRef.property) ? e.remoteRef.property : oc_omit() + } + })} + + # Generate ConfigMaps for config files + - id: config-files + forEach: ${configurations.toConfigFileList()} + var: config + template: + apiVersion: v1 + kind: ConfigMap + metadata: + name: ${config.resourceName} + namespace: ${metadata.namespace} + data: + ${config.name}: | + ${config.value} + + # Generate ExternalSecrets for secret files + - id: secret-files + forEach: ${configurations.toSecretFileList()} + var: secret + includeWhen: ${has(secret.remoteRef)} + template: + apiVersion: external-secrets.io/v1beta1 + kind: ExternalSecret + metadata: + name: ${secret.resourceName} + namespace: ${metadata.namespace} + spec: + secretStoreRef: + name: ${dataplane.secretStore} + kind: ClusterSecretStore + target: + name: ${secret.resourceName} + creationPolicy: Owner + data: + - secretKey: ${secret.name} + remoteRef: + key: ${secret.remoteRef.key} + property: ${secret.remoteRef.property} +``` + +## See Also +- [ComponentType API Reference](../api/platform/componenttype.md) - ComponentType resource documentation diff --git a/versioned_docs/version-v0.11.x/reference/cel/context-variables.md b/versioned_docs/version-v0.11.x/reference/cel/context-variables.md new file mode 100644 index 0000000..bf30635 --- /dev/null +++ b/versioned_docs/version-v0.11.x/reference/cel/context-variables.md @@ -0,0 +1,272 @@ +--- +title: Context Variables +description: Variables available in ComponentType and Trait templates +--- + +# Context Variables + +This reference documents all context variables available in ComponentType and Trait templates. These variables provide access to component metadata, parameters, workload specifications, and platform configuration. + +## ComponentType Variables + +The following variables are available in ComponentType resource templates. + +### metadata + +Platform-computed metadata for resource generation. + +| Field | Type | Description | +|-------|------|-------------| +| `metadata.name` | string | Base name for generated resources (e.g., `my-service-dev-a1b2c3d4`) | +| `metadata.namespace` | string | Target namespace for resources | +| `metadata.componentName` | string | Name of the component | +| `metadata.componentUID` | string | Unique identifier of the component | +| `metadata.projectName` | string | Name of the project | +| `metadata.projectUID` | string | Unique identifier of the project | +| `metadata.environmentName` | string | Name of the environment (e.g., `development`, `production`) | +| `metadata.environmentUID` | string | Unique identifier of the environment | +| `metadata.dataPlaneName` | string | Name of the data plane | +| `metadata.dataPlaneUID` | string | Unique identifier of the data plane | +| `metadata.labels` | map | Common labels to add to all resources | +| `metadata.annotations` | map | Common annotations to add to all resources | +| `metadata.podSelectors` | map | Platform-injected selectors for pod identity | + +**Usage:** + +```yaml +metadata: + name: ${metadata.name} + namespace: ${metadata.namespace} + labels: ${metadata.labels} +spec: + selector: + matchLabels: ${metadata.podSelectors} +``` + +### parameters + +Component parameters from `Component.spec.parameters` with schema defaults applied. Use for static configuration that doesn't change across environments. + +```yaml +# Access parameters defined in schema.parameters +replicas: ${parameters.replicas} +port: ${parameters.port} + +# Nested parameters +database: + host: ${parameters.database.host} + port: ${parameters.database.port} +``` + +### envOverrides + +Environment-specific overrides from `ReleaseBinding.spec.componentTypeEnvOverrides` with schema defaults applied. Use for values that vary per environment (resources, replicas, etc.). + +```yaml +# Access environment-specific values +replicas: ${envOverrides.replicas} +resources: + limits: + cpu: ${envOverrides.resources.cpu} + memory: ${envOverrides.resources.memory} +``` + +### workload + +Workload specification from the Workload resource. + +| Field | Type | Description | +|-------|------|-------------| +| `workload.containers` | map | Map of container configurations keyed by container name | +| `workload.containers[name].image` | string | Container image | +| `workload.containers[name].command` | []string | Container command | +| `workload.containers[name].args` | []string | Container arguments | + +**Usage:** + +```yaml +containers: + - name: app + image: ${workload.containers["main"].image} + command: ${workload.containers["main"].command} + args: ${workload.containers["main"].args} + +# Dynamic container name from parameters +image: ${workload.containers[parameters.containerName].image} +``` + +### configurations + +Configuration and secret references extracted from workload, keyed by container name. + +| Field | Type | Description | +|-------|------|-------------| +| `configurations[name].configs.envs` | []object | Environment variable configs (each has `name`, `value`) | +| `configurations[name].configs.files` | []object | File configs (each has `name`, `mountPath`, `value`) | +| `configurations[name].secrets.envs` | []object | Secret env vars (each has `name`, `value`, `remoteRef`) | +| `configurations[name].secrets.files` | []object | Secret files (each has `name`, `mountPath`, `remoteRef`) | + +The `remoteRef` object contains: `key`, `property` (optional), `version` (optional). + +**Usage:** + +```yaml +# Access config envs for a container +env: | + ${configurations["main"].configs.envs.map(e, {"name": e.name, "value": e.value})} + +# Check if container has config files +includeWhen: ${has(configurations["main"].configs.files) && configurations["main"].configs.files.size() > 0} +``` + +See [Configuration Helpers](./configuration-helpers.md) for helper functions that simplify working with configurations. + +### dataplane + +Data plane configuration. + +| Field | Type | Description | +|-------|------|-------------| +| `dataplane.secretStore` | string | Name of the ClusterSecretStore for external secrets | +| `dataplane.publicVirtualHost` | string | Public virtual host for external access | + +**Usage:** + +```yaml +# ExternalSecret configuration +spec: + secretStoreRef: + name: ${dataplane.secretStore} + kind: ClusterSecretStore + +# HTTPRoute hostname +hostnames: + - ${metadata.name}.${dataplane.publicVirtualHost} +``` + +## Trait Variables + +Traits have access to all the same variables as ComponentTypes, plus trait-specific variables. + +### trait + +Trait-specific metadata. + +| Field | Type | Description | +|-------|------|-------------| +| `trait.name` | string | Name of the trait (e.g., `persistent-volume`) | +| `trait.instanceName` | string | Unique instance name within the component (e.g., `data-storage`) | + +**Usage:** + +```yaml +# Use trait instance name for resource naming +metadata: + name: ${metadata.name}-${trait.instanceName} + +# Use trait name in labels +labels: + trait: ${trait.name} + instance: ${trait.instanceName} +``` + +### parameters (Traits) + +Trait instance parameters from `Component.spec.traits[].parameters` with schema defaults applied. + +```yaml +# Access trait-specific parameters +volumeMounts: + - name: ${parameters.volumeName} + mountPath: ${parameters.mountPath} +``` + +### envOverrides (Traits) + +Environment-specific overrides from `ReleaseBinding.spec.traitOverrides[instanceName]` with schema defaults applied. + +```yaml +# Access environment-specific trait values +resources: + requests: + storage: ${envOverrides.size} +storageClassName: ${envOverrides.storageClass} +``` + +## Variable Availability Summary + +| Variable | ComponentType | Trait creates | Trait patches | +|----------|---------------|---------------|---------------| +| `metadata.*` | Yes | Yes | Yes | +| `parameters` | Yes | Yes | Yes | +| `envOverrides` | Yes | Yes | Yes | +| `workload.*` | Yes | No | No | +| `configurations.*` | Yes | No | No | +| `dataplane.*` | Yes | Yes | Yes | +| `trait.*` | No | Yes | Yes | +| `resource` (patch target) | No | No | Yes (in `where`) | + +## Examples + +### ComponentType Using All Variables + +```yaml +apiVersion: openchoreo.dev/v1alpha1 +kind: ComponentType +metadata: + name: web-service +spec: + workloadType: deployment + resources: + - id: deployment + template: + apiVersion: apps/v1 + kind: Deployment + metadata: + name: ${metadata.name} + namespace: ${metadata.namespace} + labels: ${metadata.labels} + spec: + replicas: ${envOverrides.replicas} + selector: + matchLabels: ${metadata.podSelectors} + template: + metadata: + labels: ${metadata.podSelectors} + spec: + containers: + - name: app + image: ${workload.containers["main"].image} + ports: + - containerPort: ${parameters.port} + envFrom: ${configurations.toContainerEnvFrom("main")} +``` + +### Trait Using Trait-Specific Variables + +```yaml +apiVersion: openchoreo.dev/v1alpha1 +kind: Trait +metadata: + name: persistent-volume +spec: + creates: + - template: + apiVersion: v1 + kind: PersistentVolumeClaim + metadata: + name: ${metadata.name}-${trait.instanceName} + namespace: ${metadata.namespace} + spec: + accessModes: ["ReadWriteOnce"] + storageClassName: ${envOverrides.storageClass} + resources: + requests: + storage: ${envOverrides.size} +``` + +## Related Resources + +- [Built-in Functions](./built-in-functions.md) - Functions available in templates +- [Configuration Helpers](./configuration-helpers.md) - Helper functions for configurations +- [Templating Syntax](../../user-guide/component-types/templating-syntax.md) - Expression syntax and resource control diff --git a/versioned_docs/version-v0.11.x/reference/changelog.md b/versioned_docs/version-v0.11.x/reference/changelog.md new file mode 100644 index 0000000..d94bb7b --- /dev/null +++ b/versioned_docs/version-v0.11.x/reference/changelog.md @@ -0,0 +1,28 @@ +--- +title: Changelog & Release Notes +unlisted: true +--- + +# Changelog & Release Notes + +This document tracks all notable changes, new features, breaking changes, and important updates across OpenChoreo releases. + +## Current Release + +### [v0.3.0] - 2025-07-31 + +**[📋 View Full Release Notes](https://github.com/openchoreo/openchoreo/releases/tag/v0.3.0)** + +--- + +## Previous Releases + +### [v0.2.0] - 2025-06-06 + +**[📋 View Full Release Notes](https://github.com/openchoreo/openchoreo/releases/tag/v0.2.0)** + +--- + +## Upcoming Releases and Release Schedule + +Track our development progress and upcoming features on our [GitHub Project Board](https://github.com/orgs/openchoreo/projects/1). diff --git a/versioned_docs/version-v0.11.x/reference/cli-reference.md b/versioned_docs/version-v0.11.x/reference/cli-reference.md new file mode 100644 index 0000000..9dcfdc1 --- /dev/null +++ b/versioned_docs/version-v0.11.x/reference/cli-reference.md @@ -0,0 +1,471 @@ +# CLI Reference + +The `occ` (OpenChoreo CLI) is a command-line interface tool for interacting with OpenChoreo. It provides commands to manage organizations, projects, components, deployments, and other OpenChoreo resources. + +## Global Options + +All commands support the following global options through context configuration: + +- `--organization` - Organization name +- `--project` - Project name +- `--component` - Component name +- `--environment` - Environment name +- `--dataplane` - Data plane name + +These can be set in a configuration context to avoid repeating them in every command. See the [config](#config) command for details. + +## Commands + +### login + +Login to OpenChoreo CLI. + +**Usage:** +```bash +occ login [flags] +``` + +**Flags:** +- `--client-credentials` - Use OAuth2 client credentials flow for authentication +- `--client-id` - OAuth2 client ID for service account authentication +- `--client-secret` - OAuth2 client secret for service account authentication +- `--credential` - Name to save the credential as in config +- `--url` - Control plane URL to update + +**Examples:** +```bash +# Interactive login (default PKCE flow) +occ login + +# Service account login with client credentials +occ login --client-credentials --client-id --client-secret + +# Login to a specific control plane URL +occ login --url https://api.openchoreo.example.com +``` + +--- + +### logout + +Logout from OpenChoreo CLI. + +**Usage:** +```bash +occ logout +``` + +**Examples:** +```bash +occ logout +``` + +--- + +### version + +Print version information for both the CLI client and the OpenChoreo server. + +**Usage:** +```bash +occ version +``` + +**Examples:** +```bash +occ version +``` + +--- + +### apply + +Apply a configuration file to create or update OpenChoreo resources. + +**Usage:** +```bash +occ apply -f +``` + +**Flags:** +- `-f, --file` - Path to the YAML file containing resource definitions + +**Examples:** +```bash +# Apply a single resource file +occ apply -f organization.yaml + +# Apply a component configuration +occ apply -f my-component.yaml +``` + +--- + +### create + +Create OpenChoreo resources like projects, components, and workloads. + +**Usage:** +```bash +occ create [flags] +``` + +#### create workload + +Create a workload from a workload descriptor file. + +**Usage:** +```bash +occ create workload [flags] +``` + +**Flags:** +- `--name` - Name of the workload +- `--organization` - Organization name +- `--project` - Project name +- `--component` - Component name +- `--descriptor` - Path to the workload descriptor file +- `--image` - Docker image URL +- `-o, --output` - Output file path for the generated workload resource + +**Examples:** +```bash +# Create workload from descriptor +occ create workload --descriptor workload.yaml --organization acme-corp \ + --project online-store --component product-catalog --image myimage:latest + +# Create workload and save to file +occ create workload --descriptor workload.yaml --organization acme-corp \ + --project online-store --component product-catalog --image myimage:latest \ + --output workload-cr.yaml +``` + +--- + +### delete + +Delete OpenChoreo resources by file names. + +**Usage:** +```bash +occ delete -f [flags] +``` + +**Flags:** +- `-f, --file` - Path to the YAML file containing resources to delete +- `-w, --wait` - Wait for the deletion to complete + +**Examples:** +```bash +# Delete resources from a file +occ delete -f resources.yaml + +# Delete and wait for completion +occ delete -f resources.yaml --wait +``` + +--- + +### scaffold + +Generate scaffolded resource YAML files from existing CRDs. + +**Usage:** +```bash +occ scaffold [flags] +``` + +#### scaffold component + +Scaffold a Component YAML from ComponentType and Traits. + +**Usage:** +```bash +occ scaffold component [flags] +``` + +**Flags:** +- `--name` - Component name +- `--type` - Component type in format `workloadType/componentTypeName` (e.g., `deployment/web-app`) +- `--traits` - Comma-separated list of trait names to include +- `--workflow` - ComponentWorkflow name to include in the scaffold +- `--organization` - Organization name (can be omitted if set in context) +- `--project` - Project name (can be omitted if set in context) +- `-o, --output-file` - Write output to specified file instead of stdout +- `--skip-comments` - Skip section headers and field description comments for minimal output +- `--skip-optional` - Skip optional fields without defaults + +**Examples:** +```bash +# Scaffold a basic component +occ scaffold component --name my-app --type deployment/web-app + +# Scaffold with traits +occ scaffold component --name my-app --type deployment/web-app --traits storage,ingress + +# Scaffold with workflow +occ scaffold component --name my-app --type deployment/web-app --workflow docker-build + +# Output to file +occ scaffold component --name my-app --type deployment/web-app -o my-app.yaml + +# Minimal output without comments +occ scaffold component --name my-app --type deployment/web-app --skip-comments --skip-optional +``` + +--- + +### config + +Manage configuration contexts that store default values (e.g., organization, project, component) for occ commands. + +**Usage:** +```bash +occ config [flags] +``` + +#### config get-contexts + +List all available configuration contexts. + +**Usage:** +```bash +occ config get-contexts +``` + +**Examples:** +```bash +# Show all configuration contexts +occ config get-contexts +``` + +#### config set-context + +Create or update a configuration context. + +**Usage:** +```bash +occ config set-context [flags] +``` + +**Flags:** +- `--organization` - Organization name stored in this configuration context +- `--project` - Project name stored in this configuration context +- `--component` - Component name stored in this configuration context +- `--dataplane` - Data plane reference stored in this configuration context +- `--environment` - Environment name stored in this configuration context +- `--mode` - Context mode: `api-server` (default) or `file-system` +- `--root-directory-path` - Root directory path for file-system mode (defaults to current directory) + +**Examples:** +```bash +# Set a configuration context named acme-corp-context +occ config set-context acme-corp-context --organization acme-corp \ + --project online-store --environment dev + +# Set a file-system mode context +occ config set-context local-dev --mode file-system --root-directory-path /path/to/resources +``` + +#### config use-context + +Switch to a specified configuration context. + +**Usage:** +```bash +occ config use-context +``` + +**Examples:** +```bash +# Switch to the configuration context named acme-corp-context +occ config use-context acme-corp-context +``` + +#### config current-context + +Display the currently active configuration context. + +**Usage:** +```bash +occ config current-context +``` + +**Examples:** +```bash +# Display the currently active configuration context +occ config current-context +``` + +#### config set-control-plane + +Configure OpenChoreo API server connection. + +**Usage:** +```bash +occ config set-control-plane [flags] +``` + +**Flags:** +- `--name` - Name of the control plane configuration +- `--url` - OpenChoreo API server endpoint URL + +**Examples:** +```bash +# Set remote control plane endpoint +occ config set-control-plane --name production --url https://api.openchoreo.example.com + +# Set local control plane (for development) +occ config set-control-plane --name local --url http://localhost:8080 +``` + +--- + +### component-release + +:::note +This command only works in file-system mode. Set your context mode to `file-system` before using this command. +::: + +**Usage:** +```bash +occ component-release [flags] +``` + +#### component-release generate + +Generate ComponentRelease resources from Component, Workload, ComponentType, and Trait definitions. + +**Usage:** +```bash +occ component-release generate [flags] +``` + +**Flags:** +- `--all` - Process all resources +- `--project` - Project name +- `--component` - Component name (requires `--project`) +- `--output-path` - Custom output directory path +- `--dry-run` - Preview changes without writing files + +**Examples:** +```bash +# Generate releases for all components +occ component-release generate --all + +# Generate releases for all components in a specific project +occ component-release generate --project demo-project + +# Generate release for a specific component (requires --project and --output-path) +occ component-release generate --project demo-project --component greeter-service \ + --output-path ./releases + +# Dry run (preview without writing) +occ component-release generate --all --dry-run + +# Custom output path +occ component-release generate --all --output-path /custom/path +``` + +--- + +### release-binding + +:::note +This command only works in file-system mode. Set your context mode to `file-system` before using this command. +::: + +**Usage:** +```bash +occ release-binding [flags] +``` + +#### release-binding generate + +Generate ReleaseBinding resources that bind component releases to environments. + +**Usage:** +```bash +occ release-binding generate [flags] +``` + +**Flags:** +- `-e, --target-env` - Target environment for the release binding (required) +- `--use-pipeline` - Deployment pipeline name for environment validation (required) +- `--all` - Process all resources +- `--project` - Project name +- `--component` - Component name (requires `--project`) +- `--component-release` - Explicit component release name (only valid with `--project` and `--component`) +- `--output-path` - Custom output directory path +- `--dry-run` - Preview changes without writing files + +**Examples:** +```bash +# Generate bindings for all components in development environment +occ release-binding generate --target-env development --use-pipeline default-pipeline --all + +# Generate bindings for all components in a specific project +occ release-binding generate --target-env staging --use-pipeline default-pipeline \ + --project demo-project + +# Generate binding for a specific component +occ release-binding generate --target-env production --use-pipeline default-pipeline \ + --project demo-project --component greeter-service + +# Generate binding with explicit component release +occ release-binding generate --target-env production --use-pipeline default-pipeline \ + --project demo-project --component greeter-service \ + --component-release greeter-service-20251222-3 + +# Dry run (preview without writing) +occ release-binding generate --target-env development --use-pipeline default-pipeline \ + --all --dry-run + +# Custom output path +occ release-binding generate --target-env development --use-pipeline default-pipeline \ + --all --output-path /custom/path +``` + +--- + +## Configuration + +The CLI stores its configuration in `~/.occ/config.yaml`. This file contains: + +- **Control planes**: API server endpoints and connection details +- **Credentials**: Authentication tokens and client credentials +- **Contexts**: Named sets of default values for commands + +### Configuration File Structure + +```yaml +currentContext: my-context +controlplanes: + - name: production + url: https://api.openchoreo.example.com +credentials: + - name: my-creds + clientId: + clientSecret: + token: + refreshToken: + authMethod: pkce # or "client_credentials" +contexts: + - name: my-context + controlplane: production + credentials: my-creds + organization: acme-corp + project: online-store + component: product-catalog + environment: development + mode: api-server # or "file-system" + rootDirectoryPath: /path/to/resources # for file-system mode +``` + +### Modes + +The CLI supports two modes: + +1. **API Server Mode** (`api-server`): Connects to an OpenChoreo API server to manage resources remotely. This is the default mode. + +2. **File System Mode** (`file-system`): Works with resources stored as YAML files in a directory structure. Useful for GitOps workflows and local development. diff --git a/versioned_docs/version-v0.11.x/reference/configuration-schema.md b/versioned_docs/version-v0.11.x/reference/configuration-schema.md new file mode 100644 index 0000000..23e81c7 --- /dev/null +++ b/versioned_docs/version-v0.11.x/reference/configuration-schema.md @@ -0,0 +1,872 @@ +--- +title: Configuration Schema +unlisted: true +--- + +# Configuration Schema + +This reference provides the complete schema for all OpenChoreo configuration options, including Custom Resource Definitions (CRDs), Helm values, and environment variables. + +## Platform Resources + +OpenChoreo follows a hierarchical platform model where Organizations contain Projects, which reference DeploymentPipelines that define promotion paths between Environments deployed on DataPlanes. + +### Organization CRD Schema + +```yaml +apiVersion: openchoreo.dev/v1alpha1 +kind: Organization +metadata: + name: string # Required: Organization name (cluster-scoped) +spec: {} # Empty spec - used for namespace provisioning + +status: + namespace: string # Provisioned namespace for the organization + conditions: # Standard Kubernetes conditions + - type: string + status: enum # "True" | "False" | "Unknown" + reason: string + message: string + lastTransitionTime: string + observedGeneration: integer # Generation tracking +``` + +### Project CRD Schema + +```yaml +apiVersion: openchoreo.dev/v1alpha1 +kind: Project +metadata: + name: string # Required: Project name (DNS-1123 compliant) + namespace: string # Required: Organization namespace +spec: + deploymentPipelineRef: string # Required: Reference to deployment pipeline + +status: + conditions: # Standard Kubernetes conditions + - type: string + status: enum # "True" | "False" | "Unknown" + reason: string + message: string + lastTransitionTime: string + observedGeneration: integer # Generation tracking +``` + +### Environment CRD Schema + +```yaml +apiVersion: openchoreo.dev/v1alpha1 +kind: Environment +metadata: + name: string # Required: Environment name + namespace: string # Required: Organization namespace +spec: + dataPlaneRef: string # Optional: Reference to data plane + isProduction: boolean # Optional: Production environment flag + gateway: # Optional: Gateway configuration + dnsPrefix: string # DNS prefix for the environment + security: # Security configuration + remoteJwks: # Remote JWKS configuration + uri: string # Required: JWKS URI + +status: + conditions: # Standard Kubernetes conditions + - type: string + status: enum + reason: string + message: string + lastTransitionTime: string + observedGeneration: integer +``` + +### DataPlane CRD Schema + +```yaml +apiVersion: openchoreo.dev/v1alpha1 +kind: DataPlane +metadata: + name: string # Required: DataPlane name + namespace: string # Required: Organization namespace +spec: + # API Gateway Configuration + gateway: # Required: Gateway configuration + organizationVirtualHost: string # Required: Organization virtual host + publicVirtualHost: string # Required: Public virtual host + + # Kubernetes Cluster Configuration + kubernetesCluster: # Required: Target cluster + name: string # Required: Cluster name + credentials: # Required: Authentication details + apiServerURL: string # Required: Kubernetes API server URL + caCert: string # Required: Base64-encoded CA certificate + clientCert: string # Required: Base64-encoded client certificate + clientKey: string # Required: Base64-encoded client private key + + # Container Registry Configuration + registry: # Required: Registry configuration + prefix: string # Required: Registry domain and namespace + secretRef: string # Optional: Registry credentials secret + + # Observer API Integration + observer: # Optional: Observer API + url: string # Required: Observer API base URL + authentication: # Required: Authentication + basicAuth: # Required: Basic auth credentials + username: string # Required: Username + password: string # Required: Password + +status: + conditions: # Standard Kubernetes conditions + - type: string + status: enum + reason: string + message: string + lastTransitionTime: string + observedGeneration: integer +``` + +### BuildPlane CRD Schema + +```yaml +apiVersion: openchoreo.dev/v1alpha1 +kind: BuildPlane +metadata: + name: string # Required: BuildPlane name + namespace: string # Required: Organization namespace +spec: + # Kubernetes Cluster for Build Workloads + kubernetesCluster: # Required: Build cluster + name: string # Required: Cluster name + credentials: # Required: Same structure as DataPlane + apiServerURL: string + caCert: string + clientCert: string + clientKey: string + + # Observer API Integration (Optional) + observer: # Optional: Same structure as DataPlane + url: string + authentication: + basicAuth: + username: string + password: string + +status: {} # Minimal status implementation +``` + +### DeploymentPipeline CRD Schema + +```yaml +apiVersion: openchoreo.dev/v1alpha1 +kind: DeploymentPipeline +metadata: + name: string # Required: Pipeline name + namespace: string # Required: Organization namespace +spec: + promotionPaths: # Optional: Environment promotion paths + - sourceEnvironmentRef: string # Required: Source environment + targetEnvironmentRefs: # Required: Target environments + - name: string # Required: Target environment name + requiresApproval: boolean # Optional: Approval required flag + isManualApprovalRequired: boolean # Optional: Manual approval flag + +status: + conditions: # Standard Kubernetes conditions + - type: string + status: enum + reason: string + message: string + lastTransitionTime: string + observedGeneration: integer +``` + +## Application Resources + +OpenChoreo supports different component types through a layered architecture: Component defines deployable units with integrated build capabilities, while runtime abstractions (Services, WebApplications, ScheduledTasks, APIs) provide specific deployment patterns. + +### Component CRD Schema + +```yaml +apiVersion: openchoreo.dev/v1alpha1 +kind: Component +metadata: + name: string # Required: Component name + namespace: string # Required: Project namespace +spec: + # Build Configuration + build: # Optional: Build configuration for the component + repository: # Source repository configuration + appPath: string # Optional: Path to application within repository (default: ".") + revision: # Default revision configuration + branch: string # Git branch name + tag: string # Git tag (mutually exclusive with branch) + commit: string # Git commit SHA (mutually exclusive with branch/tag) + url: string # Required: Git repository URL + authentication: # Optional: Git authentication + secretRef: string # Secret reference for Git credentials + + # Build Process Configuration + buildPlan: # Build execution plan + type: string # Build type (e.g., "buildpacks", "dockerfile") + dockerfile: # Dockerfile-based builds + path: string # Path to Dockerfile + context: string # Build context directory + buildpacks: # Buildpacks-based builds + builder: string # Builder image to use + env: # Build-time environment variables + - name: string + value: string + + # Runtime Configuration + workloadSpec: # Workload specification + # Runtime workload configuration + replicas: integer # Number of replicas + resources: # Resource requirements + requests: + cpu: string + memory: string + limits: + cpu: string + memory: string + +status: + conditions: # Standard Kubernetes conditions + - type: string + status: enum # "True" | "False" | "Unknown" + reason: string + message: string + lastTransitionTime: string + observedGeneration: integer +``` + +### Build CRD Schema + +```yaml +apiVersion: openchoreo.dev/v1alpha1 +kind: Build +metadata: + name: string # Required: Build name + namespace: string # Required: Project namespace +spec: + # Owner Reference + owner: # Required: Owner information + projectName: string # Required: Project name (minLength: 1) + componentName: string # Required: Component name (minLength: 1) + + # Build Configuration + repository: # Source repository for the build + url: string # Git repository URL + revision: # Specific revision to build + branch: string # Git branch + tag: string # Git tag + commit: string # Git commit SHA + appPath: string # Path within repository + authentication: # Git authentication + secretRef: string # Secret reference + + # Build Execution + buildPlan: # How to execute the build + type: string # Build type + dockerfile: # Dockerfile configuration + path: string # Dockerfile path + context: string # Build context + buildpacks: # Buildpacks configuration + builder: string # Builder image + env: # Environment variables + - name: string + value: string + + # Output Configuration + output: # Build output configuration + registry: # Container registry details + repository: string # Image repository + tag: string # Image tag + +status: + # Build execution status + phase: enum # "Pending" | "Running" | "Succeeded" | "Failed" + startTime: string # Build start time + completionTime: string # Build completion time + image: string # Built image reference + conditions: # Standard Kubernetes conditions + - type: string + status: enum + reason: string + message: string + lastTransitionTime: string + observedGeneration: integer +``` + +### DeploymentTrack CRD Schema + +```yaml +apiVersion: openchoreo.dev/v1alpha1 +kind: DeploymentTrack +metadata: + name: string # Required: DeploymentTrack name + namespace: string # Required: Project namespace +spec: + # Deployment Automation + autoDeploy: boolean # Optional: Enable automatic deployment (default: false) + + # Build Template Configuration + buildTemplateSpec: # Optional: Build template configuration + # Defines how builds should be created and managed + # for this deployment track + + # Deployment Configuration + deploymentPolicy: # Optional: Deployment policies and rules + # Controls how deployments are executed and managed + strategy: enum # Deployment strategy ("rolling" | "blue-green" | "canary") + rollbackPolicy: # Rollback configuration + enabled: boolean # Enable automatic rollback + conditions: # Conditions that trigger rollback + - type: string + threshold: string + + # Environment Targeting + environments: # Optional: Target environments for this track + - name: string # Environment name + promotion: # Promotion configuration + automatic: boolean # Enable automatic promotion + approval: # Approval requirements + required: boolean # Require manual approval + reviewers: # List of required reviewers + - string + + # Component Tracking + componentRefs: # Optional: Component references to track + - name: string # Component name + branch: string # Git branch to track (optional) + + # Source Configuration + source: # Optional: Source repository configuration + repository: string # Git repository URL + branch: string # Default branch to track + path: string # Path within repository + +status: + # Deployment tracking status + phase: enum # "Active" | "Paused" | "Failed" + lastDeployment: # Information about last deployment + timestamp: string # When last deployment occurred + version: string # Deployed version/tag + status: enum # "Success" | "Failed" | "InProgress" + + # Environment Status + environments: # Status per environment + - name: string # Environment name + status: enum # "Deployed" | "Pending" | "Failed" + version: string # Currently deployed version + lastUpdated: string # Last update timestamp + + conditions: # Standard Kubernetes conditions + - type: string + status: enum # "True" | "False" | "Unknown" + reason: string + message: string + lastTransitionTime: string + observedGeneration: integer +``` + +### Service CRD Schema + +```yaml +apiVersion: openchoreo.dev/v1alpha1 +kind: Service +metadata: + name: string # Required: Service name + namespace: string # Required: Project namespace +spec: + className: string # Optional: Service class name (default: "default") + workloadName: string # Required: Referenced workload name + + # Owner Reference + owner: # Required: Owner information + projectName: string # Required: Project name (minLength: 1) + componentName: string # Required: Component name (minLength: 1) + + # API Configuration + apis: # Optional: API endpoints + "{api-name}": # Key-value pairs for API endpoints + type: string # Required: API technology type + className: string # Optional: API class name (default: "default") + rest: # REST API configuration + backend: # Backend configuration + port: integer # Required: Backend port (int32) + basePath: string # Optional: Base path + exposeLevels: # Optional: Exposure levels + - string + + overrides: {} # Optional: Boolean overrides configuration + +status: {} # Empty status object +``` + +### WebApplication CRD Schema + +```yaml +apiVersion: openchoreo.dev/v1alpha1 +kind: WebApplication +metadata: + name: string # Required: WebApplication name + namespace: string # Required: Project namespace +spec: + className: string # Optional: Web application class (default: "default") + workloadName: string # Required: Referenced workload name + + # Owner Reference + owner: # Required: Owner information + projectName: string # Required: Project name (minLength: 1) + componentName: string # Required: Component name (minLength: 1) + + overrides: {} # Optional: Boolean overrides configuration + +status: {} # Empty status object +``` + +### ScheduledTask CRD Schema + +```yaml +apiVersion: openchoreo.dev/v1alpha1 +kind: ScheduledTask +metadata: + name: string # Required: ScheduledTask name + namespace: string # Required: Project namespace +spec: + className: string # Optional: Task class name (default: "default") + workloadName: string # Required: Referenced workload name + + # Owner Reference + owner: # Required: Owner information + projectName: string # Required: Project name (minLength: 1) + componentName: string # Required: Component name (minLength: 1) + + overrides: {} # Optional: Boolean overrides configuration + +status: {} # Empty status object +``` + +### API CRD Schema + +```yaml +apiVersion: openchoreo.dev/v1alpha1 +kind: API +metadata: + name: string # Required: API name + namespace: string # Required: Project namespace +spec: + className: string # Optional: API class name (default: "default") + environmentName: string # Required: Environment name (minLength: 1) + type: string # Required: API technology type + + # Owner Reference + owner: # Required: Owner information + projectName: string # Required: Project name (minLength: 1) + componentName: string # Required: Component name (minLength: 1) + + # REST API Configuration + rest: # Optional: REST API configuration + backend: # Backend configuration + port: integer # Required: Backend port (int32) + basePath: string # Optional: Base path + exposeLevels: # Optional: Exposure levels + - string + +status: + address: string # API address + conditions: # Standard Kubernetes conditions + - type: string + status: enum + reason: string + message: string + lastTransitionTime: string +``` + +## Deployment Resources + +OpenChoreo uses a template-binding pattern for deployment where Classes define templates and Bindings create environment-specific instances. These resources work together with Workloads and Releases to manage the complete deployment lifecycle. + +### ServiceClass CRD Schema + +```yaml +apiVersion: openchoreo.dev/v1alpha1 +kind: ServiceClass +metadata: + name: string # Required: ServiceClass name + namespace: string # Required: Project namespace +spec: + # Template definition for service deployments + # Defines default configurations, resource limits, and deployment patterns + # Referenced by ServiceBinding instances + +status: {} # Empty status object +``` + +### ServiceBinding CRD Schema + +```yaml +apiVersion: openchoreo.dev/v1alpha1 +kind: ServiceBinding +metadata: + name: string # Required: ServiceBinding name + namespace: string # Required: Project namespace +spec: + # Environment-specific binding configuration + # References ServiceClass and applies environment overrides + # Creates actual deployment instances + +status: {} # Empty status object +``` + +### WebApplicationClass CRD Schema + +```yaml +apiVersion: openchoreo.dev/v1alpha1 +kind: WebApplicationClass +metadata: + name: string # Required: WebApplicationClass name + namespace: string # Required: Project namespace +spec: + # Template definition for web application deployments + # Defines frontend-specific configurations and routing + +status: {} # Empty status object +``` + +### WebApplicationBinding CRD Schema + +```yaml +apiVersion: openchoreo.dev/v1alpha1 +kind: WebApplicationBinding +metadata: + name: string # Required: WebApplicationBinding name + namespace: string # Required: Project namespace +spec: + # Environment-specific web application binding + # References WebApplicationClass with environment overrides + +status: {} # Empty status object +``` + +### ScheduledTaskClass CRD Schema + +```yaml +apiVersion: openchoreo.dev/v1alpha1 +kind: ScheduledTaskClass +metadata: + name: string # Required: ScheduledTaskClass name + namespace: string # Required: Project namespace +spec: + # Template definition for scheduled task deployments + # Defines cron schedules and task execution patterns + +status: {} # Empty status object +``` + +### ScheduledTaskBinding CRD Schema + +```yaml +apiVersion: openchoreo.dev/v1alpha1 +kind: ScheduledTaskBinding +metadata: + name: string # Required: ScheduledTaskBinding name + namespace: string # Required: Project namespace +spec: + # Environment-specific scheduled task binding + # References ScheduledTaskClass with schedule overrides + +status: {} # Empty status object +``` + +### APIClass CRD Schema + +```yaml +apiVersion: openchoreo.dev/v1alpha1 +kind: APIClass +metadata: + name: string # Required: APIClass name + namespace: string # Required: Project namespace +spec: + # Template definition for API deployments + # Defines API gateway policies, rate limiting, authentication + +status: {} # Empty status object +``` + +### APIBinding CRD Schema + +```yaml +apiVersion: openchoreo.dev/v1alpha1 +kind: APIBinding +metadata: + name: string # Required: APIBinding name + namespace: string # Required: Project namespace +spec: + # Environment-specific API binding + # References APIClass with environment-specific policies + +status: {} # Empty status object +``` + +### Workload CRD Schema + +```yaml +apiVersion: openchoreo.dev/v1alpha1 +kind: Workload +metadata: + name: string # Required: Workload name + namespace: string # Required: Project namespace +spec: + # Connection Configuration + connections: # Optional: Internal API connections + "{connection-name}": # Key-value pairs for connections + inject: # Connection detail injection + env: # Environment variables to inject + - key: string # Environment variable name + value: string # Environment variable value + files: # Files to inject + - path: string # File path in container + content: string # File content + target: # Connection target + service: string # Target service name + port: integer # Target service port + +status: {} # Empty status object +``` + +### Release CRD Schema + +```yaml +apiVersion: openchoreo.dev/v1alpha1 +kind: Release +metadata: + name: string # Required: Release name + namespace: string # Required: Project namespace +spec: + environmentName: string # Required: Target environment (minLength: 1) + interval: string # Optional: Watch interval (default: 5m) + # Pattern: ^([0-9]+(\.[0-9]+)?(ms|s|m|h))+$ + + # Release configuration and resource manifests + # Manages the actual Kubernetes resources in the target environment + +status: + # Release status tracking + conditions: # Standard Kubernetes conditions + - type: string + status: enum # "True" | "False" | "Unknown" + reason: string + message: string + lastTransitionTime: string +``` + +### DeployableArtifact CRD Schema + +```yaml +apiVersion: openchoreo.dev/v1alpha1 +kind: DeployableArtifact +metadata: + name: string # Required: DeployableArtifact name + namespace: string # Required: Project namespace +spec: + # Configuration parameters for the deployable artifact + configuration: # Application runtime configuration + application: # Application runtime parameters + args: # Optional: Command line arguments + - string + env: # Optional: Environment variables + - name: string + value: string + ports: # Optional: Container ports + - containerPort: integer # Port number + name: string # Port name + protocol: string # Protocol (TCP/UDP) + resources: # Optional: Resource requirements + requests: + cpu: string + memory: string + limits: + cpu: string + memory: string + + # Artifact Source + source: # Source of the deployable artifact + image: # Container image information + repository: string # Image repository + tag: string # Image tag + digest: string # Image digest for immutable reference + build: # Build information (if built from source) + buildRef: string # Reference to Build that created this artifact + commitSHA: string # Git commit SHA + buildTimestamp: string # When the build was completed + +status: + # Artifact status + conditions: # Standard Kubernetes conditions + - type: string + status: enum # "True" | "False" | "Unknown" + reason: string + message: string + lastTransitionTime: string + observedGeneration: integer +``` + +### Endpoint CRD Schema + +```yaml +apiVersion: openchoreo.dev/v1alpha1 +kind: Endpoint +metadata: + name: string # Required: Endpoint name + namespace: string # Required: Project namespace +spec: + # Backend Configuration + backendRef: # Required: Reference to backend service + name: string # Backend service name + port: integer # Backend service port + namespace: string # Backend service namespace + + # Endpoint Configuration + protocol: enum # Optional: Protocol ("HTTP" | "HTTPS" | "TCP" | "UDP") + path: string # Optional: URL path for HTTP/HTTPS endpoints (default: "/") + + # Traffic Management + traffic: # Optional: Traffic management configuration + weight: integer # Traffic weight for load balancing + canary: # Canary deployment configuration + enabled: boolean # Enable canary deployment + percentage: integer # Percentage of traffic to canary (0-100) + + # Security Configuration + security: # Optional: Security configuration + tls: # TLS configuration + enabled: boolean # Enable TLS termination + secretName: string # TLS certificate secret + authentication: # Authentication configuration + required: boolean # Require authentication + methods: # Authentication methods + - enum # "JWT" | "OAuth2" | "BasicAuth" + +status: + address: string # Endpoint address/URL + conditions: # Standard Kubernetes conditions + - type: string + status: enum # "True" | "False" | "Unknown" + reason: string + message: string + lastTransitionTime: string +``` + +## Configuration Management + +### ConfigurationGroup CRD Schema + +```yaml +apiVersion: openchoreo.dev/v1alpha1 +kind: ConfigurationGroup +metadata: + name: string # Required: ConfigurationGroup name + namespace: string # Required: Project namespace +spec: + # Configuration Parameters + configurations: # Required: Configuration parameters + - key: string # Required: Configuration parameter key + values: # Required: Configuration values + - environment: string # Target environment (mutually exclusive with environmentGroupRef) + environmentGroupRef: string # Target environment group (mutually exclusive with environment) + value: string # Configuration value (mutually exclusive with vaultKey) + vaultKey: string # Vault secret key (mutually exclusive with value) + + # Environment Groups + environmentGroups: # Optional: Environment groups definition + - name: string # Required: Environment group name + environments: # Required: List of environments in group + - string + + scope: {} # Optional: Configuration scope (default: {}) + +status: + conditions: # Standard Kubernetes conditions + - type: string + status: enum + reason: string + message: string + lastTransitionTime: string +``` + +## Validation Rules + +### Common Patterns + +All OpenChoreo resources follow standard Kubernetes patterns with consistent validation: + +```yaml +# Name validation (DNS-1123 compliant) +metadata.name: + pattern: "^[a-z0-9]([-a-z0-9]*[a-z0-9])?$" + maxLength: 253 + +# Condition validation +status.conditions[*].reason: + pattern: "^[A-Za-z]([A-Za-z0-9_,:]*[A-Za-z0-9_])?$" + minLength: 1 + maxLength: 1024 + +status.conditions[*].type: + pattern: "^([a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*/)?(([A-Za-z0-9][-A-Za-z0-9_.]*)?[A-Za-z0-9])$" + maxLength: 316 + +status.conditions[*].message: + maxLength: 32768 + +# Generation tracking +status.observedGeneration: + minimum: 0 + type: integer (int64) +``` + +## Short Names and Categories + +OpenChoreo resources support kubectl short names for convenience: + +```bash +# Organizations +kubectl get org,orgs + +# Projects +kubectl get proj,projs + +# Environments +kubectl get env,envs + +# DataPlanes +kubectl get dp,dps + +# DeploymentPipelines +kubectl get deppipe,deppipes + +# Component +kubectl get components + +# Build +kubectl get builds + +# DeploymentTracks +kubectl get deploymenttracks + +# DeployableArtifacts +kubectl get deployableartifacts + +# ConfigurationGroups +kubectl get configgrp +``` + +--- + +## Schema Updates + +This schema reference reflects the actual OpenChoreo v0.2.0 CRD definitions. For the latest schema definitions, see: + +- **CRD Definitions**: [GitHub Repository](https://github.com/openchoreo/openchoreo/tree/main/config/crd) +- **Resource Reference Guide**: [Complete Resource Guide](https://github.com/openchoreo/openchoreo/blob/main/docs/resource-kind-reference-guide.md) diff --git a/versioned_docs/version-v0.11.x/reference/faq.md b/versioned_docs/version-v0.11.x/reference/faq.md new file mode 100644 index 0000000..b6675b7 --- /dev/null +++ b/versioned_docs/version-v0.11.x/reference/faq.md @@ -0,0 +1,125 @@ +--- +title: Frequently Asked Questions (FAQ) +--- + +# Frequently Asked Questions (FAQ) + +## General Questions + +### What is OpenChoreo? +OpenChoreo is an open-source Internal Developer Platform (IDP) that simplifies cloud-native application development by providing developer-friendly abstractions over complex Kubernetes and cloud-native technologies. + +### How is OpenChoreo different from other platforms? +OpenChoreo focuses on: +- **Developer Experience**: Simple abstractions without losing Kubernetes power +- **Security by Default**: Built-in security with cell-based architecture +- **CNCF Integration**: Orchestrates best-in-class cloud-native tools +- **Open Source**: Community-driven development with no vendor lock-in + +### What are the main benefits of using OpenChoreo? +- **Faster Time to Market**: Deploy applications in minutes instead of days +- **Reduced Complexity**: Focus on business logic instead of infrastructure +- **Production Ready**: Enterprise-grade capabilities from day one +- **Consistent Environments**: Identical configurations across all stages + +--- + +## Getting Started + +### What are the prerequisites for OpenChoreo? +- **Kubernetes Cluster**: Version 1.24 or later +- **kubectl**: Configured to access your cluster +- **Helm**: Version 3.8 or later (for installation) +- **Container Registry**: For storing application images + +### How do I install OpenChoreo? +Choose your path: +- **Quick Try**: [On Self-Hosted Kubernetes](../getting-started/try-it-out/on-self-hosted-kubernetes.mdx) or [On Managed Kubernetes](../getting-started/try-it-out/on-managed-kubernetes.mdx) +- **Production**: See the [Operations Guide](../operations/deployment-topology.mdx) for production configuration + +### Can I try OpenChoreo locally? +Yes! The [On Self-Hosted Kubernetes guide](../getting-started/try-it-out/on-self-hosted-kubernetes.mdx) lets you try OpenChoreo on your laptop with k3d, kind, or any local/VM-hosted cluster - no cloud required. + +### What's the simplest way to deploy my first application? +Follow [Deploying your first component](../getting-started/deploy-first-component.mdx) + +--- + +## Architecture & Concepts + +### What is a "Cell" in OpenChoreo? +A Cell is OpenChoreo's security boundary that: +- Isolates applications using Kubernetes namespaces +- Enforces network policies with Cilium +- Provides encrypted communication with mTLS +- Implements identity-based access controls +- Usually this is a Project in OpenChoreo + +### How does OpenChoreo handle multi-environment deployments? +OpenChoreo uses Environment abstractions that: +- Define deployment targets (dev, staging, prod) +- Apply environment-specific configurations +- Enforce resource quotas and policies +- Enable promotion workflows between environments + +### What's the difference between a Project and a Component? +- **Project**: A logical grouping of related components (e.g., an e-commerce platform) +- **Component**: An individual deployable unit (e.g., user-service, payment-api) + +### How does OpenChoreo integrate with existing CI/CD pipelines? +OpenChoreo provides: +- **CLI tools** for integration with any CI system +- **GitHub Actions** for seamless GitHub workflows +- **Webhooks** for custom integrations +- **API endpoints** for programmatic access + +--- + +## Performance & Deployment + +### What are the resource requirements for OpenChoreo? +**Control Plane (minimum)**: +- **CPU**: 2 cores +- **Memory**: 4 GB RAM (8 GB recommended with observability plane) +- **Storage**: 20 GB + +### Can OpenChoreo work with multiple clusters? +Yes, you can setup the following patterns +- **All in one cluster**: Where all the planes are in a single cluster +- **Combined clusters**: Where a combination of planes are together spread across multiple clusters + e.g. control plane separate and others together, observability plane separate and others together +- **Totally seperated clusters**: Where each plane has it's own cluster. Note that this is not usually for a local setup. + +--- + +## Licensing & Support + +### What license does OpenChoreo use? +OpenChoreo is licensed under the **Apache 2.0 License**, ensuring: +- **Free commercial use** +- **No vendor lock-in** +- **Community contributions welcome** +- **Enterprise-friendly terms** + +### Where can I get help? +- **Documentation**: Comprehensive guides at [openchoreo.dev](../overview/what-is-openchoreo.mdx) +- **Community Forum**: GitHub Discussions for questions +- **Chat**: Real-time help on Discord +- **Issues**: Bug reports on GitHub Issues + +### Is there commercial support available? +Not yet + +### How can I contribute to OpenChoreo? +- **Code Contributions**: Submit pull requests on GitHub +- **Documentation**: Improve guides and tutorials +- **Community Support**: Help answer questions +- **Bug Reports**: File issues with detailed information + +--- + +**Can't find your question?** + +- Search our [documentation](../overview/what-is-openchoreo.mdx) +- Ask in [GitHub Discussions](https://github.com/openchoreo/openchoreo/discussions) +- Join our [Discord channel](https://discord.com/invite/asqDFC8suT) diff --git a/versioned_docs/version-v0.11.x/reference/helm/_category_.json b/versioned_docs/version-v0.11.x/reference/helm/_category_.json new file mode 100644 index 0000000..b1048be --- /dev/null +++ b/versioned_docs/version-v0.11.x/reference/helm/_category_.json @@ -0,0 +1,5 @@ +{ + "label": "Helm Charts", + "position": 2, + "collapsed": false +} diff --git a/versioned_docs/version-v0.11.x/reference/helm/build-plane.mdx b/versioned_docs/version-v0.11.x/reference/helm/build-plane.mdx new file mode 100644 index 0000000..c4eaf75 --- /dev/null +++ b/versioned_docs/version-v0.11.x/reference/helm/build-plane.mdx @@ -0,0 +1,187 @@ +--- +title: Build Plane +description: Helm chart values reference for openchoreo-build-plane. +sidebar_position: 3 +--- + +## Dependencies + +This chart depends on the following sub-charts. For full configuration options of each dependency, please refer to their official documentation. + +| Name | Version | Repository | Condition | +| :--- | :--- | :--- | :--- | +| [argo-workflows](https://argoproj.github.io/argo-helm) | 0.45.2 | [https://argoproj.github.io/argo-helm](https://argoproj.github.io/argo-helm) | - | +| [external-secrets](https://charts.external-secrets.io) | 0.19.2 | [https://charts.external-secrets.io](https://charts.external-secrets.io) | `external-secrets.enabled` | +| [fluent-bit](https://fluent.github.io/helm-charts) | 0.54.0 | [https://fluent.github.io/helm-charts](https://fluent.github.io/helm-charts) | `fluent-bit.enabled` | +| [docker-registry](https://twuni.github.io/docker-registry.helm) | 3.0.0 | [https://twuni.github.io/docker-registry.helm](https://twuni.github.io/docker-registry.helm) | `registry.enabled` | + +## Argo Workflows + +For full configuration options, please refer to the [official chart documentation](https://argoproj.github.io/argo-helm). + +Argo Workflows sub-chart configuration. See https://github.com/argoproj/argo-helm/tree/main/charts/argo-workflows for all options. + +| Parameter | Description | Type | Default | +| :--- | :--- | :--- | :--- | +| `argo-workflows.controller.resources.limits.cpu` | CPU limit for the controller | `string` | `50m` | +| `argo-workflows.controller.resources.limits.memory` | Memory limit for the controller | `string` | `64Mi` | +| `argo-workflows.controller.resources.requests.cpu` | CPU request for the controller | `string` | `25m` | +| `argo-workflows.controller.resources.requests.memory` | Memory request for the controller | `string` | `32Mi` | +| `argo-workflows.crds.keep` | Keep CRDs on chart uninstall | `boolean` | `false` | +| `argo-workflows.fullnameOverride` | Override the full name of Argo Workflows resources | `string` | `argo` | +| `argo-workflows.server.enabled` | Enable the Argo Workflows server UI | `boolean` | `false` | +| `argo-workflows.workflow.serviceAccount.create` | Create service account for workflows | `boolean` | `true` | +| `argo-workflows.workflowNamespaces` | Namespaces where Argo Workflows can submit workflows | `array` | | + +## Cluster Agent + +Cluster Agent configuration for agent-based communication with control plane + +| Parameter | Description | Type | Default | +| :--- | :--- | :--- | :--- | +| `clusterAgent.affinity` | Affinity rules for cluster agent pods | `object` | | +| `clusterAgent.dnsRewrite.enabled` | Enable DNS rewrite for k3d setups | `boolean` | `false` | +| `clusterAgent.enabled` | Enable the cluster agent for control plane communication | `boolean` | `true` | +| `clusterAgent.heartbeatInterval` | Heartbeat interval for control plane connection | `string` | `30s` | +| `clusterAgent.image.pullPolicy` | Image pull policy | `object` | `IfNotPresent` | +| `clusterAgent.image.repository` | Image repository for cluster agent | `string` | `ghcr.io/openchoreo/cluster-agent` | +| `clusterAgent.image.tag` | Image tag. If empty, uses Chart.AppVersion. | `string` | | +| `clusterAgent.logLevel` | Log level for cluster agent | `object` | `info` | +| `clusterAgent.name` | Name of the cluster agent deployment | `string` | `cluster-agent-buildplane` | +| `clusterAgent.nodeSelector` | Node selector for cluster agent pods | `object` | | +| `clusterAgent.planeID` | Logical plane identifier. Shared across multiple CRs connecting to the same physical plane for multi-tenancy. | `string` | `default-buildplane` | +| `clusterAgent.planeType` | Type of plane | `object` | `buildplane` | +| `clusterAgent.podAnnotations` | Annotations to add to cluster agent pods | `object` | | +| `clusterAgent.podSecurityContext.fsGroup` | | `integer` | `1000` | +| `clusterAgent.podSecurityContext.runAsNonRoot` | | `boolean` | `true` | +| `clusterAgent.podSecurityContext.runAsUser` | | `integer` | `1000` | +| `clusterAgent.priorityClass.create` | Create priority class | `boolean` | `false` | +| `clusterAgent.priorityClass.name` | Priority class name | `string` | `cluster-agent-buildplane` | +| `clusterAgent.priorityClass.value` | Priority value | `integer` | `900000` | +| `clusterAgent.rbac.create` | Create RBAC resources | `boolean` | `true` | +| `clusterAgent.reconnectDelay` | Delay before reconnecting on disconnection | `string` | `5s` | +| `clusterAgent.replicas` | Number of cluster agent replicas | `integer` | `1` | +| `clusterAgent.resources.limits.cpu` | | `string` | `100m` | +| `clusterAgent.resources.limits.memory` | | `string` | `256Mi` | +| `clusterAgent.resources.requests.cpu` | | `string` | `50m` | +| `clusterAgent.resources.requests.memory` | | `string` | `128Mi` | +| `clusterAgent.securityContext.allowPrivilegeEscalation` | | `boolean` | `false` | +| `clusterAgent.securityContext.capabilities.drop` | | `array` | | +| `clusterAgent.securityContext.readOnlyRootFilesystem` | | `boolean` | `true` | +| `clusterAgent.serverCANamespace` | Namespace where cluster-gateway CA exists | `string` | `openchoreo-control-plane` | +| `clusterAgent.serverUrl` | WebSocket URL of the cluster gateway in control plane | `string` | `wss://cluster-gateway.openchoreo-control-plane.svc.cluster.local:8443/ws` | +| `clusterAgent.serviceAccount.annotations` | Annotations to add to the service account | `object` | | +| `clusterAgent.serviceAccount.create` | Create service account | `boolean` | `true` | +| `clusterAgent.serviceAccount.name` | Service account name | `string` | `cluster-agent-buildplane` | +| `clusterAgent.tls.caSecretName` | CA secret name for signing agent client certificates. If empty, self-signed certs will be generated (required for multi-cluster setup). | `string` | `cluster-gateway-ca` | +| `clusterAgent.tls.caSecretNamespace` | Namespace where the CA secret exists. If empty, self-signed certs will be generated (required for multi-cluster setup). | `string` | `openchoreo-control-plane` | +| `clusterAgent.tls.caValue` | Inline CA certificate value (PEM format) for multi-cluster setup | `string` | | +| `clusterAgent.tls.clientSecretName` | Client certificate secret name | `string` | `cluster-agent-tls` | +| `clusterAgent.tls.duration` | Certificate duration | `string` | `2160h` | +| `clusterAgent.tls.enabled` | Enable TLS for agent communication | `boolean` | `true` | +| `clusterAgent.tls.generateCerts` | Generate client certificates locally using cert-manager. Set to true for multi-cluster setup. | `boolean` | `false` | +| `clusterAgent.tls.renewBefore` | Certificate renewal window | `string` | `360h` | +| `clusterAgent.tls.secretName` | Secret containing client certificate and key | `string` | `cluster-agent-tls` | +| `clusterAgent.tls.serverCAConfigMap` | ConfigMap containing server CA certificate for verifying gateway | `string` | `cluster-gateway-ca` | +| `clusterAgent.tls.serverCAValue` | Inline server CA certificate value (PEM format) for multi-cluster setup | `string` | | +| `clusterAgent.tolerations` | Tolerations for cluster agent pods | `array` | | + +## External Secrets + +For full configuration options, please refer to the [official chart documentation](https://charts.external-secrets.io). + +External Secrets Operator sub-chart configuration. See https://github.com/external-secrets/external-secrets for all options. Single cluster - set enabled to false to use data plane's ESO. Multi-cluster - set enabled to true to install dedicated ESO in build plane. + +| Parameter | Description | Type | Default | +| :--- | :--- | :--- | :--- | +| `external-secrets.enabled` | Install External Secrets Operator in the build plane | `boolean` | `false` | +| `external-secrets.fullnameOverride` | Override the full name of External Secrets resources | `string` | `external-secrets` | +| `external-secrets.nameOverride` | Override the name of External Secrets resources | `string` | `external-secrets` | + +## Fake Secret Store + +Fake Secret Store configuration for local development. Creates a ClusterSecretStore with static secrets for testing purposes. Not for production use. + +| Parameter | Description | Type | Default | +| :--- | :--- | :--- | :--- | +| `fakeSecretStore.enabled` | Enable the fake secret store for development | `boolean` | `true` | +| `fakeSecretStore.name` | Name of the ClusterSecretStore resource | `string` | `default` | +| `fakeSecretStore.secrets` | List of fake secrets to create for development | `array` | | + +## Fluent Bit + +For full configuration options, please refer to the [official chart documentation](https://fluent.github.io/helm-charts). + +Fluent Bit subchart configuration for log collection and forwarding to OpenSearch + +| Parameter | Description | Type | Default | +| :--- | :--- | :--- | :--- | +| `fluent-bit.config.customParsers` | Custom parser definitions in Fluent Bit configuration format | `string` | `(multiline string)` | +| `fluent-bit.config.filters` | Filter plugin configuration for log processing | `string` | `(multiline string)` | +| `fluent-bit.config.inputs` | Input plugin configuration for log collection | `string` | `(multiline string)` | +| `fluent-bit.config.outputs` | Output plugin configuration for log forwarding to OpenSearch | `string` | `(multiline string)` | +| `fluent-bit.dnsPolicy` | DNS policy for Fluent Bit pods | `object` | `ClusterFirstWithHostNet` | +| `fluent-bit.enabled` | Enable Fluent Bit log collector deployment | `boolean` | `false` | +| `fluent-bit.extraVolumeMounts` | Extra volume mounts for the Fluent Bit container | `array` | | +| `fluent-bit.extraVolumes` | Extra volumes for the Fluent Bit pod | `array` | | +| `fluent-bit.fullnameOverride` | Override the full name of Fluent Bit resources | `string` | `fluent-bit` | +| `fluent-bit.hostNetwork` | Use host network for Fluent Bit pods (required for node log access) | `boolean` | `true` | +| `fluent-bit.initContainers` | Init containers for the Fluent Bit pod (used to set volume ownership) | `array` | | +| `fluent-bit.metricsPort` | Port for Fluent Bit metrics endpoint | `integer` | `2021` | +| `fluent-bit.rbac.nodeAccess` | Enable node-level access for reading container logs | `boolean` | `true` | +| `fluent-bit.resources.limits.cpu` | CPU limit for Fluent Bit | `string` | `200m` | +| `fluent-bit.resources.limits.memory` | Memory limit for Fluent Bit | `string` | `256Mi` | +| `fluent-bit.resources.requests.cpu` | CPU request for Fluent Bit | `string` | `100m` | +| `fluent-bit.resources.requests.memory` | Memory request for Fluent Bit | `string` | `128Mi` | +| `fluent-bit.securityContext.allowPrivilegeEscalation` | Prevent privilege escalation | `boolean` | `false` | +| `fluent-bit.securityContext.capabilities.drop` | Capabilities to drop | `array` | | +| `fluent-bit.securityContext.readOnlyRootFilesystem` | Mount root filesystem as read-only | `boolean` | `true` | +| `fluent-bit.securityContext.runAsNonRoot` | Run container as non-root user | `boolean` | `true` | +| `fluent-bit.securityContext.runAsUser` | User ID to run the container | `integer` | `10000` | +| `fluent-bit.service.port` | Service port for Fluent Bit metrics | `integer` | `2021` | +| `fluent-bit.testFramework.enabled` | Enable Fluent Bit test framework | `boolean` | `false` | + +## Global + +Global configuration values shared across all components + +| Parameter | Description | Type | Default | +| :--- | :--- | :--- | :--- | +| `global.baseDomain` | Base domain for external access. When set, registry will be accessible at registry.<baseDomain>. | `string` | | +| `global.commonLabels` | Common labels to add to every resource | `object` | | +| `global.defaultResources.buildpackCache.enabled` | Enable buildpack image caching hook | `boolean` | `true` | +| `global.defaultResources.buildpackCache.images` | List of buildpack images to cache | `array` | | +| `global.defaultResources.enabled` | If true, applies the workflow templates | `boolean` | `true` | +| `global.defaultResources.podmanCache.size` | Size of the persistent volume for podman image layer cache | `string` | `10Gi` | +| `global.defaultResources.podmanCache.storageClass` | Storage class for the cache PVC. Uses cluster default if not set. | `string` | | +| `global.defaultResources.registry.endpoint` | Registry endpoint for pushing and pulling images. For external registry with baseDomain, automatically uses registry.<baseDomain>. | `string` | `registry.openchoreo-build-plane.svc.cluster.local:5000` | +| `global.defaultResources.registry.tlsVerify` | Enable TLS verification when pushing images to the registry. Set to false for self-signed certificates or local development. | `boolean` | `false` | +| `global.ingressClassName` | Ingress class name for registry ingress | `string` | `openchoreo-traefik` | +| `global.tls.enabled` | Enable TLS for registry ingress | `boolean` | `false` | +| `global.tls.secretName` | Secret containing TLS certificate for registry | `string` | `registry-tls` | + +## Registry + +For full configuration options, please refer to the [official chart documentation](https://twuni.github.io/docker-registry.helm). + +Container Registry sub-chart configuration using Twuni Docker Registry Helm Chart. Hosts container images built by Argo Workflows in the Build Plane. See https://github.com/twuni/docker-registry.helm for all options. + +| Parameter | Description | Type | Default | +| :--- | :--- | :--- | :--- | +| `registry.fullnameOverride` | Override the full name of registry resources | `string` | `registry` | +| `registry.ingress.annotations` | Annotations to add to the ingress resource | `object` | | +| `registry.ingress.className` | Ingress class name. Falls back to global.ingressClassName if not set. | `string` | | +| `registry.ingress.enabled` | Enable ingress for external registry access | `boolean` | `false` | +| `registry.ingress.tls.enabled` | Enable TLS for registry ingress | `boolean` | `false` | +| `registry.ingress.tls.secretName` | Secret containing TLS certificate | `string` | | +| `registry.persistence.enabled` | Enable persistent storage for registry | `boolean` | `true` | +| `registry.persistence.size` | Size of the persistent volume for registry storage | `string` | `10Gi` | + +## Wait Job + +Wait job configuration for post-install hooks + +| Parameter | Description | Type | Default | +| :--- | :--- | :--- | :--- | +| `waitJob.image` | Container image used for wait jobs (must contain kubectl) | `string` | `bitnamilegacy/kubectl:1.32.4` | + diff --git a/versioned_docs/version-v0.11.x/reference/helm/control-plane.mdx b/versioned_docs/version-v0.11.x/reference/helm/control-plane.mdx new file mode 100644 index 0000000..12d09af --- /dev/null +++ b/versioned_docs/version-v0.11.x/reference/helm/control-plane.mdx @@ -0,0 +1,540 @@ +--- +title: Control Plane +description: Helm chart values reference for openchoreo-control-plane. +sidebar_position: 1 +--- + +## Dependencies + +This chart depends on the following sub-charts. For full configuration options of each dependency, please refer to their official documentation. + +| Name | Version | Repository | Condition | +| :--- | :--- | :--- | :--- | +| [kgateway-crds](oci://cr.kgateway.dev/kgateway-dev/charts) | v2.1.1 | oci://cr.kgateway.dev/kgateway-dev/charts | `gatewayController.enabled` | +| [kgateway](oci://cr.kgateway.dev/kgateway-dev/charts) | v2.1.1 | oci://cr.kgateway.dev/kgateway-dev/charts | `gatewayController.enabled` | +| [thunder](oci://ghcr.io/asgardeo/helm-charts) | 0.15.0 | oci://ghcr.io/asgardeo/helm-charts | `thunder.enabled` | + +## Backstage + +Backstage UI configuration + +| Parameter | Description | Type | Default | +| :--- | :--- | :--- | :--- | +| `backstage.affinity` | Affinity rules | `object` | `{}` | +| `backstage.auth.clientId` | OAuth client ID | `string` | `openchoreo-backstage-client` | +| `backstage.auth.clientSecret` | OAuth client secret | `string` | `backstage-portal-secret` | +| `backstage.auth.redirectUrls` | OAuth redirect URLs | `array` | `[]` | +| `backstage.autoscaling.behavior.scaleDown.policies` | Scale-down policies | `array` | | +| `backstage.autoscaling.behavior.scaleDown.stabilizationWindowSeconds` | Stabilization window in seconds | `integer` | `300` | +| `backstage.autoscaling.behavior.scaleUp.policies` | Scale-up policies | `array` | | +| `backstage.autoscaling.behavior.scaleUp.selectPolicy` | Policy selection strategy | `object` | `Max` | +| `backstage.autoscaling.behavior.scaleUp.stabilizationWindowSeconds` | Stabilization window in seconds | `integer` | `0` | +| `backstage.autoscaling.enabled` | Enable HPA | `boolean` | `false` | +| `backstage.autoscaling.maxReplicas` | Maximum replicas | `integer` | `3` | +| `backstage.autoscaling.minReplicas` | Minimum replicas | `integer` | `1` | +| `backstage.autoscaling.targetCPUUtilizationPercentage` | Target CPU utilization percentage | `integer` | `70` | +| `backstage.autoscaling.targetMemoryUtilizationPercentage` | Target memory utilization percentage | `integer` | `80` | +| `backstage.backendSecret` | Backend secret for Backstage encryption. If empty, a random secret is generated | `string` | | +| `backstage.baseUrl` | Backstage public base URL. If empty, auto-derived from global.baseDomain | `string` | | +| `backstage.containerSecurityContext.allowPrivilegeEscalation` | Prevent privilege escalation | `boolean` | `false` | +| `backstage.containerSecurityContext.appArmorProfile.type` | AppArmor profile type | `object` | `Unconfined` | +| `backstage.containerSecurityContext.capabilities.drop` | Capabilities to drop | `array` | | +| `backstage.containerSecurityContext.readOnlyRootFilesystem` | Read-only root filesystem | `boolean` | `false` | +| `backstage.containerSecurityContext.seccompProfile.type` | Seccomp profile type | `object` | `RuntimeDefault` | +| `backstage.database.postgresql.database` | PostgreSQL database name | `string` | `backstage` | +| `backstage.database.postgresql.host` | PostgreSQL host | `string` | | +| `backstage.database.postgresql.password` | PostgreSQL password | `string` | | +| `backstage.database.postgresql.port` | PostgreSQL port | `integer` | `5432` | +| `backstage.database.postgresql.user` | PostgreSQL username | `string` | `backstage` | +| `backstage.database.sqlite.mountPath` | Mount path for database directory inside container | `string` | `/app/.config/backstage` | +| `backstage.database.sqlite.persistence.accessMode` | PVC access mode | `object` | `ReadWriteOnce` | +| `backstage.database.sqlite.persistence.enabled` | Enable PVC for persistence (false = emptyDir) | `boolean` | `false` | +| `backstage.database.sqlite.persistence.size` | PVC storage size | `string` | `1Gi` | +| `backstage.database.sqlite.persistence.storageClassName` | Storage class name (empty = default storage class) | `string` | | +| `backstage.database.type` | Database type | `object` | `sqlite` | +| `backstage.enabled` | Enable Backstage UI deployment | `boolean` | `true` | +| `backstage.env` | Environment variables for the Backstage container | `array` | | +| `backstage.features.observability.enabled` | Enable observability feature | `boolean` | `true` | +| `backstage.features.workflows.enabled` | Enable workflows feature | `boolean` | `true` | +| `backstage.image.pullPolicy` | Image pull policy | `object` | `IfNotPresent` | +| `backstage.image.repository` | Docker image repository | `string` | `ghcr.io/openchoreo/openchoreo-ui` | +| `backstage.image.tag` | Image tag. If empty, uses Chart.AppVersion | `string` | | +| `backstage.ingress.annotations` | Ingress annotations | `object` | `{}` | +| `backstage.ingress.enabled` | Enable ingress | `boolean` | `true` | +| `backstage.ingress.hosts` | Ingress hosts | `array` | `[]` | +| `backstage.ingress.ingressClassName` | Ingress class name | `string` | | +| `backstage.ingress.tls` | Ingress TLS configuration | `array` | `[]` | +| `backstage.metrics.enabled` | Enable Prometheus metrics | `boolean` | `true` | +| `backstage.metrics.serviceMonitor.enabled` | Create ServiceMonitor resource | `boolean` | `false` | +| `backstage.metrics.serviceMonitor.interval` | Scrape interval | `string` | `30s` | +| `backstage.metrics.serviceMonitor.labels.prometheus` | | `string` | `kube-prometheus` | +| `backstage.metrics.serviceMonitor.namespace` | Namespace for ServiceMonitor | `string` | `monitoring` | +| `backstage.metrics.serviceMonitor.relabelings` | Metric relabeling rules | `array` | `[]` | +| `backstage.metrics.serviceMonitor.scrapeTimeout` | Scrape timeout | `string` | `10s` | +| `backstage.networkPolicy.egress` | Egress rules | `array` | `[]` | +| `backstage.networkPolicy.enabled` | Enable NetworkPolicy | `boolean` | `false` | +| `backstage.networkPolicy.ingress` | Ingress rules | `array` | `[]` | +| `backstage.nodeSelector` | Node selector | `object` | `{}` | +| `backstage.openchoreoApi.url` | OpenChoreo API URL. If empty, auto-derived from internal service | `string` | | +| `backstage.podDisruptionBudget.enabled` | Enable PDB | `boolean` | `false` | +| `backstage.podDisruptionBudget.minAvailable` | Minimum available pods | `integer` | `1` | +| `backstage.podSecurityContext.fsGroup` | Filesystem group | `integer` | `1000` | +| `backstage.podSecurityContext.runAsGroup` | Group ID | `integer` | `1000` | +| `backstage.podSecurityContext.runAsNonRoot` | Run as non-root user | `boolean` | `true` | +| `backstage.podSecurityContext.runAsUser` | User ID | `integer` | `1000` | +| `backstage.podSecurityContext.seccompProfile.type` | Seccomp profile type | `object` | `RuntimeDefault` | +| `backstage.priorityClass.create` | Create a priority class | `boolean` | `false` | +| `backstage.priorityClass.name` | Priority class name | `string` | `openchoreo-backstage` | +| `backstage.priorityClass.value` | Priority class value | `integer` | `800000` | +| `backstage.replicas` | Number of Backstage replicas | `integer` | `1` | +| `backstage.resources.limits.cpu` | CPU limit | `string` | `2000m` | +| `backstage.resources.limits.memory` | Memory limit | `string` | `2Gi` | +| `backstage.resources.requests.cpu` | CPU request | `string` | `200m` | +| `backstage.resources.requests.memory` | Memory request | `string` | `256Mi` | +| `backstage.service.nodePort` | NodePort (only used if service.type is NodePort) | `integer,null` | `null` | +| `backstage.service.port` | Service port | `integer` | `7007` | +| `backstage.service.type` | Service type | `object` | `ClusterIP` | +| `backstage.serviceAccount.annotations` | Service account annotations | `object` | `{}` | +| `backstage.serviceAccount.name` | Service account name | `string` | `openchoreo-backstage` | +| `backstage.thunder.baseUrl` | Thunder public base URL. If empty, auto-derived from global.baseDomain | `string` | | +| `backstage.thunder.token` | Thunder API token for authentication | `string` | | +| `backstage.tolerations` | Tolerations | `array` | `[]` | +| `backstage.topologySpreadConstraints` | Topology spread constraints | `array` | | + +## Cluster Gateway + +Cluster Gateway configuration - manages WebSocket connections from cluster agents + +| Parameter | Description | Type | Default | +| :--- | :--- | :--- | :--- | +| `clusterGateway.affinity` | Affinity rules | `object` | `{}` | +| `clusterGateway.enabled` | Enable the cluster gateway | `boolean` | `true` | +| `clusterGateway.heartbeatInterval` | Heartbeat interval for agent connections | `string` | `30s` | +| `clusterGateway.heartbeatTimeout` | Heartbeat timeout for agent connections | `string` | `90s` | +| `clusterGateway.image.pullPolicy` | Image pull policy | `object` | `IfNotPresent` | +| `clusterGateway.image.repository` | Docker image repository | `string` | `ghcr.io/openchoreo/cluster-gateway` | +| `clusterGateway.image.tag` | Image tag. If empty, uses Chart.AppVersion | `string` | | +| `clusterGateway.logLevel` | Log level | `object` | `info` | +| `clusterGateway.name` | Name of the cluster gateway deployment | `string` | `cluster-gateway` | +| `clusterGateway.nodeSelector` | Node selector | `object` | `{}` | +| `clusterGateway.podSecurityContext.fsGroup` | Filesystem group | `integer` | `1000` | +| `clusterGateway.podSecurityContext.runAsNonRoot` | Run as non-root user | `boolean` | `true` | +| `clusterGateway.podSecurityContext.runAsUser` | User ID | `integer` | `1000` | +| `clusterGateway.port` | WebSocket port for agent connections | `integer` | `8443` | +| `clusterGateway.priorityClass.create` | Create a priority class | `boolean` | `false` | +| `clusterGateway.priorityClass.name` | Priority class name | `string` | `cluster-gateway` | +| `clusterGateway.priorityClass.value` | Priority class value | `integer` | `900000` | +| `clusterGateway.replicas` | Number of cluster gateway replicas | `integer` | `1` | +| `clusterGateway.resources.limits.cpu` | CPU limit | `string` | `500m` | +| `clusterGateway.resources.limits.memory` | Memory limit | `string` | `256Mi` | +| `clusterGateway.resources.requests.cpu` | CPU request | `string` | `100m` | +| `clusterGateway.resources.requests.memory` | Memory request | `string` | `64Mi` | +| `clusterGateway.securityContext.allowPrivilegeEscalation` | Prevent privilege escalation | `boolean` | `false` | +| `clusterGateway.securityContext.capabilities.drop` | Capabilities to drop | `array` | | +| `clusterGateway.securityContext.readOnlyRootFilesystem` | Read-only root filesystem | `boolean` | `true` | +| `clusterGateway.service.clusterIP` | Cluster IP (set to None for headless service) | `string,null` | `null` | +| `clusterGateway.service.loadBalancerIP` | LoadBalancer IP (only used if service.type is LoadBalancer) | `string,null` | `null` | +| `clusterGateway.service.nodePort` | NodePort (only used if service.type is NodePort) | `integer,null` | `null` | +| `clusterGateway.service.port` | Service port | `integer` | `8443` | +| `clusterGateway.service.type` | Service type | `object` | `ClusterIP` | +| `clusterGateway.serviceAccount.annotations` | Service account annotations | `object` | `{}` | +| `clusterGateway.serviceAccount.create` | Create a service account | `boolean` | `true` | +| `clusterGateway.serviceAccount.name` | Service account name | `string` | `cluster-gateway` | +| `clusterGateway.tls.dnsNames` | DNS names for the certificate | `array` | | +| `clusterGateway.tls.duration` | Certificate validity duration (90 days) | `string` | `2160h` | +| `clusterGateway.tls.enabled` | Enable TLS | `boolean` | `true` | +| `clusterGateway.tls.issuerRef.kind` | Issuer kind | `object` | `Issuer` | +| `clusterGateway.tls.issuerRef.name` | Issuer name | `string` | `cluster-gateway-selfsigned-issuer` | +| `clusterGateway.tls.renewBefore` | Certificate renewal threshold (15 days before expiry) | `string` | `360h` | +| `clusterGateway.tls.secretName` | TLS secret name | `string` | `cluster-gateway-tls` | +| `clusterGateway.tlsRoute.enabled` | Enable TLSRoute for cluster gateway | `boolean` | `false` | +| `clusterGateway.tlsRoute.hosts` | Hostnames for TLSRoute | `array` | `[]` | +| `clusterGateway.tolerations` | Tolerations | `array` | `[]` | + +## Controller Manager + +Controller Manager configuration - the main controller for OpenChoreo CRDs + +| Parameter | Description | Type | Default | +| :--- | :--- | :--- | :--- | +| `controllerManager.affinity` | Affinity rules for pod scheduling | `object` | `{}` | +| `controllerManager.autoscaling.behavior.scaleDown.policies` | Scale-down policies | `array` | | +| `controllerManager.autoscaling.behavior.scaleDown.stabilizationWindowSeconds` | Stabilization window in seconds before scaling down | `integer` | `300` | +| `controllerManager.autoscaling.behavior.scaleUp.policies` | Scale-up policies | `array` | | +| `controllerManager.autoscaling.behavior.scaleUp.selectPolicy` | Policy selection strategy | `object` | `Max` | +| `controllerManager.autoscaling.behavior.scaleUp.stabilizationWindowSeconds` | Stabilization window in seconds before scaling up | `integer` | `0` | +| `controllerManager.autoscaling.enabled` | Enable Horizontal Pod Autoscaler | `boolean` | `false` | +| `controllerManager.autoscaling.maxReplicas` | Maximum number of replicas | `integer` | `3` | +| `controllerManager.autoscaling.minReplicas` | Minimum number of replicas | `integer` | `1` | +| `controllerManager.autoscaling.targetCPUUtilizationPercentage` | Target CPU utilization percentage for scaling | `integer` | `70` | +| `controllerManager.autoscaling.targetMemoryUtilizationPercentage` | Target memory utilization percentage for scaling | `integer` | `80` | +| `controllerManager.clusterGateway.enabled` | Enable cluster gateway integration for remote data plane communication | `boolean` | `true` | +| `controllerManager.clusterGateway.tls.caPath` | Path to the CA certificate file | `string` | `/etc/cluster-gateway/ca.crt` | +| `controllerManager.clusterGateway.tls.caSecret` | Name of the secret containing the CA certificate | `string` | `cluster-gateway-ca` | +| `controllerManager.clusterGateway.url` | Cluster gateway service URL | `string` | `https://cluster-gateway.openchoreo-control-plane.svc.cluster.local:8443` | +| `controllerManager.containerSecurityContext.allowPrivilegeEscalation` | Prevent privilege escalation | `boolean` | `false` | +| `controllerManager.containerSecurityContext.appArmorProfile.type` | AppArmor profile type | `object` | `Unconfined` | +| `controllerManager.containerSecurityContext.capabilities.drop` | Capabilities to drop | `array` | | +| `controllerManager.containerSecurityContext.readOnlyRootFilesystem` | Mount root filesystem as read-only | `boolean` | `false` | +| `controllerManager.containerSecurityContext.seccompProfile.type` | Seccomp profile type | `object` | `RuntimeDefault` | +| `controllerManager.image.pullPolicy` | Image pull policy | `object` | `Always` | +| `controllerManager.image.repository` | Docker image repository | `string` | `ghcr.io/openchoreo/controller` | +| `controllerManager.image.tag` | Image tag. If empty, uses Chart.AppVersion | `string` | | +| `controllerManager.manager.args` | Command-line arguments for the controller-manager | `array` | | +| `controllerManager.manager.env.enableWebhooks` | Enable admission webhooks | `object` | `true` | +| `controllerManager.metrics.enabled` | Enable Prometheus metrics endpoint | `boolean` | `true` | +| `controllerManager.metrics.serviceMonitor.enabled` | Create a ServiceMonitor resource for Prometheus Operator | `boolean` | `false` | +| `controllerManager.metrics.serviceMonitor.interval` | Scrape interval | `string` | `30s` | +| `controllerManager.metrics.serviceMonitor.labels.prometheus` | | `string` | `kube-prometheus` | +| `controllerManager.metrics.serviceMonitor.namespace` | Namespace where ServiceMonitor should be created | `string` | `monitoring` | +| `controllerManager.metrics.serviceMonitor.relabelings` | Metric relabeling rules | `array` | `[]` | +| `controllerManager.metrics.serviceMonitor.scrapeTimeout` | Scrape timeout | `string` | `10s` | +| `controllerManager.name` | Name of the controller-manager deployment | `string` | `controller-manager` | +| `controllerManager.networkPolicy.egress` | Egress rules for the NetworkPolicy | `array` | `[]` | +| `controllerManager.networkPolicy.enabled` | Enable NetworkPolicy | `boolean` | `false` | +| `controllerManager.networkPolicy.ingress` | Ingress rules for the NetworkPolicy | `array` | `[]` | +| `controllerManager.nodeSelector` | Node selector for pod scheduling | `object` | `{}` | +| `controllerManager.podDisruptionBudget.enabled` | Enable PodDisruptionBudget | `boolean` | `false` | +| `controllerManager.podDisruptionBudget.minAvailable` | Minimum number of pods that must be available | `integer` | `1` | +| `controllerManager.podSecurityContext.fsGroup` | Filesystem group for volumes | `integer` | `1000` | +| `controllerManager.podSecurityContext.runAsGroup` | Group ID to run the container as | `integer` | `1000` | +| `controllerManager.podSecurityContext.runAsNonRoot` | Run container as non-root user | `boolean` | `true` | +| `controllerManager.podSecurityContext.runAsUser` | User ID to run the container as | `integer` | `1000` | +| `controllerManager.podSecurityContext.seccompProfile.type` | Seccomp profile type | `object` | `RuntimeDefault` | +| `controllerManager.priorityClass.create` | Create a priority class for the controller-manager | `boolean` | `false` | +| `controllerManager.priorityClass.name` | Priority class name | `string` | `openchoreo-controller-manager` | +| `controllerManager.priorityClass.value` | Priority class value (higher = more priority) | `integer` | `1000000` | +| `controllerManager.replicas` | Number of controller-manager replicas | `integer` | `1` | +| `controllerManager.resources.limits.cpu` | CPU limit | `string` | `1000m` | +| `controllerManager.resources.limits.memory` | Memory limit | `string` | `1Gi` | +| `controllerManager.resources.requests.cpu` | CPU request | `string` | `200m` | +| `controllerManager.resources.requests.memory` | Memory request | `string` | `256Mi` | +| `controllerManager.service.nodePort` | NodePort (only used if service.type is NodePort) | `integer,null` | `null` | +| `controllerManager.service.port` | Service port | `integer` | `8080` | +| `controllerManager.service.type` | Service type | `object` | `ClusterIP` | +| `controllerManager.serviceAccount.annotations` | Annotations to add to the service account | `object` | `{}` | +| `controllerManager.serviceAccount.create` | Create a service account for the controller-manager | `boolean` | `true` | +| `controllerManager.tolerations` | Tolerations for pod scheduling | `array` | `[]` | +| `controllerManager.topologySpreadConstraints` | Topology spread constraints for pod distribution across zones and nodes | `array` | | + +## Fullname Override + +Override the full name of the chart release + +| Parameter | Description | Type | Default | +| :--- | :--- | :--- | :--- | +| `fullnameOverride` | Override the full name of the chart release | `string` | `openchoreo` | + +## Gateway + +For full configuration options, please refer to the [official chart documentation](oci://cr.kgateway.dev/kgateway-dev/charts). + +KGateway (Gateway API) configuration (subchart) + +| Parameter | Description | Type | Default | +| :--- | :--- | :--- | :--- | +| `gateway.agentgateway.enabled` | Enable agent gateway | `boolean` | `false` | +| `gateway.controller.image.pullPolicy` | Image pull policy | `object` | `IfNotPresent` | +| `gateway.controller.image.registry` | Image registry | `string` | | +| `gateway.controller.image.repository` | Image repository | `string` | `kgateway` | +| `gateway.controller.image.tag` | Image tag (defaults to chart appVersion) | `string` | | +| `gateway.controller.logLevel` | Controller log level | `object` | `info` | +| `gateway.controller.replicaCount` | Number of controller replicas | `integer` | `1` | +| `gateway.controller.resources.limits.cpu` | CPU limit | `string` | `200m` | +| `gateway.controller.resources.limits.memory` | Memory limit | `string` | `256Mi` | +| `gateway.controller.resources.requests.cpu` | CPU request | `string` | `100m` | +| `gateway.controller.resources.requests.memory` | Memory request | `string` | `128Mi` | +| `gateway.controller.service.ports.agwGrpc` | Agent gateway gRPC port | `integer` | `9978` | +| `gateway.controller.service.ports.grpc` | gRPC port | `integer` | `9977` | +| `gateway.controller.service.ports.health` | Health check port | `integer` | `9093` | +| `gateway.controller.service.ports.metrics` | Metrics port | `integer` | `9092` | +| `gateway.controller.service.type` | Service type | `object` | `ClusterIP` | +| `gateway.enabled` | Enable Gateway CR creation | `boolean` | `true` | +| `gateway.envoy.enabled` | Enable Envoy proxy | `boolean` | `true` | +| `gateway.envoy.mountTmpVolume` | Mount /tmp as emptyDir volume (required for macOS Docker Desktop/Colima) | `boolean` | `false` | +| `gateway.httpPort` | HTTP listener port | `integer` | `80` | +| `gateway.httpsPort` | HTTPS listener port | `integer` | `443` | +| `gateway.image.pullPolicy` | Default image pull policy | `object` | `IfNotPresent` | +| `gateway.image.registry` | Default registry for gateway images | `string` | `cr.kgateway.dev/kgateway-dev` | +| `gateway.image.tag` | Default image tag (defaults to chart appVersion) | `string` | | +| `gateway.selfSignedIssuer.enabled` | Create self-signed ClusterIssuer (set to false in single cluster mode for data-plane) | `boolean` | `true` | +| `gateway.tls.certName` | Certificate secret name | `string` | `{{ .Values.global.tls.secretName }}` | +| `gateway.tls.clusterIssuer` | ClusterIssuer for certificate generation (empty uses default self-signed issuer) | `string` | | +| `gateway.tls.hostname` | Hostname pattern for TLS certificate | `string` | `*.{{ .Values.global.baseDomain }}` | + +## Gateway Controller + +KGateway controller configuration + +| Parameter | Description | Type | Default | +| :--- | :--- | :--- | :--- | +| `gatewayController.enabled` | Enable kgateway controller installation (set to false in single cluster mode for data-plane) | `boolean` | `true` | + +## Global + +Global values shared across all components + +| Parameter | Description | Type | Default | +| :--- | :--- | :--- | :--- | +| `global.baseDomain` | Base domain for all services. Console will be at baseDomain, API at api.baseDomain | `string` | `openchoreo.local` | +| `global.clusterName` | Kubernetes cluster name identifier | `string` | `openchoreo` | +| `global.commonLabels` | Labels applied to all resources created by the chart | `object` | `{}` | +| `global.defaultResources.deploymentPipeline.description` | Description for the default pipeline | `string` | `Standard deployment pipeline with dev, staging, and prod environments` | +| `global.defaultResources.deploymentPipeline.displayName` | Display name for the default pipeline | `string` | `Default Pipeline` | +| `global.defaultResources.deploymentPipeline.promotionOrder` | Promotion order defining how deployments flow between environments | `array` | | +| `global.defaultResources.enabled` | Enable creation of default resources (organization, project, environments, pipeline) | `boolean` | `true` | +| `global.defaultResources.environments` | Default environments to create | `array` | | +| `global.defaultResources.organization.description` | Description for the default organization | `string` | `Getting started with your first organization` | +| `global.defaultResources.organization.displayName` | Display name for the default organization | `string` | `Default Organization` | +| `global.defaultResources.project.description` | Description for the default project | `string` | `Your first project to get started` | +| `global.defaultResources.project.displayName` | Display name for the default project | `string` | `Default Project` | +| `global.imagePullSecrets` | Docker registry credentials for pulling images | `array` | `[]` | +| `global.port` | Port suffix for URLs (e.g., ":8080" for non-standard ports). Include the colon. Leave empty for standard ports (80/443) | `string` | | +| `global.tls.enabled` | Enable TLS/HTTPS for all ingresses | `boolean` | `false` | +| `global.tls.secretName` | Secret containing TLS certificate (must have all hosts - baseDomain, api.baseDomain, thunder.baseDomain) | `string` | `control-plane-tls` | + +## Kgateway Crds + +For full configuration options, please refer to the [official chart documentation](oci://cr.kgateway.dev/kgateway-dev/charts). + +KGateway CRDs subchart configuration (Helm dependency) + +| Parameter | Description | Type | Default | +| :--- | :--- | :--- | :--- | +| `kgateway-crds` | KGateway CRDs subchart configuration (Helm dependency) | `object` | | + +## Kubernetes Cluster Domain + +Kubernetes cluster domain suffix + +| Parameter | Description | Type | Default | +| :--- | :--- | :--- | :--- | +| `kubernetesClusterDomain` | Kubernetes cluster domain suffix | `string` | `cluster.local` | + +## Metrics Server + +Kubernetes metrics server configuration + +| Parameter | Description | Type | Default | +| :--- | :--- | :--- | :--- | +| `metricsServer.enabled` | Enable metrics server deployment | `boolean` | `false` | +| `metricsServer.kubeletInsecureTlsEnabled` | Allow insecure TLS connections to kubelet | `boolean` | `true` | + +## Metrics Service + +Metrics service configuration + +| Parameter | Description | Type | Default | +| :--- | :--- | :--- | :--- | +| `metricsService.ports` | Ports exposed by the metrics service | `array` | | +| `metricsService.type` | Service type | `object` | `ClusterIP` | + +## Openchoreo Api + +OpenChoreo API server configuration + +| Parameter | Description | Type | Default | +| :--- | :--- | :--- | :--- | +| `openchoreoApi.affinity` | Affinity rules | `object` | `{}` | +| `openchoreoApi.autoscaling.behavior.scaleDown.policies` | Scale-down policies | `array` | | +| `openchoreoApi.autoscaling.behavior.scaleDown.stabilizationWindowSeconds` | Stabilization window in seconds | `integer` | `300` | +| `openchoreoApi.autoscaling.behavior.scaleUp.policies` | Scale-up policies | `array` | | +| `openchoreoApi.autoscaling.behavior.scaleUp.selectPolicy` | Policy selection strategy | `object` | `Max` | +| `openchoreoApi.autoscaling.behavior.scaleUp.stabilizationWindowSeconds` | Stabilization window in seconds | `integer` | `0` | +| `openchoreoApi.autoscaling.enabled` | Enable Horizontal Pod Autoscaler | `boolean` | `false` | +| `openchoreoApi.autoscaling.maxReplicas` | Maximum number of replicas | `integer` | `3` | +| `openchoreoApi.autoscaling.minReplicas` | Minimum number of replicas | `integer` | `1` | +| `openchoreoApi.autoscaling.targetCPUUtilizationPercentage` | Target CPU utilization percentage | `integer` | `70` | +| `openchoreoApi.autoscaling.targetMemoryUtilizationPercentage` | Target memory utilization percentage | `integer` | `80` | +| `openchoreoApi.containerSecurityContext.allowPrivilegeEscalation` | Prevent privilege escalation | `boolean` | `false` | +| `openchoreoApi.containerSecurityContext.appArmorProfile.type` | AppArmor profile type | `object` | `Unconfined` | +| `openchoreoApi.containerSecurityContext.capabilities.drop` | Capabilities to drop | `array` | | +| `openchoreoApi.containerSecurityContext.readOnlyRootFilesystem` | Read-only root filesystem | `boolean` | `false` | +| `openchoreoApi.containerSecurityContext.seccompProfile.type` | Seccomp profile type | `object` | `RuntimeDefault` | +| `openchoreoApi.database.path` | Path to the SQLite database file | `string` | `/var/lib/openchoreo/data/controlplane.db` | +| `openchoreoApi.database.persistence.enabled` | Enable persistent storage for the database | `boolean` | `true` | +| `openchoreoApi.database.persistence.size` | Size of the persistent volume | `string` | `500Mi` | +| `openchoreoApi.database.persistence.storageClassName` | Storage class name. If empty, uses the default storage class | `string` | | +| `openchoreoApi.enabled` | Enable the OpenChoreo API server | `boolean` | `true` | +| `openchoreoApi.image.pullPolicy` | Image pull policy | `object` | `IfNotPresent` | +| `openchoreoApi.image.repository` | Docker image repository | `string` | `ghcr.io/openchoreo/openchoreo-api` | +| `openchoreoApi.image.tag` | Image tag. If empty, uses Chart.AppVersion | `string` | | +| `openchoreoApi.ingress.annotations` | Ingress annotations | `object` | `{}` | +| `openchoreoApi.ingress.enabled` | Enable ingress | `boolean` | `true` | +| `openchoreoApi.ingress.hosts` | Ingress hosts. If empty, derives from global.baseDomain | `array` | `[]` | +| `openchoreoApi.ingress.ingressClassName` | Ingress class name. If empty, uses global.ingressClassName | `string` | | +| `openchoreoApi.ingress.tls` | Ingress TLS configuration | `array` | `[]` | +| `openchoreoApi.logLevel` | Log level for the API server | `object` | `info` | +| `openchoreoApi.mcp.toolsets` | Comma-separated list of enabled MCP toolsets | `string` | `organization,project,component,build,deployment,infrastructure` | +| `openchoreoApi.metrics.enabled` | Enable Prometheus metrics | `boolean` | `true` | +| `openchoreoApi.metrics.serviceMonitor.enabled` | Create ServiceMonitor resource | `boolean` | `false` | +| `openchoreoApi.metrics.serviceMonitor.interval` | Scrape interval | `string` | `30s` | +| `openchoreoApi.metrics.serviceMonitor.labels.prometheus` | | `string` | `kube-prometheus` | +| `openchoreoApi.metrics.serviceMonitor.namespace` | Namespace for ServiceMonitor | `string` | `monitoring` | +| `openchoreoApi.metrics.serviceMonitor.relabelings` | Metric relabeling rules | `array` | `[]` | +| `openchoreoApi.metrics.serviceMonitor.scrapeTimeout` | Scrape timeout | `string` | `10s` | +| `openchoreoApi.name` | Static name for all openchoreo-api resources (Service, Deployment, ClusterRole, etc.) | `string` | `openchoreo-api` | +| `openchoreoApi.networkPolicy.egress` | Egress rules | `array` | `[]` | +| `openchoreoApi.networkPolicy.enabled` | Enable NetworkPolicy | `boolean` | `false` | +| `openchoreoApi.networkPolicy.ingress` | Ingress rules | `array` | `[]` | +| `openchoreoApi.nodeSelector` | Node selector | `object` | `{}` | +| `openchoreoApi.podDisruptionBudget.enabled` | Enable PodDisruptionBudget | `boolean` | `false` | +| `openchoreoApi.podDisruptionBudget.minAvailable` | Minimum available pods | `integer` | `1` | +| `openchoreoApi.podSecurityContext.fsGroup` | Filesystem group | `integer` | `1000` | +| `openchoreoApi.podSecurityContext.runAsGroup` | Group ID | `integer` | `1000` | +| `openchoreoApi.podSecurityContext.runAsNonRoot` | Run as non-root user | `boolean` | `true` | +| `openchoreoApi.podSecurityContext.runAsUser` | User ID | `integer` | `1000` | +| `openchoreoApi.podSecurityContext.seccompProfile.type` | Seccomp profile type | `object` | `RuntimeDefault` | +| `openchoreoApi.priorityClass.create` | Create a priority class | `boolean` | `false` | +| `openchoreoApi.priorityClass.name` | Priority class name | `string` | `openchoreo-api` | +| `openchoreoApi.priorityClass.value` | Priority class value | `integer` | `900000` | +| `openchoreoApi.replicas` | Number of API server replicas | `integer` | `1` | +| `openchoreoApi.resources.limits.cpu` | CPU limit | `string` | `1000m` | +| `openchoreoApi.resources.limits.memory` | Memory limit | `string` | `1Gi` | +| `openchoreoApi.resources.requests.cpu` | CPU request | `string` | `200m` | +| `openchoreoApi.resources.requests.memory` | Memory request | `string` | `256Mi` | +| `openchoreoApi.security.userTypes` | User type definitions for authorization | `array` | | +| `openchoreoApi.serverBaseUrl` | Base URL for the API server (used for OAuth metadata). If not set, defaults to protocol://api.baseDomain:port | `string` | | +| `openchoreoApi.service.nodePort` | NodePort (only used if service.type is NodePort) | `integer,null` | `null` | +| `openchoreoApi.service.port` | Service port | `integer` | `8080` | +| `openchoreoApi.service.type` | Service type | `object` | `ClusterIP` | +| `openchoreoApi.serviceAccount.annotations` | Annotations to add to the service account | `object` | `{}` | +| `openchoreoApi.serviceAccount.name` | Service account name (always created when openchoreoApi.enabled is true) | `string` | `openchoreo-api` | +| `openchoreoApi.tolerations` | Tolerations | `array` | `[]` | +| `openchoreoApi.topologySpreadConstraints` | Topology spread constraints | `array` | | + +## Security + +Common security configuration shared across all components + +| Parameter | Description | Type | Default | +| :--- | :--- | :--- | :--- | +| `security.authServerBaseUrl` | Base URL for the authorization server (used for OAuth metadata). If not set, defaults to protocol://thunder.baseDomain:port | `string` | | +| `security.authz.databasePath` | Path to the Casbin database file | `string` | `/var/lib/openchoreo/data/casbin.db` | +| `security.authz.defaultAuthzDataFilePath` | Path to custom authz data file (roles and mappings). If not set, embedded defaults are used. To use custom data, set this path and mount a ConfigMap | `string` | `/etc/openchoreo/authz/default-roles-mappings.yaml` | +| `security.authz.enabled` | Enable authorization using Casbin | `boolean` | `false` | +| `security.enabled` | Global security toggle - when disabled, authentication is turned off for all components | `boolean` | `true` | +| `security.jwt.audience` | Expected audience claim in JWT tokens | `string` | | +| `security.oidc.authorizationUrl` | OIDC authorization endpoint URL | `string` | | +| `security.oidc.issuer` | OIDC provider issuer URL | `string` | | +| `security.oidc.jwksUrl` | OIDC JWKS URL for token validation | `string` | | +| `security.oidc.tokenUrl` | OIDC token endpoint URL | `string` | | +| `security.oidc.wellKnownEndpoint` | OIDC well-known configuration endpoint URL | `string` | | + +## Thunder + +For full configuration options, please refer to the [official chart documentation](oci://ghcr.io/asgardeo/helm-charts). + +Asgardeo Thunder (Platform Identity Provider) configuration + +| Parameter | Description | Type | Default | +| :--- | :--- | :--- | :--- | +| `thunder.bootstrap.configMap.files` | Bootstrap script files to run | `array` | | +| `thunder.bootstrap.configMap.name` | ConfigMap name containing bootstrap scripts | `string` | `openchoreo-thunder-bootstrap` | +| `thunder.bootstrap.defaultApps` | Default OAuth applications to create during bootstrap | `array` | | +| `thunder.bootstrap.defaultUsers` | Default users to create during bootstrap | `array` | | +| `thunder.bootstrap.enabled` | Enable bootstrap scripts | `boolean` | `true` | +| `thunder.bootstrap.rcaAgentClient.clientId` | | `string` | `openchoreo-rca-agent` | +| `thunder.bootstrap.rcaAgentClient.clientSecret` | | `string` | `openchoreo-rca-agent-secret` | +| `thunder.configuration.cache.cleanupInterval` | Cache cleanup interval in seconds | `integer` | `300` | +| `thunder.configuration.cache.disabled` | Disable caching | `boolean` | `false` | +| `thunder.configuration.cache.evictionPolicy` | Cache eviction policy | `object` | `LRU` | +| `thunder.configuration.cache.size` | Maximum cache size | `integer` | `1000` | +| `thunder.configuration.cache.ttl` | Cache TTL in seconds | `integer` | `3600` | +| `thunder.configuration.cache.type` | Cache type | `object` | `inmemory` | +| `thunder.configuration.cors.allowedOrigins` | Allowed origins for CORS | `array` | | +| `thunder.configuration.database.identity.sqliteOptions` | SQLite connection options | `string` | `_journal_mode=WAL&_busy_timeout=5000` | +| `thunder.configuration.database.identity.sqlitePath` | SQLite database file path | `string` | `repository/database/thunderdb.db` | +| `thunder.configuration.database.identity.type` | Database type | `object` | `sqlite` | +| `thunder.configuration.database.runtime.sqliteOptions` | SQLite connection options | `string` | `_journal_mode=WAL&_busy_timeout=5000` | +| `thunder.configuration.database.runtime.sqlitePath` | SQLite database file path | `string` | `repository/database/runtimedb.db` | +| `thunder.configuration.database.runtime.type` | Database type | `object` | `sqlite` | +| `thunder.configuration.database.user.sqliteOptions` | SQLite connection options | `string` | `_journal_mode=WAL&_busy_timeout=5000` | +| `thunder.configuration.database.user.sqlitePath` | SQLite database file path | `string` | `repository/database/userdb.db` | +| `thunder.configuration.database.user.type` | Database type | `object` | `sqlite` | +| `thunder.configuration.flow.authn.defaultFlow` | Default authentication flow | `string` | `auth_flow_config_basic` | +| `thunder.configuration.flow.graphDirectory` | Directory containing flow graph definitions | `string` | `repository/resources/graphs/` | +| `thunder.configuration.gateClient.errorPath` | Error path | `string` | `/gate/error` | +| `thunder.configuration.gateClient.hostname` | Gate client hostname | `string` | | +| `thunder.configuration.gateClient.loginPath` | Login path | `string` | `/gate/signin` | +| `thunder.configuration.gateClient.port` | Gate client port | `integer` | `8080` | +| `thunder.configuration.gateClient.scheme` | Protocol scheme | `object` | `http` | +| `thunder.configuration.jwt.audience` | Token audience | `string` | `application` | +| `thunder.configuration.jwt.issuer` | JWT issuer name | `string` | `thunder` | +| `thunder.configuration.jwt.validityPeriod` | Token validity period in seconds | `integer` | `3600` | +| `thunder.configuration.oauth.refreshToken.renewOnGrant` | Renew refresh token on grant | `boolean` | `false` | +| `thunder.configuration.oauth.refreshToken.validityPeriod` | Refresh token validity period in seconds | `integer` | `86400` | +| `thunder.configuration.security.certFile` | Server certificate file path | `string` | `repository/resources/security/server.cert` | +| `thunder.configuration.security.cryptoFile` | Crypto key file path | `string` | `repository/resources/security/crypto.key` | +| `thunder.configuration.security.keyFile` | Server private key file path | `string` | `repository/resources/security/server.key` | +| `thunder.configuration.server.httpOnly` | HTTP-only mode (no HTTPS termination at Thunder) | `boolean` | `true` | +| `thunder.configuration.server.port` | Server port | `integer` | `8090` | +| `thunder.configuration.server.publicUrl` | Public URL for Thunder. If empty, auto-derived from global.baseDomain | `string` | | +| `thunder.deployment.container.port` | Container port | `integer` | `8090` | +| `thunder.deployment.image.pullPolicy` | Image pull policy | `object` | `IfNotPresent` | +| `thunder.deployment.image.registry` | Image registry | `string` | `ghcr.io/asgardeo` | +| `thunder.deployment.image.repository` | Image repository | `string` | `thunder` | +| `thunder.deployment.image.tag` | Image tag | `string` | `0.15.0` | +| `thunder.deployment.replicaCount` | Number of Thunder replicas | `integer` | `1` | +| `thunder.deployment.resources.limits.cpu` | CPU limit | `string` | `500m` | +| `thunder.deployment.resources.limits.memory` | Memory limit | `string` | `512Mi` | +| `thunder.deployment.resources.requests.cpu` | CPU request | `string` | `100m` | +| `thunder.deployment.resources.requests.memory` | Memory request | `string` | `128Mi` | +| `thunder.deployment.securityContext.enableRunAsUser` | Enable run as user | `boolean` | `true` | +| `thunder.deployment.securityContext.fsGroup` | Filesystem group | `integer` | `802` | +| `thunder.deployment.securityContext.readOnlyRootFilesystem` | Read-only root filesystem. Must be false for SQLite | `boolean` | `false` | +| `thunder.deployment.securityContext.runAsUser` | User ID | `integer` | `802` | +| `thunder.deployment.securityContext.seccompProfile.enabled` | Enable seccomp profile | `boolean` | `true` | +| `thunder.deployment.securityContext.seccompProfile.type` | Seccomp profile type | `object` | `RuntimeDefault` | +| `thunder.deployment.strategy.rollingUpdate.maxSurge` | Maximum surge pods during update | `integer` | `1` | +| `thunder.deployment.strategy.rollingUpdate.maxUnavailable` | Maximum unavailable pods during update | `integer` | `0` | +| `thunder.deployment.terminationGracePeriodSeconds` | Termination grace period in seconds | `integer` | `10` | +| `thunder.enabled` | Enable Thunder identity provider deployment | `boolean` | `true` | +| `thunder.fullnameOverride` | Override the Thunder release name | `string` | `thunder` | +| `thunder.hpa.enabled` | Enable HPA | `boolean` | `false` | +| `thunder.ingress.annotations` | Ingress annotations | `object` | `{}` | +| `thunder.ingress.enabled` | Enable standard ingress | `boolean` | `false` | +| `thunder.ingress.hosts` | Ingress hosts | `array` | `[]` | +| `thunder.ingress.ingressClassName` | Ingress class name | `string` | | +| `thunder.ingress.tls` | Ingress TLS configuration | `array` | `[]` | +| `thunder.ocIngress.annotations` | Ingress annotations | `object` | `{}` | +| `thunder.ocIngress.enabled` | Enable OpenChoreo ingress | `boolean` | `true` | +| `thunder.ocIngress.hosts` | Ingress hosts. If empty, derives from global.baseDomain | `array` | `[]` | +| `thunder.ocIngress.ingressClassName` | Ingress class name. If empty, uses global.ingressClassName | `string` | | +| `thunder.ocIngress.tls` | Ingress TLS configuration | `array` | `[]` | +| `thunder.pdb.minAvailable` | Minimum available pods (percentage or number) | `string` | `50%` | +| `thunder.persistence.accessMode` | Access mode for the persistent volume | `object` | `ReadWriteOnce` | +| `thunder.persistence.annotations` | Annotations for the PVC | `object` | `{}` | +| `thunder.persistence.enabled` | Enable persistent storage | `boolean` | `true` | +| `thunder.persistence.size` | Size of the persistent volume | `string` | `1Gi` | +| `thunder.persistence.storageClass` | Storage class name. If empty, uses default storage class | `string` | | +| `thunder.service.port` | Service port | `integer` | `8090` | +| `thunder.serviceAccount.create` | Create service account | `boolean` | `true` | +| `thunder.serviceAccount.name` | Service account name | `string` | `thunder-service-account` | +| `thunder.setup.backoffLimit` | Job backoff limit (retry count) | `integer` | `3` | +| `thunder.setup.debug` | Enable debug mode for setup job | `boolean` | `false` | +| `thunder.setup.enabled` | Enable the setup job | `boolean` | `true` | +| `thunder.setup.preserveJob` | Preserve job after completion | `boolean` | `true` | +| `thunder.setup.resources.limits.cpu` | CPU limit | `string` | `500m` | +| `thunder.setup.resources.limits.memory` | Memory limit | `string` | `256Mi` | +| `thunder.setup.resources.requests.cpu` | CPU request | `string` | `250m` | +| `thunder.setup.resources.requests.memory` | Memory request | `string` | `128Mi` | +| `thunder.setup.ttlSecondsAfterFinished` | Job retention time in seconds after completion (24 hours) | `integer` | `86400` | + +## Wait Job + +Wait job configuration for Helm hooks + +| Parameter | Description | Type | Default | +| :--- | :--- | :--- | :--- | +| `waitJob.image` | Container image for wait jobs | `string` | `bitnamilegacy/kubectl:1.32.4` | + +## Webhook Service + +Webhook service configuration + +| Parameter | Description | Type | Default | +| :--- | :--- | :--- | :--- | +| `webhookService.ports` | Ports exposed by the webhook service | `array` | | +| `webhookService.type` | Service type | `object` | `ClusterIP` | + diff --git a/versioned_docs/version-v0.11.x/reference/helm/data-plane.mdx b/versioned_docs/version-v0.11.x/reference/helm/data-plane.mdx new file mode 100644 index 0000000..99603ab --- /dev/null +++ b/versioned_docs/version-v0.11.x/reference/helm/data-plane.mdx @@ -0,0 +1,330 @@ +--- +title: Data Plane +description: Helm chart values reference for openchoreo-data-plane. +sidebar_position: 2 +--- + +## Dependencies + +This chart depends on the following sub-charts. For full configuration options of each dependency, please refer to their official documentation. + +| Name | Version | Repository | Condition | +| :--- | :--- | :--- | :--- | +| [external-secrets](https://charts.external-secrets.io) | 0.19.2 | [https://charts.external-secrets.io](https://charts.external-secrets.io) | `external-secrets.enabled` | +| [fluent-bit](https://fluent.github.io/helm-charts) | 0.54.0 | [https://fluent.github.io/helm-charts](https://fluent.github.io/helm-charts) | `fluent-bit.enabled` | +| [kgateway-crds](oci://cr.kgateway.dev/kgateway-dev/charts) | v2.1.1 | oci://cr.kgateway.dev/kgateway-dev/charts | `gatewayController.enabled` | +| [kgateway](oci://cr.kgateway.dev/kgateway-dev/charts) | v2.1.1 | oci://cr.kgateway.dev/kgateway-dev/charts | `gatewayController.enabled` | +| [kube-prometheus-stack](https://prometheus-community.github.io/helm-charts) | 78.3.0 | [https://prometheus-community.github.io/helm-charts](https://prometheus-community.github.io/helm-charts) | `kube-prometheus-stack.enabled` | +| [opentelemetry-collector](https://open-telemetry.github.io/opentelemetry-helm-charts) | 0.140.0 | [https://open-telemetry.github.io/opentelemetry-helm-charts](https://open-telemetry.github.io/opentelemetry-helm-charts) | `opentelemetry-collector.enabled` | +| [gateway-operator](oci://ghcr.io/wso2/api-platform/helm-charts) | 0.1.0 | oci://ghcr.io/wso2/api-platform/helm-charts | `api-platform.enabled` | + +## Api Platform + +For full configuration options, please refer to the [official chart documentation](oci://ghcr.io/wso2/api-platform/helm-charts). + +WSO2 API Platform configuration for advanced API management capabilities + +| Parameter | Description | Type | Default | +| :--- | :--- | :--- | :--- | +| `api-platform.enabled` | Enable WSO2 API Platform gateway operator | `boolean` | `false` | +| `api-platform.gateway.helm.chartName` | OCI chart reference for the API Platform gateway | `string` | `oci://ghcr.io/wso2/api-platform/helm-charts/gateway` | +| `api-platform.gateway.values.gateway.config.policy_configurations.JWTAuth_v010.AllowedAlgorithms` | Allowed JWT signing algorithms | `array` | `["RS256","ES256"]` | +| `api-platform.gateway.values.gateway.config.policy_configurations.JWTAuth_v010.AuthHeaderScheme` | Authorization header scheme prefix | `string` | `Bearer` | +| `api-platform.gateway.values.gateway.config.policy_configurations.JWTAuth_v010.ErrorMessage` | Error message returned on authentication failure | `string` | `Authentication failed.` | +| `api-platform.gateway.values.gateway.config.policy_configurations.JWTAuth_v010.ErrorMessageFormat` | Format for error messages | `object` | `json` | +| `api-platform.gateway.values.gateway.config.policy_configurations.JWTAuth_v010.HeaderName` | HTTP header name for JWT token | `string` | `Authorization` | +| `api-platform.gateway.values.gateway.config.policy_configurations.JWTAuth_v010.JwksCacheTtl` | Cache TTL for JWKS keys | `string` | `5m` | +| `api-platform.gateway.values.gateway.config.policy_configurations.JWTAuth_v010.JwksFetchRetryCount` | Number of retry attempts for JWKS fetch | `integer` | `3` | +| `api-platform.gateway.values.gateway.config.policy_configurations.JWTAuth_v010.JwksFetchRetryInterval` | Interval between JWKS fetch retries | `string` | `2s` | +| `api-platform.gateway.values.gateway.config.policy_configurations.JWTAuth_v010.JwksFetchTimeout` | Timeout for fetching JWKS | `string` | `5s` | +| `api-platform.gateway.values.gateway.config.policy_configurations.JWTAuth_v010.KeyManagers` | List of key managers for JWT validation | `array` | | +| `api-platform.gateway.values.gateway.config.policy_configurations.JWTAuth_v010.Leeway` | Clock skew tolerance for JWT validation | `string` | `30s` | +| `api-platform.gateway.values.gateway.config.policy_configurations.JWTAuth_v010.OnFailureStatusCode` | HTTP status code returned on authentication failure | `integer` | `401` | +| `api-platform.gateway.values.gateway.config.policy_configurations.JWTAuth_v010.ValidateIssuer` | Validate the JWT issuer claim | `boolean` | `true` | + +## Cluster Agent + +Cluster Agent configuration for WebSocket connection to control plane cluster gateway + +| Parameter | Description | Type | Default | +| :--- | :--- | :--- | :--- | +| `clusterAgent.affinity` | Affinity rules for pod scheduling | `object` | `{}` | +| `clusterAgent.dnsRewrite.enabled` | Enable CoreDNS rewrite of *.openchoreo.localhost to host.k3d.internal | `boolean` | `false` | +| `clusterAgent.enabled` | Enable the cluster agent deployment | `boolean` | `true` | +| `clusterAgent.heartbeatInterval` | Interval between heartbeat messages to control plane | `string` | `30s` | +| `clusterAgent.image.pullPolicy` | Image pull policy | `object` | `IfNotPresent` | +| `clusterAgent.image.repository` | Cluster agent image repository | `string` | `ghcr.io/openchoreo/cluster-agent` | +| `clusterAgent.image.tag` | Image tag. Empty uses Chart.AppVersion. | `string` | | +| `clusterAgent.logLevel` | Log level for cluster agent | `object` | `info` | +| `clusterAgent.name` | Name of the cluster agent deployment | `string` | `cluster-agent-dataplane` | +| `clusterAgent.nodeSelector` | Node selector for pod scheduling | `object` | `{}` | +| `clusterAgent.planeID` | Logical plane identifier shared across multiple CRs connecting to the same physical plane. Defaults to Helm release name if not specified. | `string` | `default-dataplane` | +| `clusterAgent.planeType` | Type of plane this agent manages | `object` | `dataplane` | +| `clusterAgent.podAnnotations` | Annotations to add to cluster agent pods | `object` | `{}` | +| `clusterAgent.podSecurityContext.fsGroup` | Group ID for volume mounts | `integer` | `1000` | +| `clusterAgent.podSecurityContext.runAsNonRoot` | Run container as non-root user | `boolean` | `true` | +| `clusterAgent.podSecurityContext.runAsUser` | User ID to run container as | `integer` | `1000` | +| `clusterAgent.priorityClass.create` | Create a PriorityClass for cluster agent | `boolean` | `false` | +| `clusterAgent.priorityClass.name` | PriorityClass name | `string` | `cluster-agent-dataplane` | +| `clusterAgent.priorityClass.value` | Priority value (higher = more important) | `integer` | `900000` | +| `clusterAgent.rbac.create` | Create RBAC resources (ClusterRole, ClusterRoleBinding) | `boolean` | `true` | +| `clusterAgent.reconnectDelay` | Delay before attempting reconnection after disconnect | `string` | `5s` | +| `clusterAgent.replicas` | Number of cluster agent replicas (typically 1 per data plane) | `integer` | `1` | +| `clusterAgent.resources.limits.cpu` | CPU limit for the agent | `string` | `100m` | +| `clusterAgent.resources.limits.memory` | Memory limit for the agent | `string` | `256Mi` | +| `clusterAgent.resources.requests.cpu` | CPU request for the agent | `string` | `50m` | +| `clusterAgent.resources.requests.memory` | Memory request for the agent | `string` | `128Mi` | +| `clusterAgent.securityContext.allowPrivilegeEscalation` | Prevent privilege escalation | `boolean` | `false` | +| `clusterAgent.securityContext.capabilities.drop` | Capabilities to drop from container | `array` | `["ALL"]` | +| `clusterAgent.securityContext.readOnlyRootFilesystem` | Mount root filesystem as read-only | `boolean` | `true` | +| `clusterAgent.serverCANamespace` | Namespace where cluster-gateway CA exists (control plane namespace) | `string` | `openchoreo-control-plane` | +| `clusterAgent.serverUrl` | WebSocket URL of the cluster gateway in control plane | `string` | `wss://cluster-gateway.openchoreo-control-plane.svc.cluster.local:8443/ws` | +| `clusterAgent.serviceAccount.annotations` | Annotations to add to the service account | `object` | `{}` | +| `clusterAgent.serviceAccount.create` | Create a service account for the cluster agent | `boolean` | `true` | +| `clusterAgent.serviceAccount.name` | Service account name | `string` | `cluster-agent-dataplane` | +| `clusterAgent.tls.caSecretName` | CA secret name for signing agent client certificates. If empty, self-signed certs will be generated (required for multi-cluster setup). | `string` | `cluster-gateway-ca` | +| `clusterAgent.tls.caSecretNamespace` | Namespace where the CA secret exists. If empty, self-signed certs will be generated (required for multi-cluster setup). | `string` | `openchoreo-control-plane` | +| `clusterAgent.tls.caValue` | Inline CA certificate in PEM format (for multi-cluster setup). Takes precedence over caSecretName/caSecretNamespace. | `string` | | +| `clusterAgent.tls.clientSecretName` | Secret name for client certificate (typically same as secretName) | `string` | `cluster-agent-tls` | +| `clusterAgent.tls.duration` | Certificate validity duration | `string` | `2160h` | +| `clusterAgent.tls.enabled` | Enable TLS for agent-gateway communication | `boolean` | `true` | +| `clusterAgent.tls.generateCerts` | Generate client certificates locally using cert-manager (for multi-cluster setups where data plane is in different cluster) | `boolean` | `false` | +| `clusterAgent.tls.renewBefore` | Time before expiry to renew certificate | `string` | `360h` | +| `clusterAgent.tls.secretName` | Secret name for client certificate and key | `string` | `cluster-agent-tls` | +| `clusterAgent.tls.serverCAConfigMap` | ConfigMap name containing server CA certificate for verifying gateway | `string` | `cluster-gateway-ca` | +| `clusterAgent.tls.serverCAValue` | Inline server CA certificate in PEM format (for multi-cluster setup). Takes precedence over copying from control plane. | `string` | | +| `clusterAgent.tolerations` | Tolerations for pod scheduling | `array` | `[]` | + +## External Secrets + +For full configuration options, please refer to the [official chart documentation](https://charts.external-secrets.io). + +External Secrets Operator configuration for syncing secrets from external secret stores (Vault, AWS Secrets Manager, etc.) + +| Parameter | Description | Type | Default | +| :--- | :--- | :--- | :--- | +| `external-secrets.enabled` | Enable External Secrets Operator for production secret management | `boolean` | `false` | +| `external-secrets.fullnameOverride` | Override the full name of External Secrets resources | `string` | `external-secrets` | +| `external-secrets.nameOverride` | Override the name of External Secrets resources | `string` | `external-secrets` | + +## Fake Secret Store + +Fake Secret Store for development and testing. Replace with a real ClusterSecretStore in production. + +| Parameter | Description | Type | Default | +| :--- | :--- | :--- | :--- | +| `fakeSecretStore.enabled` | Enable the fake secret store (development only - disable in production) | `boolean` | `true` | +| `fakeSecretStore.name` | Name of the fake ClusterSecretStore resource | `string` | `default` | +| `fakeSecretStore.secrets` | List of fake secrets for development testing | `array` | | + +## Fluent Bit + +For full configuration options, please refer to the [official chart documentation](https://fluent.github.io/helm-charts). + +Fluent Bit subchart configuration for log collection and forwarding to OpenSearch + +| Parameter | Description | Type | Default | +| :--- | :--- | :--- | :--- | +| `fluent-bit.config.customParsers` | Custom parser definitions in Fluent Bit configuration format | `string` | `(multiline string)` | +| `fluent-bit.config.filters` | Filter plugin configuration for log processing | `string` | `(multiline string)` | +| `fluent-bit.config.inputs` | Input plugin configuration for log collection | `string` | `(multiline string)` | +| `fluent-bit.config.outputs` | Output plugin configuration for log forwarding to OpenSearch | `string` | `(multiline string)` | +| `fluent-bit.dnsPolicy` | DNS policy for Fluent Bit pods | `object` | `ClusterFirstWithHostNet` | +| `fluent-bit.enabled` | Enable Fluent Bit log collector deployment | `boolean` | `false` | +| `fluent-bit.extraVolumeMounts` | Extra volume mounts for the Fluent Bit container | `array` | | +| `fluent-bit.extraVolumes` | Extra volumes for the Fluent Bit pod | `array` | | +| `fluent-bit.fullnameOverride` | Override the full name of Fluent Bit resources | `string` | `fluent-bit` | +| `fluent-bit.hostNetwork` | Use host network for Fluent Bit pods (required for node log access) | `boolean` | `true` | +| `fluent-bit.initContainers` | Init containers for the Fluent Bit pod (used to set volume ownership) | `array` | | +| `fluent-bit.metricsPort` | Port for Fluent Bit metrics endpoint | `integer` | `2021` | +| `fluent-bit.rbac.nodeAccess` | Enable node-level access for reading container logs | `boolean` | `true` | +| `fluent-bit.resources.limits.cpu` | CPU limit for Fluent Bit | `string` | `200m` | +| `fluent-bit.resources.limits.memory` | Memory limit for Fluent Bit | `string` | `256Mi` | +| `fluent-bit.resources.requests.cpu` | CPU request for Fluent Bit | `string` | `100m` | +| `fluent-bit.resources.requests.memory` | Memory request for Fluent Bit | `string` | `128Mi` | +| `fluent-bit.securityContext.allowPrivilegeEscalation` | Prevent privilege escalation | `boolean` | `false` | +| `fluent-bit.securityContext.capabilities.drop` | Capabilities to drop | `array` | | +| `fluent-bit.securityContext.readOnlyRootFilesystem` | Mount root filesystem as read-only | `boolean` | `true` | +| `fluent-bit.securityContext.runAsNonRoot` | Run container as non-root user | `boolean` | `true` | +| `fluent-bit.securityContext.runAsUser` | User ID to run the container | `integer` | `10000` | +| `fluent-bit.service.port` | Service port for Fluent Bit metrics | `integer` | `2021` | +| `fluent-bit.testFramework.enabled` | Enable Fluent Bit test framework | `boolean` | `false` | + +## Gateway + +For full configuration options, please refer to the [official chart documentation](oci://cr.kgateway.dev/kgateway-dev/charts). + +KGateway API gateway configuration. Provides HTTP/HTTPS traffic routing using Kubernetes Gateway API and Envoy proxy. + +| Parameter | Description | Type | Default | +| :--- | :--- | :--- | :--- | +| `gateway.agentgateway.enabled` | Enable Agent Gateway for AI agent connectivity | `boolean` | `false` | +| `gateway.controller.image.pullPolicy` | Image pull policy for the controller container | `object` | `IfNotPresent` | +| `gateway.controller.image.registry` | Container registry for the controller image. Empty uses default registry. | `string` | | +| `gateway.controller.image.repository` | Image repository name for the gateway controller | `string` | `kgateway` | +| `gateway.controller.image.tag` | Image tag. Empty uses Chart.AppVersion. | `string` | | +| `gateway.controller.logLevel` | Log level for the gateway controller | `object` | `info` | +| `gateway.controller.replicaCount` | Number of gateway controller replicas | `integer` | `1` | +| `gateway.controller.resources.limits.cpu` | CPU limit for the controller | `string` | `200m` | +| `gateway.controller.resources.limits.memory` | Memory limit for the controller | `string` | `256Mi` | +| `gateway.controller.resources.requests.cpu` | CPU request for the controller | `string` | `100m` | +| `gateway.controller.resources.requests.memory` | Memory request for the controller | `string` | `128Mi` | +| `gateway.controller.service.ports.agwGrpc` | Agent gateway gRPC port | `integer` | `9978` | +| `gateway.controller.service.ports.grpc` | gRPC port for xDS communication | `integer` | `9977` | +| `gateway.controller.service.ports.health` | Health check endpoint port | `integer` | `9093` | +| `gateway.controller.service.ports.metrics` | Metrics endpoint port | `integer` | `9092` | +| `gateway.controller.service.type` | Service type for the gateway controller | `object` | `ClusterIP` | +| `gateway.enabled` | Enable Gateway CR creation | `boolean` | `true` | +| `gateway.envoy.enabled` | Enable Envoy proxy for traffic routing | `boolean` | `true` | +| `gateway.envoy.mountTmpVolume` | Mount /tmp as emptyDir volume to fix Envoy temporary file creation issues on macOS with Docker Desktop/Colima | `boolean` | `false` | +| `gateway.httpPort` | Port for the HTTP listener on the gateway | `integer` | `9080` | +| `gateway.httpsPort` | Port for the HTTPS listener on the gateway | `integer` | `9443` | +| `gateway.image.pullPolicy` | Image pull policy for gateway containers | `object` | `IfNotPresent` | +| `gateway.image.registry` | Container registry for gateway images | `string` | `cr.kgateway.dev/kgateway-dev` | +| `gateway.image.tag` | Image tag. Empty uses Chart.AppVersion. | `string` | | +| `gateway.selfSignedIssuer.enabled` | Create self-signed ClusterIssuer (set to false in single cluster mode) | `boolean` | `true` | +| `gateway.tls.certName` | Kubernetes Secret name for storing the TLS certificate | `string` | `openchoreo-gateway-tls` | +| `gateway.tls.clusterIssuer` | Cert-manager ClusterIssuer name for certificate generation. Defaults to openchoreo-selfsigned-issuer if empty. | `string` | | +| `gateway.tls.hostname` | Hostname pattern for the HTTPS listener certificate | `string` | `*.openchoreoapis.localhost` | + +## Gateway Controller + +KGateway controller configuration + +| Parameter | Description | Type | Default | +| :--- | :--- | :--- | :--- | +| `gatewayController.enabled` | Enable kgateway controller installation (set to false in single cluster mode for data-plane) | `boolean` | `true` | + +## Global + +Global values shared across all components in the data plane + +| Parameter | Description | Type | Default | +| :--- | :--- | :--- | :--- | +| `global.commonLabels` | Common labels applied to all resources deployed by this chart | `object` | `{}` | + +## Kgateway Crds + +For full configuration options, please refer to the [official chart documentation](oci://cr.kgateway.dev/kgateway-dev/charts). + +KGateway CRDs subchart configuration (values passed through to kgateway-crds) + +| Parameter | Description | Type | Default | +| :--- | :--- | :--- | :--- | +| `kgateway-crds` | KGateway CRDs subchart configuration (values passed through to kgateway-crds) | `object` | | + +## Kube Prometheus Stack + +For full configuration options, please refer to the [official chart documentation](https://prometheus-community.github.io/helm-charts). + +Prometheus stack configuration (kube-prometheus-stack sub-chart). Provides metrics collection for workload observability. + +| Parameter | Description | Type | Default | +| :--- | :--- | :--- | :--- | +| `kube-prometheus-stack.alertmanager.enabled` | Enable Alertmanager for alert management (not used by OpenChoreo) | `boolean` | `false` | +| `kube-prometheus-stack.cleanPrometheusOperatorObjectNames` | Produce cleaner resource names without redundant prefixes | `boolean` | `true` | +| `kube-prometheus-stack.coreDns.enabled` | Enable CoreDNS metrics collection | `boolean` | `false` | +| `kube-prometheus-stack.crds.enabled` | Install Prometheus Operator CRDs (ServiceMonitor, PodMonitor, etc.) | `boolean` | `true` | +| `kube-prometheus-stack.defaultRules.create` | Create default alerting rules (disabled - OpenChoreo uses custom rules) | `boolean` | `false` | +| `kube-prometheus-stack.enabled` | Enable the Prometheus monitoring stack for metrics collection | `boolean` | `false` | +| `kube-prometheus-stack.fullnameOverride` | Override the full name of Prometheus stack resources | `string` | `openchoreo-observability` | +| `kube-prometheus-stack.grafana.enabled` | Enable Grafana dashboards (not used by OpenChoreo - use observability plane instead) | `boolean` | `false` | +| `kube-prometheus-stack.kube-state-metrics.collectors` | Kubernetes resource types to collect metrics from | `array` | `["pods"]` | +| `kube-prometheus-stack.kube-state-metrics.fullnameOverride` | Override the full name of kube-state-metrics resources | `string` | `kube-state-metrics` | +| `kube-prometheus-stack.kube-state-metrics.metricAllowlist` | Specific metrics to collect (allowlist filter) | `array` | | +| `kube-prometheus-stack.kube-state-metrics.metricLabelsAllowlist` | Pod labels to include in metrics for filtering by OpenChoreo resources | `array` | | +| `kube-prometheus-stack.kubeApiServer.enabled` | Enable API server metrics collection | `boolean` | `false` | +| `kube-prometheus-stack.kubeControllerManager.enabled` | Enable controller manager metrics collection | `boolean` | `false` | +| `kube-prometheus-stack.kubeEtcd.enabled` | Enable etcd metrics collection | `boolean` | `false` | +| `kube-prometheus-stack.kubeProxy.enabled` | Enable kube-proxy metrics collection | `boolean` | `false` | +| `kube-prometheus-stack.kubeScheduler.enabled` | Enable scheduler metrics collection | `boolean` | `false` | +| `kube-prometheus-stack.nodeExporter.enabled` | Enable node-level metrics collection | `boolean` | `false` | +| `kube-prometheus-stack.prometheus.agentMode` | Run Prometheus in agent mode for lightweight remote-write only operation | `boolean` | `true` | +| `kube-prometheus-stack.prometheus.enabled` | Deploy a Prometheus instance (requires Prometheus Operator) | `boolean` | `true` | +| `kube-prometheus-stack.prometheus.prometheusSpec.remoteWrite` | Remote write endpoints for forwarding metrics to external storage | `array` | | +| `kube-prometheus-stack.prometheusOperator.enabled` | Enable Prometheus Operator for managing Prometheus instances | `boolean` | `true` | +| `kube-prometheus-stack.prometheusOperator.fullnameOverride` | Override the full name of Prometheus Operator resources | `string` | `prometheus-operator` | +| `kube-prometheus-stack.prometheusOperator.resources.limits.cpu` | CPU limit for Prometheus Operator | `string` | `40m` | +| `kube-prometheus-stack.prometheusOperator.resources.limits.memory` | Memory limit for Prometheus Operator | `string` | `50Mi` | +| `kube-prometheus-stack.prometheusOperator.resources.requests.cpu` | CPU request for Prometheus Operator | `string` | `20m` | +| `kube-prometheus-stack.prometheusOperator.resources.requests.memory` | Memory request for Prometheus Operator | `string` | `30Mi` | + +## Kubernetes Cluster Domain + +Kubernetes cluster DNS domain used for service discovery and certificate generation + +| Parameter | Description | Type | Default | +| :--- | :--- | :--- | :--- | +| `kubernetesClusterDomain` | Kubernetes cluster DNS domain used for service discovery and certificate generation | `string` | `cluster.local` | + +## Networking + +Network configuration for the data plane + +| Parameter | Description | Type | Default | +| :--- | :--- | :--- | :--- | +| `networking.enabled` | Enable networking features (network policies, service mesh integration) | `boolean` | `true` | + +## Observability + +Observability configuration controlling metrics, logging, and tracing collection + +| Parameter | Description | Type | Default | +| :--- | :--- | :--- | :--- | +| `observability.enabled` | Master switch for all observability features | `boolean` | `true` | +| `observability.logging.enabled` | Enable log collection. Set to true after observability plane is installed. | `boolean` | `false` | +| `observability.logging.publishers.fluentbit.enabled` | Enable Fluent Bit as the log publisher | `boolean` | `true` | +| `observability.metrics.enabled` | Enable metrics collection. Set to true after observability plane is installed. | `boolean` | `false` | +| `observability.observabilityPlaneUrl` | URL of the observability plane for sending telemetry data (OTLP endpoint) | `string` | | + +## Opentelemetry Collector + +For full configuration options, please refer to the [official chart documentation](https://open-telemetry.github.io/opentelemetry-helm-charts). + +OpenTelemetry Collector configuration for trace and metrics collection + +| Parameter | Description | Type | Default | +| :--- | :--- | :--- | :--- | +| `opentelemetry-collector.clusterRole.create` | Create ClusterRole for OpenTelemetry Collector | `boolean` | `true` | +| `opentelemetry-collector.clusterRole.rules` | RBAC rules for accessing Kubernetes API resources | `array` | | +| `opentelemetry-collector.configMap.create` | Create a new ConfigMap (false to use existing) | `boolean` | `false` | +| `opentelemetry-collector.configMap.existingName` | Name of existing ConfigMap containing collector configuration | `string` | `opentelemetry-collector-config` | +| `opentelemetry-collector.enabled` | Enable OpenTelemetry Collector deployment | `boolean` | `false` | +| `opentelemetry-collector.fullnameOverride` | Override the full name of OpenTelemetry Collector resources | `string` | `opentelemetry-collector` | +| `opentelemetry-collector.image.repository` | OpenTelemetry Collector image repository (contrib version includes extra receivers/exporters) | `string` | `otel/opentelemetry-collector-contrib` | +| `opentelemetry-collector.mode` | Deployment mode for the collector | `object` | `deployment` | +| `opentelemetry-collector.resources.limits.cpu` | CPU limit for the collector | `string` | `100m` | +| `opentelemetry-collector.resources.limits.memory` | Memory limit for the collector | `string` | `200Mi` | +| `opentelemetry-collector.resources.requests.cpu` | CPU request for the collector | `string` | `50m` | +| `opentelemetry-collector.resources.requests.memory` | Memory request for the collector | `string` | `100Mi` | + +## Registry + +[DEPRECATED] Container registry configuration. Registry has been moved to Build Plane. + +| Parameter | Description | Type | Default | +| :--- | :--- | :--- | :--- | +| `registry.enabled` | [DEPRECATED] Enable the container registry. Use Build Plane registry instead. | `boolean` | `false` | +| `registry.resources.limits.cpu` | CPU limit for the registry | `string` | `100m` | +| `registry.resources.limits.memory` | Memory limit for the registry | `string` | `256Mi` | +| `registry.resources.requests.cpu` | CPU request for the registry | `string` | `50m` | +| `registry.resources.requests.memory` | Memory request for the registry | `string` | `128Mi` | +| `registry.service.nodePort` | NodePort for external access to the registry | `integer` | `30003` | +| `registry.storage.size` | Size of the persistent volume for storing container images | `string` | `2Gi` | + +## Security + +Security configuration for the data plane + +| Parameter | Description | Type | Default | +| :--- | :--- | :--- | :--- | +| `security.enabled` | Enable security features (certificate issuers, TLS configuration) | `boolean` | `true` | + +## Wait Job + +Wait job configuration for post-install Helm hooks that wait for resources + +| Parameter | Description | Type | Default | +| :--- | :--- | :--- | :--- | +| `waitJob.image` | Container image for kubectl-based wait jobs used in Helm hooks | `string` | `bitnamilegacy/kubectl:1.32.4` | + diff --git a/versioned_docs/version-v0.11.x/reference/helm/observability-plane.mdx b/versioned_docs/version-v0.11.x/reference/helm/observability-plane.mdx new file mode 100644 index 0000000..9402c28 --- /dev/null +++ b/versioned_docs/version-v0.11.x/reference/helm/observability-plane.mdx @@ -0,0 +1,489 @@ +--- +title: Observability Plane +description: Helm chart values reference for openchoreo-observability-plane. +sidebar_position: 4 +--- + +## Dependencies + +This chart depends on the following sub-charts. For full configuration options of each dependency, please refer to their official documentation. + +| Name | Version | Repository | Condition | +| :--- | :--- | :--- | :--- | +| [data-prepper](https://opensearch-project.github.io/helm-charts/) | 0.3.1 | [https://opensearch-project.github.io/helm-charts/](https://opensearch-project.github.io/helm-charts/) | `data-prepper.enabled` | +| [external-secrets](https://charts.external-secrets.io) | 0.19.2 | [https://charts.external-secrets.io](https://charts.external-secrets.io) | `external-secrets.enabled` | +| [fluent-bit](https://fluent.github.io/helm-charts) | 0.54.0 | [https://fluent.github.io/helm-charts](https://fluent.github.io/helm-charts) | `fluent-bit.enabled` | +| [kgateway](oci://cr.kgateway.dev/kgateway-dev/charts) | v2.1.2 | oci://cr.kgateway.dev/kgateway-dev/charts | `kgateway.enabled` | +| [kube-prometheus-stack](https://prometheus-community.github.io/helm-charts) | 78.3.0 | [https://prometheus-community.github.io/helm-charts](https://prometheus-community.github.io/helm-charts) | `prometheus.enabled` | +| [opensearch](https://opensearch-project.github.io/helm-charts/) | 3.3.0 | [https://opensearch-project.github.io/helm-charts/](https://opensearch-project.github.io/helm-charts/) | `openSearch.enabled` | +| [opentelemetry-collector](https://open-telemetry.github.io/opentelemetry-helm-charts) | 0.140.0 | [https://open-telemetry.github.io/opentelemetry-helm-charts](https://open-telemetry.github.io/opentelemetry-helm-charts) | `opentelemetry-collector.enabled` | +| [opensearch-dashboards](https://opensearch-project.github.io/helm-charts/) | 3.3.0 | [https://opensearch-project.github.io/helm-charts/](https://opensearch-project.github.io/helm-charts/) | `openSearchDashboards.enabled` | + +## Cluster Agent + +Cluster Agent configuration for WebSocket-based communication with the control plane's cluster gateway + +| Parameter | Description | Type | Default | +| :--- | :--- | :--- | :--- | +| `clusterAgent.affinity` | Affinity rules for pod scheduling | `object` | `{}` | +| `clusterAgent.dnsRewrite.enabled` | Enable CoreDNS rewrite for *.openchoreo.localhost to host.k3d.internal | `boolean` | `false` | +| `clusterAgent.enabled` | Enable cluster agent deployment for multi-cluster communication | `boolean` | `true` | +| `clusterAgent.heartbeatInterval` | Interval between heartbeat messages to the control plane | `string` | `30s` | +| `clusterAgent.image.pullPolicy` | Image pull policy for the cluster agent | `object` | `IfNotPresent` | +| `clusterAgent.image.repository` | Container image repository for the cluster agent | `string` | `ghcr.io/openchoreo/cluster-agent` | +| `clusterAgent.image.tag` | Container image tag (defaults to Chart.AppVersion if empty) | `string` | | +| `clusterAgent.logLevel` | Log level for the cluster agent | `object` | `info` | +| `clusterAgent.name` | Name of the cluster agent deployment and associated resources | `string` | `cluster-agent-observabilityplane` | +| `clusterAgent.nodeSelector` | Node selector for pod scheduling | `object` | `{}` | +| `clusterAgent.planeID` | Logical plane identifier for multi-tenancy. Multiple CRs with the same planeID share one agent. Defaults to Helm release name if not specified. | `string` | `default-observabilityplane` | +| `clusterAgent.planeType` | Type of plane this agent serves | `object` | `observabilityplane` | +| `clusterAgent.podAnnotations` | Annotations to add to cluster agent pods | `object` | `{}` | +| `clusterAgent.podSecurityContext.fsGroup` | Filesystem group ID | `integer` | `1000` | +| `clusterAgent.podSecurityContext.runAsNonRoot` | Run as non-root user | `boolean` | `true` | +| `clusterAgent.podSecurityContext.runAsUser` | User ID to run as | `integer` | `1000` | +| `clusterAgent.priorityClass.create` | Create a priority class | `boolean` | `false` | +| `clusterAgent.priorityClass.name` | Name of the priority class | `string` | `cluster-agent-observabilityplane` | +| `clusterAgent.priorityClass.value` | Priority value | `integer` | `900000` | +| `clusterAgent.rbac.create` | Create ClusterRole and ClusterRoleBinding for the agent | `boolean` | `true` | +| `clusterAgent.reconnectDelay` | Delay before reconnecting after connection loss | `string` | `5s` | +| `clusterAgent.replicas` | Number of cluster agent pod replicas | `integer` | `1` | +| `clusterAgent.resources.limits.cpu` | CPU limit | `string` | `100m` | +| `clusterAgent.resources.limits.memory` | Memory limit | `string` | `256Mi` | +| `clusterAgent.resources.requests.cpu` | CPU request | `string` | `50m` | +| `clusterAgent.resources.requests.memory` | Memory request | `string` | `128Mi` | +| `clusterAgent.securityContext.allowPrivilegeEscalation` | Prevent privilege escalation | `boolean` | `false` | +| `clusterAgent.securityContext.capabilities.drop` | Capabilities to drop | `array` | | +| `clusterAgent.securityContext.readOnlyRootFilesystem` | Mount root filesystem as read-only | `boolean` | `true` | +| `clusterAgent.serverCANamespace` | Namespace where cluster-gateway CA ConfigMap exists | `string` | `openchoreo-control-plane` | +| `clusterAgent.serverUrl` | WebSocket URL of the cluster gateway in the control plane | `string` | `wss://cluster-gateway.openchoreo-control-plane.svc.cluster.local:8443/ws` | +| `clusterAgent.serviceAccount.annotations` | Annotations to add to the service account | `object` | `{}` | +| `clusterAgent.serviceAccount.create` | Create a dedicated service account | `boolean` | `true` | +| `clusterAgent.serviceAccount.name` | Name of the service account | `string` | `cluster-agent-observabilityplane` | +| `clusterAgent.tls.caSecretName` | CA secret name for signing agent client certificates. If empty, self-signed certs will be generated (required for multi-cluster setup). | `string` | `cluster-gateway-ca` | +| `clusterAgent.tls.caSecretNamespace` | Namespace where the CA secret exists. If empty, self-signed certs will be generated (required for multi-cluster setup). | `string` | `openchoreo-control-plane` | +| `clusterAgent.tls.caValue` | Inline CA certificate in PEM format (for multi-cluster, takes precedence) | `string` | | +| `clusterAgent.tls.clientSecretName` | Name of the client certificate Secret | `string` | `cluster-agent-tls` | +| `clusterAgent.tls.duration` | Certificate validity duration (e.g., 2160h = 90 days) | `string` | `2160h` | +| `clusterAgent.tls.enabled` | Enable TLS for cluster agent communication | `boolean` | `true` | +| `clusterAgent.tls.generateCerts` | Generate client certificates using cert-manager (for multi-cluster setups) | `boolean` | `false` | +| `clusterAgent.tls.renewBefore` | Time before expiry to renew certificate (e.g., 360h = 15 days) | `string` | `360h` | +| `clusterAgent.tls.secretName` | Name of the Secret containing client certificate and key | `string` | `cluster-agent-tls` | +| `clusterAgent.tls.serverCAConfigMap` | Name of the ConfigMap containing server CA certificate | `string` | `cluster-gateway-ca` | +| `clusterAgent.tls.serverCAValue` | Inline server CA certificate in PEM format (for multi-cluster setups) | `string` | | +| `clusterAgent.tolerations` | Tolerations for pod scheduling | `array` | `[]` | + +## Controller Manager + +Configuration for the observability plane controller manager that reconciles ObservabilityAlertRules and other CRDs + +| Parameter | Description | Type | Default | +| :--- | :--- | :--- | :--- | +| `controllerManager.affinity` | Affinity rules for pod scheduling | `object` | `{}` | +| `controllerManager.clusterGateway.enabled` | Enable cluster gateway integration for multi-cluster setups | `boolean` | `false` | +| `controllerManager.clusterGateway.tls.caConfigMap` | Name of the ConfigMap containing the gateway CA certificate | `string` | `cluster-gateway-ca` | +| `controllerManager.clusterGateway.tls.caPath` | Path to the CA certificate file for gateway verification | `string` | `/etc/cluster-gateway/ca.crt` | +| `controllerManager.clusterGateway.url` | URL of the cluster gateway service in the control plane | `string` | `https://cluster-gateway.openchoreo-control-plane.svc.cluster.local:8443` | +| `controllerManager.containerSecurityContext.allowPrivilegeEscalation` | Prevent privilege escalation within the container | `boolean` | `false` | +| `controllerManager.containerSecurityContext.capabilities.drop` | Capabilities to drop from the container | `array` | `["ALL"]` | +| `controllerManager.containerSecurityContext.readOnlyRootFilesystem` | Mount root filesystem as read-only | `boolean` | `false` | +| `controllerManager.containerSecurityContext.seccompProfile.type` | Seccomp profile type | `object` | `RuntimeDefault` | +| `controllerManager.deploymentPlane` | Identifier for this deployment plane type | `string` | `observabilityplane` | +| `controllerManager.enabled` | Enable or disable the controller manager deployment | `boolean` | `true` | +| `controllerManager.image.pullPolicy` | Image pull policy for the controller manager container | `object` | `IfNotPresent` | +| `controllerManager.image.repository` | Container image repository for the controller manager | `string` | `ghcr.io/openchoreo/controller` | +| `controllerManager.image.tag` | Container image tag (defaults to Chart.AppVersion if empty) | `string` | | +| `controllerManager.manager.args` | Command line arguments passed to the controller manager | `array` | | +| `controllerManager.manager.env.enableWebhooks` | Enable or disable admission webhooks | `string` | `false` | +| `controllerManager.name` | Name of the controller manager deployment and associated resources | `string` | `controller-manager` | +| `controllerManager.nodeSelector` | Node selector for pod scheduling constraints | `object` | `{}` | +| `controllerManager.podSecurityContext.fsGroup` | Group ID for filesystem access | `integer` | `1000` | +| `controllerManager.podSecurityContext.runAsGroup` | Group ID to run the container process | `integer` | `1000` | +| `controllerManager.podSecurityContext.runAsNonRoot` | Require the container to run as a non-root user | `boolean` | `true` | +| `controllerManager.podSecurityContext.runAsUser` | User ID to run the container process | `integer` | `1000` | +| `controllerManager.priorityClass.create` | Create a priority class for the controller manager | `boolean` | `false` | +| `controllerManager.priorityClass.name` | Name of the priority class | `string` | `observabilityplane-controller-manager` | +| `controllerManager.priorityClass.value` | Priority value (higher values indicate higher priority) | `integer` | `900000` | +| `controllerManager.replicas` | Number of controller manager pod replicas | `integer` | `1` | +| `controllerManager.resources.limits.cpu` | CPU limit for the controller manager | `string` | `500m` | +| `controllerManager.resources.limits.memory` | Memory limit for the controller manager | `string` | `512Mi` | +| `controllerManager.resources.requests.cpu` | CPU request for the controller manager | `string` | `100m` | +| `controllerManager.resources.requests.memory` | Memory request for the controller manager | `string` | `256Mi` | +| `controllerManager.serviceAccount.annotations` | Annotations to add to the service account | `object` | `{}` | +| `controllerManager.serviceAccount.create` | Create a dedicated service account for the controller manager | `boolean` | `true` | +| `controllerManager.tolerations` | Tolerations for pod scheduling on tainted nodes | `array` | `[]` | +| `controllerManager.topologySpreadConstraints` | Topology spread constraints for pod distribution across failure domains | `array` | `[]` | + +## Data Prepper + +For full configuration options, please refer to the [official chart documentation](https://opensearch-project.github.io/helm-charts/). + +Data Prepper subchart configuration for trace data processing and transformation before sending to OpenSearch + +| Parameter | Description | Type | Default | +| :--- | :--- | :--- | :--- | +| `data-prepper.enabled` | Enable Data Prepper for trace pipeline processing | `boolean` | `false` | +| `data-prepper.fullnameOverride` | Override the full name of Data Prepper resources | `string` | `data-prepper` | +| `data-prepper.pipelineConfig.config.trace-pipeline.buffer.bounded_blocking.batch_size` | | `integer` | `200` | +| `data-prepper.pipelineConfig.config.trace-pipeline.buffer.bounded_blocking.buffer_size` | | `integer` | `12800` | +| `data-prepper.pipelineConfig.config.trace-pipeline.delay` | | `string` | `100` | +| `data-prepper.pipelineConfig.config.trace-pipeline.sink` | | `array` | | +| `data-prepper.pipelineConfig.config.trace-pipeline.source.otel_trace_source.ssl` | | `boolean` | `false` | +| `data-prepper.pipelineConfig.enabled` | Enable pipeline configuration | `boolean` | `true` | +| `data-prepper.resources.limits.cpu` | CPU limit for Data Prepper | `string` | `1000m` | +| `data-prepper.resources.limits.memory` | Memory limit for Data Prepper | `string` | `500Mi` | +| `data-prepper.resources.requests.cpu` | CPU request for Data Prepper | `string` | `700m` | +| `data-prepper.resources.requests.memory` | Memory request for Data Prepper | `string` | `500Mi` | + +## External Secrets + +For full configuration options, please refer to the [official chart documentation](https://charts.external-secrets.io). + +External Secrets Operator subchart configuration for secret management. +Single cluster: Set enabled to false to use the data plane's ESO. +Multi-cluster: Set enabled to true to install a dedicated ESO in the observability plane. + +| Parameter | Description | Type | Default | +| :--- | :--- | :--- | :--- | +| `external-secrets.enabled` | Enable External Secrets Operator installation in this chart | `boolean` | `false` | +| `external-secrets.fullnameOverride` | Override the full name of External Secrets Operator resources | `string` | `external-secrets` | +| `external-secrets.nameOverride` | Override the name of External Secrets Operator resources | `string` | `external-secrets` | + +## Fake Secret Store + +Fake Secret Store configuration for local development without a real secret backend + +| Parameter | Description | Type | Default | +| :--- | :--- | :--- | :--- | +| `fakeSecretStore.enabled` | Enable fake secret store (requires external-secrets.enabled to be true) | `boolean` | `false` | +| `fakeSecretStore.name` | Name of the ClusterSecretStore resource | `string` | `default` | +| `fakeSecretStore.secrets` | List of fake secrets to provide for development | `array` | | + +## Fluent Bit + +For full configuration options, please refer to the [official chart documentation](https://fluent.github.io/helm-charts). + +Fluent Bit subchart configuration for log collection and forwarding to OpenSearch + +| Parameter | Description | Type | Default | +| :--- | :--- | :--- | :--- | +| `fluent-bit.config.customParsers` | Custom parser definitions in Fluent Bit configuration format | `string` | `(multiline string)` | +| `fluent-bit.config.filters` | Filter plugin configuration for log processing | `string` | `(multiline string)` | +| `fluent-bit.config.inputs` | Input plugin configuration for log collection | `string` | `(multiline string)` | +| `fluent-bit.config.outputs` | Output plugin configuration for log forwarding to OpenSearch | `string` | `(multiline string)` | +| `fluent-bit.dnsPolicy` | DNS policy for Fluent Bit pods | `object` | `ClusterFirstWithHostNet` | +| `fluent-bit.enabled` | Enable Fluent Bit log collector deployment | `boolean` | `false` | +| `fluent-bit.extraVolumeMounts` | Extra volume mounts for the Fluent Bit container | `array` | | +| `fluent-bit.extraVolumes` | Extra volumes for the Fluent Bit pod | `array` | | +| `fluent-bit.fullnameOverride` | Override the full name of Fluent Bit resources | `string` | `fluent-bit` | +| `fluent-bit.hostNetwork` | Use host network for Fluent Bit pods (required for node log access) | `boolean` | `true` | +| `fluent-bit.initContainers` | Init containers for the Fluent Bit pod (used to set volume ownership) | `array` | | +| `fluent-bit.metricsPort` | Port for Fluent Bit metrics endpoint | `integer` | `2021` | +| `fluent-bit.rbac.nodeAccess` | Enable node-level access for reading container logs | `boolean` | `true` | +| `fluent-bit.resources.limits.cpu` | CPU limit for Fluent Bit | `string` | `200m` | +| `fluent-bit.resources.limits.memory` | Memory limit for Fluent Bit | `string` | `256Mi` | +| `fluent-bit.resources.requests.cpu` | CPU request for Fluent Bit | `string` | `100m` | +| `fluent-bit.resources.requests.memory` | Memory request for Fluent Bit | `string` | `128Mi` | +| `fluent-bit.securityContext.allowPrivilegeEscalation` | Prevent privilege escalation | `boolean` | `false` | +| `fluent-bit.securityContext.capabilities.drop` | Capabilities to drop | `array` | | +| `fluent-bit.securityContext.readOnlyRootFilesystem` | Mount root filesystem as read-only | `boolean` | `true` | +| `fluent-bit.securityContext.runAsNonRoot` | Run container as non-root user | `boolean` | `true` | +| `fluent-bit.securityContext.runAsUser` | User ID to run the container | `integer` | `10000` | +| `fluent-bit.service.port` | Service port for Fluent Bit metrics | `integer` | `2021` | +| `fluent-bit.testFramework.enabled` | Enable Fluent Bit test framework | `boolean` | `false` | + +## Gateway + +KGateway resource configuration for HTTPS gateway routing + +| Parameter | Description | Type | Default | +| :--- | :--- | :--- | :--- | +| `gateway.enabled` | Enable gateway resource creation | `boolean` | `false` | +| `gateway.envoy.mountTmpVolume` | Mount /tmp as emptyDir volume to fix Envoy temporary file creation issues on macOS with Docker Desktop/Colima | `boolean` | `false` | + +## Global + +Global values shared across all components in the observability plane + +| Parameter | Description | Type | Default | +| :--- | :--- | :--- | :--- | +| `global.baseDomain` | Base domain for the observability plane used in gateway routing and ingress configuration | `string` | | +| `global.commonLabels` | Common labels applied to all resources created by this chart | `object` | `{}` | +| `global.installationMode` | Installation mode of OpenChoreo | `object` | `singleCluster` | + +## Kgateway + +For full configuration options, please refer to the [official chart documentation](oci://cr.kgateway.dev/kgateway-dev/charts). + +KGateway subchart configuration for API gateway functionality using Envoy-based gateway + +| Parameter | Description | Type | Default | +| :--- | :--- | :--- | :--- | +| `kgateway.controller.image.pullPolicy` | Image pull policy for the KGateway controller | `object` | `IfNotPresent` | +| `kgateway.controller.resources.limits.cpu` | CPU limit for KGateway controller | `string` | `200m` | +| `kgateway.controller.resources.limits.memory` | Memory limit for KGateway controller | `string` | `256Mi` | +| `kgateway.controller.resources.requests.cpu` | CPU request for KGateway controller | `string` | `100m` | +| `kgateway.controller.resources.requests.memory` | Memory request for KGateway controller | `string` | `128Mi` | +| `kgateway.controller.service.ports.agwGrpc` | gRPC port for the API gateway | `integer` | `9978` | +| `kgateway.controller.service.type` | Kubernetes service type | `object` | `ClusterIP` | +| `kgateway.enabled` | Enable KGateway API gateway | `boolean` | `false` | +| `kgateway.fullnameOverride` | Override the full name of KGateway resources | `string` | `kgateway` | + +## Kubernetes Cluster Domain + +Kubernetes cluster domain used for service discovery DNS resolution + +| Parameter | Description | Type | Default | +| :--- | :--- | :--- | :--- | +| `kubernetesClusterDomain` | Kubernetes cluster domain used for service discovery DNS resolution | `string` | `cluster.local` | + +## Observer + +OpenChoreo Observer service configuration - REST API that abstracts OpenSearch for logging, metrics, and tracing + +| Parameter | Description | Type | Default | +| :--- | :--- | :--- | :--- | +| `observer.extraEnvs` | Extra environment variables for the Observer container | `array` | | +| `observer.image.pullPolicy` | Image pull policy for the Observer container | `object` | `IfNotPresent` | +| `observer.image.repository` | Container image repository for the Observer | `string` | `ghcr.io/openchoreo/observer` | +| `observer.image.tag` | Container image tag (defaults to Chart.AppVersion if empty) | `string` | | +| `observer.logLevel` | Log level for the Observer service | `object` | `info` | +| `observer.openSearchPassword` | Password for OpenSearch authentication | `string` | `ThisIsTheOpenSearchPassword1` | +| `observer.openSearchUsername` | Username for OpenSearch authentication | `string` | `admin` | +| `observer.prometheus.address` | Prometheus server address (auto-constructed from release name if empty) | `string` | | +| `observer.prometheus.timeout` | Timeout for Prometheus queries | `string` | `30s` | +| `observer.replicas` | Number of Observer pod replicas | `integer` | `1` | +| `observer.resources.limits.cpu` | CPU limit for the Observer | `string` | `200m` | +| `observer.resources.limits.memory` | Memory limit for the Observer | `string` | `200Mi` | +| `observer.resources.requests.cpu` | CPU request for the Observer | `string` | `100m` | +| `observer.resources.requests.memory` | Memory request for the Observer | `string` | `128Mi` | +| `observer.security.userTypes` | User type configurations for JWT subject resolution | `array` | | +| `observer.service.port` | Service port for the Observer API | `integer` | `8080` | +| `observer.service.type` | Kubernetes service type | `object` | `ClusterIP` | + +## Open Search + +For full configuration options, please refer to the [official chart documentation](https://opensearch-project.github.io/helm-charts/). + +OpenSearch Helm subchart configuration (legacy, prefer openSearchCluster for operator-based deployment) + +| Parameter | Description | Type | Default | +| :--- | :--- | :--- | :--- | +| `openSearch.enabled` | Enable OpenSearch Helm chart deployment (alternative to operator-based openSearchCluster) | `boolean` | `false` | +| `openSearch.extraEnvs` | Extra environment variables for OpenSearch pods | `array` | | +| `openSearch.image.tag` | OpenSearch image tag version | `string` | `3.3.0` | +| `openSearch.masterService` | Name of the master service for cluster discovery | `string` | `opensearch` | +| `openSearch.nameOverride` | Override the name of OpenSearch resources | `string` | `opensearch` | +| `openSearch.rbac.create` | Create RBAC resources for OpenSearch | `boolean` | `true` | +| `openSearch.rbac.serviceAccountName` | Name of the service account for OpenSearch | `string` | `opensearch` | +| `openSearch.singleNode` | Run OpenSearch as a single node (for development/testing) | `boolean` | `true` | + +## Open Search Cluster + +OpenSearch Operator-based cluster configuration (preferred over openSearch Helm chart) + +| Parameter | Description | Type | Default | +| :--- | :--- | :--- | :--- | +| `openSearchCluster.adminUserPassword` | Admin password for OpenSearch cluster | `string` | `ThisIsTheOpenSearchPassword1` | +| `openSearchCluster.adminUsername` | Admin username for OpenSearch cluster | `string` | `admin` | +| `openSearchCluster.bootstrap.resources.limits.cpu` | CPU limit | `string` | `1000m` | +| `openSearchCluster.bootstrap.resources.limits.memory` | Memory limit | `string` | `1000Mi` | +| `openSearchCluster.bootstrap.resources.requests.cpu` | CPU request | `string` | `100m` | +| `openSearchCluster.bootstrap.resources.requests.memory` | Memory request | `string` | `1000Mi` | +| `openSearchCluster.dashboards.enable` | Enable OpenSearch Dashboards | `boolean` | `false` | +| `openSearchCluster.dashboards.replicas` | Number of dashboard replicas | `integer` | `1` | +| `openSearchCluster.dashboards.version` | OpenSearch Dashboards version | `string` | `3.3.0` | +| `openSearchCluster.enabled` | Enable OpenSearch cluster deployment via OpenSearch Operator | `boolean` | `true` | +| `openSearchCluster.general.setVMMaxMapCount` | Set vm.max_map_count sysctl for OpenSearch (required for production) | `boolean` | `true` | +| `openSearchCluster.general.version` | OpenSearch version to deploy | `string` | `3.3.0` | +| `openSearchCluster.internalUsers` | Internal users configuration in YAML format (bcrypt hashed passwords) | `string` | `(multiline string)` | +| `openSearchCluster.nodePools.data.diskSize` | Persistent volume size for data nodes | `string` | `5Gi` | +| `openSearchCluster.nodePools.data.replicas` | Number of data node replicas | `integer` | `2` | +| `openSearchCluster.nodePools.data.resources.limits.cpu` | CPU limit | `string` | `1000m` | +| `openSearchCluster.nodePools.data.resources.limits.memory` | Memory limit | `string` | `1000Mi` | +| `openSearchCluster.nodePools.data.resources.requests.cpu` | CPU request | `string` | `100m` | +| `openSearchCluster.nodePools.data.resources.requests.memory` | Memory request | `string` | `1000Mi` | +| `openSearchCluster.nodePools.master.diskSize` | Persistent volume size for master nodes | `string` | `1Gi` | +| `openSearchCluster.nodePools.master.replicas` | Number of master node replicas (should be odd for quorum) | `integer` | `3` | +| `openSearchCluster.nodePools.master.resources.limits.cpu` | CPU limit | `string` | `1000m` | +| `openSearchCluster.nodePools.master.resources.limits.memory` | Memory limit | `string` | `900Mi` | +| `openSearchCluster.nodePools.master.resources.requests.cpu` | CPU request | `string` | `100m` | +| `openSearchCluster.nodePools.master.resources.requests.memory` | Memory request | `string` | `900Mi` | + +## Open Search Cluster Setup + +OpenSearch cluster post-install setup job configuration + +| Parameter | Description | Type | Default | +| :--- | :--- | :--- | :--- | +| `openSearchClusterSetup.alertingWebhookUrl` | Alerting webhook URL for setup configuration | `string` | `http://observer.openchoreo-observability-plane:8080/api/alerting/webhook/opensearch` | +| `openSearchClusterSetup.dataRetentionTime.containerLogs` | Retention period for container logs | `string` | `30d` | +| `openSearchClusterSetup.dataRetentionTime.rcaReports` | Retention period for RCA reports | `string` | `90d` | +| `openSearchClusterSetup.dataRetentionTime.traces` | Retention period for traces | `string` | `30d` | +| `openSearchClusterSetup.image.repository` | Container image repository | `string` | `ghcr.io/openchoreo/init-observability-opensearch` | +| `openSearchClusterSetup.image.tag` | Container image tag (defaults to Chart.AppVersion if empty) | `string` | | + +## Open Search Dashboards + +For full configuration options, please refer to the [official chart documentation](https://opensearch-project.github.io/helm-charts/). + +OpenSearch Dashboards subchart configuration for visualization UI + +| Parameter | Description | Type | Default | +| :--- | :--- | :--- | :--- | +| `openSearchDashboards.config.disableSecurity` | Disable security features in dashboards (for development) | `string` | `true` | +| `openSearchDashboards.enabled` | Enable OpenSearch Dashboards deployment | `boolean` | `false` | +| `openSearchDashboards.extraEnvs` | Extra environment variables for OpenSearch Dashboards pods | `array` | | +| `openSearchDashboards.fullnameOverride` | Override the full name of OpenSearch Dashboards resources | `string` | `opensearch-dashboards` | +| `openSearchDashboards.image.tag` | OpenSearch Dashboards image tag version | `string` | `3.3.0` | +| `openSearchDashboards.nameOverride` | Override the name of OpenSearch Dashboards resources | `string` | `opensearch-dashboards` | +| `openSearchDashboards.opensearchHosts` | URL of the OpenSearch cluster to connect to | `string` | `http://opensearch:9200` | +| `openSearchDashboards.replicas` | Number of OpenSearch Dashboards replicas | `integer` | `1` | + +## Opentelemetry Collector + +For full configuration options, please refer to the [official chart documentation](https://open-telemetry.github.io/opentelemetry-helm-charts). + +OpenTelemetry Collector subchart configuration for telemetry data collection and processing + +| Parameter | Description | Type | Default | +| :--- | :--- | :--- | :--- | +| `opentelemetry-collector.clusterRole.create` | Create a ClusterRole for the collector | `boolean` | `true` | +| `opentelemetry-collector.clusterRole.rules` | RBAC rules for the collector ClusterRole | `array` | | +| `opentelemetry-collector.configMap.create` | Create ConfigMap (set to false to use existing ConfigMap) | `boolean` | `false` | +| `opentelemetry-collector.configMap.existingName` | Name of existing ConfigMap to use for collector configuration | `string` | `opentelemetry-collector-config` | +| `opentelemetry-collector.enabled` | Enable OpenTelemetry Collector deployment | `boolean` | `true` | +| `opentelemetry-collector.fullnameOverride` | Override the full name of OpenTelemetry Collector resources | `string` | `opentelemetry-collector` | +| `opentelemetry-collector.image.repository` | Container image repository (uses contrib distribution for extended features) | `string` | `otel/opentelemetry-collector-contrib` | +| `opentelemetry-collector.mode` | Deployment mode for the collector | `object` | `deployment` | +| `opentelemetry-collector.resources.limits.cpu` | CPU limit for the collector | `string` | `100m` | +| `opentelemetry-collector.resources.limits.memory` | Memory limit for the collector | `string` | `200Mi` | +| `opentelemetry-collector.resources.requests.cpu` | CPU request for the collector | `string` | `50m` | +| `opentelemetry-collector.resources.requests.memory` | Memory request for the collector | `string` | `100Mi` | + +## Opentelemetry Collector Customizations + +OpenTelemetry Collector customizations used by OpenChoreo templates. +These are NOT passed to the opentelemetry-collector Helm chart directly. + +| Parameter | Description | Type | Default | +| :--- | :--- | :--- | :--- | +| `opentelemetryCollectorCustomizations.openSearchQueue.numConsumers` | Number of consumers processing the queue | `integer` | `5` | +| `opentelemetryCollectorCustomizations.openSearchQueue.queueSize` | Maximum queue size for pending exports | `integer` | `1000` | +| `opentelemetryCollectorCustomizations.openSearchQueue.sizer` | Queue sizing strategy | `object` | `items` | +| `opentelemetryCollectorCustomizations.tailSampling.decisionCache.nonSampledCacheSize` | Cache size for non-sampled trace decisions | `integer` | `1000` | +| `opentelemetryCollectorCustomizations.tailSampling.decisionCache.sampledCacheSize` | Cache size for sampled trace decisions | `integer` | `10000` | +| `opentelemetryCollectorCustomizations.tailSampling.decisionWait` | Time to wait before making sampling decision | `string` | `10s` | +| `opentelemetryCollectorCustomizations.tailSampling.expectedNewTracesPerSec` | Expected new traces per second (for cache sizing) | `integer` | `10` | +| `opentelemetryCollectorCustomizations.tailSampling.numTraces` | Number of traces to keep in memory | `integer` | `100` | +| `opentelemetryCollectorCustomizations.tailSampling.spansPerSecond` | Maximum spans per second rate limit | `integer` | `10` | + +## Prometheus + +For full configuration options, please refer to the [official chart documentation](https://prometheus-community.github.io/helm-charts). + +Prometheus stack subchart configuration (kube-prometheus-stack) for metrics collection and monitoring + +| Parameter | Description | Type | Default | +| :--- | :--- | :--- | :--- | +| `prometheus.alertmanager.alertmanagerSpec.podMetadata.name` | Name for Alertmanager pod metadata | `string` | `alertmanager` | +| `prometheus.alertmanager.enabled` | Enable Alertmanager deployment | `boolean` | `false` | +| `prometheus.cleanPrometheusOperatorObjectNames` | Produce cleaner resource names without redundant suffixes | `boolean` | `true` | +| `prometheus.coreDns.enabled` | Enable CoreDNS metrics scraping | `boolean` | `false` | +| `prometheus.crds.enabled` | Install Prometheus Operator CRDs (ServiceMonitor, PodMonitor, etc.) | `boolean` | `true` | +| `prometheus.defaultRules.create` | Create default alerting rules | `boolean` | `false` | +| `prometheus.enabled` | Enable Prometheus stack deployment | `boolean` | `true` | +| `prometheus.fullnameOverride` | Override the full name of Prometheus stack resources | `string` | `openchoreo-observability` | +| `prometheus.grafana.adminPassword` | Grafana admin password | `string` | `admin` | +| `prometheus.grafana.adminUser` | Grafana admin username | `string` | `admin` | +| `prometheus.grafana.datasources.datasources.yaml.apiVersion` | | `integer` | `1` | +| `prometheus.grafana.datasources.datasources.yaml.datasources` | | `array` | | +| `prometheus.grafana.defaultDashboardsEnabled` | Enable default Grafana dashboards | `boolean` | `false` | +| `prometheus.grafana.enabled` | Enable Grafana deployment | `boolean` | `false` | +| `prometheus.grafana.fullnameOverride` | Override the full name of Grafana resources | `string` | `grafana` | +| `prometheus.grafana.sidecar.dashboards.enabled` | Enable dashboard sidecar | `boolean` | `false` | +| `prometheus.grafana.sidecar.datasources.enabled` | Enable datasource sidecar | `boolean` | `false` | +| `prometheus.kube-state-metrics.collectors` | List of Kubernetes resources to collect metrics from | `array` | | +| `prometheus.kube-state-metrics.fullnameOverride` | Override the full name of kube-state-metrics resources | `string` | `kube-state-metrics` | +| `prometheus.kube-state-metrics.metricAllowlist` | Allowlist of specific metrics to collect (improves performance) | `array` | | +| `prometheus.kube-state-metrics.metricLabelsAllowlist` | Labels to include from Kubernetes resources (OpenChoreo-specific labels) | `array` | | +| `prometheus.kubeApiServer.enabled` | Enable API server metrics scraping | `boolean` | `false` | +| `prometheus.kubeControllerManager.enabled` | Enable controller manager metrics scraping | `boolean` | `false` | +| `prometheus.kubeEtcd.enabled` | Enable etcd metrics scraping | `boolean` | `false` | +| `prometheus.kubeProxy.enabled` | Enable kube-proxy metrics scraping | `boolean` | `false` | +| `prometheus.kubeScheduler.enabled` | Enable scheduler metrics scraping | `boolean` | `false` | +| `prometheus.kubeStateMetrics.enabled` | Enable kube-state-metrics scraping | `boolean` | `true` | +| `prometheus.kubelet.enabled` | Enable kubelet metrics scraping | `boolean` | `true` | +| `prometheus.kubernetesServiceMonitors.enabled` | Enable Kubernetes component ServiceMonitors | `boolean` | `true` | +| `prometheus.nodeExporter.enabled` | Enable node exporter deployment | `boolean` | `false` | +| `prometheus.prometheus.enabled` | Enable Prometheus server deployment | `boolean` | `true` | +| `prometheus.prometheus.prometheusSpec.serviceMonitorNamespaceSelector` | Namespace selector for ServiceMonitors (empty = all namespaces) | `object` | `{}` | +| `prometheus.prometheus.prometheusSpec.serviceMonitorSelector` | Label selector for ServiceMonitors (empty = all ServiceMonitors) | `object` | `{}` | +| `prometheus.prometheus.prometheusSpec.serviceMonitorSelectorNilUsesHelmValues` | Use Helm values for ServiceMonitor selection when selector is nil | `boolean` | `false` | +| `prometheus.prometheus.service.port` | Prometheus server port | `integer` | `9091` | +| `prometheus.prometheus.service.reloaderWebPort` | Config reloader web port | `integer` | `8081` | +| `prometheus.prometheusOperator.enabled` | Enable Prometheus Operator deployment | `boolean` | `true` | +| `prometheus.prometheusOperator.fullnameOverride` | Override the full name of Prometheus Operator resources | `string` | `prometheus-operator` | +| `prometheus.prometheusOperator.resources.limits.cpu` | CPU limit | `string` | `40m` | +| `prometheus.prometheusOperator.resources.limits.memory` | Memory limit | `string` | `50Mi` | +| `prometheus.prometheusOperator.resources.requests.cpu` | CPU request | `string` | `20m` | +| `prometheus.prometheusOperator.resources.requests.memory` | Memory request | `string` | `30Mi` | +| `prometheus.thanosRuler.enabled` | Enable Thanos Ruler for long-term alerting | `boolean` | `false` | + +## Rca + +AI-powered Root Cause Analysis agent configuration + +| Parameter | Description | Type | Default | +| :--- | :--- | :--- | :--- | +| `rca.controlPlaneNamespace` | Control plane namespace for service auto-discovery | `string` | `openchoreo-control-plane` | +| `rca.enabled` | Enable RCA agent deployment | `boolean` | `false` | +| `rca.image.pullPolicy` | Image pull policy | `object` | `IfNotPresent` | +| `rca.image.repository` | Container image repository | `string` | `ghcr.io/openchoreo/ai-rca-agent` | +| `rca.image.tag` | Container image tag (defaults to Chart.AppVersion if empty) | `string` | | +| `rca.llm.apiKey` | LLM API key (set via --set rca.llm.apiKey during install) | `string` | | +| `rca.llm.modelName` | LLM model name (e.g., claude-sonnet-4-5, gpt-5, gemini-2.0-flash-exp) | `string` | | +| `rca.logLevel` | Log level for the RCA agent | `string` | `INFO` | +| `rca.name` | Name of the RCA agent deployment | `string` | `ai-rca-agent` | +| `rca.logLevel` | Log level for the RCA agent | `string` | `INFO` | +| `rca.oauth.clientId` | OAuth2 client ID registered with the IDP | `string` | `openchoreo-rca-agent` | +| `rca.oauth.clientSecret` | OAuth2 client secret (override via --set rca.oauth.clientSecret) | `string` | `openchoreo-rca-agent-secret` | +| `rca.observerMcpUrl` | Observer MCP endpoint URL | `string` | | +| `rca.openchoreoMcpUrl` | OpenChoreo API MCP endpoint URL | `string` | | +| `rca.opensearch.address` | OpenSearch cluster address | `string` | `https://opensearch:9200` | +| `rca.replicas` | Number of RCA agent replicas | `integer` | `1` | +| `rca.resources.limits.cpu` | CPU limit | `string` | `250m` | +| `rca.resources.limits.memory` | Memory limit | `string` | `1536Mi` | +| `rca.resources.requests.cpu` | CPU request | `string` | `100m` | +| `rca.resources.requests.memory` | Memory request | `string` | `1024Mi` | +| `rca.service.port` | Service port | `integer` | `8080` | +| `rca.service.type` | Service type | `object` | `ClusterIP` | + +## Security + +Common security configuration shared across all components + +| Parameter | Description | Type | Default | +| :--- | :--- | :--- | :--- | +| `security.enabled` | Global security toggle - when disabled, authentication is turned off for all components | `boolean` | `true` | +| `security.jwt.audience` | Expected audience claim in JWT tokens | `string` | | +| `security.oidc.issuer` | OIDC issuer URL | `string` | | +| `security.oidc.jwksUrl` | JWKS URL for token verification | `string` | | +| `security.oidc.jwksUrlTlsInsecureSkipVerify` | Skip TLS verification for JWKS URL | `string` | `false` | +| `security.oidc.tokenUrl` | OIDC token endpoint URL | `string` | | + +## Tls + +Global TLS certificate configuration using cert-manager + +| Parameter | Description | Type | Default | +| :--- | :--- | :--- | :--- | +| `tls.enabled` | Enable TLS certificate generation for the observability plane | `boolean` | `false` | + +## Wait Job + +Wait job configuration for post-install hooks + +| Parameter | Description | Type | Default | +| :--- | :--- | :--- | :--- | +| `waitJob.image` | Container image for kubectl-based wait jobs | `string` | `bitnamilegacy/kubectl:1.32.4` | + diff --git a/versioned_docs/version-v0.11.x/reference/mcp-servers/mcp-configuration.md b/versioned_docs/version-v0.11.x/reference/mcp-servers/mcp-configuration.md new file mode 100644 index 0000000..a9be076 --- /dev/null +++ b/versioned_docs/version-v0.11.x/reference/mcp-servers/mcp-configuration.md @@ -0,0 +1,103 @@ +--- +title: MCP Configuration +--- + +# MCP Configuration + +This guide shows how to configure different AI assistants to connect to the OpenChoreo MCP server. + +## Prerequisites + +1. **Running OpenChoreo instance** - Complete the [Quick Start Guide](../../getting-started/quick-start-guide.mdx) +2. **MCP Server Endpoint** - Know your OpenChoreo API endpoint (e.g., `http://api.openchoreo.localhost:8080/mcp`) +3. **Authentication Token** - Obtain a JWT token for authenticating with the MCP server +4. **AI Assistant Installed** - Have one of the supported AI assistants installed + +## MCP Server Configuration for AI assistants + +The OpenChoreo MCP server exposes an HTTP endpoint that AI assistants connect to. You'll need: + +- **Endpoint URL**: Typically `http://api.openchoreo.localhost:8080/mcp` (adjust based on your setup) +- **Authentication**: Bearer token in `Authorization` header +- **Transport**: HTTP-based MCP transport (most assistants support this) + +## Obtaining an Authentication Token + +OpenChoreo uses an identity provider for authentication. The default identity provider is **Asgardeo Thunder** with the token endpoint at `http://thunder.openchoreo.localhost:8080/oauth2/token`. + +Follow these steps to obtain an authentication token if you're using the default identity provider: + +### Step 1: Get the Application ID + +1. Open your browser and navigate to http://thunder.openchoreo.localhost:8080/develop + > **Note**: Default credentials are `admin` / `admin` + +2. Open the `Sample App` application +3. Copy the **Application ID** + +### Step 2: Obtain an Admin Token + +Replace `` with your Sample App ID and run: + +```bash +ADMIN_TOKEN_RESPONSE=$(curl -k -s -X POST 'http://thunder.openchoreo.localhost:8080/flow/execute' \ + -H 'Content-Type: application/json' \ + -d '{ + "applicationId": "", + "flowType": "AUTHENTICATION", + "inputs": { + "username": "admin", + "password": "admin", + "requested_permissions": "system" + } + }') + +ADMIN_TOKEN=$(echo $ADMIN_TOKEN_RESPONSE | jq -r '.assertion') +``` + +### Step 3: Create an OAuth2 Application + +Create a new OAuth2 application with client credentials grant: + +```bash +curl -L 'http://thunder.openchoreo.localhost:8080/applications' \ + -H 'Content-Type: application/json' \ + -H "Authorization: Bearer $ADMIN_TOKEN" \ + -d '{ + "name": "MCP client", + "description": "MCP client application to use openchoreo MCP server", + "auth_flow_graph_id": "auth_flow_config_basic", + "inbound_auth_config": [ + { + "type": "oauth2", + "config": { + "client_id": "mcp_client", + "client_secret": "mcp_client_secret", + "grant_types": [ + "client_credentials" + ], + "token_endpoint_auth_method": "client_secret_basic", + "token": { + "issuer": "thunder", + "access_token": { + "validity_period": 3600 + } + } + } + } + ] +}' +``` + +### Step 4: Obtain Your Token + +Use the client credentials to get an access token: + +```bash +curl -L 'http://thunder.openchoreo.localhost:8080/oauth2/token' \ + -H 'Content-Type: application/x-www-form-urlencoded' \ + -u 'mcp_client:mcp_client_secret' \ + -d 'grant_type=client_credentials' +``` + +The response will contain an `access_token` that you can use as the Bearer token for authenticating with the OpenChoreo MCP server. diff --git a/versioned_docs/version-v0.11.x/reference/resource-limits.md b/versioned_docs/version-v0.11.x/reference/resource-limits.md new file mode 100644 index 0000000..768878c --- /dev/null +++ b/versioned_docs/version-v0.11.x/reference/resource-limits.md @@ -0,0 +1,162 @@ +--- +title: Resource Limits & Quotas +unlisted: true +--- + +# Resource Limits & Quotas + +This document outlines OpenChoreo's resource constraints, sizing guidelines, and quota management to help you plan and optimize your platform deployment. + +## Platform Resource Requirements + +### Control Plane Requirements + +#### Minimum Configuration +**Single Control Plane Node**: +- **CPU**: 4 cores (2 cores minimum) +- **Memory**: 8 GB RAM (4 GB minimum) +- **Storage**: 50 GB SSD (20 GB minimum) +- **Network**: 1 Gbps (100 Mbps minimum) + +### Data Plane Requirements + +#### Per-Node Recommendations +```yaml +# Small Environment (Development/Testing) +nodes: + count: 3 + specifications: + cpu: 4 cores + memory: 16 GB + storage: 100 GB + max_pods: 50 +``` + +## Component Resource Limits + +### Default Resource Specifications + +#### CPU Limits +```yaml +# Default CPU configurations per component type +service_components: + requests: + min: "100m" # 0.1 CPU cores + default: "200m" # 0.2 CPU cores + max: "4000m" # 4 CPU cores + limits: + min: "200m" # 0.2 CPU cores + default: "500m" # 0.5 CPU cores + max: "8000m" # 8 CPU cores + +worker_components: + requests: + min: "200m" # 0.2 CPU cores + default: "500m" # 0.5 CPU cores + max: "8000m" # 8 CPU cores + limits: + min: "500m" # 0.5 CPU cores + default: "1000m" # 1 CPU core + max: "16000m" # 16 CPU cores + +scheduled_components: + requests: + min: "100m" # 0.1 CPU cores + default: "200m" # 0.2 CPU cores + max: "2000m" # 2 CPU cores + limits: + min: "200m" # 0.2 CPU cores + default: "1000m" # 1 CPU core + max: "4000m" # 4 CPU cores +``` + +#### Memory Limits +```yaml +# Default memory configurations per component type +service_components: + requests: + min: "64Mi" # 64 MiB + default: "128Mi" # 128 MiB + max: "8Gi" # 8 GiB + limits: + min: "128Mi" # 128 MiB + default: "256Mi" # 256 MiB + max: "16Gi" # 16 GiB + +worker_components: + requests: + min: "128Mi" # 128 MiB + default: "256Mi" # 256 MiB + max: "16Gi" # 16 GiB + limits: + min: "256Mi" # 256 MiB + default: "512Mi" # 512 MiB + max: "32Gi" # 32 GiB + +scheduled_components: + requests: + min: "64Mi" # 64 MiB + default: "128Mi" # 128 MiB + max: "4Gi" # 4 GiB + limits: + min: "128Mi" # 128 MiB + default: "512Mi" # 512 MiB + max: "8Gi" # 8 GiB +``` + +## Environment Quotas + +### Resource Quota Templates + +#### Development Environment +```yaml +apiVersion: v1 +kind: ResourceQuota +metadata: + name: development-quota +spec: + hard: + # Compute Resources + requests.cpu: "10" # 10 CPU cores + requests.memory: "20Gi" # 20 GiB memory + limits.cpu: "20" # 20 CPU cores + limits.memory: "40Gi" # 40 GiB memory + + # Storage Resources + requests.storage: "100Gi" # 100 GiB storage + persistentvolumeclaims: "10" # 10 PVCs + + # Object Counts + pods: "50" # 50 pods + services: "20" # 20 services + secrets: "20" # 20 secrets + configmaps: "20" # 20 configmaps + + # OpenChoreo Resources + components.choreo.dev: "10" # 10 components +``` + +--- + +## Best Practices + +### Resource Planning +1. **Start Small**: Begin with minimal resources and scale up based on actual usage +2. **Monitor Continuously**: Track resource usage patterns and trends +3. **Set Appropriate Quotas**: Use quotas to prevent resource exhaustion +4. **Plan for Growth**: Account for traffic growth in resource planning + +### Performance Optimization +1. **Use Resource Requests**: Always set resource requests for predictable scheduling +2. **Set Resource Limits**: Prevent resource contention with appropriate limits +3. **Monitor Efficiency**: Track resource utilization efficiency +4. **Optimize Regularly**: Regularly review and optimize resource allocations + +### Cost Management +1. **Right-size Resources**: Avoid over-provisioning resources +2. **Use Autoscaling**: Implement horizontal and vertical pod autoscaling +3. **Clean Up Unused Resources**: Regularly clean up unused resources +4. **Monitor Costs**: Track resource costs and optimize based on usage patterns + +--- + diff --git a/versioned_docs/version-v0.11.x/resources/openchoreo-cell-runtime-view.png b/versioned_docs/version-v0.11.x/resources/openchoreo-cell-runtime-view.png new file mode 100644 index 0000000..917dc41 Binary files /dev/null and b/versioned_docs/version-v0.11.x/resources/openchoreo-cell-runtime-view.png differ diff --git a/versioned_docs/version-v0.11.x/resources/openchoreo-development-abstractions.png b/versioned_docs/version-v0.11.x/resources/openchoreo-development-abstractions.png new file mode 100644 index 0000000..ece2032 Binary files /dev/null and b/versioned_docs/version-v0.11.x/resources/openchoreo-development-abstractions.png differ diff --git a/versioned_docs/version-v0.11.x/resources/openchoreo-diagram-v1-with-borders.png b/versioned_docs/version-v0.11.x/resources/openchoreo-diagram-v1-with-borders.png new file mode 100644 index 0000000..0c146bb Binary files /dev/null and b/versioned_docs/version-v0.11.x/resources/openchoreo-diagram-v1-with-borders.png differ diff --git a/versioned_docs/version-v0.11.x/resources/openchoreo-platform-abstractions.png b/versioned_docs/version-v0.11.x/resources/openchoreo-platform-abstractions.png new file mode 100644 index 0000000..148268a Binary files /dev/null and b/versioned_docs/version-v0.11.x/resources/openchoreo-platform-abstractions.png differ diff --git a/versioned_docs/version-v0.11.x/resources/openchoreo_components.svg b/versioned_docs/version-v0.11.x/resources/openchoreo_components.svg new file mode 100644 index 0000000..c5ae2ae --- /dev/null +++ b/versioned_docs/version-v0.11.x/resources/openchoreo_components.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/versioned_docs/version-v0.11.x/use-cases/api-management.mdx b/versioned_docs/version-v0.11.x/use-cases/api-management.mdx new file mode 100644 index 0000000..3d4d1b0 --- /dev/null +++ b/versioned_docs/version-v0.11.x/use-cases/api-management.mdx @@ -0,0 +1,373 @@ +--- +title: Securing APIs with OAuth2 Security +description: Configure API gateway, routing, and API management features in OpenChoreo. +sidebar_position: 6 +--- + +import CodeBlock from "@theme/CodeBlock"; +import { versions } from "../_constants.mdx"; + +# Securing APIs with OAuth2 Security + +OpenChoreo provides comprehensive API Management capabilities through its WSO2 API Platform module, including OAuth2 security, AI gateway features with guardrails and MCP authentication, and request transformations. This guide walks you through enabling API Management and securing your APIs with OAuth2 authentication for your components. + +## Prerequisites + +Before you begin, ensure you have: + +- **OpenChoreo installed** in your Kubernetes cluster +- **kubectl** configured to access your cluster +- **Helm 3.12+** installed +- **curl** or similar tool for testing API endpoints + +## Installation + +The API Platform module is **disabled by default**. You need to explicitly enable it during OpenChoreo installation or upgrade. + +### Enable During Initial Installation + +When installing OpenChoreo Dataplane, enable the API Platform module using the `--set` flag: + + +{`helm upgrade --install openchoreo-data-plane ${versions.helmSource}/openchoreo-data-plane \\ + --version ${versions.helmChart} \\ + --namespace openchoreo-data-plane \\ + --create-namespace \\ + --set gateway.httpPort=19080 \\ + --set gateway.httpsPort=19443 \\ + --set external-secrets.enabled=true \\ + --set gateway.envoy.mountTmpVolume=true \\ + --set api-platform.enabled=true`} + + + +### Enable in Existing Installation + +If OpenChoreo Dataplane is already installed, first install the API Platform CRDs: + +```bash +kubectl apply --server-side \ + -f https://raw.githubusercontent.com/wso2/api-platform/gateway-operator-v0.1.0/kubernetes/helm/operator-helm-chart/crds/api.api-platform.wso2.com_apiconfigurations.yaml \ + -f https://raw.githubusercontent.com/wso2/api-platform/gateway-operator-v0.1.0/kubernetes/helm/operator-helm-chart/crds/api.api-platform.wso2.com_gatewayconfigurations.yaml +``` + +Then upgrade the OpenChoreo Data plane to enable API Management: + + + {`helm upgrade --install openchoreo-data-plane ${versions.helmSource}/openchoreo-data-plane \\ + --version ${versions.helmChart} \\ + --namespace openchoreo-data-plane \\ + --reuse-values \\ + --set api-platform.enabled=true`} + + +## Verify Installation + +After enabling the API Platform, verify that all components are running: + +```bash +# Check API Platform pods +kubectl get pods -n openchoreo-data-plane --selector="app.kubernetes.io/instance=api-platform-default-gateway" +``` + +You should see pods similar to: + +``` +NAME READY STATUS RESTARTS AGE +api-platform-default-gateway-controller-6d574f8478-skd8n 1/1 Running 0 17m +api-platform-default-gateway-policy-engine-6ccc5f76b4-m87f7 1/1 Running 0 17m +api-platform-default-gateway-router-55cd96cfc9-njf56 1/1 Running 0 17m +``` + +## Deploy a Sample Service + +Let's deploy the Go Greeter Service to demonstrate API Management capabilities. If you've already deployed this service from the [Deploy Your First Component](../getting-started/deploy-first-component.mdx) guide, you can skip this step. + + + {`kubectl apply -f https://raw.githubusercontent.com/openchoreo/openchoreo/${versions.githubRef}/samples/from-image/go-greeter-service/greeter-service.yaml`} + + +Wait for the deployment to complete: + +```bash +kubectl get releasebinding greeter-service-development +``` + +Test that the service is accessible: + +```bash +curl http://development.openchoreoapis.localhost:19080/greeter-service/greeter/greet\?name\=OpenChoreo +``` + +You should receive: + +```text +Hello, OpenChoreo! +``` + +## Enable API Management for Your Component + +To secure your component with API Management, you need to add an API Management trait. This can be done in two ways: + +### Option 1: Update Component Custom Resource + +Add the API Management trait configuration to your Component resource by applying it directly: + +```bash +kubectl apply -f - < + +6. Click **Add Trait** and **Save Changes** to apply changes to your component. + +:::tip Verify Configuration +Before saving changes, verify the Trait is properly configured with following details. + +``` +Parameters: +apiName: greeter-api +apiVersion: v1.0 +context: /greeter-api/v1.0 +operations: [ { "method": "GET", "path": "/*" }, { "method": "POST", "path": "/*" }, { "method": "PUT", "path": "/*" }, { "method": "DELETE", "path": "/*" }, { "method": "PATCH", "path": "/*" }, { "method": "OPTIONS", "path": "/*" } ] +policies: [ { "name": "JwtAuthentication", "version": "v0.1.0" } ] +upstreamPort: 80 +``` +::: + +## Wait for Configuration to Apply + +Monitor the component to ensure the API Management trait is applied: + +```bash +kubectl get component/greeter-service -o yaml +``` + +Wait for the release to be updated: + +```bash +kubectl get releasebinding greeter-service-development -o yaml +``` + +## Obtain an Access Token + +OpenChoreo Control Plane uses WSO2 Thunder IDP for System Authentication. For testing purposes, OpenChoreo automatically creates an OAuth Application. +Let's obtain an access token using the test OAuth Application. + +Please use the following test credentials to get a token: + +- **Client ID**: `customer-portal-client` +- **Client Secret**: `supersecret` + +### Request an Access Token + +Use the OAuth2 client credentials flow to obtain a token: + +```bash +curl -k -X POST https://thunder.openchoreo.localhost:8443/oauth2/token \ + -d 'grant_type=client_credentials' \ + -d 'client_id=customer-portal-client' \ + -d 'client_secret=supersecret' +``` + +You should receive a response similar to: + +```json +{ + "access_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6Ik11WGVKS...", + "token_type": "Bearer", + "expires_in": 3600 +} +``` + +Save the access token for testing: + +```bash +export ACCESS_TOKEN="eyJhbGciOiJSUzI1NiIsImtpZCI6Ik11WGVKS..." +``` + +## Test API Authentication + +Now let's verify that API Management is working correctly. + +### Test Without Token (Should Fail) + +Try accessing the API without authentication: + +```bash +curl -i http://development.openchoreoapis.localhost:19080/greeter-service/greeter/greet +``` + +You should receive a **401 Unauthorized** response: + +``` +HTTP/1.1 401 Unauthorized +content-type: application/json +content-length: 59 +date: Mon, 22 Dec 2025 16:28:58 GMT +server: envoy +x-envoy-upstream-service-time: 20 + +{"error":"Unauthorized","message":"Authentication failed."} +``` + +This confirms that API Management is protecting your endpoint. + +### Test With Token (Should Succeed) + +Now test with the access token: + +```bash +curl http://development.openchoreoapis.localhost:19080/greeter-service/greeter/greet\?name\=OpenChoreo \ + -H "Authorization: Bearer $ACCESS_TOKEN" +``` + +You should receive a **200 OK** response: + +``` +HTTP/1.1 200 OK +date: Mon, 22 Dec 2025 16:32:11 GMT +content-length: 19 +content-type: text/plain; charset=utf-8 +x-envoy-upstream-service-time: 18 +server: envoy + +Hello, OpenChoreo! +``` + +## Troubleshooting + +### API Platform Pods Not Running + +Check pod status and logs: + +```bash +kubectl get pods -n openchoreo-data-plane -l app.kubernetes.io/instance=api-platform-default-gateway +kubectl logs -n openchoreo-data-plane -l app.kubernetes.io/instance=api-platform-default-gateway +``` + +### Token Validation Failures + +Verify Thunder IDP is accessible: + +```bash +kubectl get svc -n openchoreo-control-plane thunder-service +kubectl logs -n openchoreo-control-plane -l app.kubernetes.io/name=thunder +``` + +### API Still Accessible Without Token + +Check that the component has the API Management trait applied: + +```bash +kubectl get component greeter-service -o jsonpath='{.spec.traits}' +``` + +Verify the release has been updated: + +```bash +kubectl describe releasebinding greeter-service-development +``` + +## Summary + +You've successfully: + +- Enabled the API Platform module in OpenChoreo +- Deployed a sample service and secured it with OAuth2 authentication +- Obtained and validated access tokens using client credentials flow +- Tested OAuth2 token-based access control +- Verified that your API endpoints are protected from unauthorized access + +Your components are now protected with OAuth2 security—all managed declaratively through OpenChoreo! + +## Next Steps + +- [Learn more about WSO2 API Platform policies](https://github.com/wso2/api-platform/tree/gateway-v0.1.0/gateway/policies) +- [Set up Observability and Alerting](../operations/observability-alerting.mdx) +- [Configure Identity Provider Configuration](../operations/identity-configuration.mdx) + +## Clean Up + +To disable API Management for a component, remove the trait: + +```bash +kubectl patch component greeter-service --type=json \ + -p='[{"op": "remove", "path": "/spec/traits"}]' +``` + +To uninstall the API Platform module: + + + {`helm upgrade openchoreo-data-plane ${versions.helmSource}/openchoreo-data-plane \\ + --version ${versions.helmChart} \\ + --namespace openchoreo-data-plane \\ + --reuse-values \\ + --set api-platform.enabled=false`} + diff --git a/versioned_docs/version-v0.11.x/use-cases/api-management.png b/versioned_docs/version-v0.11.x/use-cases/api-management.png new file mode 100644 index 0000000..ad8b230 Binary files /dev/null and b/versioned_docs/version-v0.11.x/use-cases/api-management.png differ diff --git a/versioned_docs/version-v0.11.x/use-cases/deploy-prebuilt-image.mdx b/versioned_docs/version-v0.11.x/use-cases/deploy-prebuilt-image.mdx new file mode 100644 index 0000000..fe2bfc8 --- /dev/null +++ b/versioned_docs/version-v0.11.x/use-cases/deploy-prebuilt-image.mdx @@ -0,0 +1,115 @@ +--- +title: Deploy a Prebuilt Container Image +description: Deploy your existing container images to OpenChoreo without using the Build Plane. +sidebar_position: 5 +--- + +import CodeBlock from "@theme/CodeBlock"; +import { versions } from "../_constants.mdx"; + +# Deploy a Prebuilt Container Image + +This guide walks you through deploying a prebuilt container image to OpenChoreo. This is useful when you have existing container images built by external CI/CD pipelines and want to deploy them without using OpenChoreo's Build Plane. + +## Overview + +OpenChoreo supports deploying applications from prebuilt container images, commonly referred to as "Bring Your Own Image" (BYOI). + +## Prerequisites + +Before you begin, ensure you have: + +- **OpenChoreo installed** in your Kubernetes cluster +- **kubectl** configured to access your cluster +- **A container image** to deploy + +## Deploy an Image + +Deploying an image is straightforward - simply create the Component and Workload resources. + +### Example + +```bash +kubectl apply -f - < /tmp/git-revision.txt + else + echo "Cloning branch: $BRANCH with latest commit" + git clone --single-branch --branch $BRANCH --depth 1 "$CLONE_URL" /mnt/vol/source + cd /mnt/vol/source + COMMIT_SHA=$(git rev-parse HEAD) + echo -n "$COMMIT_SHA" | cut -c1-8 > /tmp/git-revision.txt + fi + command: + - sh + - -c + image: alpine/git + name: "" + volumeMounts: + - mountPath: /mnt/vol + name: workspace + - mountPath: /etc/secrets/git-secret + name: git-secret + readOnly: true + name: clone-step + outputs: + parameters: + - name: git-revision + valueFrom: + path: /tmp/git-revision.txt + volumes: + - name: git-secret + secret: + optional: true + secretName: '{{workflow.parameters.git-secret}}' + - container: + args: + - |- + set -e + + WORKDIR=/mnt/vol/source + + IMAGE="{{workflow.parameters.image-name}}:{{workflow.parameters.image-tag}}-{{inputs.parameters.git-revision}}" + APP_PATH="{{workflow.parameters.app-path}}" + + ##################################################################### + # 1. Podman daemon + storage.conf + ##################################################################### + mkdir -p /etc/containers + cat > /etc/containers/storage.conf </dev/null | grep -q true; do sleep 1; done + + ##################################################################### + # 2. Registry configuration and pull pre-cached images + ##################################################################### + REGISTRY_ENDPOINT="host.k3d.internal:10082" + + # Pull pre-cached buildpack images from registry + BUILDER="${REGISTRY_ENDPOINT}/buildpacks-cache/google-builder:latest" + RUN_IMG="${REGISTRY_ENDPOINT}/buildpacks-cache/google-run:latest" + LIFECYCLE_IMG="${REGISTRY_ENDPOINT}/buildpacks-cache/lifecycle:0.20.5" + + echo "Pulling cached builder: $BUILDER" + podman pull --tls-verify=false "$BUILDER" + + echo "Pulling cached run image: $RUN_IMG" + podman pull --tls-verify=false "$RUN_IMG" + + echo "Pulling cached lifecycle: $LIFECYCLE_IMG" + podman pull --tls-verify=false "$LIFECYCLE_IMG" + + # Tag lifecycle image to expected name (referenced by builder image metadata) + podman tag "$LIFECYCLE_IMG" "docker.io/buildpacksio/lifecycle:0.20.5" + + ##################################################################### + # 3. Build with Google Buildpacks + ##################################################################### + /usr/local/bin/pack build "$IMAGE" \ + --builder "$BUILDER" \ + --run-image "$RUN_IMG" \ + --docker-host inherit \ + --path "$WORKDIR/$APP_PATH" \ + --pull-policy if-not-present + + podman save -o /mnt/vol/app-image.tar "$IMAGE" + command: + - sh + - -c + image: ghcr.io/openchoreo/podman-runner:v1.0 + securityContext: + privileged: true + volumeMounts: + - mountPath: /mnt/vol + name: workspace + inputs: + parameters: + - name: git-revision + name: build-step + - container: + args: + - |- + set -e + + ##################################################################### + # 1. Inputs + ##################################################################### + GIT_REVISION={{inputs.parameters.git-revision}} + IMAGE_NAME={{workflow.parameters.image-name}} + IMAGE_TAG={{workflow.parameters.image-tag}} + SRC_IMAGE="${IMAGE_NAME}:${IMAGE_TAG}-${GIT_REVISION}" + + ##################################################################### + # 2. Registry + ##################################################################### + REGISTRY_ENDPOINT="host.k3d.internal:10082" + + ##################################################################### + # 3. Podman storage configuration + ##################################################################### + mkdir -p /etc/containers + cat < /etc/containers/storage.conf + [storage] + driver = "overlay" + runroot = "/run/containers/storage" + graphroot = "/var/lib/containers/storage" + [storage.options.overlay] + mount_program = "/usr/bin/fuse-overlayfs" + EOF + + ##################################################################### + # 4. Load the tarred image and push to registry + ##################################################################### + podman load -i /mnt/vol/app-image.tar + + podman tag $SRC_IMAGE $REGISTRY_ENDPOINT/$SRC_IMAGE + podman push --tls-verify=false $REGISTRY_ENDPOINT/$SRC_IMAGE + + ##################################################################### + # 5. Emit image reference (for later steps/kubelet pulls) + ##################################################################### + echo -n "$REGISTRY_ENDPOINT/$SRC_IMAGE" > /tmp/image.txt + command: + - sh + - -c + image: ghcr.io/openchoreo/podman-runner:v1.0 + securityContext: + privileged: true + volumeMounts: + - mountPath: /mnt/vol + name: workspace + inputs: + parameters: + - name: git-revision + name: push-step + outputs: + parameters: + - name: image + valueFrom: + path: /tmp/image.txt + - container: + args: + - |- + set -e + + ##################################################################### + # 1. Initialize variables + ##################################################################### + IMAGE={{inputs.parameters.image}} + PROJECT_NAME={{workflow.parameters.project-name}} + COMPONENT_NAME={{workflow.parameters.component-name}} + APP_PATH="{{workflow.parameters.app-path}}" + + DESCRIPTOR_PATH="/mnt/vol/source${APP_PATH:+/${APP_PATH#/}}" + + OUTPUT_PATH="/mnt/vol/workload-cr.yaml" + + echo "Creating workload with image: ${IMAGE}" + echo "Using descriptor in: ${DESCRIPTOR_PATH}" + + ##################################################################### + # 2. Podman storage configuration + ##################################################################### + mkdir -p /etc/containers + cat < /etc/containers/storage.conf + [storage] + driver = "overlay" + runroot = "/run/containers/storage" + graphroot = "/var/lib/containers/storage" + [storage.options.overlay] + mount_program = "/usr/bin/fuse-overlayfs" + EOF + + ##################################################################### + # 3. Create workload CR and export to output + ##################################################################### + # Check if workload.yaml exists and build the command accordingly + if [ -f "${DESCRIPTOR_PATH}/workload.yaml" ]; then + echo "Found workload.yaml descriptor, using it for workload creation" + podman run --rm --network=none \ + -v $DESCRIPTOR_PATH:/app:rw -w /app \ + ghcr.io/openchoreo/openchoreo-cli:latest-dev \ + create workload \ + --project "${PROJECT_NAME}" \ + --component "${COMPONENT_NAME}" \ + --image "${IMAGE}" \ + --descriptor "workload.yaml" \ + -o "workload-cr.yaml" + else + echo "No workload.yaml descriptor found, creating workload without descriptor" + podman run --rm --network=none \ + -v $DESCRIPTOR_PATH:/app:rw -w /app \ + ghcr.io/openchoreo/openchoreo-cli:latest-dev \ + create workload \ + --project "${PROJECT_NAME}" \ + --component "${COMPONENT_NAME}" \ + --image "${IMAGE}" \ + -o "workload-cr.yaml" + fi + + # Copy output CR to the shared volume + cp -f "${DESCRIPTOR_PATH}/workload-cr.yaml" "${OUTPUT_PATH}" + command: + - sh + - -c + image: ghcr.io/openchoreo/podman-runner:v1.0 + securityContext: + privileged: true + volumeMounts: + - mountPath: /mnt/vol + name: workspace + inputs: + parameters: + - name: image + name: workload-create-step + outputs: + parameters: + - name: workload-cr + valueFrom: + path: /mnt/vol/workload-cr.yaml + ttlStrategy: + secondsAfterCompletion: 3600 + volumeClaimTemplates: + - metadata: + creationTimestamp: null + name: workspace + spec: + accessModes: + - ReadWriteOnce + resources: + requests: + storage: 2Gi +``` + +## Step 2: Create ComponentWorkflow + +The ComponentWorkflow defines the schema and references the ClusterWorkflowTemplate. + +### Example: Go ComponentWorkflow + +```yaml +apiVersion: openchoreo.dev/v1alpha1 +kind: ComponentWorkflow +metadata: + name: google-cloud-buildpacks + namespace: default +spec: + schema: + parameters: {} + systemParameters: + repository: + appPath: string | default=. description="Path to the application directory + within the repository" + revision: + branch: string | default=main description="Git branch to checkout" + commit: string | description="Git commit SHA or reference (optional, defaults + to latest)" + url: string | description="Git repository URL" + runTemplate: + apiVersion: argoproj.io/v1alpha1 + kind: Workflow + metadata: + name: ${metadata.workflowRunName} + namespace: openchoreo-ci-${metadata.orgName} + spec: + arguments: + parameters: + - name: component-name + value: ${metadata.componentName} + - name: project-name + value: ${metadata.projectName} + - name: git-repo + value: ${systemParameters.repository.url} + - name: branch + value: ${systemParameters.repository.revision.branch} + - name: commit + value: ${systemParameters.repository.revision.commit} + - name: app-path + value: ${systemParameters.repository.appPath} + - name: image-name + value: ${metadata.projectName}-${metadata.componentName}-image + - name: image-tag + value: v1 + - name: git-secret + value: ${metadata.workflowRunName}-git-secret + serviceAccountName: workflow-sa + workflowTemplateRef: + clusterScope: true + name: google-cloud-buildpacks + resources: + - id: git-secret + template: + apiVersion: external-secrets.io/v1 + kind: ExternalSecret + metadata: + name: ${metadata.workflowRunName}-git-secret + namespace: openchoreo-ci-${metadata.orgName} + spec: + data: + - remoteRef: + key: git-token + secretKey: git-token + refreshInterval: 15s + secretStoreRef: + kind: ClusterSecretStore + name: default + target: + creationPolicy: Owner + name: ${metadata.workflowRunName}-git-secret +``` + +## Step 3: Allow ComponentWorkflow in ComponentType + +After creating the ClusterWorkflowTemplate and ComponentWorkflow, the final step is to make the workflow available to developers by adding it to the `allowedWorkflows` list in ComponentType CRs. + +### Why This Step is Required + +ComponentTypes act as governance boundaries that control which build strategies developers can use. The `allowedWorkflows` field explicitly lists which ComponentWorkflows are permitted for components of that type. + +### Update ComponentType CR + +Add the custom workflow name to the `allowedWorkflows` array in the relevant ComponentType CR: + +```yaml +apiVersion: openchoreo.dev/v1alpha1 +kind: ComponentType +metadata: + name: service + namespace: default +spec: + workloadType: deployment + allowedWorkflows: + - google-cloud-buildpacks # Existing workflow + - ballerina-buildpack # Existing workflow + - docker # Existing workflow + + # Schema and resources configuration + schema: + # ... component schema definition + resources: + # ... resource templates +``` diff --git a/versioned_docs/version-v0.11.x/user-guide/ci/external-container-registry.mdx b/versioned_docs/version-v0.11.x/user-guide/ci/external-container-registry.mdx new file mode 100644 index 0000000..e222c54 --- /dev/null +++ b/versioned_docs/version-v0.11.x/user-guide/ci/external-container-registry.mdx @@ -0,0 +1,325 @@ +--- +title: External Container Registry +description: Learn how to configure OpenChoreo to use external container registries like Docker Hub, AWS ECR, GCR, or ACR for storing and pulling container images in both build and data planes. +sidebar_position: 7 +--- + +# Configure External Container Registry + +This guide explains how to configure OpenChoreo to use an external container registry instead of the built-in one. External registries like Docker Hub, AWS ECR, Google Container Registry (GCR), or Azure Container Registry (ACR) can be used for storing container images. + +:::info Architecture +OpenChoreo uses separate planes for building and running applications: +- **Build Plane**: Where images are built and pushed to the registry (requires push credentials) +- **Data Plane**: Where applications run and pull images from the registry (requires pull credentials) + +Both planes need to be configured separately. +::: + +## Part 1: Configure Build Plane (Push Credentials) + +The Build Plane needs credentials to push built container images to your external registry. + +### Step 1: Install Build Plane with Registry Configuration + +When installing the build plane, configure the external registry endpoint and TLS settings: + +```bash +helm upgrade --install openchoreo-build-plane oci://ghcr.io/openchoreo/helm-charts/openchoreo-build-plane \ + --version 0.0.0-latest-dev \ + --namespace openchoreo-build-plane \ + --create-namespace \ + --set external-secrets.enabled=false \ + --set registry.enabled=false \ + --set global.defaultResources.registry.endpoint=registry.example.com \ + --set global.defaultResources.registry.tlsVerify=true +``` + +**Key Settings:** +- `registry.enabled=false` - Disables the built-in registry +- `global.defaultResources.registry.endpoint` - Your external registry endpoint +- `global.defaultResources.registry.tlsVerify` - Enable TLS verification (set to `false` only for local development) + +### Step 2: (Optional) Disable Default Workflow Templates + +If you need to customize the workflow templates, disable the default ones: + +```yaml +global: + defaultResources: + enabled: false +``` + +Then, create custom `ClusterWorkflowTemplates` based on the [default templates](https://github.com/openchoreo/openchoreo/tree/main/install/helm/openchoreo-build-plane/templates/workflow-templates) in the OpenChoreo repository. + +### Step 3: Add Registry Push Credentials + +#### For Development/Testing (Fake Provider) + +Create a Docker config JSON file with your registry credentials: + +```json +{ + "auths": { + "https://index.docker.io/v1/": { + "auth": "" + } + } +} +``` + +Add the credentials to the ClusterSecretStore in the build plane: + +```bash +kubectl patch clustersecretstore default --type='json' -p='[ + { + "op": "add", + "path": "/spec/provider/fake/data/-", + "value": { + "key": ".dockerconfigjson", + "value": "{\"auths\":{\"https://index.docker.io/v1/\":{\"auth\":\"\"}}}" + } + } +]' +``` + +#### For Production + +Use a real secret backend like AWS Secrets Manager, HashiCorp Vault, Azure Key Vault, or Google Secret Manager. Store the Docker config JSON in your secret backend and configure the ClusterSecretStore accordingly. + +### Step 4: Update ComponentWorkflow with Registry Credentials + +Add an ExternalSecret resource to your ComponentWorkflow to provide registry push credentials: + +```yaml +apiVersion: openchoreo.dev/v1alpha1 +kind: ComponentWorkflow +metadata: + name: docker + namespace: default +spec: + schema: + # ... schema definition + + runTemplate: + apiVersion: argoproj.io/v1alpha1 + kind: Workflow + metadata: + name: ${metadata.workflowRunName} + namespace: openchoreo-ci-${metadata.orgName} + spec: + arguments: + parameters: + # ... other parameters + - name: registry-push-secret + value: ${metadata.workflowRunName}-registry-push-secret + serviceAccountName: workflow-sa + workflowTemplateRef: + clusterScope: true + name: docker + + resources: + - id: registry-push-secret + template: + apiVersion: external-secrets.io/v1 + kind: ExternalSecret + metadata: + name: ${metadata.workflowRunName}-registry-push-secret + namespace: openchoreo-ci-${metadata.orgName} + spec: + refreshInterval: 15s + secretStoreRef: + name: default + kind: ClusterSecretStore + target: + name: ${metadata.workflowRunName}-registry-push-secret + creationPolicy: Owner + data: + - secretKey: .dockerconfigjson + remoteRef: + key: .dockerconfigjson +``` + +### Step 5: Update ClusterWorkflowTemplate Push Step + +Modify the push step in your ClusterWorkflowTemplate to use the registry credentials: + +```yaml +- name: push-step + inputs: + parameters: + - name: git-revision + outputs: + parameters: + - name: image + valueFrom: + path: /tmp/image.txt + volumes: + - name: registry-push-secret + secret: + secretName: '{{workflow.parameters.registry-push-secret}}' + container: + image: ghcr.io/openchoreo/podman-runner:v1.0 + command: [sh, -c] + securityContext: + privileged: true + volumeMounts: + - mountPath: /mnt/vol + name: workspace + - mountPath: /etc/secrets/registry-push-secret + name: registry-push-secret + readOnly: true + args: + - |- + set -e + + ##################################################################### + # 1. Inputs + ##################################################################### + GIT_REVISION={{inputs.parameters.git-revision}} + IMAGE_NAME={{workflow.parameters.image-name}} + IMAGE_TAG={{workflow.parameters.image-tag}} + SRC_IMAGE="${IMAGE_NAME}:${IMAGE_TAG}-${GIT_REVISION}" + + ##################################################################### + # 2. Registry Configuration + ##################################################################### + REGISTRY_ENDPOINT="{{workflow.parameters.registry-endpoint}}" + AUTH_FILE="/etc/secrets/registry-push-secret/.dockerconfigjson" + + ##################################################################### + # 3. Podman Storage Configuration + ##################################################################### + mkdir -p /etc/containers + cat < /etc/containers/storage.conf + [storage] + driver = "overlay" + runroot = "/run/containers/storage" + graphroot = "/var/lib/containers/storage" + [storage.options.overlay] + mount_program = "/usr/bin/fuse-overlayfs" + EOF + + ##################################################################### + # 4. Load Image and Push to Registry + ##################################################################### + podman load -i /mnt/vol/app-image.tar + podman tag $SRC_IMAGE $REGISTRY_ENDPOINT/$SRC_IMAGE + podman push --authfile "$AUTH_FILE" --tls-verify=true $REGISTRY_ENDPOINT/$SRC_IMAGE + + ##################################################################### + # 5. Emit Image Reference + ##################################################################### + echo -n "$REGISTRY_ENDPOINT/$SRC_IMAGE" > /tmp/image.txt +``` + +**Key Changes Compared to Default Push Step in Default Templates:** + +This modified push step differs from the default in the following ways: + +1. **Mounts the registry push secret as a volume**: The `registry-push-secret` is mounted at `/etc/secrets/registry-push-secret` to provide authentication credentials +2. **Uses the secret for authentication**: The `--authfile` flag references the `.dockerconfigjson` file from the mounted secret +3. **Enables TLS verification**: Uses `--tls-verify=true` for secure communication with production registries (set to `false` only for local development) +4. **Dynamic registry endpoint**: Uses `{{workflow.parameters.registry-endpoint}}` instead of a hardcoded value, making it configurable per workflow execution + +## Part 2: Configure Data Plane (Pull Credentials) + +The Data Plane needs credentials to pull container images when deploying applications. + +### Step 1: Add Pull Credentials to Data Plane + +#### For Development/Testing (Fake Provider) + +Add the pull credentials to the ClusterSecretStore in each data plane cluster: + +```bash +kubectl patch clustersecretstore default --type='json' -p='[ + { + "op": "add", + "path": "/spec/provider/fake/data/-", + "value": { + "key": "registry-pull-credentials", + "value": "{\"auths\":{\"registry.example.com\":{\"auth\":\"\"}}}" + } + } +]' +``` + +#### For Production + +Configure the ClusterSecretStore in your data plane to use a real secret backend (same as build plane). + +### Step 2: Add imagePullSecrets to ComponentType + +Configure your ComponentType to create an ExternalSecret for pull credentials and reference it in the Deployment: + +```yaml +apiVersion: openchoreo.dev/v1alpha1 +kind: ComponentType +metadata: + name: service + namespace: default +spec: + workloadType: deployment + + schema: + # ... schema definition + + resources: + # ExternalSecret for registry pull credentials + - id: registry-pull-secret + template: + apiVersion: external-secrets.io/v1 + kind: ExternalSecret + metadata: + name: ${metadata.name}-registry-pull-secret + namespace: ${metadata.namespace} + spec: + refreshInterval: 15s + secretStoreRef: + name: default + kind: ClusterSecretStore + target: + name: ${metadata.name}-registry-pull-secret + creationPolicy: Owner + template: + type: kubernetes.io/dockerconfigjson + data: + - secretKey: .dockerconfigjson + remoteRef: + key: registry-pull-credentials + + # Deployment that uses the pull secret + - id: deployment + template: + apiVersion: apps/v1 + kind: Deployment + metadata: + name: ${metadata.name} + namespace: ${metadata.namespace} + spec: + replicas: ${parameters.replicas} + selector: + matchLabels: + app: ${metadata.name} + template: + metadata: + labels: + app: ${metadata.name} + spec: + # Reference the pull secret + imagePullSecrets: + - name: ${metadata.name}-registry-pull-secret + containers: + - name: ${parameters.containerName} + image: ${workload.containers[parameters.containerName].image} + ports: + - containerPort: ${workload.containers[parameters.containerName].port} + # ... other container configuration +``` + +## Related Resources + +- [ComponentWorkflow API Reference](../../reference/api/platform/componentworkflow.md) +- [ComponentType API Reference](../../reference/api/platform/componenttype.md) +- [External Secrets Operator Documentation](https://external-secrets.io/) diff --git a/versioned_docs/version-v0.11.x/user-guide/ci/overview.md b/versioned_docs/version-v0.11.x/user-guide/ci/overview.md new file mode 100644 index 0000000..5665fe9 --- /dev/null +++ b/versioned_docs/version-v0.11.x/user-guide/ci/overview.md @@ -0,0 +1,379 @@ +--- +title: Overview +description: Understand how CI works in OpenChoreo using ComponentWorkflows and Argo Workflows +sidebar_position: 1 +--- + +# CI with OpenChoreo + +OpenChoreo's CI capabilities enable platform engineers to define, manage, and execute build and automation workflows. By leveraging Kubernetes-native technologies like Argo Workflows, OpenChoreo provides a scalable and flexible CI solution that integrates seamlessly with existing DevOps toolchains. + +:::note +OpenChoreo currently supports only Argo Workflows as the underlying engine for executing CI workflows. It can be extended to support more Kubernetes-native engines. +::: + +## Core Concepts + +### ComponentWorkflow + +A **ComponentWorkflow** is a platform engineer-defined template that specifies *how* to build applications. It consists of: + +- **Schema**: Defines system parameters (fixed structure for repository, branch, commit) and developer parameters (flexible, PE-defined fields like version, build options, resources) +- **RunTemplate**: An Argo Workflow template with template variables (`${metadata.*}`, `${systemParameters.*}`, `${parameters.*}`) +- **Resources**: Additional Kubernetes resources needed for the workflow (e.g., ExternalSecrets for Git credentials) + +ComponentWorkflows live in the control plane and are referenced by Components. Platform engineers control which workflows are available and what parameters developers can configure. + +### ComponentWorkflowRun + +A **ComponentWorkflowRun** represents a single execution instance of a ComponentWorkflow. When created, it: + +- References the Component being built (projectName, componentName) +- References the ComponentWorkflow to use +- Provides actual values for system and developer parameters +- Tracks execution state through conditions (WorkflowPending, WorkflowRunning, WorkflowSucceeded, WorkflowFailed, WorkloadUpdated) +- Stores outputs (image reference, resource references, workflow run reference) + +ComponentWorkflowRuns are created either manually or automatically (e.g., via Git webhooks). + +:::warning Imperative Resource +ComponentWorkflowRun is an **imperative** resource, it triggers an action (a build) rather than declaring a desired state. Each time a ComponentWorkflowRun is applied, it initiates a new build execution. For this reason, do not include ComponentWorkflowRuns in GitOps repositories. Instead, create them through Git webhooks, the UI, or direct `kubectl apply` commands. +::: + +## Architecture + + + +### Multi-Plane Separation + +- **Control Plane**: Hosts ComponentWorkflow and ComponentWorkflowRun CRs, orchestrates workflow execution +- **Build Plane**: Executes Argo Workflows using ClusterWorkflowTemplates, performs compute-intensive build operations +- **Communication**: Control plane controller connects to build plane via a websocket connection + +In Single Cluster Setup, both planes run in the same cluster. + +## Execution Lifecycle + +When a ComponentWorkflowRun is created, the following lifecycle occurs: + +1. **Initialization**: ComponentWorkflowRun CR created (manually or via webhook) +2. **Template Rendering**: Controller fetches ComponentWorkflow and renders the runTemplate by substituting all template variables with values from ComponentWorkflowRun +3. **Build Plane Setup**: Controller creates namespace (`openchoreo-ci-{orgName}`), ServiceAccount, Role, and RoleBinding in build plane +4. **Resource Application**: Additional resources (ExternalSecrets, ConfigMaps, etc.) applied to build plane +5. **Workflow Execution**: Rendered Argo Workflow applied to build plane, execution begins +6. **Status Polling**: Controller polls workflow status and updates ComponentWorkflowRun conditions: + - `WorkflowCompleted`: Workflow completed either successfully or with failure + - `WorkflowRunning`: Argo Workflow executing + - `WorkflowSucceeded`: Workflow completed successfully + - `WorkflowFailed`: Workflow failed or errored +7. **Workload Creation**: On success, controller extracts image reference from push-step output and creates/updates Workload CR +8. **Completion**: `WorkloadUpdated` condition set to true, reconciliation complete + +### Resource Cleanup + +When a ComponentWorkflowRun is deleted: +- Controller removes all resources created in build plane (ExternalSecrets, ConfigMaps, Workflow, etc.) + +## Default ComponentWorkflows + +OpenChoreo ships with four default ComponentWorkflows installed in the control plane: + +- **docker**: Builds container images using Docker/Podman with a Dockerfile +- **google-cloud-buildpacks**: Builds container images using Google Cloud Buildpacks (auto-detects language) +- **ballerina-buildpack**: Builds Ballerina applications using Ballerina-specific buildpacks +- **react**: Builds React applications with optimized frontend build process + +These workflows reference corresponding ClusterWorkflowTemplates in the build plane. + +## ClusterWorkflowTemplate + +ClusterWorkflowTemplates are an Argo Workflows concept used to define reusable workflow templates at cluster scope in the build plane. For more details, refer to the [Argo Workflows documentation](https://argo-workflows.readthedocs.io/en/latest/cluster-workflow-templates/). + +OpenChoreo ships four default ClusterWorkflowTemplates in the build plane: + +- **docker**: Docker-based builds using Dockerfile +- **google-cloud-buildpacks**: Google Cloud Buildpacks with automatic language detection +- **ballerina-buildpack**: Ballerina-specific buildpack builds +- **react**: React application builds + +Each template defines a standard four-step build workflow: + +## Build Workflow Steps + +### 1. Clone Step + +Clones the source repository (private or public) and supports both branch and specific commit checkout. + +**Key features:** +- Automatic Git provider detection (GitHub, GitLab, Bitbucket) +- Private repository authentication +- Specific commit checkout or latest commit on branch + +```yaml +##################################################################### +# 1. Initialize variables +##################################################################### +BRANCH={{workflow.parameters.branch}} +REPO_URL={{workflow.parameters.git-repo}} +COMMIT={{workflow.parameters.commit}} + +##################################################################### +# 2. Read authentication token +##################################################################### +TOKEN_FILE="/etc/secrets/git-secret/git-token" +GIT_TOKEN="" +if [ -f "$TOKEN_FILE" ]; then + GIT_TOKEN="$(cat "$TOKEN_FILE")" +fi + +##################################################################### +# 3. Build authenticated repository URL +##################################################################### +CLONE_URL="$REPO_URL" +if [ -n "$GIT_TOKEN" ]; then + HOST=$(echo "$REPO_URL" | sed -E 's|https://([^/]+)/.*|\1|') + REPO_PATH=$(echo "$REPO_URL" | sed -E 's|https://[^/]+/(.*)|\1|') + + # Map host to authentication prefix + case "$HOST" in + github.com) AUTH_PREFIX="x-access-token" ;; + gitlab.com) AUTH_PREFIX="oauth2" ;; + bitbucket.org) AUTH_PREFIX="x-token-auth" ;; + *) AUTH_PREFIX="" ;; + esac + + if [ -n "$AUTH_PREFIX" ]; then + CLONE_URL="https://${AUTH_PREFIX}:${GIT_TOKEN}@${HOST}/${REPO_PATH}" + fi +fi + +echo "Cloning repository..." + +##################################################################### +# 4. Clone repository +##################################################################### +if [[ -n "$COMMIT" ]]; then + echo "Cloning specific commit: $COMMIT" + git clone --no-checkout --depth 1 "$CLONE_URL" /mnt/vol/source + cd /mnt/vol/source + git config --global advice.detachedHead false + git fetch --depth 1 origin "$COMMIT" + git checkout "$COMMIT" + echo -n "$COMMIT" | cut -c1-8 > /tmp/git-revision.txt +else + echo "Cloning branch: $BRANCH with latest commit" + git clone --single-branch --branch $BRANCH --depth 1 "$CLONE_URL" /mnt/vol/source + cd /mnt/vol/source + COMMIT_SHA=$(git rev-parse HEAD) + echo -n "$COMMIT_SHA" | cut -c1-8 > /tmp/git-revision.txt +fi +``` +### 2. Build Step + +The build step executes the actual container image build process. The specific commands vary based on the selected build strategy. + +**Example: Docker build step** + +```yaml +WORKDIR=/mnt/vol/source +IMAGE="{{workflow.parameters.image-name}}:{{workflow.parameters.image-tag}}-{{inputs.parameters.git-revision}}" +DOCKER_CONTEXT="{{workflow.parameters.docker-context}}" +DOCKERFILE_PATH="{{workflow.parameters.dockerfile-path}}" + +##################################################################### +# 1. Podman daemon + storage.conf +##################################################################### +mkdir -p /etc/containers +cat > /etc/containers/storage.conf < /etc/containers/storage.conf +[storage] +driver = "overlay" +runroot = "/run/containers/storage" +graphroot = "/var/lib/containers/storage" +[storage.options.overlay] +mount_program = "/usr/bin/fuse-overlayfs" +EOF + +##################################################################### +# 4. Load the tarred image and push to registry +##################################################################### +podman load -i /mnt/vol/app-image.tar + +podman tag $SRC_IMAGE $REGISTRY_ENDPOINT/$SRC_IMAGE +podman push --tls-verify=false $REGISTRY_ENDPOINT/$SRC_IMAGE + +##################################################################### +# 5. Emit image reference (for later steps/kubelet pulls) +##################################################################### +echo -n "$REGISTRY_ENDPOINT/$SRC_IMAGE" > /tmp/image.txt +``` + +### 4. WorkloadCreate Step + +The WorkloadCreate step generates a Workload CR (Custom Resource) that defines the runtime specification for the Component. A Workload includes container configurations, network endpoints, and connections to other services. + +**Process:** +1. Checks for `workload.yaml` descriptor in the repository at the specified `appPath` +2. Uses `openchoreo-cli` to create Workload CR +3. Outputs the Workload CR YAML + +**Behavior:** +- **With workload.yaml**: Full workload specification with endpoints, connections, and configurations +- **Without workload.yaml**: Basic workload with just the container image (additional configurations can be added at deployment time) + +The ComponentWorkflowRun controller retrieves this Workload CR from the workflow output and creates/updates the Workload resource in the control plane. + + +```yaml +##################################################################### +# 1. Initialize variables +##################################################################### +IMAGE={{inputs.parameters.image}} +PROJECT_NAME={{workflow.parameters.project-name}} +COMPONENT_NAME={{workflow.parameters.component-name}} +APP_PATH="{{workflow.parameters.app-path}}" + +DESCRIPTOR_PATH="/mnt/vol/source${APP_PATH:+/${APP_PATH#/}}" + +OUTPUT_PATH="/mnt/vol/workload-cr.yaml" + +echo "Creating workload with image: ${IMAGE}" +echo "Using descriptor in: ${DESCRIPTOR_PATH}" + +##################################################################### +# 2. Podman storage configuration +##################################################################### +mkdir -p /etc/containers +cat < /etc/containers/storage.conf +[storage] +driver = "overlay" +runroot = "/run/containers/storage" +graphroot = "/var/lib/containers/storage" +[storage.options.overlay] +mount_program = "/usr/bin/fuse-overlayfs" +EOF + +##################################################################### +# 3. Create workload CR and export to output +##################################################################### +# Check if workload.yaml exists and build the command accordingly +if [ -f "${DESCRIPTOR_PATH}/workload.yaml" ]; then + echo "Found workload.yaml descriptor, using it for workload creation" + podman run --rm --network=none \ + -v $DESCRIPTOR_PATH:/app:rw -w /app \ + ghcr.io/openchoreo/openchoreo-cli:latest-dev \ + create workload \ + --project "${PROJECT_NAME}" \ + --component "${COMPONENT_NAME}" \ + --image "${IMAGE}" \ + --descriptor "workload.yaml" \ + -o "workload-cr.yaml" +else + echo "No workload.yaml descriptor found, creating workload without descriptor" + podman run --rm --network=none \ + -v $DESCRIPTOR_PATH:/app:rw -w /app \ + ghcr.io/openchoreo/openchoreo-cli:latest-dev \ + create workload \ + --project "${PROJECT_NAME}" \ + --component "${COMPONENT_NAME}" \ + --image "${IMAGE}" \ + -o "workload-cr.yaml" +fi + +# Copy output CR to the shared volume +cp -f "${DESCRIPTOR_PATH}/workload-cr.yaml" "${OUTPUT_PATH}" +``` +:::important +The workload CR is an output of the workload-create-step with the parameter name `workload-cr`. This name must remain consistent even when creating custom ClusterWorkflowTemplates, as the ComponentWorkflowRun controller expects this specific output parameter to retrieve the generated Workload CR. + +```yaml +name: workload-create-step +outputs: + parameters: + - name: workload-cr + valueFrom: + path: /mnt/vol/workload-cr.yaml +``` +::: + +## Workflow Governance + +### Allowing ComponentWorkflows for Components + +Platform engineers control which ComponentWorkflows are available to developers by configuring the `allowedWorkflows` field in ComponentType CRs. + +**Example configuration:** + +```yaml +apiVersion: openchoreo.dev/v1alpha1 +kind: ComponentType +metadata: + name: service + namespace: default +spec: + workloadType: deployment + allowedWorkflows: + - google-cloud-buildpacks + - ballerina-buildpack + - docker + # ... other ComponentType spec fields +``` + +**Benefits:** +- **Governance**: Only approved build strategies can be used +- **Consistency**: Enforces organizational build standards +- **Compliance**: Ensures security scanning and build policies are applied +- **Flexibility**: Different component types can have different allowed workflows + +Components can only reference workflows from their component type's allowed list. This prevents developers from using unapproved or potentially insecure build processes. diff --git a/versioned_docs/version-v0.11.x/user-guide/ci/overview.png b/versioned_docs/version-v0.11.x/user-guide/ci/overview.png new file mode 100644 index 0000000..28c8bd5 Binary files /dev/null and b/versioned_docs/version-v0.11.x/user-guide/ci/overview.png differ diff --git a/versioned_docs/version-v0.11.x/user-guide/ci/private-repository-multiple.md b/versioned_docs/version-v0.11.x/user-guide/ci/private-repository-multiple.md new file mode 100644 index 0000000..38ea25f --- /dev/null +++ b/versioned_docs/version-v0.11.x/user-guide/ci/private-repository-multiple.md @@ -0,0 +1,215 @@ +--- +title: Multiple Private Git Organizations +description: Configure workflows to authenticate with private repositories across multiple Git organizations, groups, or workspaces +sidebar_position: 6 +--- + +# Configure Multiple Private Git Organizations + +When your organization works with private repositories across multiple Git organizations, groups, or workspaces, you can configure ComponentWorkflows to let developers select which credentials to use for their builds. This eliminates the need to create separate workflows for each Git organization. + +## Use Cases + +- **Multiple GitHub Organizations**: Your company has separate GitHub organizations for different teams or projects +- **Multiple GitLab Groups**: Different GitLab groups for frontend, backend, and infrastructure repositories +- **Multiple Bitbucket Workspaces**: Separate Bitbucket workspaces for different business units +- **Mixed Providers**: Some projects in GitHub, others in GitLab or Bitbucket +- **Client Projects**: Building applications from different client organizations + +## How It Works + +Instead of hardcoding a single Git token: + +1. **Add a parameter** to the ComponentWorkflow schema that lets developers select the Git organization +2. **Store multiple tokens** in your secret backend, one for each organization/group/workspace +3. **Dynamically reference** the appropriate token based on the developer's selection + +## Configuration Steps + +### Step 1: Create Git Tokens for Each Organization + +Create a separate Personal Access Token (PAT) for each Git organization you want to support. + +### Step 2: Switch to Build Plane Context + +If your control plane and build plane are in **separate Kubernetes clusters**, switch to the build plane cluster context. This is where workflow execution and git cloning happens. + +```bash +kubectl config use-context +``` + +### Step 3: Store Tokens in Secret Backend + +Store each token in your secret backend using a naming convention like `-git-token`. + +**For Development/Testing (Fake Provider):** + +```bash +# Add token for organization A +kubectl patch clustersecretstore default --type='json' -p='[ + { + "op": "add", + "path": "/spec/provider/fake/data/-", + "value": { + "key": "github-acme-corp-git-token", + "value": "ghp_xxxxxxxxxxxx" + } + } +]' + +# Add token for organization B +kubectl patch clustersecretstore default --type='json' -p='[ + { + "op": "add", + "path": "/spec/provider/fake/data/-", + "value": { + "key": "github-acme-labs-git-token", + "value": "ghp_yyyyyyyyyyyy" + } + } +]' + +# Add token for organization C +kubectl patch clustersecretstore default --type='json' -p='[ + { + "op": "add", + "path": "/spec/provider/fake/data/-", + "value": { + "key": "github-open-source-git-token", + "value": "ghp_zzzzzzzzzzzz" + } + } +]' +``` + +**For Production (AWS Secrets Manager, Vault, etc.):** + +Store secrets with keys following the same pattern: +- `github-acme-corp-git-token` +- `github-acme-labs-git-token` +- `github-open-source-git-token` + +### Step 4: Configure ComponentWorkflow with Selection Parameter + +Add a parameter to your ComponentWorkflow schema that allows developers to select the Git organization: + +```yaml +apiVersion: openchoreo.dev/v1alpha1 +kind: ComponentWorkflow +metadata: + name: docker + namespace: default +spec: + schema: + systemParameters: + repository: + url: string | description="Git repository URL" + revision: + branch: string | default=main description="Git branch to checkout" + commit: string | description="Git commit SHA (optional)" + appPath: string | default=. description="Path to application directory" + + parameters: + # Parameter for selecting Git organization + gitOrganization: string | default=github-acme-corp enum=github-acme-corp,github-acme-labs,github-open-source description="Git organization/group/workspace to use for authentication" + docker: + context: string | default=. description="Docker build context path relative to the repository root" + filePath: string | default=./Dockerfile description="Path to the Dockerfile relative to the repository root" + + resources: + - id: git-secret + template: + apiVersion: external-secrets.io/v1 + kind: ExternalSecret + metadata: + name: ${metadata.workflowRunName}-git-secret + namespace: openchoreo-ci-${metadata.orgName} + spec: + refreshInterval: 15s + secretStoreRef: + name: default + kind: ClusterSecretStore + target: + name: ${metadata.workflowRunName}-git-secret + creationPolicy: Owner + data: + # Dynamically fetch token based on selected organization + - secretKey: git-token + remoteRef: + key: ${parameters.gitOrganization}-git-token + + runTemplate: + apiVersion: argoproj.io/v1alpha1 + kind: Workflow + metadata: + name: ${metadata.workflowRunName} + namespace: openchoreo-ci-${metadata.orgName} + spec: + arguments: + parameters: + - name: component-name + value: ${metadata.componentName} + - name: project-name + value: ${metadata.projectName} + - name: git-repo + value: ${systemParameters.repository.url} + - name: branch + value: ${systemParameters.repository.revision.branch} + - name: commit + value: ${systemParameters.repository.revision.commit} + - name: app-path + value: ${systemParameters.repository.appPath} + - name: image-name + value: ${metadata.projectName}-${metadata.componentName}-image + - name: image-tag + value: v1 + - name: git-secret + value: ${metadata.workflowRunName}-git-secret + serviceAccountName: workflow-sa + workflowTemplateRef: + clusterScope: true + name: docker +``` + +**Key Points:** + +1. **Parameter Definition**: `gitOrganization` parameter with enum constraining available options +2. **Default Value**: Set a sensible default (e.g., your primary organization) +3. **Dynamic Secret Key**: Use `${parameters.gitOrganization}-git-token` to fetch the correct token +4. **SecretKey**: Always use `git-token` as the secretKey (not the full key path) so the clone step works correctly + +### Step 5: Use in Components + +Developers can now select the Git organization when creating components: + +```yaml +apiVersion: openchoreo.dev/v1alpha1 +kind: Component +metadata: + name: my-service + namespace: default +spec: + owner: + projectName: my-project + componentType: deployment/service + + workflow: + name: docker + systemParameters: + repository: + url: "https://github.com/acme-labs/private-repo" # Repository in acme-labs org + revision: + branch: "main" + appPath: "/" + parameters: + gitOrganization: "github-acme-labs" # Select the corresponding organization + docker: + context: "/" + filePath: "/Dockerfile" +``` + +## See Also + +- [Private Repositories](./private-repository.mdx) - Basic private repository setup +- [Additional Resources](./additional-resources.md) - Working with ExternalSecrets and other resources +- [Component Workflow Schema](./component-workflow-schema.md) - Parameter system documentation diff --git a/versioned_docs/version-v0.11.x/user-guide/ci/private-repository.mdx b/versioned_docs/version-v0.11.x/user-guide/ci/private-repository.mdx new file mode 100644 index 0000000..ef105d6 --- /dev/null +++ b/versioned_docs/version-v0.11.x/user-guide/ci/private-repository.mdx @@ -0,0 +1,131 @@ +--- +title: Private Git Repository +description: Learn how to build applications from private Git repositories using ComponentWorkflows +sidebar_position: 5 +--- + +# Configure a Private Git Repository + +OpenChoreo's ComponentWorkflows support building from private Git repositories that require authentication. Private repository support is built-in for all default workflows. + +Follow these steps to enable private repository access: + +### Step 1: Create a Git Personal Access Token + +Create a git token with read access to your repositories. + +### Step 2: Switch to Build Plane Context + +Switch to the build plane cluster context. This is where workflow execution and git cloning happens. + +```bash +kubectl config use-context +``` + +### Step 3: Store the Token in the Key Vault + +**For Development/Testing (using fake provider):** + +```bash +kubectl patch clustersecretstore default --type='json' -p='[ + { + "op": "add", + "path": "/spec/provider/fake/data/-", + "value": { + "key": "git-token", + "value": "GitAccessToken" + } + } +]' +``` + +Verify the secret is configured: + +```bash +kubectl get clustersecretstore default -o yaml +``` + +**For Production (using real secret backend):** + +Configure a ClusterSecretStore for your secret manager (AWS Secrets Manager, HashiCorp Vault, etc.) and store your token with key `git-token`. + +:::warning +Do not change the key name `git-token`. This key is referenced by the default ComponentWorkflows during the clone step. +::: + +### Step 4: Use Private Repository in Your Component + +Simply reference your private repository URL in the Component spec: + +```yaml +apiVersion: openchoreo.dev/v1alpha1 +kind: Component +metadata: + name: my-private-service + namespace: default +spec: + owner: + projectName: my-project + componentType: deployment/service + + workflow: + name: google-cloud-buildpacks + systemParameters: + repository: + url: "https://github.com/myorg/private-repo" # Your private repo + revision: + branch: "main" + appPath: "/" + parameters: {} +``` + +That's it! Trigger a build and the workflow will automatically handle authentication when cloning the repository. + +## How It Works + +Understanding the authentication flow helps with troubleshooting and customization. + +### Architecture Overview + +When building from a private repository: + +1. **ComponentWorkflow** defines an ExternalSecret resource that fetches your Git token from a secret backend +2. **ComponentWorkflowRun controller** creates the ExternalSecret in the Build Plane before executing the workflow +3. **Clone step** reads the token from the mounted secret, constructs an authenticated URL, and clones the repository + +This architecture separates secret management (control plane) from build execution (build plane) while maintaining security. + +### ExternalSecret Resource + +ComponentWorkflows define an ExternalSecret resource in the `resources` field: + +```yaml +resources: + - id: git-secret + template: + apiVersion: external-secrets.io/v1 + kind: ExternalSecret + metadata: + name: ${metadata.workflowRunName}-git-secret + namespace: openchoreo-ci-${metadata.orgName} + spec: + refreshInterval: 15s + secretStoreRef: + name: default + kind: ClusterSecretStore + target: + name: ${metadata.workflowRunName}-git-secret + creationPolicy: Owner + data: + - secretKey: git-token + remoteRef: + key: git-token +``` + +The ComponentWorkflowRun controller creates this ExternalSecret in the Build Plane before executing the workflow, and the clone step mounts it as a volume. + +## See Also + +- [CI Overview](./overview.md) - Understand ComponentWorkflows and build architecture +- [Custom Workflows](./custom-workflows.md) - Create custom ComponentWorkflows +- [External Secrets Operator](https://external-secrets.io/) - Secret management documentation diff --git a/versioned_docs/version-v0.11.x/user-guide/component-types/overview.md b/versioned_docs/version-v0.11.x/user-guide/component-types/overview.md new file mode 100644 index 0000000..a26b67d --- /dev/null +++ b/versioned_docs/version-v0.11.x/user-guide/component-types/overview.md @@ -0,0 +1,290 @@ +--- +title: Overview +description: Learn how to create ComponentTypes and Traits for OpenChoreo +--- + +# Authoring ComponentTypes and Traits + +This guide covers how to create custom [ComponentTypes](../../reference/api/platform/componenttype.md) and [Traits](../../reference/api/platform/trait.md) in OpenChoreo. + +## What is a ComponentType? + +OpenChoreo ships with default component types for common cases—backend services, web applications, scheduled tasks. In most organizations, these defaults are a starting point, not the finish line. + +A **ComponentType** provides platform operators with a declarative way to define the infrastructure created when a component is deployed. It builds on base workload types that map to Kubernetes (Deployment, StatefulSet, Job, CronJob), letting you customize what resources get created and how they're configured. + +Platform operators can: + +- Adjust defaults to match internal standards +- Add new component types for the organization's specific patterns +- Enforce best practices and security policies + +Developers keep working with a simple Component model without worrying about underlying Kubernetes details. + +**Key concepts:** +- `workloadType` - The primary workload kind: `deployment`, `statefulset`, `cronjob`, or `job` +- `schema` - Defines parameters developers can configure and environment-specific overrides +- `resources` - Templates that generate Kubernetes resources using CEL expressions + +### ComponentType Example + +```yaml +apiVersion: openchoreo.dev/v1alpha1 +kind: ComponentType +metadata: + name: web-service + namespace: default +spec: + # Primary workload type - must have a matching resource id + workloadType: deployment + + # Schema defines what developers can configure + schema: + # Parameters set by developers in Component spec + parameters: + port: "integer | default=8080" + replicas: "integer | default=1 minimum=1" + exposed: "boolean | default=false" + + # Environment-specific values set in ReleaseBinding + envOverrides: + resources: + cpu: "string | default=100m" + memory: "string | default=256Mi" + + # Resources to generate - templates use CEL expressions + resources: + # Primary workload - id must match workloadType + - id: deployment + template: + apiVersion: apps/v1 + kind: Deployment + metadata: + name: ${metadata.name} + namespace: ${metadata.namespace} + labels: ${metadata.labels} + 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} + resources: + requests: + cpu: ${envOverrides.resources.cpu} + memory: ${envOverrides.resources.memory} + + # Service for the deployment + - id: service + template: + apiVersion: v1 + kind: Service + metadata: + name: ${metadata.name} + namespace: ${metadata.namespace} + spec: + selector: ${metadata.podSelectors} + ports: + - port: ${parameters.port} + targetPort: ${parameters.port} + + # Optional HTTPRoute - only created when exposed=true + - id: httproute + includeWhen: ${parameters.exposed} + template: + apiVersion: gateway.networking.k8s.io/v1 + kind: HTTPRoute + metadata: + name: ${metadata.name} + namespace: ${metadata.namespace} + spec: + hostnames: + - ${metadata.name}.${dataplane.publicVirtualHost} + rules: + - backendRefs: + - name: ${metadata.name} + port: ${parameters.port} +``` + +## What is a Trait? + +A **Trait** augments a Component with operational behavior without modifying the ComponentType. Think of it as a composable overlay—you can mix and match Traits to add capabilities like storage, autoscaling, or network policies to any component. + +This lets platform operators define reusable operational patterns separately from the base component types, and lets developers attach only the capabilities they need. + +**Examples of what Traits can do:** + +- Add persistent storage (PVCs, volume mounts) +- Configure autoscaling rules +- Set network policies or ingress routing +- Inject sidecars for observability or service mesh + +**Key concepts:** +- `schema` - Defines trait-specific parameters and environment overrides +- `creates` - New Kubernetes resources to create (e.g., PVC, ConfigMap) +- `patches` - Modifications to existing ComponentType resources (e.g., add volume mounts) + +### Trait Example + +```yaml +apiVersion: openchoreo.dev/v1alpha1 +kind: Trait +metadata: + name: persistent-volume + namespace: default +spec: + # Schema for trait configuration + schema: + # Static parameters set in Component.spec.traits[].parameters + parameters: + volumeName: "string" + mountPath: "string" + containerName: "string | default=main" + + # Environment-specific values in ReleaseBinding.spec.traitOverrides + envOverrides: + size: "string | default=10Gi" + storageClass: "string | default=standard" + + # Create new resources + creates: + - template: + apiVersion: v1 + kind: PersistentVolumeClaim + metadata: + # Use trait.instanceName for unique naming + name: ${metadata.name}-${trait.instanceName} + namespace: ${metadata.namespace} + spec: + accessModes: ["ReadWriteOnce"] + storageClassName: ${envOverrides.storageClass} + resources: + requests: + storage: ${envOverrides.size} + + # Patch existing resources from ComponentType + patches: + - target: + kind: Deployment + group: apps + version: v1 + operations: + # Add volume to pod spec + - op: add + path: /spec/template/spec/volumes/- + value: + name: ${parameters.volumeName} + persistentVolumeClaim: + claimName: ${metadata.name}-${trait.instanceName} + + # Add volume mount to container + - op: add + path: /spec/template/spec/containers[?(@.name=='${parameters.containerName}')]/volumeMounts/- + value: + name: ${parameters.volumeName} + mountPath: ${parameters.mountPath} +``` + +## How Components Use ComponentTypes and Traits + +Developers create **Components** that reference a ComponentType and optionally attach Traits. The Component specifies parameter values defined in the ComponentType and Trait schemas: + +- `componentType` references the ComponentType (format: `workloadType/name`) +- `parameters` provides values for the ComponentType schema +- `traits[]` attaches Traits with their instance-specific parameters + +```yaml +apiVersion: openchoreo.dev/v1alpha1 +kind: Component +metadata: + name: my-api + namespace: default +spec: + # Reference ComponentType as workloadType/name + componentType: deployment/web-service + + # Set ComponentType parameters + parameters: + port: 3000 + replicas: 2 + exposed: true + + # Attach traits with instance-specific configuration + traits: + - name: persistent-volume + instanceName: data-storage # Unique name for this trait instance + parameters: + volumeName: data + mountPath: /var/data +``` + +To deploy a Component, you first create a **ComponentRelease** that captures the Component, its Workload, ComponentType, and Traits as an immutable snapshot. Then you create a **ReleaseBinding** to deploy that release to a specific environment. + +The ReleaseBinding is where environment-specific values are set—the `envOverrides` defined in ComponentType and Trait schemas. The same ComponentRelease can be deployed to multiple environments (dev → staging → prod), with each ReleaseBinding providing different override values: + +```yaml +apiVersion: openchoreo.dev/v1alpha1 +kind: ReleaseBinding +metadata: + name: my-api-production +spec: + # Required: identifies the component this binding belongs to + owner: + projectName: my-project + componentName: my-api + + # Required: target environment + environment: production + + # Optional: specific release to deploy (omit for auto-deploy) + releaseName: my-api-release-v1 + + # ComponentType environment overrides + componentTypeEnvOverrides: + resources: + cpu: "500m" + memory: "1Gi" + + # Trait environment overrides (keyed by instanceName) + traitOverrides: + data-storage: + size: "100Gi" + storageClass: "production-ssd" +``` + +## Syntax Systems + +ComponentTypes and Traits use three interconnected syntax systems: + +| Syntax | Purpose | Used In | +|--------|---------|---------| +| [Templating](./templating-syntax.md) | Dynamic value generation using CEL expressions | Resource templates | +| [Schema](./schema-syntax.md) | Parameter validation and defaults | `schema.parameters` and `schema.envOverrides` | +| [Patching](./patching-syntax.md) | Modifying existing resources | Trait `patches` section | + +## CEL Reference + +Templates use CEL expressions that have access to context variables and built-in functions: + +- **[Context Variables](../../reference/cel/context-variables.md)** - `metadata`, `parameters`, `workload`, `configurations`, etc. +- **[Built-in Functions](../../reference/cel/built-in-functions.md)** - `oc_omit()`, `oc_merge()`, `oc_generate_name()` +- **[Configuration Helpers](../../reference/cel/configuration-helpers.md)** - Helper functions for working with configs and secrets + +## Next Steps + +- **[Templating Syntax](./templating-syntax.md)** - Learn CEL expression syntax and resource control fields +- **[Schema Syntax](./schema-syntax.md)** - Define parameters with validation and defaults +- **[Patching Syntax](./patching-syntax.md)** - Modify resources in Traits using JSON Patch + +## Related Resources + +- [ComponentType API Reference](../../reference/api/platform/componenttype.md) - Full CRD specification +- [Trait API Reference](../../reference/api/platform/trait.md) - Full CRD specification +- [Component API Reference](../../reference/api/application/component.md) - Full CRD specification diff --git a/versioned_docs/version-v0.11.x/user-guide/component-types/patching-syntax.md b/versioned_docs/version-v0.11.x/user-guide/component-types/patching-syntax.md new file mode 100644 index 0000000..8441ac0 --- /dev/null +++ b/versioned_docs/version-v0.11.x/user-guide/component-types/patching-syntax.md @@ -0,0 +1,408 @@ +--- +title: Patching Syntax +description: JSON Patch operations for modifying resources in Traits +--- + +# Patching Syntax + +This guide explains how to use the patching system in OpenChoreo Traits to modify resources generated by ComponentTypes. + +## Overview + +Traits can modify existing resources using patches, which are JSON Patch operations enhanced with: +- Array filtering using JSONPath-like syntax +- CEL-based resource targeting +- forEach iteration support + +## Basic Patch Structure + +Patches are defined in the Trait's `spec.patches` section: + +```yaml +apiVersion: openchoreo.dev/v1alpha1 +kind: Trait +metadata: + name: monitoring-sidecar +spec: + patches: + - target: + kind: Deployment + group: apps + version: v1 + operations: + - op: add + path: /spec/template/spec/containers/- + value: + name: prometheus-exporter + image: prom/node-exporter:latest + ports: + - containerPort: 9100 +``` + +## Supported Operations + +### add + +Adds a value at the specified path: + +```yaml +# Add a new label +- op: add + path: /metadata/labels/monitoring + value: "enabled" + +# Append to array (using -) +- op: add + path: /spec/containers/- + value: + name: sidecar + image: sidecar:latest + +# Add nested structure +- op: add + path: /metadata/annotations/example.com~1version + value: "v2.0" +``` + +### replace + +Replaces an existing value. The path must exist: + +```yaml +# Replace a value +- op: replace + path: /spec/replicas + value: 3 + +# Replace array element +- op: replace + path: /spec/containers/0/image + value: nginx:latest +``` + +### remove + +Removes a value at the path: + +```yaml +# Remove a label +- op: remove + path: /metadata/labels/deprecated + +# Remove array element +- op: remove + path: /spec/containers/1 +``` + +## Array Filtering + +Use JSONPath-like syntax to target specific array elements by field value: + +### Basic Filtering + +```yaml +# Target container by name +- op: add + path: /spec/template/spec/containers[?(@.name=='app')]/env/- + value: + name: MONITORING + value: enabled + +# Target volume by name +- op: replace + path: /spec/template/spec/volumes[?(@.name=='data')]/emptyDir + value: + sizeLimit: 10Gi +``` + +### Nested Field Filters + +```yaml +# Filter by nested field path (dot notation) +- op: replace + path: /spec/containers[?(@.resources.limits.memory=='2Gi')]/image + value: app:high-mem-v2 + +# Filter by configMap name +- op: add + path: /spec/volumes[?(@.configMap.name=='app-config')]/configMap/defaultMode + value: 0644 +``` + +### Filter Limitations + +**Supported**: Simple equality filters of the form `@.field.path=='value'` + +```yaml +# Supported +- op: add + path: /spec/containers[?(@.name=='app')]/env/- + value: {name: VAR, value: val} +``` + +**Not supported**: Multiple conditions (`&&`, `||`), operators like `contains`, array indexing in filters, or existence checks. + +## CEL Expression Support + +CEL expressions (`${...}`) can be used in patch fields: + +### In path + +```yaml +# Dynamic path segments +- op: add + path: /data/${env.name} + value: ${env.value} + +# Dynamic filter conditions +- op: add + path: /spec/containers[?(@.name=='${parameters.containerName}')]/env/- + value: + name: VERSION + value: ${parameters.version} +``` + +### In value + +```yaml +- op: add + path: /metadata/labels/app + value: ${metadata.name} + +- op: add + path: /spec/template/spec/containers/- + value: + name: ${parameters.sidecarName} + image: ${parameters.sidecarImage} + ports: + - containerPort: ${parameters.sidecarPort} +``` + +## Resource Targeting + +### Basic Targeting + +The `target` spec requires `kind`, `group`, and `version`: + +```yaml +patches: + # Patch apps/v1 Deployment + - target: + kind: Deployment + group: apps + version: v1 + operations: + - op: add + path: /metadata/labels/patched + value: "true" + + # Patch core v1 Service (empty string for core API) + - target: + kind: Service + group: "" # Empty string for core API resources + version: v1 + operations: + - op: add + path: /metadata/annotations/patched + value: "true" +``` + +**Key points:** +- `kind`, `group`, and `version` are **required** +- For core API resources (Service, ConfigMap, Secret), use `group: ""` +- `targetPlane` is optional, defaults to `"dataplane"` + +### CEL-Based Filtering with where + +Use `where` clause to target resources conditionally: + +```yaml +patches: + - target: + kind: Deployment + group: apps + version: v1 + where: ${resource.spec.replicas > 1} # Only multi-replica deployments + operations: + - op: add + path: /metadata/annotations/ha-mode + value: "true" + + - target: + kind: Service + group: "" + version: v1 + where: ${resource.spec.type == 'LoadBalancer'} + operations: + - op: add + path: /metadata/annotations/external + value: "true" +``` + +## ForEach Iteration + +Apply patches iteratively over a list: + +```yaml +patches: + - target: + kind: ConfigMap + group: "" + version: v1 + forEach: ${parameters.environments} + var: env + operations: + - op: add + path: /data/${env.name} + value: ${env.value} + + - target: + kind: Deployment + group: apps + version: v1 + forEach: ${parameters.extraPorts} + var: port + operations: + - op: add + path: /spec/template/spec/containers[?(@.name=='app')]/ports/- + value: + containerPort: ${port.number} + name: ${port.name} +``` + +## Path Resolution Behavior + +| Path Type | Operation | Behavior | +|-----------|-----------|----------| +| Map key | add | Auto-creates parent maps if missing | +| Map key | replace | Error if target doesn't exist | +| Map key | remove | Idempotent - no error if key doesn't exist | +| Filter `[?(...)]` | add, replace, remove | Error if no match | +| Array index | add, replace, remove | Error if index out of bounds | + +**Auto-create and idempotent removal** - The `add` operation automatically creates missing parent objects, and `remove` on map keys succeeds silently if the key doesn't exist. This reduces boilerplate and matches Kubernetes Strategic Merge Patch behavior. + +**Array indices** - All array index operations error on out-of-bounds indices, as this likely indicates a mismatch between the patch and the resource. Use filters like `[?(@.name=='app')]` instead of positional indices for resilient patches. + +## Path Escaping + +Paths use JSON Pointer syntax with special character escaping: + +- `/` in a key → `~1` +- `~` in a key → `~0` + +This is commonly needed for Kubernetes annotations that contain `/`: + +```yaml +# Annotation: kubernetes.io/ingress-class +- op: add + path: /metadata/annotations/kubernetes.io~1ingress-class + value: nginx + +# Annotation: sidecar.istio.io/inject +- op: add + path: /spec/template/metadata/annotations/sidecar.istio.io~1inject + value: "true" + +# Key containing ~ +- op: add + path: /data/config~0backup + value: backup-data +``` + +## Common Patterns + +### Safe Label Addition + +```yaml +# Good - adds individual labels without affecting existing ones +- op: add + path: /metadata/labels/monitoring + value: enabled + +# Bad - replaces all existing labels +- op: replace + path: /metadata/labels + value: + monitoring: enabled +``` + +### Add Sidecar Container + +```yaml +patches: + - target: + kind: Deployment + group: apps + version: v1 + operations: + # Add sidecar container + - op: add + path: /spec/template/spec/containers/- + value: + name: fluentd + image: fluent/fluentd:v1.14 + volumeMounts: + - name: logs + mountPath: /var/log + + # Add shared volume + - op: add + path: /spec/template/spec/volumes/- + value: + name: logs + emptyDir: {} + + # Mount to main container + - op: add + path: /spec/template/spec/containers[?(@.name=='app')]/volumeMounts/- + value: + name: logs + mountPath: /app/logs +``` + +### Volume Mount Injection + +```yaml +- op: add + path: /spec/template/spec/volumes/- + value: + name: config + configMap: + name: ${metadata.name}-config + +- op: add + path: /spec/template/spec/containers[?(@.name=='app')]/volumeMounts/- + value: + name: config + mountPath: /etc/config + readOnly: true +``` + +### Environment Variables from Parameters + +```yaml +patches: + - target: + kind: Deployment + group: apps + version: v1 + forEach: ${parameters.envVars} + var: envVar + operations: + - op: add + path: /spec/template/spec/containers[?(@.name=='${parameters.containerName}')]/env/- + value: + name: ${envVar.name} + value: ${envVar.value} +``` + +:::tip +**Use filters for explicit targeting** - Prefer `[?(@.name=='app')]` over positional indices like `[0]`. Filters are more resilient to changes in resource structure. +::: + +## Related Resources + +- [Templating Syntax](./templating-syntax.md) - CEL expressions for dynamic values +- [Schema Syntax](./schema-syntax.md) - Parameter definitions for Traits +- [Trait API Reference](../../reference/api/platform/trait.md) - Full CRD specification diff --git a/versioned_docs/version-v0.11.x/user-guide/component-types/schema-syntax.md b/versioned_docs/version-v0.11.x/user-guide/component-types/schema-syntax.md new file mode 100644 index 0000000..eac877f --- /dev/null +++ b/versioned_docs/version-v0.11.x/user-guide/component-types/schema-syntax.md @@ -0,0 +1,348 @@ +--- +title: Schema Syntax +description: Parameter schema syntax for ComponentTypes and Traits +--- + +# Schema Syntax + +This guide explains how to define schemas for ComponentTypes and Traits using OpenChoreo's schema syntax. The syntax provides a concise, readable alternative to verbose JSON Schema. + +## Overview + +Schemas allow you to define parameter validation rules using simple string expressions: + +```yaml +fieldName: "type | constraint1=value1 constraint2=value2" +``` + +## Basic Types + +### Primitives + +```yaml +name: string # Required string +age: "integer | minimum=0 maximum=120" # Integer with constraints +price: "number | minimum=0.01" # Number (float) with minimum +enabled: "boolean | default=false" # Optional boolean with default +``` + +### Arrays + +```yaml +tags: "[]string" # Array of strings +ports: "[]integer" # Array of integers +mounts: "[]MountConfig" # Array of custom type +configs: "[]map" # Array of maps +``` + +### Maps + +```yaml +labels: "map" # Map with string values (keys always strings) +ports: "map" # Map with integer values +settings: "map" # Map with boolean values +``` + +### Objects + +For structured objects, use nested field definitions: + +```yaml +database: + host: "string" + port: "integer | default=5432" + username: "string" + password: "string" + options: + ssl: "boolean | default=true" + timeout: "integer | default=30" +``` + +## Custom Types + +Define reusable types in the `schema.types` section. Use custom types when a structure is reused in multiple places or for self-documenting type names. + +```yaml +apiVersion: openchoreo.dev/v1alpha1 +kind: ComponentType +metadata: + name: web-app +spec: + schema: + types: + MountConfig: + path: "string" + subPath: "string | default=''" + readOnly: "boolean | default=false" + + DatabaseConfig: + host: "string" + port: "integer | default=5432 minimum=1 maximum=65535" + database: "string" + + parameters: + volumes: "[]MountConfig" + database: DatabaseConfig + replicas: "integer | default=1 minimum=1" +``` + +## Defaults + +All fields are **required by default**. To make a field optional, provide a `default` value. + +### Primitives, Arrays, and Maps + +```yaml +# Required - must provide value +name: string +tags: "[]string" +labels: "map" + +# Optional - have explicit defaults +replicas: "integer | default=1" +tags: "[]string | default=[]" +labels: "map | default={}" +``` + +### Objects + +Objects are required unless they have a default. Two approaches: + +**Approach 1: Default when referencing a type** + +```yaml +schema: + types: + Monitoring: + enabled: "boolean | default=false" + port: "integer | default=9090" + + Database: + host: string + port: "integer | default=5432" + + parameters: + # Valid: All fields in Monitoring have defaults + monitoring: "Monitoring | default={}" + + # Valid: Default provides required host field + database: "Database | default={\"host\":\"localhost\"}" +``` + +**Approach 2: Default in the definition (`$default`)** + +```yaml +schema: + parameters: + # Inline object with empty default + monitoring: + $default: {} + enabled: "boolean | default=false" + port: "integer | default=9090" + + # Inline object with non-empty default + database: + $default: + host: "localhost" + host: string + port: "integer | default=5432" +``` + +### Default Precedence + +When an object is **not provided**, the object default is used, then field-level defaults apply to missing fields: + +```yaml +# Schema +database: + $default: + host: "localhost" + host: string + port: "integer | default=5432" + +# Input: parameters: {} +# Result: database = {host: "localhost", port: 5432} +``` + +When an object **is provided**, the object default is ignored and field-level defaults apply: + +```yaml +# Input: parameters: {database: {host: "production-db"}} +# Result: database = {host: "production-db", port: 5432} +``` + +### Using `$default` in Type Definitions + +Type-level `$default` makes all references to that type automatically optional: + +```yaml +types: + Resources: + $default: {} + cpu: "string | default=100m" + memory: "string | default=256Mi" + +parameters: + resources1: Resources # Optional + resources2: Resources # Optional +``` + +:::note Why explicit defaults are required +Objects are required unless you explicitly provide a default—even when all nested fields have defaults. This is intentional: + +- **Predictable**: You can tell if an object is optional by checking for a default, without inspecting nested fields +- **Safe evolution**: When you add a required field to an object, the existing `$default: {}` fails validation, alerting you to update it. Without explicit defaults, the object would silently become required, breaking existing Components. +- **Clear intent**: `$default: {}` signals that the entire configuration block is optional +::: + +## Constraint Markers + +Constraints are specified after the pipe (`|`) separator, space-separated. + +### Validation Constraints + +```yaml +# Strings +username: "string | minLength=3 maxLength=20 pattern=^[a-z][a-z0-9_]*$" +email: "string | format=email" + +# Numbers +age: "integer | minimum=0 maximum=150" +price: "number | minimum=0 exclusiveMinimum=true multipleOf=0.01" + +# Arrays +tags: "[]string | minItems=1 maxItems=10 uniqueItems=true" +``` + +### Enumerations + +```yaml +environment: "string | enum=development,staging,production" +logLevel: "string | enum=debug,info,warning,error default=info" +``` + +### Documentation + +```yaml +apiKey: "string | title='API Key' description='Authentication key for external service' example=sk-abc123" +timeout: "integer | description='Request timeout in seconds' default=30" +``` + +## Custom Annotations + +Add custom metadata using the `oc:` prefix. These are ignored during validation but can be used by UI generators and tooling: + +```yaml +commitHash: "string | oc:build:inject=git.sha oc:ui:hidden=true" +advancedTimeout: "string | default='30s' oc:scaffolding=omit" +``` + +## Escaping and Special Characters + +### Quoting Rules + +```yaml +# Single quotes: double to escape +description: "string | default='User''s timezone'" + +# Double quotes: backslash escape +pattern: "string | default=\"^[a-z]+\\\\d{3}$\"" + +# Pipes in values must be quoted +format: 'string | pattern="a|b|c"' + +# Enum values with spaces/commas - quote each value +size: 'string | enum="extra small","small","medium","large"' +format: 'string | enum="lastname, firstname","firstname lastname"' +``` + +**Summary:** +- Single quotes: `''` escapes `'` +- Double quotes: `\\` escapes `\`, `\"` escapes `"` +- Pipes (`|`) in values require quoting +- Enum values with spaces or commas need individual quotes + +## Schema Evolution + +OpenChoreo schemas allow additional properties beyond what's defined, enabling safe schema evolution: + +- **Development**: Add fields to Component before updating ComponentType schema +- **Promotion**: Add new `envOverrides` in target environment before promoting +- **Rollback**: Rolling back works - extra fields are simply ignored +- **Safety**: Unknown fields don't cause failures + +```yaml +# Environment prepared for promotion +envOverrides: + replicas: 2 + monitoring: "enabled" # Added before new Release arrives +``` + +## Complete Example + +```yaml +apiVersion: openchoreo.dev/v1alpha1 +kind: ComponentType +metadata: + name: web-service +spec: + workloadType: deployment + + schema: + types: + ResourceRequirements: + $default: {} + cpu: "string | default=100m" + memory: "string | default=256Mi" + + ProbeConfig: + $default: {} + path: "string | default=/healthz" + port: "integer | default=8080" + initialDelaySeconds: "integer | default=0" + periodSeconds: "integer | default=10" + + parameters: + # Required parameters + port: "integer | minimum=1 maximum=65535" + + # Optional parameters with defaults + replicas: "integer | default=1 minimum=1 maximum=100" + serviceType: "string | enum=ClusterIP,NodePort,LoadBalancer default=ClusterIP" + exposed: "boolean | default=false" + + # Nested optional objects + livenessProbe: ProbeConfig + readinessProbe: ProbeConfig + + envOverrides: + resources: ResourceRequirements + replicas: "integer | default=1" + + resources: + - id: deployment + template: + # ... uses ${parameters.port}, ${envOverrides.resources.cpu}, etc. +``` + +## JSON Schema Mapping + +OpenChoreo's schema syntax compiles to standard JSON Schema. For reference: + +| OpenChoreo | JSON Schema | +|------------|-------------| +| `string` | `{"type": "string"}` | +| `integer` | `{"type": "integer"}` | +| `number` | `{"type": "number"}` | +| `boolean` | `{"type": "boolean"}` | +| `[]string` | `{"type": "array", "items": {"type": "string"}}` | +| `map` | `{"type": "object", "additionalProperties": {"type": "string"}}` | +| `default=value` | `{"default": value}` | +| `minimum=N` | `{"minimum": N}` | +| `enum=a,b,c` | `{"enum": ["a", "b", "c"]}` | + +## Related Resources + +- [Templating Syntax](./templating-syntax.md) - Using parameters in templates +- [Patching Syntax](./patching-syntax.md) - JSON Patch operations for Traits +- [ComponentType API Reference](../../reference/api/platform/componenttype.md) - Full CRD specification diff --git a/versioned_docs/version-v0.11.x/user-guide/component-types/templating-syntax.md b/versioned_docs/version-v0.11.x/user-guide/component-types/templating-syntax.md new file mode 100644 index 0000000..856f2a4 --- /dev/null +++ b/versioned_docs/version-v0.11.x/user-guide/component-types/templating-syntax.md @@ -0,0 +1,383 @@ +--- +title: Templating Syntax +description: CEL expression syntax for dynamic resource generation in ComponentTypes and Traits +--- + +# Templating Syntax + +This guide covers the OpenChoreo templating system for dynamic resource generation in ComponentTypes and Traits. + +## Overview + +OpenChoreo's templating system enables dynamic configuration through expressions embedded in YAML/JSON structures. Expressions are enclosed in `${}` and evaluated using [CEL (Common Expression Language)](https://github.com/google/cel-spec). + +CEL expressions can be used in: + +- **Resource templates** (`template:` in ComponentType `resources[]` or Trait `creates[]`) - complete Kubernetes resources with embedded expressions +- **Patch values** (`value:` in Trait `patches[]`) - primitives, objects, or nested structures +- **Resource control fields** (`includeWhen`, `forEach`) - entire field value is a CEL expression + +```yaml +resources: + - id: deployment + includeWhen: ${parameters.enabled} # Resource control - entire CEL expression + forEach: ${parameters.instances} # Resource control - entire CEL expression + template: # Resource template + apiVersion: apps/v1 + kind: Deployment + metadata: + name: ${metadata.name} # Embedded expression + spec: + replicas: ${parameters.replicas} + +patches: + - target: + kind: Deployment + operations: + - op: add + path: /metadata/labels/app + value: ${metadata.name} # Patch value - primitive + - op: add + path: /spec/template/spec/volumes/- + value: # Patch value - object + name: ${parameters.volumeName} + emptyDir: {} +``` + +**Key components:** +- **Template Syntax**: Where expressions can be used and how to control resource generation +- **CEL Expression Language**: What you can write inside `${}` +- **[Built-in Functions](../../reference/cel/built-in-functions.md)**: OpenChoreo-provided functions like `oc_omit()`, `oc_merge()`, and `oc_generate_name()` +- **[Context Variables](../../reference/cel/context-variables.md)**: Variables providing access to metadata, parameters, workload, and configurations + +## Template Syntax + +This section covers where expressions can be used and how to control resource generation. + +### Expression Formats + +Expressions can appear in three formats within templates: + +#### Standalone Value + +When an expression is the entire value, it preserves the original data type. + +```yaml +# Returns an integer +replicas: ${parameters.replicas} + +# Returns a map +labels: ${metadata.labels} + +# Returns a boolean +enabled: ${has(parameters.feature) ? parameters.feature : false} + +# Returns a list +volumes: ${parameters.volumes} + +# Complex expression with block scalar (avoids quoting issues) +nodeSelector: | + ${parameters.highPerformance ? {"node-type": "compute"} : {"node-type": "standard"}} +``` + +#### String Interpolation + +When an expression is embedded within a string, it is converted to a string and interpolated. + +```yaml +# Multiple expressions in a string +message: "Application ${metadata.name} has ${parameters.replicas} replicas" + +# URL construction +url: "https://${metadata.name}.${metadata.namespace}.svc.cluster.local:${parameters.port}" + +# Image tag +image: "${parameters.registry}/${parameters.repository}:${parameters.tag}" +``` + +#### Dynamic Map Keys + +Map keys can be dynamically generated (must evaluate to strings). + +```yaml +# Dynamic labels based on component name +labels: + ${metadata.name}: active + ${metadata.name + "-metrics"}: enabled + +# Dynamic labels with parameters +labels: + ${'app.kubernetes.io/' + metadata.name}: active + ${parameters.labelPrefix + '/version'}: ${parameters.version} +``` + +### Resource Control Fields + +These fields control resource generation in ComponentTypes and Traits. They use CEL expressions to determine which resources to generate. + +#### includeWhen + +Controls whether a resource is included based on a CEL expression: + +```yaml +resources: + # Only create HPA if auto-scaling is enabled + - id: hpa + includeWhen: ${parameters.autoscaling.enabled} + template: + apiVersion: autoscaling/v2 + kind: HorizontalPodAutoscaler + # ... + + # Create PDB only for production with multiple replicas + - id: pdb + includeWhen: ${parameters.environment == "production" && parameters.replicas > 1} + template: + apiVersion: policy/v1 + kind: PodDisruptionBudget + # ... +``` + +#### forEach + +Generates multiple resources from a list or map: + +```yaml +resources: + # Generate ConfigMaps for each database + - id: db-config + forEach: ${parameters.databases} + var: db + template: + apiVersion: v1 + kind: ConfigMap + metadata: + name: ${oc_generate_name(metadata.name, db.name, "config")} + data: + host: ${db.host} + port: ${string(db.port)} +``` + +**Iterating over maps** - Each item has `.key` and `.value` fields: + +```yaml +resources: + - id: config + forEach: ${parameters.configFiles} + var: config + template: + apiVersion: v1 + kind: ConfigMap + metadata: + name: ${oc_generate_name(metadata.name, config.key)} + data: + "${config.key}": ${config.value} +``` + +Map keys are iterated in **alphabetical order** for deterministic output. + +#### Filtering Items in forEach + +Use `.filter()` within the forEach expression: + +```yaml +resources: + # Generate secrets only for enabled integrations + - id: secrets + forEach: ${parameters.integrations.filter(i, i.enabled && has(i.credentials))} + var: integration + template: + apiVersion: v1 + kind: Secret + metadata: + name: ${oc_generate_name(metadata.name, integration.name, "secret")} + stringData: + api_key: ${integration.credentials.apiKey} +``` + +#### Combining forEach with includeWhen + +`includeWhen` is evaluated **before** the forEach loop and controls the **entire block**. The loop variable is **not available** in `includeWhen`: + +```yaml +resources: + # CORRECT - includeWhen controls entire forEach block + - includeWhen: ${parameters.createSecrets} + forEach: ${parameters.integrations} + var: integration + template: + # ... + + # WRONG - loop variable not available in includeWhen + - includeWhen: ${integration.enabled} # ERROR: 'integration' doesn't exist yet + forEach: ${parameters.integrations} + var: integration + + # CORRECT - use filter() for item-level filtering + - forEach: ${parameters.integrations.filter(i, i.enabled)} + var: integration + template: + # ... +``` + +## CEL Expression Language + +This section documents what you can write inside `${}` expressions. These are standard CEL and cel-go extension capabilities, documented here for convenience. + +### Map Access + +Both dot notation and bracket notation work for accessing map fields: + +```yaml +# Equivalent for static keys: +${workload.containers.app.image} +${workload.containers["app"].image} +``` + +**Bracket notation is required for:** +- Dynamic keys: `${configurations[parameters.containerName].configs.envs}` +- Keys with special characters: `${resource.metadata.labels["app.kubernetes.io/name"]}` +- Optional dynamic keys: `${configurations[?containerName].?configs.orValue({})}` + +### Conditional Logic + +```yaml +# Ternary operator with default +serviceType: ${has(parameters.serviceType) ? parameters.serviceType : "ClusterIP"} + +# Minimum value check +replicas: ${parameters.replicas > 0 ? parameters.replicas : 1} + +# Multi-condition logic +nodeSelector: | + ${parameters.highPerformance ? + {"node-type": "compute-optimized"} : + (parameters.costOptimized ? + {"node-type": "spot"} : + {"node-type": "general-purpose"})} +``` + +### Safe Navigation + +```yaml +# Optional chaining with ? for static keys +customValue: ${parameters.?custom.?value.orValue("default")} + +# Optional index access with dynamic keys +containerConfig: ${configurations[?containerName].?configs.?envs.orValue([])} + +# Map with optional keys +config: | + ${{"required": parameters.requiredConfig, ?"optional": parameters.?optionalConfig}} +``` + +### Array and List Operations + +```yaml +# Transform list items +env: | + ${parameters.envVars.map(e, {"name": e.key, "value": e.value})} + +# Filter and transform +ports: | + ${parameters.services.filter(s, s.enabled).map(s, {"port": s.port, "name": s.name})} + +# List operations +firstItem: ${parameters.items[0]} +lastItem: ${parameters.items[size(parameters.items) - 1]} +joined: ${parameters.items.join(",")} + +# Sorting +sortedStrings: ${parameters.names.sort()} +sortedByName: ${parameters.items.sortBy(item, item.name)} + +# List concatenation +combined: ${parameters.list1 + parameters.list2} +withInlineItem: ${parameters.userPorts + [{"port": 8080, "name": "http"}]} + +# Flatten nested lists +flattened: ${[[1, 2], [3, 4]].flatten()} # returns [1, 2, 3, 4] +``` + +### Map Operations + +```yaml +# Transform map to list +containerList: | + ${workload.containers.transformList(name, container, { + "name": name, + "image": container.image + })} + +# Transform list to map with dynamic keys +envMap: | + ${parameters.envVars.transformMapEntry(i, v, {v.name: v.value})} + +# Map transformation (map to map) +labelMap: | + ${parameters.labels.transformMap(k, v, {"app/" + k: v})} +``` + +### String Operations + +```yaml +uppercaseName: ${metadata.name.upperAscii()} +trimmedValue: ${parameters.value.trim()} +replaced: ${parameters.text.replace("old", "new")} +prefixed: ${parameters.value.startsWith("prefix")} + +# Split string into list +parts: ${parameters.path.split("/")} +limited: ${parameters.text.split(",", 2)} # "a,b,c" → ["a", "b,c"] + +# Extract substring +suffix: ${parameters.name.substring(4)} # "hello-world" → "o-world" +middle: ${parameters.name.substring(0, 5)} # "hello-world" → "hello" +``` + +### Math Operations + +```yaml +maxValue: ${math.greatest([parameters.min, parameters.max, parameters.default])} +minValue: ${math.least([parameters.v1, parameters.v2, parameters.v3])} +rounded: ${math.ceil(parameters.floatValue)} +``` + +### Encoding Operations + +```yaml +# Base64 encode (convert to bytes first) +encoded: ${base64.encode(bytes(parameters.value))} + +# Base64 decode to string +decoded: ${string(base64.decode(parameters.encodedValue))} +``` + +### Built-in Functions + +OpenChoreo provides built-in CEL functions for common operations: + +- `oc_omit()` - Remove fields conditionally from output +- `oc_merge()` - Shallow merge maps +- `oc_generate_name()` - Generate Kubernetes-safe names with hash suffix +- `oc_hash()` - Generate hash from string + +See the [Built-in Functions Reference](../../reference/cel/built-in-functions.md) for complete documentation and examples. + +### Context Variables + +Templates have access to context variables that provide component metadata, parameters, workload specifications, and platform configuration. + +**ComponentType variables:** `metadata`, `parameters`, `envOverrides`, `workload`, `configurations`, `dataplane` + +**Trait variables:** All ComponentType variables plus `trait.name` and `trait.instanceName` + +See the [Context Variables Reference](../../reference/cel/context-variables.md) for complete documentation of all available fields. + +## Related Resources + +- [Schema Syntax](./schema-syntax.md) - Parameter validation and defaults +- [Patching Syntax](./patching-syntax.md) - JSON Patch operations for Traits +- [Context Variables](../../reference/cel/context-variables.md) - Variables available in templates +- [Built-in Functions](../../reference/cel/built-in-functions.md) - OpenChoreo CEL functions +- [Configuration Helpers](../../reference/cel/configuration-helpers.md) - Helper functions for configurations diff --git a/versioned_sidebars/version-v0.11.x-sidebars.json b/versioned_sidebars/version-v0.11.x-sidebars.json new file mode 100644 index 0000000..504b6df --- /dev/null +++ b/versioned_sidebars/version-v0.11.x-sidebars.json @@ -0,0 +1,346 @@ +{ + "docsSidebar": [ + { + "type": "category", + "label": "Overview", + "collapsed": false, + "items": [ + "overview/what-is-openchoreo", + "overview/architecture" + ] + }, + { + "type": "category", + "label": "Get Started", + "collapsed": false, + "items": [ + "getting-started/quick-start-guide", + { + "type": "category", + "label": "Try It Out", + "collapsed": false, + "items": [ + "getting-started/try-it-out/on-self-hosted-kubernetes", + "getting-started/try-it-out/on-managed-kubernetes" + ] + }, + "getting-started/deploy-first-component", + "learn-from-examples/examples-catalog" + ] + }, + { + "type": "category", + "label": "Operator Manual", + "items": [ + "operations/deployment-topology", + "operations/multi-cluster-connectivity", + "operations/identity-configuration", + "operations/backstage-configuration", + "operations/api-management", + "operations/auto-build", + "operations/secret-management", + "operations/cluster-agent-rbac", + "operations/observability-alerting", + "operations/rca-agent", + "operations/upgrades", + { + "type": "category", + "label": "GitOps", + "items": [ + "operations/gitops/overview", + { + "type": "category", + "label": "FluxCD", + "items": [ + "operations/gitops/fluxcd/getting-started" + ] + } + ] + } + ] + }, + { + "type": "category", + "label": "Use Cases", + "items": [ + "use-cases/deploy-prebuilt-image", + "use-cases/api-management" + ] + }, + { + "type": "category", + "label": "Concepts", + "link": { + "type": "generated-index", + "title": "Concepts", + "description": "Understand the fundamental abstractions and relationships in OpenChoreo" + }, + "items": [ + "concepts/developer-abstractions", + "concepts/platform-abstractions", + "concepts/runtime-model", + "concepts/resource-relationships" + ] + }, + { + "type": "category", + "label": "User Guide", + "items": [ + { + "type": "category", + "label": "CI", + "items": [ + "user-guide/ci/overview", + "user-guide/ci/component-workflow-schema", + "user-guide/ci/custom-workflows", + "user-guide/ci/additional-resources", + "user-guide/ci/private-repository", + "user-guide/ci/private-repository-multiple" + ] + }, + { + "type": "category", + "label": "Component Types", + "items": [ + "user-guide/component-types/overview", + "user-guide/component-types/templating-syntax", + "user-guide/component-types/schema-syntax", + "user-guide/component-types/patching-syntax" + ] + } + ] + }, + { + "type": "category", + "label": "Reference", + "items": [ + { + "type": "category", + "label": "Helm Charts", + "items": [ + "reference/helm/control-plane", + "reference/helm/data-plane", + "reference/helm/build-plane", + "reference/helm/observability-plane" + ] + }, + { + "type": "category", + "label": "API Reference", + "items": [ + { + "type": "category", + "label": "Application Resources", + "items": [ + { + "type": "doc", + "id": "reference/api/application/project", + "label": "Project" + }, + { + "type": "doc", + "id": "reference/api/application/component", + "label": "Component" + }, + { + "type": "doc", + "id": "reference/api/application/componentworkflowrun", + "label": "ComponentWorkflowRun" + }, + { + "type": "doc", + "id": "reference/api/application/workload", + "label": "Workload" + }, + { + "type": "doc", + "id": "reference/api/application/componentdeployment", + "label": "ComponentDeployment (Deprecated)" + }, + { + "type": "doc", + "id": "reference/api/application/build", + "label": "Build (Deprecated)" + }, + { + "type": "doc", + "id": "reference/api/application/service", + "label": "Service (Deprecated)" + }, + { + "type": "doc", + "id": "reference/api/application/webapplication", + "label": "WebApplication (Deprecated)" + }, + { + "type": "doc", + "id": "reference/api/application/scheduledtask", + "label": "ScheduledTask (Deprecated)" + } + ] + }, + { + "type": "category", + "label": "Platform Resources", + "items": [ + { + "type": "doc", + "id": "reference/api/platform/organization", + "label": "Organization" + }, + { + "type": "doc", + "id": "reference/api/platform/dataplane", + "label": "DataPlane" + }, + { + "type": "doc", + "id": "reference/api/platform/environment", + "label": "Environment" + }, + { + "type": "doc", + "id": "reference/api/platform/buildplane", + "label": "BuildPlane" + }, + { + "type": "doc", + "id": "reference/api/platform/componentworkflow", + "label": "ComponentWorkflow" + }, + { + "type": "doc", + "id": "reference/api/platform/observabilityplane", + "label": "ObservabilityPlane" + }, + { + "type": "doc", + "id": "reference/api/platform/observabilityalertrule", + "label": "ObservabilityAlertRule" + }, + { + "type": "doc", + "id": "reference/api/platform/observabilityalertsnotificationchannel", + "label": "ObservabilityAlertsNotificationChannel" + }, + { + "type": "doc", + "id": "reference/api/platform/deployment-pipeline", + "label": "DeploymentPipeline" + }, + { + "type": "doc", + "id": "reference/api/platform/releasebinding", + "label": "ReleaseBinding" + }, + { + "type": "doc", + "id": "reference/api/platform/componenttype", + "label": "ComponentType" + }, + { + "type": "doc", + "id": "reference/api/platform/trait", + "label": "Trait" + }, + { + "type": "doc", + "id": "reference/api/platform/secretreference", + "label": "SecretReference" + }, + { + "type": "doc", + "id": "reference/api/platform/serviceclass", + "label": "ServiceClass (Deprecated)" + }, + { + "type": "doc", + "id": "reference/api/platform/webapplicationclass", + "label": "WebApplicationClass (Deprecated)" + }, + { + "type": "doc", + "id": "reference/api/platform/scheduledtaskclass", + "label": "ScheduledTaskClass (Deprecated)" + } + ] + }, + { + "type": "category", + "label": "Runtime Resources", + "items": [ + { + "type": "doc", + "id": "reference/api/runtime/componentrelease", + "label": "ComponentRelease" + }, + { + "type": "doc", + "id": "reference/api/runtime/release", + "label": "Release" + }, + { + "type": "doc", + "id": "reference/api/runtime/servicebinding", + "label": "ServiceBinding (Deprecated)" + }, + { + "type": "doc", + "id": "reference/api/runtime/webapplicationbinding", + "label": "WebApplicationBinding (Deprecated)" + }, + { + "type": "doc", + "id": "reference/api/runtime/scheduledtaskbinding", + "label": "ScheduledTaskBinding (Deprecated)" + } + ] + } + ] + }, + { + "type": "category", + "label": "CEL Reference", + "items": [ + { + "type": "doc", + "id": "reference/cel/context-variables", + "label": "Context Variables" + }, + { + "type": "doc", + "id": "reference/cel/built-in-functions", + "label": "Built-in Functions" + }, + { + "type": "doc", + "id": "reference/cel/configuration-helpers", + "label": "Configuration Helpers" + } + ] + }, + { + "type": "category", + "label": "MCP Servers", + "items": [ + { + "type": "doc", + "id": "reference/mcp-servers/mcp-configuration", + "label": "MCP Configuration" + } + ] + }, + { + "type": "doc", + "id": "reference/cli-reference", + "label": "CLI Reference" + } + ] + }, + { + "type": "doc", + "id": "reference/faq", + "label": "FAQ" + } + ] +} diff --git a/versions.json b/versions.json index 3eb8bf8..65df3ba 100644 --- a/versions.json +++ b/versions.json @@ -1,4 +1,5 @@ [ + "v0.11.x", "v0.10.x", "v0.9.x", "v0.8.x",