Using Kubeval
Kubeval is used to validate one or more Kubernetes configuration files, and is often used locally as part of a development workflow as well as in CI pipelines.
At the most basic level, Kubeval is used like so:
$ kubeval my-invalid-rc.yaml
WARN - my-invalid-rc.yaml contains an invalid ReplicationController - spec.replicas: Invalid type. Expected: integer, given: string
$ echo $?
1
Strict schemas
The Kubernetes API allows for specifying properties on objects that are not part of the schemas.
However, kubectl
will throw an error if you use it with such files. Kubeval can be
used to simulate this behaviour using the --strict
flag.
$ kubeval additional-properties.yaml
PASS - additional-properties.yaml contains a valid ReplicationController
$ echo $?
0
$ kubeval --strict additional-properties.yaml
WARN - additional-properties.yaml contains an invalid ReplicationController - spec: Additional property replicas is not allowed
$ echo $?
1
If you're using kubectl
you may find it useful to always set the --strict
flag.
Stdin
Alternatively Kubeval can also take input via stdin
which can make using
it as part of an automated pipeline easier by removing the need to securely
manage temporary files.
$ cat my-invalid-rc.yaml | kubeval
WARN - stdin contains an invalid ReplicationController - spec.replicas: Invalid type. Expected: integer, given: string
$ echo $?
1
To make the output of pipelines more readable, a filename can be injected
to replace stdin
in the output:
$ cat my-invalid-rc.yaml | kubeval --filename="my-invalid-rc.yaml"
WARN - my-invalid-rc.yaml contains an invalid ReplicationController - spec.replicas: Invalid type. Expected: integer, given: string
$ echo $?
1
CRDs
Currently kubeval relies on schemas generated from the Kubernetes API. This means it's not possible to validate resources using CRDs. Currently you need to pass a flag to ignore missing schemas, though this may change in a future major version.
$ kubeval --ignore-missing-schemas fixtures/test_crd.yaml
WARN - Set to ignore missing schemas
WARN - fixtures/test_crd.yaml containing a SealedSecret was not validated against a schema
If you would prefer to be more explicit about which custom resources to skip you can instead provide a list of resources to skip like so.
$ kubeval --skip-kinds SealedSecret fixtures/test_crd.yaml
WARN - fixtures/test_crd.yaml containing a SealedSecret was not validated against a schema
Helm
Helm chart configurations generally have a reference to the source template in a comment like so:
# Source: chart/templates/frontend.yaml
When kubeval detects these comments it will report the relevant chart template files in the output.
$ kubeval fixtures/multi_valid_source.yaml
PASS - chart/templates/primary.yaml contains a valid Service
PASS - chart/templates/primary.yaml contains a valid ReplicationControlle
Configuring Output
The output of kubeval
can be configured using the --output
flag (-o
).
As of today kubeval
supports the following output types:
- Plaintext
--output=stdout
- JSON:
--output=json
- TAP:
--output=tap
Example Output
Plaintext
$ kubeval my-invalid-rc.yaml
WARN - my-invalid-rc.yaml contains an invalid ReplicationController - spec.replicas: Invalid type. Expected: integer, given: string
JSON
$ kubeval fixtures/invalid.yaml -o json
[
{
"filename": "fixtures/invalid.yaml",
"kind": "ReplicationController",
"status": "invalid",
"errors": [
"spec.replicas: Invalid type. Expected: [integer,null], given: string"
]
}
]
TAP
$ kubeval fixtures/invalid.yaml -o tap
1..1
not ok 1 - fixtures/invalid.yaml (ReplicationController) - spec.replicas: Invalid type. Expected: [integer,null], given: string
Full usage instructions
$ kubeval --help
Validate a Kubernetes YAML file against the relevant schema
Usage:
kubeval <file> [file...] [flags]
Flags:
-d, --directories strings A comma-separated list of directories to recursively search for YAML documents
--exit-on-error Immediately stop execution when the first error is encountered
-f, --filename string filename to be displayed when testing manifests read from stdin (default "stdin")
--force-color Force colored output even if stdout is not a TTY
-h, --help help for kubeval
--ignore-missing-schemas Skip validation for resource definitions without a schema
-v, --kubernetes-version string Version of Kubernetes to validate against (default "master")
--openshift Use OpenShift schemas instead of upstream Kubernetes
-o, --output string The format of the output of this script. Options are: [stdout json]
--schema-location string Base URL used to download schemas. Can also be specified with the environment variable KUBEVAL_SCHEMA_LOCATION
--skip-kinds strings Comma-separated list of case-sensitive kinds to skip when validating against schemas
--strict Disallow additional properties not in schema
--version version for kubeval
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
kubeval
will 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