Автоматическая публикация схем CRD и валидация манифестов Kubernetes в IDEЗаметка · дайджест за 8 ноября
Кинематографичный натюрморт рабочего места инженера с экраном ноутбука, где опубликованные JSON-схемы валидируют манифест Kubernetes.
Заметка3 раздела≈ 3 мин

Автоматическая публикация схем CRD и валидация манифестов Kubernetes в IDE

Утро начинается с остывающей кружки кофе у ноутбука и открытого VS Code: нужно выписать TLS-сертификат example-cert через cert-manager для тестового стенда. Ты создаешь манифест Certificate версии v1, начинаешь заполнять блок spec — а редактор либо молчит, не подсказывая поля, либо подчеркивает половину файла красной волнистой линией. Опечатку в ключе замечаешь, только когда кластер отбивает kubectl apply.

Как быстро настроить в редакторе валидацию и автодополнение для кастомных ресурсов Kubernetes без ручного поиска схем? Задачу решает открытая утилита crd-schema-publisher от разработчика sholdee, которую разобрали в DevOps&SRE Library: она извлекает схемы прямо из кластера или YAML-файлов и разворачивает сайт документации с готовыми ссылками для IDE.

Почему каталоги схем CRD устаревают и страдает автодополнение

Посмотрим, почему редактор слепнет на ресурсе Certificate. Базовый кластер знает только встроенные объекты вроде Pod или Service. При установке оператора мы загружаем определение кастомного ресурса — CRD (Custom Resource Definition). Это как зарегистрировать новый бланк заявления в паспортном столе: API-сервер кластера сразу запоминает обязательные поля и типы.

Но локальный редактор в этот «паспортный стол» не заглядывает, а публичные каталоги схем подводят в трех местах: они отстают от версий операторов в кластере, не знают о закрытых корпоративных CRD компании и привязывают проверку к внешней сети.

Как crd-schema-publisher извлекает схемы OpenAPI v2 и публикует документацию

Раз точные описания ресурсов уже лежат в кластере, надежнее забирать их оттуда. Я изучил устройство crd-schema-publisher: это статический бинарник на Go (лицензия MIT) в минимальном distroless-контейнере без прав root (nonroot). Он работает в три шага:

  1. Извлечение. Утилита читает CRD через Kubernetes API либо парсит YAML-файлы командой convert. С флагом --include-builtins она забирает и схемы встроенных ресурсов из /openapi/v2.
  2. Конвертация. Описания OpenAPI v2 переводятся в JSON Schema по путям <apigroup>/<kind>_<version>.json (cert-manager.io/certificate_v1.json, core/pod_v1.json), а в корне создается индекс all.json, сопоставляющий манифесты по apiVersion и kind.
  3. Публикация. Генератор собирает статический сайт с поиском по группам API и версиям для раздачи локально, через Git, S3 или Cloudflare Pages.

Подключение схем в VS Code через yaml-language-server и работа в Helm

За проверку YAML в VS Code отвечает сервер yaml-language-server. Чтобы редактор проверил структуру сертификата example-cert, укажем в первой строке манифеста ссылку на схему:

# yaml-language-server: $schema=https://kube-schemas.example.com/cert-manager.io/certificate_v1.json
apiVersion: cert-manager.io/v1
kind: Certificate
metadata:
  name: example-cert
spec:
  secretName: example-tls
  issuerRef:
    name: letsencrypt-prod
    kind: ClusterIssuer

После добавления этой строки красные подчеркивания исчезают, при наведении на secretName и issuerRef всплывает справка из кластера, а автодополнение подсказывает вложенные ключи до сохранения файла. А если привязать корневой индекс all.json в настройке yaml.schemas внутри VS Code, валидация автоматически накроет весь репозиторий.

Для автообновления схем утилиту ставят в кластер через Helm-чарт oci://ghcr.io/sholdee/charts/crd-schema-publisher. В режиме контроллера механизм Informer следит за CRD, поддерживает выбор лидера, пробы и метрики, а фильтр сглаживания (debounce) гасит шторм холостых пересборок при массовой выкатке чартов. Нужны лишь права ClusterRole на чтение customresourcedefinitions.apiextensions.k8s.io и /openapi/v2, плюс доступ к домену схем. О других легких инструментах для кластера читай в обзорах дашборда Klarity и плагина Headlamp KubeBuddy.

Проверить инструмент прямо сейчас можно без серверов — выгрузи схемы из текущего контекста kubeconfig:

crd-schema-publisher extract -o ./schemas --include-builtins

Через пару секунд в папке ./schemas появятся JSON-схемы всех операторов твоего кластера и индекс all.json. Добавь путь к нему в yaml.schemas своего VS Code — и редактор сразу начнет страховать манифесты от опечаток.

Хочу подробный разборГолоса помогают выбрать, что разобрать подробно. За этот материал 0 голосов.
Источники · 2