Skip to content

Add ComponentRelease API reference #132

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
VajiraPrabuddhaka merged 1 commit into from
Nov 22, 2025
Merged

Add ComponentRelease API reference #132

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion docs/reference/api/application/componentdeployment.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
55 changes: 28 additions & 27 deletions ...ference/api/application/releasebinding.md → .../reference/api/platform/releasebinding.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand All @@ -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
Expand All @@ -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

Expand All @@ -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

Expand Down Expand Up @@ -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
235 changes: 235 additions & 0 deletions docs/reference/api/runtime/componentrelease.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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: <componentrelease-name>
namespace: <org-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
Loading