Skip to content

Commit 110d2ae

Browse files
Mirage20shirolk
Mirage20
authored and
shirolk
committed
Add comprehensive API reference documentation for OpenChoreo
This commit adds complete API reference documentation for all OpenChoreo resource types across Platform, Application, and Runtime categories: Platform Resources: - Organization, DataPlane, BuildPlane, Environment - DeploymentPipeline, ServiceClass, WebApplicationClass, ScheduledTaskClass Application Resources: - Project, Component, Workload, Build - Service, WebApplication, ScheduledTask Runtime Resources: - ServiceBinding, WebApplicationBinding, ScheduledTaskBinding - Release Each documentation file includes: - Resource description and purpose - API version and metadata requirements - Complete field specifications with types and descriptions - Practical YAML examples - Related resources and cross-references
1 parent cbf4a6f commit 110d2ae

23 files changed

+2443
-8
lines changed

‎README.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -154,4 +154,4 @@ For questions and support:
154154

155155
---
156156

157-
Built with ❤️ by the OpenChoreo community
157+
Built with ❤️ by the OpenChoreo community

‎_config.yml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -5,4 +5,4 @@ permalink: pretty
55

66
# Table of Contents configuration
77
toc:
8-
max_level: 2 # Show headings up to h2 (1=h1, 2=h2, 3=h3, etc.)
8+
max_level: 3 # Show headings up to h3 (1=h1, 2=h2, 3=h3, etc.)

‎_data/docs_nav.yml‎

Lines changed: 50 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -19,8 +19,6 @@
1919
# url: /docs/getting-started/multi-cluster/
2020
- title: Deploy Your First Component
2121
url: /docs/getting-started/deploy-your-first-component/
22-
- title: Learn from Examples
23-
children:
2422
- title: Examples Catalog
2523
url: /docs/learn-from-examples/examples-catalog/
2624
- title: Core Concepts
@@ -41,12 +39,59 @@
4139
# url: /docs/integrating-with-openchoreo/gitops/
4240
- title: Reference
4341
children:
44-
- title: Frequently Asked Questions (FAQ)
42+
- title: API Reference
43+
url: /docs/reference/api/application/project/
44+
children:
45+
- title: Application Resources
46+
children:
47+
- title: Project
48+
url: /docs/reference/api/application/project/
49+
- title: Component
50+
url: /docs/reference/api/application/component/
51+
- title: Workload
52+
url: /docs/reference/api/application/workload/
53+
- title: Build
54+
url: /docs/reference/api/application/build/
55+
- title: Service
56+
url: /docs/reference/api/application/service/
57+
- title: WebApplication
58+
url: /docs/reference/api/application/webapplication/
59+
- title: ScheduledTask
60+
url: /docs/reference/api/application/scheduledtask/
61+
- title: Platform Resources
62+
children:
63+
- title: Organization
64+
url: /docs/reference/api/platform/organization/
65+
- title: DataPlane
66+
url: /docs/reference/api/platform/dataplane/
67+
- title: Environment
68+
url: /docs/reference/api/platform/environment/
69+
- title: BuildPlane
70+
url: /docs/reference/api/platform/buildplane/
71+
- title: DeploymentPipeline
72+
url: /docs/reference/api/platform/deployment-pipeline/
73+
- title: ServiceClass
74+
url: /docs/reference/api/platform/serviceclass/
75+
- title: WebApplicationClass
76+
url: /docs/reference/api/platform/webapplicationclass/
77+
- title: ScheduledTaskClass
78+
url: /docs/reference/api/platform/scheduledtaskclass/
79+
- title: Runtime Resources
80+
children:
81+
- title: ServiceBinding
82+
url: /docs/reference/api/runtime/servicebinding/
83+
- title: WebApplicationBinding
84+
url: /docs/reference/api/runtime/webapplicationbinding/
85+
- title: ScheduledTaskBinding
86+
url: /docs/reference/api/runtime/scheduledtaskbinding/
87+
- title: Release
88+
url: /docs/reference/api/runtime/release/
89+
# - title: CLI Reference
90+
# url: /docs/reference/cli/
91+
- title: Frequently Asked Questions
4592
url: /docs/reference/faq/
4693
- title: Changelog
4794
url: /docs/reference/changelog/
48-
- title: Configuration Schema
49-
url: /docs/reference/configuration-schema/
5095
# - title: Resource Limits & Quotas
5196
# url: /docs/reference/resource-limits/
5297

‎css/openchoreo-docs.css‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -475,4 +475,4 @@ color: #B7B7B7;
475475
main.py-4 {
476476
padding: 1.5rem !important;
477477
}
478-
}
478+
}

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

