`kubeconform`

Проверка манифестов Kubernetes по JSON-схемам без кластера — strict, сводка, CRD, офлайн-схемы

kubeconform проверяет YAML-манифесты Kubernetes по JSON-схемам API: правильные ли поля, типы и вложенность. Кластер не нужен — это проверка «как бы отреагировал API-сервер на kubectl apply», которую удобно запускать в CI до деплоя. Логику (совпадают ли метки селектора и пода, есть ли образ) он не проверяет.

Синтаксис

kubeconform [опции] файл|каталог… 
kubeconform [опции] -          # манифесты из stdin

В одном файле может быть несколько документов через ---. Каталог обходится рекурсивно, берутся .yaml, .yml и .json.

Опции

Что считать ошибкой

Опция	Что делает
`-strict`	запретить поля, которых нет в схеме, и повторяющиеся ключи в YAML
`-ignore-missing-schemas`	ресурсы без схемы (CRD и др.) пропускать (`Skipped`), а не считать ошибкой
`-skip Kind1,Kind2`	не проверять эти виды ресурсов (можно `группа/версия/Kind`)
`-reject Kind1,Kind2`	запретить эти виды: их наличие — ошибка
`-kubernetes-version 1.29.0`	по какой версии API проверять (подставляется в путь к схемам)
`-schema-location путь`	где искать схемы; можно повторять, с шаблоном `{{ .ResourceKind }}` и др.; `default` — стандартный репозиторий на GitHub
`-ignore-filename-pattern regex`	пропускать файлы по шаблону пути; можно повторять

Вывод

Опция	Что делает
`-summary`	в конце строка `Summary: N resources found in M files - Valid, Invalid, Errors, Skipped`
`-verbose`	печатать и валидные ресурсы (`… is valid`)
`-output text\|json\|tap\|junit\|pretty`	формат; `json` показывает все ошибки ресурса, `text` — только первую
`-exit-on-error`	остановиться на первой ошибке
`-n N`	число потоков (по умолчанию 4)
`-debug`	какие файлы схем используются
`-v`	версия

Результаты и коды выхода

Статус	Что значит
`valid`	ресурс соответствует схеме
`invalid`	схема найдена, ресурс ей не соответствует: лишнее поле, не тот тип, нет обязательного
`error` (`failed validation`)	проверить не удалось: YAML не разбирается, нет `kind`, нет схемы, запрещённый вид
`skipped`	пропущен через `-skip` или `-ignore-missing-schemas`

Код выхода 0 — нет ни invalid, ни error; 1 — есть хотя бы один.

Без -summary и -verbose при успехе kubeconform ничего не печатает — смотри код выхода.

Как настроен в песочнице IzzyLab

У песочницы нет выхода в интернет, а обычный kubeconform скачивает схемы с GitHub. Поэтому kubeconform здесь — обёртка, которая добавляет -schema-location '/opt/k8s-schemas/{{ .ResourceKind }}{{ .KindSuffix }}.json'. В /opt/k8s-schemas лежат схемы Kubernetes 1.32 для частых видов: Deployment, Service, ConfigMap, Secret, Pod, Job, CronJob, Ingress, StatefulSet, DaemonSet, HPA, NetworkPolicy, PVC, RBAC и других (ls /opt/k8s-schemas).

Особенности:

схемы взяты в strict-варианте — лишние поля запрещены даже без -strict; -strict добавляет проверку повторяющихся ключей;
-kubernetes-version ни на что не влияет — путь к схемам фиксированный;
для вида, которого нет в каталоге (CRD, старые batch/v1beta1), будет could not find schema — добавь -ignore-missing-schemas или -skip;
твой собственный -schema-location тоже учитывается — после встроенного.

Примеры

cat > app.yaml <<'EOF'
apiVersion: apps/v1
kind: Deployment
metadata:
  name: web
spec:
  replicas: 2
  selector:
    matchLabels: {app: web}
  template:
    metadata:
      labels: {app: web}
    spec:
      containers:
        - name: web
          image: nginx:1.27
---
apiVersion: v1
kind: Service
metadata:
  name: web
spec:
  selector: {app: web}
  ports:
    - port: 80
EOF

# строгая проверка со сводкой — типичный шаг CI
kubeconform -strict -summary app.yaml

# весь каталог с манифестами, каждый ресурс — в выводе
kubeconform -strict -summary -verbose k8s/

# сгенерированные манифесты — прямо из конвейера
kubectl create deployment demo --image=nginx --dry-run=client -o yaml | kubeconform -strict -summary -

# в манифестах есть CRD, для которых схем нет
kubeconform -strict -ignore-missing-schemas -summary k8s/

# не проверять конкретные виды, запретить другие
kubeconform -skip Certificate -reject Secret -summary k8s/

# все ошибки ресурса (text показывает только первую)
kubeconform -strict -output json app.yaml

# пропустить шаблоны Helm и kustomize-патчи
kubeconform -summary -ignore-filename-pattern 'templates/' -ignore-filename-pattern 'patch' k8s/

# в CI: упасть, если что-то не так
kubeconform -strict -summary k8s/ || exit 1

Как читать ошибки

typo.yaml - Service web is invalid: problem validating schema. Check JSON formatting:
  jsonschema: '/spec/ports/0/port' does not validate with
  file:///opt/k8s-schemas/service-v1.json#/properties/spec/.../port/type: expected integer, but got string

typo.yaml - Service web — файл, вид и имя ресурса;
'/spec/ports/0/port' — путь к полю: spec.ports[0].port;
в конце — суть: expected integer, but got string, additionalProperties 'selectr' not allowed (опечатка или лишнее поле), missing properties: 'containers' (нет обязательного поля).

Фраза Check JSON formatting — шаблонная, к JSON-форматированию отношения обычно не имеет.

Подводные камни

Числа и строки. port: "80" — ошибка (нужно число), а значения в data у ConfigMap — наоборот, только строки: replicas: 3 внутри data надо писать "3".
YAML 1.1 превращает yes, no, on, off, y, n в булевы значения. name: y станет true, ключ n: — false, и ошибка будет про странное поле. Бери такие значения в кавычки.
Text-вывод показывает только первую ошибку ресурса. Исправишь одну — появится следующая. Чтобы увидеть все сразу, бери -output json.
Повторяющийся ключ без -strict проходит молча: YAML берёт последнее значение. С -strict — key "…" already set in map.
Пустой файл — это 0 resources, код 0. Если перепутать путь к сгенерированному файлу или конвейер ничего не выдаст, проверка «пройдёт». Смотри -summary: сколько ресурсов найдено.
Отсутствующий файл — ошибка (lstat …: no such file or directory, код 1), а вот пустой каталог — нет.
Валидность ≠ работоспособность. Селектор, не совпадающий с метками пода, несуществующий образ или ConfigMap — всё это пройдёт проверку схемы.
Без офлайн-схем стандартный kubeconform ходит на GitHub. Без интернета он падает с failed downloading schema. Схемы можно скачать заранее и указать через -schema-location.

См. также

kubectl · yq · yamlschema · actionlint · gitlab-ci