actions/kubeconform
9
0
Fork 0
mirror of https://github.com/yannh/kubeconform.git synced 2026-02-19 01:47:02 +00:00
Code Issues Projects Releases 1 Packages Wiki Activity Actions

docs: update usage

Browse source
This commit is contained in:
Edwin Smith 2024-10-09 08:30:18 -05:00
parent 0318a05418
commit fc5cc50d56
No known key found for this signature in database
1 changed files with 75 additions and 63 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

134
Readme.md
View file

@ -10,13 +10,14 @@
It is inspired by, contains code from and is designed to stay close to It is inspired by, contains code from and is designed to stay close to
[Kubeval](https://github.com/instrumenta/kubeval), but with the following improvements: [Kubeval](https://github.com/instrumenta/kubeval), but with the following improvements:
* **high performance**: will validate & download manifests over multiple routines, caching
downloaded files in memory - **high performance**: will validate & download manifests over multiple routines, caching
* configurable list of **remote, or local schemas locations**, enabling validating Kubernetes downloaded files in memory
custom resources (CRDs) and offline validation capabilities - configurable list of **remote, or local schemas locations**, enabling validating Kubernetes
* uses by default a [self-updating fork](https://github.com/yannh/kubernetes-json-schema) of the schemas registry maintained custom resources (CRDs) and offline validation capabilities
by the kubernetes-json-schema project - which guarantees - uses by default a [self-updating fork](https://github.com/yannh/kubernetes-json-schema) of the schemas registry maintained
up-to-date **schemas for all recent versions of Kubernetes**. 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> <details><summary><h4>Speed comparison with Kubeval</h4></summary><p>
Running on a pretty large kubeconfigs setup, on a laptop with 4 cores: Running on a pretty large kubeconfigs setup, on a laptop with 4 cores:
@ -37,21 +38,21 @@ sys 0m1,069s
## Table of contents ## Table of contents
* [A small overview of Kubernetes manifest validation](#a-small-overview-of-kubernetes-manifest-validation) - [A small overview of Kubernetes manifest validation](#a-small-overview-of-kubernetes-manifest-validation)
* [Limits of Kubeconform validation](#Limits-of-Kubeconform-validation) - [Limits of Kubeconform validation](#Limits-of-Kubeconform-validation)
* [Installation](#Installation) - [Installation](#Installation)
* [Usage](#Usage) - [Usage](#Usage)
* [Usage examples](#Usage-examples) - [Usage examples](#Usage-examples)
* [Proxy support](#Proxy-support) - [Proxy support](#Proxy-support)
* [Overriding schemas location](#Overriding-schemas-location) - [Overriding schemas location](#Overriding-schemas-location)
* [CustomResourceDefinition (CRD) Support](#CustomResourceDefinition-CRD-Support) - [CustomResourceDefinition (CRD) Support](#CustomResourceDefinition-CRD-Support)
* [OpenShift schema Support](#OpenShift-schema-Support) - [OpenShift schema Support](#OpenShift-schema-Support)
* [Integrating Kubeconform in the CI](#Integrating-Kubeconform-in-the-CI) - [Integrating Kubeconform in the CI](#Integrating-Kubeconform-in-the-CI)
* [Github Workflow](#Github-Workflow) - [Github Workflow](#Github-Workflow)
* [Gitlab-CI](#Gitlab-CI) - [Gitlab-CI](#Gitlab-CI)
* [Helm charts](#helm-charts) - [Helm charts](#helm-charts)
* [Using kubeconform as a Go Module](#Using-kubeconform-as-a-Go-Module) - [Using kubeconform as a Go Module](#Using-kubeconform-as-a-Go-Module)
* [Credits](#Credits) - [Credits](#Credits)
## A small overview of Kubernetes manifest validation ## A small overview of Kubernetes manifest validation
@ -103,51 +104,55 @@ $ go install github.com/yannh/kubeconform/cmd/kubeconform@latest
``` ```
$ kubeconform -h $ kubeconform -h
Usage: kubeconform [OPTION]... [FILE OR FOLDER]... Usage: ./kubeconform [OPTION]... [FILE OR FOLDER]...
-cache string -cache string
cache schemas downloaded via HTTP to this folder cache schemas downloaded via HTTP to this folder
-debug -debug
print debug information print debug information
-exit-on-error -exit-on-error
immediately stop execution when the first error is encountered immediately stop execution when the first error is encountered
-h show help information -h show help information
-ignore-filename-pattern value -ignore-filename-pattern value
regular expression specifying paths to ignore (can be specified multiple times) regular expression specifying paths to ignore (can be specified multiple times)
-ignore-missing-schemas -ignore-missing-schemas
skip files with missing schemas instead of failing skip files with missing schemas instead of failing
-inject-missing-defaults
Inject missing required fields with defaults from the schema (default true)
-insecure-skip-tls-verify -insecure-skip-tls-verify
disable verification of the server's SSL certificate. This will make your HTTPS connections insecure disable verification of the server's SSL certificate. This will make your HTTPS connections insecure
-kubernetes-version string -kubernetes-version value
version of Kubernetes to validate against, e.g.: 1.18.0 (default "master") version of Kubernetes to validate against, e.g.: 1.18.0 (default master)
-n int -n int
number of goroutines to run concurrently (default 4) number of goroutines to run concurrently (default 4)
-output string -output string
output format - json, junit, pretty, tap, text (default "text") output format - json, junit, pretty, tap, text (default "text")
-reject string -reject string
comma-separated list of kinds or GVKs to reject comma-separated list of kinds or GVKs to reject
-schema-location value -schema-location value
override schemas location search path (can be specified multiple times) override schemas location search path (can be specified multiple times)
-skip string -skip string
comma-separated list of kinds or GVKs to ignore comma-separated list of kinds or GVKs to ignore
-strict -strict
disallow additional properties not in schema or duplicated keys disallow additional properties not in schema or duplicated keys
-summary -summary
print a summary at the end (ignored for junit output) print a summary at the end (ignored for junit output)
-v show version information -v show version information
-verbose -verbose
print results for all resources (ignored for tap and junit output) print results for all resources (ignored for tap and junit output)
``` ```
### Usage examples ### Usage examples
* Validating a single, valid file - Validating a single, valid file
```bash ```bash
$ kubeconform fixtures/valid.yaml $ kubeconform fixtures/valid.yaml
$ echo $? $ echo $?
0 0
``` ```
* Validating a single invalid file, setting output to json, and printing a summary - Validating a single invalid file, setting output to json, and printing a summary
```bash ```bash
$ kubeconform -summary -output json fixtures/invalid.yaml $ kubeconform -summary -output json fixtures/invalid.yaml
{ {
@ -171,13 +176,15 @@ $ echo $?
1 1
``` ```
* Passing manifests via Stdin - Passing manifests via Stdin
```bash ```bash
cat fixtures/valid.yaml | ./bin/kubeconform -summary cat fixtures/valid.yaml | ./bin/kubeconform -summary
Summary: 1 resource found parsing stdin - Valid: 1, Invalid: 0, Errors: 0 Skipped: 0 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 - Validating a file, ignoring its resource using both Kind, and GVK (Group, Version, Kind) notations
``` ```
# This will ignore ReplicationController for all apiVersions # This will ignore ReplicationController for all apiVersions
$ kubeconform -summary -skip ReplicationController fixtures/valid.yaml $ kubeconform -summary -skip ReplicationController fixtures/valid.yaml
@ -188,7 +195,8 @@ $ kubeconform -summary -skip v1/ReplicationController fixtures/valid.yaml
Summary: 1 resource found in 1 file - Valid: 0, Invalid: 0, Errors: 0, Skipped: 1 Summary: 1 resource found in 1 file - Valid: 0, Invalid: 0, Errors: 0, Skipped: 1
``` ```
* Validating a folder, increasing the number of parallel workers - Validating a folder, increasing the number of parallel workers
``` ```
$ kubeconform -summary -n 16 fixtures $ kubeconform -summary -n 16 fixtures
fixtures/crd_schema.yaml - CustomResourceDefinition trainingjobs.sagemaker.aws.amazon.com failed validation: could not find schema for CustomResourceDefinition fixtures/crd_schema.yaml - CustomResourceDefinition trainingjobs.sagemaker.aws.amazon.com failed validation: could not find schema for CustomResourceDefinition
@ -212,25 +220,28 @@ schemas from https://github.com/yannh/kubernetes-json-schema. Kubeconform howeve
schemas locations - HTTP(s) URLs, or local filesystem paths, in which case it will lookup for schema definitions 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. 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 - If the `-schema-location` value does not end with `.json`, Kubeconform will assume filenames / a file
structure identical to that of [kubernetesjsonschema.dev](https://kubernetesjsonschema.dev/) or [yannh/kubernetes-json-schema](https://github.com/yannh/kubernetes-json-schema). structure identical to that of [kubernetesjsonschema.dev](https://kubernetesjsonschema.dev/) or [yannh/kubernetes-json-schema](https://github.com/yannh/kubernetes-json-schema).
* if the `-schema-location` value ends with `.json` - Kubeconform assumes the value is a **Go templated - 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. 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 `-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 equivalent:** **The following command lines are equivalent:**
```bash ```bash
$ kubeconform fixtures/valid.yaml $ kubeconform fixtures/valid.yaml
$ kubeconform -schema-location default fixtures/valid.yaml $ kubeconform -schema-location default fixtures/valid.yaml
$ kubeconform -schema-location 'https://raw.githubusercontent.com/yannh/kubernetes-json-schema/master/{{.NormalizedKubernetesVersion}}-standalone{{.StrictSuffix}}/{{.ResourceKind}}{{.KindSuffix}}.json' fixtures/valid.yaml $ kubeconform -schema-location 'https://raw.githubusercontent.com/yannh/kubernetes-json-schema/master/{{.NormalizedKubernetesVersion}}-standalone{{.StrictSuffix}}/{{.ResourceKind}}{{.KindSuffix}}.json' fixtures/valid.yaml
``` ```
Here are the variables you can use in -schema-location: Here are the variables you can use in -schema-location:
* *NormalizedKubernetesVersion* - Kubernetes Version, prefixed by v
* *StrictSuffix* - "-strict" or "" depending on whether validation is running in strict mode or not - _NormalizedKubernetesVersion_ - Kubernetes Version, prefixed by v
* *ResourceKind* - Kind of the Kubernetes Resource - _StrictSuffix_ - "-strict" or "" depending on whether validation is running in strict mode or not
* *ResourceAPIVersion* - Version of API used for the resource - "v1" in "apiVersion: monitoring.coreos.com/v1" - _ResourceKind_ - Kind of the Kubernetes Resource
* *Group* - the group name as stated in this resource's definition - "monitoring.coreos.com" in "apiVersion: monitoring.coreos.com/v1" - _ResourceAPIVersion_ - Version of API used for the resource - "v1" in "apiVersion: monitoring.coreos.com/v1"
* *KindSuffix* - suffix computed from apiVersion - for compatibility with `Kubeval` schema registries - _Group_ - the group name as stated in this resource's definition - "monitoring.coreos.com" in "apiVersion: monitoring.coreos.com/v1"
- _KindSuffix_ - suffix computed from apiVersion - for compatibility with `Kubeval` schema registries
### CustomResourceDefinition (CRD) Support ### CustomResourceDefinition (CRD) Support
@ -298,6 +309,7 @@ can be used directly in a Github Action, once logged in using a [_Github Token_]
### Github Workflow ### Github Workflow
Example: Example:
```yaml ```yaml
name: kubeconform name: kubeconform
on: push on: push
@ -310,7 +322,7 @@ jobs:
- uses: actions/checkout@v2 - uses: actions/checkout@v2
- uses: docker://ghcr.io/yannh/kubeconform:latest - uses: docker://ghcr.io/yannh/kubeconform:latest
with: with:
entrypoint: '/kubeconform' entrypoint: "/kubeconform"
args: "-summary -output json kubeconfigs/" args: "-summary -output json kubeconfigs/"
``` ```
@ -331,7 +343,7 @@ lint-kubeconform:
name: ghcr.io/yannh/kubeconform:latest-alpine name: ghcr.io/yannh/kubeconform:latest-alpine
entrypoint: [""] entrypoint: [""]
script: script:
- /kubeconform -summary -output json kubeconfigs/ - /kubeconform -summary -output json kubeconfigs/
``` ```
See [issue 106](https://github.com/yannh/kubeconform/issues/106) for more details. See [issue 106](https://github.com/yannh/kubeconform/issues/106) for more details.
@ -354,5 +366,5 @@ Additional documentation on [pkg.go.dev](https://pkg.go.dev/github.com/yannh/kub
## Credits ## Credits
* @garethr for the [Kubeval](https://github.com/instrumenta/kubeval) and - @garethr for the [Kubeval](https://github.com/instrumenta/kubeval) and
[kubernetes-json-schema](https://github.com/instrumenta/kubernetes-json-schema) projects ❤️ [kubernetes-json-schema](https://github.com/instrumenta/kubernetes-json-schema) projects ❤️