Kubeconform Helm

April 21, 2026 ยท View on GitHub

This repo contains tools that allow to use kubeconform to test Helm charts in the form of Helm plugin and pre-commit hook.

Usage

Helm plugin

Requirements

The Helm plugin is implemented as a Python wrapper and requires the following to be available on the system:

  • Python 3
  • PyYAML (pip install pyyaml, or python3-yaml / python-yaml via the system package manager)

Without PyYAML, the plugin fails with ModuleNotFoundError: No module named 'yaml' on first run.

Installation

The kubeconform Helm plugin can be installed using this command:

helm plugin install https://github.com/jtyr/kubeconform-helm

Once installed, the plugin can be used from any Helm chart directory:

# Enter the chart directory
cd charts/mychart
# Run kubeconform plugin
helm kubeconform .

The plugin uses helm template internally and passes its output to the kubeconform. There is several helm template command line options supported by the plugin that can be specified:

helm kubeconform --namespace myns .

There is also several kubeconform command line options supported by the plugin that can be specified:

# Kubeconform options
helm kubeconform --verbose --summary .

It's also possible to create .kubeconform file in the Helm chart directory that can contain default kubeconform settings:

# Command line options that can be set multiple times can be defined as an array
schema-location:
  - default
  - https://raw.githubusercontent.com/datreeio/CRDs-catalog/main/{{.Group}}/{{.ResourceKind}}_{{.ResourceAPIVersion}}.json
# Command line options that can be specified without a value must have boolean
# value in the config file
summary: true
verbose: true

The full list of options for the plugin is as follows:

$ ./scripts/plugin_wrapper.py --help
usage: plugin_wrapper.py [-h] [--cache] [--cache-dir DIR] [--config FILE] [--values-dir DIR]
                         [--values-pattern PATTERN] [-d] [--stdout] [--errors-only] [--fail-fast]
                         [--skip-refresh] [--verify] [--force-dep-update] [-v VERSION] [-f FILE]
                         [-n NAME] [--chart-version CHART_VERSION] [-r NAME]
                         [--ignore-missing-schemas] [--insecure-skip-tls-verify]
                         [--kubernetes-version VERSION] [--goroutines NUMBER]
                         [--output {json,junit,tap,text}] [--reject LIST]
                         [--schema-location LOCATION] [--skip LIST] [--strict] [--summary]
                         [--verbose]
                         CHART

Wrapper to run kubeconform for a Helm chart.

options:
  -h, --help            show this help message and exit
  --cache               whether to use kubeconform cache
  --cache-dir DIR       path to the cache directory (default: ~/.cache/kubeconform)
  --config FILE         config file name (default: .kubeconform)
  --values-dir DIR      directory with optional values files for the tests (default:
                        tests/kubeconform)
  --values-pattern PATTERN
                        pattern to select the values files (default: *-values.yaml)
  -d                    debug output
  --stdout              log to stdout
  --errors-only         output only errors
  --fail-fast           fail on first error

helm dependency update:
  Options passed to the 'helm dependency update' command

  --skip-refresh        do not refresh the local repository cache
  --verify              verify the packages against signatures
  --force-dep-update    force dependency update even if Chart.lock already exists

helm template:
  Options passed to the 'helm template' command

  -v, --kube-version VERSION
                        Kubernetes version to generate for (default: same as --kubernetes-version)
  -f, --values FILE     values YAML file or URL (can specified multiple)
  -n, --namespace NAME  namespace
  --chart-version CHART_VERSION
                        chart version
  -r, --release NAME    release name
  CHART                 chart path (e.g. '.')

kubeconform:
  Options passsed to the 'kubeconform' command

  --ignore-missing-schemas
                        skip files with missing schemas instead of failing
  --insecure-skip-tls-verify
                        disable verification of the server's SSL certificate
  --kubernetes-version VERSION
                        version of Kubernetes to validate against, e.g. 1.33.0 (default: master)
  --goroutines NUMBER   number of goroutines to run concurrently (default: 4)
  --output {json,junit,tap,text}
                        output format (default: text)
  --reject LIST         comma-separated list of kinds or GVKs to reject
  --schema-location LOCATION
                        override schemas location search path (can specified multiple)
  --skip LIST           comma-separated list of kinds or GVKs to ignore
  --strict              disallow additional properties not in schema or duplicated keys
  --summary             print a summary at the end (ignored for junit output)
  --verbose             print results for all resources (ignored for tap and junit output)

Helm pre-commit hook

The kubeconform pre-commit hook can be added into the .pre-commit-config.yaml file like this:

repos:
  - repo: https://github.com/jtyr/kubeconform-helm
    rev: v0.3.0
    hooks:
      - id: kubeconform-helm

