Using KubeLinter

March 10, 2026 ยท View on GitHub

You can run KubeLinter both locally and on your CI systems.

Running locally

After you've installed KubeLinter, use the lint command and provide:

** Kubernetes **

  • The path to your Kubernetes yaml file: 
    kube-linter lint /path/to/yaml-file.yaml
  • The path to a directory containing your Kubernetes yaml files: 
    kube-linter lint /path/to/directory/containing/yaml-files/

** Helm **

The path to a directory containing the Chart.yaml file:

kube-linter lint /path/to/directory/containing/Chart.yaml-file/

** Kustomize **

The path to a directory containing a kustomization.yaml file:

kube-linter lint /path/to/directory/containing/kustomization.yaml

[!NOTE] KubeLinter automatically detects Kustomize directories and renders the manifests before linting. Source file paths are preserved in lint reports, pointing to the actual base/overlay files rather than generated output.

[!NOTE] To get structured output, use the --format option. For example,

  • Use --format=json to get the output in JSON format.
  • Use --format=sarif to get the output in the SARIF spec.

Multiple Output Formats

KubeLinter supports writing results in multiple formats in a single run. This eliminates the need to run the linter multiple times for different output formats, improving efficiency and ensuring consistency across reports.

Single format to stdout (backward compatible)

The default behavior outputs a single format to stdout:

kube-linter lint --format json myapp.yaml

Single format to file

To write output to a file, use the --output flag:

kube-linter lint --format sarif --output results.sarif myapp.yaml

Multiple formats to multiple files

You can generate multiple output formats in a single run by repeating the --format and --output flags. The flags are paired by position (first --format with first --output, etc.):

kube-linter lint \
  --format sarif --output kube-linter.sarif \
  --format json --output kube-linter.json \
  --format plain --output kube-linter.txt \
  myapp.yaml

This command will:

  • Generate a SARIF format report in kube-linter.sarif
  • Generate a JSON format report in kube-linter.json
  • Generate a plain text report in kube-linter.txt
  • Process the files only once, improving efficiency

Important Notes

  • Positional pairing: Format and output flags are paired by position. The first --format corresponds to the first --output, the second --format to the second --output, and so on.
  • All stdout or all files: Either all formats write to stdout (when no --output flags are provided), or each format must have a corresponding output file. You cannot mix stdout and file outputs.
  • Error handling: If one format fails to write, the other successful formats are still written, and errors are reported at the end.
  • File overwrites: Output files are created or overwritten if they already exist.
  • Duplicate formats allowed: You can specify the same format multiple times with different output files if needed.

Examples

Example 1: Generate JSON and SARIF for CI integration

kube-linter lint \
  --format json --output build/kube-linter.json \
  --format sarif --output build/kube-linter.sarif \
  --config .kube-linter.yaml \
  deployments/

Example 2: Error case - mismatched counts

# This will fail with an error
kube-linter lint \
  --format json --format sarif \
  --output out.json \
  pod.yaml

Output: Error: format/output mismatch: 2 format(s) specified but 1 output(s) provided

Example 3: Error case - multiple formats to stdout

# This will fail with an error (prevents unparseable mixed output)
kube-linter lint --format json --format plain pod.yaml

Output: Error: multiple formats require explicit --output flags. Use --output to specify files, or use a single --format for stdout

Using KubeLinter with the pre-commit framework

If you are using the pre-commit framework for managing Git pre-commit hooks, you can install and use KubeLinter as a pre-commit hook. To do this, add the following to your .pre-commit-config.yaml:

  - repo: https://github.com/stackrox/kube-linter
    rev: 0.6.0 # kube-linter version 
    hooks:
        # You can change this to kube-linter-system or kube-linter-docker
      - id: kube-linter

The .pre-commit-hooks.yaml includes the following pre-commit hooks:

  1. kube-linter: Clones, builds, and installs KubeLinter locally (by using go get).
  2. kube-linter-system: Runs the KubeLinter binary.
    • You must install KubeLinter and add it to your path before running this pre-commit hook.
  3. kube-linter-docker: Pulls the KubeLinter docker image, mounts the project directory in the container, and runs the kube-linter command.

Using KubeLinter as part of your CI pipeline

If you're using GitHub, there's the KubeLinter GitHub Action available.

Alternatively, you can grab the latest binary release with the following commands

LOCATION=$(curl -s https://api.github.com/repos/stackrox/kube-linter/releases/latest \
| jq -r '.tag_name
    | "https://github.com/stackrox/kube-linter/releases/download/\(.)/kube-linter-linux.tar.gz"')
curl -L -o kube-linter-linux.tar.gz $LOCATION
mkdir kube-linter/
tar -xf kube-linter-linux.tar.gz -C "kube-linter/"

and pass --fail-on-invalid-resource as an option to have your pipeline fail if your YAML file can't be parsed. See the following example:

./kube-linter/kube-linter lint --fail-on-invalid-resource /path/to/yaml-file.yaml

KubeLinter commands

This section covers kube-linter command syntax, describes the command operations, and provides some common command examples.

Commands syntax

Use the following syntax to run KubeLinter commands:

kube-linter [resource] [command] [options]

where resource, command, and options are:

  • resource specifies the resources on which you want to perform operations. For example, checks or templates.
  • command specifies the operation that you want to perform, for example, kube-linter lint. Or the operation you want to perform on a specified resource, for example, kube-linter checks list.
  • options specifies options for each command. For example, you can use the -c or --config option to specify a configuration file.

Viewing help

Use the --help (or -h) option to get a complete list of resources and commands. The --help option lists CLI reference information about available resources, commands, and their options.

For example,

  • to find all resources, run the following command: 
    kube-linter --help
  • to find available commands for a specific resource, run the following command: 
    kube-linter checks --help
  • to find available options for a specific command, run the following command: 
    kube-linter lint --help