The module lifecycle stage: Experimental
The module has requirements for installation
Before enabling the module, you need to allow the use of experimental modules in the deckhouse ModuleConfig. To do this, set the allowExperimentalModules parameter to true.
This guide describes how to work with the operator-helm module using cluster-wide resources.
Working with these custom resources requires permissions no lower than the SuperAdmin role.
In the granular role-based model (Deckhouse Platform 1.78 and later), managing HelmClusterAddon, HelmClusterAddonRepository and HelmClusterApplicationRepository resources requires the d8:subsystem:delivery:superadmin role. The d8:subsystem:delivery:viewer role grants read access to HelmClusterAddon, HelmClusterAddonChart and HelmClusterApplicationChart resources.
Adding an addon repository
A Helm repository is the entry point for every other resource. It contains Helm charts for a following installation in the cluster.
To add a new Helm addon repository, create a HelmClusterAddonRepository resource:
- Via command line
- Via web interface
Run the following command:
d8 k apply -f - <<EOF
apiVersion: helm.deckhouse.io/v1alpha1
kind: HelmClusterAddonRepository
metadata:
name: podinfo
spec:
url: https://stefanprodan.github.io/podinfo
EOF- Go to the “System” tab.
- Go to “Operator Helm” → “Addon Repositories”.
- Click the “Create” button.
- In the form that opens, enter an arbitrary repository name in the “Name” field.
- Enter the URL of the chart repository in the “URL” field.
- Click the “Apply” button.
Use one of the two schemes in the repository URL:
http(s)://: Helm repository that publishes anindex.yamlfile listing the available Helm charts.oci://: Repository of a single Helm chart in a container registry that supports storing Helm charts, for exampleoci://registry.example.com/charts/podinfo. The last path segment is the chart name, and the image tags are its versions.
After the HelmClusterAddonRepository resource is created, the module synchronizes the repository and creates a separate HelmClusterAddonChart object for each chart in the repository. To view the charts in a repository:
- Via command line
- Via web interface
Run the following command:
d8 k get helmclusteraddoncharts -l repository=podinfo --show-labelsExample output:
NAME AGE LABELS
podinfo-chart-podinfo-dfbe83e63b0b 11d chart=podinfo,heritage=deckhouse,repository=podinfoThe name of a catalog object is composed of the repository name, the chart name and a hash, so it is more convenient to select a chart by the repository and chart labels than by name.
The available chart versions are listed in its status. To see a list of versions, run the following command:
d8 k get helmclusteraddonchart -l repository=podinfo,chart=podinfo -o yamlExample output:
apiVersion: v1
items:
- apiVersion: helm.deckhouse.io/v1alpha1
kind: HelmClusterAddonChart
metadata:
creationTimestamp: "2026-10-30T07:13:31Z"
generation: 1
labels:
chart: podinfo
heritage: deckhouse
repository: podinfo
name: podinfo-chart-podinfo-dfbe83e63b0b
ownerReferences:
- apiVersion: helm.deckhouse.io/v1alpha1
blockOwnerDeletion: true
controller: true
kind: HelmClusterAddonRepository
name: podinfo
uid: e782d1df-cee1-4a35-bcb5-09c307bd06b4
resourceVersion: "95969705"
uid: 20111084-bc34-4f12-acbc-1f72cf328bc7
status:
versions:
- version: 6.17.0
- version: 6.16.0- Go to the “System” tab.
- Go to “Operator Helm” → “Addon Charts”.
Checking the repository state
The state of a repository is reflected by the conditions in its status (status.conditions). To assess the state of a repository:
- Via command line
- Via web interface
Run the following command:
d8 k get helmclusteraddonrepository podinfo -o yamlExample output:
apiVersion: helm.deckhouse.io/v1alpha1
kind: HelmClusterAddonRepository
metadata:
creationTimestamp: "2026-09-22T15:28:51Z"
finalizers:
- helm.deckhouse.io/cleanup
generation: 2
name: podinfo
resourceVersion: "48926557"
uid: 0fbfec2f-6669-40ba-a7ef-0cd223aabfca
spec:
url: https://stefanprodan.github.io/podinfo
status:
chartCount: 1
conditions:
- lastTransitionTime: "2026-09-22T15:28:52Z"
message: ""
observedGeneration: 2
reason: Success
status: "True"
type: Ready
- lastTransitionTime: "2026-09-22T15:28:51Z"
message: ""
observedGeneration: 2
reason: Success
status: "True"
type: Synced
lastSuccessfulSyncTime: "2026-09-22T15:28:51Z"
lastSyncedGeneration: 2
nextSyncTime: "2026-09-22T15:34:09Z"
observedGeneration: 2- Go to the “System” tab.
- Go to “Operator Helm” → “Addon Repositories”.
- Select the repository you need and hover over its status. The pop-up window shows information about its state.
Deploying an addon
To deploy an addon, create a HelmClusterAddon resource, specifying the repository, the chart name and version, and the namespace to deploy into:
- Via command line
- Via web interface
Run the following command:
d8 k apply -f - <<EOF
apiVersion: helm.deckhouse.io/v1alpha1
kind: HelmClusterAddon
metadata:
name: podinfo
spec:
namespace: test
chart:
helmClusterAddonChart: podinfo
helmClusterAddonRepository: podinfo
version: 6.10.2
EOF- Go to the “System” tab.
- Go to “Operator Helm” → “Addons”.
- Click the “Create” button.
- In the form that opens, enter an arbitrary addon name in the “Name” field.
- In the “Repository” field, select the repository holding the addon Helm charts.
- In the “Chart” field, select the Helm chart.
- In the “Version” field, select the Helm chart version.
- In the “Namespace” field, select the namespace the chart resources will be deployed into.
- Click the “Create” button.
You can adjust the Helm chart parameters if needed. To see the parameters used by default, click “Show default values” in the addon creation form.
Only one HelmClusterAddon instance using a given Helm chart from a given repository can be deployed at a time. However, different Helm charts from the same repository can be deployed simultaneously.
Checking the addon state
The state of an addon is reflected by the conditions in its status (status.conditions). To assess the state of an addon:
- Via command line
- Via web interface
Run the following command:
d8 k get helmclusteraddon podinfo -o yamlExample output:
apiVersion: helm.deckhouse.io/v1alpha1
kind: HelmClusterAddon
metadata:
annotations:
kubectl.kubernetes.io/last-applied-configuration: |
{"apiVersion":"helm.deckhouse.io/v1alpha1","kind":"HelmClusterAddon","metadata":{"annotations":{},"name":"podinfo"},"spec":{"chart":{"helmClusterAddonChart":"podinfo","helmClusterAddonRepository":"podinfo","version":"6.10.2"},"namespace":"test"}}
creationTimestamp: "2026-10-30T07:18:01Z"
finalizers:
- helm.deckhouse.io/cleanup
generation: 1
name: podinfo
resourceVersion: "95974870"
uid: ecf21939-1068-42de-a3a2-c812600f1303
spec:
chart:
helmClusterAddonChart: podinfo
helmClusterAddonRepository: podinfo
version: 6.10.2
namespace: test
status:
conditions:
- lastTransitionTime: "2026-10-30T07:18:19Z"
message: Helm install succeeded for release test/podinfo.v1 with chart podinfo@6.10.2
observedGeneration: 1
reason: Success
status: "True"
type: Ready
- lastTransitionTime: "2026-10-30T07:18:19Z"
message: Helm install succeeded for release test/podinfo.v1 with chart podinfo@6.10.2
observedGeneration: 1
reason: InstallSucceeded
status: "True"
type: Installed
inventory:
- apiVersion: apps/v1
kind: Deployment
name: podinfo
namespace: test
- apiVersion: v1
kind: Service
name: podinfo
namespace: test
lastAppliedChart:
helmClusterAddonChart: podinfo
helmClusterAddonRepository: podinfo
version: 6.10.2
observedGeneration: 1- Go to the “System” tab.
- Go to “Operator Helm” → “Addons”.
- Click the name of the addon you need. The addon page opens on the “Overview” tab. The “Lifecycle” block describes the current state of the release.
Adding a repository with application charts
By creating a HelmClusterApplicationRepository, a platform administrator can give namespace administrators centralized access to Helm charts. The Helm charts of such a repository become available to the administrators of every namespace for deploying HelmApplication.
To add an application chart repository, create a HelmClusterApplicationRepository resource:
- Via command line
- Via web interface
Run the following command:
d8 k apply -f - <<EOF
apiVersion: helm.deckhouse.io/v1alpha1
kind: HelmClusterApplicationRepository
metadata:
name: podinfo-shared
spec:
url: https://stefanprodan.github.io/podinfo
EOF- Go to the “System” tab.
- Go to “Operator Helm” → “Application Repositories”.
- Click the “Create” button.
- In the form that opens, enter an arbitrary repository name in the “Name” field.
- Enter the URL of the chart repository in the “URL” field.
- Click the “Apply” button.
Use one of the two schemes in the repository URL:
http(s)://: Helm repository that publishes anindex.yamlfile listing the available Helm charts.oci://: Repository of a single Helm chart in a container registry that supports storing Helm charts, for exampleoci://registry.example.com/charts/podinfo. The last path segment is the chart name, and the image tags are its versions.
The catalog of such a repository is published in HelmClusterApplicationChart resources. To list all Helm charts available in a repository:
- Via command line
- Via web interface
Run the following command:
d8 k get helmclusterapplicationcharts -l repository=podinfo-shared- Go to the “System” tab.
- Go to “Operator Helm” → “Application Repositories”.
- Select the repository you are interested in from the list and click its name.
- In the form that opens, the “Charts” tab shows the list of the available Helm charts.
For details on working with the charts in this repository, refer to the “User guide” page.
Connecting a private repository
To connect a private repository, specify the credentials and the TLS parameters in the repository specification. An example of configuring a repository with authentication and a self-signed certificate:
- Via command line
- Via web interface
Run the following command:
d8 k apply -f - <<EOF
apiVersion: helm.deckhouse.io/v1alpha1
kind: HelmClusterAddonRepository
metadata:
name: private
spec:
url: oci://registry.example.com/charts/podinfo
auth:
username: admin
password: secret
caCertificate: |
-----BEGIN CERTIFICATE-----
...
-----END CERTIFICATE-----
EOF- Go to the “System” tab.
- Go to “Operator Helm” → “Addon Repositories”.
- Click the “Create” button.
- In the form that opens, enter an arbitrary repository name in the “Name” field.
- Enter the URL of the chart repository in the “URL” field.
- In the “Authentication” section, specify the credentials for accessing the repository.
- In the “CA Certificate” section, specify the CA certificate in PEM format, or use the certificate upload form by clicking the “click to upload” link.
- Click the “Apply” button.
The credentials are stored in the resource in plain text. A user that has a read-level access to a repository can view its credentials as well.
Forcing reconciliation
While working with addons and repositories, you may need to force a reconciliation. In normal operation, reconciliation starts automatically whenever the resources are changed or the state of their dependencies changes.
For addons, a forced reconciliation can be useful if a terminal error occurred while deploying the addon or changing its settings. Without manual intervention, the module’s controllers make no further reconciliation attempts.
For repositories, a forced reconciliation lets you synchronize the repository without waiting for the next scheduled run.
- Via command line
- Via web interface
To force the reconciliation of a HelmClusterAddon, add the annotation reconcile.helm.deckhouse.io/force to it by running the following command:
d8 k annotate helmclusteraddon podinfo reconcile.helm.deckhouse.io/force="$(date -u +%Y-%m-%dT%H:%M:%SZ)" --overwriteTo force the reconciliation of a HelmClusterAddonRepository, add the annotation reconcile.helm.deckhouse.io/force to it by running the following command:
d8 k annotate helmclusteraddonrepository podinfo reconcile.helm.deckhouse.io/force="$(date -u +%Y-%m-%dT%H:%M:%SZ)" --overwriteThe annotation value is ignored. The module only checks that the annotation is present on the resource. The time stamp in the examples is only to make one request differ from another.
The processing of a forced reconciliation request is recorded in the status.lastForceReconcileTime field of the resource. The outcome is reflected in the Ready condition for an addon and in the Synced condition for a repository. For example:
d8 k get helmclusteraddon podinfo -o jsonpath='{.status.lastForceReconcileTime}'If the reconciliation of an addon stops at an error that retries cannot fix before the chart is processed (for example, UnsupportedRepositoryType), the module removes the annotation without updating the status.lastForceReconcileTime field. Check the Ready condition in that case.
To force the reconciliation of an addon:
- Go to the “System” tab.
- Go to “Operator Helm” → “Addons”.
- Select the addon you need and click the “Force Reconcile” icon.
The outcome of the forced reconciliation is shown in the “Status” column.
To force the reconciliation of an addon repository:
- Go to the “System” tab.
- Go to “Operator Helm” → “Addon Repositories”.
- Select the repository you need and click the “Force Reconcile” icon.
The outcome of the forced reconciliation is shown in the “Status” column.
Reconciliation can be very fast, so the web interface may not have time to show the status change. To make sure that the forced reconciliation request has been processed, check the value of the .status.lastForceReconcileTime field of the resource. The outcome of the synchronization is shown by the Ready and Synced conditions. To do this, click the name of the resource you are interested in and switch to the “YAML” tab in the form that opens.
Maintenance mode
Maintenance mode pauses the reconciliation of an addon, which lets you modify the release manually by adjusting the parameters of the previously deployed resources (such as the number of replicas and other parameters).
- Via command line
- Via web interface
To enable maintenance mode, run the following command:
d8 k patch helmclusteraddon podinfo --type=merge -p '{"spec":{"maintenance":"NoResourceReconciliation"}}'To check that maintenance mode is on, run the following command:
d8 k get helmclusteraddon podinfo -o jsonpath='{.status.conditions[?(@.type=="Managed")].reason}'Example of successful output:
MaintenanceModeActiveTo disable maintenance mode, run the following command:
d8 k patch helmclusteraddon podinfo --type=json -p '[{"op":"remove","path":"/spec/maintenance"}]'To check that maintenance mode is off, run the following command:
d8 k get helmclusteraddon podinfo -o jsonpath='{.status.conditions[?(@.type=="Managed")].reason}'Example of successful output:
MaintenanceModeInactiveTo manage the maintenance mode of an addon:
- Go to the “System” tab.
- Go to “Operator Helm” → “Addons”.
- Click the name of the addon you need.
- The “Maintenance” option is available on the “Configuration” tab.
An addon that is in maintenance mode gets the “Maintenance” status.
An addon in maintenance mode does not support forced reconciliation and cannot be deleted.