DOCSEARCHbyAlgolia
Submit Docs

fluxcd/helm-controller

repository·main·Indexed 19 days ago

https://github.com/fluxcd/helm-controller

A Kubernetes operator for the declarative management of Helm chart releases as part of a GitOps workflow. It automates Helm actions including install, upgrade, uninstall, rollback, and test using the HelmRelease custom resource. Key features include dependency management, drift detection, automated updates based on semver ranges, and post-rendering capabilities. It integrates with source-controller to fetch charts from Helm repositories, Git, Buckets, and OCI repositories.

Tokens
43.2K
Snippets
77
Records
142
Agent score
66%

What's inside helm-controller

  1. Overview of helm-controller

    main

    The helm-controller is a Kubernetes operator designed for the declarative management of Helm chart releases. It is a component of the Flux GitOps toolkit.

    Users define the desired state of a Helm release using a Kubernetes Custom Resource called HelmRelease. The controller monitors these resources and performs the necessary Helm actions (install, upgrade, rollback, etc.) to match the cluster state to the defined specification. It relies on source-controller to fetch Helm charts from various sources like Helm repositories, Git repositories, or Buckets.

  2. Overview of the Helm Controller

    main

    The Helm Controller is a Kubernetes operator designed to declaratively manage Helm chart releases using Kubernetes manifests. It automates Helm actions such as install, upgrade, uninstall, rollback, and test, while continuously reconciling the state of Helm releases to match the desired configuration.

    Key capabilities include:

    • Automated Reconciliation: Continuously ensures the cluster state matches the defined HelmRelease.
    • Dependency Management: Allows installing releases in a specific order (e.g., ensuring a service mesh is ready before deploying applications).
    • Suspension: Enables suspending reconciliation for specific releases during incidents without affecting the rest of the cluster.
    • Drift Detection: Performs in-cluster drift detection and correction if enabled.
    • Automated Updates: Supports automated chart updates based on semver ranges.
    • Alerting Integration: Works with the notification-controller to send alerts via webhooks based on HelmRelease status.

  3. Use the helm.toolkit.fluxcd.io/v2 API for Helm management

    main
    The helm.toolkit.fluxcd.io/v2 API is the specification used to declaratively manage Helm chart releases using Kubernetes manifests. It allows you to define the desired state of a Helm release within a HelmRelease Custom Resource (CR), which the helm-controller then reconciles.

  5. Use the helm.toolkit.fluxcd.io/v2beta2 API

    main

    The helm.toolkit.fluxcd.io/v2beta2 API is used to declaratively manage Helm chart releases using Kubernetes manifests. This API allows you to define the desired state of a Helm release (such as chart version, values, and dependency management) within a HelmRelease custom resource, which the helm-controller then reconciles.

    apiVersion: helm.toolkit.fluxcd.io/v2beta2
kind: HelmRelease
...

  6. Use the helm.toolkit.fluxcd.io/v2alpha1 API to manage Helm releases

    main

    The helm.toolkit.fluxcd.io/v2alpha1 API allows you to declaratively manage Helm chart releases using Kubernetes manifests. The primary resource for this is the HelmRelease Custom Resource Definition (CRD).

    Key capabilities of the HelmRelease resource include:

    • Helm release placement: Controlling where the release is installed.
    • Helm chart templates: Defining the chart source and version.
    • Values overrides: Providing custom configuration for the Helm chart.
    • Reconciliation control: Managing how the controller reacts to changes, including disabling resource waiting, managing dependencies, configuring Helm test actions, and setting up failure remediation.
    • Status tracking: Monitoring the state of the release via the resource status.

  7. What is a HelmRelease

    main

    The HelmRelease API (part of the helm.toolkit.fluxcd.io/v2 group) enables controller-driven reconciliation of Helm releases. It automates Helm actions such as install, upgrade, test, uninstall, and rollback.

    Key capabilities include:

    • Automated Reconciliation: Detects and corrects cluster state drift from the desired release state.
    • Artifact Management: Creates a HelmChart object from a specified source (like a HelmRepository) and watches it for changes.
    • Remediation: Supports configurable retries for failed install or upgrade operations.
    • Drift Detection: Can be configured to monitor the cluster and re-apply the desired state if manual changes are detected.
    • Automated Testing: Can automatically run Helm tests if they haven't been executed for the current release.
    apiVersion: helm.toolkit.fluxcd.io/v2
kind: HelmRelease

  9. Configure Helm release placement and naming

    main

    By default, a Helm release is deployed into the same namespace and with the same name as the HelmRelease resource. You can override these using:

    • spec.targetNamespace: The namespace where the release is deployed.
    • spec.releaseName: The name of the Helm release.

    Important: Setting spec.targetNamespace only changes where the release is deployed. The Helm storage (metadata/secrets for the release) is always stored in the metadata.namespace of the HelmRelease resource.

    If spec.targetNamespace is provided but spec.releaseName is not, the release name defaults to <spec.targetNamespace>-<metadata.name>.

  10. Understand HelmRelease lifecycle conditions

    main

    A HelmRelease uses Kubernetes Conditions to communicate its current state. Key conditions include:

    Reconciling

    Marked True when the controller is actively processing the release (e.g., installing, upgrading, detecting drift, or running tests).

    • Type: Reconciling
    • Reason: Progressing or ProgressingWithRetry
    • Note: This condition has negative polarity and is only present while the status is True.

    Ready

    Marked True when the release is installed, up-to-date, and all enabled tests have passed.

    • Type: Ready
    • Reason: InstallSucceeded, UpgradeSucceeded, or TestSucceeded

    Drifted

    Marked True if drift detection is enabled/warn and a drift is detected.

    • Type: Drifted
    • Reason: DriftDetected (if drifted) or NoDriftDetected (if not drifted).

    Failed

    Marked False when a Helm action or test fails.

    • Type: Ready (with status: "False")
    • Reason: InstallFailed, UpgradeFailed, or TestFailed.
    • Remediation: If a failure results in a rollback or uninstall, a Remediated condition is set to True with reasons like RollbackSucceeded or UninstallFailed.

  11. Handle spurious drift with upgrade force

    main

    Some Helm charts may trigger spurious drift detection because Helm fails to properly patch certain objects (e.g., related to Helm#5915).

    Instead of excluding the entire resource from drift detection, a more robust solution for some workloads is to set .spec.upgrade.force to true. This forces the recreation of resources during an upgrade, which can resolve patching inconsistencies.

    spec:
  upgrade:
    force: true

  12. Lifecycle and Garbage Collection of HelmReleases

    main

    The Helm Controller manages the lifecycle of resources and their associated Helm releases as follows:

    • Resource Deletion: When a HelmRelease custom resource is deleted from the cluster, the controller's garbage collector automatically removes the associated HelmChart and performs a Helm uninstall of the release.
    • Suspension: If a HelmRelease is marked as suspended, the controller stops reconciling it. However, deleting a suspended resource does not trigger a Helm uninstall; the release remains in the cluster.