Using nixhelm

nixhelm is a collection of Helm Charts that can be used with nix-kube-generators and as a result also nixidy. The charts are automatically updated to the most recent version by CI regularly.

To use with nixidy, pass the nixhelm derivation attribute set to nixidy's mkEnv builder like so.

flake.nix

{
  description = "My ArgoCD configuration with nixidy.";
  inputs.nixpkgs.url = "github:nixos/nixpkgs/nixos-unstable";
  inputs.flake-utils.url = "github:numtide/flake-utils";
  inputs.nixidy = {
    url = "github:arnarg/nixidy/latest";
    inputs.nixpkgs.follows = "nixpkgs";
  };
  inputs.nixhelm = {
    url = "github:farcaller/nixhelm";
    inputs.nixpkgs.follows = "nixpkgs";
  };
  outputs = {
    self,
    nixpkgs,
    flake-utils,
    nixidy,
    nixhelm,
  }: (flake-utils.lib.eachDefaultSystem (system: let
    pkgs = import nixpkgs {
      inherit system;
    };
  in {
    nixidyEnvs.dev = nixidy.lib.mkEnv {
      inherit pkgs;
      # Pass nixhelm to all nixidy modules.
      charts = nixhelm.chartsDerivations.${system};
      modules = [./env/dev.nix];
    };
  }));
}

Using nixidy without flakes

If you prefer not to use flakes, the following can be written to default.nix instead.

default.nix

let
  # With npins
  sources = import ./npins;
  # With niv
  # sources = import ./nix/sources.nix;

  # nixhelm added with:
  #   npins: `npins add github farcaller nixhelm --branch master`
  #   niv: `niv add github farcaller/nixhelm --branch master`
  nixhelm = sources.nixhelm;

  # Import nixidy
  nixidy = import sources.nixidy {};
in
  nixidy.lib.mkEnvs {
    # These modules get passed to every env.
    modules = [
      ({lib, ...}: {
        # nixhelm is a flake so we can't just import it
        # like we do in flakes (as an input).
        # Thankfully the directory structure in nixhelm
        # is compatible with the one expected by
        # `lib.helm.mkChartAttrs`.
        nixidy.charts = lib.helm.mkChartAttrs "${nixhelm}/charts";
      })
    ];

    # This declares the available nixidy envs.
    envs = {
      # Currently we only have the one dev env.
      dev.modules = [./env/dev.nix];
    };
  }

And then the argument charts will be passed to every module in nixidy.

./env/dev.nix

{
  charts,
  ...
}: {
  applications.traefik = {
    namespace = "traefik";
    createNamespace = true;

    helm.releases.traefik = {
      # Use the traefik helm chart from nixhelm.
      chart = charts.traefik.traefik;

      # Example values to pass to the Helm Chart.
      values = {
        ingressClass.enabled = true;
      };
    };
  };
}

Provide your own charts not available in nixhelm

Not all charts are available in nixhelm and in such cases you can contribute an initial version to them or setup a specific folder structure locally to merge with the charts argument passed to modules.

With the nixidy option nixidy.chartsDir that folder will be walked recursively and look for default.nix files that will build up the charts attribute set.

./charts/kubernetes-csi/csi-driver-nfs/default.nix

{
  repo = "https://raw.githubusercontent.com/kubernetes-csi/csi-driver-nfs/master/charts";
  chart = "csi-driver-nfs";
  version = "4.7.0";
  chartHash = "sha256-EU2qaZglUU3vxa41l1p/2yBscksIhYMr8kSgH8t0vL8=";
}

And then in your nixidy modules you pass that ./charts folder to nixidy.chartsDir.

./env/dev.nix

{charts, ...}: {
  # Point nixidy to a directory with charts to add to
  # the charts attribute set.
  nixidy.chartsDir = ../charts;

  # Use the nfs chart in an application.
  applications.csi-driver-nfs = {
    namespace = "kube-system";

    helm.releases.csi-driver-nfs = {
      chart = charts.kubernetes-csi.csi-driver-nfs;

      # Pass some values overrides to the chart.
      values = {};
    };
  };
}

Updating Charts

Each chart produced by mkChartAttrs carries an updateScript in its passthru that resolves the latest upstream version, recomputes the hash, and rewrites the chart's default.nix in place.

To update all charts at once, wrap the chart tree with mkChartsUpdateScript and expose it as a flake app:

flake.nix

{
  outputs = { self, nixpkgs, flake-utils, nixidy, ... }:
    flake-utils.lib.eachDefaultSystem (system:
      let
        pkgs = import nixpkgs { inherit system; };
        inherit (pkgs) lib;
      in {
        apps.updateCharts = {
          type = "app";
          program = lib.getExe (nixidy.packages.${system}.mkChartsUpdateScript
            (nixidy.packages.${system}.mkChartAttrs ./charts));
        };
      });
}

Then run:

nix run .#updateCharts

The script runs every chart's update script sequentially, continues past individual failures, and exits non-zero if any chart failed to update.

Using nixidy without flakes

Create a small derivation file and build it:

update-charts.nix

let
  sources = import ./npins;
  nixidy = import sources.nixidy {};
in
  nixidy.mkChartsUpdateScript (nixidy.mkChartAttrs ./charts)

nix-build update-charts.nix && ./result/bin/update-all-charts

Optional fields

Two optional fields can be set in a chart's default.nix to control update behaviour:

versionConstraint

A semver range (e.g. ">=4.7.0 <5.0.0") passed to helm show chart --version. The updater resolves the latest version matching the constraint instead of the absolute latest.

freeze

When true, the updater skips this chart entirely. Useful for charts you want to pin manually.

./charts/argoproj/argo-cd/default.nix

{
  repo = "https://argoproj.github.io/argo-helm/";
  chart = "argo-cd";
  version = "7.7.0";
  chartHash = "sha256-...";
  versionConstraint = ">=7.0.0 <8.0.0";
}

Store path resolution

The update script edits files in your working tree. When mkChartAttrs is given a path inside your repository, the script automatically maps the store path back to the corresponding working-tree relative path.

If the charts directory was copied into the store as a standalone entry, the working-tree path cannot be inferred. In that case set CHARTS_DIR at runtime:

CHARTS_DIR=./charts nix run .#updateCharts