kubeval is a tool for validating a Kubernetes YAML or JSON configuration file.
It can also be used as a library in other Go applications.
- If you're writing Kubernetes configuration files by hand it is useful
to check them for validity before applying them
- If you're distributing Kubernetes configuration files or examples it's
handy to check them against multiple versions of Kubernetes
- If you're generating Kubernetes configurations using a tool like
ksonnet or hand-rolled templating it's important to make sure the
output is valid
I'd like to be able to address the above both locally when developing,
and also as a simple gate in a continuous integration system.
kubectl doesn't address the above needs in a few ways, importantly
kubectl requires a Kubernetes cluster. If you want to
validate against multiple versions of Kubernetes, you'll need multiple
clusters. All of that for validating the structure of a data structure
stored in plain text makes for an unweild development environment.
Kubernetes has strong definitions of what a Deployment, Pod, or
ReplicationController are. It exposes that information via an OpenAPI
based description. That description contains JSON Schema information for
the Kubernetes types. This tool uses those extracted schemas, published
at garethr/kubernetes-json-schema and garethr/openshift-json-schema. See
those repositories and
this blog post
for the details.
Tagged versions of
kubeval are built by Travis and automatically
uploaded to GitHub. This means you should find
tar.gz files under the
release tab. These should contain a single
kubeval binary for platform
in the filename (ie. windows, linux, darwin). Either execute that binary
directly or place it on your path.
tar xf kubeval-darwin-amd64.tar.gz
cp kubeval /usr/local/bin
Windows users can download tar or zip files from the releases, or for Chocolatey
users you can install with:
choco install kubeval
For those on macOS using Homebrew you can use the kubeval tap:
brew tap garethr/kubeval
brew install kubeval
kubeval is also published as a Docker image. So can be used as
$ docker run -it -v `pwd`/fixtures:/fixtures garethr/kubeval fixtures/*
Missing a kind key in /fixtures/blank.yaml
The document fixtures/int_or_string.yaml contains a valid Service
The document fixtures/int_or_string_false.yaml contains an invalid Deployment
--> spec.template.spec.containers.0.env.0.value: Invalid type. Expected: string, given: integer
The document fixtures/invalid.yaml contains an invalid ReplicationController
--> spec.replicas: Invalid type. Expected: integer, given: string
Missing a kind key in /fixtures/missing-kind.yaml
The document fixtures/valid.json contains a valid Deployment
The document fixtures/valid.yaml contains a valid ReplicationController
If you are modifying
kubeval, or simply prefer to build your own
binary, then the accompanying
Makefile has all the build instructions.
If you're on a Mac you should be able to just run:
The above relies on you having installed Go build environment and
GOPATH. It also requires
git to be installed. This will
build binaries in
bin, and tar files of those binaries in
for several common architectures.
$ kubeval --help
Validate a Kubernetes YAML file against the relevant schema
kubeval <file> [file...] [flags]
-h, --help help for kubeval
-v, --kubernetes-version string Version of Kubernetes to validate against (default "master")
--openshift Use OpenShift schemas instead of upstream Kubernetes
--schema-location string Base URL used to download schemas. Can also be specified with the environment variable KUBEVAL_SCHEMA_LOCATION (default "https://raw.githubusercontent.com/garethr")
--version Display the kubeval version information and exit
The command has three important features:
- You can pass one or more files as arguments, including using wildcard
expansion. Each file will be validated in turn, and
exit with a non-zero code if any of the files fail validation.
- You can toggle between the upstream Kubernetes definitions and the
expanded OpenShift ones using the
--openshift flag. The default is
to use the upstream Kubernetes definitions.
- You can pass a version of Kubernetes or OpenShift and the relevant
type schemas for that version will be used. For instance:
$ kubeval -v 1.6.6 my-deployment.yaml
$ kubeval --openshift -v 1.5.1 my-deployment.yaml
After installing with you prefered dependency management tool, import the relevant module.
The module provides one public function,
Validate, which can be used
results, err := kubeval.Validate(fileContents, fileName)
The method signature for
Validate(config byte, fileName string) (ValidationResult, error)
The simples way of seeing it's usage is probably in the
command line tool source code.
kubeval should be useful now but can be obviously improved in a number
of ways. If you have suggestions for improvements or new features, or
run into a bug please open issues against the GitHub
repository. Pull requests also