{"id":13498680,"url":"https://github.com/yannh/kubeconform","last_synced_at":"2025-05-14T12:02:29.538Z","repository":{"id":37003411,"uuid":"268015482","full_name":"yannh/kubeconform","owner":"yannh","description":"A FAST Kubernetes manifests validator, with support for Custom Resources!","archived":false,"fork":false,"pushed_at":"2025-02-16T17:30:35.000Z","size":6310,"stargazers_count":2579,"open_issues_count":74,"forks_count":139,"subscribers_count":6,"default_branch":"master","last_synced_at":"2025-05-07T11:41:46.094Z","etag":null,"topics":["compliance","kubernetes","validation"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/yannh.png","metadata":{"files":{"readme":"Readme.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-05-30T05:28:20.000Z","updated_at":"2025-05-07T10:26:22.000Z","dependencies_parsed_at":"2023-02-14T03:01:59.172Z","dependency_job_id":"ecb8e318-5019-4639-b84c-072359172114","html_url":"https://github.com/yannh/kubeconform","commit_stats":{"total_commits":341,"total_committers":38,"mean_commits":8.973684210526315,"dds":0.3782991202346041,"last_synced_commit":"1bd44986dd3d281725afab6b173770ec86b454fc"},"previous_names":[],"tags_count":32,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yannh%2Fkubeconform","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yannh%2Fkubeconform/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yannh%2Fkubeconform/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yannh%2Fkubeconform/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/yannh","download_url":"https://codeload.github.com/yannh/kubeconform/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254140738,"owners_count":22021218,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["compliance","kubernetes","validation"],"created_at":"2024-07-31T21:00:40.823Z","updated_at":"2025-05-14T12:02:29.496Z","avatar_url":"https://github.com/yannh.png","language":"Go","funding_links":[],"categories":["Supported Linters","kubernetes","Go","Kubernetes","Other","Configuration Management"],"sub_categories":["Kubernetes static analysis","Kubernetes // Dashboards, UI, Reporting and Validation"],"readme":"\u003cimg width=\"50%\" alt=\"Kubeconform-GitHub-Hero\" src=\"https://user-images.githubusercontent.com/19731161/142411871-f695e40c-bfa8-43ca-97c0-94c256749732.png\"\u003e\n\u003chr\u003e\n\n[![Build status](https://github.com/yannh/kubeconform/actions/workflows/main.yml/badge.svg)](https://github.com/yannh/kubeconform/actions?query=branch%3Amaster)\n[![Homebrew](https://img.shields.io/badge/dynamic/json.svg?url=https://formulae.brew.sh/api/formula/kubeconform.json\u0026query=$.versions.stable\u0026label=homebrew)](https://formulae.brew.sh/formula/kubeconform)\n[![Go Report card](https://goreportcard.com/badge/github.com/yannh/kubeconform)](https://goreportcard.com/report/github.com/yannh/kubeconform)\n[![PkgGoDev](https://pkg.go.dev/badge/github.com/yannh/kubeconform/pkg/validator)](https://pkg.go.dev/github.com/yannh/kubeconform/pkg/validator)\n\n`Kubeconform` is a Kubernetes manifest validation tool. Incorporate it into your CI, or use it locally to validate your Kubernetes configuration!\n\nIt is inspired by, contains code from and is designed to stay close to\n[Kubeval](https://github.com/instrumenta/kubeval), but with the following improvements:\n * **high performance**: will validate \u0026 download manifests over multiple routines, caching\n   downloaded files in memory\n * configurable list of **remote, or local schemas locations**, enabling validating Kubernetes\n   custom resources (CRDs) and offline validation capabilities\n * uses by default a [self-updating fork](https://github.com/yannh/kubernetes-json-schema) of the schemas registry maintained\n   by the kubernetes-json-schema project - which guarantees\n   up-to-date **schemas for all recent versions of Kubernetes**.\n   \n\u003cdetails\u003e\u003csummary\u003e\u003ch4\u003eSpeed comparison with Kubeval\u003c/h4\u003e\u003c/summary\u003e\u003cp\u003e\nRunning on a pretty large kubeconfigs setup, on a laptop with 4 cores:\n   \n```bash\n$ time kubeconform -ignore-missing-schemas -n 8 -summary  preview staging production\nSummary: 50714 resources found in 35139 files - Valid: 27334, Invalid: 0, Errors: 0 Skipped: 23380\nreal\t0m6,710s\nuser\t0m38,701s\nsys\t0m1,161s\n$ time kubeval -d preview,staging,production --ignore-missing-schemas --quiet\n[... Skipping output]\nreal\t0m35,336s\nuser\t0m0,717s\nsys\t0m1,069s\n```\n\u003c/p\u003e\u003c/details\u003e\n\n## Table of contents\n\n* [A small overview of Kubernetes manifest validation](#a-small-overview-of-kubernetes-manifest-validation)\n  * [Limits of Kubeconform validation](#Limits-of-Kubeconform-validation)\n* [Installation](#Installation)\n* [Usage](#Usage)\n  * [Usage examples](#Usage-examples)\n  * [Proxy support](#Proxy-support)\n* [Overriding schemas location](#Overriding-schemas-location)\n  * [CustomResourceDefinition (CRD) Support](#CustomResourceDefinition-CRD-Support)\n  * [OpenShift schema Support](#OpenShift-schema-Support)\n* [Integrating Kubeconform in the CI](#Integrating-Kubeconform-in-the-CI)\n  * [Github Workflow](#Github-Workflow)\n  * [Gitlab-CI](#Gitlab-CI)\n* [Helm charts](#helm-charts)\n* [Using kubeconform as a Go Module](#Using-kubeconform-as-a-Go-Module)\n* [Credits](#Credits)\n\n## A small overview of Kubernetes manifest validation\n\nKubernetes's API is described using the [OpenAPI (formerly swagger) specification](https://www.openapis.org),\nin a [file](https://github.com/kubernetes/kubernetes/blob/master/api/openapi-spec/swagger.json) checked into\nthe main Kubernetes repository.\n\nBecause of the state of the tooling to perform validation against OpenAPI schemas, projects usually convert\nthe OpenAPI schemas to [JSON schemas](https://json-schema.org/) first. Kubeval relies on\n[instrumenta/OpenApi2JsonSchema](https://github.com/instrumenta/openapi2jsonschema) to convert Kubernetes' Swagger file\nand break it down into multiple JSON schemas, stored in github at\n[instrumenta/kubernetes-json-schema](https://github.com/instrumenta/kubernetes-json-schema) and published on\n[kubernetesjsonschema.dev](https://kubernetesjsonschema.dev/).\n\n`Kubeconform` relies on [a fork of kubernetes-json-schema](https://github.com/yannh/kubernetes-json-schema/)\nthat is more meticulously kept up-to-date, and contains schemas for all recent versions of Kubernetes.\n\n### Limits of Kubeconform validation\n\n`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](https://github.com/yannh/kubeconform/issues/65), [#122](https://github.com/yannh/kubeconform/issues/122), [#142](https://github.com/yannh/kubeconform/issues/142)). You can use a 3rd-party tool or the `kubectl --dry-run=server` command to fill the missing (validation) gap.\n\n## Installation\n\nIf you are a [Homebrew](https://brew.sh/) user, you can install by running:\n\n```bash\n$ brew install kubeconform\n```\n\nIf you are a Windows user, you can install with [winget](https://learn.microsoft.com/en-us/windows/package-manager/winget/) by running:\n\n```cmd\nwinget install YannHamon.kubeconform\n```\n\nYou can also download the latest version from the [release page](https://github.com/yannh/kubeconform/releases).\n\nAnother way of installation is via Golang's package manager:\n\n```bash\n# With a specific version tag\n$ go install github.com/yannh/kubeconform/cmd/kubeconform@v0.4.13\n\n# Latest version\n$ go install github.com/yannh/kubeconform/cmd/kubeconform@latest\n```\n\n## Usage\n\n```\n$ kubeconform -h\nUsage: kubeconform [OPTION]... [FILE OR FOLDER]...\n  -cache string\n    \tcache schemas downloaded via HTTP to this folder\n  -debug\n    \tprint debug information\n  -exit-on-error\n    \timmediately stop execution when the first error is encountered\n  -h\tshow help information\n  -ignore-filename-pattern value\n    \tregular expression specifying paths to ignore (can be specified multiple times)\n  -ignore-missing-schemas\n    \tskip files with missing schemas instead of failing\n  -insecure-skip-tls-verify\n    \tdisable verification of the server's SSL certificate. This will make your HTTPS connections insecure\n  -kubernetes-version string\n    \tversion of Kubernetes to validate against, e.g.: 1.18.0 (default \"master\")\n  -n int\n    \tnumber of goroutines to run concurrently (default 4)\n  -output string\n    \toutput format - json, junit, pretty, tap, text (default \"text\")\n  -reject string\n    \tcomma-separated list of kinds or GVKs to reject\n  -schema-location value\n    \toverride schemas location search path (can be specified multiple times)\n  -skip string\n    \tcomma-separated list of kinds or GVKs to ignore\n  -strict\n    \tdisallow additional properties not in schema or duplicated keys\n  -summary\n    \tprint a summary at the end (ignored for junit output)\n  -v\tshow version information\n  -verbose\n    \tprint results for all resources (ignored for tap and junit output)\n```\n\n### Usage examples\n\n* Validating a single, valid file\n```bash\n$ kubeconform fixtures/valid.yaml\n$ echo $?\n0\n```\n\n* Validating a single invalid file, setting output to json, and printing a summary\n```bash\n$ kubeconform -summary -output json fixtures/invalid.yaml\n{\n  \"resources\": [\n    {\n      \"filename\": \"fixtures/invalid.yaml\",\n      \"kind\": \"ReplicationController\",\n      \"version\": \"v1\",\n      \"status\": \"INVALID\",\n      \"msg\": \"Additional property templates is not allowed - Invalid type. Expected: [integer,null], given: string\"\n    }\n  ],\n  \"summary\": {\n    \"valid\": 0,\n    \"invalid\": 1,\n    \"errors\": 0,\n    \"skipped\": 0\n  }\n}\n$ echo $?\n1\n```\n\n* Passing manifests via Stdin\n```bash\ncat fixtures/valid.yaml  | ./bin/kubeconform -summary\nSummary: 1 resource found parsing stdin - Valid: 1, Invalid: 0, Errors: 0 Skipped: 0\n```\n\n* Validating a file, ignoring its resource using both Kind, and GVK (Group, Version, Kind) notations\n```\n# This will ignore ReplicationController for all apiVersions\n$ kubeconform -summary -skip ReplicationController fixtures/valid.yaml\nSummary: 1 resource found in 1 file - Valid: 0, Invalid: 0, Errors: 0, Skipped: 1\n\n# This will ignore ReplicationController only for apiVersion v1\n$ kubeconform -summary -skip v1/ReplicationController fixtures/valid.yaml\nSummary: 1 resource found in 1 file - Valid: 0, Invalid: 0, Errors: 0, Skipped: 1\n```\n\n* Validating a folder, increasing the number of parallel workers\n```\n$ kubeconform -summary -n 16 fixtures\nfixtures/crd_schema.yaml - CustomResourceDefinition trainingjobs.sagemaker.aws.amazon.com failed validation: could not find schema for CustomResourceDefinition\nfixtures/invalid.yaml - ReplicationController bob is invalid: Invalid type. Expected: [integer,null], given: string\n[...]\nSummary: 65 resources found in 34 files - Valid: 55, Invalid: 2, Errors: 8 Skipped: 0\n```\n\n### Proxy support\n\n`Kubeconform` will respect the **HTTPS_PROXY** variable when downloading schema files.\n\n```bash\n$ HTTPS_PROXY=proxy.local bin/kubeconform fixtures/valid.yaml\n```\n\n## Overriding schemas location\n\nWhen the `-schema-location` parameter is not used, or set to `default`, kubeconform will default to downloading\nschemas from https://github.com/yannh/kubernetes-json-schema. Kubeconform however supports passing one, or multiple,\nschemas locations - HTTP(s) URLs, or local filesystem paths, in which case it will lookup for schema definitions\nin each of them, in order, stopping as soon as a matching file is found.\n\n * If the `-schema-location` value does not end with `.json`, Kubeconform will assume filenames / a file\n structure identical to that of [kubernetesjsonschema.dev](https://kubernetesjsonschema.dev/) or [yannh/kubernetes-json-schema](https://github.com/yannh/kubernetes-json-schema).\n * if the `-schema-location` value ends with `.json` - Kubeconform assumes the value is a **Go templated\n string** that indicates how to search for JSON schemas.\n* 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`.\n\n**The following command lines are equivalent:**\n```bash\n$ kubeconform fixtures/valid.yaml\n$ kubeconform -schema-location default fixtures/valid.yaml\n$ kubeconform -schema-location 'https://raw.githubusercontent.com/yannh/kubernetes-json-schema/master/{{.NormalizedKubernetesVersion}}-standalone{{.StrictSuffix}}/{{.ResourceKind}}{{.KindSuffix}}.json' fixtures/valid.yaml\n```\nHere are the variables you can use in -schema-location:\n * *NormalizedKubernetesVersion* - Kubernetes Version, prefixed by v\n * *StrictSuffix* - \"-strict\" or \"\" depending on whether validation is running in strict mode or not\n * *ResourceKind* - Kind of the Kubernetes Resource\n * *ResourceAPIVersion* - Version of API used for the resource - \"v1\" in \"apiVersion: monitoring.coreos.com/v1\"\n * *Group* - the group name as stated in this resource's definition - \"monitoring.coreos.com\" in \"apiVersion: monitoring.coreos.com/v1\"\n * *KindSuffix* - suffix computed from apiVersion - for compatibility with `Kubeval` schema registries\n\n### CustomResourceDefinition (CRD) Support\n\nBecause Custom Resources (CR) are not native Kubernetes objects, they are not included in the default schema.  \nIf your CRs are present in [Datree's CRDs-catalog](https://github.com/datreeio/CRDs-catalog), you can specify this project as an additional registry to lookup:\n  \n```bash\n# Look in the CRDs-catalog for the desired schema/s\n$ kubeconform -schema-location default -schema-location 'https://raw.githubusercontent.com/datreeio/CRDs-catalog/main/{{.Group}}/{{.ResourceKind}}_{{.ResourceAPIVersion}}.json' [MANIFEST]\n```\n\nIf your CRs are not present in the CRDs-catalog, you will need to manually pull the CRDs manifests from your cluster and convert the `OpenAPI.spec` to JSON schema format.\n\n\u003cdetails\u003e\u003csummary\u003eConverting an OpenAPI file to a JSON Schema\u003c/summary\u003e\n\u003cp\u003e\n\n`Kubeconform` uses JSON schemas to validate Kubernetes resources. For Custom Resource, the CustomResourceDefinition\nfirst needs to be converted to JSON Schema. A script is provided to convert these CustomResourceDefinitions\nto JSON schema. Here is an example how to use it:\n\n```bash\n$ python ./scripts/openapi2jsonschema.py https://raw.githubusercontent.com/aws/amazon-sagemaker-operator-for-k8s/master/config/crd/bases/sagemaker.aws.amazon.com_trainingjobs.yaml\nJSON schema written to trainingjob_v1.json\n```\n\nBy default, the file name output format is `{kind}_{version}`. The `FILENAME_FORMAT` environment variable can be used to change the output file name (Available variables: `kind`, `group`, `fullgroup`, `version`):\n\n```\n$ export FILENAME_FORMAT='{kind}-{group}-{version}'\n$ ./scripts/openapi2jsonschema.py https://raw.githubusercontent.com/aws/amazon-sagemaker-operator-for-k8s/master/config/crd/bases/sagemaker.aws.amazon.com_trainingjobs.yaml\nJSON schema written to trainingjob-sagemaker-v1.json\n\n$ export FILENAME_FORMAT='{kind}-{fullgroup}-{version}'\n$ ./scripts/openapi2jsonschema.py https://raw.githubusercontent.com/aws/amazon-sagemaker-operator-for-k8s/master/config/crd/bases/sagemaker.aws.amazon.com_trainingjobs.yaml\nJSON schema written to trainingjob-sagemaker.aws.amazon.com-v1.json\n```\n\nAfter converting your CRDs to JSON schema files, you can use `kubeconform` to validate your CRs against them:\n\n```\n# If the resource Kind is not found in default, also lookup in the schemas/ folder for a matching file\n$ kubeconform -schema-location default -schema-location 'schemas/{{ .ResourceKind }}{{ .KindSuffix }}.json' fixtures/custom-resource.yaml\n```\n\nℹ️ Datree's [CRD Extractor](https://github.com/datreeio/CRDs-catalog#crd-extractor) is a utility that can be used instead of this manual process.\n\n\u003c/p\u003e\n\u003c/details\u003e\n\n### OpenShift schema Support\n\nYou can validate Openshift manifests using a custom schema location. Set the OpenShift version (v3.10.0-4.1.0) to validate\nagainst using `-kubernetes-version`.\n\n```\nkubeconform -kubernetes-version 3.8.0  -schema-location 'https://raw.githubusercontent.com/garethr/openshift-json-schema/master/{{ .NormalizedKubernetesVersion }}-standalone{{ .StrictSuffix }}/{{ .ResourceKind }}.json'  -summary fixtures/valid.yaml\nSummary: 1 resource found in 1 file - Valid: 1, Invalid: 0, Errors: 0 Skipped: 0\n```\n\n## Integrating Kubeconform in the CI\n\n`Kubeconform` publishes Docker Images to Github's new Container Registry (ghcr.io). These images\ncan be used directly in a Github Action, once logged in using a [_Github Token_](https://github.blog/changelog/2021-03-24-packages-container-registry-now-supports-github_token/).\n\n### Github Workflow\n\nExample:\n```yaml\nname: kubeconform\non: push\njobs:\n  kubeconform:\n    runs-on: ubuntu-latest\n    steps:\n      - name: login to Github Packages\n        run: echo \"${{ github.token }}\" | docker login https://ghcr.io -u ${GITHUB_ACTOR} --password-stdin\n      - uses: actions/checkout@v2\n      - uses: docker://ghcr.io/yannh/kubeconform:latest\n        with:\n          entrypoint: '/kubeconform'\n          args: \"-summary -output json kubeconfigs/\"\n```\n\n_Note on pricing_: Kubeconform relies on Github Container Registry which is currently in Beta. During that period,\n[bandwidth is free](https://docs.github.com/en/packages/guides/about-github-container-registry). After that period,\nbandwidth costs might be applicable. Since bandwidth from Github Packages within Github Actions is free, I expect\nGithub Container Registry to also be usable for free within Github Actions in the future. If that were not to be the\ncase, I might publish the Docker image to a different platform.\n\n### Gitlab-CI\n\nThe Kubeconform Docker image can be used in Gitlab-CI. Here is an example of a Gitlab-CI job:\n\n```yaml\nlint-kubeconform:\n  stage: validate\n  image:\n    name: ghcr.io/yannh/kubeconform:latest-alpine\n    entrypoint: [\"\"]\n  script:\n  - /kubeconform -summary -output json kubeconfigs/\n```\n\nSee [issue 106](https://github.com/yannh/kubeconform/issues/106) for more details.\n\n## Helm charts\n\nThere is a 3rd party [repository](https://github.com/jtyr/kubeconform-helm) that\nallows to use `kubeconform` to test [Helm charts](https://helm.sh) in the form of\na [Helm plugin](https://helm.sh/docs/topics/plugins/) and [`pre-commit`\nhook](https://pre-commit.com/).\n\n## Using kubeconform as a Go Module\n\n**Warning**: This is a work-in-progress, the interface is not yet considered stable. Feedback is encouraged.\n\n`Kubeconform` contains a package that can be used as a library.\nAn example of usage can be found in [examples/main.go](examples/main.go)\n\nAdditional documentation on [pkg.go.dev](https://pkg.go.dev/github.com/yannh/kubeconform/pkg/validator)\n\n## Credits\n\n * @garethr for the [Kubeval](https://github.com/instrumenta/kubeval) and\n [kubernetes-json-schema](https://github.com/instrumenta/kubernetes-json-schema) projects ❤️\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyannh%2Fkubeconform","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fyannh%2Fkubeconform","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyannh%2Fkubeconform/lists"}