• Stars
    star
    114
  • Rank 300,972 (Top 7 %)
  • Language
    Go
  • License
    Apache License 2.0
  • Created almost 5 years ago
  • Updated about 2 months ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

A Helm chart templating CLI, kustomize plugin and containerized kustomize/kpt KRM function

khelm GitHub workflow badge Go Report Card

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:

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

kpt function

khelm can be used as a containerized KRM function with kpt. The khelm function templates a chart and returns the output as single manifest file or kustomization directory (when outputPath ends with /) that kpt writes to disk.

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 to a cluster (e.g. using kpt live apply).

kpt function usage example

When using the khelm image directly with kpt, it must be invoked as an imperative function since it requires a chart to be mounted or network access to fetch a chart. This is shown as follows:

cat - > fn-config.yaml <<-EOF
  apiVersion: khelm.mgoltzsche.github.com/v2
  kind: ChartRenderer
  metadata:
    name: cert-manager-manifest-generator-config
  repository: https://charts.jetstack.io
  chart: cert-manager
  version: 0.9.x
  name: myrelease
  namespace: cert-manager
  values:
    webhook:
      enabled: false
  outputPath: output-manifest.yaml
EOF
kpt fn eval --image mgoltzsche/khelm:latest --fn-config fn-config.yaml --network .

For all available fields see the table below.

To use a local chart or values file, the source must be mounted to the function container using e.g. kpt fn eval --mount="type=bind,src=$(pwd),dst=/source,rw=true" --image mgoltzsche/khelm --fn-config fn-config.yaml ..
The kpt examples and corresponding e2e tests show how to do that.

To use khelm as a declarative function, you could distribute a container image that includes both khelm and your chart as shown in the declarative example.

kpt can also be leveraged to sync charts from other git repositories into your own repository using the kpt pkg get and kpt pkg update commands (with a corresponding dependency set up) before running the khelm function.

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" .. 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 but the ~/.helm/cache subdirectory into /helm/cache.

kustomize exec plugin

khelm can be used as kustomize exec plugin. Though plugin support in kustomize is still an alpha feature and may be slated to be deprecated in a future version (see KEP 2953).

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.

kustomize Containerized KRM Function

Similar to the kpt function approach, khelm can be used as Containerized KRM Function kustomize plugin. Though plugin support in kustomize is still an alpha feature, this form of extension seems destined to be graduated out of alpha (see KEP 2953).

This approach only works with kustomize>=v4.1.0.

Unlike the exec plugin strategy, this method does not require installation.

kustomize containerized KRM function 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
  namespace: cert-manager
  annotations:
    config.kubernetes.io/function: |
      container:
        image: mgoltzsche/khelm:latest
        network: true
repository: https://charts.jetstack.io
chart: cert-manager
name: my-cert-manager-release
namespace: 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/kustomize-krm directory.

For instance cert-manager can be rendered like this:

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

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

Field CLI Description
chart ARGUMENT Chart file (if repository not set) or name.
version --version Chart version. Latest version is used if not specified.
repository --repo URL to the repository the chart should be loaded from.
valueFiles -f Locations of values files.
values --set Set values object or in CLI key1=val1,key2=val2.
apiVersions --api-versions Kubernetes api versions used for Capabilities.APIVersions.
kubeVersion --kube-version Kubernetes version used for Capabilities.KubeVersion.
name --name Release name used to render the chart.
verify --verify If enabled verifies the signature of all charts using the keyring (see Helm 3 provenance and integrity).
keyring --keyring GnuPG keyring file (default ~/.gnupg/pubring.gpg).
replaceLockFile --replace-lock-file Remove requirements.lock and reload charts when it is out of sync.
include List of resource selectors that include matching resources from the output. If no selector specified all resources are included. Fails if a selector doesn't match any resource. Inclusions precede exclusions.
include[].apiVersion Includes resources by apiVersion.
include[].kind Includes resources by kind.
include[].namespace Includes resources by namespace.
include[].name Includes resources by name.
exclude List of resource selectors that exclude matching resources from the output. Fails if a selector doesn't match any resource.
exclude[].apiVersion Excludes resources by apiVersion.
exclude[].kind Excludes resources by kind.
exclude[].namespace Excludes resources by namespace.
exclude[].name Excludes resources by name.
excludeCRDs --skip-crds If true Custom Resource Definitions are excluded from the output.
excludeHooks --no-hooks If enabled excludes chart hooks from the output.
namespace --namespace Set the namespace used by Helm templates.
namespacedOnly --namespaced-only If enabled fail on known cluster-scoped resources and those of unknown kinds.
forceNamespace --force-namespace Set namespace on all namespaced resources (and those of unknown kinds).
outputPath --output Path to write the output to. If it ends with / a kustomization is generated. (Not supported by the kustomize plugin.)
outputPathMapping[].outputPath output path to which all resources should be written that match resourceSelectors. (Only supported by the kpt function.)
outputPathMapping[].selectors[].apiVersion Selects resources by apiVersion.
outputPathMapping[].selectors[].kind Selects resources by kind.
outputPathMapping[].selectors[].namespace Selects resources by namespace.
outputPathMapping[].selectors[].name Selects resources by name.
--output-replace If enabled replace the output directory or file (CLI-only).
--trust-any-repo If enabled repositories that are not registered within repositories.yaml can be used as well (env var KHELM_TRUST_ANY_REPO). Within the kpt function this behaviour can be disabled by mounting /helm/repository/repositories.yaml or disabling network access.
debug --debug Enables debug log and provides a stack trace on error.

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

