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 namespaced resources of the module, including chart repositories, their catalogs and applications.
Working with the custom resources of the module requires permissions of no lower than Admin role in a designated namespace.
In the granular role-based model (Deckhouse Platform 1.78 and later), the d8:namespace:admin role is enough to manage HelmApplication resources, while viewing and managing HelmApplicationRepository resources requires the d8:namespace:superadmin role.
Adding an application repository
A Helm application repository is the entry point for every other resource. It contains Helm charts for a following installation within a designated namespace.
To add a new Helm application repository, create a HelmApplicationRepository resource in the target namespace:
- Via command line
- Via web interface
Run the following command:
d8 k apply -f - <<EOF
apiVersion: helm.deckhouse.io/v1alpha1
kind: HelmApplicationRepository
metadata:
name: podinfo
namespace: test
spec:
url: https://stefanprodan.github.io/podinfo
EOF- Go to the “Projects” tab and select the project you need.
- Go to “Operator Helm” → “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 HelmApplicationRepository resource is created, the module synchronizes the repository and creates a separate HelmApplicationChart 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 -n test get helmapplicationcharts -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 -n test get helmapplicationchart -l repository=podinfo,chart=podinfo -o yamlExample output:
apiVersion: v1
items:
- apiVersion: helm.deckhouse.io/v1alpha1
kind: HelmApplicationChart
metadata:
creationTimestamp: "2026-10-30T07:21:58Z"
generation: 1
labels:
chart: podinfo
heritage: deckhouse
repository: podinfo
name: podinfo-chart-podinfo-dfbe83e63b0b
namespace: test
ownerReferences:
- apiVersion: helm.deckhouse.io/v1alpha1
blockOwnerDeletion: true
controller: true
kind: HelmApplicationRepository
name: podinfo
uid: 8e454e87-d937-4e22-85c2-6ed7ac7770ad
resourceVersion: "95980641"
uid: 9e88bbd3-2165-4d8b-b3d6-e05735800ff8
status:
versions:
- version: 6.17.0
- version: 6.16.0- Go to the “Projects” tab and select the project you need.
- Go to “Operator Helm” → “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 -n test get helmapplicationrepository podinfo -o yamlExample output:
apiVersion: helm.deckhouse.io/v1alpha1
kind: HelmApplicationRepository
metadata:
annotations:
kubectl.kubernetes.io/last-applied-configuration: |
{"apiVersion":"helm.deckhouse.io/v1alpha1","kind":"HelmApplicationRepository","metadata":{"annotations":{},"name":"podinfo","namespace":"test"},"spec":{"url":"https://stefanprodan.github.io/podinfo"}}
creationTimestamp: "2026-10-30T07:21:58Z"
finalizers:
- helm.deckhouse.io/cleanup
generation: 1
name: podinfo
namespace: test
resourceVersion: "95980699"
uid: 8e454e87-d937-4e22-85c2-6ed7ac7770ad
spec:
url: https://stefanprodan.github.io/podinfo
status:
chartCount: 1
conditions:
- lastTransitionTime: "2026-10-30T07:21:59Z"
message: ""
observedGeneration: 1
reason: Success
status: "True"
type: Ready
- lastTransitionTime: "2026-10-30T07:21:58Z"
message: ""
observedGeneration: 1
reason: Success
status: "True"
type: Synced
lastSuccessfulSyncTime: "2026-10-30T07:21:58Z"
lastSyncedGeneration: 1
nextSyncTime: "2026-10-30T07:26:34Z"
observedGeneration: 1- Go to the “Projects” tab and select the project you need.
- Go to “Operator Helm” → “Repositories”.
- Select the repository you need and hover over its status. The pop-up window shows information about its state.
Deploying an application
To deploy an application, create a HelmApplication resource in the same namespace, specifying the repository, chart name and version:
- Via command line
- Via web interface
Run the following command:
d8 k apply -f - <<EOF
apiVersion: helm.deckhouse.io/v1alpha1
kind: HelmApplication
metadata:
name: podinfo
namespace: test
spec:
chart:
name: podinfo
repository: podinfo
version: 6.10.2
EOFApplications can be deployed not only from the Helm charts of a repository local to the namespace, but also from a shared repository set up by a Deckhouse Platform administrator. Shared repositories are described with the HelmClusterApplicationRepository resource, and their catalog with HelmClusterApplicationChart resources.
Every user in a namespace has read-level access to HelmClusterApplicationChart.
To use a chart from a shared repository, specify the spec.chart.clusterRepository field instead of spec.chart.repository when describing the HelmApplication resource.
- Go to the “Projects” tab and select the project you need.
- Go to “Operator Helm” → “Applications”.
- Click the “Create” button.
- In the form that opens, enter an arbitrary resource name in the “Name” field.
- In the “Repository” field, select the repository holding the application Helm charts, or a shared application repository created by an administrator.
- In the “Chart” field, select the Helm chart.
- In the “Version” field, select the Helm chart version.
- Click the “Create” button.
Some repositories in the list may carry the “(cluster)” suffix. This means that the repository is shared (HelmClusterApplicationRepository) and was created by a Deckhouse Platform administrator.
You can adjust the Helm chart parameters if needed. To see the parameters used by default, click “Show default values” in the application creation form.
A HelmApplication is deployed with the permissions of the namespace administrator role. To do this, the module creates a RoleBinding resource in the application namespace that binds the application’s ServiceAccount to the d8:namespace:admin ClusterRole (d8:use:role:admin in Deckhouse Platform versions earlier than 1.78).
If these permissions are not sufficient to deploy the Helm chart, extend the permissions of the namespace administrator role. For details, refer to the user-authz module documentation.
Checking the application state
The state of an application is reflected by the conditions in its status (status.conditions). To assess the state of an application:
- Via command line
- Via web interface
Run the following command:
d8 k -n test get helmapplication podinfo -o yamlExample output:
apiVersion: helm.deckhouse.io/v1alpha1
kind: HelmApplication
metadata:
annotations:
kubectl.kubernetes.io/last-applied-configuration: |
{"apiVersion":"helm.deckhouse.io/v1alpha1","kind":"HelmApplication","metadata":{"annotations":{},"name":"podinfo","namespace":"test"},"spec":{"chart":{"name":"podinfo","repository":"podinfo","version":"6.10.2"}}}
creationTimestamp: "2026-10-30T07:23:43Z"
finalizers:
- helm.deckhouse.io/cleanup
generation: 1
name: podinfo
namespace: test
resourceVersion: "95984747"
uid: a52cad1f-0f40-46f7-8791-6d39ecf9c2ee
spec:
chart:
name: podinfo
repository: podinfo
version: 6.10.2
status:
conditions:
- lastTransitionTime: "2026-10-30T07:23:51Z"
message: Helm install succeeded for release test/hap-podinfo-3fb7b289386f.v1 with
chart podinfo@6.10.2
observedGeneration: 1
reason: Success
status: "True"
type: Ready
- lastTransitionTime: "2026-10-30T07:23:51Z"
message: Helm install succeeded for release test/hap-podinfo-3fb7b289386f.v1 with
chart podinfo@6.10.2
observedGeneration: 1
reason: InstallSucceeded
status: "True"
type: Installed
inventory:
- apiVersion: apps/v1
kind: Deployment
name: hap-podinfo-3fb7b289386f
namespace: test
- apiVersion: v1
kind: Service
name: hap-podinfo-3fb7b289386f
namespace: test
lastAppliedChart:
name: podinfo
repository: podinfo
version: 6.10.2
observedGeneration: 1- Go to the “Projects” tab and select the project you need.
- Go to “Operator Helm” → “Applications”.
- Click the name of the application you need. The application page opens on the “Overview” tab. The “Lifecycle” block describes the current state of the release.
Forcing reconciliation
While working with applications 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 applications, a forced reconciliation can be useful if a terminal error occurred while deploying the application 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 HelmApplication resource, add the annotation reconcile.helm.deckhouse.io/force to it by running the following command:
d8 k -n test annotate helmapplication podinfo reconcile.helm.deckhouse.io/force="$(date -u +%Y-%m-%dT%H:%M:%SZ)" --overwriteTo force the reconciliation of a HelmApplicationRepository, add the annotation reconcile.helm.deckhouse.io/force to it by running the following command:
d8 k -n test annotate helmapplicationrepository 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 application and in the Synced condition for a repository. For example:
d8 k -n test get helmapplication podinfo -o jsonpath='{.status.lastForceReconcileTime}'If the reconciliation of an application stops at an error that retries cannot fix before the chart is processed (for example, ForeignRBACObject or 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 application:
- Go to the “Projects” tab and select the project you need.
- Go to “Operator Helm” → “Applications”.
- Select the application 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 application repository:
- Go to the “Projects” tab and select the project you need.
- Go to “Operator Helm” → “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 application, 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 -n test patch helmapplication podinfo --type=merge -p '{"spec":{"maintenance":"NoResourceReconciliation"}}'To check that maintenance mode is on, run the following command:
d8 k -n test get helmapplication podinfo -o jsonpath='{.status.conditions[?(@.type=="Managed")].reason}'Example of successful output:
MaintenanceModeActiveTo disable maintenance mode, run the following command:
d8 k -n test patch helmapplication podinfo --type=json -p '[{"op":"remove","path":"/spec/maintenance"}]'To check that maintenance mode is off, run the following command:
d8 k -n test get helmapplication podinfo -o jsonpath='{.status.conditions[?(@.type=="Managed")].reason}'Example of successful output:
MaintenanceModeInactiveTo manage the maintenance mode of an application:
- Go to the “Projects” tab and select the project you need.
- Go to “Operator Helm” → “Applications”.
- Click the name of the application you need.
- The “Maintenance” option is available on the “Configuration” tab.
An application that is in maintenance mode gets the “Maintenance” status.
An application in maintenance mode does not support forced reconciliation and cannot be deleted. The only exception is deleting the namespace of the application: the application is then deleted together with it.