diff --git a/docs/reference/api/application/componentdeployment.md b/docs/reference/api/application/componentdeployment.md index 09c6deb2..6d3f37a1 100644 --- a/docs/reference/api/application/componentdeployment.md +++ b/docs/reference/api/application/componentdeployment.md @@ -5,7 +5,7 @@ title: ComponentDeployment API Reference (Deprecated) # ComponentDeployment (Deprecated) :::warning Deprecated -ComponentDeployment has been replaced by [ReleaseBinding](releasebinding.md). Please use ReleaseBinding for new deployments. +ComponentDeployment has been replaced by [ReleaseBinding](../platform/releasebinding.md). Please use ReleaseBinding for new deployments. ::: A ComponentDeployment represents an environment-specific deployment of a Component. It allows platform engineers to diff --git a/docs/reference/api/application/releasebinding.md b/docs/reference/api/platform/releasebinding.md similarity index 76% rename from docs/reference/api/application/releasebinding.md rename to docs/reference/api/platform/releasebinding.md index 1711d00c..37767427 100644 --- a/docs/reference/api/application/releasebinding.md +++ b/docs/reference/api/platform/releasebinding.md @@ -26,14 +26,14 @@ metadata: ### Spec Fields -| Field | Type | Required | Default | Description | -|-----------------------------|---------------------------------------------------|----------|---------|--------------------------------------------------------| -| `owner` | [ReleaseBindingOwner](#releasebindingowner) | Yes | - | Identifies the component this release binding applies to | -| `environment` | string | Yes | - | Name of the environment (must match an Environment CR) | -| `releaseName` | string | Yes | - | Name of the release to bind | -| `componentTypeEnvOverrides` | object | No | - | Overrides for ComponentType `envOverrides` parameters | -| `traitOverrides` | map[string]object | No | - | Environment-specific trait parameter overrides | -| `workloadOverrides` | [WorkloadOverride](#workloadoverride) | No | - | Overrides for workload configurations | +| Field | Type | Required | Default | Description | +|-----------------------------|---------------------------------------------|----------|---------|--------------------------------------------------------------| +| `owner` | [ReleaseBindingOwner](#releasebindingowner) | Yes | - | Identifies the component this release binding applies to | +| `environment` | string | Yes | - | Name of the environment (must match an Environment CR) | +| `releaseName` | string | Yes | - | Name of the ComponentRelease to bind to this environment | +| `componentTypeEnvOverrides` | object | No | - | Overrides for ComponentType `envOverrides` parameters | +| `traitOverrides` | map[string]object | No | - | Environment-specific trait parameter overrides | +| `workloadOverrides` | [WorkloadOverride](#workloadoverride) | No | - | Overrides for workload configurations | ### ReleaseBindingOwner @@ -48,8 +48,8 @@ Identifies which component this release binding is for. Environment-specific configuration overrides for the workload. -| Field | Type | Required | Description | -|--------------|-------------------------------------------|----------|------------------------------------------------------| +| Field | Type | Required | Description | +|--------------|----------------------------------------------------|----------|------------------------------------------------------| | `containers` | map[string][ContainerOverride](#containeroverride) | No | Container-specific overrides keyed by container name | #### ContainerOverride @@ -61,11 +61,11 @@ Environment-specific configuration overrides for the workload. #### EnvVar -| Field | Type | Required | Description | -|-------------|-----------------------------------|----------|--------------------------------------------------| -| `name` | string | Yes | Environment variable name | -| `value` | string | No | Plain text value | -| `secretRef` | [SecretRef](#secretref) | No | Reference to a secret value | +| Field | Type | Required | Description | +|-------------|-------------------------|----------|-------------------------------| +| `name` | string | Yes | Environment variable name | +| `value` | string | No | Plain text value | +| `secretRef` | [SecretRef](#secretref) | No | Reference to a secret value | #### SecretRef @@ -76,18 +76,18 @@ Environment-specific configuration overrides for the workload. #### FileVar -| Field | Type | Required | Description | -|-------------|-------------------------------|----------|----------------------------| -| `name` | string | Yes | File name | -| `mountPath` | string | Yes | Mount path in container | -| `value` | string | No | Plain text file content | +| Field | Type | Required | Description | +|-------------|-------------------------|----------|----------------------------| +| `name` | string | Yes | File name | +| `mountPath` | string | Yes | Mount path in container | +| `value` | string | No | Plain text file content | | `secretRef` | [SecretRef](#secretref) | No | Reference to a secret file | ### Status Fields -| Field | Type | Default | Description | -|--------------|-------------|---------|---------------------------------------------------------------| -| `conditions` | []Condition | [] | Standard Kubernetes conditions tracking ReleaseBinding state | +| Field | Type | Default | Description | +|--------------|-------------|---------|--------------------------------------------------------------| +| `conditions` | []Condition | [] | Standard Kubernetes conditions tracking ReleaseBinding state | #### Condition Types @@ -313,7 +313,8 @@ Example: ## Related Resources -- [Component](component.md) - Defines the component being deployed -- [Environment](../platform/environment.md) - Defines the target environment -- [ComponentType](../platform/componenttype.md) - Defines available parameters for override -- [Trait](../platform/trait.md) - Traits whose parameters can be overridden +- [Component](../application/component.md) - Defines the component being deployed +- [ComponentRelease](../runtime/componentrelease.md) - Immutable snapshot that ReleaseBinding references for deployment +- [Environment](environment.md) - Defines the target environment +- [ComponentType](componenttype.md) - Defines available parameters for override +- [Trait](trait.md) - Traits whose parameters can be overridden diff --git a/docs/reference/api/runtime/componentrelease.md b/docs/reference/api/runtime/componentrelease.md new file mode 100644 index 00000000..67ab8e71 --- /dev/null +++ b/docs/reference/api/runtime/componentrelease.md @@ -0,0 +1,235 @@ +--- +title: ComponentRelease API Reference +--- + +# ComponentRelease + +A ComponentRelease represents an immutable snapshot of a component's configuration at a specific point in time in OpenChoreo. It captures the complete component specification including the ComponentType, Traits, parameters, and Workload template with the built image. ComponentReleases ensure reproducibility and enable rollback by preserving the exact state of a component when it was released. + +## API Version + +`openchoreo.dev/v1alpha1` + +## Resource Definition + +### Metadata + +ComponentReleases are namespace-scoped resources that must be created within an Organization's namespace. + +```yaml +apiVersion: openchoreo.dev/v1alpha1 +kind: ComponentRelease +metadata: + name: + namespace: # Organization namespace +``` + +### Spec Fields + +| Field | Type | Required | Default | Description | +|--------------------|---------------------------------------------------------------------------------|----------|---------|-----------------------------------------------------------------------| +| `owner` | [ComponentReleaseOwner](#componentreleaseowner) | Yes | - | Ownership information linking the release to a project and component | +| `componentType` | [ComponentTypeSpec](../platform/componenttype.md#spec-fields) | Yes | - | Immutable snapshot of the ComponentType at release time | +| `traits` | map[string][TraitSpec](../platform/trait.md#spec-fields) | No | {} | Immutable snapshot of trait specifications at release time | +| `componentProfile` | [ComponentProfile](#componentprofile) | Yes | - | Immutable snapshot of parameter values and trait configurations | +| `workload` | [WorkloadTemplateSpec](#workloadtemplatespec) | Yes | - | Immutable snapshot of the workload specification with the built image | + +### ComponentReleaseOwner + +| Field | Type | Required | Default | Description | +|-----------------|--------|----------|---------|------------------------------------------------------| +| `projectName` | string | Yes | - | Name of the project that owns this component release | +| `componentName` | string | Yes | - | Name of the component this release belongs to | + +### ComponentProfile + +ComponentProfile contains the frozen parameter values and trait configurations at the time of release. + +| Field | Type | Required | Default | Description | +|--------------|-----------------------------------------------------------------------------------------|----------|---------|-------------------------------------------------------------------| +| `parameters` | [runtime.RawExtension](https://pkg.go.dev/k8s.io/apimachinery/pkg/runtime#RawExtension) | No | - | Merged schema of parameters + envOverrides from the ComponentType | +| `traits` | [[ComponentTrait](#componenttrait)] | No | [] | Trait instances with their configurations | + +### ComponentTrait + +| Field | Type | Required | Default | Description | +|----------------|-----------------------------------------------------------------------------------------|----------|---------|----------------------------------------------------------------| +| `name` | string | Yes | - | Name of the Trait resource | +| `instanceName` | string | Yes | - | Unique identifier for this trait instance within the component | +| `parameters` | [runtime.RawExtension](https://pkg.go.dev/k8s.io/apimachinery/pkg/runtime#RawExtension) | No | - | Trait parameter values conforming to the trait's schema | + +### WorkloadTemplateSpec + +The WorkloadTemplateSpec contains the complete workload specification with the built container image. + +| Field | Type | Required | Default | Description | +|---------------|--------------------------------------------------------------------------------|----------|---------|-----------------------------------------------------------------------------------------------------| +| `containers` | map[string][Container](../application/workload.md#container) | Yes | - | Container specifications keyed by container name. Must have at least one container with key "main" | +| `endpoints` | map[string][WorkloadEndpoint](../application/workload.md#workloadendpoint) | No | {} | Network endpoints for port exposure keyed by endpoint name | +| `connections` | map[string][WorkloadConnection](../application/workload.md#workloadconnection) | No | {} | Connections to internal/external resources keyed by connection name. Supports template variables | + +### Status Fields + +Currently, ComponentRelease does not have any status fields defined. + +## Examples + +### Basic ComponentRelease for a Service Component + +```yaml +apiVersion: openchoreo.dev/v1alpha1 +kind: ComponentRelease +metadata: + name: customer-service-v1.0.0 + namespace: default +spec: + owner: + projectName: my-project + componentName: customer-service + componentType: + workloadType: deployment + schema: + parameters: + runtime: + port: "integer | default=8080" + resources: + - id: deployment + template: + apiVersion: apps/v1 + kind: Deployment + metadata: + name: "${metadata.name}" + spec: + replicas: 1 + template: + spec: + containers: + - name: main + image: "${spec.workload.containers.main.image}" + ports: + - containerPort: "${spec.parameters.runtime.port}" + componentProfile: + parameters: + runtime: + port: 8080 + workload: + containers: + main: + image: myregistry/customer-service@sha256:abc123... + env: + - key: LOG_LEVEL + value: info + endpoints: + api: + type: REST + port: 8080 +``` + +### ComponentRelease with Traits + +```yaml +apiVersion: openchoreo.dev/v1alpha1 +kind: ComponentRelease +metadata: + name: order-service-v2.1.0 + namespace: default +spec: + owner: + projectName: my-project + componentName: order-service + componentType: + workloadType: deployment + schema: + parameters: + runtime: + replicas: "integer | default=1" + resources: + - id: deployment + template: + apiVersion: apps/v1 + kind: Deployment + metadata: + name: "${metadata.name}" + spec: + replicas: "${spec.parameters.runtime.replicas}" + traits: + persistent-volume: + schema: + parameters: + volumeName: "string | required=true" + mountPath: "string | required=true" + envOverrides: + size: "string | default=10Gi" + patches: + - target: + id: deployment + operations: + - op: add + path: /spec/template/spec/volumes/- + value: + name: "${spec.traits.volumeName}" + componentProfile: + parameters: + runtime: + replicas: 3 + traits: + - name: persistent-volume + instanceName: data-volume + parameters: + volumeName: data + mountPath: /var/data + size: 20Gi + workload: + containers: + main: + image: myregistry/order-service@sha256:def456... + env: + - key: DATA_DIR + value: /var/data + endpoints: + order-api: + type: REST + port: 8080 + connections: + database: + type: api + params: + projectName: my-project + componentName: postgres-db + endpoint: tcp-endpoint + inject: + env: + - name: DATABASE_HOST + value: "{{ .host }}" + - name: DATABASE_PORT + value: "{{ .port }}" +``` + +## Immutability + +ComponentRelease is designed to be immutable once created. All spec fields have validation rules that prevent modifications after creation: + +- `spec.componentType` - Immutable +- `spec.traits` - Immutable +- `spec.componentProfile` - Immutable +- `spec.workload` - Immutable + +This ensures that a ComponentRelease always represents the exact state of the component at a specific point in time, enabling reliable rollbacks and auditing. + +## Annotations + +ComponentReleases support the following annotations: + +| Annotation | Description | +|-------------------------------|----------------------------------------------------| +| `openchoreo.dev/display-name` | Human-readable name for UI display | +| `openchoreo.dev/description` | Detailed description of the component release | +| `openchoreo.dev/version` | Semantic version or tag for this release | + +## Related Resources + +- [Component](../application/component.md) - Components that ComponentReleases are created from +- [ComponentType](../platform/componenttype.md) - Component type definitions captured in releases +- [Trait](../platform/trait.md) - Trait specifications captured in releases +- [Workload](../application/workload.md) - Workload specifications captured in releases +- [ReleaseBinding](../platform/releasebinding.md) - Binds a ComponentRelease to a target environment for deployment \ No newline at end of file diff --git a/sidebars.ts b/sidebars.ts index 3635ec26..604073d1 100644 --- a/sidebars.ts +++ b/sidebars.ts @@ -75,10 +75,9 @@ const sidebars: SidebarsConfig = { items: [ {type: 'doc', id: 'reference/api/application/project', label: 'Project'}, {type: 'doc', id: 'reference/api/application/component', label: 'Component'}, - {type: 'doc', id: 'reference/api/application/releasebinding', label: 'ReleaseBinding'}, {type: 'doc', id: 'reference/api/application/workload', label: 'Workload'}, - {type: 'doc', id: 'reference/api/application/componentdeployment', label: 'ComponentDeployment (Deprecated)'}, {type: 'doc', id: 'reference/api/application/workflowrun', label: 'WorkflowRun'}, + {type: 'doc', id: 'reference/api/application/componentdeployment', label: 'ComponentDeployment (Deprecated)'}, {type: 'doc', id: 'reference/api/application/build', label: 'Build (Deprecated)'}, {type: 'doc', id: 'reference/api/application/service', label: 'Service (Deprecated)'}, {type: 'doc', id: 'reference/api/application/webapplication', label: 'WebApplication (Deprecated)'}, @@ -94,6 +93,7 @@ const sidebars: SidebarsConfig = { {type: 'doc', id: 'reference/api/platform/environment', label: 'Environment'}, {type: 'doc', id: 'reference/api/platform/buildplane', label: 'BuildPlane'}, {type: 'doc', id: 'reference/api/platform/deployment-pipeline', label: 'DeploymentPipeline'}, + {type: 'doc', id: 'reference/api/platform/releasebinding', label: 'ReleaseBinding'}, {type: 'doc', id: 'reference/api/platform/componenttype', label: 'ComponentType'}, {type: 'doc', id: 'reference/api/platform/trait', label: 'Trait'}, {type: 'doc', id: 'reference/api/platform/workflow', label: 'Workflow'}, @@ -106,10 +106,11 @@ const sidebars: SidebarsConfig = { type: 'category', label: 'Runtime Resources', items: [ + {type: 'doc', id: 'reference/api/runtime/componentrelease', label: 'ComponentRelease'}, + {type: 'doc', id: 'reference/api/runtime/release', label: 'Release'}, {type: 'doc', id: 'reference/api/runtime/servicebinding', label: 'ServiceBinding (Deprecated)'}, {type: 'doc', id: 'reference/api/runtime/webapplicationbinding', label: 'WebApplicationBinding (Deprecated)'}, - {type: 'doc', id: 'reference/api/runtime/scheduledtaskbinding', label: 'ScheduledTaskBinding (Deprecated)'}, - {type: 'doc', id: 'reference/api/runtime/release', label: 'Release'} + {type: 'doc', id: 'reference/api/runtime/scheduledtaskbinding', label: 'ScheduledTaskBinding (Deprecated)'} ] } ]