DOCSEARCHbyAlgolia
Submit Docs

KubeLinter

repository·main·Indexed 25 days ago

https://github.com/stackrox/kube-linter

A static analysis tool for Kubernetes that checks YAML files, Helm charts, and Kustomize manifests against security and production readiness best practices. It supports custom check definitions, multiple output formats including SARIF and JSON, and integration with pre-commit hooks and CI pipelines.

Tokens
4.5K
Snippets
10
Records
32
Agent score
86%

What's inside kube-linter

  1. Configure KubeLinter with a YAML file

    main

    You can configure the checks KubeLinter runs or define custom checks using a YAML configuration file. When running the lint command, use the --config flag to specify the path to your file.

    If no config file is provided, KubeLinter searches the current working directory for files in this order:

    1. .kube-linter.yaml
    2. .kube-linter.yml

    If neither is found, KubeLinter uses its default configuration.

    The configuration file is divided into two main sections:

    • customChecks: For defining and configuring custom checks.
    • checks: For configuring built-in default checks.

  2. Run KubeLinter tests

    main

    If you are developing KubeLinter, you can run different layers of testing using make commands:

    • Unit tests: make test (Go unit tests).
    • Integration tests: make e2e-test (End-to-end integration tests).
    • BATS tests: make e2e-bats (End-to-end integration tests using bats-core).
    make test
make e2e-test
make e2e-bats

  3. Define and extend custom checks

    main

    Custom checks are created using existing templates in the customChecks section of your configuration file. You can define the check name, the template to use, and any required parameters (params).

    Advanced Customization:

    • Scope (scope.objectKinds): Limit the check to specific Kubernetes object types (e.g., DeploymentLike).
    • Remediation (remediation): Provide a custom message that users see when the check fails.
    • Custom objectKinds: For CRDs, you can register your own custom objectKind alongside your custom check.
    customChecks:
  # Basic custom check using a template
  - name: required-annotation-responsible
    template: required-annotation
    params:
      key: company.io/responsible

  # Extended custom check with scope and remediation
  - name: required-annotation-responsible-deployment
    template: required-annotation
    params:
      key: company.io/responsible
    scope:
      objectKinds:
        - DeploymentLike
    remediation: Please set the annotation 'company.io/responsible'.

  4. Use KubeLinter in CI pipelines

    main

    For CI environments, you can use the KubeLinter GitHub Action or download the latest binary release directly.

    When running in CI, it is recommended to use the --fail-on-invalid-resource flag. This ensures the pipeline fails if a YAML file is unparseable, preventing silent failures due to syntax errors.

  5. Build KubeLinter from source

    main

    To build KubeLinter from the source repository, ensure you have Go installed, then follow these steps:

    1. Clone the repository.
    2. Run make build to compile the source. Binaries are placed in the .gobin folder.
    3. Verify the installation using the version command.
    git clone git@github.com:stackrox/kube-linter.git
make build
.gobin/kube-linter version

  6. Run KubeLinter on Kubernetes, Helm, or Kustomize resources

    main

    Use the lint command to scan Kubernetes manifests. KubeLinter supports various resource types:

    • Kubernetes YAML: Provide a path to a single .yaml file or a directory containing multiple files.
    • Helm: Provide the path to a directory containing a Chart.yaml file.
    • Kustomize: Provide the path to a directory containing a kustomization.yaml file. KubeLinter automatically detects Kustomize directories and renders manifests before linting, preserving original source file paths in reports.

    To get structured output (like JSON or SARIF), use the --format option.

  7. Ignore violations using Kubernetes annotations

    main

    You can suppress specific KubeLinter violations directly in your Kubernetes manifests using annotations. It is recommended to provide an explanation as the annotation value.

    • To ignore a specific check: Use the key ignore-check.kube-linter.io/<check-name>.
    • To ignore all checks for an object: Use the key kube-linter.io/ignore-all.

  8. Configure multiple output formats and files

    main

    KubeLinter allows generating multiple report formats in a single run by pairing --format and --output flags. The flags are paired by position (the first --format corresponds to the first --output, etc.).

    Rules for multiple outputs:

    • Positional pairing: You must provide an equal number of --format and --output flags if using multiple formats.
    • All stdout or all files: You cannot mix stdout and file outputs. Either all formats write to stdout (by omitting --output), or every format must have a corresponding --output file.
    • Error handling: If one format fails to write, other successful formats are still written.
    • Overwrites: Output files are created or overwritten if they already exist.
    # Generate multiple formats to multiple files
kube-linter lint \
  --format sarif --output kube-linter.sarif \
  --format json --output kube-linter.json \
  --format plain --output kube-linter.txt \
  myapp.yaml

  9. Integrate KubeLinter with pre-commit

    main

    You can use KubeLinter as a Git pre-commit hook by adding it to your .pre-commit-config.yaml. There are three available hook IDs:

    1. kube-linter: Clones, builds, and installs KubeLinter locally using go get.
    2. kube-linter-system: Runs the KubeLinter binary already installed on your system and available in your PATH.
    3. kube-linter-docker: Runs KubeLinter via a Docker container (requires Docker to be installed).

    Note: Replace rev with the desired KubeLinter version.

      - repo: https://github.com/stackrox/kube-linter
    rev: 0.6.0 # kube-linter version 
    hooks:
      - id: kube-linter

  10. Install KubeLinter

    main

    You can install KubeLinter using several methods depending on your environment:

    • Go: Use go install to install the binary directly.
    • Homebrew/LinuxBrew: Use brew install for macOS or Linux.
    • nix-shell: Use nix-shell to run it in a Nix environment.
    • Docker: Pull the official image from Docker Hub.
    # Using Go
go install golang.stackrox.io/kube-linter/cmd/kube-linter@latest

# Using Homebrew
brew install kube-linter

# Using nix-shell
nix-shell -p kube-linter

# Using docker
docker pull stackrox/kube-linter:latest

  11. Lint Kubernetes YAML files locally

    main

    To perform static analysis on a Kubernetes YAML file, use the lint command followed by the path to your file. KubeLinter checks the file against best practices for security and production readiness (e.g., checking for non-root users, memory limits, and read-only filesystems).

    kube-linter lint /path/to/your/yaml.yaml

  12. Configure default checks (include, exclude, and ignore paths)

    main

    The checks section of your configuration file allows you to control which built-in checks are executed and which files are scanned.

    Key Options:

    • doNotAutoAddDefaults: Set to true to disable all built-in checks. (CLI: --do-not-auto-add-defaults)
    • addAllBuiltIn: Set to true to run all built-in checks. (CLI: --add-all-built-in)
    • include: A list of specific check names to run. Use this with doNotAutoAddDefaults: true to run only a subset of checks. (CLI: --include)
    • exclude: A list of specific check names to skip. Use this with addAllBuiltIn: true to run everything except these checks. (CLI: --exclude)
    • ignorePaths: A list of file or directory paths to ignore using ** match syntax. (CLI: --ignore-paths)

    Note: If both doNotAutoAddDefaults and addAllBuiltIn are set to true, addAllBuiltIn takes precedence. Additionally, exclude always takes precedence over include if a check is present in both.

    checks:
  doNotAutoAddDefaults: true
  include:
    - "privileged-container"
    - "run-as-non-root"

# OR

checks:
  addAllBuiltIn: true
  exclude:
    - "unset-cpu-requirements"
    - "unset-memory-requirements"

# To ignore paths
checks:
  ignorePaths:
    - ~/foo/bar/**
    - /**/*/foo/**
    - ../baz/**
    - /tmp/*.yaml