diff --git a/docs/concepts/developer-abstractions.md b/docs/concepts/developer-abstractions.md index 7e0c6f8..115965d 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..6c53076 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. diff --git a/docs/concepts/resource-relationships.md b/docs/concepts/resource-relationships.md index 2d8d93f..6ea16cb 100644 --- a/docs/concepts/resource-relationships.md +++ b/docs/concepts/resource-relationships.md @@ -31,78 +31,74 @@ Within an organization, **Projects** form the next level of ownership for applic Components, establishing team boundaries and application domains. This ownership relationship means that components cannot exist without a parent project, and deleting a project removes all its components. -The project ownership boundary also defines the scope for internal communication. Components within the same project -can reference each other directly and communicate without crossing security boundaries. This locality enables teams to +The project ownership boundary also defines the scope for internal communication. Components within the same project +can reference each other directly and communicate without crossing security boundaries. This locality enables teams to work efficiently within their domain while maintaining isolation from other projects. -### Component and Runtime Resources +### ComponentType -**Components** own the runtime resources that result from their deployment. When a component deploys, it generates -Builds and produces Releases. These resources maintain a clear ownership chain back to the component, enabling -lifecycle management and garbage collection. +**ComponentTypes** define platform-level templates that govern how components are deployed. Each ComponentType +specifies a workload type (deployment, statefulset, cronjob, or job) and provides a schema for configurable +parameters. Platform engineers create ComponentTypes that encode organizational policies, resource templates, and +operational best practices. -This ownership relationship ensures that runtime resources are properly cleaned up when components are removed. It also -provides clear attribution for resource usage, cost allocation, and audit trails. Platform operators can trace any -running workload back to its originating component and project. +ComponentTypes serve as the platform's contract for component deployment. They define what developers can configure +through parameter schemas, what resources will be created through resource templates, and which workflows are allowed +for building components. By centralizing these definitions in ComponentTypes, platform teams ensure consistency across +all applications while maintaining control over infrastructure patterns. -## Class and Binding Relationships +### Component to ComponentType -OpenChoreo implements the Kubernetes Class pattern that enables platform standardization while allowing -application-specific customization. This system separates platform governance from developer flexibility through -multiple layers of configuration. +**Components** reference a ComponentType using the format `{workloadType}/{componentTypeName}`. This relationship +establishes which template governs the component's deployment. The component provides parameter values that conform to +the schema defined in the ComponentType, and these parameters are validated automatically. -### Platform Classes +The component-to-ComponentType relationship is fundamental to OpenChoreo's governance model. Components cannot be +created without referencing a valid ComponentType, ensuring all deployments follow platform standards. This +relationship also determines which resource templates will be used to generate the actual Kubernetes resources. -**Classes** define platform-level abstractions that establish organizational standards. ServiceClass, -WebApplicationClass, and ScheduledTaskClass provide platform capabilities for different workload types. These classes -are created by platform engineers and encode organizational policies, security requirements, and operational best -practices. +### Trait Composition -Classes serve as the platform's contract for how applications should be deployed. They define standard resource limits, -security policies, network configurations, and operational parameters. By centralizing these definitions in classes, -platform teams ensure consistency across all applications while maintaining a single point of control for platform-wide -changes. +**Traits** attach additional capabilities to components through composition. Each component can instantiate multiple +traits, such as persistent storage, caching, or monitoring. Traits use the same schema-driven approach as +ComponentTypes, with parameters that can be overridden per environment through ComponentDeployment resources. -### Binding Instantiation +Traits maintain an independent lifecycle from components but are applied together during deployment. This separation +enables platform engineers to define reusable capabilities that can be composed into different component types. The +trait relationship provides flexibility while maintaining governance through schema validation. -**Bindings** create concrete instances of classes for specific environments. A ServiceBinding references a ServiceClass -but can override certain parameters for its target environment. This relationship allows the same class to be used -across different environments with appropriate customization. +### Workflow Integration -The binding relationship is not just a simple override mechanism. Bindings can only modify parameters that the class -explicitly allows, ensuring that security policies and governance rules cannot be circumvented. This controlled -flexibility enables environment-specific optimization while maintaining platform standards. +**Workflows** define build and automation templates that components can reference through their workflow configuration. +ComponentTypes can restrict which workflows are allowed, ensuring components use appropriate build strategies. This +relationship between components, ComponentTypes, and Workflows enables platform teams to enforce build standards and +security policies. +When a component references a Workflow, it provides schema values that configure the workflow execution. The Workflow +template uses these values along with platform-controlled parameters to generate the actual CI/CD pipeline. This +separation enables developers to trigger builds with simple configuration while platform engineers maintain control +over build infrastructure and security. -### Component to Build +### Component to WorkflowRun -Components define build specifications that result in **Build** resources. This relationship captures how source code -should be transformed into container images. The component maintains the build configuration while builds represent -individual execution instances. +Components trigger **WorkflowRuns** through their workflow configuration to build container images. Each WorkflowRun +represents an execution instance of a Workflow template with specific parameter values. WorkflowRuns maintain a +relationship back to their originating component and the specific commit that triggered them. -Each build maintains a relationship back to its originating component and the specific commit or tag that triggered it. -This relationship provides complete traceability from running containers back to source code, essential for debugging -and compliance. +This relationship provides complete traceability from running containers back to source code. Platform operators can +trace any container image to the WorkflowRun that built it, which links to the component and ultimately to the source +repository and commit. This traceability is essential for debugging, compliance, and security auditing. -### Workload and Binding Creation +### ComponentDeployment and Release -When developers create a Service, WebApplication, or ScheduledTask (the claim), along with a Workload specification, -the platform creates the appropriate Binding. The Binding combines: -- The claim (Service/WebApplication/ScheduledTask) that references a Class -- The Workload that defines the runtime requirements -- The Environment where it should be deployed +When a component deploys to an environment, it creates **ComponentDeployment** resources that can override parameters +from the ComponentType on a per-environment basis. These deployments generate **Releases** that contain the final +Kubernetes manifests rendered from ComponentType templates combined with component parameters, trait configurations, +and environment overrides. -This relationship ensures that the platform standards from the Class are applied while respecting the application's -runtime requirements from the Workload. - -### Binding to Release - -Bindings generate Releases that contain the actual Kubernetes resources to be deployed. The Release combines the Class -configuration, Workload specifications, and environment-specific settings into concrete Kubernetes manifests that are -applied to the target DataPlane. - -This relationship chain from Component → Build → Claim+Workload → Binding → Release ensures complete traceability -and proper lifecycle management throughout the application delivery process. +This relationship chain from Component → ComponentType → ComponentDeployment → Release ensures complete governance +while enabling environment-specific customization. The Release combines all these layers into concrete Kubernetes +resources that are applied to the target DataPlane. ## Network Relationships @@ -139,7 +135,7 @@ These relationships ensure consistent progression while maintaining appropriate These relationships create a directed graph of environment progression, potentially with multiple paths for different scenarios. -Pipeline relationships include more than just ordering. They define approval requirements and testing gates. These +Pipeline relationships include more than just ordering. They define approval requirements and testing gates. These relationships ensure that applications follow organizational processes while enabling automation where appropriate. @@ -157,13 +153,12 @@ maintains consistency during resource creation. ### Update Propagation -When resources are updated, changes propagate through relationships to dependent resources. Updating a class triggers -reconciliation of all bindings that reference it. These relationships ensure that changes are consistently applied -throughout the system. +When resources are updated, changes propagate through relationships to dependent resources. Updating a ComponentType +triggers reconciliation of all components that reference it, regenerating their deployments and releases with the new +template. These relationships ensure that changes are consistently applied throughout the system. ### Deletion Cascades Resource relationships define deletion behavior. When a project is deleted, all its components are removed. When a -component is deleted, its builds and deployments are cleaned up. These cascading relationships ensure that resources are -properly cleaned up without leaving orphaned objects. - +component is deleted, its WorkflowRuns, ComponentDeployments, and Releases are cleaned up. These cascading +relationships ensure that resources are properly cleaned up without leaving orphaned objects. diff --git a/docs/reference/api/application/build.md b/docs/reference/api/application/build.md index 9b3cbc3..257cf7a 100644 --- a/docs/reference/api/application/build.md +++ b/docs/reference/api/application/build.md @@ -4,6 +4,11 @@ title: Build API Reference # Build +:::warning Deprecated +The Build resource is deprecated as of OpenChoreo v0.4.0 and will be removed in a future release. +Use [WorkflowRun](workflowrun.md) in combination with [Workflow](../platform/workflow.md) for a more flexible and powerful workflow execution system. +::: + A Build represents a build job in OpenChoreo that transforms source code into a container image. It defines the source repository, revision, and build template to use for creating workloads. Upon successful completion, a Build creates a Workload resource containing the built container image. diff --git a/docs/reference/api/application/workflowrun.md b/docs/reference/api/application/workflowrun.md new file mode 100644 index 0000000..84531ea --- /dev/null +++ b/docs/reference/api/application/workflowrun.md @@ -0,0 +1,229 @@ +--- +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. + +:::note +WorkflowRuns currently support Argo Workflow-based workflows only. +::: + +## API Version + +`openchoreo.dev/v1alpha1` + +## Resource Definition + +### Metadata + +WorkflowRuns are namespace-scoped resources that must be created within an Organization's namespace. + +```yaml +apiVersion: openchoreo.dev/v1alpha1 +kind: WorkflowRun +metadata: + name: + namespace: # Organization namespace +``` + +### Spec Fields + +| Field | Type | Required | Default | Description | +|------------|-----------------------------------|----------|---------|--------------------------------------------------------------------------------| +| `owner` | [WorkflowOwner](#workflowowner) | No | - | Optional owner information identifying the Component that triggered this run | +| `workflow` | [WorkflowConfig](#workflowconfig) | Yes | - | Workflow configuration referencing the Workflow CR and providing schema values | + +### WorkflowOwner + +Owner information is optional and used for component-bound workflows to establish the relationship between builds +and components. + +| Field | Type | Required | Default | Description | +|-----------------|--------|----------|---------|---------------------------------------| +| `projectName` | string | Yes | - | Name of the project (min length: 1) | +| `componentName` | string | Yes | - | Name of the component (min length: 1) | + +### WorkflowConfig + +| Field | Type | Required | Default | Description | +|----------|--------|----------|---------|-----------------------------------------------------------------------------------| +| `name` | string | Yes | - | Name of the Workflow CR to use for this execution (min length: 1) | +| `schema` | object | No | - | Developer-provided values conforming to the schema defined in the Workflow CR | + +The `schema` field contains nested configuration that matches the schema structure defined in the referenced Workflow. + +### Status Fields + +| Field | Type | Default | Description | +|------------------|---------------------------------------------|---------|-------------------------------------------------------------| +| `conditions` | []Condition | [] | Standard Kubernetes conditions tracking execution state | +| `imageStatus` | [WorkflowImage](#workflowimage) | - | Information about the built image (for build workflows) | +| `runReference` | [WorkflowRunReference](#workflowrunreference) | - | Reference to the workflow execution resource in build plane | + +#### WorkflowImage + +| Field | Type | Default | Description | +|---------|--------|---------|-----------------------------------------------------------------------| +| `image` | string | "" | Fully qualified image name (e.g., registry.example.com/myapp:v1.0.0) | + +#### WorkflowRunReference + +| Field | Type | Default | Description | +|-------------|--------|---------|----------------------------------------------------------------| +| `name` | string | "" | Name of the workflow run resource in the target cluster | +| `namespace` | string | "" | Namespace of the workflow run resource in the target cluster | + +#### Condition Types + +Common condition types for WorkflowRun resources: + +- `Ready` - Indicates if the workflow run has completed successfully +- `Running` - Indicates if the workflow is currently executing +- `Failed` - Indicates if the workflow execution failed + +## Examples + +### Docker Build WorkflowRun + +```yaml +apiVersion: openchoreo.dev/v1alpha1 +kind: WorkflowRun +metadata: + name: customer-service-build-1 + namespace: default +spec: + owner: + projectName: my-project + componentName: customer-service + workflow: + name: docker + schema: + repository: + url: https://github.com/myorg/customer-service + revision: + branch: main + commit: abc123 + appPath: . + secretRef: github-credentials + docker: + context: . + filePath: ./Dockerfile +``` + +### Google Cloud Buildpacks WorkflowRun + +```yaml +apiVersion: openchoreo.dev/v1alpha1 +kind: WorkflowRun +metadata: + name: frontend-build-v2 + namespace: default +spec: + owner: + projectName: ecommerce + componentName: frontend-app + workflow: + name: google-cloud-buildpacks + schema: + repository: + url: https://github.com/myorg/frontend-app + revision: + branch: develop + commit: def456 + appPath: ./webapp + secretRef: reading-list-repo-credentials-dev + version: 2 + testMode: unit + resources: + cpuCores: 2 + memoryGb: 4 + timeout: "45m" + cache: + enabled: true + paths: + - /root/.cache + - /workspace/node_modules + limits: + maxRetries: 2 + maxDurationMinutes: 60 +``` + +### Standalone WorkflowRun (No Component Owner) + +```yaml +apiVersion: openchoreo.dev/v1alpha1 +kind: WorkflowRun +metadata: + name: integration-test-run + namespace: default +spec: + workflow: + name: integration-tests + schema: + repository: + url: https://github.com/myorg/test-suite + branch: main + secretRef: test-repo-credentials + testSuite: smoke + environment: staging +``` + +### WorkflowRun with Minimal Schema + +```yaml +apiVersion: openchoreo.dev/v1alpha1 +kind: WorkflowRun +metadata: + name: simple-build + namespace: default +spec: + owner: + projectName: demo + componentName: hello-world + workflow: + name: docker + schema: + repository: + url: https://github.com/myorg/hello-world + secretRef: github-token + # Uses default values for other fields from Workflow schema +``` + +## Status Example + +After execution, a WorkflowRun status might look like: + +```yaml +status: + conditions: + - type: Ready + status: "True" + lastTransitionTime: "2024-01-15T10:30:00Z" + reason: WorkflowSucceeded + message: Workflow execution completed successfully + imageStatus: + image: gcr.io/openchoreo-dev/images/my-project-customer-service-image:v1 + runReference: + name: customer-service-build-1-abc12 + namespace: openchoreo-ci-default +``` + +## Annotations + +WorkflowRuns support the following annotations: + +| Annotation | Description | +|-------------------------------|------------------------------------------| +| `openchoreo.dev/display-name` | Human-readable name for UI display | +| `openchoreo.dev/description` | Detailed description of the workflow run | + +## Related Resources + +- [Workflow](../platform/workflow.md) - Template definitions for workflow execution +- [Component](./component.md) - Components that can trigger WorkflowRuns +- [ComponentType](../platform/componenttype.md) - Can restrict allowed workflows diff --git a/docs/reference/api/platform/workflow.md b/docs/reference/api/platform/workflow.md new file mode 100644 index 0000000..e695d82 --- /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 diff --git a/versioned_docs/version-v0.4.x/concepts/developer-abstractions.md b/versioned_docs/version-v0.4.x/concepts/developer-abstractions.md index 7e0c6f8..115965d 100644 --- a/versioned_docs/version-v0.4.x/concepts/developer-abstractions.md +++ b/versioned_docs/version-v0.4.x/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/versioned_docs/version-v0.4.x/concepts/platform-abstractions.md b/versioned_docs/version-v0.4.x/concepts/platform-abstractions.md index 91a658c..6c53076 100644 --- a/versioned_docs/version-v0.4.x/concepts/platform-abstractions.md +++ b/versioned_docs/version-v0.4.x/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. diff --git a/versioned_docs/version-v0.4.x/concepts/resource-relationships.md b/versioned_docs/version-v0.4.x/concepts/resource-relationships.md index 2d8d93f..6ea16cb 100644 --- a/versioned_docs/version-v0.4.x/concepts/resource-relationships.md +++ b/versioned_docs/version-v0.4.x/concepts/resource-relationships.md @@ -31,78 +31,74 @@ Within an organization, **Projects** form the next level of ownership for applic Components, establishing team boundaries and application domains. This ownership relationship means that components cannot exist without a parent project, and deleting a project removes all its components. -The project ownership boundary also defines the scope for internal communication. Components within the same project -can reference each other directly and communicate without crossing security boundaries. This locality enables teams to +The project ownership boundary also defines the scope for internal communication. Components within the same project +can reference each other directly and communicate without crossing security boundaries. This locality enables teams to work efficiently within their domain while maintaining isolation from other projects. -### Component and Runtime Resources +### ComponentType -**Components** own the runtime resources that result from their deployment. When a component deploys, it generates -Builds and produces Releases. These resources maintain a clear ownership chain back to the component, enabling -lifecycle management and garbage collection. +**ComponentTypes** define platform-level templates that govern how components are deployed. Each ComponentType +specifies a workload type (deployment, statefulset, cronjob, or job) and provides a schema for configurable +parameters. Platform engineers create ComponentTypes that encode organizational policies, resource templates, and +operational best practices. -This ownership relationship ensures that runtime resources are properly cleaned up when components are removed. It also -provides clear attribution for resource usage, cost allocation, and audit trails. Platform operators can trace any -running workload back to its originating component and project. +ComponentTypes serve as the platform's contract for component deployment. They define what developers can configure +through parameter schemas, what resources will be created through resource templates, and which workflows are allowed +for building components. By centralizing these definitions in ComponentTypes, platform teams ensure consistency across +all applications while maintaining control over infrastructure patterns. -## Class and Binding Relationships +### Component to ComponentType -OpenChoreo implements the Kubernetes Class pattern that enables platform standardization while allowing -application-specific customization. This system separates platform governance from developer flexibility through -multiple layers of configuration. +**Components** reference a ComponentType using the format `{workloadType}/{componentTypeName}`. This relationship +establishes which template governs the component's deployment. The component provides parameter values that conform to +the schema defined in the ComponentType, and these parameters are validated automatically. -### Platform Classes +The component-to-ComponentType relationship is fundamental to OpenChoreo's governance model. Components cannot be +created without referencing a valid ComponentType, ensuring all deployments follow platform standards. This +relationship also determines which resource templates will be used to generate the actual Kubernetes resources. -**Classes** define platform-level abstractions that establish organizational standards. ServiceClass, -WebApplicationClass, and ScheduledTaskClass provide platform capabilities for different workload types. These classes -are created by platform engineers and encode organizational policies, security requirements, and operational best -practices. +### Trait Composition -Classes serve as the platform's contract for how applications should be deployed. They define standard resource limits, -security policies, network configurations, and operational parameters. By centralizing these definitions in classes, -platform teams ensure consistency across all applications while maintaining a single point of control for platform-wide -changes. +**Traits** attach additional capabilities to components through composition. Each component can instantiate multiple +traits, such as persistent storage, caching, or monitoring. Traits use the same schema-driven approach as +ComponentTypes, with parameters that can be overridden per environment through ComponentDeployment resources. -### Binding Instantiation +Traits maintain an independent lifecycle from components but are applied together during deployment. This separation +enables platform engineers to define reusable capabilities that can be composed into different component types. The +trait relationship provides flexibility while maintaining governance through schema validation. -**Bindings** create concrete instances of classes for specific environments. A ServiceBinding references a ServiceClass -but can override certain parameters for its target environment. This relationship allows the same class to be used -across different environments with appropriate customization. +### Workflow Integration -The binding relationship is not just a simple override mechanism. Bindings can only modify parameters that the class -explicitly allows, ensuring that security policies and governance rules cannot be circumvented. This controlled -flexibility enables environment-specific optimization while maintaining platform standards. +**Workflows** define build and automation templates that components can reference through their workflow configuration. +ComponentTypes can restrict which workflows are allowed, ensuring components use appropriate build strategies. This +relationship between components, ComponentTypes, and Workflows enables platform teams to enforce build standards and +security policies. +When a component references a Workflow, it provides schema values that configure the workflow execution. The Workflow +template uses these values along with platform-controlled parameters to generate the actual CI/CD pipeline. This +separation enables developers to trigger builds with simple configuration while platform engineers maintain control +over build infrastructure and security. -### Component to Build +### Component to WorkflowRun -Components define build specifications that result in **Build** resources. This relationship captures how source code -should be transformed into container images. The component maintains the build configuration while builds represent -individual execution instances. +Components trigger **WorkflowRuns** through their workflow configuration to build container images. Each WorkflowRun +represents an execution instance of a Workflow template with specific parameter values. WorkflowRuns maintain a +relationship back to their originating component and the specific commit that triggered them. -Each build maintains a relationship back to its originating component and the specific commit or tag that triggered it. -This relationship provides complete traceability from running containers back to source code, essential for debugging -and compliance. +This relationship provides complete traceability from running containers back to source code. Platform operators can +trace any container image to the WorkflowRun that built it, which links to the component and ultimately to the source +repository and commit. This traceability is essential for debugging, compliance, and security auditing. -### Workload and Binding Creation +### ComponentDeployment and Release -When developers create a Service, WebApplication, or ScheduledTask (the claim), along with a Workload specification, -the platform creates the appropriate Binding. The Binding combines: -- The claim (Service/WebApplication/ScheduledTask) that references a Class -- The Workload that defines the runtime requirements -- The Environment where it should be deployed +When a component deploys to an environment, it creates **ComponentDeployment** resources that can override parameters +from the ComponentType on a per-environment basis. These deployments generate **Releases** that contain the final +Kubernetes manifests rendered from ComponentType templates combined with component parameters, trait configurations, +and environment overrides. -This relationship ensures that the platform standards from the Class are applied while respecting the application's -runtime requirements from the Workload. - -### Binding to Release - -Bindings generate Releases that contain the actual Kubernetes resources to be deployed. The Release combines the Class -configuration, Workload specifications, and environment-specific settings into concrete Kubernetes manifests that are -applied to the target DataPlane. - -This relationship chain from Component → Build → Claim+Workload → Binding → Release ensures complete traceability -and proper lifecycle management throughout the application delivery process. +This relationship chain from Component → ComponentType → ComponentDeployment → Release ensures complete governance +while enabling environment-specific customization. The Release combines all these layers into concrete Kubernetes +resources that are applied to the target DataPlane. ## Network Relationships @@ -139,7 +135,7 @@ These relationships ensure consistent progression while maintaining appropriate These relationships create a directed graph of environment progression, potentially with multiple paths for different scenarios. -Pipeline relationships include more than just ordering. They define approval requirements and testing gates. These +Pipeline relationships include more than just ordering. They define approval requirements and testing gates. These relationships ensure that applications follow organizational processes while enabling automation where appropriate. @@ -157,13 +153,12 @@ maintains consistency during resource creation. ### Update Propagation -When resources are updated, changes propagate through relationships to dependent resources. Updating a class triggers -reconciliation of all bindings that reference it. These relationships ensure that changes are consistently applied -throughout the system. +When resources are updated, changes propagate through relationships to dependent resources. Updating a ComponentType +triggers reconciliation of all components that reference it, regenerating their deployments and releases with the new +template. These relationships ensure that changes are consistently applied throughout the system. ### Deletion Cascades Resource relationships define deletion behavior. When a project is deleted, all its components are removed. When a -component is deleted, its builds and deployments are cleaned up. These cascading relationships ensure that resources are -properly cleaned up without leaving orphaned objects. - +component is deleted, its WorkflowRuns, ComponentDeployments, and Releases are cleaned up. These cascading +relationships ensure that resources are properly cleaned up without leaving orphaned objects. diff --git a/versioned_docs/version-v0.4.x/reference/api/application/build.md b/versioned_docs/version-v0.4.x/reference/api/application/build.md index 9b3cbc3..257cf7a 100644 --- a/versioned_docs/version-v0.4.x/reference/api/application/build.md +++ b/versioned_docs/version-v0.4.x/reference/api/application/build.md @@ -4,6 +4,11 @@ title: Build API Reference # Build +:::warning Deprecated +The Build resource is deprecated as of OpenChoreo v0.4.0 and will be removed in a future release. +Use [WorkflowRun](workflowrun.md) in combination with [Workflow](../platform/workflow.md) for a more flexible and powerful workflow execution system. +::: + A Build represents a build job in OpenChoreo that transforms source code into a container image. It defines the source repository, revision, and build template to use for creating workloads. Upon successful completion, a Build creates a Workload resource containing the built container image. diff --git a/versioned_docs/version-v0.4.x/reference/api/application/workflowrun.md b/versioned_docs/version-v0.4.x/reference/api/application/workflowrun.md new file mode 100644 index 0000000..84531ea --- /dev/null +++ b/versioned_docs/version-v0.4.x/reference/api/application/workflowrun.md @@ -0,0 +1,229 @@ +--- +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. + +:::note +WorkflowRuns currently support Argo Workflow-based workflows only. +::: + +## API Version + +`openchoreo.dev/v1alpha1` + +## Resource Definition + +### Metadata + +WorkflowRuns are namespace-scoped resources that must be created within an Organization's namespace. + +```yaml +apiVersion: openchoreo.dev/v1alpha1 +kind: WorkflowRun +metadata: + name: + namespace: # Organization namespace +``` + +### Spec Fields + +| Field | Type | Required | Default | Description | +|------------|-----------------------------------|----------|---------|--------------------------------------------------------------------------------| +| `owner` | [WorkflowOwner](#workflowowner) | No | - | Optional owner information identifying the Component that triggered this run | +| `workflow` | [WorkflowConfig](#workflowconfig) | Yes | - | Workflow configuration referencing the Workflow CR and providing schema values | + +### WorkflowOwner + +Owner information is optional and used for component-bound workflows to establish the relationship between builds +and components. + +| Field | Type | Required | Default | Description | +|-----------------|--------|----------|---------|---------------------------------------| +| `projectName` | string | Yes | - | Name of the project (min length: 1) | +| `componentName` | string | Yes | - | Name of the component (min length: 1) | + +### WorkflowConfig + +| Field | Type | Required | Default | Description | +|----------|--------|----------|---------|-----------------------------------------------------------------------------------| +| `name` | string | Yes | - | Name of the Workflow CR to use for this execution (min length: 1) | +| `schema` | object | No | - | Developer-provided values conforming to the schema defined in the Workflow CR | + +The `schema` field contains nested configuration that matches the schema structure defined in the referenced Workflow. + +### Status Fields + +| Field | Type | Default | Description | +|------------------|---------------------------------------------|---------|-------------------------------------------------------------| +| `conditions` | []Condition | [] | Standard Kubernetes conditions tracking execution state | +| `imageStatus` | [WorkflowImage](#workflowimage) | - | Information about the built image (for build workflows) | +| `runReference` | [WorkflowRunReference](#workflowrunreference) | - | Reference to the workflow execution resource in build plane | + +#### WorkflowImage + +| Field | Type | Default | Description | +|---------|--------|---------|-----------------------------------------------------------------------| +| `image` | string | "" | Fully qualified image name (e.g., registry.example.com/myapp:v1.0.0) | + +#### WorkflowRunReference + +| Field | Type | Default | Description | +|-------------|--------|---------|----------------------------------------------------------------| +| `name` | string | "" | Name of the workflow run resource in the target cluster | +| `namespace` | string | "" | Namespace of the workflow run resource in the target cluster | + +#### Condition Types + +Common condition types for WorkflowRun resources: + +- `Ready` - Indicates if the workflow run has completed successfully +- `Running` - Indicates if the workflow is currently executing +- `Failed` - Indicates if the workflow execution failed + +## Examples + +### Docker Build WorkflowRun + +```yaml +apiVersion: openchoreo.dev/v1alpha1 +kind: WorkflowRun +metadata: + name: customer-service-build-1 + namespace: default +spec: + owner: + projectName: my-project + componentName: customer-service + workflow: + name: docker + schema: + repository: + url: https://github.com/myorg/customer-service + revision: + branch: main + commit: abc123 + appPath: . + secretRef: github-credentials + docker: + context: . + filePath: ./Dockerfile +``` + +### Google Cloud Buildpacks WorkflowRun + +```yaml +apiVersion: openchoreo.dev/v1alpha1 +kind: WorkflowRun +metadata: + name: frontend-build-v2 + namespace: default +spec: + owner: + projectName: ecommerce + componentName: frontend-app + workflow: + name: google-cloud-buildpacks + schema: + repository: + url: https://github.com/myorg/frontend-app + revision: + branch: develop + commit: def456 + appPath: ./webapp + secretRef: reading-list-repo-credentials-dev + version: 2 + testMode: unit + resources: + cpuCores: 2 + memoryGb: 4 + timeout: "45m" + cache: + enabled: true + paths: + - /root/.cache + - /workspace/node_modules + limits: + maxRetries: 2 + maxDurationMinutes: 60 +``` + +### Standalone WorkflowRun (No Component Owner) + +```yaml +apiVersion: openchoreo.dev/v1alpha1 +kind: WorkflowRun +metadata: + name: integration-test-run + namespace: default +spec: + workflow: + name: integration-tests + schema: + repository: + url: https://github.com/myorg/test-suite + branch: main + secretRef: test-repo-credentials + testSuite: smoke + environment: staging +``` + +### WorkflowRun with Minimal Schema + +```yaml +apiVersion: openchoreo.dev/v1alpha1 +kind: WorkflowRun +metadata: + name: simple-build + namespace: default +spec: + owner: + projectName: demo + componentName: hello-world + workflow: + name: docker + schema: + repository: + url: https://github.com/myorg/hello-world + secretRef: github-token + # Uses default values for other fields from Workflow schema +``` + +## Status Example + +After execution, a WorkflowRun status might look like: + +```yaml +status: + conditions: + - type: Ready + status: "True" + lastTransitionTime: "2024-01-15T10:30:00Z" + reason: WorkflowSucceeded + message: Workflow execution completed successfully + imageStatus: + image: gcr.io/openchoreo-dev/images/my-project-customer-service-image:v1 + runReference: + name: customer-service-build-1-abc12 + namespace: openchoreo-ci-default +``` + +## Annotations + +WorkflowRuns support the following annotations: + +| Annotation | Description | +|-------------------------------|------------------------------------------| +| `openchoreo.dev/display-name` | Human-readable name for UI display | +| `openchoreo.dev/description` | Detailed description of the workflow run | + +## Related Resources + +- [Workflow](../platform/workflow.md) - Template definitions for workflow execution +- [Component](./component.md) - Components that can trigger WorkflowRuns +- [ComponentType](../platform/componenttype.md) - Can restrict allowed workflows diff --git a/versioned_docs/version-v0.4.x/reference/api/platform/workflow.md b/versioned_docs/version-v0.4.x/reference/api/platform/workflow.md new file mode 100644 index 0000000..e695d82 --- /dev/null +++ b/versioned_docs/version-v0.4.x/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