github.com/mgoltzsche/khelm@v1.0.1/README.md (about) 1 # khelm ![GitHub workflow badge](https://github.com/mgoltzsche/khelm/workflows/Release/badge.svg) [![Go Report Card](https://goreportcard.com/badge/github.com/mgoltzsche/khelm)](https://goreportcard.com/report/github.com/mgoltzsche/khelm) 2 3 A [Helm](https://github.com/helm/helm) chart templating CLI, helm to kustomize converter, [kpt](https://github.com/GoogleContainerTools/kpt) function and [kustomize](https://github.com/kubernetes-sigs/kustomize/) plugin. 4 5 Formerly known as "helm-kustomize-plugin". 6 7 8 ## Motivation / History 9 10 [Helm](https://github.com/helm/helm) _charts_ provide a great way to share and reuse [Kubernetes](https://github.com/kubernetes/kubernetes) applications and there is a lot of them. 11 However writing helm templates is cumbersome and you cannot reuse a chart properly if it does not yet support a particular parameter/value. 12 13 [Kustomize](https://github.com/kubernetes-sigs/kustomize/) solves these issues declaratively by merging Kubernetes API objects which grants users of a _kustomization_ the freedom to change anything. 14 However kustomize neither supports lifecycle management nor templating with externally passed in values (which is sometimes still required). 15 16 To overcome the gap between helm and kustomize initially this repository provided a kustomize plugin and [k8spkg](https://github.com/mgoltzsche/k8spkg) was used for lifecycle management. 17 Since [kpt](https://github.com/GoogleContainerTools/kpt) is [published](https://opensource.googleblog.com/2020/03/kpt-packaging-up-your-kubernetes.html) 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](https://googlecontainertools.github.io/kpt/guides/consumer/set/) as well as [dependency](https://googlecontainertools.github.io/kpt/reference/pkg/) and [lifecycle management](https://googlecontainertools.github.io/kpt/reference/live/). 18 19 20 ## Features 21 22 * Templates/renders a Helm chart 23 * Builds local charts automatically when templating 24 * Automatically fetches and updates required repository index files when needed 25 * Allows to automatically reload dependencies when lock file is out of sync 26 * Allows to use any repository without registering it in repositories.yaml 27 * Allows to exclude certain resources from the Helm chart output 28 * Allows to enforce namespace-scoped resources within the template output 29 * Allows to enforce a namespace on all resources 30 * Allows to convert a chart's output into a kustomization 31 32 ## Supported interfaces 33 34 khelm can be used as: 35 * [kpt function](#kpt-function) (recommended) 36 * [kustomize exec plugin](#kustomize-exec-plugin) 37 * [CLI](#cli) 38 * [Go API](#go-api) 39 40 Usage examples can be found in the [example](example) and [e2e](e2e) directories. 41 42 ### kpt function 43 44 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. 45 46 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`. 47 48 #### kpt function usage example 49 50 A kpt function can be declared as annotated _ConfigMap_ within a kpt project. 51 A kpt project can be initialized and used with such a function as follows: 52 ```sh 53 mkdir example-project && cd example-project 54 kpt pkg init . # Creates the Kptfile 55 cat - > khelm-function.yaml <<-EOF 56 apiVersion: v1 57 kind: ConfigMap 58 metadata: 59 name: cert-manager-manifest-generator 60 annotations: 61 config.kubernetes.io/function: | 62 container: 63 image: mgoltzsche/khelm:latest 64 network: true 65 config.kubernetes.io/local-config: "true" 66 data: 67 repository: https://charts.jetstack.io 68 chart: cert-manager 69 version: 0.9.x 70 name: my-cert-manager-release 71 namespace: cert-manager 72 values: 73 webhook: 74 enabled: false 75 outputPath: output-manifest.yaml 76 EOF 77 kpt fn run --network . # Renders the chart into output-manifest.yaml 78 ``` 79 _For all available fields see the [table](#configuration-options) below._ 80 81 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" .`. 82 An [example kpt project](example/kpt/test-cases) and the corresponding [e2e test](e2e/kpt-function-test.sh) show how to do that. 83 84 Kpt can also be leveraged to pull charts from other git repositories into your own repository using the `kpt pkg sync .` [command](https://googlecontainertools.github.io/kpt/reference/pkg/) (with a corresponding dependency set up) before running the khelm function (for this reason the go-getter support has been removed from this project). 85 86 If necessary the chart output can be transformed using kustomize. 87 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](example/kpt/cert-manager). 88 A more complex example that also manages a Helm chart from another git repository locally as kpt dependency can be found [here](example/kpt/linkerd). 89 90 #### Caching Helm Charts and repository index files 91 92 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. 93 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](example/kpt/cache-dependencies). 94 _Please be aware that the presence of `/helm/repository/repositories.yaml` enables a strict repository policy by default (see [repository configuration](#repository-configuration))._ 95 _Therefore, to be independent of existing Helm 2 installations, a host's `~/.helm` directory should not be mounted to `/helm` in most cases._ 96 97 ### kustomize exec plugin 98 99 khelm can be used as [kustomize](https://github.com/kubernetes-sigs/kustomize) [exec plugin](https://kubectl.docs.kubernetes.io/guides/extending_kustomize/execpluginguidedexample/). 100 Though plugin support in kustomize is still an alpha feature and may be removed in a future version. 101 102 #### Plugin installation 103 104 Install using curl (on OSX or Linux): 105 ```sh 106 OS=$(uname | tr '[:upper:]' '[:lower:]') 107 ARCH=$(uname -m | sed 's/x86_64/amd64/; s/aarch64/arm64/') 108 mkdir -p $HOME/.config/kustomize/plugin/khelm.mgoltzsche.github.com/v1/chartrenderer 109 curl -fsSL https://github.com/mgoltzsche/khelm/releases/latest/download/khelm-${OS}-${ARCH} > $HOME/.config/kustomize/plugin/khelm.mgoltzsche.github.com/v1/chartrenderer/ChartRenderer 110 chmod +x $HOME/.config/kustomize/plugin/khelm.mgoltzsche.github.com/v1/chartrenderer/ChartRenderer 111 ``` 112 or using `go`: 113 ```sh 114 go get github.com/mgoltzsche/khelm/cmd/khelm 115 mkdir -p $HOME/.config/kustomize/plugin/khelm.mgoltzsche.github.com/v1/chartrenderer 116 mv $GOPATH/bin/khelm $HOME/.config/kustomize/plugin/khelm.mgoltzsche.github.com/v1/chartrenderer/ChartRenderer 117 ``` 118 119 #### Plugin usage example 120 121 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: 122 ```yaml 123 apiVersion: khelm.mgoltzsche.github.com/v1 124 kind: ChartRenderer 125 metadata: 126 name: cert-manager # fallback for `name` 127 namespace: cert-manager # fallback for `namespace` 128 repository: https://charts.jetstack.io 129 chart: cert-manager 130 version: 0.9.x 131 values: 132 webhook: 133 enabled: false 134 ``` 135 _For all available fields see the [table](#configuration-options) below._ 136 137 More complete examples can be found within the [example](example) directory. 138 For instance `cert-manager` can be rendered like this: 139 ```sh 140 kustomize build --enable-alpha-plugins github.com/mgoltzsche/khelm/example/cert-manager 141 ``` 142 _When using kustomize 3 the option is called `--enable_alpha_plugins`._ 143 144 ### CLI 145 146 khelm also supports a helm-like `template` CLI. 147 148 #### Binary installation 149 ```sh 150 OS=$(uname | tr '[:upper:]' '[:lower:]') 151 ARCH=$(uname -m | sed 's/x86_64/amd64/; s/aarch64/arm64/') 152 curl -fsSL https://github.com/mgoltzsche/khelm/releases/latest/download/khelm-${OS}-${ARCH} > khelm 153 chmod +x khelm 154 sudo mv khelm /usr/local/bin/khelm 155 ``` 156 157 #### Binary usage example 158 ```sh 159 khelm template cert-manager --version=0.9.x --repo=https://charts.jetstack.io 160 ``` 161 _For all available options see the [table](#configuration-options) below._ 162 163 #### Docker usage example 164 ```sh 165 docker run mgoltzsche/khelm:latest template cert-manager --version=0.9.x --repo=https://charts.jetstack.io 166 ``` 167 168 ### Go API 169 170 The khelm Go API `github.com/mgoltzsche/khelm/pkg/helm` provides a simple templating interface on top of the Helm Go API. 171 It exposes a `Helm` struct that provides a `Render()` function that returns the rendered resources as `kyaml` objects. 172 173 ## Configuration options 174 175 | Field | CLI | Description | 176 | ----- | ---------- | ----------- | 177 | `chart` | ARGUMENT | Chart file (if `repository` not set) or name. | 178 | `version` | `--version` | Chart version. Latest version is used if not specified. | 179 | `repository` | `--repo` | URL to the repository the chart should be loaded from. | 180 | `valueFiles` | `-f` | Locations of values files. 181 | `values` | `--set` | Set values object or in CLI `key1=val1,key2=val2`. | 182 | `apiVersions` | `--api-versions` | Kubernetes api versions used for Capabilities.APIVersions. | 183 | `kubeVersion` | `--kube-version` | Kubernetes version used for Capabilities.KubeVersion. | 184 | `name` | `--name` | Release name used to render the chart. | 185 | `verify` | `--verify` | If enabled verifies the signature of all charts using the `keyring` (see [Helm 2 provenance and integrity](https://v2.helm.sh/docs/provenance/)). | 186 | `keyring` | `--keyring` | GnuPG keyring file (default `~/.gnupg/pubring.gpg`). | 187 | `replaceLockFile` | `--replace-lock-file` | Remove requirements.lock and reload charts when it is out of sync. | 188 | `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. | 189 | `include[].apiVersion` | | Includes resources by apiVersion. | 190 | `include[].kind` | | Includes resources by kind. | 191 | `include[].namespace` | | Includes resources by namespace. | 192 | `include[].name` | | Includes resources by name. | 193 | `exclude` | | List of resource selectors that exclude matching resources from the output. Fails if a selector doesn't match any resource. | 194 | `exclude[].apiVersion` | | Excludes resources by apiVersion. | 195 | `exclude[].kind` | | Excludes resources by kind. | 196 | `exclude[].namespace` | | Excludes resources by namespace. | 197 | `exclude[].name` | | Excludes resources by name. | 198 | `excludeHooks` | `--no-hooks` | If enabled excludes chart hooks from the output. | 199 | `namespace` | `--namespace` | Set the namespace used by Helm templates. | 200 | `namespacedOnly` | `--namespaced-only` | If enabled fail on known cluster-scoped resources and those of unknown kinds. | 201 | `forceNamespace` | `--force-namespace` | Set namespace on all namespaced resources (and those of unknown kinds). | 202 | `outputPath` | `--output` | Path to write the output to. If it ends with `/` a kustomization is generated. (Not supported by the kustomize plugin.) | 203 | `outputPathMapping[].outputPath` | | output path to which all resources should be written that match `resourceSelectors`. (Only supported by the kpt function.) | 204 | `outputPathMapping[].selectors[].apiVersion` | | Selects resources by apiVersion. | 205 | `outputPathMapping[].selectors[].kind` | | Selects resources by kind. | 206 | `outputPathMapping[].selectors[].namespace` | | Selects resources by namespace. | 207 | `outputPathMapping[].selectors[].name` | | Selects resources by name. | 208 | | `--output-replace` | If enabled replace the output directory or file (CLI-only). | 209 | | `--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. | 210 | `debug` | `--debug` | Enables debug log and provides a stack trace on error. | 211 212 ### Repository configuration 213 214 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. 215 216 When running khelm as kpt function or within a container the `repositories.yaml` should be mounted to `/helm/repository/repositories.yaml`. 217 218 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. 219 220 ## Helm support 221 222 * Helm 2 is supported by the `v1` module version. 223 * Helm 3 is supported by the `v2` module version. 224 225 ## Build and test 226 227 Build and test the khelm binary (requires Go 1.13) as well as the container image: 228 ```sh 229 make clean khelm test check image e2e-test 230 ``` 231 _The binary is written to `build/bin/khelm`_. 232 233 Install the binary on your host at `/usr/local/bin/khelm`: 234 ```sh 235 sudo make install 236 ```