kubeconform Documentation

Kubeconform is a high-performance Kubernetes manifest validation tool. It checks whether your Kubernetes manifests are valid according to Kubernetes resource definitions.

Key features include:

• High performance: Validates and downloads manifests using multiple routines and caches downloaded files in memory.
• Configurable schema locations: Supports both remote and local schema locations, enabling validation of Custom Resource Definitions (CRDs) and offline validation.
• Up-to-date schemas: Uses a self-updating fork of the kubernetes-json-schema registry, ensuring support for all recent Kubernetes versions.
• Improved logging: Supports multiple output formats including Tap, Junit, and JSON.

To install kubeconform on Linux, download the latest release from the GitHub releases page and move the binary to your local bin directory. For x86_64 architecture, you can use the following command to download, extract, and install it to /usr/local/bin/.

curl -L https://github.com/yannh/kubeconform/releases/latest/download/kubeconform-linux-amd64.tar.gz | tar xvzf - && \
sudo mv kubeconform /usr/local/bin/

To get machine-readable results, use the -output json flag. Combining this with the -summary flag provides a JSON object containing the status of each resource and a high-level summary of valid, invalid, error, and skipped counts. An invalid file will return a non-zero exit code.

$ ./bin/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

Kubeconform requires JSON schemas to validate Kubernetes resources. To validate Custom Resources (CRDs), you must first convert the CRD's OpenAPI specification to a JSON Schema using the provided openapi2jsonschema.py script.

Pass the URL or path to the CRD YAML file as an argument to the script.

$ ./scripts/openapi2jsonschema.py https://raw.githubusercontent.com/aws/amazon-sagemaker-operator-for-k8s/master/config/crd/bases/sagemaker.aws.amazon.com_trainingjobs.yaml
JSON schema written to trainingjob_v1.json

To validate a single YAML or JSON manifest file, pass the file path as an argument to kubeconform. A successful validation returns an exit code of 0.

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

To validate CRDs, you must provide a local or remote registry containing the converted JSON schemas. Kubeconform supports multiple -schema-location flags; it will search through them in order and stop at the first match.

To use a local folder (e.g., schemas/) as a fallback for resources not found in the default registry, pass both the default location and your local path using Go templated strings.

# If the resource Kind is not found in kubernetesjsonschema.dev, also lookup in the schemas/ folder for a matching file
$ ./bin/kubeconform -schema-location default -schema-location 'schemas/{{ .ResourceKind }}{{ .KindSuffix }}.json' fixtures/custom-resource.yaml

Kubeconform provides a package that can be imported and used as a library within your Go applications.

Warning: The library interface is currently a work-in-progress and is not considered stable. Use with caution in production environments.

For detailed API documentation, refer to the package on pkg.go.dev.

You can run kubeconform in your CI pipelines using its official Docker images from ghcr.io.

GitHub Actions

Use the docker:// syntax in a step. Note that you may need to log in to ghcr.io first.

GitLab-CI

Use the ghcr.io/yannh/kubeconform:latest-alpine image. Ensure you override the entrypoint to allow running commands via script.

# GitHub Actions Example
- uses: docker://ghcr.io/yannh/kubeconform:latest
  with:
    entrypoint: '/kubeconform'
    args: "-summary -output json kubeconfigs/"

# GitLab-CI Example
lint-kubeconform:
  stage: validate
  image:
    name: ghcr.io/yannh/kubeconform:latest-alpine
    entrypoint: [""]
  script:
  - /kubeconform -summary -output json kubeconfigs/