khelm

A Helm chart templating CLI, helm to kustomize converter, kpt function and kustomize plugin.

Formerly known as "helm-kustomize-plugin".

Motivation / History

Helm charts provide a great way to share and reuse Kubernetes applications and there is a lot of them. However writing helm templates is cumbersome and you cannot reuse a chart properly if it does not yet support a particular parameter/value.

Kustomize solves these issues declaratively by merging Kubernetes API objects which grants users of a kustomization the freedom to change anything. However kustomize neither supports lifecycle management nor templating with externally passed in values (which is sometimes still required).

To overcome the gap between helm and kustomize initially this repository provided a kustomize plugin and k8spkg was used for lifecycle management.
Since kpt is published helm and kustomize can be run as (chained) kpt functions supporting declarative, GitOps-based workflows. kpt also supports dynamic modification of static (rendered) manifests with externally passed in values using setters as well as dependency and lifecycle management.

Features

• Templates/renders a Helm chart
• Builds local charts automatically when templating
• Automatically fetches and updates required repository index files when needed
• Allows to automatically reload dependencies when lock file is out of sync
• Allows to use any repository without registering it in repositories.yaml
• Allows to exclude certain resources from the Helm chart output
• Allows to enforce namespace-scoped resources within the template output
• Allows to enforce a namespace on all resources
• Allows to convert a chart's output into a kustomization

Supported interfaces

khelm can be used as:

• kpt function (recommended)
• kustomize exec plugin
• CLI
• Go API

Usage examples can be found in the example and e2e directories.

kpt function

The khelm kpt function templates a chart and returns the output as single manifest file or kustomization directory (when outputPath ends with /). The kustomization output can be used to apply further transformations by running a kustomize function afterwards.

In opposite to the kustomize plugin approach kpt function outputs can be audited reliably when committed to a git repository, a kpt function does not depend on particular plugin binaries on the host and CD pipelines can run without dependencies to rendering technologies and chart servers since they just apply static mainfests (and eventually change values using kpt cfg set) to a cluster using kpt live apply.

kpt function usage example

A kpt function can be declared as annotated ConfigMap within a kpt project. A kpt project can be initialized and used with such a function as follows:

mkdir example-project && cd example-project
kpt pkg init . # Creates the Kptfile
cat - > khelm-function.yaml <<-EOF
  apiVersion: v1
  kind: ConfigMap
  metadata:
    name: cert-manager-manifest-generator
    annotations:
      config.kubernetes.io/function: |
        container:
          image: mgoltzsche/khelm:latest
          network: true
      config.kubernetes.io/local-config: "true"
  data:
    repository: https://charts.jetstack.io
    chart: cert-manager
    version: 0.9.x
    name: my-cert-manager-release
    namespace: cert-manager
    values:
      webhook:
        enabled: false
    outputPath: output-manifest.yaml
EOF
kpt fn run --network . # Renders the chart into output-manifest.yaml

For all available fields see the table below.

Please note that, in case you need to refer to a local chart directory or values file, the source must be mounted to the function using e.g. kpt fn run --mount="type=bind,src=$(pwd),dst=/source,rw=true" ..
An example kpt project and the corresponding e2e test show how to do that.

Kpt can also be leveraged to pull charts from other git repositories into your own repository using the kpt pkg sync . command (with a corresponding dependency set up) before running the khelm function (for this reason the go-getter support has been removed from this project).

If necessary the chart output can be transformed using kustomize. This can be done by declaring the khelm and a kustomize function orderly within a file and specifying the chart output kustomization as input for the kustomize function as shown in the cert-manager example. A more complex example that also manages a Helm chart from another git repository locally as kpt dependency can be found here.

Caching Helm Charts and repository index files

When external Helm Charts are used the download of their repositories' index files and of the charts itself can take a significant amount of time that adds up when running multiple functions or calling a function frequently during development.
To speed this up caching can be enabled by mounting a host directory into the container at /helm, e.g. kpt fn run --mount "type=bind,src=$HOME/.khelm,dst=/helm,rw=true" . as also shown here.
Please be aware that the presence of /helm/repository/repositories.yaml enables a strict repository policy by default (see repository configuration). Therefore, to be independent of existing Helm 2 installations, a host's ~/.helm directory should not be mounted to /helm in most cases.

