From cb9ffdffc3af25f5b1fe4cbe6c838570177f25b8 Mon Sep 17 00:00:00 2001 From: jkalinic Date: Thu, 5 Mar 2026 15:02:55 +0100 Subject: [PATCH 1/6] Add streamshub-console-helm-charts proposal Signed-off-by: jkalinic --- 001-streamshub-console-helm.md | 86 ++++++++++++++++++++++++++++++++++ 1 file changed, 86 insertions(+) create mode 100644 001-streamshub-console-helm.md diff --git a/001-streamshub-console-helm.md b/001-streamshub-console-helm.md new file mode 100644 index 0000000..dd54617 --- /dev/null +++ b/001-streamshub-console-helm.md @@ -0,0 +1,86 @@ +# Helm Installation Support for StreamsHub Console + +This proposal outlines adding official Helm chart support for the StreamsHub Console operator and its Custom Resources (CRs). +This would provide a standardized installation method and lay the foundation for a broader StreamsHub Helm ecosystem. + +## Current situation + +There is currently no official Helm chart for the StreamsHub Console operator or its associated Custom Resources. +Among the broader StreamsHub stack, only Strimzi provides an official Helm chart. +Components such as Strimzi, Prometheus, and other dependencies each maintain their own Helm charts through their respective upstream projects. + +## Motivation + +Helm is widely adopted as the standard packaging mechanism for k8s applications. +A large portion of the k8s ecosystem — including GitOps platforms (e.g. Argo CD) and cloud provider marketplaces — relies on Helm as the primary installation mechanism. + +By introducing an official Helm chart for the Console operator and CRs, StreamsHub could: + +- **Lower the barrier to adoption** for teams already using Helm-based workflows and environments +- **Enable fine-tuned configuration** with value overrides, environment-specific configuration, and lifecycle management via Helm +- **Align with ecosystem standards**, making StreamsHub easier to discover and integrate +- **Unlock the possibility for a future StreamsHub Helm chart** — once the Console operator has its own chart, it becomes easier to compose a top-level `streamshub` chart +that depends on Console, Strimzi, Kafka, Prometheus, and other components, enabling full-stack deployment through a single `helm install` command + +## Proposal + +The proposal is to create and maintain an official Helm chart repo for: + +1. **The StreamsHub Console Operator** — managing its deployment, RBAC, service accounts, and associated configuration +2. **The Console Custom Resource (CR)** — exposing the Console instance configuration as Helm values, allowing users to customise the Console without editing raw YAML manifests + +### Scope of initial chart(s) + +The initial implementation should be deliberately scoped and simple. It should cover: + +- Operator's `Deployment`, `ServiceAccount`, `ClusterRole`, and `ClusterRoleBinding` +- CRD installation (either bundled or as a dependency) +- A Console CR that can be optionally deployed alongside the operator by passing a Helm value (e.g. console.instance=true), allowing users who prefer to manage the CR separately to do so + +- The chart should **not** attempt to manage external dependencies such as Strimzi, Kafka, or Prometheus in this initial phase. +Those components have already well-maintained charts and could be addressed in a follow-up effort. + +### Possible Future: StreamsHub Umbrella Chart + +Once official charts exist for the Console operator and operands, it becomes possible to introduce a `streamshub` +umbrella Helm chart that composes the full stack. This chart would declare Helm dependencies on: + +- `streamshub-console` (this proposal) +- `strimzi-kafka-operator` (official Strimzi chart) +- `kafka` / `kraft` via Strimzi CRs +- `prometheus` or equivalent monitoring +- `apicurio` or equivalent schema registries +- Any other components managed by StreamsHub + +This umbrella chart would give users an easy way to deploy the entire stack, significantly improving the onboarding experience and enabling catalogue listings on platforms like Artifact Hub. + +### Delivery + +- Charts to be hosted within the StreamsHub GitHub organisation, either in a dedicated `helm-charts` repository under a `${PROJECT_NAME}-charts/` directory +- Charts published to a Helm repository (like GitHub Pages or `oci` variants like Quay / DockerHub) + Artifact Hub following each release +- Chart versioning to follow the operator release cycle, with independent patch versioning where chart-only fixes are needed +- A GitHub Actions workflow can be introduced to lint chart using helm lint on every pull request/release, catching templating errors and schema violations early +- A minimal deployment test will run on each push, spinning up a light k8s cluster (kind or minikube might be the best options) and verifying that the operator and Console CR deploy and reach a healthy state +- Chart releases will be automated using github action workflows, allowing the Console operator chart to be tested and published to the StreamsHub Helm repository + +## Affected/not affected projects + +**Affected:** +- `streamshub/console` — primary subject of this proposal - the operator and Console CR chart will live in or alongside this repository +- StreamsHub documentation — installation guides will need updating to include Helm-based instructions + +**Not affected (at this stage):** +- Strimzi, Apicurio, Prometheus, and other stack components — remain independently managed and they will only be referenced if the future umbrella chart is taken forward + +## Compatibility + +- CRD management will follow Helm community best practices (CRDs in `crds/` directory) to avoid conflicts with existing CRD installations +- The chart will declare a minimum supported k8s version consistent with the operator's existing requirements +- Future versions of the chart will follow semantic versioning; breaking value changes will result in a major version bump and will be documented in a compatibility/migration guide + +## Rejected alternatives + +**Single monolithic StreamsHub chart (immediate)** +Jumping directly to a full StreamsHub umbrella chart that includes Strimzi, Kafka, and Prometheus was considered but rejected for the initial phase. +Managing other chart dependencies increases complexity and introduces coupling to third-party release cycles. +Starting with a focused Console operator chart allows us to establish chart quality and release processes before taking on a broader scope. \ No newline at end of file From 90b3be2047e25f5d51259c8065feaf3f06337447 Mon Sep 17 00:00:00 2001 From: jkalinic Date: Thu, 5 Mar 2026 15:18:47 +0100 Subject: [PATCH 2/6] Fix validation, add entry Signed-off-by: jkalinic # Conflicts: # README.md --- README.md | 1 + 1 file changed, 1 insertion(+) diff --git a/README.md b/README.md index 2c15bf1..c9c10c5 100644 --- a/README.md +++ b/README.md @@ -15,4 +15,5 @@ File name format and numbering is validated by the CI workflow defined in [valid | 000 | [StreamsHub Proposal Template](./000-template.md) | | 001 | [StreamsHub Quick-start Kustomize Repository](./001-quickstart-kustomize-repo.md) | | 002 | [StreamsHub MCP: Strimzi MCP proposal](./002-streamshub-mcp-strimzi.md) | +| 003 | [StreamsHub Console Helm](./001-streamshub-console-helm.md) | From ae3cc903a9d94cba93355ab8915994558c6a62ff Mon Sep 17 00:00:00 2001 From: jkalinic Date: Mon, 16 Mar 2026 22:50:13 +0100 Subject: [PATCH 3/6] addressed comments and ideas Signed-off-by: jkalinic --- 001-streamshub-console-helm.md | 86 +++++++++++++++++++++++----------- 1 file changed, 58 insertions(+), 28 deletions(-) diff --git a/001-streamshub-console-helm.md b/001-streamshub-console-helm.md index dd54617..ed58941 100644 --- a/001-streamshub-console-helm.md +++ b/001-streamshub-console-helm.md @@ -1,7 +1,7 @@ # Helm Installation Support for StreamsHub Console This proposal outlines adding official Helm chart support for the StreamsHub Console operator and its Custom Resources (CRs). -This would provide a standardized installation method and lay the foundation for a broader StreamsHub Helm ecosystem. +It provides a standardized installation method and establishes CRD lifecycle management patterns. ## Current situation @@ -19,8 +19,6 @@ By introducing an official Helm chart for the Console operator and CRs, StreamsH - **Lower the barrier to adoption** for teams already using Helm-based workflows and environments - **Enable fine-tuned configuration** with value overrides, environment-specific configuration, and lifecycle management via Helm - **Align with ecosystem standards**, making StreamsHub easier to discover and integrate -- **Unlock the possibility for a future StreamsHub Helm chart** — once the Console operator has its own chart, it becomes easier to compose a top-level `streamshub` chart -that depends on Console, Strimzi, Kafka, Prometheus, and other components, enabling full-stack deployment through a single `helm install` command ## Proposal @@ -34,31 +32,55 @@ The proposal is to create and maintain an official Helm chart repo for: The initial implementation should be deliberately scoped and simple. It should cover: - Operator's `Deployment`, `ServiceAccount`, `ClusterRole`, and `ClusterRoleBinding` -- CRD installation (either bundled or as a dependency) -- A Console CR that can be optionally deployed alongside the operator by passing a Helm value (e.g. console.instance=true), allowing users who prefer to manage the CR separately to do so +- CRD installation — see the [CRD Management](#crd-management) section below for the chosen approach -- The chart should **not** attempt to manage external dependencies such as Strimzi, Kafka, or Prometheus in this initial phase. -Those components have already well-maintained charts and could be addressed in a follow-up effort. +The chart will **not** attempt to manage external dependencies such as Strimzi, Kafka, or Prometheus in this initial phase. +Those components have well-maintained charts and can be addressed in a separate proposal. -### Possible Future: StreamsHub Umbrella Chart +## CRD Management -Once official charts exist for the Console operator and operands, it becomes possible to introduce a `streamshub` -umbrella Helm chart that composes the full stack. This chart would declare Helm dependencies on: +CRD lifecycle management in Helm has known limitations that need to be addressed explicitly. +Understanding these is important both for the standalone chart and for potential future use as a subchart. -- `streamshub-console` (this proposal) -- `strimzi-kafka-operator` (official Strimzi chart) -- `kafka` / `kraft` via Strimzi CRs -- `prometheus` or equivalent monitoring -- `apicurio` or equivalent schema registries -- Any other components managed by StreamsHub +### The Core Problem -This umbrella chart would give users an easy way to deploy the entire stack, significantly improving the onboarding experience and enabling catalogue listings on platforms like Artifact Hub. +Helm's built-in CRD support — placing CRDs in the `crds/` directory — has two significant limitations: -### Delivery +1. **CRDs in `crds/` are not upgraded during `helm upgrade`**. This creates version drift risk: a new operator release may depend on an updated CRD schema or a new stored version that is not present in the cluster after a routine upgrade. +2. **CRDs in subcharts are silently skipped**. If this chart is later used as a subchart in an umbrella chart, Helm only processes CRDs from the top-level chart's `crds/` directory. Any CRDs in subchart `crds/` directories are silently ignored on install, meaning the Console CRDs would not be present when the operator tries to reconcile. + +### Options Considered + +**Option 1 — `crds/` directory (Strimzi pattern)** + +Place CRDs in the `crds/` directory, consistent with Strimzi's approach. CRDs are installed on `helm install` but require explicit user actions (e.g. `kubectl apply`) for upgrades. +This is an established and well-understood pattern, but it does require users to be aware of the manual upgrade step. + +**Option 2 — Dedicated `streamshub-crds` chart (cert-manager pattern)** + +Package CRDs as a separate `streamshub-crds` Helm chart, similar to the approach used by cert-manager. +This chart can be installed and upgraded independently from the operator chart, giving full control over CRD lifecycle. +It also cleanly solves the future subchart problem: an umbrella chart could declare a dependency on `streamshub-crds` directly, ensuring CRDs are always installed at the top level regardless of how the operator chart is composed. + +**Option 3 — Pre-install hook Job** + +A `pre-install` / `pre-upgrade` hook Job that applies CRDs via `kubectl apply`. +This gives the most control over upgrade ordering but adds complexity and requires appropriate RBAC for the hook Job to manage resources. + +### Recommended Approach + +The recommended initial approach is **Option 1** — the `crds/` directory pattern, consistent with how Strimzi manages its CRDs. + +The CRD upgrade limitation must be explicitly documented: users must manually apply updated CRDs before upgrading the operator chart (e.g. `kubectl apply -f crds/`). +Again, this is the same pattern Strimzi uses and is a known trade off in the Helm ecosystem. + +> Note: Option 2 (a dedicated `streamshub-crds` chart) should be revisited if and only when an umbrella chart is proposed, as it provides the cleanest solution to the subchart CRD visibility problem and avoids duplicating CRD definitions across charts. + +## Delivery - Charts to be hosted within the StreamsHub GitHub organisation, either in a dedicated `helm-charts` repository under a `${PROJECT_NAME}-charts/` directory - Charts published to a Helm repository (like GitHub Pages or `oci` variants like Quay / DockerHub) + Artifact Hub following each release -- Chart versioning to follow the operator release cycle, with independent patch versioning where chart-only fixes are needed +- **Chart versioning to be independent from the operator version**. Chart and operator versions will naturally diverge over time (e.g. chart fixes). Independent versioning avoids confusion from the start. A clear mapping between chart versions and compatible operator versions will be maintained on the release page and in the documentation. - A GitHub Actions workflow can be introduced to lint chart using helm lint on every pull request/release, catching templating errors and schema violations early - A minimal deployment test will run on each push, spinning up a light k8s cluster (kind or minikube might be the best options) and verifying that the operator and Console CR deploy and reach a healthy state - Chart releases will be automated using github action workflows, allowing the Console operator chart to be tested and published to the StreamsHub Helm repository @@ -66,21 +88,29 @@ This umbrella chart would give users an easy way to deploy the entire stack, sig ## Affected/not affected projects **Affected:** -- `streamshub/console` — primary subject of this proposal - the operator and Console CR chart will live in or alongside this repository -- StreamsHub documentation — installation guides will need updating to include Helm-based instructions +- `console` — primary subject of this proposal; the operator and Console CR chart will live in this repository +- `documentation` — installation guides will need updating to include Helm-based instructions, including the CRD upgrade procedure -**Not affected (at this stage):** -- Strimzi, Apicurio, Prometheus, and other stack components — remain independently managed and they will only be referenced if the future umbrella chart is taken forward +**Not affected:** +- Strimzi, Apicurio, Prometheus, and other stack components — remain independently managed ## Compatibility - CRD management will follow Helm community best practices (CRDs in `crds/` directory) to avoid conflicts with existing CRD installations - The chart will declare a minimum supported k8s version consistent with the operator's existing requirements -- Future versions of the chart will follow semantic versioning; breaking value changes will result in a major version bump and will be documented in a compatibility/migration guide +- Chart versioning follows semantic versioning independently from the operator; breaking value changes will result in a major version bump and will be documented in a compatibility/migration guide ## Rejected alternatives -**Single monolithic StreamsHub chart (immediate)** -Jumping directly to a full StreamsHub umbrella chart that includes Strimzi, Kafka, and Prometheus was considered but rejected for the initial phase. -Managing other chart dependencies increases complexity and introduces coupling to third-party release cycles. -Starting with a focused Console operator chart allows us to establish chart quality and release processes before taking on a broader scope. \ No newline at end of file +**StreamsHub umbrella chart (deferred to a separate proposal)** + +Including an umbrella chart that composes Strimzi, Kafka, Prometheus, and other dependencies was considered but removed from this proposal. +The CRD lifecycle limitations like upgrade skipping, silent subchart skipping, and the complexity of keeping a multi-operator stack in sync. +These are not trivial and deserve a dedicated proposal and design discussion. +Any future umbrella chart proposal should address the CRD subchart problem directly. The dedicated `streamshub-crds` chart pattern described above is a candidate solution. + + +**CRD hook Job approach** + +A hook Job for CRD management was considered but deferred in favour of the simpler `crds/` directory pattern for the initial release. +The hook approach adds operational complexity and RBAC requirements that are not justified at this stage. \ No newline at end of file From 9ca05d8f3176c9491f3dd66a906f6981ca3b62b5 Mon Sep 17 00:00:00 2001 From: jkalinic Date: Tue, 7 Apr 2026 13:38:38 +0200 Subject: [PATCH 4/6] update proposal, address crds and jakub comments Signed-off-by: jkalinic --- ...streamshub-console-helm.md => 003-streamshub-console-helm.md | 0 README.md | 2 +- 2 files changed, 1 insertion(+), 1 deletion(-) rename 001-streamshub-console-helm.md => 003-streamshub-console-helm.md (100%) diff --git a/001-streamshub-console-helm.md b/003-streamshub-console-helm.md similarity index 100% rename from 001-streamshub-console-helm.md rename to 003-streamshub-console-helm.md diff --git a/README.md b/README.md index c9c10c5..352790d 100644 --- a/README.md +++ b/README.md @@ -15,5 +15,5 @@ File name format and numbering is validated by the CI workflow defined in [valid | 000 | [StreamsHub Proposal Template](./000-template.md) | | 001 | [StreamsHub Quick-start Kustomize Repository](./001-quickstart-kustomize-repo.md) | | 002 | [StreamsHub MCP: Strimzi MCP proposal](./002-streamshub-mcp-strimzi.md) | -| 003 | [StreamsHub Console Helm](./001-streamshub-console-helm.md) | +| 003 | [StreamsHub Console Helm](./003-streamshub-console-helm.md) | From 26eb423ddf6c21c74f76dfef8d6568b014accf55 Mon Sep 17 00:00:00 2001 From: jkalinic Date: Tue, 7 Apr 2026 14:01:28 +0200 Subject: [PATCH 5/6] update proposal, address crds and jakub comments Signed-off-by: jkalinic --- 003-streamshub-console-helm.md | 123 +++++++++++++++++---------------- 1 file changed, 64 insertions(+), 59 deletions(-) diff --git a/003-streamshub-console-helm.md b/003-streamshub-console-helm.md index ed58941..a5bc968 100644 --- a/003-streamshub-console-helm.md +++ b/003-streamshub-console-helm.md @@ -1,20 +1,20 @@ # Helm Installation Support for StreamsHub Console -This proposal outlines adding official Helm chart support for the StreamsHub Console operator and its Custom Resources (CRs). -It provides a standardized installation method and establishes CRD lifecycle management patterns. +This proposal outlines adding official Helm chart support for the StreamsHub Console operator. +It provides a standardized installation method and establishes CRD lifecycle management patterns. ## Current situation There is currently no official Helm chart for the StreamsHub Console operator or its associated Custom Resources. -Among the broader StreamsHub stack, only Strimzi provides an official Helm chart. +Among the broader StreamsHub stack, only Strimzi provides an official Helm chart. Components such as Strimzi, Prometheus, and other dependencies each maintain their own Helm charts through their respective upstream projects. ## Motivation Helm is widely adopted as the standard packaging mechanism for k8s applications. -A large portion of the k8s ecosystem — including GitOps platforms (e.g. Argo CD) and cloud provider marketplaces — relies on Helm as the primary installation mechanism. +A large portion of the k8s ecosystem - including GitOps platforms (e.g. Argo CD) and cloud provider marketplaces - relies on Helm as the primary installation mechanism. -By introducing an official Helm chart for the Console operator and CRs, StreamsHub could: +By introducing an official Helm chart for the Console operator, StreamsHub could: - **Lower the barrier to adoption** for teams already using Helm-based workflows and environments - **Enable fine-tuned configuration** with value overrides, environment-specific configuration, and lifecycle management via Helm @@ -22,95 +22,100 @@ By introducing an official Helm chart for the Console operator and CRs, StreamsH ## Proposal -The proposal is to create and maintain an official Helm chart repo for: +The proposal is to create and maintain an official Helm chart for the **StreamsHub Console Operator** - managing its deployment, RBAC, service accounts, and associated configuration. -1. **The StreamsHub Console Operator** — managing its deployment, RBAC, service accounts, and associated configuration -2. **The Console Custom Resource (CR)** — exposing the Console instance configuration as Helm values, allowing users to customise the Console without editing raw YAML manifests - -### Scope of initial chart(s) +### Scope of initial chart The initial implementation should be deliberately scoped and simple. It should cover: - Operator's `Deployment`, `ServiceAccount`, `ClusterRole`, and `ClusterRoleBinding` -- CRD installation — see the [CRD Management](#crd-management) section below for the chosen approach +- CRD installation - see the [CRD Management](#crd-management) section below for the chosen approach -The chart will **not** attempt to manage external dependencies such as Strimzi, Kafka, or Prometheus in this initial phase. +The chart will **not** attempt to manage external dependencies such as Strimzi, Kafka, Prometheus, or other stack components in this initial phase. Those components have well-maintained charts and can be addressed in a separate proposal. - -## CRD Management - -CRD lifecycle management in Helm has known limitations that need to be addressed explicitly. + +> Note on Prometheus: although Prometheus is a significant dependency for the Console, it has a well-maintained upstream chart and introduces operator-level complexity (CRDs, RBAC) that is out of scope here. Including it is deferred to a possible future proposal. + +### Chart hosting + +The chart will live **within the `console` repository**, consistent with how Strimzi manages its Helm chart. +This keeps chart changes co-located with operator changes, making it straightforward to keep the chart in sync with new operator releases and to run system tests that validate the chart against each new version. + +Charts will be published to a Helm repository (GitHub Pages or an OCI registry such as Quay or DockerHub) and listed on Artifact Hub following each release. + +### Chart versioning + +Chart versioning will be **independent from the operator version**. + +Chart and operator versions will naturally diverge over time - for example, when a chart only fix is needed without an operator release. +Starting from an independent versioning scheme avoids confusion from the outset. +A clear mapping between chart versions and compatible operator versions will be maintained on the release page and in the documentation. + +## CRD management + +CRD lifecycle management in Helm has known limitations that need to be addressed explicitly. Understanding these is important both for the standalone chart and for potential future use as a subchart. -### The Core Problem +### The core CRDs problem -Helm's built-in CRD support — placing CRDs in the `crds/` directory — has two significant limitations: +Helm's built-in CRD support - placing CRDs in the `crds/` directory - has two significant limitations: 1. **CRDs in `crds/` are not upgraded during `helm upgrade`**. This creates version drift risk: a new operator release may depend on an updated CRD schema or a new stored version that is not present in the cluster after a routine upgrade. 2. **CRDs in subcharts are silently skipped**. If this chart is later used as a subchart in an umbrella chart, Helm only processes CRDs from the top-level chart's `crds/` directory. Any CRDs in subchart `crds/` directories are silently ignored on install, meaning the Console CRDs would not be present when the operator tries to reconcile. -### Options Considered - -**Option 1 — `crds/` directory (Strimzi pattern)** - -Place CRDs in the `crds/` directory, consistent with Strimzi's approach. CRDs are installed on `helm install` but require explicit user actions (e.g. `kubectl apply`) for upgrades. -This is an established and well-understood pattern, but it does require users to be aware of the manual upgrade step. - -**Option 2 — Dedicated `streamshub-crds` chart (cert-manager pattern)** - -Package CRDs as a separate `streamshub-crds` Helm chart, similar to the approach used by cert-manager. -This chart can be installed and upgraded independently from the operator chart, giving full control over CRD lifecycle. -It also cleanly solves the future subchart problem: an umbrella chart could declare a dependency on `streamshub-crds` directly, ensuring CRDs are always installed at the top level regardless of how the operator chart is composed. +### Recommended approach -**Option 3 — Pre-install hook Job** +The recommended approach is the **`crds/` directory pattern**, consistent with how Strimzi manages its CRDs. -A `pre-install` / `pre-upgrade` hook Job that applies CRDs via `kubectl apply`. -This gives the most control over upgrade ordering but adds complexity and requires appropriate RBAC for the hook Job to manage resources. - -### Recommended Approach - -The recommended initial approach is **Option 1** — the `crds/` directory pattern, consistent with how Strimzi manages its CRDs. - -The CRD upgrade limitation must be explicitly documented: users must manually apply updated CRDs before upgrading the operator chart (e.g. `kubectl apply -f crds/`). -Again, this is the same pattern Strimzi uses and is a known trade off in the Helm ecosystem. - -> Note: Option 2 (a dedicated `streamshub-crds` chart) should be revisited if and only when an umbrella chart is proposed, as it provides the cleanest solution to the subchart CRD visibility problem and avoids duplicating CRD definitions across charts. +CRDs are installed automatically on `helm install`. The CRD upgrade limitation must be explicitly documented: users must manually apply updated CRDs before upgrading the operator chart (e.g. `kubectl apply -f crds/`). +This is the exactly same pattern Strimzi uses and is an understood trade-off in the Helm ecosystem. ## Delivery -- Charts to be hosted within the StreamsHub GitHub organisation, either in a dedicated `helm-charts` repository under a `${PROJECT_NAME}-charts/` directory -- Charts published to a Helm repository (like GitHub Pages or `oci` variants like Quay / DockerHub) + Artifact Hub following each release -- **Chart versioning to be independent from the operator version**. Chart and operator versions will naturally diverge over time (e.g. chart fixes). Independent versioning avoids confusion from the start. A clear mapping between chart versions and compatible operator versions will be maintained on the release page and in the documentation. -- A GitHub Actions workflow can be introduced to lint chart using helm lint on every pull request/release, catching templating errors and schema violations early -- A minimal deployment test will run on each push, spinning up a light k8s cluster (kind or minikube might be the best options) and verifying that the operator and Console CR deploy and reach a healthy state -- Chart releases will be automated using github action workflows, allowing the Console operator chart to be tested and published to the StreamsHub Helm repository +- Chart to be hosted within the `console` repository, under a `helm/` or `charts/` directory +- Chart published to a Helm repository (GitHub Pages or OCI variants like Quay / DockerHub) + Artifact Hub following each release +- **Chart versioning to be independent from the operator version**, with a clear version compatibility mapping maintained in documentation and release notes +- A GitHub Actions workflow will lint the chart using `helm lint` on every pull request and release, catching templating errors and schema violations early +- A minimal deployment test will run on each push, spinning up a lightweight k8s cluster (kind or minikube) and verifying that the operator deploys and reaches a healthy state +- Chart releases will be automated using GitHub Actions, allowing the chart to be tested and published to the StreamsHub Helm repository following each release -## Affected/not affected projects +# Affected/not affected projects **Affected:** -- `console` — primary subject of this proposal; the operator and Console CR chart will live in this repository -- `documentation` — installation guides will need updating to include Helm-based instructions, including the CRD upgrade procedure +- `console` - primary subject of this proposal; the operator chart will live within this repository +- `documentation` - installation guides will need updating to include Helm-based instructions, including the CRD manual upgrade procedure **Not affected:** -- Strimzi, Apicurio, Prometheus, and other stack components — remain independently managed +- Strimzi, Apicurio, Prometheus, and other stack components - remain independently managed ## Compatibility - CRD management will follow Helm community best practices (CRDs in `crds/` directory) to avoid conflicts with existing CRD installations +- The CRD upgrade limitation is a known trade-off and will be clearly documented; users must manually apply updated CRDs before running `helm upgrade` - The chart will declare a minimum supported k8s version consistent with the operator's existing requirements - Chart versioning follows semantic versioning independently from the operator; breaking value changes will result in a major version bump and will be documented in a compatibility/migration guide ## Rejected alternatives + +**CR instance management via Helm (deferred)** + +An earlier version of this proposal included managing the Console Custom Resource (CR) instance as part of the Helm chart, exposing its configuration as Helm values. +This was removed from scope. Managing operator CRs via Helm leads to an unbounded configuration surface - every field of the CR becomes a potential Helm value, requiring huge ongoing maintenance and branching logic. +Strimzi does not manage its CRs via Helm for the same reasons. +Teams that want to manage their Console CR via GitOps workflows can do so directly against the CRD using standard tooling. **StreamsHub umbrella chart (deferred to a separate proposal)** -Including an umbrella chart that composes Strimzi, Kafka, Prometheus, and other dependencies was considered but removed from this proposal. -The CRD lifecycle limitations like upgrade skipping, silent subchart skipping, and the complexity of keeping a multi-operator stack in sync. -These are not trivial and deserve a dedicated proposal and design discussion. -Any future umbrella chart proposal should address the CRD subchart problem directly. The dedicated `streamshub-crds` chart pattern described above is a candidate solution. - +Including an umbrella chart that composes Strimzi, Kafka, Prometheus, and other dependencies was considered but removed from this proposal. +The CRD lifecycle limitations - upgrade skipping, silent subchart skipping, and the complexity of keeping a multi-operator stack in sync are not trivial and deserve a dedicated proposal and design discussion. +Any future umbrella chart proposal should address the subchart CRD visibility problem directly; the dedicated `streamshub-crds` chart pattern is a possible future candidate solution, but it has too much overhead for this proposal. **CRD hook Job approach** -A hook Job for CRD management was considered but deferred in favour of the simpler `crds/` directory pattern for the initial release. -The hook approach adds operational complexity and RBAC requirements that are not justified at this stage. \ No newline at end of file +A hook Job for CRD management was considered but deferred in favour of the simpler `crds/` directory pattern for the initial release. +The hook approach adds operational complexity and RBAC requirements that are not justified at this stage. + +**Dedicated `helm-charts` repository** + +Hosting the chart in a standalone `helm-charts` repository was considered but rejected in favour of keeping it within the `console` repository. +This location makes it easier to keep the chart in sync with operator releases and to run tests that validate the chart against each new version. \ No newline at end of file From 2d3960d900c9b6ef138f79e94b193bd3f84e28ed Mon Sep 17 00:00:00 2001 From: jkalinic Date: Thu, 9 Apr 2026 23:19:05 +0200 Subject: [PATCH 6/6] better chart versioning wording Signed-off-by: jkalinic --- .idea/.gitignore | 10 ++++++++++ .idea/checkstyle-idea.xml | 15 +++++++++++++++ .idea/misc.xml | 6 ++++++ .idea/modules.xml | 8 ++++++++ .idea/vcs.xml | 7 +++++++ 003-streamshub-console-helm.md | 7 ++++--- streamshub-proposals.iml | 11 +++++++++++ 7 files changed, 61 insertions(+), 3 deletions(-) create mode 100644 .idea/.gitignore create mode 100644 .idea/checkstyle-idea.xml create mode 100644 .idea/misc.xml create mode 100644 .idea/modules.xml create mode 100644 .idea/vcs.xml create mode 100644 streamshub-proposals.iml diff --git a/.idea/.gitignore b/.idea/.gitignore new file mode 100644 index 0000000..ab1f416 --- /dev/null +++ b/.idea/.gitignore @@ -0,0 +1,10 @@ +# Default ignored files +/shelf/ +/workspace.xml +# Ignored default folder with query files +/queries/ +# Datasource local storage ignored files +/dataSources/ +/dataSources.local.xml +# Editor-based HTTP Client requests +/httpRequests/ diff --git a/.idea/checkstyle-idea.xml b/.idea/checkstyle-idea.xml new file mode 100644 index 0000000..99d8224 --- /dev/null +++ b/.idea/checkstyle-idea.xml @@ -0,0 +1,15 @@ + + + + 13.3.0 + JavaOnly + + + \ No newline at end of file diff --git a/.idea/misc.xml b/.idea/misc.xml new file mode 100644 index 0000000..42957fa --- /dev/null +++ b/.idea/misc.xml @@ -0,0 +1,6 @@ + + + + + + \ No newline at end of file diff --git a/.idea/modules.xml b/.idea/modules.xml new file mode 100644 index 0000000..67e5bb1 --- /dev/null +++ b/.idea/modules.xml @@ -0,0 +1,8 @@ + + + + + + + + \ No newline at end of file diff --git a/.idea/vcs.xml b/.idea/vcs.xml new file mode 100644 index 0000000..8306744 --- /dev/null +++ b/.idea/vcs.xml @@ -0,0 +1,7 @@ + + + + + + + \ No newline at end of file diff --git a/003-streamshub-console-helm.md b/003-streamshub-console-helm.md index a5bc968..2edb47e 100644 --- a/003-streamshub-console-helm.md +++ b/003-streamshub-console-helm.md @@ -49,12 +49,13 @@ Chart versioning will be **independent from the operator version**. Chart and operator versions will naturally diverge over time - for example, when a chart only fix is needed without an operator release. Starting from an independent versioning scheme avoids confusion from the outset. +Chart versioning will follow the format - (e.g. 1.0.0 for the initial release, 1.0.0-1 if a chart-only fix follows). +This keeps the chart version anchored to the specific operator release it targets, while still allowing chart only patch releases without requiring an operator release. A clear mapping between chart versions and compatible operator versions will be maintained on the release page and in the documentation. ## CRD management CRD lifecycle management in Helm has known limitations that need to be addressed explicitly. -Understanding these is important both for the standalone chart and for potential future use as a subchart. ### The core CRDs problem @@ -63,9 +64,9 @@ Helm's built-in CRD support - placing CRDs in the `crds/` directory - has two si 1. **CRDs in `crds/` are not upgraded during `helm upgrade`**. This creates version drift risk: a new operator release may depend on an updated CRD schema or a new stored version that is not present in the cluster after a routine upgrade. 2. **CRDs in subcharts are silently skipped**. If this chart is later used as a subchart in an umbrella chart, Helm only processes CRDs from the top-level chart's `crds/` directory. Any CRDs in subchart `crds/` directories are silently ignored on install, meaning the Console CRDs would not be present when the operator tries to reconcile. -### Recommended approach +### Solution -The recommended approach is the **`crds/` directory pattern**, consistent with how Strimzi manages its CRDs. +CRDs will be managed using the **`crds/` directory pattern**, consistent with how Strimzi manages its CRDs. CRDs are installed automatically on `helm install`. The CRD upgrade limitation must be explicitly documented: users must manually apply updated CRDs before upgrading the operator chart (e.g. `kubectl apply -f crds/`). This is the exactly same pattern Strimzi uses and is an understood trade-off in the Helm ecosystem. diff --git a/streamshub-proposals.iml b/streamshub-proposals.iml new file mode 100644 index 0000000..33b20cb --- /dev/null +++ b/streamshub-proposals.iml @@ -0,0 +1,11 @@ + + + + + + + + + + + \ No newline at end of file