Skip to content

Commit 7a5d383

Browse files
Mirage20Mirage20
committed
Add ComponentType and Trait API reference docs
- Create new ComponentType API reference documentation - Create new Trait API reference documentation - Add deprecation notices to ServiceClass - Add deprecation notices to WebApplicationClass - Add deprecation notices to ScheduledTaskClass - Update sidebars.ts to include new resources - Mark deprecated classes in sidebar navigation
1 parent 978c79b commit 7a5d383

6 files changed

Lines changed: 652 additions & 6 deletions

File tree

‎docs/reference/api/platform/componenttype.md‎

Lines changed: 282 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,282 @@
1+
---
2+
title: ComponentType API Reference
3+
---
4+
5+
# ComponentType
6+
7+
A ComponentType is a platform-defined template that determines how components are deployed and what resources are generated for them. ComponentTypes enable platform engineers to create reusable deployment patterns with configurable parameters, replacing the fixed component classes from previous versions.
8+
9+
## API Version
10+
11+
`openchoreo.dev/v1alpha1`
12+
13+
## Resource Definition
14+
15+
### Metadata
16+
17+
ComponentTypes are namespace-scoped resources typically created in an Organization's namespace to be available for components in that organization.
18+
19+
```yaml
20+
apiVersion: openchoreo.dev/v1alpha1
21+
kind: ComponentType
22+
metadata:
23+
name: <componenttype-name>
24+
namespace: <org-namespace> # Organization namespace
25+
```
26+
27+
### Spec Fields
28+
29+
| Field | Type | Required | Default | Description |
30+
|--------------------|-----------------------------------------------|----------|---------|----------------------------------------------------------------------|
31+
| `workloadType` | string | Yes | - | Primary workload type: `deployment`, `statefulset`, `cronjob`, `job` |
32+
| `allowedWorkflows` | [[AllowedWorkflow](#allowedworkflow)] | No | [] | Workflows that developers can use for building this component type |
33+
| `schema` | [ComponentTypeSchema](#componenttypeschema) | No | - | Configurable parameters for components of this type |
34+
| `resources` | [[ResourceTemplate](#resourcetemplate)] | Yes | - | Templates for generating Kubernetes resources |
35+
36+
:::note
37+
The `workloadType` field is immutable after creation and determines the primary resource type for components of this type.
38+
:::
39+
40+
### ComponentTypeSchema
41+
42+
Defines the configurable parameters that developers can set when creating components of this type.
43+
44+
| Field | Type | Required | Default | Description |
45+
|---------------|----------------|----------|---------|------------------------------------------------------------------|
46+
| `types` | object | No | - | Reusable type definitions referenced in parameters |
47+
| `parameters` | object | No | - | Static parameters exposed to developers (same across all envs) |
48+
| `envOverrides`| object | No | - | Parameters that can be overridden per environment |
49+
50+
#### Parameter Schema Syntax
51+
52+
Parameters use inline schema syntax with pipe-separated modifiers:
53+
54+
```
55+
fieldName: "type | default=value | required=true | enum=val1,val2"
56+
```
57+
58+
Supported types: `string`, `integer`, `boolean`, `array<type>`, custom type references
59+
60+
**Example:**
61+
```yaml
62+
schema:
63+
types:
64+
Resources:
65+
cpu: "string | default=100m"
66+
memory: "string | default=256Mi"
67+
68+
parameters:
69+
replicas: "integer | default=1"
70+
port: "integer | default=8080"
71+
imagePullPolicy: "string | default=IfNotPresent | enum=Always,IfNotPresent,Never"
72+
73+
envOverrides:
74+
resources:
75+
requests: Resources
76+
limits: Resources
77+
```
78+
79+
### ResourceTemplate
80+
81+
Defines a template for generating Kubernetes resources with CEL expressions for dynamic values.
82+
83+
| Field | Type | Required | Default | Description |
84+
|--------------|--------|----------|---------|------------------------------------------------------------|
85+
| `id` | string | Yes | - | Unique identifier (must match `workloadType` for primary) |
86+
| `includeWhen`| string | No | - | CEL expression determining if resource should be created |
87+
| `forEach` | string | No | - | CEL expression for generating multiple resources from list |
88+
| `var` | string | No | - | Variable name for `forEach` iterations |
89+
| `template` | object | Yes | - | Kubernetes resource template with CEL expressions |
90+
91+
#### CEL Expression Syntax
92+
93+
Templates use CEL expressions enclosed in `${...}` that have access to:
94+
95+
- `metadata.*` - Component metadata (name, namespace, labels, podSelectors)
96+
- `parameters.*` - ComponentType parameters
97+
- `workload.*` - Workload specification (containers, volumes)
98+
- `configurations.*` - Configuration and secret references
99+
- `environment.*` - Environment information
100+
- `dataplane.*` - DataPlane configuration
101+
- OpenChoreo helper functions: `oc_generate_name()`, `oc_hash()`, `oc_omit()`
102+
103+
### AllowedWorkflow
104+
105+
References a Workflow CR that developers can use for building components of this type.
106+
107+
| Field | Type | Required | Description |
108+
|--------|--------|----------|----------------------|
109+
| `name` | string | Yes | Name of the Workflow |
110+
111+
## Examples
112+
113+
### Basic HTTP Service ComponentType
114+
115+
```yaml
116+
apiVersion: openchoreo.dev/v1alpha1
117+
kind: ComponentType
118+
metadata:
119+
name: service
120+
namespace: default
121+
spec:
122+
workloadType: deployment
123+
124+
schema:
125+
parameters:
126+
replicas: "integer | default=1"
127+
port: "integer | default=80"
128+
exposed: "boolean | default=false"
129+
130+
resources:
131+
- id: deployment
132+
template:
133+
apiVersion: apps/v1
134+
kind: Deployment
135+
metadata:
136+
name: ${metadata.name}
137+
namespace: ${metadata.namespace}
138+
spec:
139+
replicas: ${parameters.replicas}
140+
selector:
141+
matchLabels: ${metadata.podSelectors}
142+
template:
143+
metadata:
144+
labels: ${metadata.podSelectors}
145+
spec:
146+
containers:
147+
- name: main
148+
image: ${workload.containers["main"].image}
149+
ports:
150+
- containerPort: ${parameters.port}
151+
152+
- id: service
153+
template:
154+
apiVersion: v1
155+
kind: Service
156+
metadata:
157+
name: ${metadata.componentName}
158+
namespace: ${metadata.namespace}
159+
spec:
160+
selector: ${metadata.podSelectors}
161+
ports:
162+
- port: 80
163+
targetPort: ${parameters.port}
164+
165+
- id: httproute
166+
includeWhen: ${parameters.exposed == true}
167+
template:
168+
apiVersion: gateway.networking.k8s.io/v1
169+
kind: HTTPRoute
170+
metadata:
171+
name: ${metadata.name}
172+
namespace: ${metadata.namespace}
173+
spec:
174+
parentRefs:
175+
- name: gateway-external
176+
namespace: openchoreo-data-plane
177+
hostnames:
178+
- ${metadata.name}-${environment.name}.${environment.vhost}
179+
rules:
180+
- backendRefs:
181+
- name: ${metadata.componentName}
182+
port: 80
183+
```
184+
185+
### Scheduled Task ComponentType
186+
187+
```yaml
188+
apiVersion: openchoreo.dev/v1alpha1
189+
kind: ComponentType
190+
metadata:
191+
name: scheduled-task
192+
namespace: default
193+
spec:
194+
workloadType: cronjob
195+
196+
schema:
197+
parameters:
198+
schedule: "string | required=true"
199+
concurrencyPolicy: "string | default=Forbid | enum=Allow,Forbid,Replace"
200+
201+
resources:
202+
- id: cronjob
203+
template:
204+
apiVersion: batch/v1
205+
kind: CronJob
206+
metadata:
207+
name: ${metadata.name}
208+
namespace: ${metadata.namespace}
209+
spec:
210+
schedule: ${parameters.schedule}
211+
concurrencyPolicy: ${parameters.concurrencyPolicy}
212+
jobTemplate:
213+
spec:
214+
template:
215+
spec:
216+
containers:
217+
- name: main
218+
image: ${workload.containers["main"].image}
219+
restartPolicy: OnFailure
220+
```
221+
222+
### ComponentType with Resource Iteration
223+
224+
```yaml
225+
apiVersion: openchoreo.dev/v1alpha1
226+
kind: ComponentType
227+
metadata:
228+
name: multi-config-service
229+
namespace: default
230+
spec:
231+
workloadType: deployment
232+
233+
resources:
234+
- id: deployment
235+
template:
236+
# ... deployment spec ...
237+
238+
- id: file-config
239+
includeWhen: ${has(configurations.configs.files) && configurations.configs.files.size() > 0}
240+
forEach: ${configurations.configs.files}
241+
var: config
242+
template:
243+
apiVersion: v1
244+
kind: ConfigMap
245+
metadata:
246+
name: ${metadata.name}-${config.name}
247+
namespace: ${metadata.namespace}
248+
data:
249+
${config.name}: ${config.value}
250+
```
251+
252+
## Usage
253+
254+
Components reference a ComponentType using the `spec.componentType` field:
255+
256+
```yaml
257+
apiVersion: openchoreo.dev/v1alpha1
258+
kind: Component
259+
metadata:
260+
name: my-service
261+
spec:
262+
componentType: deployment/service # References the ComponentType
263+
parameters:
264+
replicas: 3
265+
port: 8080
266+
exposed: true
267+
```
268+
269+
## Best Practices
270+
271+
1. **Naming Convention**: Use descriptive names like `service`, `web-application`, `scheduled-task`
272+
2. **Parameter Design**: Keep parameters focused and provide sensible defaults
273+
3. **Resource IDs**: Use clear, descriptive IDs for each resource template
274+
4. **Conditional Resources**: Use `includeWhen` for optional resources based on parameters
275+
5. **Type Definitions**: Define reusable types for complex parameter structures
276+
6. **Testing**: Validate ComponentTypes with sample components before platform-wide deployment
277+
278+
## Related Resources
279+
280+
- [Component](../application/component.md) - Uses ComponentTypes for deployment
281+
- [ComponentDeployment](../application/componentdeployment.md) - Can override ComponentType parameters per environment
282+
- [Trait](trait.md) - Adds cross-cutting concerns to components using ComponentTypes

‎docs/reference/api/platform/scheduledtaskclass.md‎

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

55
# ScheduledTaskClass
66

7+
:::warning Deprecated
8+
ScheduledTaskClass is deprecated as of OpenChoreo v0.4.0 and will be removed in a future version.
9+
Use [ComponentType](componenttype.md) with [Traits](trait.md) instead for a more flexible and composable approach to
10+
defining component deployment patterns.
11+
:::
12+
713
A ScheduledTaskClass is a platform-level template that provides governance and standardization for ScheduledTask
814
resources in OpenChoreo. It follows the Claim/Class pattern where platform teams define Classes to enforce
915
organizational policies, resource limits, and scheduling configurations while application teams create

‎docs/reference/api/platform/serviceclass.md‎

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

55
# ServiceClass
66

7+
:::warning Deprecated
8+
ServiceClass is deprecated as of OpenChoreo v0.4.0 and will be removed in a future version.
9+
Use [ComponentType](componenttype.md) with [Traits](trait.md) instead for a more flexible and composable approach to
10+
defining component deployment patterns.
11+
:::
12+
713
A ServiceClass is a platform-level template that provides governance and standardization for Service
814
resources in OpenChoreo. It follows the Claim/Class pattern where platform teams define Classes to enforce
915
organizational policies, resource limits, and deployment configurations while application teams create Services (claims)

0 commit comments

Comments
 (0)