Kubeconform is a Kubernetes manifest validation tool. Incorporate it into your CI, or use it locally to validate your Kubernetes configuration!

It is inspired by, contains code from and is designed to stay close to Kubeval, but with the following improvements:

high performance: will validate & download manifests over multiple routines, caching downloaded files in memory
configurable list of remote, or local schemas locations, enabling validating Kubernetes custom resources (CRDs) and offline validation capabilities
uses by default a self-updating fork of the schemas registry maintained by the kubernetes-json-schema project - which guarantees up-to-date schemas for all recent versions of Kubernetes.

<details><summary><h4>Speed comparison with Kubeval</h4></summary><p> Running on a pretty large kubeconfigs setup, on a laptop with 4 cores:

$ time kubeconform -ignore-missing-schemas -n 8 -summary  preview staging production
Summary: 50714 resources found in 35139 files - Valid: 27334, Invalid: 0, Errors: 0 Skipped: 23380
real	0m6,710s
user	0m38,701s
sys	0m1,161s
$ time kubeval -d preview,staging,production --ignore-missing-schemas --quiet
[... Skipping output]
real	0m35,336s
user	0m0,717s
sys	0m1,069s

</p></details>

A small overview of Kubernetes manifest validation
- Limits of Kubeconform validation
Installation
Usage
- Usage examples
- Proxy support
Overriding schemas location
- CustomResourceDefinition (CRD) Support
- OpenShift schema Support
Integrating Kubeconform in the CI
- Github Workflow
- Gitlab-CI
Helm charts
Using kubeconform as a Go Module
Credits

A small overview of Kubernetes manifest validation

Kubernetes's API is described using the OpenAPI (formerly swagger) specification, in a file checked into the main Kubernetes repository.

Because of the state of the tooling to perform validation against OpenAPI schemas, projects usually convert the OpenAPI schemas to JSON schemas first. Kubeval relies on instrumenta/OpenApi2JsonSchema to convert Kubernetes' Swagger file and break it down into multiple JSON schemas, stored in github at instrumenta/kubernetes-json-schema and published on kubernetesjsonschema.dev.

Kubeconform relies on a fork of kubernetes-json-schema that is more meticulously kept up-to-date, and contains schemas for all recent versions of Kubernetes.

Limits of Kubeconform validation

Kubeconform, similar to kubeval, only validates manifests using the official Kubernetes OpenAPI specifications. The Kubernetes controllers still perform additional server-side validations that are not part of the OpenAPI specifications. Those server-side validations are not covered by Kubeconform (examples: #65, #122, #142). You can use a 3rd-party tool or the kubectl --dry-run=server command to fill the missing (validation) gap.

Installation

If you are a Homebrew user, you can install by running:

$ brew install kubeconform

If you are a Windows user, you can install with winget by running:

winget install YannHamon.kubeconform

You can also download the latest version from the release page.

Another way of installation is via Golang's package manager:

# With a specific version tag
$ go install github.com/yannh/kubeconform/cmd/kubeconform@v0.4.13

# Latest version
$ go install github.com/yannh/kubeconform/cmd/kubeconform@latest

Usage

$ kubeconform -h
Usage: kubeconform [OPTION]... [FILE OR FOLDER]...
  -cache string
    	cache schemas downloaded via HTTP to this folder
  -debug
    	print debug information
  -exit-on-error
    	immediately stop execution when the first error is encountered
  -h	show help information
  -ignore-filename-pattern value
    	regular expression specifying paths to ignore (can be specified multiple times)
  -ignore-missing-schemas
    	skip files with missing schemas instead of failing
  -insecure-skip-tls-verify
    	disable verification of the server's SSL certificate. This will make your HTTPS connections insecure
  -kubernetes-version string
    	version of Kubernetes to validate against, e.g.: 1.18.0 (default "master")
  -n int
    	number of goroutines to run concurrently (default 4)
  -output string
    	output format - json, junit, pretty, tap, text (default "text")
  -reject string
    	comma-separated list of kinds or GVKs to reject
  -schema-location value
    	override schemas location search path (can be specified multiple times)
  -skip string
    	comma-separated list of kinds or GVKs to ignore
  -strict
    	disallow additional properties not in schema or duplicated keys
  -summary
    	print a summary at the end (ignored for junit output)
  -v	show version information
  -verbose
    	print results for all resources (ignored for tap and junit output)

Usage examples

Validating a single, valid file

$ kubeconform fixtures/valid.yaml
$ echo $?
0

Validating a single invalid file, setting output to json, and printing a summary

$ kubeconform -summary -output json fixtures/invalid.yaml
{
  "resources": [
    {
      "filename": "fixtures/invalid.yaml",
      "kind": "ReplicationController",
      "version": "v1",
      "status": "INVALID",
      "msg": "Additional property templates is not allowed - Invalid type. Expected: [integer,null], given: string"
    }
  ],
  "summary": {
    "valid": 0,
    "invalid": 1,
    "errors": 0,
    "skipped": 0
  }
}
$ echo $?
1

Passing manifests via Stdin

cat fixtures/valid.yaml  | ./bin/kubeconform -summary
Summary: 1 resource found parsing stdin - Valid: 1, Invalid: 0, Errors: 0 Skipped: 0

Validating a file, ignoring its resource using both Kind, and GVK (Group, Version, Kind) notations

# This will ignore ReplicationController for all apiVersions
$ kubeconform -summary -skip ReplicationController fixtures/valid.yaml
Summary: 1 resource found in 1 file - Valid: 0, Invalid: 0, Errors: 0, Skipped: 1

# This will ignore ReplicationController only for apiVersion v1
$ kubeconform -summary -skip v1/ReplicationController fixtures/valid.yaml
Summary: 1 resource found in 1 file - Valid: 0, Invalid: 0, Errors: 0, Skipped: 1

Validating a folder, increasing the number of parallel workers

$ kubeconform -summary -n 16 fixtures
fixtures/crd_schema.yaml - CustomResourceDefinition trainingjobs.sagemaker.aws.amazon.com failed validation: could not find schema for CustomResourceDefinition
fixtures/invalid.yaml - ReplicationController bob is invalid: Invalid type. Expected: [integer,null], given: string
[...]
Summary: 65 resources found in 34 files - Valid: 55, Invalid: 2, Errors: 8 Skipped: 0

Proxy support

Kubeconform will respect the HTTPS_PROXY variable when downloading schema files.

$ HTTPS_PROXY=proxy.local bin/kubeconform fixtures/valid.yaml

Overriding schemas location

When the -schema-location parameter is not used, or set to default, kubeconform will default to downloading schemas from https://github.com/yannh/kubernetes-json-schema. Kubeconform however supports passing one, or multiple, schemas locations - HTTP(s) URLs, or local filesystem paths, in which case it will lookup for schema definitions in each of them, in order, stopping as soon as a matching file is found.

If the -schema-location value does not end with .json, Kubeconform will assume filenames / a file structure identical to that of kubernetesjsonschema.dev or yannh/kubernetes-json-schema.
if the -schema-location value ends with .json - Kubeconform assumes the value is a Go templated string that indicates how to search for JSON schemas.
the -schema-location value of default is an alias for https://raw.githubusercontent.com/yannh/kubernetes-json-schema/master/{{.NormalizedKubernetesVersion}}-standalone{{.StrictSuffix}}/{{.ResourceKind}}{{.KindSuffix}}.json.

**The following command lines are

Kubeconform

Install / Use

README

Table of contents