Kubeconform

Kubeconform 是一款 Kubernetes 清单验证工具。可将其集成到 CI 中，或在本地使用以验证 Kubernetes 配置！

它受 Kubeval 启发，包含其部分代码，并旨在与 Kubeval 保持相近的功能，但具有以下改进：

• 高性能：通过多协程验证和下载清单，将下载的文件缓存在内存中
• 可配置的远程或本地模式位置列表，支持验证 Kubernetes 自定义资源（CRD）和离线验证功能
• 默认使用 kubernetes-json-schema 项目维护的模式注册表的自更新分支，确保所有近期 Kubernetes 版本的模式都是最新的

与 Kubeval 的速度对比

在一台 4 核笔记本电脑上，对一个相当大的 kubeconfigs 配置进行测试：

$ 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
[... 省略输出 ...]
real	0m35,336s
user	0m0,717s
sys	0m1,069s

目录

• Kubernetes 清单验证简介 Kubeconform 验证的限制
• Kubeconform 验证的限制
• 安装
• 使用方法 使用示例 代理支持
• 使用示例
• 代理支持
• 覆盖模式位置 自定义资源定义（CRD）支持 OpenShift 模式支持
• 自定义资源定义（CRD）支持
• OpenShift 模式支持
• 在 CI 中集成 Kubeconform Github Workflow Gitlab-CI
• Github Workflow
• Gitlab-CI
• Helm 图表
• 将 kubeconform 用作 Go 模块
• 致谢

Kubernetes 清单验证简介

Kubernetes 的 API 使用 OpenAPI（前身为 swagger）规范进行描述，该规范文件已签入 Kubernetes 主仓库。

由于针对 OpenAPI 模式执行验证的工具现状，项目通常会先将 OpenAPI 模式转换为 JSON 模式。Kubeval 依赖 instrumenta/OpenApi2JsonSchema 来转换 Kubernetes 的 Swagger 文件，并将其分解为多个 JSON 模式，这些模式存储在 GitHub 的 instrumenta/kubernetes-json-schema 仓库中，并发布在 kubernetesjsonschema.dev 上。

Kubeconform 依赖 kubernetes-json-schema 的一个分支，该分支更精心地保持更新，并包含所有近期 Kubernetes 版本的模式。

Kubeconform 验证的限制

与 kubeval 类似，Kubeconform 仅使用官方 Kubernetes OpenAPI 规范验证清单。Kubernetes 控制器仍会执行 OpenAPI 规范中未包含的额外服务器端验证。这些服务器端验证不在 Kubeconform 的覆盖范围内（示例：#65、#122、#142）。你可以使用第三方工具或 kubectl --dry-run=server 命令来填补（验证）空白。

安装

如果你是 Homebrew 用户，可以通过以下命令安装：

$ brew install kubeconform

如果你是 Windows 用户，可以通过 winget 安装：

winget install YannHamon.kubeconform

你也可以从https://github.com/yannh/kubeconform/releases%E4%B8%8B%E8%BD%BD%E6%9C%80%E6%96%B0%E7%89%88%E6%9C%AC%E3%80%82

另一种安装方式是通过 Golang 的包管理器：

# 使用特定版本标签
$ go install github.com/yannh/kubeconform/cmd/kubeconform@v0.4.13

# 最新版本
$ go install github.com/yannh/kubeconform/cmd/kubeconform@latest

使用方法

$ 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)

使用示例

• 验证单个有效文件

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

• 验证单个无效文件，设置输出为 json 并打印摘要

$ 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

• 通过标准输入传递清单

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

• 验证文件时，使用 Kind 和 GVK（Group、Version、Kind）表示法忽略其资源

# 忽略所有 apiVersion 的 ReplicationController
$ kubeconform -summary -skip ReplicationController fixtures/valid.yaml
Summary: 1 resource found in 1 file - Valid: 0, Invalid: 0, Errors: 0, Skipped: 1