kustomize exec plugin

khelm can be used as kustomize exec plugin. Though plugin support in kustomize is still an alpha feature and may be removed in a future version.

Plugin installation

Install using curl (on OSX or Linux):

OS=$(uname | tr '[:upper:]' '[:lower:]')
ARCH=$(uname -m | sed 's/x86_64/amd64/; s/aarch64/arm64/')
mkdir -p $HOME/.config/kustomize/plugin/khelm.mgoltzsche.github.com/v2/chartrenderer
curl -fsSL https://github.com/mgoltzsche/khelm/releases/latest/download/khelm-${OS}-${ARCH} > $HOME/.config/kustomize/plugin/khelm.mgoltzsche.github.com/v2/chartrenderer/ChartRenderer
chmod +x $HOME/.config/kustomize/plugin/khelm.mgoltzsche.github.com/v2/chartrenderer/ChartRenderer

or using go:

go get github.com/mgoltzsche/khelm/v2/cmd/khelm
mkdir -p $HOME/.config/kustomize/plugin/khelm.mgoltzsche.github.com/v2/chartrenderer
mv $GOPATH/bin/khelm $HOME/.config/kustomize/plugin/khelm.mgoltzsche.github.com/v2/chartrenderer/ChartRenderer

Plugin usage example

A plugin descriptor specifies the helm repository, chart, version and values that should be used in a kubernetes-style resource can be referenced in the generators section of a kustomization.yaml and can look as follows:

apiVersion: khelm.mgoltzsche.github.com/v2
kind: ChartRenderer
metadata:
  name: cert-manager # fallback for `name`
  namespace: cert-manager # fallback for `namespace`
repository: https://charts.jetstack.io
chart: cert-manager
version: 0.9.x
values:
  webhook:
    enabled: false

For all available fields see the table below.

More complete examples can be found within the example directory. For instance cert-manager can be rendered like this:

kustomize build --enable-alpha-plugins github.com/mgoltzsche/khelm/example/cert-manager

When using kustomize 3 the option is called --enable_alpha_plugins.

CLI

khelm also supports a helm-like template CLI.

Binary installation

OS=$(uname | tr '[:upper:]' '[:lower:]')
ARCH=$(uname -m | sed 's/x86_64/amd64/; s/aarch64/arm64/')
curl -fsSL https://github.com/mgoltzsche/khelm/releases/latest/download/khelm-${OS}-${ARCH} > khelm
chmod +x khelm
sudo mv khelm /usr/local/bin/khelm

Binary usage example

khelm template cert-manager --version=0.9.x --repo=https://charts.jetstack.io

For all available options see the table below.

Docker usage example

docker run mgoltzsche/khelm:latest template cert-manager --version=0.9.x --repo=https://charts.jetstack.io

Go API

The khelm Go API github.com/mgoltzsche/khelm/v2/pkg/helm provides a simple templating interface on top of the Helm Go API. It exposes a Helm struct that provides a Render() function that returns the rendered resources as kyaml objects.

Configuration options

Repository configuration

Repository credentials can be configured using Helm's repositories.yaml which can be passed through as Secret to generic build jobs. khelm downloads the corresponding repo index files when needed.

When running khelm as kpt function or within a container the repositories.yaml should be mounted to /helm/repository/repositories.yaml.

Unlike Helm khelm allows usage of any repository when repositories.yaml is not present or --trust-any-repo (env var KHELM_TRUST_ANY_REPO) is enabled.

Helm support

• Helm 2 is supported by the v1 module version.
• Helm 3 is supported by the v2 module version.

Build and test

Build and test the khelm binary (requires Go 1.13) as well as the container image:

make clean khelm test check image e2e-test

The binary is written to build/bin/khelm.

Install the binary on your host at /usr/local/bin/khelm:

sudo make install