diff --git a/docs/concepts/developer-abstractions.md b/docs/concepts/developer-abstractions.md index 115965dd..6b7b72fb 100644 --- a/docs/concepts/developer-abstractions.md +++ b/docs/concepts/developer-abstractions.md @@ -95,28 +95,39 @@ 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. -## 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. - -Each WorkflowRun captures two essential pieces of information: - -**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. - -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. +## ComponentWorkflowRun + +A **ComponentWorkflowRun** represents a runtime execution instance of a ComponentWorkflow - a specialized workflow type +designed specifically for building components. While ComponentWorkflows define the build template and schema, +ComponentWorkflowRuns represent actual build executions with specific parameter values and ownership tracking. + +ComponentWorkflowRuns bridge the gap between developer intent and CI/CD execution for component builds. Developers +create ComponentWorkflowRun resources to trigger builds, providing component ownership information, repository details, +and build parameters. The platform handles all the complexity of rendering the final workflow specification, +synchronizing secrets, and managing execution in the build plane. + +Each ComponentWorkflowRun captures three essential pieces of information: + +**Ownership Tracking** links the build execution to a specific component and project. This enables traceability, +allowing the platform to track which builds belong to which components and maintain build history per component. The +ownership information includes both project name and component name, ensuring proper audit trails and enabling +component-specific build operations. + +**System Parameters** provide the structured repository information required for build-specific platform features. These +parameters follow a fixed structure with `repository.url`, `repository.revision.branch`, `repository.revision.commit`, +and `repository.appPath` fields. This predictable structure enables the platform to support auto-builds triggered by +webhooks, manual build actions in the UI, build traceability linking images to source commits, and monorepo support by +identifying specific application paths within repositories. + +**Developer Parameters** provide values for the flexible configuration schema defined by the platform engineer in the +ComponentWorkflow. These might include build version numbers, test modes, resource allocations, timeout settings, +caching configurations, and retry limits. The schema validation ensures type correctness and constraint satisfaction +automatically. + +This abstraction provides a specialized interface for component builds, where developers interact with curated schemas +rather than complex CI/CD pipeline definitions. The separation of concerns allows platform engineers to control build +implementation and security policies through ComponentWorkflow templates while developers manage repository information +and build parameters through ComponentWorkflowRun instances. ComponentWorkflowRuns can be created manually for ad-hoc +builds or automatically by platform controllers in response to code changes, supporting both interactive development and +fully automated CI/CD pipelines while maintaining consistent execution patterns and governance specifically tailored for +component build operations. diff --git a/docs/concepts/platform-abstractions.md b/docs/concepts/platform-abstractions.md index 6c53076e..f3b56a83 100644 --- a/docs/concepts/platform-abstractions.md +++ b/docs/concepts/platform-abstractions.md @@ -165,42 +165,55 @@ application patterns. Platform engineers create ComponentTypes that encode organ 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. +## ComponentWorkflow + +A **ComponentWorkflow** is a platform engineer-defined template specifically designed for building components in +OpenChoreo. Unlike generic automation workflows, ComponentWorkflows enforce a structured schema for repository +information while providing flexibility for additional build configuration, enabling powerful build-specific platform +features like auto-builds, webhooks, and build traceability. + +ComponentWorkflows address the unique requirements of component builds that generic workflows cannot solve. Component +builds need to power manual build actions in the UI, integrate with Git webhooks for auto-builds, maintain build +traceability linking container images to source commits, and support monorepo structures by identifying specific +application paths. These features require the platform to reliably locate critical repository fields, which is only +possible with a predictable schema structure. + +Each ComponentWorkflow defines three key sections: + +**System Parameters Schema** enforces a required structured schema for repository information. This schema must follow +a specific structure with `repository.url`, `repository.revision.branch`, `repository.revision.commit`, and +`repository.appPath` fields, all of type string. Platform engineers can customize defaults, enums, and descriptions +within each field, but must maintain the field names, nesting structure, and types. This predictable structure enables +build-specific platform features to work reliably across all component workflows while still giving platform engineers +control over validation rules and default values. + +**Developer Parameters Schema** provides complete freedom for platform engineers to define additional build +configuration. This flexible schema can include any structure the platform engineer designs - build version numbers, +test modes, resource allocations, timeout settings, caching configurations, retry limits, and more. The schema supports +all types including integers, booleans, strings, arrays, and nested objects, with full validation through defaults, +minimums, maximums, and enums. This separation between required system parameters and flexible developer parameters +balances platform reliability with configuration freedom. + +**Run Template** contains the actual Kubernetes resource specification (typically an Argo Workflow) with template +variables for dynamic value injection. These expressions access context variables like `${ctx.componentWorkflowRunName}`, +`${ctx.componentName}`, `${ctx.projectName}`, and `${ctx.orgName}` for runtime information, system parameter values +through `${systemParameters.*}` for repository details, and developer parameter values through `${parameters.*}` for +custom configuration. Platform engineers can also hardcode platform-controlled parameters directly in the template, +such as builder images, registry URLs, security scanning settings, and organizational policies. + +ComponentTypes govern which ComponentWorkflows developers can use through the `allowedWorkflows` field. This enables +platform engineers to enforce build standards per component type, ensuring that web applications use approved frontend +build tools, backend services use appropriate security scanners, and different component types follow their specific +build requirements. + +Components reference ComponentWorkflows in their `workflow` field, providing the system parameters for repository +information and developer parameters for build configuration. The platform handles template rendering, secret +synchronization, and execution management in the build plane, with ComponentWorkflowRun resources tracking individual +build executions. + +The ComponentWorkflow abstraction thus provides a specialized interface for component builds that balances platform +needs with developer flexibility. Platform engineers control build implementation, security policies, and +infrastructure configurations while ensuring build-specific features work reliably. Developers get a simplified +interface for configuring builds without managing complex CI/CD pipeline definitions. The separation from generic +workflows makes clear that component builds have unique requirements deserving dedicated abstractions, while +maintaining the schema-driven approach that characterizes OpenChoreo's architecture. diff --git a/docs/reference/api/application/componentworkflowrun.md b/docs/reference/api/application/componentworkflowrun.md new file mode 100644 index 00000000..7aedc308 --- /dev/null +++ b/docs/reference/api/application/componentworkflowrun.md @@ -0,0 +1,294 @@ +--- +title: ComponentWorkflowRun API Reference +--- + +# ComponentWorkflowRun + +A ComponentWorkflowRun represents a runtime execution instance of a ComponentWorkflow - a specialized workflow type +designed specifically for building components. ComponentWorkflowRuns bridge the gap between developer intent and CI/CD +execution for component builds, providing ownership tracking, structured repository information, and flexible build +parameters. + +:::note +ComponentWorkflowRuns currently support Argo Workflow-based workflows only. +::: + +## API Version + +`openchoreo.dev/v1alpha1` + +## Resource Definition + +### Metadata + +ComponentWorkflowRuns are namespace-scoped resources that must be created within an Organization's namespace. + +```yaml +apiVersion: openchoreo.dev/v1alpha1 +kind: ComponentWorkflowRun +metadata: + name: + namespace: # Organization namespace +``` + +### Spec Fields + +| Field | Type | Required | Default | Description | +|------------|-------------------------------------------------------------|----------|---------|---------------------------------------------------------------------------------------------| +| `owner` | [ComponentWorkflowOwner](#componentworkflowowner) | Yes | - | Owner information identifying the Component and Project for this build | +| `workflow` | [ComponentWorkflowRunConfig](#componentworkflowrunconfig) | Yes | - | Workflow configuration referencing the ComponentWorkflow and providing parameter values | + +### ComponentWorkflowOwner + +Owner information links the build execution to a specific component and project, enabling traceability and build +history tracking. + +| Field | Type | Required | Default | Description | +|-----------------|--------|----------|---------|---------------------------------------| +| `projectName` | string | Yes | - | Name of the project (min length: 1) | +| `componentName` | string | Yes | - | Name of the component (min length: 1) | + +### ComponentWorkflowRunConfig + +| Field | Type | Required | Default | Description | +|--------------------|--------|----------|---------|--------------------------------------------------------------------------------------------------| +| `name` | string | Yes | - | Name of the ComponentWorkflow CR to use for this execution (min length: 1) | +| `systemParameters` | object | Yes | - | Repository information following the required structure (url, revision.branch, revision.commit, appPath) | +| `parameters` | object | No | - | Developer-provided values conforming to the flexible parameter schema defined in the ComponentWorkflow | + +#### System Parameters Structure + +System parameters must follow this required structure: + +```yaml +systemParameters: + repository: + url: string # Required: Git repository URL (must start with http:// or https://) + revision: + branch: string # Required: Git branch name + commit: string # Optional: Specific commit SHA (7-40 hex characters) + appPath: string # Required: Path to application code within repository +``` + +#### Parameters + +The `parameters` field contains flexible configuration that matches the developer parameters schema defined in the +referenced ComponentWorkflow. These values are validated against the ComponentWorkflow's parameter schema. + +### Status Fields + +| Field | Type | Default | Description | +|------------------|-------------------------------------------------------------------|---------|-------------------------------------------------------------| +| `conditions` | []Condition | [] | Standard Kubernetes conditions tracking execution state | +| `imageStatus` | [ComponentWorkflowImage](#componentworkflowimage) | - | Information about the built container image | +| `runReference` | [ComponentWorkflowRunReference](#componentworkflowrunreference) | - | Reference to the workflow execution resource in build plane | + +#### ComponentWorkflowImage + +| Field | Type | Default | Description | +|---------|--------|---------|-----------------------------------------------------------------------| +| `image` | string | "" | Fully qualified image name (e.g., registry.example.com/myapp:v1.0.0) | + +#### ComponentWorkflowRunReference + +| Field | Type | Default | Description | +|-------------|--------|---------|-----------------------------------------------------------------| +| `name` | string | "" | Name of the workflow run resource in the build plane cluster | +| `namespace` | string | "" | Namespace of the workflow run resource in the build plane cluster | + +#### Condition Types + +Common condition types for ComponentWorkflowRun 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 + +### Google Cloud Buildpacks ComponentWorkflowRun + +```yaml +apiVersion: openchoreo.dev/v1alpha1 +kind: ComponentWorkflowRun +metadata: + name: reading-list-service-build-01 + namespace: default +spec: + owner: + projectName: "default" + componentName: "reading-list-service" + + workflow: + name: google-cloud-buildpacks + + systemParameters: + repository: + url: "https://github.com/openchoreo/sample-workloads" + revision: + branch: "main" + commit: "a1b2c3d4e5f6" + appPath: "/service-go-reading-list" + + parameters: + version: 1 + testMode: "integration" + command: ["npm", "run", "build"] + args: ["--production", "--verbose"] + resources: + cpuCores: 2 + memoryGb: 4 + timeout: "45m" + cache: + enabled: true + paths: ["/root/.npm", "/root/.cache"] + limits: + maxRetries: 5 + maxDurationMinutes: 90 +``` + +### Docker Build ComponentWorkflowRun + +```yaml +apiVersion: openchoreo.dev/v1alpha1 +kind: ComponentWorkflowRun +metadata: + name: customer-service-build-1 + namespace: default +spec: + owner: + projectName: my-project + componentName: customer-service + + workflow: + name: docker + + systemParameters: + repository: + url: "https://github.com/myorg/customer-service" + revision: + branch: "main" + commit: "abc123def456" + appPath: "." + + parameters: + docker: + context: "." + filePath: "./Dockerfile" + buildArgs: ["ENV=production", "VERSION=1.0.0"] +``` + +### ComponentWorkflowRun with Latest Commit + +```yaml +apiVersion: openchoreo.dev/v1alpha1 +kind: ComponentWorkflowRun +metadata: + name: frontend-build-latest + namespace: default +spec: + owner: + projectName: ecommerce + componentName: frontend-app + + workflow: + name: google-cloud-buildpacks + + systemParameters: + repository: + url: "https://github.com/myorg/frontend-app" + revision: + branch: "develop" + # No commit specified - will use latest from branch + appPath: "./webapp" + + parameters: + version: 2 + testMode: "unit" + resources: + cpuCores: 4 + memoryGb: 8 +``` + +### Minimal ComponentWorkflowRun Using Defaults + +```yaml +apiVersion: openchoreo.dev/v1alpha1 +kind: ComponentWorkflowRun +metadata: + name: simple-build + namespace: default +spec: + owner: + projectName: demo + componentName: hello-world + + workflow: + name: docker + + systemParameters: + repository: + url: "https://github.com/myorg/hello-world" + revision: + branch: "main" + appPath: "." + # Uses default values for parameters from ComponentWorkflow schema +``` + +## Status Example + +After execution, a ComponentWorkflowRun 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/default-reading-list-service-image:v1 + runReference: + name: reading-list-service-build-01 + namespace: openchoreo-ci-default +``` + +## Build-Specific Platform Features + +The structured system parameters in ComponentWorkflowRun enable several build-specific platform features: + +### Manual Build Actions +The UI can offer actions like "build from latest commit" or "build from specific commit" by reliably locating +repository URL, branch, and commit fields. + +### Auto-Build / Webhook Integration +Automated builds triggered by Git push events use: +- `repository.url` and `repository.appPath` - To map webhook events to the correct component +- `repository.revision.commit` - To trigger builds with the correct commit SHA +- `repository.revision.branch` - To filter events by branch + +### Build Traceability +Tracking which Git repository, branch, and commit produced each container image enables: +- Debugging production issues +- Compliance and audit trails +- Rollback to specific code versions + +### Monorepo Support +The `repository.appPath` field identifies specific application paths within a repository, enabling multiple components +to be built from different paths in the same repository. + +## Annotations + +ComponentWorkflowRuns support the following annotations: + +| Annotation | Description | +|-------------------------------|--------------------------------------------------| +| `openchoreo.dev/display-name` | Human-readable name for UI display | +| `openchoreo.dev/description` | Detailed description of the component workflow run | + +## Related Resources + +- [ComponentWorkflow](../platform/componentworkflow.md) - Template definitions for component workflow execution +- [Component](./component.md) - Components that reference ComponentWorkflows +- [ComponentType](../platform/componenttype.md) - Can restrict allowed component workflows \ No newline at end of file diff --git a/docs/reference/api/application/workflowrun.md b/docs/reference/api/application/workflowrun.md index 84531ea4..92917988 100644 --- a/docs/reference/api/application/workflowrun.md +++ b/docs/reference/api/application/workflowrun.md @@ -4,6 +4,16 @@ title: WorkflowRun API Reference # WorkflowRun +:::warning Deprecated +The WorkflowRun resource is deprecated for component builds and will be removed in a future release. Use +[ComponentWorkflowRun](./componentworkflowrun.md) instead for building components. ComponentWorkflowRun provides +required ownership tracking and structured repository information needed for build-specific platform features like +auto-builds, webhooks, and build traceability. + +Generic Workflow Run resources will still be used for non-component automation tasks (Terraform, ETL pipelines, database +migrations, etc.) in the future. +::: + A WorkflowRun represents a runtime execution instance of a Workflow in OpenChoreo. While Workflows define the template and schema for what can be executed, WorkflowRuns represent actual executions with specific parameter values and context. WorkflowRuns bridge the gap between developer intent and CI/CD execution, providing a simplified interface diff --git a/docs/reference/api/platform/componentworkflow.md b/docs/reference/api/platform/componentworkflow.md new file mode 100644 index 00000000..4d657e83 --- /dev/null +++ b/docs/reference/api/platform/componentworkflow.md @@ -0,0 +1,316 @@ +--- +title: ComponentWorkflow API Reference +--- + +# ComponentWorkflow + +A ComponentWorkflow is a platform engineer-defined template specifically designed for building components in OpenChoreo. +ComponentWorkflows enforce a structured schema for repository information while providing +flexibility for additional build configuration. This enables powerful build-specific platform features like auto-builds, +webhooks, build traceability, and monorepo support. + +## API Version + +`openchoreo.dev/v1alpha1` + +## Resource Definition + +### Metadata + +ComponentWorkflows are namespace-scoped resources that must be created within an Organization's namespace. + +```yaml +apiVersion: openchoreo.dev/v1alpha1 +kind: ComponentWorkflow +metadata: + name: + namespace: # Organization namespace +``` + +### Spec Fields + +| Field | Type | Required | Default | Description | +|---------------|--------|----------|---------|----------------------------------------------------------------------------------------------| +| `schema` | object | Yes | - | Parameter schemas including required system parameters and flexible developer parameters | +| `runTemplate` | object | Yes | - | Kubernetes resource template (typically Argo Workflow) with CEL expressions for runtime evaluation | + +### Schema + +The schema field defines two distinct parameter sections: + +#### System Parameters Schema (Required) + +System parameters follow a fixed structure required for build-specific platform features. Platform engineers can +customize defaults, enums, and descriptions, but must maintain the field structure. + +**Required Structure:** + +```yaml +schema: + systemParameters: + repository: + url: 'string | description="Git repository URL"' + revision: + branch: 'string | default=main description="Git branch"' + commit: 'string | description="Commit SHA (optional)"' + appPath: 'string | default=. description="Application path"' +``` + +**Field Constraints:** +- Field names must match exactly: `url`, `revision.branch`, `revision.commit`, `appPath` +- All fields must be of type `string` +- Platform Engineers can customize: defaults, enums, descriptions, validation rules +- Platform Engineers cannot change: field names, nesting structure, or types + +#### Developer Parameters Schema (Flexible) + +Developer parameters provide complete freedom for platform engineers to define additional build configuration using +the same inline type definition syntax as ComponentType: + +``` +"type | default=value enum=val1,val2 minimum=N maximum=N" +``` + +Supported types: `string`, `integer`, `boolean`, `array`, nested objects + +**Example:** + +```yaml +schema: + parameters: + version: integer | default=1 description="Build version" + testMode: string | enum=unit,integration,none default=unit + resources: + cpuCores: integer | default=1 minimum=1 maximum=8 + memoryGb: integer | default=2 minimum=1 maximum=32 + cache: + enabled: boolean | default=true + paths: '[]string | default=["/root/.cache"]' +``` + +## CEL Variables in Run Templates + +ComponentWorkflow run templates support CEL expressions with access to: + +| Variable | Description | +|-------------------------------------|--------------------------------------------------------------| +| `${ctx.componentWorkflowRunName}` | ComponentWorkflowRun CR name (the execution instance) | +| `${ctx.componentName}` | Component name | +| `${ctx.projectName}` | Project name | +| `${ctx.orgName}` | Organization name (namespace) | +| `${ctx.timestamp}` | Unix timestamp | +| `${ctx.uuid}` | Short UUID (8 characters) | +| `${systemParameters.*}` | Repository information from system parameters | +| `${parameters.*}` | Developer-provided values from the flexible parameter schema | + +## Examples + +### Google Cloud Buildpacks ComponentWorkflow + +```yaml +apiVersion: openchoreo.dev/v1alpha1 +kind: ComponentWorkflow +metadata: + name: google-cloud-buildpacks + namespace: default + annotations: + openchoreo.dev/description: "Google Cloud Buildpacks workflow for containerized builds" +spec: + schema: + # Required system parameters with fixed structure + systemParameters: + repository: + url: 'string | description="Git repository URL for the component source code"' + revision: + branch: 'string | default=main description="Git branch to build from"' + commit: 'string | description="Specific commit SHA to build (optional, defaults to latest)"' + appPath: 'string | default=. description="Path to the application code within the repository"' + + # Flexible developer parameters + parameters: + version: integer | default=1 description="Build version number for image tagging" + testMode: string | enum=unit,integration,none default=unit description="Test mode to execute" + command: '[]string | default=[] description="Custom command to override the default entrypoint"' + args: '[]string | default=[] description="Custom arguments to pass to the command"' + resources: + cpuCores: integer | default=1 minimum=1 maximum=8 description="Number of CPU cores" + memoryGb: integer | default=2 minimum=1 maximum=32 description="Amount of memory in GB" + timeout: string | default="30m" description="Build timeout duration (e.g., 30m, 1h)" + cache: + enabled: boolean | default=true description="Enable build cache" + paths: '[]string | default=["/root/.cache"] description="Paths to cache between builds"' + limits: + maxRetries: integer | default=3 minimum=0 maximum=10 description="Maximum retry attempts" + maxDurationMinutes: integer | default=60 minimum=5 maximum=240 description="Maximum duration" + + runTemplate: + apiVersion: argoproj.io/v1alpha1 + kind: Workflow + metadata: + name: ${ctx.componentWorkflowRunName} + namespace: openchoreo-ci-${ctx.orgName} + spec: + arguments: + parameters: + # Context variables + - name: component-name + value: ${ctx.componentName} + - name: project-name + value: ${ctx.projectName} + # System parameters + - name: git-repo + value: ${systemParameters.repository.url} + - name: branch + value: ${systemParameters.repository.revision.branch} + - name: commit + value: ${systemParameters.repository.revision.commit} + - name: app-path + value: ${systemParameters.repository.appPath} + # Developer parameters + - name: version + value: ${parameters.version} + - name: test-mode + value: ${parameters.testMode} + - name: cpu-cores + value: ${parameters.resources.cpuCores} + - name: memory-gb + value: ${parameters.resources.memoryGb} + # PE-controlled hardcoded parameters + - name: builder-image + value: gcr.io/buildpacks/builder@sha256:5977b4bd47d3e9ff729eefe9eb99d321d4bba7aa3b14986323133f40b622aef1 + - name: registry-url + value: gcr.io/openchoreo-dev/images + - name: security-scan-enabled + value: "true" + - name: image-name + value: ${ctx.projectName}-${ctx.componentName}-image + - name: image-tag + value: v${parameters.version} + serviceAccountName: workflow-sa + workflowTemplateRef: + clusterScope: true + name: google-cloud-buildpacks +``` + +### Docker Build ComponentWorkflow + +```yaml +apiVersion: openchoreo.dev/v1alpha1 +kind: ComponentWorkflow +metadata: + name: docker + namespace: default + annotations: + openchoreo.dev/description: "Docker build workflow using Dockerfile" +spec: + schema: + systemParameters: + repository: + url: 'string | description="Git repository URL"' + revision: + branch: 'string | default=main description="Git branch"' + commit: 'string | description="Commit SHA (optional)"' + appPath: 'string | default=. description="Application path"' + + parameters: + docker: + context: string | default=. description="Docker build context path" + filePath: string | default=./Dockerfile description="Path to Dockerfile" + buildArgs: '[]string | default=[] description="Docker build arguments"' + + runTemplate: + apiVersion: argoproj.io/v1alpha1 + kind: Workflow + metadata: + name: ${ctx.componentWorkflowRunName} + namespace: openchoreo-ci-${ctx.orgName} + spec: + arguments: + parameters: + - name: component-name + value: ${ctx.componentName} + - name: project-name + value: ${ctx.projectName} + - name: git-repo + value: ${systemParameters.repository.url} + - name: branch + value: ${systemParameters.repository.revision.branch} + - name: commit + value: ${systemParameters.repository.revision.commit} + - name: app-path + value: ${systemParameters.repository.appPath} + - name: docker-context + value: ${parameters.docker.context} + - name: dockerfile-path + value: ${parameters.docker.filePath} + - name: registry-url + value: gcr.io/openchoreo-dev/images + - name: image-name + value: ${ctx.projectName}-${ctx.componentName}-image + serviceAccountName: workflow-sa + workflowTemplateRef: + clusterScope: true + name: docker +``` + +## ComponentType Integration + +ComponentTypes can restrict which ComponentWorkflows developers can use through the `allowedWorkflows` field: + +```yaml +apiVersion: openchoreo.dev/v1alpha1 +kind: ComponentType +metadata: + name: service +spec: + workloadType: deployment + allowedWorkflows: + - google-cloud-buildpacks + - docker +``` + +## Component Integration + +Components reference ComponentWorkflows in their workflow configuration: + +```yaml +apiVersion: openchoreo.dev/v1alpha1 +kind: Component +metadata: + name: reading-list-service +spec: + componentType: deployment/service + + workflow: + name: google-cloud-buildpacks + + systemParameters: + repository: + url: "https://github.com/openchoreo/sample-workloads" + revision: + branch: "main" + commit: "" + appPath: "/service-go-reading-list" + + parameters: + version: 1 + testMode: "integration" + resources: + cpuCores: 2 + memoryGb: 4 +``` + +## Annotations + +ComponentWorkflows support the following annotations: + +| Annotation | Description | +|-------------------------------|----------------------------------------------| +| `openchoreo.dev/display-name` | Human-readable name for UI display | +| `openchoreo.dev/description` | Detailed description of the ComponentWorkflow | + +## Related Resources + +- [ComponentWorkflowRun](../application/componentworkflowrun.md) - Runtime execution instances of ComponentWorkflows +- [ComponentType](./componenttype.md) - Can restrict allowed component workflows via `allowedWorkflows` +- [Component](../application/component.md) - References ComponentWorkflows for building \ No newline at end of file diff --git a/docs/reference/api/platform/workflow.md b/docs/reference/api/platform/workflow.md index e695d829..6f67bd32 100644 --- a/docs/reference/api/platform/workflow.md +++ b/docs/reference/api/platform/workflow.md @@ -4,6 +4,16 @@ title: Workflow API Reference # Workflow +:::warning Deprecated +The Workflow resource is deprecated for component builds and will be removed in a future release. Use +[ComponentWorkflow](./componentworkflow.md) instead for building components. ComponentWorkflow provides a structured +schema for repository information required for build-specific platform features like auto-builds, webhooks, and build +traceability. + +Generic Workflow resources will still be used for non-component automation tasks (Terraform, ETL pipelines, database +migrations, etc.) in the future. +::: + A Workflow is a platform engineer-defined template for executing build, test, and automation tasks in OpenChoreo. Workflows provide a schema-driven interface that separates developer-facing parameters from platform-controlled configurations, integrating with Argo Workflows to provide Kubernetes-native CI/CD execution.