diff --git a/content/en/docs/v1.2/applications/external.md b/content/en/docs/v1.2/applications/external.md index 32ff8613..70632ef7 100644 --- a/content/en/docs/v1.2/applications/external.md +++ b/content/en/docs/v1.2/applications/external.md @@ -5,35 +5,201 @@ description: "Learn how to add managed applications from external sources" weight: 5 --- -Since v0.37.0, Cozystack administrators can add applications from external sources in addition to the standard application catalog. -These applications will appear in the same application catalog and behave like regular managed applications for platform users. +Cozystack administrators can add applications from external sources in addition to the standard application catalog. +These applications appear in the same catalog and behave like regular managed applications for platform users. -This guide explains how to define a managed application package and how to add it to Cozystack. +This guide explains the structure of an external application package and how to add it to a Cozystack cluster. +For a complete working example, see [github.com/cozystack/external-apps-example](https://github.com/cozystack/external-apps-example). -## 1. Create an Application Package Repository +Just like standard Cozystack applications, this external application package uses Helm and FluxCD. +To learn more about developing application packages, read the Cozystack [Developer Guide]({{% ref "/docs/v1.2/development" %}}). -Create a repository with the application package sources. -For a reference, see [github.com/cozystack/external-apps-example](https://github.com/cozystack/external-apps-example). +## Repository Structure -Application repository has the following structure: +An external application repository has the following layout: -- `./packages/core`: Manifests for the platform configuration and to deploy system applications. -- `./packages/system`: Helm charts for system applications. -- `./packages/apps`: Helm charts for applications that can be installed from the dashboard. +```text +init.yaml # Bootstrap manifest (GitRepository + HelmRelease) +scripts/ + package.mk # Shared Makefile targets for app charts +packages/ + core/platform/ # Platform chart: namespaces, operators, HelmCharts, ApplicationDefinitions + apps// # Helm chart for each user-installable application +``` -Just like standard Cozystack applications, this external application package is using Helm and FluxCD. -To learn more about developing application packages, read Cozystack [Developer Guide]({{% ref "/docs/v1.2/development" %}}) +- `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. +- `packages/apps/` — standard Helm charts that template the actual Kubernetes resources (CRDs, ConfigMaps, Secrets, etc.). -These FluxCD documents will help you understand the resources used in this guide: +## Platform Chart + +The platform chart (`packages/core/platform/`) is the central piece. It contains templates for: + +### Namespaces + +Create namespaces for operators and system components: + +```yaml +apiVersion: v1 +kind: Namespace +metadata: + labels: + cozystack.io/system: "true" + name: external- +``` + +### HelmCharts + +Define `HelmChart` resources that tell FluxCD where to find each app chart within the Git repository: + +```yaml +apiVersion: source.toolkit.fluxcd.io/v1 +kind: HelmChart +metadata: + name: external-apps- + namespace: cozy-public +spec: + interval: 5m + chart: ./packages/apps/ + sourceRef: + kind: GitRepository + name: external-apps + reconcileStrategy: Revision +``` + +Use `reconcileStrategy: Revision` so that charts with a static `version: 0.0.0` are re-reconciled whenever the Git content changes. + +### Operator Deployment + +If your application requires an operator, deploy it via a `HelmRepository` and `HelmRelease`: + +```yaml +apiVersion: source.toolkit.fluxcd.io/v1 +kind: HelmRepository +metadata: + name: + namespace: external- +spec: + type: oci + interval: 5m + url: oci://ghcr.io//charts +--- +apiVersion: helm.toolkit.fluxcd.io/v2 +kind: HelmRelease +metadata: + name: + namespace: external- +spec: + interval: 5m + releaseName: + targetNamespace: external- + chart: + spec: + chart: + sourceRef: + kind: HelmRepository + name: + version: '>=1.0.0' +``` -- [GitRepository](https://fluxcd.io/flux/components/source/gitrepositories/) -- [HelmRelease](https://fluxcd.io/flux/components/helm/helmreleases/) +### ApplicationDefinitions -## 2. Add the Application Package with a Manifest +Register each application in the Cozystack dashboard with an `ApplicationDefinition`: -Create a manifest file with resources `GitRepository` and `HelmRelease`, as in the example: +```yaml +apiVersion: cozystack.io/v1alpha1 +kind: ApplicationDefinition +metadata: + name: +spec: + application: + kind: + singular: + plural: + openAPISchema: '{"title":"Chart Values","type":"object","properties":{...}}' + release: + chartRef: + kind: HelmChart + name: external-apps- + namespace: cozy-public + labels: + cozystack.io/ui: "true" + prefix: - + dashboard: + category: + singular: + plural: + description: + tags: + - + icon: + keysOrder: + - - apiVersion + - - appVersion + - - kind + - - metadata + - - metadata + - name + - - spec + - +``` +Follow these naming conventions (matching the main Cozystack repository): + +| Field | Convention | Example for `my-app` | +| --- | --- | --- | +| `metadata.name` | lowercase, hyphens allowed | `my-app` | +| `application.kind` | PascalCase, no hyphens | `MyApp` | +| `application.singular` | lowercase, no hyphens | `myapp` | +| `application.plural` | lowercase, no hyphens | `myapps` | +| `release.prefix` | `-` | `my-app-` | +| `openAPISchema` title | always `"Chart Values"` | — | + +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`. + +## Application Charts + +Each application chart in `packages/apps//` is a standard Helm chart: + +```text +packages/apps// + Chart.yaml + Makefile + values.yaml + values.schema.json + templates/ + .yaml +``` + +### Chart.yaml + +```yaml +apiVersion: v2 +name: +description: +type: application +version: 0.0.0 +appVersion: "1.0.0" +``` + +Use `version: 0.0.0` — the actual version is derived from the Git revision by FluxCD. + +### Makefile + +```makefile +export NAME= +export NAMESPACE=external- + +include ../../../scripts/package.mk +``` + +### values.schema.json + +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. + +## Bootstrap Manifest + +The `init.yaml` file creates two FluxCD resources that bootstrap the entire catalog: ```yaml --- @@ -47,7 +213,7 @@ spec: ref: branch: main timeout: 60s - url: https://github.com/cozystack/external-apps-example.git + url: https://github.com//.git --- apiVersion: helm.toolkit.fluxcd.io/v2 kind: HelmRelease @@ -64,15 +230,21 @@ spec: kind: GitRepository name: external-apps namespace: cozy-public - version: '*' + reconcileStrategy: Revision ``` -For a detailed reference, read [Git Repositories in Flux CD](https://fluxcd.io/flux/components/source/gitrepositories/). - -Next, write this manifest to a file and apply it to your Cozystack cluster: +Apply it to your Cozystack cluster: ```bash kubectl apply -f init.yaml ``` -After applying the manifest, open your application catalog to confirm that the application is available. +After FluxCD reconciles, the applications will appear in the Cozystack dashboard. + +## FluxCD Reference + +These FluxCD documents will help you understand the resources used in this guide: + +- [GitRepository](https://fluxcd.io/flux/components/source/gitrepositories/) +- [HelmRelease](https://fluxcd.io/flux/components/helm/helmreleases/) +- [HelmChart](https://fluxcd.io/flux/components/source/helmcharts/)