{"id":18733957,"url":"https://github.com/mgoltzsche/khelm","last_synced_at":"2025-04-04T13:11:06.201Z","repository":{"id":39693939,"uuid":"199538769","full_name":"mgoltzsche/khelm","owner":"mgoltzsche","description":"A Helm chart templating CLI, kustomize plugin and containerized kustomize/kpt KRM function","archived":false,"fork":false,"pushed_at":"2025-03-18T21:20:23.000Z","size":4924,"stargazers_count":122,"open_issues_count":4,"forks_count":11,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-03-28T12:07:36.157Z","etag":null,"topics":["declarative-workflows","helm","helm-chart","helm-charts","helm-charts-as-code","k8s","kpt","kubernetes","kustomize","kustomize-plugin"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mgoltzsche.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-07-29T23:15:37.000Z","updated_at":"2025-03-18T21:20:20.000Z","dependencies_parsed_at":"2024-02-01T02:40:07.931Z","dependency_job_id":"20062d28-7e12-4fb9-ab20-f15b91868868","html_url":"https://github.com/mgoltzsche/khelm","commit_stats":{"total_commits":204,"total_committers":10,"mean_commits":20.4,"dds":0.1568627450980392,"last_synced_commit":"23fa69831497543f609de8727038d14955f7f35f"},"previous_names":["mgoltzsche/helm-kustomize-plugin"],"tags_count":38,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mgoltzsche%2Fkhelm","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mgoltzsche%2Fkhelm/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mgoltzsche%2Fkhelm/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mgoltzsche%2Fkhelm/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mgoltzsche","download_url":"https://codeload.github.com/mgoltzsche/khelm/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247182354,"owners_count":20897380,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["declarative-workflows","helm","helm-chart","helm-charts","helm-charts-as-code","k8s","kpt","kubernetes","kustomize","kustomize-plugin"],"created_at":"2024-11-07T15:11:54.533Z","updated_at":"2025-04-04T13:11:06.178Z","avatar_url":"https://github.com/mgoltzsche.png","language":"Go","funding_links":[],"categories":["Configuration Management"],"sub_categories":[],"readme":"# 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)\n\nA [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.  \n\nFormerly known as \"helm-kustomize-plugin\".\n\n\n## Motivation / History\n\n[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.\nHowever writing helm templates is cumbersome and you cannot reuse a chart properly if it does not yet support a particular parameter/value.\n\n[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.\nHowever kustomize neither supports lifecycle management nor templating with externally passed in values (which is sometimes still required).  \n\nTo 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.  \nSince [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/).\n\n\n## Features\n\n* Templates/renders a Helm chart\n* Builds local charts automatically when templating\n* Automatically fetches and updates required repository index files when needed\n* Allows to automatically reload dependencies when lock file is out of sync\n* Allows to use any repository without registering it in repositories.yaml\n* Allows to exclude certain resources from the Helm chart output\n* Allows to enforce namespace-scoped resources within the template output\n* Allows to enforce a namespace on all resources\n* Allows to convert a chart's output into a kustomization\n\n## Supported interfaces\n\nkhelm can be used as:\n* [kpt function](#kpt-function)\n* [kustomize exec plugin](#kustomize-exec-plugin)\n* [kustomize Containerized KRM Function](#kustomize-containerized-krm-function)\n* [CLI](#cli)\n* [Go API](#go-api)\n\nUsage examples can be found in the [example](example) and [e2e](e2e) directories.\n\n### kpt function\n\nkhelm can be used as a containerized KRM function with [kpt](https://github.com/GoogleContainerTools/kpt).\nThe 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.\n\nIn 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 manifests to a cluster (e.g. using `kpt live apply`).\n\n#### kpt function usage example\n\nWhen using the khelm image directly with [kpt](https://github.com/GoogleContainerTools/kpt), it must be invoked as an [imperative function](https://kpt.dev/book/04-using-functions/02-imperative-function-execution) since it requires a chart to be mounted or network access to fetch a chart.\nThis is shown as follows:\n```sh\ncat - \u003e fn-config.yaml \u003c\u003c-EOF\n  apiVersion: khelm.mgoltzsche.github.com/v2\n  kind: ChartRenderer\n  metadata:\n    name: cert-manager-manifest-generator-config\n  repository: https://charts.jetstack.io\n  chart: cert-manager\n  version: 0.9.x\n  name: myrelease\n  namespace: cert-manager\n  values:\n    webhook:\n      enabled: false\n  outputPath: output-manifest.yaml\nEOF\nkpt fn eval --image mgoltzsche/khelm:latest --fn-config fn-config.yaml --network .\n```\n_For all available fields see the [table](#configuration-options) below._\n\nTo 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 .`.  \nThe [kpt examples](example/kpt) and corresponding [e2e tests](e2e/kpt-function-test.sh) show how to do that.\n\nTo use khelm as a [declarative function](https://kpt.dev/book/04-using-functions/01-declarative-function-execution), you could distribute a container image that includes both khelm and your chart as shown in the [declarative example](example/kpt/declarative).\n\nkpt 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](https://kpt.dev/reference/cli/pkg/) (with a corresponding dependency set up) before running the khelm function.\n\n#### Caching Helm Charts and repository index files\n\nWhen 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.  \nTo 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\" .`.\n_Please be aware that the presence of `/helm/repository/repositories.yaml` enables a strict repository policy by default (see [repository configuration](#repository-configuration))._\n_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`._\n\n### kustomize exec plugin\n\nkhelm can be used as [kustomize](https://github.com/kubernetes-sigs/kustomize) [exec plugin](https://kubectl.docs.kubernetes.io/guides/extending_kustomize/exec_plugins/).\nThough plugin support in kustomize is still an alpha feature and may be slated to be deprecated in a future version (see [KEP 2953](https://github.com/kubernetes/enhancements/tree/master/keps/sig-cli/2953-kustomize-plugin-graduation)).\n\n#### Plugin installation\n\nInstall using curl (on OSX or Linux):\n```sh\nOS=$(uname | tr '[:upper:]' '[:lower:]')\nARCH=$(uname -m | sed 's/x86_64/amd64/; s/aarch64/arm64/')\nmkdir -p $HOME/.config/kustomize/plugin/khelm.mgoltzsche.github.com/v2/chartrenderer\ncurl -fsSL https://github.com/mgoltzsche/khelm/releases/latest/download/khelm-${OS}-${ARCH} \u003e $HOME/.config/kustomize/plugin/khelm.mgoltzsche.github.com/v2/chartrenderer/ChartRenderer\nchmod +x $HOME/.config/kustomize/plugin/khelm.mgoltzsche.github.com/v2/chartrenderer/ChartRenderer\n```\nor using `go`:\n```sh\ngo get github.com/mgoltzsche/khelm/v2/cmd/khelm\nmkdir -p $HOME/.config/kustomize/plugin/khelm.mgoltzsche.github.com/v2/chartrenderer\nmv $GOPATH/bin/khelm $HOME/.config/kustomize/plugin/khelm.mgoltzsche.github.com/v2/chartrenderer/ChartRenderer\n```\n\n#### Plugin usage example\n\nA _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:\n```yaml\napiVersion: khelm.mgoltzsche.github.com/v2\nkind: ChartRenderer\nmetadata:\n  name: cert-manager # fallback for `name`\n  namespace: cert-manager # fallback for `namespace`\nrepository: https://charts.jetstack.io\nchart: cert-manager\nversion: 0.9.x\nvalues:\n  webhook:\n    enabled: false\n```\n_For all available fields see the [table](#configuration-options) below._\n\nMore complete examples can be found within the [example](example) directory.\nFor instance `cert-manager` can be rendered like this:\n```sh\nkustomize build --enable-alpha-plugins github.com/mgoltzsche/khelm/example/cert-manager\n```\n_When using kustomize 3 the option is called `--enable_alpha_plugins`._\n\n### kustomize Containerized KRM Function\n\nSimilar to the kpt function approach, khelm can be used as [Containerized KRM Function](https://kubectl.docs.kubernetes.io/guides/extending_kustomize/containerized_krm_functions/) [kustomize](https://github.com/kubernetes-sigs/kustomize) plugin.\nThough plugin support in kustomize is still an alpha feature, this form of extension seems destined to be graduated out of alpha (see [KEP 2953](https://github.com/kubernetes/enhancements/tree/master/keps/sig-cli/2953-kustomize-plugin-graduation)).\n\nThis approach only works with kustomize\u003e=v4.1.0.\n\nUnlike the [exec plugin strategy](#kustomize-exec-plugin), this method does not require installation.\n\n#### kustomize containerized KRM function usage example\n\nA _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:\n\n```yaml\napiVersion: khelm.mgoltzsche.github.com/v2\nkind: ChartRenderer\nmetadata:\n  name: cert-manager\n  namespace: cert-manager\n  annotations:\n    config.kubernetes.io/function: |\n      container:\n        image: mgoltzsche/khelm:latest\n        network: true\nrepository: https://charts.jetstack.io\nchart: cert-manager\nname: my-cert-manager-release\nnamespace: cert-manager\nversion: 0.9.x\nvalues:\n  webhook:\n    enabled: false\n```\n\n_For all available fields see the [table](#configuration-options) below._\n\nMore complete examples can be found within the [`example/kustomize-krm`](example/kustomize-krm/) directory.\n\nFor instance `cert-manager` can be rendered like this:\n```sh\nkustomize build --enable-alpha-plugins --network github.com/mgoltzsche/khelm/example/kustomize-krm/cert-manager\n```\n\n### CLI\n\nkhelm also supports a helm-like `template` CLI.\n\n#### Binary installation\n```sh\nOS=$(uname | tr '[:upper:]' '[:lower:]')\nARCH=$(uname -m | sed 's/x86_64/amd64/; s/aarch64/arm64/')\ncurl -fsSL https://github.com/mgoltzsche/khelm/releases/latest/download/khelm-${OS}-${ARCH} \u003e khelm\nchmod +x khelm\nsudo mv khelm /usr/local/bin/khelm\n```\n\n#### Binary usage example\n```sh\nkhelm template cert-manager --version=0.9.x --repo=https://charts.jetstack.io\n```\n_For all available options see the [table](#configuration-options) below._\n\n#### Docker usage example\n```sh\ndocker run mgoltzsche/khelm:latest template cert-manager --version=0.9.x --repo=https://charts.jetstack.io\n```\n\n### Go API\n\nThe khelm Go API `github.com/mgoltzsche/khelm/v2/pkg/helm` provides a simple templating interface on top of the Helm Go API.\nIt exposes a `Helm` struct that provides a `Render()` function that returns the rendered resources as `kyaml` objects.\n\n## Configuration options\n\n| Field | CLI        | Description |\n| ----- | ---------- | ----------- |\n| `chart` | ARGUMENT    | Chart file (if `repository` not set) or name. |\n| `version` | `--version` | Chart version. Latest version is used if not specified. |\n| `repository` | `--repo` | URL to the repository the chart should be loaded from. |\n| `valueFiles` | `-f` | Locations of values files.\n| `values` | `--set` | Set values object or in CLI `key1=val1,key2=val2`. |\n| `apiVersions` | `--api-versions` | Kubernetes api versions used for Capabilities.APIVersions. |\n| `kubeVersion` | `--kube-version` | Kubernetes version used for Capabilities.KubeVersion. |\n| `name` | `--name` | Release name used to render the chart. |\n| `verify` | `--verify` | If enabled verifies the signature of all charts using the `keyring` (see [Helm 3 provenance and integrity](https://helm.sh/docs/topics/provenance/)). |\n| `keyring` | `--keyring` | GnuPG keyring file (default `~/.gnupg/pubring.gpg`). |\n| `replaceLockFile` | `--replace-lock-file` | Remove requirements.lock and reload charts when it is out of sync. |\n| `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. |\n| `include[].apiVersion` |  | Includes resources by apiVersion. |\n| `include[].kind` |  | Includes resources by kind. |\n| `include[].namespace` |  | Includes resources by namespace. |\n| `include[].name` |  | Includes resources by name. |\n| `exclude` |  | List of resource selectors that exclude matching resources from the output. Fails if a selector doesn't match any resource. |\n| `exclude[].apiVersion` |  | Excludes resources by apiVersion. |\n| `exclude[].kind` |  | Excludes resources by kind. |\n| `exclude[].namespace` |  | Excludes resources by namespace. |\n| `exclude[].name` |  | Excludes resources by name. |\n| `excludeCRDs` | `--skip-crds` | If true Custom Resource Definitions are excluded from the output. |\n| `excludeHooks` | `--no-hooks` | If enabled excludes chart hooks from the output. |\n| `namespace` | `--namespace` | Set the namespace used by Helm templates. |\n| `namespacedOnly` | `--namespaced-only` | If enabled fail on known cluster-scoped resources and those of unknown kinds. |\n| `forceNamespace` | `--force-namespace` | Set namespace on all namespaced resources (and those of unknown kinds). |\n| `outputPath` | `--output` | Path to write the output to. If it ends with `/` a kustomization is generated. (Not supported by the kustomize plugin.) |\n| `outputPathMapping[].outputPath` |  | output path to which all resources should be written that match `resourceSelectors`. (Only supported by the kpt function.) |\n| `outputPathMapping[].selectors[].apiVersion` |  | Selects resources by apiVersion. |\n| `outputPathMapping[].selectors[].kind` |  | Selects resources by kind. |\n| `outputPathMapping[].selectors[].namespace` |  | Selects resources by namespace. |\n| `outputPathMapping[].selectors[].name` |  | Selects resources by name. |\n|  | `--output-replace` | If enabled replace the output directory or file (CLI-only). |\n|  | `--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. |\n| `debug` | `--debug` | Enables debug log and provides a stack trace on error. |\n\n### Repository configuration\n\nRepository 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.  \n\nWhen running khelm as kpt function or within a container the `repositories.yaml` should be mounted to `/helm/repository/repositories.yaml`.  \n\nUnlike 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.\n\n### Loading a chart from an OCI registry\n\nUsing Helm, you can store a Helm chart as OCI image within a container registry.\nTo load a chart from an OCI registry using khelm, you can specify the OCI registry within the `repository` field, prefixed with `oci://`.\nThe complete OCI image name is constructed from the `repository` and the `chart` field values, separated by `/`.\nFor an example, see [here](./example/oci-image/generator.yaml) and [here](./example/oci-dependency/Chart.yaml).\n\nWhen using a chart from an OCI registry, Helm's `repository.yaml` configuration is not used.\nInstead, Docker's `config.json` is used to read private registry credentials from, if any.\n\n## Helm support\n\n* Helm 2 is supported by the `v1` module version.\n* Helm 3 is supported by the `v2` module version.\n\n## Build and test\n\nBuild and test the khelm binary (requires Go 1.13) as well as the container image:\n```sh\nmake clean khelm test check image e2e-test\n```\n_The binary is written to `build/bin/khelm`_.\n\nInstall the binary on your host at `/usr/local/bin/khelm`:\n```sh\nsudo make install\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmgoltzsche%2Fkhelm","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmgoltzsche%2Fkhelm","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmgoltzsche%2Fkhelm/lists"}