Helm Deployment

Every project you design in KubeKanvas generates a Helm chart. You can install that chart directly with the Helm CLI if you do not want to use KubeKanvas CLI. There are two ways to get the chart:

Download the archive — export the chart as a .tar.gz file directly from the KubeKanvas editor and install it locally.
Pull from the Helm repo — generate Helm repository credentials in the editor, then use helm pull to fetch the chart in any environment, including CI/CD pipelines.

If your chart contains Secrets encrypted by KubeKanvas, add the helm-kubekanvas post-renderer to your Helm command and it will decrypt values automatically at deploy time — no plaintext secrets in your pipeline.

How It Works

Helm pipes rendered YAML to helm-kubekanvas on stdin. The post-renderer decrypts any AGE-ENC: values in place and writes the result to stdout, which Helm then applies to the cluster.

Helm renders chart → pipes YAML to helm-kubekanvas stdin → decrypted YAML → applied to cluster

Values without the AGE-ENC: prefix pass through unchanged. If no encrypted values are found, the input is returned byte-for-byte.

Installation

As a Helm plugin (recommended)

Requires Helm v3.18.10 or later.

Run helm version to check. Older versions will fail with an unknown field "platformHooks" error. Upgrade with brew upgrade helm or from helm.sh/docs/intro/install.

helm plugin install https://downloads.kubekanvas.io/helm-plugin/latest/plugin.tar.gz

The plugin downloads the correct pre-built binary for your OS and architecture. After installation, the binary is available as:

helm-kubekanvas — for use with --post-renderer
helm kubekanvas — as a Helm subcommand

Manual download

Download the binary for your platform directly:

OS	Architecture	Download
macOS	Apple Silicon (arm64)	helm-kubekanvas_darwin_arm64.tar.gz
macOS	Intel (amd64)	helm-kubekanvas_darwin_amd64.tar.gz
Linux	amd64	helm-kubekanvas_linux_amd64.tar.gz
Linux	arm64	helm-kubekanvas_linux_arm64.tar.gz
Windows	amd64	helm-kubekanvas_windows_amd64.zip

Or Download using helm

helm plugin install --verify=false https://downloads.kubekanvas.io/helm-plugin/latest/plugin.tar.gz

Basic Usage

export KUBEKANVAS_AGE_KEY="AGE-SECRET-KEY-1..."

Install or Upgrade Chart using one of the following commands

helm install myapp ./chart --post-renderer helm-kubekanvas
helm upgrade myapp ./chart --install --post-renderer helm-kubekanvas

CI/CD Pipeline Setup

In a CI/CD environment, provide the AGE private key via the KUBEKANVAS_AGE_KEY environment variable and pass --post-renderer helm-kubekanvas to your Helm commands. No other changes to your pipeline are required.

export KUBEKANVAS_AGE_KEY="AGE-SECRET-KEY-1..."
helm upgrade myapp ./chart --install --post-renderer helm-kubekanvas

Store KUBEKANVAS_AGE_KEY as a secret in your CI/CD platform (GitHub Actions secrets, GitLab CI variables, etc.) and inject it as an environment variable at deploy time. The plaintext key value never appears in logs or pipeline output.

GitHub Actions example

- name: Deploy to Kubernetes
  env:
    KUBEKANVAS_AGE_KEY: ${{ secrets.KUBEKANVAS_AGE_KEY }}
  run: |
    helm upgrade myapp ./chart --install --post-renderer helm-kubekanvas

Key Loading Priority

The private key is resolved using the following priority chain — first match wins:

Priority	Source	How
1	`--key-file <path>`	CLI flag: path to an AGE private key file
2	`KUBEKANVAS_AGE_KEY_FILE`	Env var: path to an AGE private key file
3	`KUBEKANVAS_AGE_KEY`	Env var: raw AGE private key string
4	System keychain	Stored by `kubekanvas configure` (requires keychain build tag — see below)

Using a key file

helm install myapp ./chart \
     --post-renderer helm-kubekanvas \
     --post-renderer-args "--key-file /path/to/age.key"

Or set the path via environment variable:

export KUBECANVAS_AGE_KEY_FILE=/path/to/age.key
helm upgrade myapp ./chart --install --post-renderer helm-kubekanvas

System keychain (desktop only)

Pre-built release binaries do not include keychain support (they are static/CGO-free). Desktop users who installed the KubeKanvas CLI can build from source with the keychain tag to use the key stored by kubekanvas configure:

go build -tags keychain -o helm-kubekanvas .

Error Handling

If decryption fails — wrong key, malformed value, or key not found — the post-renderer:

Writes the original unmodified input back to stdout (prevents Helm from hanging).
Writes the error details to stderr.
Exits with code 1, causing the Helm command to fail visibly.

Related:

To learn how Secret values are encrypted in the first place, see Secret Encryption. To get your AGE private key, see the keys command reference.