Декларативна перевірка API

СТАН ФУНКЦІОНАЛУ: Kubernetes v1.33 [beta]

Kubernetes 1.33 включає необовʼязкову декларативну перевірку для API. Якщо її увімкнено, сервер API Kubernetes може використовувати цей механізм, а не застарілий підхід, який покладається на рукописний код Go (файли validation.go), щоб гарантувати, що запити до API є дійсними. Розробники Kubernetes та люди, які [розширюють Kubernetes API] (/docs/concepts/extend-kubernetes/api-extension/apiserver-aggregation/), можуть визначати правила валідації безпосередньо поряд з визначеннями типів API (файли types.go). Автори коду визначають спеціальні теґи коментарів (наприклад, +k8s:minimum=0). Генератор коду (validation-gen) потім використовує ці теґи для створення оптимізованого коду Go для перевірки API.

Хоча ця функція в першу чергу впливає на учасників Kubernetes і потенційних розробників [серверів API розширень] (/docs/concepts/extend-kubernetes/api-extension/apiserver-aggregation/), адміністратори кластерів повинні розуміти її поведінку, особливо на етапах її розгортання.

Декларативна перевірка розгортається поступово. У Kubernetes 1.33, API, які використовують декларативну перевірку, включають:

  • DeclarativeValidation: (Beta, стандартно: true) Якщо увімкнено, сервер API виконує як нову декларативну перевірку, так і стару ручну перевірку для перенесених типів/полів. Результати порівнюються внутрішньо.
  • DeclarativeValidationTakeover: (Beta, стандартно: false) Ця можливість визначає, який результат перевірки є авторитетним (тобто, повертається користувачеві і використовується для прийняття рішень про допуск).

Типова поведінка (Kubernetes 1.33):

  • Зі значеннями DeclarativeValidation=true та DeclarativeValidationTakeover=false ( стандартні значення для функціональних можливостей) працюють обидві системи валідації.
  • Використовуються результати рукописної валідації. Декларативна валідація запускається у режимі розбіжностей для порівняння.
  • Невідповідності між двома системами валідації реєструються сервером API і збільшують метрику declarative_validation_mismatch_total. Це допомагає розробникам виявляти та виправляти розбіжності на етапі бета-версії.
  • Оновлення кластерів має бути безпечним щодо цієї функції, оскільки логіка авторитетної перевірки стандартно не змінюється.

Адміністратори можуть явно ввімкнути DeclarativeValidationTakeover=true, щоб зробити декларативну перевірку авторитетною для перенесених полів, зазвичай після перевірки стабільності в їхньому середовищі (наприклад, шляхом моніторингу метрики невідповідностей).

Вимкнення декларативної перевірки

Як адміністратор кластера, ви можете вимкнути декларативну перевірку, поки вона ще є бета-версією, за певних обставин:

  • Неочікувана поведінка перевірки: Якщо увімкнення DeclarativeValidationTakeover призводить до неочікуваних помилок перевірки або дозволяє обʼєкти, які раніше були недійсними.
  • Погіршення продуктивності: Якщо моніторинг вказує на значне збільшення затримок (наприклад, у apiserver_request_duration_seconds), повʼязане з увімкненням цієї функції.
  • Високий рівень невідповідностей: Якщо метрика declarative_validation_mismatch_total показує часті невідповідності, що свідчить про потенційні помилки в декларативних правилах, які впливають на робочі навантаження кластера, навіть якщо DeclarativeValidationTakeover має значення false.

Щоб повернутися до використання лише рукописної перевірки (як це було до Kubernetes v1.33), вимкніть DeclarativeValidation feature gate, наприклад, за допомогою аргументів командного рядка: (--feature-gates=DeclarativeValidation=false). Це також неявно вимкне ефект DeclarativeValidationTakeover.

Міркування щодо пониження версії та відкату

Вимкнення цієї функції діє як механізм безпеки. Однак, памʼятайте про потенційний крайній випадок (який вважається малоймовірним завдяки ретельному тестуванню): Якщо помилка у декларативній перевірці (коли DeclarativeValidationTakeover=true) неправильно дозволила зберегти недійсний обʼєкт, вимкнення функціональних можливостей може призвести до блокування подальших оновлень цього конкретного обʼєкта за допомогою тепер авторизованої (і правильної) ручної перевірки. Розвʼязання цієї проблеми може вимагати ручного виправлення збереженого обʼєкта, можливо, за допомогою прямої модифікації etcd у рідкісних випадках.

Докладні відомості про керування функціональними можливостями наведено у статті Функціональні можливості.

Змінено April 24, 2025 at 5:18 PM PST: sync upstream (03e4e921ba)