ghcr.io/yannh/kubeconform:v0.8.0-alpine

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

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

• 高性能：通过多协程验证和下载清单，并将下载的文件缓存在内存中
• 可配置远程或本地模式位置列表，支持验证 Kubernetes 自定义资源（CRDs）和离线验证功能
• 默认使用 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 验证的限制
• 安装
• 使用方法
  • 使用示例
  • 代理支持
• 覆盖模式位置
  • 自定义资源定义（CRD）支持
  • OpenShift 模式支持
• 在 CI 中集成 Kubeconform
  • 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

您也可以从发布页面下载最新版本。

另一种安装方式是通过 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) 支持

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

# 在 CRDs-catalog 中查找所需的 schema
$ 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 schema 格式。

Kubeconform 使用 JSON schema 验证 Kubernetes 资源。对于自定义资源，需要先将 CustomResourceDefinition 转换为 JSON Schema。提供了一个 Go 工具用于将这些 CustomResourceDefinition 转换为 JSON schema。从 openapi2jsonschema-go/ 目录构建该工具，并按如下方式使用：

$ cd openapi2jsonschema-go && make local-build
$ ./bin/openapi2jsonschema 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}'
$ ./bin/openapi2jsonschema 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}'
$ ./bin/openapi2jsonschema 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 schema 文件后，您可以使用 kubeconform 根据这些文件验证 CR：

# 如果在默认位置未找到资源 Kind，也在 schemas/ 文件夹中查找匹配文件
$ kubeconform -schema-location default -schema-location 'schemas/{{ .ResourceKind }}{{ .KindSuffix }}.json' fixtures/custom-resource.yaml

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

OpenShift schema 支持

您可以使用自定义 schema 位置验证 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

在 CI 中集成 Kubeconform

Kubeconform 将 Docker 镜像发布到 Github 的新容器注册表（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/"

定价说明：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 图表

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

将 kubeconform 用作 Go 模块

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

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

Kubeconform 的更多文档请参见 pkg.go.dev

致谢

• @garethr 贡献了 Kubeval 和 kubernetes-json-schema 项目 ❤️