|
| 1 | +--- |
| 2 | +title: ComponentRelease API Reference |
| 3 | +--- |
| 4 | + |
| 5 | +# ComponentRelease |
| 6 | + |
| 7 | +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. |
| 8 | + |
| 9 | +## API Version |
| 10 | + |
| 11 | +`openchoreo.dev/v1alpha1` |
| 12 | + |
| 13 | +## Resource Definition |
| 14 | + |
| 15 | +### Metadata |
| 16 | + |
| 17 | +ComponentReleases are namespace-scoped resources that must be created within an Organization's namespace. |
| 18 | + |
| 19 | +```yaml |
| 20 | +apiVersion: openchoreo.dev/v1alpha1 |
| 21 | +kind: ComponentRelease |
| 22 | +metadata: |
| 23 | + name: <componentrelease-name> |
| 24 | + namespace: <org-namespace> # Organization namespace |
| 25 | +``` |
| 26 | +
|
| 27 | +### Spec Fields |
| 28 | +
|
| 29 | +| Field | Type | Required | Default | Description | |
| 30 | +|--------------------|---------------------------------------------------------------------------------|----------|---------|-----------------------------------------------------------------------| |
| 31 | +| `owner` | [ComponentReleaseOwner](#componentreleaseowner) | Yes | - | Ownership information linking the release to a project and component | |
| 32 | +| `componentType` | [ComponentTypeSpec](../platform/componenttype.md#spec-fields) | Yes | - | Immutable snapshot of the ComponentType at release time | |
| 33 | +| `traits` | map[string][TraitSpec](../platform/trait.md#spec-fields) | No | {} | Immutable snapshot of trait specifications at release time | |
| 34 | +| `componentProfile` | [ComponentProfile](#componentprofile) | Yes | - | Immutable snapshot of parameter values and trait configurations | |
| 35 | +| `workload` | [WorkloadTemplateSpec](#workloadtemplatespec) | Yes | - | Immutable snapshot of the workload specification with the built image | |
| 36 | + |
| 37 | +### ComponentReleaseOwner |
| 38 | + |
| 39 | +| Field | Type | Required | Default | Description | |
| 40 | +|-----------------|--------|----------|---------|------------------------------------------------------| |
| 41 | +| `projectName` | string | Yes | - | Name of the project that owns this component release | |
| 42 | +| `componentName` | string | Yes | - | Name of the component this release belongs to | |
| 43 | + |
| 44 | +### ComponentProfile |
| 45 | + |
| 46 | +ComponentProfile contains the frozen parameter values and trait configurations at the time of release. |
| 47 | + |
| 48 | +| Field | Type | Required | Default | Description | |
| 49 | +|--------------|-----------------------------------------------------------------------------------------|----------|---------|-------------------------------------------------------------------| |
| 50 | +| `parameters` | [runtime.RawExtension](https://pkg.go.dev/k8s.io/apimachinery/pkg/runtime#RawExtension) | No | - | Merged schema of parameters + envOverrides from the ComponentType | |
| 51 | +| `traits` | [[ComponentTrait](#componenttrait)] | No | [] | Trait instances with their configurations | |
| 52 | + |
| 53 | +### ComponentTrait |
| 54 | + |
| 55 | +| Field | Type | Required | Default | Description | |
| 56 | +|----------------|-----------------------------------------------------------------------------------------|----------|---------|----------------------------------------------------------------| |
| 57 | +| `name` | string | Yes | - | Name of the Trait resource | |
| 58 | +| `instanceName` | string | Yes | - | Unique identifier for this trait instance within the component | |
| 59 | +| `parameters` | [runtime.RawExtension](https://pkg.go.dev/k8s.io/apimachinery/pkg/runtime#RawExtension) | No | - | Trait parameter values conforming to the trait's schema | |
| 60 | + |
| 61 | +### WorkloadTemplateSpec |
| 62 | + |
| 63 | +The WorkloadTemplateSpec contains the complete workload specification with the built container image. |
| 64 | + |
| 65 | +| Field | Type | Required | Default | Description | |
| 66 | +|---------------|--------------------------------------------------------------------------------|----------|---------|-----------------------------------------------------------------------------------------------------| |
| 67 | +| `containers` | map[string][Container](../application/workload.md#container) | Yes | - | Container specifications keyed by container name. Must have at least one container with key "main" | |
| 68 | +| `endpoints` | map[string][WorkloadEndpoint](../application/workload.md#workloadendpoint) | No | {} | Network endpoints for port exposure keyed by endpoint name | |
| 69 | +| `connections` | map[string][WorkloadConnection](../application/workload.md#workloadconnection) | No | {} | Connections to internal/external resources keyed by connection name. Supports template variables | |
| 70 | + |
| 71 | +### Status Fields |
| 72 | + |
| 73 | +Currently, ComponentRelease does not have any status fields defined. |
| 74 | + |
| 75 | +## Examples |
| 76 | + |
| 77 | +### Basic ComponentRelease for a Service Component |
| 78 | + |
| 79 | +```yaml |
| 80 | +apiVersion: openchoreo.dev/v1alpha1 |
| 81 | +kind: ComponentRelease |
| 82 | +metadata: |
| 83 | + name: customer-service-v1.0.0 |
| 84 | + namespace: default |
| 85 | +spec: |
| 86 | + owner: |
| 87 | + projectName: my-project |
| 88 | + componentName: customer-service |
| 89 | + componentType: |
| 90 | + workloadType: deployment |
| 91 | + schema: |
| 92 | + parameters: |
| 93 | + runtime: |
| 94 | + port: "integer | default=8080" |
| 95 | + resources: |
| 96 | + - id: deployment |
| 97 | + template: |
| 98 | + apiVersion: apps/v1 |
| 99 | + kind: Deployment |
| 100 | + metadata: |
| 101 | + name: "${metadata.name}" |
| 102 | + spec: |
| 103 | + replicas: 1 |
| 104 | + template: |
| 105 | + spec: |
| 106 | + containers: |
| 107 | + - name: main |
| 108 | + image: "${spec.workload.containers.main.image}" |
| 109 | + ports: |
| 110 | + - containerPort: "${spec.parameters.runtime.port}" |
| 111 | + componentProfile: |
| 112 | + parameters: |
| 113 | + runtime: |
| 114 | + port: 8080 |
| 115 | + workload: |
| 116 | + containers: |
| 117 | + main: |
| 118 | + image: myregistry/customer-service@sha256:abc123... |
| 119 | + env: |
| 120 | + - key: LOG_LEVEL |
| 121 | + value: info |
| 122 | + endpoints: |
| 123 | + api: |
| 124 | + type: REST |
| 125 | + port: 8080 |
| 126 | +``` |
| 127 | + |
| 128 | +### ComponentRelease with Traits |
| 129 | + |
| 130 | +```yaml |
| 131 | +apiVersion: openchoreo.dev/v1alpha1 |
| 132 | +kind: ComponentRelease |
| 133 | +metadata: |
| 134 | + name: order-service-v2.1.0 |
| 135 | + namespace: default |
| 136 | +spec: |
| 137 | + owner: |
| 138 | + projectName: my-project |
| 139 | + componentName: order-service |
| 140 | + componentType: |
| 141 | + workloadType: deployment |
| 142 | + schema: |
| 143 | + parameters: |
| 144 | + runtime: |
| 145 | + replicas: "integer | default=1" |
| 146 | + resources: |
| 147 | + - id: deployment |
| 148 | + template: |
| 149 | + apiVersion: apps/v1 |
| 150 | + kind: Deployment |
| 151 | + metadata: |
| 152 | + name: "${metadata.name}" |
| 153 | + spec: |
| 154 | + replicas: "${spec.parameters.runtime.replicas}" |
| 155 | + traits: |
| 156 | + persistent-volume: |
| 157 | + schema: |
| 158 | + parameters: |
| 159 | + volumeName: "string | required=true" |
| 160 | + mountPath: "string | required=true" |
| 161 | + envOverrides: |
| 162 | + size: "string | default=10Gi" |
| 163 | + patches: |
| 164 | + - target: |
| 165 | + id: deployment |
| 166 | + operations: |
| 167 | + - op: add |
| 168 | + path: /spec/template/spec/volumes/- |
| 169 | + value: |
| 170 | + name: "${spec.traits.volumeName}" |
| 171 | + componentProfile: |
| 172 | + parameters: |
| 173 | + runtime: |
| 174 | + replicas: 3 |
| 175 | + traits: |
| 176 | + - name: persistent-volume |
| 177 | + instanceName: data-volume |
| 178 | + parameters: |
| 179 | + volumeName: data |
| 180 | + mountPath: /var/data |
| 181 | + size: 20Gi |
| 182 | + workload: |
| 183 | + containers: |
| 184 | + main: |
| 185 | + image: myregistry/order-service@sha256:def456... |
| 186 | + env: |
| 187 | + - key: DATA_DIR |
| 188 | + value: /var/data |
| 189 | + endpoints: |
| 190 | + order-api: |
| 191 | + type: REST |
| 192 | + port: 8080 |
| 193 | + connections: |
| 194 | + database: |
| 195 | + type: api |
| 196 | + params: |
| 197 | + projectName: my-project |
| 198 | + componentName: postgres-db |
| 199 | + endpoint: tcp-endpoint |
| 200 | + inject: |
| 201 | + env: |
| 202 | + - name: DATABASE_HOST |
| 203 | + value: "{{ .host }}" |
| 204 | + - name: DATABASE_PORT |
| 205 | + value: "{{ .port }}" |
| 206 | +``` |
| 207 | + |
| 208 | +## Immutability |
| 209 | + |
| 210 | +ComponentRelease is designed to be immutable once created. All spec fields have validation rules that prevent modifications after creation: |
| 211 | + |
| 212 | +- `spec.componentType` - Immutable |
| 213 | +- `spec.traits` - Immutable |
| 214 | +- `spec.componentProfile` - Immutable |
| 215 | +- `spec.workload` - Immutable |
| 216 | + |
| 217 | +This ensures that a ComponentRelease always represents the exact state of the component at a specific point in time, enabling reliable rollbacks and auditing. |
| 218 | + |
| 219 | +## Annotations |
| 220 | + |
| 221 | +ComponentReleases support the following annotations: |
| 222 | + |
| 223 | +| Annotation | Description | |
| 224 | +|-------------------------------|----------------------------------------------------| |
| 225 | +| `openchoreo.dev/display-name` | Human-readable name for UI display | |
| 226 | +| `openchoreo.dev/description` | Detailed description of the component release | |
| 227 | +| `openchoreo.dev/version` | Semantic version or tag for this release | |
| 228 | + |
| 229 | +## Related Resources |
| 230 | + |
| 231 | +- [Component](../application/component.md) - Components that ComponentReleases are created from |
| 232 | +- [ComponentType](../platform/componenttype.md) - Component type definitions captured in releases |
| 233 | +- [Trait](../platform/trait.md) - Trait specifications captured in releases |
| 234 | +- [Workload](../application/workload.md) - Workload specifications captured in releases |
| 235 | +- [ReleaseBinding](../platform/releasebinding.md) - Binds a ComponentRelease to a target environment for deployment |
0 commit comments