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:

      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:

Run in kix-examples/

❱ kix check how-to-helm-bridge
 TOOL         RESULT  DETAILS                                                       
 eval         pass    11 manifests evaluated                                        
 kubeconform  pass    skipped (this validation tool is not yet integrated with Kix) 
 pluto        pass    skipped (this validation tool is not yet integrated with Kix) 
 kyverno      pass    skipped (this validation tool is not yet integrated with Kix) 
 scorecard    pass    0 errors, 5 warnings, 2 info

Inspect one of the resources produced by the chart:

Run in 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:

Run in 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.

If evaluation reports a missing root resource or an invalid Kubernetes relationship, inspect the chart’s rendered resources. Charts that need custom root selection, output builders, or cross-chart dependencies should use a dedicated Kix package built with scope.helm.importChart.