More Repositories

1

podman-static

static podman binaries and container image
Dockerfile
207
star
2

ctnr

rootless runc-based container engine - deprecated in favour of podman
Go
32
star
3

rkt-compose

CLI to run Docker Compose file as pod on rkt with integrated service discovery using Consul - EOL
Go
24
star
4

slirp-cni-plugin

A user-mode network ("slirp") CNI plugin - container networking for unprivileged users
Go
17
star
5

jenkins-jnlp-slave

A jenkins JNLP slave with podman to provide rootless docker CLI support
Shell
15
star
6

beets-autogenre

beets plugin to auto-detect the genre for each item within your music library
Python
5
star
7

image-registry-operator

A kubernetes operator that manages image registries and access to them (alpha)
Go
3
star
8

hydra-spring-oauth2

oauth2 sample: ory hydra identity provider & spring boot resource server
Java
3
star
9

k8spkg

A Kubernetes component lifecycle manager CLI (deprecated in favour of kpt)
Go
3
star
10

fa-pap-xml-interpreter

A GUI and interpreter for the german tax office's program flow format. https://mgoltzsche.github.io/fa-pap-xml-interpreter/
HTML
2
star
11

mopidy-container

An opinionated, containerized mopidy bundle for Kubernetes (alpha)
Shell
2
star
12

kubemate

Experimental k3s-based Kubernetes distribution for IoT (alpha)
Go
2
star
13

k8storagex

host path and layered cache file system provisioner for distributed (CI) jobs on Kubernetes (alpha)
Go
2
star
14

liteide-docker

LiteIDE containerized: A fast reproducible Go development environment
Dockerfile
2
star
15

beets-ytimport

A beets plugin to import music from Youtube and SoundCloud
Python
2
star
16

gpg-helper

Letters instead of postcards! This little GnuPG 2 wrapper script helps you use PGP
Shell
1
star
17

kustomizr

kpt function container image to run kustomize builds
Go
1
star
18

hifiberry-detector

Containerized detect-hifiberry script from hifiberry-os (alpha)
Makefile
1
star
19

nodehack

A container image and DaemonSet to configure a host (for dev purposes)
Shell
1
star
20

runc-compose

CLI to compose runc containers
Go
1
star
21

beets-webm3u

A Beets plugin to serve M3U playlists via HTTP
Python
1
star
22

beets-webrouter

A Beets plugin to serve multiple web apps using a single process on the same port, each under a different path
Python
1
star
23

beets-container

An opinionated, containerized beets distribution
Makefile
1
star
24

conventional-release

A GitHub Action to automate releases based on Conventional Commits
Shell
1
star
25

highfipi

An SD card image to run Raspberry Pi based wireless Hifi speakers for multi-room audio
Makefile
1
star
26

coreos-setup

CoreOS setup for hetzner server
Shell
1
star
27

ktransform

Experimental K8s CRD and controller to transform Secrets and ConfigMaps using jq queries
Go
1
star
28

wifi-manager

Wifi manager linux container for a SoC/Raspberry Pi
Dockerfile
1
star
29

algorythm-cms

An old collection of experimental CMS modules - only valueable: a Maven plugin to build XAR packages
XSLT
1
star
30

file-service

Service to share and browse files using a JS UI and WebDAV based on nginx
JavaScript
1
star
31

stable-diffusion-container

Experimental stable diffusion linux container image (early alpha)
Makefile
1
star