DOCSEARCHbyAlgolia
Submit Docs

k3s-io/helm-controller

repository·master·Indexed 19 days ago

https://github.com/k3s-io/helm-controller

A tool for managing Helm charts using Kubernetes Custom Resource Definitions (CRDs). It allows users to define Helm chart deployments declaratively via HelmChart and HelmChartConfig resources in the helm.cattle.io/v1 API. The controller supports namespaced and cluster-scoped deployments, value overrides via YAML or Kubernetes Secrets, and configurable failure policies.

Tokens
4.1K
Snippets
11
Records
17
Agent score
68%

What's inside helm-controller

  1. Override HelmChart values using HelmChartConfig

    master

    The HelmChartConfig resource allows you to provide additional configuration for a HelmChart that is managed by an external system. This is useful for injecting user-specific values into a chart without modifying the original HelmChart resource.

    Fields in HelmChartConfigSpec are merged with or override the corresponding fields in the related HelmChart resource:

    • values: Structured YAML overrides. Takes precedence over valuesContent.
    • valuesContent: Inline YAML string overrides.
    • valuesSecrets: An array of SecretSpec objects to load values from external Kubernetes Secrets.
    • failurePolicy: Configures handling of failed installations/upgrades (abort, reinstall, or retry).
    • serverSide: Controls server-side apply behavior (true, false, or auto).
    apiVersion: helm.cattle.io/v1
kind: HelmChartConfig
metadata:
  name: my-release-config
  ownerReferences:
    - apiVersion: helm.cattle.io/v1
      kind: HelmChart
      name: my-release
spec:
  values:
    ingress:
      enabled: true
  failurePolicy: retry

  3. Deploy the Helm Controller in Kubernetes

    master

    The Helm Controller can be deployed in two modes depending on the scope of visibility required for HelmChart CRDs:

    Namespaced Deployment

    Use the deploy-namespaced.yaml manifest (included in releases) to restrict the Helm Controller to a specific namespace. This locks the controller down so it only processes HelmChart CRDs within that namespace. The default namespace is helm-controller; you should modify this in the YAML before applying.

    Cluster Scoped Deployment

    Use the deploy-cluster-scoped.yaml manifest (included in releases) if you want the controller to watch the entire cluster for HelmChart CRD changes. By default, this deploys the controller into the kube-system namespace; update metadata.namespace in the manifest to change this.

  4. Build and test the Helm Controller

    master

    The project uses make for common development tasks:

    • make: The default target. It builds the binary and performs validation and testing.
    • make build: Builds the binary and optionally generates new CRDs if the API has changed.
    • make test: Runs the test suite.
    • make validate: Performs validation tasks.

  5. Run the Helm Controller locally

    master

    To run the Helm Controller as a local daemon, you must build the binary and provide a way to connect to a Kubernetes API. The controller requires either the --kubeconfig flag or the --masterurl flag to function. All CLI options have corresponding environment variables.

    Before running, ensure you have applied the necessary CRDs from ./pkg/crds/yaml/generated/ to your local cluster.

    go build -o ./bin/helm-controller
./bin/helm-controller --kubeconfig $HOME/.kube/config

  6. Run the helm-controller application

    master

    The helm-controller entrypoint initializes the application using the app package and executes it within a signal-aware context. It handles graceful shutdowns via signals.SetupSignalContext(). If the application exits due to an error other than a context cancellation (e.g., a user interrupt), it logs a fatal error using logrus.

    // Conceptual usage of the application entrypoint logic
app := app.New()
ctx := signals.SetupSignalContext()
if err := app.RunContext(ctx, os.Args); err != nil && !errors.Is(err, context.Canceled) {
	logrus.Fatal(err)
}

  7. Load Helm chart values from Kubernetes Secrets

    master

    You can override Helm chart values using data stored in Kubernetes Secrets via the valuesSecrets field in either HelmChart or HelmChartConfig.

    Each entry in the valuesSecrets array uses a SecretSpec:

    • name: The name of the Secret (must be in the same namespace as the HelmChart).
    • keys: An array of specific keys to read from the secret. If omitted, the entire secret is used.
    • ignoreUpdates: If true, the secret is treated as optional and changes to the secret will not trigger a chart upgrade.
    apiVersion: helm.cattle.io/v1
