helm/chart-testing

Chart Testing

ct is the tool for testing Helm charts. It is meant to be used for linting and testing pull requests. It automatically detects charts changed against the target branch.

Installation

Prerequisites

It is recommended to use the provided Docker image which can be found on Quay. It comes with all necessary tools installed.

• Helm
• Git (2.17.0 or later)
• Yamllint
• Yamale
• Kubectl

Binary Distribution

Download the release distribution for your OS from the Releases page:

https://github.com/helm/chart-testing/releases

Unpack the ct binary, add it to your PATH, and you are good to go!

Verifying the release

Release artifacts (archives, checksums, and SBOMs) are signed with cosign using keyless signing. Each artifact has a <artifact>.sigstore.json bundle next to it. To verify a download, for example the checksums file:

$ cosign verify-blob checksums.txt \
    --bundle checksums.txt.sigstore.json \
    --certificate-identity "https://github.com/helm/chart-testing/.github/workflows/release.yaml@refs/heads/main" \
    --certificate-oidc-issuer "https://token.actions.githubusercontent.com"

The Docker image is signed as well:

$ cosign verify quay.io/helmpack/chart-testing:<version> \
    --certificate-identity "https://github.com/helm/chart-testing/.github/workflows/release.yaml@refs/heads/main" \
    --certificate-oidc-issuer "https://token.actions.githubusercontent.com"

Earlier releases were signed with separate .sig and .pem files instead of a bundle.

Docker Image

A Docker image is available at quay.io/helmpack/chart-testing with list of available tags here.

Homebrew

$ brew install chart-testing

Usage

See documentation for individual commands:

• ct
• ct install
• ct lint
• ct lint-and-install
• ct list-changed
• ct version

Charts with type: library in their Chart.yaml cannot be installed, so ct install and ct lint-and-install skip the install step for them and print a message instead. They are still linted by ct lint.

For a more extensive how-to guide, please see:

• charts-repo-actions-demo

Configuration

ct is a command-line application. All command-line flags can also be set via environment variables or config file. Environment variables must be prefixed with CT_. Underscores must be used instead of hyphens.

CLI flags, environment variables, and a config file can be mixed. The following order of precedence applies:

1. CLI flags
2. Environment variables
3. Config file

Note that linting requires config file for yamllint and yamale. If not specified, these files are search in the current directory, the .ct directory in current directory, $HOME/.ct, and /etc/ct, in that order. Samples are provided in the etc folder.

Examples

The following example show various way of configuring the same thing:

CLI

Remote repo

With remote repo:

ct install --remote upstream --chart-dirs stable,incubator --build-id pr-42

Local repo

If you have a chart in current directory and ct installed on the host then you can run:

ct install --chart-dirs . --charts .

With docker it works with:

docker run -it --network host --workdir=/data --volume ~/.kube/config:/root/.kube/config:ro --volume $(pwd):/data quay.io/helmpack/chart-testing:v3.15.0 ct install --chart-dirs . --charts .

Notice that workdir param is important and must be the same as volume mounted.

Environment Variables

export CT_REMOTE=upstream
export CT_CHART_DIRS=stable,incubator
export CT_BUILD_ID

ct install

Config File

config.yaml:

remote: upstream
chart-dirs:
  - stable
  - incubator
build-id: pr-42

Config Usage

ct install --config config.yaml

ct supports any format Viper can read, i. e. JSON, TOML, YAML, HCL, and Java properties files.

Notice that if no config file is specified, then ct.yaml (or any of the supported formats) is loaded from the current directory, $HOME/.ct, or /etc/ct, in that order, if found.

Using private chart repositories

When adding chart-repos you can specify additional arguments for the helm repo add command using helm-repo-extra-args on a per-repo basis. You can also specify OCI registries which will be added using the helm registry login command, they also support the helm-repo-extra-args for authentication. This could for example be used to authenticate a private chart repository.

config.yaml:

chart-repos:
  - incubator=https://incubator.io
  - basic-auth=https://private.com
  - ssl-repo=https://self-signed.ca
  - oci-registry=oci://nice-oci-registry.pt
helm-repo-extra-args:
  - ssl-repo=--ca-file ./my-ca.crt

ct install --config config.yaml --helm-repo-extra-args "basic-auth=--username user --password secret"

Building from Source

ct is built using Go 1.13 or higher.

build.sh is used to build and release the tool. It uses Goreleaser under the covers.

Note: on MacOS you will need GNU Coreutils readlink. You can install it with:

brew install coreutils

Then add gnubin to your $PATH, with:

echo 'export PATH="$(brew --prefix coreutils)/libexec/gnubin:$PATH"' >> ~/.bash_profile
bash --login

To use the build script:

$ ./build.sh -h
Usage: build.sh <options>

Build ct using Goreleaser.

    -h, --help      Display help
    -d, --debug     Display verbose output and run Goreleaser with --debug
    -r, --release   Create a release using Goreleaser. This includes the creation
                    of a GitHub release and building and pushing the Docker image.
                    If this flag is not specified, Goreleaser is run with --snapshot

Releasing

Prepare Release

Before a release is created, versions have to be updated in the examples. A pull request needs to be created for this, which should be merged right before the release is cut. Here's a previous one for reference: https://github.com/helm/chart-testing/pull/89

Create Release

The release workflow is dispatched from github actions Versions must start with a lower-case v, e. g. v3.15.0.

Supported versions

The previous MAJOR version will be supported for three months after each new MAJOR release.

Within this support window, pull requests for the previous MAJOR version should be made against the previous release branch. For example, if the current MAJOR version is v2, the pull request base branch should be release-v1.

Upgrading

When upgrading from < v2.0.0 you will also need to change the usage in your scripts. This is because, while the v2.0.0 release has parity with v1, it was refactored from a bash library to Go so there are minor syntax differences. Compare v1 usage with this (v2) version's README usage section above.