# 仅忽略 apiVersion v1 的 ReplicationController
$ kubeconform -summary -skip v1/ReplicationController fixtures/valid.yaml
Summary: 1 resource found in 1 file - Valid: 0, Invalid: 0, Errors: 0, Skipped: 1

• 验证文件夹，增加并行工作进程数

$ 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

代理支持

Kubeconform 在下载模式文件时会遵守 HTTPS_PROXY 变量。

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

CustomResourceDefinition (CRD) Support

由于自定义资源（CR）不是原生的Kubernetes对象，因此默认模式中不包含它们。如果您的CR存在于Datree的CRDs-catalog中，您可以将此项目指定为额外的查找 registry：

# Look in the CRDs-catalog for the desired schema/s
$ kubeconform -schema-location default -schema-location 'https://raw.githubusercontent.com/datreeio/CRDs-catalog/main/{{.Group}}/{{.ResourceKind}}_{{.ResourceAPIVersion}}.json' [MANIFEST]

如果您的CR不在CRDs-catalog中，则需要手动从集群中拉取CRD清单，并将OpenAPI.spec转换为JSON模式格式。

Kubeconform使用JSON模式验证Kubernetes资源。对于自定义资源，需要先将CustomResourceDefinition转换为JSON模式。提供了一个脚本用于将这些CustomResourceDefinition转换为JSON模式。以下是使用示例：

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

默认情况下，文件名输出格式为{kind}_{version}。可以使用FILENAME_FORMAT环境变量更改输出文件名（可用变量：kind、group、fullgroup、version）：

$ export FILENAME_FORMAT='{kind}-{group}-{version}'
$ ./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-sagemaker-v1.json

$ export FILENAME_FORMAT='{kind}-{fullgroup}-{version}'
$ ./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-sagemaker.aws.amazon.com-v1.json

将CRD转换为JSON模式文件后，您可以使用kubeconform根据这些文件验证CR：

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

[!NOTE] Datree的CRD Extractor是一个实用工具，可替代此手动流程。

OpenShift schema Support

您可以使用自定义模式位置验证OpenShift清单。使用-kubernetes-version设置要验证的OpenShift版本（v3.10.0-4.1.0）。

kubeconform -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
Summary: 1 resource found in 1 file - Valid: 1, Invalid: 0, Errors: 0 Skipped: 0

Integrating Kubeconform in the CI

Kubeconform将Docker镜像发布到Github的新容器 registry（ghcr.io）。使用Github Token登录后，这些镜像可直接在Github Action中使用。

Github Workflow

示例：

name: kubeconform
on: push
jobs:
kubeconform:
runs-on: ubuntu-latest
steps:
- name: login to Github Packages
run: echo "${{ github.token }}" | docker login https://ghcr.io -u ${GITHUB_ACTOR} --password-stdin
- uses: actions/checkout@v2
- uses: docker://ghcr.io/yannh/kubeconform:latest
with:
entrypoint: '/kubeconform'
args: "-summary -output json kubeconfigs/"

[!NOTE] 关于定价：Kubeconform依赖于当前处于Beta版的Github Container Registry。在此期间，带宽是免费的。此阶段之后，可能会产生带宽费用。由于Github Actions中来自Github Packages的带宽是免费的，我预计未来Github Container Registry在Github Actions中也可免费使用。如果情况并非如此，我可能会将Docker镜像发布到其他平台。

Gitlab-CI

Kubeconform Docker镜像可用于Gitlab-CI。以下是Gitlab-CI作业示例：

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

有关更多详细信息，请参见issue 106。

Helm charts

有一个第三方仓库允许以Helm插件和pre-commit钩子的形式使用kubeconform测试Helm图表。

Using kubeconform as a Go Module

[!WARNING] 注意：这是一项正在进行的工作，接口尚未稳定。欢迎提供反馈。

Kubeconform包含一个可用作库的包。用法示例可在examples/main.go中找到。

Kubeconform的补充文档位于pkg.go.dev

致谢

• 感谢 @garethr 贡献的 Kubeval 和 kubernetes-json-schema 项目 ❤️