From ac5c29c2cac343a47aa03f89f46b4bc0bd07fcc2 Mon Sep 17 00:00:00 2001 From: Chalindu Kodikara Date: Sat, 15 Nov 2025 12:03:12 +0530 Subject: [PATCH 1/2] Update abstractions with new design --- docs/concepts/developer-abstractions.md | 101 +++++++++++-------- docs/concepts/platform-abstractions.md | 128 ++++++++++++++++++------ 2 files changed, 156 insertions(+), 73 deletions(-) diff --git a/docs/concepts/developer-abstractions.md b/docs/concepts/developer-abstractions.md index 7e0c6f8..b23a5a4 100644 --- a/docs/concepts/developer-abstractions.md +++ b/docs/concepts/developer-abstractions.md @@ -32,37 +32,44 @@ A **Component** represents a deployable unit of software - the fundamental build Each component encapsulates a specific piece of functionality, whether it's a microservice handling business logic, a web application serving user interfaces, or a background job processing data. -Components provide the connection between source code and running applications. They define how code is built, what -resources it requires, and how it should be deployed. This abstraction allows developers to focus on application logic -while the platform handles the complexities of containerization, orchestration, and lifecycle management. - -## Component Types - -OpenChoreo provides specialized component types that represent common application patterns, each with its own -operational characteristics and platform integrations. - -### Service - -A **Service** component represents backend applications that expose APIs or handle business logic. Services are the -workhorses of cloud-native applications, processing requests, managing data, and integrating with other systems. The -platform understands that services need stable network identities, load balancing, and API management capabilities. - -Services can expose multiple protocols including HTTP, gRPC, and TCP, with the platform handling the appropriate -routing and load balancing for each protocol type. - -### WebApplication - -A **WebApplication** component represents frontend applications that serve user interfaces. These might be single-page -applications, server-side rendered websites, or static content. The platform recognizes that web applications have -different operational requirements than backend services and provides appropriate deployment patterns through the -WebApplicationClass. - -### ScheduledTask - -A **ScheduledTask** component represents batch jobs, cron jobs, and other time-based workloads. Unlike continuously -running services, scheduled tasks execute at specific times or intervals, complete their work, and terminate. -ScheduledTasks are configured with cron expressions to define when they should run, and the platform handles the -scheduling through the ScheduledTaskClass and Kubernetes CronJob resources. +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. These values include both static parameters that remain consistent across environments and +environment-overridable parameters that can be customized per environment through ComponentDeployment resources. The +inline schema syntax from the ComponentType validates these values automatically, ensuring developers provide correct +types and stay within defined constraints. + +**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 and environment overrides that can be customized through +ComponentDeployment 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 @@ -88,16 +95,28 @@ enables platform teams to control infrastructure policies while developers focus limits, scaling parameters, and operational policies come from the ServiceClass or WebApplicationClass, while the workload simply declares what the application needs to function. -## Build +## WorkflowRun + +A **WorkflowRun** represents a runtime execution instance of a Workflow. 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. Developers create WorkflowRun resources to +trigger workflows, providing only the schema values defined in the Workflow template. The platform handles all the +complexity of rendering the final workflow specification, synchronizing secrets, and managing execution in the build +plane. -A **Build** represents the process of transforming source code into deployable artifacts. It captures the build -configuration, tracks build execution, and manages the resulting container images. The build abstraction provides a -consistent interface for different build strategies while handling the complexities of secure, reproducible builds. +Each WorkflowRun captures two essential pieces of information: -Builds in OpenChoreo are first-class resources that can be monitored, audited, and managed independently of deployments. -This separation enables practices like building once and deploying many times, pre-building images for faster -deployments, and maintaining clear traceability from source code to running containers. +**Workflow Configuration** references the Workflow template to use and provides the developer-configured schema values. +These values conform to the schema defined in the referenced Workflow, with automatic validation ensuring type +correctness and constraint satisfaction. For example, a Docker build workflow might receive repository URL, branch +name, and Dockerfile path, while a buildpack workflow might receive additional configuration for build resources, +caching, and testing modes. -The platform supports multiple build strategies to accommodate different technology stacks and organizational -preferences. Whether using Cloud Native Buildpacks for automatic, opinionated builds or custom Dockerfiles for complete -control, the build abstraction provides a consistent operational model. +This abstraction provides a simplified interface where developers interact with curated schemas rather than complex +CI/CD pipeline definitions, while creating permanent audit trails essential for compliance and debugging. The separation +of concerns allows platform engineers to control workflow implementation and security policies through Workflow templates +while developers manage application-specific parameters through WorkflowRun schema values. For component-bound workflows, +automatic linkage between builds and components enables coordinated build and deployment lifecycles. WorkflowRuns 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. diff --git a/docs/concepts/platform-abstractions.md b/docs/concepts/platform-abstractions.md index 91a658c..2f4cf8f 100644 --- a/docs/concepts/platform-abstractions.md +++ b/docs/concepts/platform-abstractions.md @@ -108,35 +108,99 @@ configured for sensitive environments, automated testing can be triggered at pro can be enforced before production deployment. This ensures that all applications follow organizational standards regardless of which team develops them. -## Class System - -OpenChoreo implements the standard Kubernetes Class pattern, similar to GatewayClass or StorageClass, enabling platform -engineers to define platform-level abstractions that developers consume through their applications. - -### The Class Pattern - -Classes are platform-level resources that encode organizational standards, best practices, and governance policies. -Platform engineers create Classes for different workload types - ServiceClass for backend services, WebApplicationClass -for frontend applications, and ScheduledTaskClass for batch jobs. Each Class defines the platform standards that -applications must follow when claiming these resources. - -Just as GatewayClass defines infrastructure capabilities that Gateway resources consume, or StorageClass defines how -storage should be provisioned when a PersistentVolumeClaim is created, ServiceClass defines how services should be -deployed when developers create Service resources. This pattern provides a clean separation between platform -capabilities (defined by platform engineers) and application requirements (expressed by developers). - -### Class Consumption - -When developers create application resources like Service or WebApplication, they reference the appropriate Class, -similar to how a PersistentVolumeClaim references a StorageClass. The platform uses the Class definition to provision -the actual workload with the correct configuration, policies, and governance rules. - -Environment-specific Bindings act as the instantiation of this claim in a specific environment. While the Service -resource expresses the developer's intent and references a ServiceClass, the ServiceBinding represents the actual -deployment of that service in a particular environment with environment-specific overrides. - -This consumption model balances standardization with flexibility. Platform teams maintain control over critical -configurations through Classes while developers express their requirements through simple resource definitions. The -platform handles the complex mapping between developer intent and infrastructure reality. - - +## 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 static configurations that remain consistent across all environments. These include settings like +replica counts, image pull policies, and container ports. Once set at component creation, these values apply uniformly +whether the component runs in development, staging, or production. + +**EnvOverrides** are configurations that platform engineers can override on a per-environment basis through +ComponentDeployment 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. + +## Workflows + +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, enabling developers to trigger complex CI/CD processes through simple, validated inputs. + +Workflows in OpenChoreo integrate with Argo Workflows to provide Kubernetes-native execution for continuous +integration tasks. Unlike traditional CI/CD systems where developers must understand pipeline implementation details, +OpenChoreo Workflows present a curated schema of configurable options while platform engineers control the underlying +execution logic, security policies, and infrastructure configurations. + +Each Workflow defines a **schema** that specifies what developers can configure when creating a run instance. +This schema uses the same inline type definition syntax as ComponentTypes, making validation rules explicit and +self-documenting. The schema typically includes repository configuration, build parameters, resource limits, and +testing options, with type validation, default values, and constraints enforced automatically. + +The Workflow's **resource template** contains the actual Argo Workflow specification with CEL expressions for dynamic +value injection. These expressions access three categories of variables: + +**Context variables** (`${ctx.*}`) provide runtime information like the workflow run name, component name, project name, and +organization name. These enable unique resource naming and proper isolation across +executions. + +**Schema variables** (`${schema.*}`) inject developer-provided values from the WorkflowRun instance. These include +repository URLs, build configurations, and other parameters defined in the workflow schema. + +**Platform-controlled parameters** are hardcoded directly in the workflow and remain invisible to developers. These may +include container image references, registry URLs, security scanning configurations, and organizational policies. By +hardcoding these values, platform engineers ensure compliance with security standards and infrastructure policies +regardless of developer input. + +Workflows can be referenced by Components through the `workflow` field, enabling automated builds triggered by code +changes or manual developer actions. ComponentTypes can restrict which Workflows are allowed through the +`allowedWorkflows` field, ensuring that different component types use appropriate build strategies and security +policies. + +The Workflow abstraction thus provides a controlled interface to powerful CI/CD capabilities, enabling platform teams +to offer self-service build automation while maintaining governance over build processes, security scanning, artifact +storage, and compliance requirements. From b958c7e35bbf7c2558d479a8b7a5209872085460 Mon Sep 17 00:00:00 2001 From: Chalindu Kodikara Date: Sat, 15 Nov 2025 12:03:25 +0530 Subject: [PATCH 2/2] Update references for new design --- docs/reference/api/application/build.md | 159 ---- docs/reference/api/application/component.md | 276 ++++-- docs/reference/api/application/project.md | 1 - .../api/application/scheduledtask.md | 93 -- docs/reference/api/application/service.md | 147 ---- .../api/application/webapplication.md | 93 -- docs/reference/api/application/workflowrun.md | 225 +++++ docs/reference/api/application/workload.md | 4 - docs/reference/api/platform/buildplane.md | 1 - docs/reference/api/platform/componenttype.md | 261 ++++++ docs/reference/api/platform/dataplane.md | 1 - .../api/platform/deployment-pipeline.md | 1 - docs/reference/api/platform/environment.md | 1 - docs/reference/api/platform/organization.md | 79 -- .../api/platform/scheduledtaskclass.md | 84 -- docs/reference/api/platform/serviceclass.md | 85 -- .../api/platform/webapplicationclass.md | 87 -- docs/reference/api/platform/workflow.md | 254 ++++++ .../api/runtime/componentdeployment.md | 280 ++++++ docs/reference/api/runtime/release.md | 153 +++- .../api/runtime/scheduledtaskbinding.md | 108 --- docs/reference/api/runtime/servicebinding.md | 196 ----- .../api/runtime/webapplicationbinding.md | 188 ---- docs/reference/configuration-schema.md | 819 ++++++------------ 24 files changed, 1633 insertions(+), 1963 deletions(-) delete mode 100644 docs/reference/api/application/build.md delete mode 100644 docs/reference/api/application/scheduledtask.md delete mode 100644 docs/reference/api/application/service.md delete mode 100644 docs/reference/api/application/webapplication.md create mode 100644 docs/reference/api/application/workflowrun.md create mode 100644 docs/reference/api/platform/componenttype.md delete mode 100644 docs/reference/api/platform/organization.md delete mode 100644 docs/reference/api/platform/scheduledtaskclass.md delete mode 100644 docs/reference/api/platform/serviceclass.md delete mode 100644 docs/reference/api/platform/webapplicationclass.md create mode 100644 docs/reference/api/platform/workflow.md create mode 100644 docs/reference/api/runtime/componentdeployment.md delete mode 100644 docs/reference/api/runtime/scheduledtaskbinding.md delete mode 100644 docs/reference/api/runtime/servicebinding.md delete mode 100644 docs/reference/api/runtime/webapplicationbinding.md diff --git a/docs/reference/api/application/build.md b/docs/reference/api/application/build.md deleted file mode 100644 index 9b3cbc3..0000000 --- a/docs/reference/api/application/build.md +++ /dev/null @@ -1,159 +0,0 @@ ---- -title: Build API Reference ---- - -# Build - -A Build represents a build job in OpenChoreo that transforms source code into a container image. It defines the -source repository, revision, and build template to use for creating workloads. Upon successful -completion, a Build creates a Workload resource containing the built container image. - -## API Version - -`openchoreo.dev/v1alpha1` - -## Resource Definition - -### Metadata - -Builds are namespace-scoped resources that must be created within an Organization's namespace and belong to a -Component through the owner field. - -```yaml -apiVersion: openchoreo.dev/v1alpha1 -kind: Build -metadata: - name: - namespace: # Organization namespace -``` - -### Spec Fields - -| Field | Type | Required | Default | Description | -|---------------|-----------------------------|----------|---------|--------------------------------------------------------------------| -| `owner` | [BuildOwner](#buildowner) | Yes | - | Ownership information linking the build to a project and component | -| `repository` | [Repository](#repository) | Yes | - | Source repository configuration | -| `templateRef` | [TemplateRef](#templateref) | Yes | - | Build template reference and parameters | - -### BuildOwner - -| Field | Type | Required | Default | Description | -|-----------------|--------|----------|---------|-----------------------------------------------------| -| `projectName` | string | Yes | - | Name of the project that owns this build (min: 1) | -| `componentName` | string | Yes | - | Name of the component that owns this build (min: 1) | - -### Repository - -| Field | Type | Required | Default | Description | -|------------|-----------------------|----------|---------|--------------------------------------------------------------------| -| `url` | string | Yes | - | Repository URL (e.g., https://github.com/org/repo) | -| `revision` | [Revision](#revision) | Yes | - | Revision specification for the build | -| `appPath` | string | Yes | - | Path to the application within the repository (e.g., "." for root) | - -### Revision - -| Field | Type | Required | Default | Description | -|----------|--------|----------|---------|-------------------------------------------------------------------| -| `branch` | string | No | "" | Branch to build from | -| `commit` | string | No | "" | Specific commit hash to build from (takes precedence over branch) | - -### TemplateRef - -| Field | Type | Required | Default | Description | -|--------------|---------------------------|----------|---------|------------------------------------------------------| -| `engine` | string | No | "" | Build engine to use | -| `name` | string | Yes | - | Name of the build template (ClusterWorkflowTemplate) | -| `parameters` | [[Parameter](#parameter)] | No | [] | Template parameters | - -### Parameter - -| Field | Type | Required | Default | Description | -|---------|--------|----------|---------|-----------------| -| `name` | string | Yes | - | Parameter name | -| `value` | string | Yes | - | Parameter value | - -### Status Fields - -| Field | Type | Default | Description | -|---------------|-----------------|---------|---------------------------------------------------------| -| `conditions` | []Condition | [] | Standard Kubernetes conditions tracking the build state | -| `imageStatus` | [Image](#image) | {} | Information about the built image | - -### Image - -| Field | Type | Default | Description | -|---------|--------|---------|-----------------------------------------------------------| -| `image` | string | "" | Full image reference including registry, name, and digest | - -#### Condition Types - -Common condition types for Build resources: - -- `Ready` - Indicates if the build has completed successfully -- `Building` - Indicates if the build is currently in progress -- `Failed` - Indicates if the build has failed - -## Examples - -### Build with Docker Template - -```yaml -apiVersion: openchoreo.dev/v1alpha1 -kind: Build -metadata: - name: customer-service-build-abc123 - namespace: default -spec: - owner: - projectName: my-project - componentName: customer-service - repository: - url: https://github.com/myorg/customer-service - revision: - branch: main - commit: abc123def456 - appPath: . - templateRef: - name: docker - parameters: - - name: docker-context - value: . - - name: dockerfile-path - value: ./Dockerfile -``` - -### Build with Buildpacks - -```yaml -apiVersion: openchoreo.dev/v1alpha1 -kind: Build -metadata: - name: frontend-build-xyz789 - namespace: default -spec: - owner: - projectName: my-project - componentName: frontend-app - repository: - url: https://github.com/myorg/frontend - revision: - branch: develop - appPath: ./webapp - templateRef: - name: google-cloud-buildpacks -``` - -## Annotations - -Builds support the following annotations: - -| Annotation | Description | -|-------------------------------|------------------------------------| -| `openchoreo.dev/display-name` | Human-readable name for UI display | -| `openchoreo.dev/description` | Detailed description of the build | - -## Related Resources - -- [Component](./component.md) - Components that trigger builds -- [Workload](./workload.md) - Workloads created by successful builds -- [BuildPlane](../platform/buildplane.md) - Infrastructure where builds execute diff --git a/docs/reference/api/application/component.md b/docs/reference/api/application/component.md index 585aea4..0de703c 100644 --- a/docs/reference/api/application/component.md +++ b/docs/reference/api/application/component.md @@ -4,9 +4,9 @@ title: Component API Reference # Component -A Component represents a deployable unit of an application in OpenChoreo. It serves as the core abstraction that -defines the component type (Service, WebApplication, ScheduledTask, etc.) and optionally includes build configuration -when using OpenChoreo's CI system to build from source. Components are the primary building blocks used to define +A Component represents a deployable unit of software in OpenChoreo. It connects a ComponentType (which defines how to +deploy) with parameters (which configure what to deploy), optional traits (which add capabilities), and optional +workflow configuration (which defines how to build). Components are the primary building blocks used to define applications within a Project. ## API Version @@ -30,11 +30,16 @@ metadata: ### Spec Fields -| Field | Type | Required | Default | Description | -|---------|-----------------------------------------------|----------|---------|--------------------------------------------------------------------------------------------------------| -| `owner` | [ComponentOwner](#componentowner) | Yes | - | Ownership information linking the component to a project | -| `type` | [ComponentType](#componenttype) | Yes | - | Specifies the component type (Service, WebApplication, ScheduledTask, etc.) | -| `build` | [BuildSpecInComponent](#buildspecincomponent) | No | - | Optional build configuration when using OpenChoreo CI to build from source (omit for pre-built images) | +| Field | Type | Required | Default | Description | +|-----------------|-----------------------------------|----------|---------|------------------------------------------------------------------------------------------------| +| `owner` | [ComponentOwner](#componentowner) | Yes | - | Ownership information linking the component to a project | +| `componentType` | string | No* | - | ComponentType reference in format `{workloadType}/{componentTypeName}` (new schema-driven API) | +| `type` | string | No* | - | Legacy component type (Service, WebApplication, ScheduledTask) - use `componentType` instead | +| `parameters` | object | No | - | Configuration values conforming to the ComponentType schema | +| `traits` | [[ComponentTrait](#componenttrait)] | No | [] | Trait instances to compose into this component | +| `workflow` | [WorkflowConfig](#workflowconfig) | No | - | Optional workflow configuration for building from source | + +*Either `componentType` (new) or `type` (legacy) must be specified. ### ComponentOwner @@ -42,51 +47,20 @@ metadata: |---------------|--------|----------|---------|-------------------------------------------------------| | `projectName` | string | Yes | - | Name of the project that owns this component (min: 1) | -### ComponentType - -The component type determines how the component will be deployed and what resources it can create. - -| Value | Description | -|------------------|-------------------------------------| -| `Service` | Long-running service component | -| `WebApplication` | Web application with HTTP endpoints | -| `ScheduledTask` | Scheduled/cron job component | - -### BuildSpecInComponent - -| Field | Type | Required | Default | Description | -|---------------|-------------------------------------|----------|---------|-----------------------------------------------------------------------| -| `repository` | [BuildRepository](#buildrepository) | Yes | - | Source repository configuration where the component code resides | -| `templateRef` | [TemplateRef](#templateref) | Yes | - | Build template reference (ClusterWorkflowTemplate in the build plane) | - -### BuildRepository +### ComponentTrait -| 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., ".") | +| Field | Type | Required | Default | Description | +|----------------|--------|----------|---------|---------------------------------------------------------------------------| +| `name` | string | Yes | - | Name of the Trait resource to use | +| `instanceName` | string | Yes | - | Unique identifier for this trait instance within the component | +| `parameters` | object | No | - | Trait parameter values conforming to the Trait's schema | -### BuildRevision +### WorkflowConfig -| 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 | +| Field | Type | Required | Default | Description | +|----------|--------|----------|---------|----------------------------------------------------------------------| +| `name` | string | Yes | - | Name of the Workflow CR to use for building | +| `schema` | object | No | - | Developer-provided values conforming to the Workflow's schema | ### Status Fields @@ -104,7 +78,7 @@ Common condition types for Component resources: ## Examples -### Service Component with Docker Build +### Basic Component with ComponentType ```yaml apiVersion: openchoreo.dev/v1alpha1 @@ -114,43 +88,184 @@ metadata: namespace: default spec: owner: - projectName: my-project - type: Service - build: - repository: - url: https://github.com/myorg/customer-service - revision: - branch: main - appPath: . - templateRef: - name: docker + projectName: ecommerce + + componentType: deployment/http-service + + parameters: + replicas: 2 + port: 8080 + resources: + requests: + cpu: "200m" + memory: "512Mi" + limits: + cpu: "1000m" + memory: "1Gi" +``` + +### Component with Workflow Configuration + +```yaml +apiVersion: openchoreo.dev/v1alpha1 +kind: Component +metadata: + name: payment-service + namespace: default +spec: + owner: + projectName: ecommerce + + componentType: deployment/secure-service + + parameters: + replicas: 3 + port: 8080 + + workflow: + name: docker + schema: + repository: + url: https://github.com/myorg/payment-service + revision: + branch: main + appPath: . + secretRef: github-credentials + docker: + context: . + filePath: ./Dockerfile +``` + +### Component with Traits + +```yaml +apiVersion: openchoreo.dev/v1alpha1 +kind: Component +metadata: + name: order-service + namespace: default +spec: + owner: + projectName: ecommerce + + componentType: deployment/web-service + + parameters: + replicas: 2 + port: 8080 + resources: + requests: + cpu: "200m" + memory: "512Mi" + limits: + cpu: "1000m" + memory: "1Gi" + + traits: + - name: persistent-volume + instanceName: data-storage + parameters: + volumeName: order-data + mountPath: /var/data + containerName: app + size: "20Gi" + storageClass: "fast" + + - name: emptydir-volume + instanceName: cache + parameters: + volumeName: cache-vol + mounts: + - containerName: app + mountPath: /tmp/cache + readOnly: false + medium: "" + sizeLimit: "1Gi" +``` + +### Component with Multiple Traits and Workflow + +```yaml +apiVersion: openchoreo.dev/v1alpha1 +kind: Component +metadata: + name: analytics-service + namespace: default +spec: + owner: + projectName: data-platform + + componentType: deployment/data-processor + + parameters: + replicas: 1 + resources: + requests: + cpu: "500m" + memory: "2Gi" + limits: + cpu: "2000m" + memory: "4Gi" + + traits: + - name: persistent-volume + instanceName: analytics-data + parameters: + volumeName: analytics-storage + mountPath: /data + size: "100Gi" + + - name: monitoring + instanceName: metrics parameters: - - name: docker-context - value: . - - name: dockerfile-path - value: ./Dockerfile + enabled: true + port: 9090 + + workflow: + name: google-cloud-buildpacks + schema: + repository: + url: https://github.com/myorg/analytics-service + revision: + branch: main + secretRef: repo-credentials + version: 1 + testMode: unit + resources: + cpuCores: 2 + memoryGb: 4 ``` -### WebApplication Component with Buildpacks +### CronJob Component ```yaml apiVersion: openchoreo.dev/v1alpha1 kind: Component metadata: - name: frontend-app + name: daily-report-generator namespace: default spec: owner: - projectName: my-project - type: WebApplication - build: - repository: - url: https://github.com/myorg/frontend - revision: - branch: develop - appPath: ./webapp - templateRef: - name: google-cloud-buildpacks + projectName: reporting + + componentType: cronjob/scheduled-processor + + parameters: + schedule: "0 2 * * *" # Run at 2 AM daily + resources: + requests: + cpu: "100m" + memory: "256Mi" + limits: + cpu: "500m" + memory: "512Mi" + + workflow: + name: docker + schema: + repository: + url: https://github.com/myorg/report-generator + secretRef: github-token ``` ## Annotations @@ -165,8 +280,7 @@ Components support the following annotations: ## Related Resources - [Project](./project.md) - Contains components -- [Build](./build.md) - Build jobs triggered by components +- [ComponentType](../platform/componenttype.md) - Defines deployment templates for 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 +- [WorkflowRun](./workflowrun.md) - Workflow execution instances for builds +- [Workflow](../platform/workflow.md) - Build workflow templates \ No newline at end of file diff --git a/docs/reference/api/application/project.md b/docs/reference/api/application/project.md index a7f61ab..8431064 100644 --- a/docs/reference/api/application/project.md +++ b/docs/reference/api/application/project.md @@ -79,4 +79,3 @@ Projects support the following annotations: - [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/docs/reference/api/application/scheduledtask.md b/docs/reference/api/application/scheduledtask.md deleted file mode 100644 index 395415e..0000000 --- a/docs/reference/api/application/scheduledtask.md +++ /dev/null @@ -1,93 +0,0 @@ ---- -title: ScheduledTask API Reference ---- - -# ScheduledTask - -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/docs/reference/api/application/service.md b/docs/reference/api/application/service.md deleted file mode 100644 index 1a8ecef..0000000 --- a/docs/reference/api/application/service.md +++ /dev/null @@ -1,147 +0,0 @@ ---- -title: Service API Reference ---- - -# Service - -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/docs/reference/api/application/webapplication.md b/docs/reference/api/application/webapplication.md deleted file mode 100644 index f521a0c..0000000 --- a/docs/reference/api/application/webapplication.md +++ /dev/null @@ -1,93 +0,0 @@ ---- -title: WebApplication API Reference ---- - -# WebApplication - -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/docs/reference/api/application/workflowrun.md b/docs/reference/api/application/workflowrun.md new file mode 100644 index 0000000..27a4909 --- /dev/null +++ b/docs/reference/api/application/workflowrun.md @@ -0,0 +1,225 @@ +--- +title: WorkflowRun API Reference +--- + +# WorkflowRun + +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. + +## 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 \ No newline at end of file diff --git a/docs/reference/api/application/workload.md b/docs/reference/api/application/workload.md index 0ea1c1d..130cf99 100644 --- a/docs/reference/api/application/workload.md +++ b/docs/reference/api/application/workload.md @@ -190,7 +190,3 @@ Workloads support the following annotations: ## 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/docs/reference/api/platform/buildplane.md b/docs/reference/api/platform/buildplane.md index a17acef..3f7e792 100644 --- a/docs/reference/api/platform/buildplane.md +++ b/docs/reference/api/platform/buildplane.md @@ -99,4 +99,3 @@ BuildPlanes support the following annotations: - [Build](../application/build.md) - Build job definitions that execute on BuildPlanes - [Component](../application/component.md) - Application components that trigger builds -- [Organization](./organization.md) - Organizational context for BuildPlanes diff --git a/docs/reference/api/platform/componenttype.md b/docs/reference/api/platform/componenttype.md new file mode 100644 index 0000000..56696f1 --- /dev/null +++ b/docs/reference/api/platform/componenttype.md @@ -0,0 +1,261 @@ +--- +title: ComponentType API Reference +--- + +# ComponentType + +A ComponentType is a platform engineer-defined template that governs how components are deployed and managed in +OpenChoreo. It implements the platform's claim/class pattern, where platform engineers define ComponentTypes (classes) +to enforce organizational policies, best practices, and infrastructure patterns, while developers create Components +(claims) that reference these types. + +## API Version + +`openchoreo.dev/v1alpha1` + +## Resource Definition + +### Metadata + +ComponentTypes are namespace-scoped resources that must be created within an Organization's namespace. + +```yaml +apiVersion: openchoreo.dev/v1alpha1 +kind: ComponentType +metadata: + name: + namespace: # Organization namespace +``` + +### Spec Fields + +| Field | Type | Required | Default | Description | +|--------------------|---------------------|----------|---------|------------------------------------------------------------------------------------------------------| +| `workloadType` | string | Yes | - | Primary workload resource type: `deployment`, `statefulset`, `cronjob`, or `job` | +| `allowedWorkflows` | []AllowedWorkflow | No | [] | Restricts which Workflow CRs developers can use for building components of this type | +| `schema` | ComponentTypeSchema | No | - | Defines configurable parameters for components, including types, parameters, and environment overrides | +| `resources` | []ResourceTemplate | Yes | - | Templates that generate Kubernetes resources dynamically using CEL expressions | + +#### ComponentTypeSchema + +| Field | Type | Required | Default | Description | +|---------------|--------------------------|----------|---------|-----------------------------------------------------------------------------------------| +| `types` | map[string]interface{} | No | - | Reusable type definitions that can be referenced in schema fields | +| `parameters` | map[string]interface{} | No | - | Static configurations that remain consistent across environments | +| `envOverrides`| map[string]interface{} | No | - | Configurations that can be overridden per environment via ComponentDeployment resources | + +#### ResourceTemplate + +| Field | Type | Required | Default | Description | +|--------------|--------|----------|---------|--------------------------------------------------------------------------------------------------| +| `id` | string | Yes | - | Unique identifier for this resource. For primary workload, must match `workloadType` | +| `includeWhen`| string | No | - | CEL expression determining if this resource should be created | +| `forEach` | string | No | - | CEL expression for generating multiple resources from a list | +| `var` | string | No | - | Loop variable name when using `forEach` (required if `forEach` is specified) | +| `template` | object | Yes | - | Kubernetes resource template with CEL expressions enclosed in `${...}` for dynamic value injection | + +#### AllowedWorkflow + +| Field | Type | Required | Default | Description | +|--------|--------|----------|---------|---------------------------------| +| `name` | string | Yes | - | Name of the allowed Workflow CR | + +## Schema Syntax + +ComponentType schemas use an inline type definition syntax: + +``` +"type | default=value enum=val1,val2 minimum=1 maximum=10" +``` + +**Supported Types:** +- `string`, `integer`, `number`, `boolean` +- `array` or `[]type` +- Custom type references defined in `types` section + +**Modifiers:** +- `default=value` - Default value if not provided +- `required=true` - Field must be provided +- `enum=val1,val2` - Restrict to enumerated values +- `minimum=N`, `maximum=N` - Numeric constraints +- `minItems=N`, `maxItems=N` - Array size constraints + +## CEL Variables in Templates + +Resource templates support CEL expressions with access to: + +| Variable | Description | +|---------------------------------------|-------------------------------------------------------------------| +| `${metadata.name}` | Generated resource name for the deployment | +| `${metadata.namespace}` | Target namespace for resources | +| `${metadata.labels}` | Platform-generated labels for resources | +| `${metadata.podSelectors}` | Pod selector labels for Deployments and Services | +| `${parameters.*}` | Component parameters (merged from Component and ComponentDeployment) | +| `${environment.name}` | Environment name | +| `${environment.vhost}` | Environment virtual host for routing | +| `${configurations.*}` | Configuration values from SecretReferences (configs, secrets) | +| `${dataplane.secretStore}` | Secret store reference name from DataPlane (for External Secrets) | +| `${trait.instanceName}` | Trait instance name (available in trait templates) | + +## Examples + +### Basic ComponentType for HTTP Service + +```yaml +apiVersion: openchoreo.dev/v1alpha1 +kind: ComponentType +metadata: + name: http-service + namespace: default +spec: + workloadType: deployment + + schema: + types: + Resources: + cpu: "string | default=100m" + memory: "string | default=256Mi" + + parameters: + replicas: "integer | default=1" + imagePullPolicy: "string | default=IfNotPresent" + port: "integer | default=8080" + + envOverrides: + resources: + requests: Resources + limits: Resources + + resources: + - 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: app + image: ${workload.containers["app"].image} + imagePullPolicy: ${parameters.imagePullPolicy} + ports: + - name: http + containerPort: ${parameters.port} + protocol: TCP + resources: + requests: + cpu: ${parameters.resources.requests.cpu} + memory: ${parameters.resources.requests.memory} + limits: + cpu: ${parameters.resources.limits.cpu} + memory: ${parameters.resources.limits.memory} + + - id: service + template: + apiVersion: v1 + kind: Service + metadata: + name: ${metadata.name} + namespace: ${metadata.namespace} + labels: ${metadata.labels} + spec: + type: ClusterIP + selector: ${metadata.podSelectors} + ports: + - name: http + port: 80 + targetPort: ${parameters.port} + protocol: TCP +``` + +### ComponentType with Allowed Workflows + +```yaml +apiVersion: openchoreo.dev/v1alpha1 +kind: ComponentType +metadata: + name: secure-web-service + namespace: default +spec: + workloadType: deployment + + allowedWorkflows: + - name: docker + - name: google-cloud-buildpacks + + schema: + parameters: + replicas: "integer | default=2" + port: "integer | default=8080" + + resources: + - id: deployment + template: + apiVersion: apps/v1 + kind: Deployment + metadata: + name: ${metadata.name} + spec: + replicas: ${parameters.replicas} + # ... deployment spec +``` + +### ComponentType with Conditional Resources + +```yaml +apiVersion: openchoreo.dev/v1alpha1 +kind: ComponentType +metadata: + name: scalable-service + namespace: default +spec: + workloadType: deployment + + schema: + parameters: + replicas: "integer | default=1" + autoscaling: + enabled: "boolean | default=false" + minReplicas: "integer | default=1" + maxReplicas: "integer | default=10" + + resources: + - id: deployment + template: + # ... deployment template + + - id: hpa + includeWhen: ${parameters.autoscaling.enabled} + template: + apiVersion: autoscaling/v2 + kind: HorizontalPodAutoscaler + metadata: + name: ${metadata.name} + spec: + minReplicas: ${parameters.autoscaling.minReplicas} + maxReplicas: ${parameters.autoscaling.maxReplicas} + # ... HPA spec +``` + +## Annotations + +ComponentTypes support the following annotations: + +| Annotation | Description | +|-------------------------------|---------------------------------------------| +| `openchoreo.dev/display-name` | Human-readable name for UI display | +| `openchoreo.dev/description` | Detailed description of the ComponentType | + +## Related Resources + +- [Component](../application/component.md) - Components that reference ComponentTypes +- [Workflow](./workflow.md) - Build workflows that can be restricted by ComponentTypes diff --git a/docs/reference/api/platform/dataplane.md b/docs/reference/api/platform/dataplane.md index 6e63d9b..1f5411d 100644 --- a/docs/reference/api/platform/dataplane.md +++ b/docs/reference/api/platform/dataplane.md @@ -125,5 +125,4 @@ DataPlanes support the following annotations: ## Related Resources - [Environment](./environment.md) - Runtime environments deployed on DataPlanes -- [Organization](./organization.md) - Contains DataPlane definitions - [Project](../application/project.md) - Applications deployed to DataPlanes diff --git a/docs/reference/api/platform/deployment-pipeline.md b/docs/reference/api/platform/deployment-pipeline.md index 4dd1202..79f18d4 100644 --- a/docs/reference/api/platform/deployment-pipeline.md +++ b/docs/reference/api/platform/deployment-pipeline.md @@ -95,4 +95,3 @@ DeploymentPipelines support the following annotations: - [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/docs/reference/api/platform/environment.md b/docs/reference/api/platform/environment.md index 5f2c576..ff1e53a 100644 --- a/docs/reference/api/platform/environment.md +++ b/docs/reference/api/platform/environment.md @@ -107,4 +107,3 @@ Environments support the following annotations: - [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/docs/reference/api/platform/organization.md b/docs/reference/api/platform/organization.md deleted file mode 100644 index e14c3ee..0000000 --- a/docs/reference/api/platform/organization.md +++ /dev/null @@ -1,79 +0,0 @@ ---- -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/docs/reference/api/platform/scheduledtaskclass.md b/docs/reference/api/platform/scheduledtaskclass.md deleted file mode 100644 index 672f61c..0000000 --- a/docs/reference/api/platform/scheduledtaskclass.md +++ /dev/null @@ -1,84 +0,0 @@ ---- -title: ScheduledTaskClass API Reference ---- - -# ScheduledTaskClass - -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/docs/reference/api/platform/serviceclass.md b/docs/reference/api/platform/serviceclass.md deleted file mode 100644 index 144a501..0000000 --- a/docs/reference/api/platform/serviceclass.md +++ /dev/null @@ -1,85 +0,0 @@ ---- -title: ServiceClass API Reference ---- - -# ServiceClass - -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/docs/reference/api/platform/webapplicationclass.md b/docs/reference/api/platform/webapplicationclass.md deleted file mode 100644 index 6ffefe1..0000000 --- a/docs/reference/api/platform/webapplicationclass.md +++ /dev/null @@ -1,87 +0,0 @@ ---- -title: WebApplicationClass API Reference ---- - -# WebApplicationClass - -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/docs/reference/api/platform/workflow.md b/docs/reference/api/platform/workflow.md new file mode 100644 index 0000000..ce4283d --- /dev/null +++ b/docs/reference/api/platform/workflow.md @@ -0,0 +1,254 @@ +--- +title: Workflow API Reference +--- + +# Workflow + +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 \ No newline at end of file diff --git a/docs/reference/api/runtime/componentdeployment.md b/docs/reference/api/runtime/componentdeployment.md new file mode 100644 index 0000000..318054f --- /dev/null +++ b/docs/reference/api/runtime/componentdeployment.md @@ -0,0 +1,280 @@ +--- +title: ComponentDeployment API Reference +--- + +# ComponentDeployment + +A ComponentDeployment represents an environment-specific deployment configuration for a Component in OpenChoreo. It +allows platform engineers and developers to override component parameters and trait configurations on a per-environment +basis, enabling progressive delivery and environment-specific customization while maintaining a single component +definition. + +## API Version + +`openchoreo.dev/v1alpha1` + +## Resource Definition + +### Metadata + +ComponentDeployments are namespace-scoped resources that must be created within an Organization's namespace. + +```yaml +apiVersion: openchoreo.dev/v1alpha1 +kind: ComponentDeployment +metadata: + name: + namespace: # Organization 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 this deployment applies to | +| `overrides` | object | No | - | Environment-specific overrides for ComponentType envOverrides parameters | +| `traitOverrides` | map[string]object | No | {} | Environment-specific overrides for trait configurations (keyed by instanceName) | +| `configurationOverrides` | [EnvConfigurationOverrides](#envconfigurationoverrides) | No | - | Environment-specific overrides for workload configurations | + +### ComponentDeploymentOwner + +| Field | Type | Required | Default | Description | +|-----------------|--------|----------|---------|---------------------------------------------------| +| `projectName` | string | Yes | - | Name of the project that owns the component | +| `componentName` | string | Yes | - | Name of the component this deployment applies to | + +### EnvConfigurationOverrides + +| Field | Type | Required | Default | Description | +|---------|-----------------|----------|---------|-----------------------------------------| +| `env` | [[EnvVar](#envvar)] | No | [] | Environment variable overrides | +| `files` | [[FileVar](#filevar)] | No | [] | File configuration overrides | + +### EnvVar + +Environment variable configuration (structure depends on workload implementation). + +### FileVar + +File configuration (structure depends on workload implementation). + +### Status Fields + +| Field | Type | Default | Description | +|----------------------|-------------|---------|--------------------------------------------------------------| +| `observedGeneration` | integer | 0 | The generation observed by the controller | +| `conditions` | []Condition | [] | Standard Kubernetes conditions tracking deployment state | + +#### Condition Types + +Common condition types for ComponentDeployment resources: + +- `Ready` - Indicates if the component deployment is ready +- `Reconciled` - Indicates if the controller has successfully reconciled the deployment + +## Examples + +### Basic ComponentDeployment with Resource Overrides + +```yaml +apiVersion: openchoreo.dev/v1alpha1 +kind: ComponentDeployment +metadata: + name: customer-service-production + namespace: default +spec: + owner: + projectName: ecommerce + componentName: customer-service + + environment: production + + overrides: + resources: + requests: + cpu: "1000m" + memory: "2Gi" + limits: + cpu: "4000m" + memory: "8Gi" +``` + +### ComponentDeployment with Development Environment Constraints + +```yaml +apiVersion: openchoreo.dev/v1alpha1 +kind: ComponentDeployment +metadata: + name: payment-service-development + namespace: default +spec: + owner: + projectName: ecommerce + componentName: payment-service + + environment: development + + overrides: + resources: + requests: + cpu: "50m" + memory: "128Mi" + limits: + cpu: "200m" + memory: "256Mi" +``` + +### ComponentDeployment with Trait Overrides + +```yaml +apiVersion: openchoreo.dev/v1alpha1 +kind: ComponentDeployment +metadata: + name: order-service-staging + namespace: default +spec: + owner: + projectName: ecommerce + componentName: order-service + + environment: staging + + overrides: + resources: + requests: + cpu: "500m" + memory: "1Gi" + limits: + cpu: "2000m" + memory: "4Gi" + + traitOverrides: + data-storage: + size: "50Gi" + storageClass: "standard" + cache: + medium: "Memory" + sizeLimit: "2Gi" +``` + +### ComponentDeployment with Configuration Overrides + +```yaml +apiVersion: openchoreo.dev/v1alpha1 +kind: ComponentDeployment +metadata: + name: analytics-service-production + namespace: default +spec: + owner: + projectName: data-platform + componentName: analytics-service + + environment: production + + overrides: + replicas: 5 + resources: + requests: + cpu: "2000m" + memory: "8Gi" + limits: + cpu: "8000m" + memory: "16Gi" + + configurationOverrides: + env: + - name: DATABASE_URL + value: "postgres://prod-db.example.com:5432/analytics" + - name: CACHE_ENABLED + value: "true" + files: + - name: app-config.yaml + value: | + logging: + level: info + performance: + maxConnections: 1000 +``` + +### Multiple Environment Deployments for Same Component + +Development: +```yaml +apiVersion: openchoreo.dev/v1alpha1 +kind: ComponentDeployment +metadata: + name: api-gateway-development + namespace: default +spec: + owner: + projectName: platform + componentName: api-gateway + environment: development + overrides: + replicas: 1 + resources: + requests: + cpu: "100m" + memory: "256Mi" +``` + +Staging: +```yaml +apiVersion: openchoreo.dev/v1alpha1 +kind: ComponentDeployment +metadata: + name: api-gateway-staging + namespace: default +spec: + owner: + projectName: platform + componentName: api-gateway + environment: staging + overrides: + replicas: 2 + resources: + requests: + cpu: "500m" + memory: "1Gi" +``` + +Production: +```yaml +apiVersion: openchoreo.dev/v1alpha1 +kind: ComponentDeployment +metadata: + name: api-gateway-production + namespace: default +spec: + owner: + projectName: platform + componentName: api-gateway + environment: production + overrides: + replicas: 5 + resources: + requests: + cpu: "2000m" + memory: "4Gi" + limits: + cpu: "8000m" + memory: "16Gi" +``` + +## Annotations + +ComponentDeployments support the following annotations: + +| Annotation | Description | +|-------------------------------|-------------------------------------------------| +| `openchoreo.dev/display-name` | Human-readable name for UI display | +| `openchoreo.dev/description` | Detailed description of the component deployment | + +## Related Resources + +- [Component](../application/component.md) - Components being deployed +- [ComponentType](../platform/componenttype.md) - Defines envOverrides schema +- [Environment](../platform/environment.md) - Target environments +- [Release](./release.md) - Created by ComponentDeployment for actual deployment \ No newline at end of file diff --git a/docs/reference/api/runtime/release.md b/docs/reference/api/runtime/release.md index 9046c2b..20c68e9 100644 --- a/docs/reference/api/runtime/release.md +++ b/docs/reference/api/runtime/release.md @@ -5,9 +5,9 @@ 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. +created by ComponentDeployment controllers 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 across +all component types (deployments, statefulsets, cronjobs, jobs). ## API Version @@ -92,7 +92,7 @@ Releases report their state through standard Kubernetes conditions. The followin ## Examples -### Basic Release with Deployment and Service +### Release for Deployment-based Component ```yaml apiVersion: openchoreo.dev/v1alpha1 @@ -102,7 +102,7 @@ metadata: namespace: default spec: owner: - projectName: my-project + projectName: ecommerce componentName: customer-service environmentName: production interval: 5m @@ -113,38 +113,162 @@ spec: apiVersion: apps/v1 kind: Deployment metadata: - name: customer-service + name: customer-service-prod namespace: prod-data-plane + labels: + openchoreo.dev/component: customer-service + openchoreo.dev/environment: production spec: replicas: 3 selector: matchLabels: - app: customer-service + openchoreo.dev/component-id: abc123 template: metadata: labels: - app: customer-service + openchoreo.dev/component-id: abc123 spec: containers: - - name: main + - name: app image: myregistry/customer-service:v1.0.0 ports: - containerPort: 8080 + resources: + requests: + cpu: "500m" + memory: "1Gi" + limits: + cpu: "2000m" + memory: "2Gi" - id: service object: apiVersion: v1 kind: Service metadata: - name: customer-service + name: customer-service-prod namespace: prod-data-plane spec: selector: - app: customer-service + openchoreo.dev/component-id: abc123 ports: - port: 80 targetPort: 8080 ``` +### Release for CronJob-based Component + +```yaml +apiVersion: openchoreo.dev/v1alpha1 +kind: Release +metadata: + name: report-generator-prod-release + namespace: default +spec: + owner: + projectName: reporting + componentName: daily-report-generator + environmentName: production + resources: + - id: cronjob + object: + apiVersion: batch/v1 + kind: CronJob + metadata: + name: daily-report-generator-prod + namespace: prod-data-plane + spec: + schedule: "0 2 * * *" + jobTemplate: + spec: + template: + spec: + containers: + - name: app + image: myregistry/report-generator:v2.0.0 + resources: + requests: + cpu: "200m" + memory: "512Mi" + restartPolicy: OnFailure +``` + +### Release with Multiple Resources + +```yaml +apiVersion: openchoreo.dev/v1alpha1 +kind: Release +metadata: + name: order-service-staging-release + namespace: default +spec: + owner: + projectName: ecommerce + componentName: order-service + environmentName: staging + resources: + - id: deployment + object: + apiVersion: apps/v1 + kind: Deployment + # ... deployment spec + - id: service + object: + apiVersion: v1 + kind: Service + # ... service spec + - id: configmap + object: + apiVersion: v1 + kind: ConfigMap + metadata: + name: order-service-config + data: + database_url: "postgres://db.staging.example.com:5432/orders" + - id: httproute + object: + apiVersion: gateway.networking.k8s.io/v1 + kind: HTTPRoute + metadata: + name: order-service-route + spec: + parentRefs: + - name: gateway-external + hostnames: + - order-service-staging.example.com + # ... route spec +``` + +## Status Example + +After deployment, a Release status might look like: + +```yaml +status: + conditions: + - type: Ready + status: "True" + lastTransitionTime: "2024-01-15T10:30:00Z" + reason: AllResourcesHealthy + message: All resources are healthy + resources: + - id: deployment + group: apps + version: v1 + kind: Deployment + name: customer-service-prod + namespace: prod-data-plane + healthStatus: Healthy + lastObservedTime: "2024-01-15T10:35:00Z" + - id: service + group: "" + version: v1 + kind: Service + name: customer-service-prod + namespace: prod-data-plane + healthStatus: Healthy + lastObservedTime: "2024-01-15T10:35:00Z" +``` + ## Annotations Releases support the following annotations: @@ -156,8 +280,7 @@ Releases support the following annotations: ## 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 +- [ComponentDeployment](./componentdeployment.md) - Creates releases for component deployments +- [Component](../application/component.md) - Components being deployed - [Environment](../platform/environment.md) - Target environments for releases -- [DataPlane](../platform/dataplane.md) - Data planes where resources are deployed +- [DataPlane](../platform/dataplane.md) - Data planes where resources are deployed \ No newline at end of file diff --git a/docs/reference/api/runtime/scheduledtaskbinding.md b/docs/reference/api/runtime/scheduledtaskbinding.md deleted file mode 100644 index 67b3823..0000000 --- a/docs/reference/api/runtime/scheduledtaskbinding.md +++ /dev/null @@ -1,108 +0,0 @@ ---- -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/docs/reference/api/runtime/servicebinding.md b/docs/reference/api/runtime/servicebinding.md deleted file mode 100644 index 125eadc..0000000 --- a/docs/reference/api/runtime/servicebinding.md +++ /dev/null @@ -1,196 +0,0 @@ ---- -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/docs/reference/api/runtime/webapplicationbinding.md b/docs/reference/api/runtime/webapplicationbinding.md deleted file mode 100644 index 6e431d1..0000000 --- a/docs/reference/api/runtime/webapplicationbinding.md +++ /dev/null @@ -1,188 +0,0 @@ ---- -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/docs/reference/configuration-schema.md b/docs/reference/configuration-schema.md index 23e81c7..da5e737 100644 --- a/docs/reference/configuration-schema.md +++ b/docs/reference/configuration-schema.md @@ -92,7 +92,7 @@ spec: 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 @@ -101,12 +101,16 @@ spec: 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 - + + # Secret Store Configuration + secretStoreRef: # Optional: External Secrets reference + name: string # Required: Secret store name + # Observer API Integration observer: # Optional: Observer API url: string # Required: Observer API base URL @@ -142,7 +146,7 @@ spec: caCert: string clientCert: string clientKey: string - + # Observer API Integration (Optional) observer: # Optional: Same structure as DataPlane url: string @@ -180,433 +184,178 @@ status: 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 +### ComponentType CRD Schema ```yaml apiVersion: openchoreo.dev/v1alpha1 -kind: Component +kind: ComponentType metadata: - name: string # Required: Component name - namespace: string # Required: Project namespace + name: string # Required: ComponentType name + namespace: string # Required: Organization 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 + # Workload Type + workloadType: enum # Required: "deployment" | "statefulset" | "cronjob" | "job" + + # Workflow Restrictions + allowedWorkflows: # Optional: Restrict which workflows can be used + - name: string # Required: Workflow name + + # Schema Definition + schema: # Optional: Developer-facing configuration schema + types: # Optional: Reusable type definitions + "{TypeName}": # Custom type definitions + field: string # Type definition using inline syntax + + parameters: # Optional: Static parameters (environment-independent) + "{fieldName}": string # Type definition: "type | default=value | enum=val1,val2" + + envOverrides: # Optional: Environment-overridable parameters + "{fieldName}": string # Type definition: "type | default=value" + + # Resource Templates + resources: # Required: Templates for generating Kubernetes resources + - id: string # Required: Unique identifier (primary must match workloadType) + includeWhen: string # Optional: CEL expression for conditional inclusion + forEach: string # Optional: CEL expression for iteration + var: string # Optional: Loop variable name (required if forEach specified) + template: # Required: Kubernetes resource with CEL expressions + # ... Kubernetes resource YAML with ${...} CEL expressions -status: - conditions: # Standard Kubernetes conditions - - type: string - status: enum # "True" | "False" | "Unknown" - reason: string - message: string - lastTransitionTime: string - observedGeneration: integer +status: {} # Empty status object ``` -### Build CRD Schema + +### Trait CRD Schema ```yaml apiVersion: openchoreo.dev/v1alpha1 -kind: Build +kind: Trait metadata: - name: string # Required: Build name - namespace: string # Required: Project namespace + name: string # Required: Trait name + namespace: string # Required: Organization 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 + # Schema Definition + schema: # Optional: Trait configuration schema + types: # Optional: Reusable type definitions + "{TypeName}": # Custom type definitions + field: string # Type definition using inline syntax + + parameters: # Optional: Static parameters + "{fieldName}": string # Type definition + + envOverrides: # Optional: Environment-overridable parameters + "{fieldName}": string # Type definition + + # Resource Creation + creates: # Optional: Resources to create + - includeWhen: string # Optional: CEL condition + forEach: string # Optional: CEL iteration + var: string # Optional: Loop variable + template: # Required: Resource template + # ... Kubernetes resource with CEL expressions + + # Resource Patches + patches: # Optional: Patches to apply + - target: # Required: Target resource + group: string # API group + version: string # API version + kind: string # Resource kind + forEach: string # Optional: CEL iteration + var: string # Optional: Loop variable + operations: # Required: JSON Patch operations + - op: enum # "add" | "remove" | "replace" + path: string # JSON path + value: # Value (for add/replace) + # ... Value specification -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 +status: {} # Empty status object ``` -### DeploymentTrack CRD Schema +### Workflow CRD Schema ```yaml apiVersion: openchoreo.dev/v1alpha1 -kind: DeploymentTrack +kind: Workflow metadata: - name: string # Required: DeploymentTrack name - namespace: string # Required: Project namespace + name: string # Required: Workflow name + namespace: string # Required: Organization 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 + # Developer-facing Schema + schema: # Optional: Parameters developers can configure + "{fieldName}": string # Type definition: "type | default=value | enum=val1,val2" + # Nested structure supported for complex configurations + + # Secret References + secrets: # Optional: Secrets to sync to build plane + - string # Secret reference (supports CEL: ${schema.field}) + + # Resource Template + resource: # Required: Argo Workflow with CEL expressions + # Kubernetes resource with ${ctx.*} and ${schema.*} variables + apiVersion: argoproj.io/v1alpha1 + kind: Workflow + # ... Argo Workflow specification with CEL expressions 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 + conditions: - type: string - status: enum # "True" | "False" | "Unknown" + status: enum 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 +## Application Resources -status: {} # Empty status object -``` +OpenChoreo uses a schema-driven architecture where Components reference ComponentTypes to define deployment patterns, compose capabilities through Traits, and optionally configure Workflows for building from source. -### WebApplication CRD Schema +### Component CRD Schema ```yaml apiVersion: openchoreo.dev/v1alpha1 -kind: WebApplication +kind: Component metadata: - name: string # Required: WebApplication name - namespace: string # Required: Project namespace + name: string # Required: Component name + namespace: string # Required: Organization 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 + # Component Type (new schema-driven API) + componentType: string # Optional: Format "{workloadType}/{componentTypeName}" + # Example: "deployment/web-service" -```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 + # Legacy Type (deprecated) + type: enum # Optional: "Service" | "WebApplication" | "ScheduledTask" + # Use componentType instead for new components -status: {} # Empty status object -``` + # Parameters + parameters: # Optional: Configuration conforming to ComponentType schema + # Structure defined by referenced ComponentType's schema + # Supports both parameters and envOverrides fields -### API CRD Schema + # Traits (Composition) + traits: # Optional: Trait instances to compose + - name: string # Required: Trait resource name + instanceName: string # Required: Unique instance identifier + parameters: # Optional: Trait-specific configuration + # Structure defined by Trait's 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 + # Workflow Configuration + workflow: # Optional: Build workflow configuration + name: string # Required: Workflow CR name + schema: # Optional: Developer-provided values + # Structure defined by Workflow's schema status: - address: string # API address conditions: # Standard Kubernetes conditions - type: string - status: enum + status: enum # "True" | "False" | "Unknown" 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 + observedGeneration: integer ``` ### Workload CRD Schema @@ -616,180 +365,181 @@ apiVersion: openchoreo.dev/v1alpha1 kind: Workload metadata: name: string # Required: Workload name - namespace: string # Required: Project namespace + namespace: string # Required: Organization 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 + # Owner Reference + owner: # Required: Owner information + projectName: string # Required: Project name + componentName: string # Required: Component name + + # Container Specifications + containers: # Optional: Container definitions (map) + "{containerName}": # Container name (e.g., "app", "sidecar") + image: string # Required: Container image reference + command: # Optional: Command override + - string + args: # Optional: Arguments + - string + env: # Optional: Environment variables + - name: string + value: string + + # Endpoints + endpoints: # Optional: Network endpoints + - name: string # Required: Endpoint name + port: integer # Required: Port number + protocol: string # Optional: Protocol (default: "TCP") + type: string # Optional: Type (e.g., "http", "grpc") + + # Connections + connections: # Optional: Service dependencies + - name: string # Required: Connection name + target: # Required: Target service + service: string # Service name + port: integer # Service port + inject: # Optional: Injection configuration + env: # Environment variables + - key: string + value: string status: {} # Empty status object ``` -### Release CRD Schema +### WorkflowRun CRD Schema ```yaml apiVersion: openchoreo.dev/v1alpha1 -kind: Release +kind: WorkflowRun metadata: - name: string # Required: Release name - namespace: string # Required: Project namespace + name: string # Required: WorkflowRun name + namespace: string # Required: Organization 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 + # Owner Reference (Optional) + owner: # Optional: Component-bound workflow + projectName: string # Required: Project name + componentName: string # Required: Component name + + # Workflow Configuration + workflow: # Required: Workflow execution config + name: string # Required: Workflow CR name + schema: # Optional: Developer-provided values + # Structure defined by Workflow's schema status: - # Release status tracking + # Execution Status conditions: # Standard Kubernetes conditions - type: string - status: enum # "True" | "False" | "Unknown" + status: enum reason: string message: string lastTransitionTime: string + + # Build Output + imageStatus: # Optional: Built image information + image: string # Fully qualified image name + + # Execution Reference + runReference: # Optional: Reference to actual workflow run + name: string # Workflow run name in build plane + namespace: string # Workflow run namespace in build plane ``` -### DeployableArtifact CRD Schema +## Runtime Resources + +OpenChoreo uses ComponentDeployment for environment-specific configuration and Release for managing deployed resources across all component types. + +### ComponentDeployment CRD Schema ```yaml apiVersion: openchoreo.dev/v1alpha1 -kind: DeployableArtifact +kind: ComponentDeployment metadata: - name: string # Required: DeployableArtifact name - namespace: string # Required: Project namespace + name: string # Required: ComponentDeployment name + namespace: string # Required: Organization 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 + # Owner Reference + owner: # Required: Component reference + projectName: string # Required: Project name + componentName: string # Required: Component name + + # Environment + environment: string # Required: Target environment name + + # Parameter Overrides + overrides: # Optional: Environment-specific parameter overrides + # Structure matches ComponentType's envOverrides schema + # Merged with Component.spec.parameters + + # Trait Overrides + traitOverrides: # Optional: Environment-specific trait overrides + "{instanceName}": # Keyed by trait instanceName + # Structure matches Trait's envOverrides schema + + # Configuration Overrides + configurationOverrides: # Optional: Workload configuration overrides + env: # Environment variable overrides + - name: string + value: string + files: # File configuration overrides + - name: string + value: string status: - # Artifact status conditions: # Standard Kubernetes conditions - type: string - status: enum # "True" | "False" | "Unknown" + status: enum reason: string message: string lastTransitionTime: string observedGeneration: integer ``` -### Endpoint CRD Schema +### Release CRD Schema ```yaml apiVersion: openchoreo.dev/v1alpha1 -kind: Endpoint +kind: Release metadata: - name: string # Required: Endpoint name - namespace: string # Required: Project namespace + name: string # Required: Release name + namespace: string # Required: Organization 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 -``` + # Owner Reference + owner: # Required: Component reference + projectName: string # Required: Project name + componentName: string # Required: Component name -## Configuration Management + # Environment + environmentName: string # Required: Target environment (minLength: 1) -### ConfigurationGroup CRD Schema + # Resources + resources: # Optional: Kubernetes resources to deploy + - id: string # Required: Resource identifier + object: # Required: Complete Kubernetes resource + # ... Kubernetes resource YAML -```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: {}) + # Watch Configuration + interval: string # Optional: Watch interval (default: 5m) + # Pattern: ^([0-9]+(\.[0-9]+)?(ms|s|m|h))+$ + progressingInterval: string # Optional: Interval when progressing (default: 10s) status: + # Resource Status + resources: # List of deployed resources + - id: string # Resource identifier + group: string # API group + version: string # API version + kind: string # Resource kind + name: string # Resource name in data plane + namespace: string # Resource namespace in data plane + status: # Resource status from data plane + # ... Resource-specific status + healthStatus: enum # "Unknown" | "Progressing" | "Healthy" | "Suspended" | "Degraded" + lastObservedTime: string # Last observation timestamp + + # Release Status conditions: # Standard Kubernetes conditions - type: string - status: enum + status: enum # "True" | "False" | "Unknown" reason: string message: string lastTransitionTime: string @@ -824,6 +574,10 @@ status.conditions[*].message: status.observedGeneration: minimum: 0 type: integer (int64) + +# ComponentType validation +componentType: + pattern: "^(deployment|statefulset|cronjob|job)/[a-z0-9]([-a-z0-9]*[a-z0-9])?$" ``` ## Short Names and Categories @@ -831,42 +585,29 @@ status.observedGeneration: 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 +# Platform Resources +kubectl get org,orgs # Organization +kubectl get proj,projs # Project +kubectl get env,envs # Environment +kubectl get dp,dps # DataPlane +kubectl get deppipe,deppipes # DeploymentPipeline + +# Application Resources +kubectl get comp,comps # Component +kubectl get ct,cts # ComponentType +kubectl get wf # Workflow +kubectl get wfr # WorkflowRun + +# Runtime Resources +kubectl get compdeployment,compdeployments # ComponentDeployment +kubectl get release # Release ``` --- ## Schema Updates -This schema reference reflects the actual OpenChoreo v0.2.0 CRD definitions. For the latest schema definitions, see: +This schema reference reflects OpenChoreo's v0.4.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) +- **Resource Reference Guide**: [Complete Resource Guide](https://github.com/openchoreo/openchoreo/blob/main/docs/resource-kind-reference-guide.md) \ No newline at end of file