Use Helm charts through the Kix Helm bridge

Use kix.helmChart when you want Kix to fetch, render, and deploy an upstream Helm chart as part of a cluster definition.

This guide uses the Reflector chart. You need the chart repository, chart name, version, and Nix SRI hash.

Add the chart instance

Declare the chart as the instance’s package:

how-to/adoption/helm-bridge-cluster.nix

      instances.reflector-system.reflector = {
        package = kix.helmChart {
          repo = "https://emberstack.github.io/helm-charts";
          name = "reflector";
          version = "10.0.60";
          hash = "sha256-UdCVcUqJogyUYmGo1HnQ1fMxY7ZEV56+9wQSJfWOhVM=";
          releaseName = "reflector";
        };
      };

View source on GitHub ↗

The version and hash pin the chart archive. releaseName controls the release name passed to Helm and therefore affects names generated by the chart.

Pass chart values under the instance’s config.values attribute, using the option names and value types documented by the upstream chart.

Check the rendered chart

Evaluate the cluster and run Kix’s validation checks:

kix-examples/

❱ kix check how-to-helm-bridge
 TOOL       RESULT  DETAILS                      
 eval       pass    12 manifests evaluated       
 scorecard  pass    0 errors, 5 warnings, 2 info

Inspect one of the resources produced by the chart:

kix-examples/ output excerpt

❱ kix build how-to-helm-bridge --output json
{
  "apiVersion": "apps/v1",
  "kind": "Deployment",
  "metadata": {
    "name": "reflector",
    "namespace": "reflector-system",
    "labels": {
      "app.kubernetes.io/instance": "reflector",
      "app.kubernetes.io/managed-by": "kix",
      "app.kubernetes.io/name": "reflector",
      "app.kubernetes.io/version": "10.0.60"
    }
  },
  "spec": {
    "replicas": 1,
    "serviceAccountName": "reflector",
    "containers": [
      {
        "name": "reflector",
        "image": "docker.io/emberstack/kubernetes-reflector:10.0.60"
      }
    ]
  }
}

The rendered Deployment carries Kix’s cluster and package metadata. Kix also reconstructs dependencies between the chart’s ServiceAccounts, RBAC resources, Services, and workloads.

Deploy the chart

Deploy and inspect the package instance:

kix-examples/

❱ kix deploy how-to-helm-bridge

❱ kix status how-to-helm-bridge

❱ kubectl get deployment -n reflector-system reflector

When you update the chart, change version and hash together, run kix check, and review kix diff before deploying.

Kix picks the chart’s root resource: the only Service, or, with no Service, the only Deployment, StatefulSet, or DaemonSet. When the chart renders several, evaluation fails and lists them; name the one consumers connect to with root = { kind = "Service"; name = "<name>"; }; in the kix.helmChart arguments. Charts that need output builders or cross-chart dependencies should use a dedicated Kix package built with scope.helm.importChart.