Ця сторінка надає рекомендації та міркування щодо проєктування вебхуків допуску в Kubernetes. Ця інформація призначена для операторів кластерів, які запускають сервери вебхуків допуску або сторонні застосунки, що змінюють або перевіряють ваші API-запити.
Перед читанням цієї сторінки переконайтеся, що ви знайомі з наступними поняттями:
Контроль допуску відбувається, коли будь-який запит на створення, оновлення або видалення надсилається до API Kubernetes. Контролери допуску перехоплюють запити, які відповідають певним критеріям, які ви визначаєте. Ці запити потім надсилаються до модифікуючих вебхуків допуску або валідаційних вебхуків допуску. Ці вебхуки часто створюються для забезпечення наявності певних полів у специфікаціях обʼєктів або їх відповідності дозволеним значенням.
Вебхуки є потужним механізмом для розширення API Kubernetes. Погано спроєктовані вебхуки часто призводять до збоїв у роботі навантажень через те, наскільки великий контроль вебхуки мають над обʼєктами в кластері. Як і інші механізми розширення API, вебхуки складно тестувати в масштабі на сумісність з усіма вашими навантаженнями, іншими вебхуками, надбудовами та втулками.
Крім того, з кожним випуском Kubernetes додає або змінює API з новими функціями, підвищенням статусу функцій до бета або стабільного стану та застаріваннями. Навіть стабільні API Kubernetes можуть змінюватися. Наприклад, API Pod змінився у версії v1.29 для додавання функціоналу контейнерів Sidecar. Хоча рідко трапляється, що обʼєкт Kubernetes стає несправним через новий API Kubernetes, вебхуки, які працювали як очікувалося з попередніми версіями API, можуть не змогти узгодити більш нові зміни в цьому API. Це може призвести до неочікуваної поведінки після оновлення кластерів до новіших версій.
Ця сторінка описує загальні сценарії збоїв вебхуків і як їх уникнути шляхом обережного та вдумливого проєктування та реалізації ваших вебхуків.
Навіть якщо ви не запускаєте власні вебхуки допуску, деякі сторонні застосунки, які ви запускаєте у своїх кластерах, можуть використовувати модифікуючі або валідаційні вебхуки допуску.
Щоб перевірити, чи є у вашому кластері модифікуючий вебхук допуску, виконайте наступну команду:
kubectl get mutatingwebhookconfigurations
Вивід покаже будь-який контролер модифікуючого вебхуку допуску в кластері.
Щоб перевірити, чи є у вашому кластері валідаційний вебхук допуску, виконайте наступну команду:
kubectl get validatingwebhookconfigurations
Вивід покаже будь-який контролер валідаційного вебхуку допуску в кластері.
Kubernetes включає кілька варіантів контролю допуску та забезпечення політики. Знання, коли використовувати конкретний варіант, може допомогти вам покращити затримку та продуктивність, зменшити витрати на керування та уникнути проблем під час оновлення версій. Наступна таблиця описує механізми, які дозволяють змінювати або перевіряти ресурси під час допуску:
| Механізм | Опис | Випадки використання |
|---|---|---|
| Модифікуючий вебхук допуску | Перехоплює API-запити перед допуском і змінює їх за потреби за допомогою власної логіки користувача. |
|
| Змінювані політики допуску | Перехоплюють API-запити перед допуском і змінюють їх за потреби за допомогою виразів Common Expression Language (CEL). |
|
| Валідаційний вебхук допуску | Перехоплює API-запити перед допуском і перевіряє їх на відповідність складним визначенням політик. |
|
| Правила перевірки допуску | Перехоплюють API-запити перед допуском і перевіряють їх на відповідність виразам CEL. |
|
Загалом, використовуйте вебхук контролю допуску, коли вам потрібен розширюваний спосіб задекларувати або налаштувати логіку. Використовуйте вбудований контроль допуску на основі CEL, коли вам потрібно задекларувати простішу логіку без накладних витрат на запуск сервера вебхуків. Проєкт Kubernetes рекомендує використовувати контроль допуску на основі CEL, коли це можливо.
Якщо ви використовуєте CustomResourceDefinitions, не використовуйте вебхуки допуску для перевірки значень у специфікаціях CustomResource або для встановлення стандартних значень для полів. Kubernetes дозволяє вам визначати правила перевірки та стандартні значення полів під час створення CustomResourceDefinitions.
Щоб дізнатися більше, дивіться наступні ресурси:
Цей розділ описує рекомендації щодо покращення продуктивності та зменшення затримки. У підсумку, вони такі:
Модифікуючі вебхуки допуску викликаються послідовно. Залежно від налаштування вебхука, деякі вебхуки можуть викликатися кілька разів. Кожен виклик модифікуючого вебхуку додає затримку до процесу допуску. Це відрізняється від валідаційних вебхуків, які викликаються паралельно.
Під час проєктування ваших модифікуючих вебхуків враховуйте ваші вимоги до затримки та толерантність. Чим більше модитфікуючих вебхуків у вашому кластері, тим більша ймовірність збільшення затримки.
Розгляньте наступні рекомендації для зменшення затримки:
Враховуйте будь-які інші компоненти, які працюють у вашому кластері, які можуть конфліктувати зі змінами, які робить ваш вебхук. Наприклад, якщо ваш вебхук додає мітку, яку інший контролер видаляє, ваш вебхук викликатиметься знову. Це призводить до зациклювання.
Щоб виявити ці цикли, спробуйте наступне:
Оновіть політику аудиту вашого кластера для запису подій аудиту. Використовуйте наступні параметри:
level: RequestResponseverbs: ["patch"]omitStages: RequestReceivedВстановіть правило аудиту для створення подій для конкретних ресурсів, які ваш вебхук змінює.
Перевірте ваші події аудиту на предмет повторного виклику вебхуків з однаковим патчем, застосованим до одного й того ж обʼєкта, або на предмет оновлення та скасування поля обʼєкта кілька разів.
Вебхуки допуску повинні оцінюватися якомога швидше (зазвичай за мілісекунди), оскільки вони додають затримку до API-запиту. Використовуйте невелике значення тайм-ауту для вебхуків.
Для деталей дивіться Тайм-аути.
Вебхуки допуску повинні використовувати якусь форму балансування навантаження для забезпечення високої доступності та продуктивності. Якщо вебхук працює всередині кластера, ви можете запустити кілька бекендів вебхука за Service типу ClusterIP.
Враховуйте вимоги до доступності вашого кластера під час проєктування вашого вебхуку. Наприклад, під час простою вузла або зональних збоїв, Kubernetes позначає Podʼи як NotReady, щоб дозволити балансувальникам навантаження перенаправляти трафік до доступних зон та вузлів. Ці оновлення Podʼів можуть викликати ваші модифікуючі вебхуки. Залежно від кількості задіяних Podʼів, сервер модифікуючого вебхука ризикує вийти за межі тайм-ауту або спричинити затримки в обробці Podʼа. В результаті, трафік не буде перенаправлений так швидко, як вам потрібно.
Враховуйте ситуації, подібні до наведеного прикладу, під час створення ваших вебхуків. Виключайте операції, які є результатом реакції Kubernetes на неминучі інциденти.
Цей розділ надає рекомендації щодо фільтрації запитів, які викликають конкретні вебхуки. У підсумку, вони такі:
Вебхуки допуску викликаються тільки тоді, коли API-запит збігається з відповідною конфігурацією вебхука. Обмежте область дії кожного вебхука, щоб зменшити непотрібні виклики до сервера вебхука. Враховуйте наступні обмеження області дії:
kube-system. Якщо ви запускаєте свої Podʼи у просторі імен kube-system, використовуйте objectSelector, щоб уникнути зміни критичного робочого навантаження.kube-node-lease. Зміна лізингу вузлів може призвести до невдалих оновлень вузлів. Застосовуйте контроль перевірки до обʼєктів Lease у цьому просторі імен тільки якщо ви впевнені, що контроль не завдасть вашому кластеру ризику.namespaceSelector.Контролери допуску підтримують кілька полів, які ви можете використовувати для перевірки збігів з запитами, які відповідають певним критеріям. Наприклад, ви можете використовувати namespaceSelector для фільтрації запитів, які спрямовані на конкретний простір імен.
Для більш тонкої фільтрації запитів використовуйте поле matchConditions у вашій конфігурації вебхука. Це поле дозволяє вам створювати кілька виразів CEL, які повинні оцінюватися як true, щоб запит викликав ваш вебхук допуску. Використання matchConditions може значно зменшити кількість викликів до вашого сервера вебхука.
Для деталей дивіться Відповідність запитам: matchConditions.
Стандартно, вебхуки допуску працюють на будь-яких версіях API, які впливають на вказаний ресурс. Поле matchPolicy у конфігурації вебхука контролює цю поведінку. Вкажіть значення Equivalent у полі matchPolicy або пропустіть поле, щоб дозволити вебхуку працювати на будь-якій версії API.
Для деталей дивіться Відповідність запитам: matchPolicy.
Цей розділ надає рекомендації щодо області дії змін та будь-яких особливих міркувань щодо полів обʼєктів. У підсумку, вони такі:
Сервери вебхуків допуску надсилають HTTP-відповіді, щоб вказати, що робити з конкретним API-запитом Kubernetes. Ця відповідь є обʼєктом AdmissionReview. Модифікуючий вебхук може додати конкретні поля для зміни перед дозволом допуску за допомогою поля patchType та поля patch у відповіді. Переконайтеся, що ви змінюєте тільки ті поля, які потребують змін.
Наприклад, розгляньте модифікуючий вебхук, який налаштований для забезпечення того, щоб Deployments web-server мали принаймні три репліки. Коли запит на створення обʼєкта Deployment відповідає вашій конфігурації вебхука, вебхук
повинен оновити тільки значення у полі spec.replicas.
Поля у специфікаціях обʼєктів Kubernetes можуть містити масиви. Деякі масиви містять пари ключ:значення (наприклад, поле envVar у специфікації контейнера), тоді як інші масиви не мають ключів (наприклад, поле readinessGates у специфікації Pod). Порядок значень у полі масиву може бути важливим в деяких ситуаціях. Наприклад, порядок аргументів у полі args специфікації контейнера може впливати на контейнер.
Враховуйте наступне під час зміни масивів:
add замість replace, щоб уникнути випадкового заміщення необхідного значення.Переконайтеся, що ваші вебхуки працюють тільки з вмістом AdmissionReview, який надсилається їм, і не роблять змін поза межами. Ці додаткові зміни, звані побічними ефектами, можуть спричинити конфлікти під час допуску, якщо вони не узгоджені належним чином. Поле .webhooks[].sideEffects повинно бути встановлено в None, якщо вебхук не має побічних ефектів.
Якщо побічні ефекти необхідні під час оцінки допуску, вони повинні бути придушені під час обробки обʼєкта AdmissionReview з dryRun, встановлене у true, і поле .webhooks[].sideEffects повинно бути встановлено на NoneOnDryRun.
Для деталей дивіться Побічні ефекти.
Вебхук, що працює всередині кластера, може спричинити взаємоблокування для свого власного розгортання, якщо він налаштований для перехоплення ресурсів, необхідних для запуску його власних Podʼів.
Наприклад, модифікуючий вебхук допуску налаштований для допуску запитів create Pod тільки якщо певна мітка встановлена у Pod (наприклад, env: prod). Сервер вебхука працює у Deployment, який не встановлює мітку env.
Коли вузол, який запускає Podʼи сервера вебхука, стає несправним, Deployment вебхука намагається перенаправити Podʼи на інший вузол. Однак, існуючий сервер вебхука відхиляє запити, оскільки мітка env не встановлена. В результаті, міграція не може відбутися.
Виключіть простір імен, де працює ваш вебхук, за допомогою namespaceSelector.
Цикли залежностей можуть виникати у таких сценаріях:
Щоб уникнути цих циклів залежностей, спробуйте наступне:
objectSelector.Модифікуючі вебхуки допуску підтримують поле конфігурації failurePolicy. Це поле вказує, чи повинен API-сервер допустити або відхилити запит у разі збою вебхука. Збої вебхука можуть статися через тайм-аути або помилки у логіці сервера.
Стандартно, вебхуки допуску встановлюють поле failurePolicy у Fail. API-сервер відхиляє запит, якщо вебхук зазнає збою. Однак, таке стандартне відхилення запитів може призвести до відхилення доцільних запитів під час простою вебхука.
Дозвольте вашим модифікуючим вебхукам "не приховувати збої", встановивши поле failurePolicy в Ignore. Використовуйте контролер перевірки для перевірки стану запитів, щоб забезпечити їх відповідність вашим політикам.
Цей підхід має наступні переваги:
Загалом, проєктуйте ваші вебхуки з урахуванням того, що API Kubernetes можуть змінитися в наступній версії. Не створюйте сервер, який приймає стабільність API як належне. Наприклад, випуск контейнерів sidecar у Kubernetes додав поле restartPolicy до API Pod.
Модифікуючі вебхуки, які відповідають на широкий спектр API-запитів, можуть ненавмисно викликати самі себе. Наприклад, розгляньте вебхук, який відповідає на всі запити в кластері. Якщо ви налаштуєте вебхук для створення обʼєктів Event для кожної зміни, він буде відповідати на власні запити на створення обʼєктів Event.
Щоб уникнути цього, розгляньте можливість встановлення унікальної мітки у будь-яких ресурсах, які створює ваш вебхук. Перевіряте наявність цієї мітки в умовах збігу вашого вебхуку.
Деякі обʼєкти Kubernetes в API-сервері не можуть змінюватися. Наприклад, коли ви розгортаєте static Pod, kubelet на вузлі створює mirror Pod в API-сервері для відстеження статичного Podʼа. Однак, зміни у mirror Pod не поширюються на статичний Pod.
Не намагайтеся змінювати ці обʼєкти під час допуску. Усі mirror Podʼи мають анотацію kubernetes.io/config.mirror. Щоб виключити mirror Podʼи, зменшуючи ризик безпеки від ігнорування анотації, дозволяйте статичним Podʼам працювати тільки в конкретних просторах імен.
Цей розділ надає рекомендації щодо порядку виклику вебхука та проєктування ідемпотентних вебхуків. У підсумку, вони такі:
Модифікуючі вебхуки допуску не працюють у стабільному порядку. Різні фактори можуть змінити, коли конкретний вебхук викликається. Не покладайтеся на те, що ваш вебхук працює у конкретний момент у процесі допуску. Інші вебхуки все ще можуть змінити ваш змінений обʼєкт.
Наступні рекомендації можуть допомогти мінімізувати ризик непередбачуваних змін:
Кожен модифікуючий вебхук допуску повинен бути ідемпотентним. Вебхук повинен бути здатним працювати на обʼєкті, який він вже змінив, без внесення додаткових змін, крім початкової зміни.
Крім того, усі модифікуючі вебхуки у вашому кластері повинні, як колекція, бути ідемпотентними. Після завершення фази зміни контролю допуску, кожен окремий модифікуючий вебхук повинен бути здатним працювати на обʼєкті без внесення додаткових змін до обʼєкта.
Залежно від вашого середовища, забезпечення ідемпотентності в масштабі може бути складним. Наступні рекомендації можуть допомогти:
Наступні приклади показують ідемпотентну логіку змін:
Для запиту create Pod встановіть поле
.spec.securityContext.runAsNonRoot Pod у true.
Для запиту create Pod, якщо поле .spec.containers[].resources.limits контейнера не встановлено, встановіть стандартні значення ресурсних обмежень.
Для запиту create Pod, додайте контейнер sidecar з імʼям foo-sidecar, якщо контейнер з імʼям foo-sidecar ще не існує.
У цих випадках вебхук може бути безпечно повторно викликаний або допустити обʼєкт, який вже має встановлені поля.
Наступні приклади показують неідемпотентну логіку змін:
Для запиту create Pod додайте контейнер sidecar з імʼям foo-sidecar, до якого додається поточний відбиток часу (наприклад, foo-sidecar-19700101-000000).
Повторний виклик вебхука може призвести до того, що той самий sidecar буде доданий кілька разів до Podʼа, кожного разу з іншим імʼям контейнера. Аналогічно, вебхук може додати дубльовані контейнери, якщо sidecar вже існує у podʼі користувача.
Для запиту create/update Pod відхиліть його, якщо Pod має встановлену мітку env, інакше додайте мітку env: prod до Pod.
Повторний виклик вебхука призведе до того, що вебхук не зможе обробити свій власний вивід.
Для запиту create Pod додайте контейнер sidecar з імʼям foo-sidecar без перевірки, чи існує контейнер foo-sidecar.
Повторний виклик webhook призведе до дублювання контейнерів у Pod, що робить запит недійсним і відхиленим API-сервером.
Цей розділ надає рекомендації щодо тестування ваших модифікуючих вебхуків та перевірки змінених обʼєктів. У підсумку, вони такі:
Ретельне тестування повинно бути основною частиною вашого циклу випуску нових або оновлених вебхуків. Якщо можливо, тестуйте будь-які зміни до ваших кластерних вебхуків у тестовому середовищі, яке тісно нагадує ваші промислові кластери. Принаймні, розгляньте можливість використання інструменту, такого як minikube або kind, щоб створити невеликий тестовий кластер для змін вебхука.
Ваші модифікуючі вебхуки не повинні порушувати жодні перевірки, які застосовуються до обʼєкта перед допуском. Наприклад, розгляньте модифікуючий вебхук, який встановлює стандартне значення для запиту CPU Podʼа. Якщо обмеження CPU цього Podʼа встановлено на нижче значення, ніж змінений запит, Pod не пройде допуск.
Тестуйте кожен модифікуючий вебхук на перевірки, які працюють у вашому кластері.
Перед оновленням ваших промислових кластерів до нової мінорної версії, тестуйте ваші вебхуки та навантаження у тестовому середовищі. Порівняйте результати, щоб переконатися, що ваші вебхуки продовжують функціонувати як очікувалося після оновлення.
Крім того, використовуйте наступні ресурси, щоб бути в курсі змін API:
Модифікуючі вебхуки працюють до завершення перед тим, як будь-які валідаційні вебхуки починають працювати. Немає стабільного порядку, в якому зміни застосовуються до обʼєктів. В результаті, ваші зміни можуть бути перезаписані модифікуючим вебхуком, який працює пізніше.
Додайте контролер перевірки, такий як ValidatingAdmissionWebhook або ValidatingAdmissionPolicy, до вашого кластера, щоб переконатися, що ваші зміни залишаються. Наприклад, розгляньте модифікуючтй вебхук, який вставляє поле restartPolicy: Always до конкретних init-контейнерів, щоб зробити їх працюючими як sidecar-контейнери. Ви можете запустити валідаційний вебхук, щоб переконатися, що ці init-контейнери зберегли конфігурацію restartPolicy: Always після завершення всіх змін.
Для деталей дивіться наступні ресурси:
Цей розділ надає рекомендації щодо розгортання ваших модифікуючих вебхуків допуску. У підсумку, вони такі:
Коли ви готові розгорнути ваш модифікуючий вебхук у кластері, використовуйте наступний порядок дій:
failurePolicy у маніфесті MutatingWebhookConfiguration в Ignore. Це дозволяє уникнути збоїв, спричинених неправильно налаштованими вебхуками.namespaceSelector у маніфесті MutatingWebhookConfiguration на тестовий простір імен.Моніторте вебхук у тестовому просторі імен, щоб перевірити наявність будь-яких проблем, потім розгорніть вебхук в інших просторах імен. Якщо вебхук перехоплює API-запит, який він не повинен був перехоплювати, призупиніть розгортання та налаштуйте область дії конфігурації вебхука.
Модифікуючі вебхуки є потужними контролерами Kubernetes. Використовуйте RBAC або інший механізм авторизації для обмеження доступу до ваших конфігурацій вебхуків та серверів. Для RBAC переконайтеся, що наступний доступ доступний тільки довіреним субʼєктам:
admissionregistration.k8s.io/v1Якщо сервер вашого модифікуючого вебхука працює у кластері, обмежте доступ до створення або зміни будь-яких ресурсів у цьому просторі імен.
Наступні проєкти є прикладами "якісних" реалізацій власних серверів вебхуків. Ви можете використовувати їх як відправну точку під час проєктування власних вебхуків. Не використовуйте ці приклади як є; використовуйте їх як відправну точку та проєктуйте ваші вебхуки для гарної роботи у вашому конкретному середовищі.
Елементи на цій сторінці відносяться до сторонніх продуктів чи проєктів, які надають функціонал, необхідний для Kubernetes. Автори проєкту Kubernetes не несуть відповідальності за ці проєкти. Ознайомтесь з настановами на вебсайті CNCF для отримання докладної інформації.
Ознайомтесь з посібником з контенту перед тим, як пропонувати додавання посилання на стороні компоненти.