Skip to content

docs(development): describe operator-based and HelmRelease-based package patterns #413

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
kvaps merged 1 commit into from
Feb 5, 2026
Merged

docs(development): describe operator-based and HelmRelease-based package patterns #413

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
51 changes: 47 additions & 4 deletions content/en/docs/development.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -74,9 +74,15 @@ Core packages do not use Helm to apply manifests; they are intended to be used o
### [system](https://github.com/cozystack/cozystack/tree/main/packages/system)

System packages configure the system to manage and deploy user applications. The
necessary system components are specified in the bundle configuration. This can also
include components without an operator, whose installation can be triggered as part
of user applications.
necessary system components are specified in the bundle configuration.

System packages include two kinds of components:

- **Operators** (e.g., `postgres-operator`, `kafka-operator`, `redis-operator`): Controllers
that know how to manage the full lifecycle of a specific application, including day-2 operations.
- **Upstream Helm charts** for applications without a dedicated operator (e.g., `nats`, `ingress-nginx`):
These charts are placed in system so that apps and extra packages can deploy them
via Flux `HelmRelease` CRs, effectively using FluxCD as the operator.

{{% alert color="info" %}}
System packages use Helm to install and are managed by FluxCD.
Expand All @@ -86,7 +92,42 @@ System packages use Helm to install and are managed by FluxCD.

These user-facing applications appear in the dashboard and include manifests to be applied to the cluster.

They should not contain business logic, because they are managed by operators installed from system.
Apps charts serve as a high-level API for users. They define only the parameters that
should be exposed and validated through `values.schema.json`, keeping the interface
minimal and secure. Apps charts should not contain business logic for deploying the
application itself — instead they delegate to an operator or to FluxCD.

Depending on whether the application has a dedicated operator, apps follow one of two patterns:

#### Operator-based pattern

When an application has a dedicated operator (e.g., PostgreSQL, MongoDB, Redis, Kafka),
the app chart creates **CRD instances** that the operator manages:

```
packages/system/postgres-operator/ # Operator Helm chart
packages/apps/postgres/ # App chart creates postgresql.cnpg.io/v1.Cluster CRs
```
Comment on lines +107 to +110
Copy link
Contributor

@coderabbitai coderabbitai bot Feb 5, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor

Add language specifiers to fenced code blocks.

The fenced code blocks showing directory structure should include a language identifier for proper rendering and syntax highlighting. Consider using text or shell as the identifier.

📝 Proposed fix

For lines 107-110:

-```
+```text
 packages/system/postgres-operator/   # Operator Helm chart
 packages/apps/postgres/              # App chart creates postgresql.cnpg.io/v1.Cluster CRs

For lines 121-124:
```diff
-```
+```text
 packages/system/nats/                # Upstream NATS Helm chart
 packages/apps/nats/                  # App chart creates helm.toolkit.fluxcd.io/v2.HelmRelease


</details>

As per coding guidelines, markdownlint-cli2 flags fenced code blocks without language specifiers (MD040).


Also applies to: 121-124

<details>
<summary>🧰 Tools</summary>

<details>
<summary>🪛 markdownlint-cli2 (0.20.0)</summary>

[warning] 107-107: Fenced code blocks should have a language specified

(MD040, fenced-code-language)

</details>

</details>

<details>
<summary>🤖 Prompt for AI Agents</summary>

In @content/en/docs/development.md around lines 107 - 110, Add a language
specifier to the two fenced code blocks that list directories (the block
containing "packages/system/postgres-operator/ # Operator Helm chart" and
"packages/apps/postgres/ # App chart creates
postgresql.cnpg.io/v1.Cluster CRs", and the block containing
"packages/system/nats/ # Upstream NATS Helm chart" and
"packages/apps/nats/ # App chart creates
helm.toolkit.fluxcd.io/v2.HelmRelease") by changing the opening triple backticks
to include a language token such as "text" (e.g., ```text) so markdownlint MD040
is satisfied and rendering/syntax highlighting works correctly.


</details>

<!-- fingerprinting:phantom:triton:puma -->

<!-- This is an auto-generated comment by CodeRabbit -->


The operator handles all deployment details and day-2 operations (scaling, backups, failover).
The app chart simply creates the appropriate CRD with values derived from user input.

#### HelmRelease-based pattern

When an application has no dedicated operator and a Helm chart is the standard deployment
method, the upstream chart is placed in `system/` and the app chart creates a
**Flux `HelmRelease` CR** pointing to it:

```
packages/system/nats/ # Upstream NATS Helm chart
packages/apps/nats/ # App chart creates helm.toolkit.fluxcd.io/v2.HelmRelease
```

In this case FluxCD acts as the operator, managing the Helm release lifecycle. The app
chart controls which upstream values are exposed to the user, providing an additional layer
of security — users cannot bypass validation to deploy the chart with arbitrary values.

Other examples of this pattern: `extra/ingress`, `extra/seaweedfs`, `extra/monitoring`.

### [extra](https://github.com/cozystack/cozystack/tree/main/packages/extra)

Expand All @@ -97,6 +138,8 @@ Read more about [Tenant System](/docs/guides/concepts/#tenant-system) on the Cor

It is possible to use only one application type within a single tenant namespace.

Extra packages follow the same two architectural patterns as apps (operator-based or HelmRelease-based).

{{% alert color="info" %}}
Apps and extra packages use Helm for application and are installed from the dashboard and managed by FluxCD.
Copy link
Contributor

@coderabbitai coderabbitai bot Feb 5, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor

Fix grammar: use plural form.

The phrase should use "applications" (plural) for grammatical correctness.

✏️ Proposed fix 
-Apps and extra packages use Helm for application and are installed from the dashboard and managed by FluxCD.
+Apps and extra packages use Helm for applications and are installed from the dashboard and managed by FluxCD.
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
Apps and extra packages use Helm for application and are installed from the dashboard and managed by FluxCD.
Apps and extra packages use Helm for applications and are installed from the dashboard and managed by FluxCD.
🤖 Prompt for AI Agents 
In `@content/en/docs/development.md` at line 144, The sentence "Apps and extra
packages use Helm for application and are installed from the dashboard and
managed by FluxCD." uses the singular "application"; change it to the plural
"applications" so it reads "Apps and extra packages use Helm for applications
and are installed from the dashboard and managed by FluxCD." Locate this exact
sentence in content/en/docs/development.md and update the word "application" to
"applications".

{{% /alert %}}
Expand Down