kind: HelmChart
metadata:
  name: my-app
spec:
  chart: my-chart
  valuesSecrets:
    - name: my-app-values-secret
      keys: ["config.yaml"]
      ignoreUpdates: false

  8. Configure a HelmChart deployment

    master

    The HelmChart resource is used to define the configuration and state for deploying a Helm chart. You specify the chart source (repository URL or HTTPS URL), the target namespace, and various overrides for the chart values.

    Key configuration options include:

    • chart: The name of the chart in a repository or a complete HTTPS URL to a .tgz archive.
    • repo: The URL of the Helm Chart repository.
    • version: The specific version of the chart to install.
    • targetNamespace: The namespace where the chart will be deployed.
    • createNamespace: If set to true, the controller will create the target namespace if it does not exist.
    • values: Structured YAML for overriding complex chart values.
    • set: A map of simple key-value pairs to override chart values (takes precedence over values).
    • failurePolicy: Determines what happens if an installation or upgrade fails. Options are abort (leave in failed state), reinstall (default: clean uninstall and reinstall), or retry (retry whenever configuration changes).
    apiVersion: helm.cattle.io/v1
kind: HelmChart
metadata:
  name: my-release
spec:
  chart: nginx
  repo: https://charts.bitnami.com/bitnami
  version: 15.0.0
  targetNamespace: bitnami
  createNamespace: true
  values:
    service:
      type: LoadBalancer
  set:
    replicaCount: "3"

  9. Reference: HelmChartConfigSpec fields

    master

    The HelmChartConfigSpec defines overrides for an existing HelmChart.

    # HelmChartConfigSpec Reference
- values (JSON): Override complex Chart values via structured YAML.
- valuesContent (string): Override complex Chart values via inline YAML content.
- valuesSecrets (SecretSpec array): Override complex Chart values via references to external Secrets.
- failurePolicy (Enum: [abort, reinstall, retry]): Handling of failed installations (default: reinstall).
- serverSide (Enum: [true, false, auto]): Enable server-side apply.
- forceConflicts (boolean): Force changes when conflicts arise in managed fields.

  11. Reference: HelmChartSpec fields

    master

    The HelmChartSpec defines the desired state for a Helm release. Below are the available configuration fields.

    # HelmChartSpec Reference
- targetNamespace (string): Helm Chart target namespace.
- createNamespace (boolean): Create target namespace if not present.
- chart (string): Helm Chart name or complete HTTPS URL to chart archive.
- version (string): Helm Chart version.
- repo (string): Helm Chart repository URL.
- repoCA (string): PEM-encoded CA Certificates string.
- repoCAConfigMap (LocalObjectReference): Reference to a ConfigMap containing CA Certificates.
- set (object): Override simple Chart values (keys: string, values: IntOrString).
- values (JSON): Override complex Chart values via structured YAML.
- valuesContent (string): Override complex Chart values via inline YAML content.
- valuesSecrets (SecretSpec array): Override complex Chart values via references to external Secrets.
- bootstrap (boolean): Set to True if this chart is needed to bootstrap the cluster.
- takeOwnership (boolean): Set to True to take ownership of existing resources.
- serverSide (Enum: [true, false, auto]): Enable server-side apply.
- forceConflicts (boolean): Force changes when conflicts arise in managed fields.
- chartContent (string): Base64-encoded chart archive .tgz.
- jobImage (string): Image to use for the helm job pod.
- backOffLimit (integer): Number of retries before considering the helm job failed.
- timeout (Duration): Timeout for Helm operations.
- failurePolicy (Enum: [abort, reinstall, retry]): Handling of failed installations.
- authSecret (LocalObjectReference): Reference to Secret for Basic auth credentials.
- authPassCredentials (boolean): Pass Basic auth credentials to all domains.
- insecureSkipTLSVerify (boolean): Skip TLS certificate checks.
- plainHTTP (boolean): Use insecure HTTP connections.
- dockerRegistrySecret (LocalObjectReference): Reference to Secret for OCI-based registry auth.
- podSecurityContext (PodSecurityContext): Custom PodSecurityContext for the helm job pod.
- securityContext (SecurityContext): Custom SecurityContext for the helm job pod.
- driver (Enum: [secret, configmap]): Helm storage driver (default: secret).