Skip to main content
Version: 0.9

Helmfile KCL Plugin


Helmfile is a declarative spec for deploying helm charts. It lets you...

  • Keep a directory of chart value files and maintain changes in version control.
  • Apply CI/CD to configuration changes.
  • Periodically sync to avoid skew in environments.

KCL can be used to create functions to mutate and/or validate the YAML Kubernetes Resource Model (KRM) input/output format, and we provide Kustomize KCL functions to simplify the function authoring process.


  • Install helmfile
  • Prepare a Kubernetes cluster

Quick Start

Let’s write a KCL function which add annotation managed-by=helmfile-kcl only to Deployment resources.

1. Get the Example

git clone
cd ./helmfile-kcl/examples/hello-world/

We can execute the command to show config

cat helmfile.yaml

The output is

- name: prometheus-community

- name: prom-norbac-ubuntu
namespace: prometheus
chart: prometheus-community/prometheus
- name: rbac.create
value: false
# Use KCL Plugin to mutate or validate Kubernetes manifests.
- apiVersion:
kind: KCLRun
name: "set-annotation"
annotations: |
source: |
[resource | {if resource.kind == "Deployment": metadata.annotations: {"managed-by" = "helmfile-kcl"}} for resource in option("resource_list").items]

In the above config, we use a KCLRun plugin to assign the transfomer field. This means that we will add annotations to all deployment resources in the prometheus helm chart.

2. Test and Run

Firstly, init the helmfile tool.

helmfile init

The output may looks like this:

The helm plugin helm-git is not installed, do you need to install it [y/n]: y
Install helm plugin helm-git
Installed plugin: helm-git

helmfile initialization completed!

Then apply the configuration.

helmfile apply

The output is

Adding repo prometheus-community
"prometheus-community" has been added to your repositories


Guides for Developing KCL

Here's what you can do in the KCL code:

  • Read resources from option("items"). The option("items") complies with the KRM Functions Specification.
  • Return a KRM list for output resources.
  • Return an error using assert {condition}, {error_message}.
  • Read the PATH variables. e.g. option("PATH").
  • Read the environment variables. e.g. option("env").

More Documents and Examples