The hook uses helm template internally and passes its output to the kubeconform. There is several helm template command line options supported by the hook that can be specified:

  - repo: https://github.com/jtyr/kubeconform-helm
    rev: v0.3.0
    hooks:
      - id: kubeconform-helm
        args:
          - --namespace=myns
          - --release=myrelease

There is also several kubeconform command line options supported by the hook that can be specified:

  - repo: https://github.com/jtyr/kubeconform-helm
    rev: v0.3.0
    hooks:
      - id: kubeconform-helm
        args:
          - --kubernetes-version=1.33.0
          - --verbose
          - --summary

The full list of options for the hook is as follows:

$ ./scripts/pre_commit.py --help
usage: pre_commit.py [-h] [--charts-path PATH] [--include-charts LIST] [--exclude-charts LIST]
                     [--path-sub-pattern PATTERN] [--path-sub-separator SEP] [--cache]
                     [--cache-dir DIR] [--config FILE] [--values-dir DIR]
                     [--values-pattern PATTERN] [-d] [--stdout] [--errors-only] [--fail-fast]
                     [--skip-refresh] [--verify] [--force-dep-update] [-v VERSION] [-f FILE]
                     [-n NAME] [--chart-version CHART_VERSION] [-r NAME]
                     [--ignore-missing-schemas] [--insecure-skip-tls-verify]
                     [--kubernetes-version VERSION] [--goroutines NUMBER]
                     [--output {json,junit,tap,text}] [--reject LIST]
                     [--schema-location LOCATION] [--skip LIST] [--strict] [--summary]
                     [--verbose]
                     FILES [FILES ...]

Wrapper to run kubeconform for a Helm chart.

positional arguments:
  FILES                 files that have changed

options:
  -h, --help            show this help message and exit
  --charts-path PATH    path to the directory with charts, can be multiple (default: charts)
  --include-charts LIST
                        comma-separated list of chart names to include in the testing
  --exclude-charts LIST
                        comma-separated list of chart names to exclude from the testing
  --path-sub-pattern PATTERN
                        substitution pattern to rewrite chart directory path for library charts
                        (e.g. '^charts/(commonlib),helper-charts/\1-test')
  --path-sub-separator SEP
                        separator used to split the path-sub-pattern (default: ,)
  --cache               whether to use kubeconform cache
  --cache-dir DIR       path to the cache directory (default: ~/.cache/kubeconform)
  --config FILE         config file name (default: .kubeconform)
  --values-dir DIR      directory with optional values files for the tests (default:
                        tests/kubeconform)
  --values-pattern PATTERN
                        pattern to select the values files (default: *-values.yaml)
  -d                    debug output
  --stdout              log to stdout
  --errors-only         output only errors
  --fail-fast           fail on first error

helm dependency update:
  Options passed to the 'helm dependency update' command

  --skip-refresh        do not refresh the local repository cache
  --verify              verify the packages against signatures
  --force-dep-update    force dependency update even if Chart.lock already exists

helm template:
  Options passed to the 'helm template' command

  -v, --kube-version VERSION
                        Kubernetes version to generate for (default: same as --kubernetes-version)
  -f, --values FILE     values YAML file or URL (can specified multiple)
  -n, --namespace NAME  namespace
  --chart-version CHART_VERSION
                        chart version
  -r, --release NAME    release name

kubeconform:
  Options passsed to the 'kubeconform' command

  --ignore-missing-schemas
                        skip files with missing schemas instead of failing
  --insecure-skip-tls-verify
                        disable verification of the server's SSL certificate
  --kubernetes-version VERSION
                        version of Kubernetes to validate against, e.g. 1.33.0 (default: master)
  --goroutines NUMBER   number of goroutines to run concurrently (default: 4)
  --output {json,junit,tap,text}
                        output format (default: text)
  --reject LIST         comma-separated list of kinds or GVKs to reject
  --schema-location LOCATION
                        override schemas location search path (can specified multiple)
  --skip LIST           comma-separated list of kinds or GVKs to ignore
  --strict              disallow additional properties not in schema or duplicated keys
  --summary             print a summary at the end (ignored for junit output)
  --verbose             print results for all resources (ignored for tap and junit output)

Contribution

This repo utilises pre-commit hooks to lint code changes. Make sure you install it before contributing to the repo.

Installation

Following are the installation instructions for pre-commit. Further details can be found in the official documentation.

Mac

brew install pre-commit

Ubuntu

pip install pre-commit

Arch Linux

pacman -S python-pre-commit

Usage

pre-commit can run automatically on every commit. This requires to run the following command once:

pre-commit install

Use the following command to run pre-commit manually for all files in the repository:

pre-commit run --all-files

License

MIT

Author

Jiri Tyr