Lines changed: 160 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,160 @@
1+
---
2+
layout: docs
3+
title: Build API Reference
4+
---
5+
6+
# Build
7+
8+
A Build represents a build job in OpenChoreo that transforms source code into a container image. It defines the
9+
source repository, revision, and build template to use for creating workloads. Upon successful
10+
completion, a Build creates a Workload resource containing the built container image.
11+
12+
## API Version
13+
14+
`openchoreo.dev/v1alpha1`
15+
16+
## Resource Definition
17+
18+
### Metadata
19+
20+
Builds are namespace-scoped resources that must be created within an Organization's namespace and belong to a
21+
Component through the owner field.
22+
23+
```yaml
24+
apiVersion: openchoreo.dev/v1alpha1
25+
kind: Build
26+
metadata:
27+
name: <build-name>
28+
namespace: <org-namespace> # Organization namespace
29+
```
30+
31+
### Spec Fields
32+
33+
| Field | Type | Required | Default | Description |
34+
|---------------|-----------------------------|----------|---------|--------------------------------------------------------------------|
35+
| `owner` | [BuildOwner](#buildowner) | Yes | - | Ownership information linking the build to a project and component |
36+
| `repository` | [Repository](#repository) | Yes | - | Source repository configuration |
37+
| `templateRef` | [TemplateRef](#templateref) | Yes | - | Build template reference and parameters |
38+
39+
### BuildOwner
40+
41+
| Field | Type | Required | Default | Description |
42+
|-----------------|--------|----------|---------|-----------------------------------------------------|
43+
| `projectName` | string | Yes | - | Name of the project that owns this build (min: 1) |
44+
| `componentName` | string | Yes | - | Name of the component that owns this build (min: 1) |
45+
46+
### Repository
47+
48+
| Field | Type | Required | Default | Description |
49+
|------------|-----------------------|----------|---------|--------------------------------------------------------------------|
50+
| `url` | string | Yes | - | Repository URL (e.g., https://github.com/org/repo) |
51+
| `revision` | [Revision](#revision) | Yes | - | Revision specification for the build |
52+
| `appPath` | string | Yes | - | Path to the application within the repository (e.g., "." for root) |
53+
54+
### Revision
55+
56+
| Field | Type | Required | Default | Description |
57+
|----------|--------|----------|---------|-------------------------------------------------------------------|
58+
| `branch` | string | No | "" | Branch to build from |
59+
| `commit` | string | No | "" | Specific commit hash to build from (takes precedence over branch) |
60+
61+
### TemplateRef
62+
63+
| Field | Type | Required | Default | Description |
64+
|--------------|---------------------------|----------|---------|------------------------------------------------------|
65+
| `engine` | string | No | "" | Build engine to use |
66+
| `name` | string | Yes | - | Name of the build template (ClusterWorkflowTemplate) |
67+
| `parameters` | [[Parameter](#parameter)] | No | [] | Template parameters |
68+
69+
### Parameter
70+
71+
| Field | Type | Required | Default | Description |
72+
|---------|--------|----------|---------|-----------------|
73+
| `name` | string | Yes | - | Parameter name |
74+
| `value` | string | Yes | - | Parameter value |
75+
76+
### Status Fields
77+
78+
| Field | Type | Default | Description |
79+
|---------------|-----------------|---------|---------------------------------------------------------|
80+
| `conditions` | []Condition | [] | Standard Kubernetes conditions tracking the build state |
81+
| `imageStatus` | [Image](#image) | {} | Information about the built image |
82+
83+
### Image
84+
85+
| Field | Type | Default | Description |
86+
|---------|--------|---------|-----------------------------------------------------------|
87+
| `image` | string | "" | Full image reference including registry, name, and digest |
88+
89+
#### Condition Types
90+
91+
Common condition types for Build resources:
92+
93+
- `Ready` - Indicates if the build has completed successfully
94+
- `Building` - Indicates if the build is currently in progress
95+
- `Failed` - Indicates if the build has failed
96+
97+
## Examples
98+
99+
### Build with Docker Template
100+
101+
```yaml
102+
apiVersion: openchoreo.dev/v1alpha1
103+
kind: Build
104+
metadata:
105+
name: customer-service-build-abc123
106+
namespace: default
107+
spec:
108+
owner:
109+
projectName: my-project
110+
componentName: customer-service
111+
repository:
112+
url: https://github.com/myorg/customer-service
113+
revision:
114+
branch: main
115+
commit: abc123def456
116+
appPath: .
117+
templateRef:
118+
name: docker
119+
parameters:
120+
- name: docker-context
121+
value: .
122+
- name: dockerfile-path
123+
value: ./Dockerfile
124+
```
125+
126+
### Build with Buildpacks
127+
128+
```yaml
129+
apiVersion: openchoreo.dev/v1alpha1
130+
kind: Build
131+
metadata:
132+
name: frontend-build-xyz789
133+
namespace: default
134+
spec:
135+
owner:
136+
projectName: my-project
137+
componentName: frontend-app
138+
repository:
139+
url: https://github.com/myorg/frontend
140+
revision:
141+
branch: develop
142+
appPath: ./webapp
143+
templateRef:
144+
name: google-cloud-buildpacks
145+
```
146+
147+
## Annotations
148+
149+
Builds support the following annotations:
150+
151+
| Annotation | Description |
152+
|-------------------------------|------------------------------------|
153+
| `openchoreo.dev/display-name` | Human-readable name for UI display |
154+
| `openchoreo.dev/description` | Detailed description of the build |
155+
156+
## Related Resources
157+
158+
- [Component](/docs/reference/api/application/component/) - Components that trigger builds
159+
- [Workload](/docs/reference/api/application/workload/) - Workloads created by successful builds
160+
- [BuildPlane](/docs/reference/api/platform/buildplane/) - Infrastructure where builds execute

0 commit comments

Comments
 (0)