KubeLinter is an open source tool that analyzes Kubernetes YAML files and Helm charts to ensure they adhere to best practices, focusing on production readiness and
security. It performs checks on various aspects of the configuration to identify potential security misconfigurations and
DevOps best practices.
By running KubeLinter, you can obtain valuable information about your
Kubernetes configuration files and Helm charts. It helps teams detect and address security issues early in the development process. Some examples of the checks performed by KubeLinter include running
containers as non-root users, enforcing least privilege, and properly handling sensitive information by storing it only in secrets.
KubeLinter is licensed under the Apache License 2.0, allowing you to use, modify, and distribute it according to the terms of the license.
Why KubeLinter?
KubeLinter comes with sensible default checks, but it is also configurable. You have the flexibility to enable or disable specific checks according to your organization’s policies. Additionally, you can create your own custom checks to enforce specific requirements.
When a lint check fails, KubeLinter provides recommendations on how to resolve the identified issues. It also returns a non-zero exit code to indicate the presence of potential problems.
Installation, Setup and Getting Started
To get started with KubeLinter, you can refer to the
official documentation. The documentation provides detailed information on installing, using and configuring KubeLinter.
Here are a few installation options for KubeLinter.
Using Go
Install KubeLinter using Go by running the following command:
go install golang.stackrox.io/kube-linter/cmd/kube-linter@latest
Using Homebrew (macOS) or LinuxBrew (Linux)
Install KubeLinter using Homebrew or LinuxBrew by running the following command:
Building from Source
If you prefer to build KubeLinter from source, follow these steps:
- Clone the KubeLinter repository:
git clone git@github.com:stackrox/kube-linter.git
- Compile the source code to create the kube-linter binary files:
- Verify the installation by checking the version:
.gobin/kube-linter version
KubeLinter provides different layers of testing, including go unit tests, end-to-end integration tests and end-to-end integration tests using
bats-core. You can run these tests to ensure the correctness and reliability of KubeLinter.
How to Use KubeLinter
To use KubeLinter, you can start by running it against your local YAML files. Simply specify the path to the YAML file you want to test, and KubeLinter will perform the linting checks. For example.
kube-linter lint /path/to/your/yaml.yaml
The output of KubeLinter will show any detected issues along with recommended remediation steps. It will also provide a summary of the lint errors found.
You have the option to run it locally or integrate it into your CI systems. Here are the instructions for running KubeLinter locally:
After installing KubeLinter, you can use the lint command and provide the path to your Kubernetes YAML file or directory containing YAML files.
For a single YAML file:
kube-linter lint /path/to/yaml-file.yaml
kube-linter lint /path/to/directory/containing/yaml-files/
To use KubeLinter for local YAML linting, follow these steps:
- Locate the YAML file that you want to test for security and production readiness best practices.
- Run the following command, replacing `/path/to/your/yaml.yaml` with the actual path to your YAML file. Here’s the format:
kube-linter lint /path/to/your/yaml.yaml
Here’s an example using a sample pod specification file named `pod.yaml` that has production readiness and security issues:
apiVersion: v1
kind: Pod
metadata:
name: security-context-demo
spec:
securityContext:
runAsUser: 1000
runAsGroup: 3000
fsGroup: 2000
volumes:
- name: sec-ctx-vol
emptyDir: {}
containers:
- name: sec-ctx-demo
image: busybox
resources:
requests:
memory: "64Mi"
cpu: "250m"
command: [ "sh", "-c", "sleep 1h" ]
volumeMounts:
- name: sec-ctx-vol
mountPath: /data/demo
securityContext:
allowPrivilegeEscalation: false
Save the YAML content above to a file named `lint-pod.yaml`. Then, you can lint this file by running the following command:
kube-linter lint lint-pod.yaml
KubeLinter will run its default checks and report recommendations based on the linting results. In the example above, the output will show three lint errors:
pod.yaml: (object: <no namespace>/security-context-demo /v1, Kind=Pod)
container "sec-ctx-demo" does not have a read-only root file system (check:
no-read-only-root-fs, remediation: Set readOnlyRootFilesystem to true in your
container's securityContext.)
pod.yaml: (object: <no namespace>/security-context-demo /v1, Kind=Pod)
container "sec-ctx-demo" has cpu limit 0 (check: unset-cpu-requirements,
remediation: Set your container's CPU requests and limits depending on its
requirements. See
https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/#requests-and-limits for more details.)
pod.yaml: (object: <no namespace>/security-context-demo /v1, Kind=Pod)
container "sec-ctx-demo" has memory limit 0 (check: unset-memory-requirements,
remediation: Set your container's memory requests and limits depending on its requirements.
See
https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/#requests-and-limits for more details.)
Error: found 3 lint errors
you need to provide the path to a directory containing the `chart.yaml` file. Here’s the command to run KubeLinter for Helm charts:
kube-linter lint /path/to/directory/containing/chart.yaml-file/
You can also use the `–format` option to specify the output format. For example, use –format=json for JSON format or –format=sarif for the SARIF spec.
If you’re using the pre-commit framework for managing git pre-commit hooks, you can integrate KubeLinter as a pre-commit hook. Add the following configuration to your `.pre-commit-config.yaml` file:
- repo: https://github.com/stackrox/kube-linter
rev: 0.6.0 # kube-linter version
hooks:
- id: kube-linter
This configuration sets up the `kube-linter hook`, which clones, builds, and installs KubeLinter locally using go get.
KubeLinter provides additional commands and options for different operations. Here’s the general syntax for running KubeLinter commands.
kube-linter [resource] [command] [options]
- `resource`. specifies the resources on which you want to perform operations, such as checks or templates
- `command`. specifies the operation you want to perform, such as lint or checks list
- `options`. specifies additional options for each command. For example, you can use the `-c` or `–config` option to specify a configuration file.
To view the complete list of available resources, commands, and options, you can use the `–help` or `-h` option.
To find all resources:
To find available commands for a specific resource, such as checks:
kube-linter checks --help
To configure the checks that KubeLinter runs or to create your own custom checks, you can use a YAML configuration file. When running the lint command, you can provide the –config option followed by the path to your configuration file.
If a configuration file is not explicitly provided, KubeLinter will look for a configuration file in the current working directory with the following filenames in order of preference:
If none of these files are found, KubeLinter will use the default configuration.
Here’s an example of how to run the lint command with a specific configuration file:
kube-linter lint pod.yaml –config kubelinter-config.yaml
The configuration file has two main sections
- customChecks for configuring custom checks.
- checks for configuring default checks.
To view a list of all built-in checks, you can refer to the
KubeLinter checks documentation.
Here are some configuration options you can use in the configuration file.
Disable all default checks. You can disable all built-in checks by setting `doNotAutoAddDefaults` to true in the checks section.
checks:
doNotAutoAddDefaults: true
You can run all built-in checks by setting `addAllBuiltIn` to true in the checks section
checks:
addAllBuiltIn: true
You can create custom checks based on existing templates. Each template description in the documentation includes details about the parameters (`params`) you can use with that template. Here’s an example.
customChecks:
- name: required-annotation-responsible
template: required-annotation
params:
key: company.io/responsible
These are some of the configuration options available in KubeLinter. You can refer to the KubeLinter documentation for more details on configuration and customization.
Conclusion
KubeLinter is an alpha release, which means it is still in the early stages of development. As a result, there may be breaking changes in the future regarding command usage, flags and configuration file formats.
However, you are encouraged to use KubeLinter to test your environment YAML files, identify issues — and contribute to its development.
