Skip to content

Commit 6901afe

Browse files
Mirage20Mirage20
committed
Add ComponentDeployment and deprecate old application resources
- Create ComponentDeployment API reference documentation - Add deprecation notices to Service - Add deprecation notices to WebApplication - Add deprecation notices to ScheduledTask - Update sidebars.ts to include ComponentDeployment - Mark deprecated application resources in sidebar
1 parent 7a5d383 commit 6901afe

7 files changed

Lines changed: 387 additions & 64 deletions

File tree

‎docs/reference/api/application/componentdeployment.md‎

Lines changed: 297 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,297 @@
1+
---
2+
title: ComponentDeployment API Reference
3+
---
4+
5+
# ComponentDeployment
6+
7+
A ComponentDeployment represents an environment-specific deployment of a Component. It allows platform engineers to
8+
override component parameters, trait configurations, and workload settings for specific environments like development,
9+
staging, or production.
10+
11+
## API Version
12+
13+
`openchoreo.dev/v1alpha1`
14+
15+
## Resource Definition
16+
17+
### Metadata
18+
19+
ComponentDeployments are namespace-scoped resources created in the same namespace as the Component they deploy.
20+
21+
```yaml
22+
apiVersion: openchoreo.dev/v1alpha1
23+
kind: ComponentDeployment
24+
metadata:
25+
name: <component-name>-<environment-name>
26+
namespace: <project-namespace>
27+
```
28+
29+
### Spec Fields
30+
31+
| Field | Type | Required | Default | Description |
32+
|--------------------------|---------------------------------------------------------|----------|---------|--------------------------------------------------------|
33+
| `owner` | [ComponentDeploymentOwner](#componentdeploymentowner) | Yes | - | Identifies the component this deployment applies to |
34+
| `environment` | string | Yes | - | Name of the environment (must match an Environment CR) |
35+
| `overrides` | object | No | - | Overrides for ComponentType `envOverrides` parameters |
36+
| `traitOverrides` | map[string]object | No | - | Environment-specific trait parameter overrides |
37+
| `configurationOverrides` | [EnvConfigurationOverrides](#envconfigurationoverrides) | No | - | Overrides for workload configurations |
38+
39+
### ComponentDeploymentOwner
40+
41+
Identifies which component this deployment is for.
42+
43+
| Field | Type | Required | Description |
44+
|-----------------|--------|----------|---------------------------------------------|
45+
| `projectName` | string | Yes | Name of the project that owns the component |
46+
| `componentName` | string | Yes | Name of the component to deploy |
47+
48+
### EnvConfigurationOverrides
49+
50+
Environment-specific configuration overrides for the workload.
51+
52+
| Field | Type | Required | Description |
53+
|---------|-----------------------|----------|--------------------------------|
54+
| `env` | [[EnvVar](#envvar)] | No | Environment variable overrides |
55+
| `files` | [[FileVar](#filevar)] | No | File configuration overrides |
56+
57+
#### EnvVar
58+
59+
| Field | Type | Required | Description |
60+
|---------|--------|----------|----------------------------|
61+
| `name` | string | Yes | Environment variable name |
62+
| `value` | string | Yes | Environment variable value |
63+
64+
#### FileVar
65+
66+
| Field | Type | Required | Description |
67+
|-------------|--------|----------|-------------------------|
68+
| `name` | string | Yes | File name |
69+
| `mountPath` | string | Yes | Mount path in container |
70+
| `value` | string | Yes | File content |
71+
72+
### Status Fields
73+
74+
| Field | Type | Default | Description |
75+
|----------------------|-------------|---------|-------------------------------------------------------------------|
76+
| `observedGeneration` | integer | 0 | Generation observed by the controller |
77+
| `conditions` | []Condition | [] | Standard Kubernetes conditions tracking ComponentDeployment state |
78+
79+
#### Condition Types
80+
81+
Common condition types for ComponentDeployment resources:
82+
83+
- `Ready` - Indicates if the deployment is ready
84+
- `Deployed` - Indicates if resources have been deployed successfully
85+
- `Synced` - Indicates if the deployment is in sync with the component definition
86+
87+
## Examples
88+
89+
### Basic ComponentDeployment
90+
91+
```yaml
92+
apiVersion: openchoreo.dev/v1alpha1
93+
kind: ComponentDeployment
94+
metadata:
95+
name: my-service-production
96+
namespace: default
97+
spec:
98+
owner:
99+
projectName: default
100+
componentName: my-service
101+
102+
environment: production
103+
```
104+
105+
### ComponentDeployment with Parameter Overrides
106+
107+
Override ComponentType `envOverrides` parameters for production:
108+
109+
```yaml
110+
apiVersion: openchoreo.dev/v1alpha1
111+
kind: ComponentDeployment
112+
metadata:
113+
name: my-service-production
114+
namespace: default
115+
spec:
116+
owner:
117+
projectName: default
118+
componentName: my-service
119+
120+
environment: production
121+
122+
overrides:
123+
resources:
124+
requests:
125+
cpu: "500m"
126+
memory: "1Gi"
127+
limits:
128+
cpu: "2000m"
129+
memory: "4Gi"
130+
```
131+
132+
### ComponentDeployment with Trait Overrides
133+
134+
Override trait parameters for a specific environment:
135+
136+
```yaml
137+
apiVersion: openchoreo.dev/v1alpha1
138+
kind: ComponentDeployment
139+
metadata:
140+
name: my-service-production
141+
namespace: default
142+
spec:
143+
owner:
144+
projectName: default
145+
componentName: my-service
146+
147+
environment: production
148+
149+
traitOverrides:
150+
data-storage: # instanceName of the trait attachment
151+
size: 100Gi
152+
storageClass: production-ssd
153+
iops: 3000
154+
```
155+
156+
### ComponentDeployment with Configuration Overrides
157+
158+
Override workload environment variables and files:
159+
160+
```yaml
161+
apiVersion: openchoreo.dev/v1alpha1
162+
kind: ComponentDeployment
163+
metadata:
164+
name: my-service-production
165+
namespace: default
166+
spec:
167+
owner:
168+
projectName: default
169+
componentName: my-service
170+
171+
environment: production
172+
173+
configurationOverrides:
174+
env:
175+
- name: LOG_LEVEL
176+
value: "error"
177+
- name: CACHE_TTL
178+
value: "3600"
179+
180+
files:
181+
- name: config.yaml
182+
mountPath: /etc/app
183+
value: |
184+
database:
185+
host: prod-db.example.com
186+
port: 5432
187+
cache:
188+
enabled: true
189+
```
190+
191+
### Complete ComponentDeployment Example
192+
193+
Combining all override types:
194+
195+
```yaml
196+
apiVersion: openchoreo.dev/v1alpha1
197+
kind: ComponentDeployment
198+
metadata:
199+
name: my-service-production
200+
namespace: default
201+
spec:
202+
owner:
203+
projectName: default
204+
componentName: my-service
205+
206+
environment: production
207+
208+
# Override ComponentType envOverrides
209+
overrides:
210+
resources:
211+
requests:
212+
cpu: "500m"
213+
memory: "1Gi"
214+
limits:
215+
cpu: "2000m"
216+
memory: "4Gi"
217+
218+
# Override trait parameters
219+
traitOverrides:
220+
data-storage:
221+
size: 100Gi
222+
storageClass: fast-ssd
223+
224+
backup:
225+
schedule: "0 2 * * *"
226+
retention: 30
227+
228+
# Override workload configurations
229+
configurationOverrides:
230+
env:
231+
- name: LOG_LEVEL
232+
value: "info"
233+
- name: MAX_CONNECTIONS
234+
value: "1000"
235+
```
236+
237+
## Usage
238+
239+
ComponentDeployments are typically created for each environment where a component should be deployed:
240+
241+
```bash
242+
# Development environment
243+
kubectl apply -f my-service-development.yaml
244+
245+
# Staging environment
246+
kubectl apply -f my-service-staging.yaml
247+
248+
# Production environment
249+
kubectl apply -f my-service-production.yaml
250+
```
251+
252+
View component deployments:
253+
254+
```bash
255+
# List all component deployments
256+
kubectl get componentdeployments
257+
258+
# Get deployments for a specific component
259+
kubectl get componentdeployment -l openchoreo.dev/component=my-service
260+
261+
# View deployment details
262+
kubectl describe componentdeployment my-service-production
263+
```
264+
265+
## Override Hierarchy
266+
267+
Parameters are resolved in the following order (later overrides earlier):
268+
269+
1. **ComponentType defaults** - Default values from ComponentType schema
270+
2. **Component parameters** - Values specified in the Component spec
271+
3. **ComponentDeployment overrides** - Environment-specific values in ComponentDeployment
272+
273+
Example:
274+
275+
```yaml
276+
# ComponentType defines: replicas default=1
277+
# Component sets: replicas=3
278+
# ComponentDeployment (prod) overrides: replicas=5
279+
# Result: Production deployment will have 5 replicas
280+
```
281+
282+
## Best Practices
283+
284+
1. **Naming Convention**: Use `<component-name>-<environment-name>` pattern
285+
2. **Environment-Specific Values**: Only override what differs between environments
286+
3. **Resource Limits**: Always set appropriate limits for production environments
287+
4. **Configuration Management**: Use ConfigMaps/Secrets for complex configurations
288+
5. **Trait Management**: Override trait parameters rather than removing/adding traits
289+
6. **Testing**: Validate overrides in lower environments before production
290+
7. **Documentation**: Document why specific overrides are needed
291+
292+
## Related Resources
293+
294+
- [Component](component.md) - Defines the component being deployed
295+
- [Environment](../platform/environment.md) - Defines the target environment
296+
- [ComponentType](../platform/componenttype.md) - Defines available parameters for override
297+
- [Trait](../platform/trait.md) - Traits whose parameters can be overridden

‎docs/reference/api/application/scheduledtask.md‎

Lines changed: 6 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,14 @@
11
---
2-
title: ScheduledTask API Reference
2+
title: ScheduledTask API Reference (Deprecated)
33
---
44

55
# ScheduledTask
66

7+
:::warning Deprecated
8+
ScheduledTask is deprecated as of OpenChoreo v0.4.0 and will be removed in a future version.
9+
Use [Component](component.md) with [ComponentType](../platform/componenttype.md) and [ComponentDeployment](componentdeployment.md) instead for a more flexible deployment model.
10+
:::
11+
712
A ScheduledTask represents a scheduled or cron job component in OpenChoreo. It defines the deployment configuration for
813
scheduled task-type components by referencing a Workload and optionally a ScheduledTaskClass for platform-defined
914
policies. ScheduledTasks are used for batch processing, periodic maintenance, or any workload that runs on a schedule.

‎docs/reference/api/application/service.md‎

Lines changed: 6 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,14 @@
11
---
2-
title: Service API Reference
2+
title: Service API Reference (Deprecated)
33
---
44

55
# Service
66

7+
:::warning Deprecated
8+
Service is deprecated as of OpenChoreo v0.4.0 and will be removed in a future version.
9+
Use [Component](component.md) with [ComponentType](../platform/componenttype.md) and [ComponentDeployment](componentdeployment.md) instead for a more flexible deployment model.
10+
:::
11+
712
A Service represents a long-running service component in OpenChoreo. It defines the deployment configuration for
813
service-type components by referencing a Workload and optionally a ServiceClass for platform-defined policies.
914
Services can expose APIs with different access levels and integrate with OpenChoreo's API management capabilities.

‎docs/reference/api/application/webapplication.md‎

Lines changed: 6 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,14 @@
11
---
2-
title: WebApplication API Reference
2+
title: WebApplication API Reference (Deprecated)
33
---
44

55
# WebApplication
66

7+
:::warning Deprecated
8+
WebApplication is deprecated as of OpenChoreo v0.4.0 and will be removed in a future version.
9+
Use [Component](component.md) with [ComponentType](../platform/componenttype.md) and [ComponentDeployment](componentdeployment.md) instead for a more flexible deployment model.
10+
:::
11+
712
A WebApplication represents a web application component in OpenChoreo. It defines the deployment configuration for
813
web application-type components by referencing a Workload and optionally a WebApplicationClass for platform-defined
914
policies. WebApplications are typically frontend applications or web services that serve HTTP content.

0 commit comments

Comments
 (0)