Skip to content

Commit 937014d

Browse files
kitsunoffkitsunoff
authored
docs(external-apps): rewrite guide for ApplicationDefinition API (#488)
## Summary Rewrite the external applications guide to reflect the current API and conventions: - Replace outdated `CozystackResourceDefinition` references with `ApplicationDefinition` - Document the full platform chart structure (namespaces, HelmCharts, operator deployment, ApplicationDefinitions) - Add naming conventions table matching the main Cozystack repository - Document application chart structure and Makefile conventions - Update bootstrap manifest to use `reconcileStrategy: Revision` ## Context The previous guide only covered creating a GitRepository + HelmRelease and pointed to the example repo for everything else. The rewrite provides a self-contained reference for building external application packages, based on conventions from the main Cozystack repository and the updated [external-apps-example](cozystack/external-apps-example#2). <!-- This is an auto-generated comment: release notes by coderabbit.ai --> ## Summary by CodeRabbit * **Documentation** * Updated external application package repository structure and setup guidelines. * Enhanced deployment instructions with improved FluxCD configuration and reconciliation strategy details. * Added comprehensive chart authoring instructions and ApplicationDefinition examples. <!-- end of auto-generated comment: release notes by coderabbit.ai -->
2 parents 0be1724 + 0658772 commit 937014d

1 file changed

Lines changed: 195 additions & 23 deletions

File tree

‎content/en/docs/v1.2/applications/external.md‎

Lines changed: 195 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -5,35 +5,201 @@ description: "Learn how to add managed applications from external sources"
55
weight: 5
66
---
77

8-
Since v0.37.0, Cozystack administrators can add applications from external sources in addition to the standard application catalog.
9-
These applications will appear in the same application catalog and behave like regular managed applications for platform users.
8+
Cozystack administrators can add applications from external sources in addition to the standard application catalog.
9+
These applications appear in the same catalog and behave like regular managed applications for platform users.
1010

11-
This guide explains how to define a managed application package and how to add it to Cozystack.
11+
This guide explains the structure of an external application package and how to add it to a Cozystack cluster.
1212

13+
For a complete working example, see [github.com/cozystack/external-apps-example](https://github.com/cozystack/external-apps-example).
1314

14-
## 1. Create an Application Package Repository
15+
Just like standard Cozystack applications, this external application package uses Helm and FluxCD.
16+
To learn more about developing application packages, read the Cozystack [Developer Guide]({{% ref "/docs/v1.2/development" %}}).
1517

16-
Create a repository with the application package sources.
17-
For a reference, see [github.com/cozystack/external-apps-example](https://github.com/cozystack/external-apps-example).
18+
## Repository Structure
1819

19-
Application repository has the following structure:
20+
An external application repository has the following layout:
2021

21-
- `./packages/core`: Manifests for the platform configuration and to deploy system applications.
22-
- `./packages/system`: Helm charts for system applications.
23-
- `./packages/apps`: Helm charts for applications that can be installed from the dashboard.
22+
```text
23+
init.yaml # Bootstrap manifest (GitRepository + HelmRelease)
24+
scripts/
25+
package.mk # Shared Makefile targets for app charts
26+
packages/
27+
core/platform/ # Platform chart: namespaces, operators, HelmCharts, ApplicationDefinitions
28+
apps/<app-name>/ # Helm chart for each user-installable application
29+
```
2430

25-
Just like standard Cozystack applications, this external application package is using Helm and FluxCD.
26-
To learn more about developing application packages, read Cozystack [Developer Guide]({{% ref "/docs/v1.2/development" %}})
31+
- `packages/core/platform` — a Helm chart deployed by FluxCD. It registers all applications via `ApplicationDefinition` CRDs, creates required namespaces, deploys operators, and defines `HelmChart` resources that point to the app charts in the same Git repository.
32+
- `packages/apps/<app-name>` — standard Helm charts that template the actual Kubernetes resources (CRDs, ConfigMaps, Secrets, etc.).
2733

28-
These FluxCD documents will help you understand the resources used in this guide:
34+
## Platform Chart
35+
36+
The platform chart (`packages/core/platform/`) is the central piece. It contains templates for:
37+
38+
### Namespaces
39+
40+
Create namespaces for operators and system components:
41+
42+
```yaml
43+
apiVersion: v1
44+
kind: Namespace
45+
metadata:
46+
labels:
47+
cozystack.io/system: "true"
48+
name: external-<operator-name>
49+
```
50+
51+
### HelmCharts
52+
53+
Define `HelmChart` resources that tell FluxCD where to find each app chart within the Git repository:
54+
55+
```yaml
56+
apiVersion: source.toolkit.fluxcd.io/v1
57+
kind: HelmChart
58+
metadata:
59+
name: external-apps-<app-name>
60+
namespace: cozy-public
61+
spec:
62+
interval: 5m
63+
chart: ./packages/apps/<app-name>
64+
sourceRef:
65+
kind: GitRepository
66+
name: external-apps
67+
reconcileStrategy: Revision
68+
```
69+
70+
Use `reconcileStrategy: Revision` so that charts with a static `version: 0.0.0` are re-reconciled whenever the Git content changes.
71+
72+
### Operator Deployment
73+
74+
If your application requires an operator, deploy it via a `HelmRepository` and `HelmRelease`:
75+
76+
```yaml
77+
apiVersion: source.toolkit.fluxcd.io/v1
78+
kind: HelmRepository
79+
metadata:
80+
name: <operator-name>
81+
namespace: external-<operator-name>
82+
spec:
83+
type: oci
84+
interval: 5m
85+
url: oci://ghcr.io/<org>/charts
86+
---
87+
apiVersion: helm.toolkit.fluxcd.io/v2
88+
kind: HelmRelease
89+
metadata:
90+
name: <operator-name>
91+
namespace: external-<operator-name>
92+
spec:
93+
interval: 5m
94+
releaseName: <operator-name>
95+
targetNamespace: external-<operator-name>
96+
chart:
97+
spec:
98+
chart: <operator-chart-name>
99+
sourceRef:
100+
kind: HelmRepository
101+
name: <operator-name>
102+
version: '>=1.0.0'
103+
```
29104

30-
- [GitRepository](https://fluxcd.io/flux/components/source/gitrepositories/)
31-
- [HelmRelease](https://fluxcd.io/flux/components/helm/helmreleases/)
105+
### ApplicationDefinitions
32106

33-
## 2. Add the Application Package with a Manifest
107+
Register each application in the Cozystack dashboard with an `ApplicationDefinition`:
34108

35-
Create a manifest file with resources `GitRepository` and `HelmRelease`, as in the example:
109+
```yaml
110+
apiVersion: cozystack.io/v1alpha1
111+
kind: ApplicationDefinition
112+
metadata:
113+
name: <app-name>
114+
spec:
115+
application:
116+
kind: <AppKind>
117+
singular: <appkind>
118+
plural: <appkinds>
119+
openAPISchema: '{"title":"Chart Values","type":"object","properties":{...}}'
120+
release:
121+
chartRef:
122+
kind: HelmChart
123+
name: external-apps-<app-name>
124+
namespace: cozy-public
125+
labels:
126+
cozystack.io/ui: "true"
127+
prefix: <app-name>-
128+
dashboard:
129+
category: <Category>
130+
singular: <Human-readable Name>
131+
plural: <Human-readable Names>
132+
description: <Short description.>
133+
tags:
134+
- <tag>
135+
icon: <base64-encoded SVG>
136+
keysOrder:
137+
- - apiVersion
138+
- - appVersion
139+
- - kind
140+
- - metadata
141+
- - metadata
142+
- name
143+
- - spec
144+
- <field>
145+
```
36146

147+
Follow these naming conventions (matching the main Cozystack repository):
148+
149+
| Field | Convention | Example for `my-app` |
150+
| --- | --- | --- |
151+
| `metadata.name` | lowercase, hyphens allowed | `my-app` |
152+
| `application.kind` | PascalCase, no hyphens | `MyApp` |
153+
| `application.singular` | lowercase, no hyphens | `myapp` |
154+
| `application.plural` | lowercase, no hyphens | `myapps` |
155+
| `release.prefix` | `<metadata.name>-` | `my-app-` |
156+
| `openAPISchema` title | always `"Chart Values"` | — |
157+
158+
The `openAPISchema` field contains a single-line JSON string with the schema for the application values. It intentionally omits `if`/`then`/`else` conditional rules because Kubernetes `apiextensions/v1` `JSONSchemaProps` does not support these keywords. Use conditional validation only in the Helm chart's `values.schema.json`.
159+
160+
## Application Charts
161+
162+
Each application chart in `packages/apps/<app-name>/` is a standard Helm chart:
163+
164+
```text
165+
packages/apps/<app-name>/
166+
Chart.yaml
167+
Makefile
168+
values.yaml
169+
values.schema.json
170+
templates/
171+
<resource>.yaml
172+
```
173+
174+
### Chart.yaml
175+
176+
```yaml
177+
apiVersion: v2
178+
name: <app-name>
179+
description: <Short description>
180+
type: application
181+
version: 0.0.0
182+
appVersion: "1.0.0"
183+
```
184+
185+
Use `version: 0.0.0` — the actual version is derived from the Git revision by FluxCD.
186+
187+
### Makefile
188+
189+
```makefile
190+
export NAME=<app-name>
191+
export NAMESPACE=external-<operator-name>
192+
193+
include ../../../scripts/package.mk
194+
```
195+
196+
### values.schema.json
197+
198+
Define the JSON Schema (draft-07) for the application values. This schema is used by Helm for validation at install time and can include conditional rules (`if`/`then`/`else`) that are not supported at the `ApplicationDefinition` level.
199+
200+
## Bootstrap Manifest
201+
202+
The `init.yaml` file creates two FluxCD resources that bootstrap the entire catalog:
37203

38204
```yaml
39205
---
@@ -47,7 +213,7 @@ spec:
47213
ref:
48214
branch: main
49215
timeout: 60s
50-
url: https://github.com/cozystack/external-apps-example.git
216+
url: https://github.com/<org>/<repo>.git
51217
---
52218
apiVersion: helm.toolkit.fluxcd.io/v2
53219
kind: HelmRelease
@@ -64,15 +230,21 @@ spec:
64230
kind: GitRepository
65231
name: external-apps
66232
namespace: cozy-public
67-
version: '*'
233+
reconcileStrategy: Revision
68234
```
69235

70-
For a detailed reference, read [Git Repositories in Flux CD](https://fluxcd.io/flux/components/source/gitrepositories/).
71-
72-
Next, write this manifest to a file and apply it to your Cozystack cluster:
236+
Apply it to your Cozystack cluster:
73237

74238
```bash
75239
kubectl apply -f init.yaml
76240
```
77241

78-
After applying the manifest, open your application catalog to confirm that the application is available.
242+
After FluxCD reconciles, the applications will appear in the Cozystack dashboard.
243+
244+
## FluxCD Reference
245+
246+
These FluxCD documents will help you understand the resources used in this guide:
247+
248+
- [GitRepository](https://fluxcd.io/flux/components/source/gitrepositories/)
249+
- [HelmRelease](https://fluxcd.io/flux/components/helm/helmreleases/)
250+
- [HelmChart](https://fluxcd.io/flux/components/source/helmcharts/)

0 commit comments

Comments
 (0)