API Kubernetes — це програмний інтерфейс на основі ресурсів (RESTful), який надається через HTTP. Він підтримує отримання, створення, оновлення та видалення основних ресурсів за допомогою стандартних HTTP-дієслів (POST, PUT, PATCH, DELETE, GET).
Для деяких ресурсів API включає додаткові субресурси, що дозволяють детальніше налаштовувати авторизацію (наприклад, окремі представлення для деталей Pod та отримання логів), і може приймати та надавати ці ресурси в різних представленнях для зручності або ефективності.
Kubernetes підтримує ефективні сповіщення про зміни ресурсів за допомогою спостережень (watches):
в API Kubernetes watch — це дієслово, яке використовується для відстеження змін обʼєкта в Kubernetes у вигляді потоку. Використовується для ефективного виявлення змін.
Kubernetes також забезпечує узгоджені операції отримання списків, щоб клієнти API могли ефективно кешувати, відстежувати та синхронізувати стан ресурсів.Ви можете переглянути довідник API онлайн або прочитати далі, щоб дізнатися про API загалом.
Kubernetes зазвичай використовує загальноприйняту термінологію RESTful для опису концепцій API:
pods, namespaces, services)Більшість типів ресурсів API Kubernetes є обʼєктами — вони представляють конкретний екземпляр концепції у кластері, як-от Pod або простір імен. Невелика кількість типів ресурсів API є віртуальними, оскільки вони часто представляють операції над обʼєктами, а не самі обʼєкти, такі як перевірка дозволів (використання POST із JSON-кодованим тілом SubjectAccessReview для ресурсу subjectaccessreviews), або субресурс eviction у Pod (використовується для запуску виселення, ініційованого API).
Усі обʼєкти, які ви можете створити через API, мають унікальне імʼя (name), що дозволяє ідемпотентне створення та отримання, за винятком віртуальних типів ресурсів, які можуть не мати унікальних імен, якщо вони не можуть бути отримані або не залежать від ідемпотентності.
У межах Namespace (простору імен) унікальна ідентичність обʼєкта визначається кортежем з його групи API, ресурсу, простору імен та імені.
apps та example.com).v1 та v1beta1) однієї групи та ресурсу представляють ті самі базові дані. Створення обʼєкта з однаковим іменем в іншій версії тієї ж групи призводить до конфлікту імен, оскільки вони мають однакову ідентичність у сховищі.Деякі обʼєкти не належать до простору імен (наприклад: Nodes), тому їхні імена повинні бути унікальними в межах усього кластера.
Майже всі типи ресурсів обʼєктів підтримують стандартні HTTP-дієслова — GET, POST, PUT, PATCH та DELETE. Kubernetes також використовує власні дієслова, які часто пишуться малими літерами, щоб відрізняти їх від HTTP-дієслів.
Kubernetes використовує термін list для опису дії повернення колекції ресурсів, щоб відрізняти її від отримання одного ресурсу, яке зазвичай називається get. Якщо ви надішлете HTTP-запит GET із параметром запиту ?watch, Kubernetes називає це watch, а не get (див. Ефективне виявлення змін для деталей).
Запити PUT Kubernetes внутрішньо класифікує як create або update залежно від стану наявного обʼєкта. update відрізняється від patch; HTTP-дієслово для patch — PATCH.
Усі типи ресурсів або належать кластеру (/apis/GROUP/VERSION/*), або простору імен (/apis/GROUP/VERSION/namespaces/NAMESPACE/*). Тип ресурсу, що належить простору імен, буде видалений при видаленні простору імен, і доступ до цього типу ресурсу контролюється перевірками авторизації в межах простору імен.
Примітка: основні ресурси використовують /api замість /apis і пропускають сегмент шляху GROUP.
Приклади:
/api/v1/namespaces/api/v1/pods/api/v1/namespaces/my-namespace/pods/apis/apps/v1/deployments/apis/apps/v1/namespaces/my-namespace/deployments/apis/apps/v1/namespaces/my-namespace/deployments/my-deploymentВи також можете отримати доступ до колекцій ресурсів (наприклад, до переліку усіх Nodes). Для отримання колекцій та ресурсів використовуються такі шляхи:
Ресурси кластерного рівня:
GET /apis/GROUP/VERSION/RESOURCETYPE — повертає колекцію ресурсів вказаного типу ресурсуGET /apis/GROUP/VERSION/RESOURCETYPE/NAME — повертає ресурс з імʼям NAME вказаного типу ресурсуРесурси рівня простору імен:
GET /apis/GROUP/VERSION/RESOURCETYPE — повертає колекцію всіх
екземплярів вказаного типу ресурсу в усіх просторах іменGET /apis/GROUP/VERSION/namespaces/NAMESPACE/RESOURCETYPE — повертає
колекцію всіх екземплярів вказаного типу ресурсу в просторі імен NAMESPACEGET /apis/GROUP/VERSION/namespaces/NAMESPACE/RESOURCETYPE/NAME —
повертає екземпляр вказаного типу ресурсу з імʼям NAME в просторі імен NAMESPACEОскільки простір імен є типом ресурсу кластерного рівня, ви можете отримати перелік («колекцію») всіх просторів імен за допомогою GET /api/v1/namespaces та деталі про конкретний простір імен за допомогою GET /api/v1/namespaces/NAME.
GET /apis/GROUP/VERSION/RESOURCETYPE/NAME/SUBRESOURCEGET /apis/GROUP/VERSION/namespaces/NAMESPACE/RESOURCETYPE/NAME/SUBRESOURCEПідтримувані дієслова для кожного субресурсу будуть відрізнятися залежно від обʼєкта — див. довідник API для отримання додаткової інформації. Немає можливості отримати доступ до субресурсів через декілька ресурсів — зазвичай, якщо це стає необхідним, використовується новий віртуальний тип ресурсу.
Через HTTP Kubernetes підтримує кодування даних JSON, YAML, CBOR та Protobuf.
Типово Kubernetes повертає обʼєкти у серіалізації JSON, використовуючи медіатип application/json. Хоча JSON є типовим форматом, клієнти можуть запитувати відповідь у форматі YAML або використовувати ефективніше двійкове представлення Protobuf для кращої продуктивності у великих масштабах.
API Kubernetes реалізує стандартне узгодження типів вмісту HTTP: передача заголовка Accept у виклику GET вказує серверу спробувати повернути відповідь у бажаному для вас медіатипі. Якщо ви хочете надіслати обʼєкт у форматі Protobuf на сервер для запиту PUT або POST, вам необхідно відповідно встановити заголовок запиту Content-Type.
Якщо ви запитуєте доступний медіатип, API-сервер повертає відповідь з відповідним заголовком Content-Type; якщо жоден із запитаних медіатипів не підтримується, API-сервер повертає повідомлення про помилку 406 Not acceptable. Усі вбудовані типи ресурсів підтримують медіатип application/json.
Для кодування JSON та Protobuf Kubernetes реалізує власні кодувальники, які записують дані елемент за елементом. Ця функція не змінює вихідні дані, але дозволяє API-серверу уникати завантаження всієї відповіді LIST в памʼять. Слід уникати використання інших типів кодування (включно з форматованим представленням JSON) для великих колекцій ресурсів (>100MB), оскільки це може негативно вплинути на продуктивність.
API Kubernetes типово використовує JSON для кодування тіла HTTP-повідомлень.
Наприклад:
Отримати список усіх Podʼів у кластері без вказування бажаного формату
GET /api/v1/pods
200 OK
Content-Type: application/json
… JSON encoded collection of Pods (PodList object)
Створити Pod, надіславши JSON на сервер та запросивши відповідь у форматі JSON.
POST /api/v1/namespaces/test/pods
Content-Type: application/json
Accept: application/json
… JSON encoded Pod object
200 OK
Content-Type: application/json
{
"kind": "Pod",
"apiVersion": "v1",
…
}
Ви також можете запитувати в цьому кодуванні таблиці та лише метадані.
Kubernetes також підтримує медіатип application/yaml як для запитів, так і для відповідей. YAML можна використовувати для визначення маніфестів Kubernetes та взаємодії з API.
Наприклад:
Отримати список усіх Podʼів у кластері у форматі YAML
GET /api/v1/pods
Accept: application/yaml
200 OK
Content-Type: application/yaml
… YAML encoded collection of Pods (PodList object)
Створити Pod, надіславши дані у форматі YAML на сервер і запросивши відповідь у форматі YAML:
POST /api/v1/namespaces/test/pods
Content-Type: application/yaml
Accept: application/yaml
… YAML encoded Pod object
200 OK
Content-Type: application/yaml
apiVersion: v1
kind: Pod
metadata:
name: my-pod
…
Ви також можете запитувати в цьому кодуванні таблиці та лише метадані.
Kubernetes використовує обгортку-конверт для кодування відповідей у форматі Protobuf. Ця обгортка починається з 4-байтового магічного числа, щоб допомогти ідентифікувати вміст на диску або в etcd як Protobuf (на відміну від JSON). За 4-байтовим магічним числом слідує закодоване у форматі Protobuf повідомлення-обгортка, яке описує кодування та тип основного обʼєкта. Усередині повідомлення-обгортки Protobuf дані внутрішнього обʼєкта записуються за допомогою поля raw повідомлення Unknown (дивіться IDL для докладної інформації).
Наприклад:
Отримати список усіх Podʼів у кластері у форматі Protobuf.
GET /api/v1/pods
Accept: application/vnd.kubernetes.protobuf
200 OK
Content-Type: application/vnd.kubernetes.protobuf
… binary encoded collection of Pods (PodList object)
Створити Pod, надіславши дані, закодовані у форматі Protobuf, на сервер, але запросити відповідь у форматі JSON.
POST /api/v1/namespaces/test/pods
Content-Type: application/vnd.kubernetes.protobuf
Accept: application/json
… binary encoded Pod object
200 OK
Content-Type: application/json
{
"kind": "Pod",
"apiVersion": "v1",
...
}
Ви можете використовувати обидві техніки разом і застосовувати кодування Protobuf Kubernetes для взаємодії з будь-яким API, яке його підтримує, як для читання, так і для запису. Лише деякі типи ресурсів API є сумісними з Protobuf.
Формат обгортки:
Префікс — чотирибайтове магічне число:
Bytes 0-3: "k8s\x00" [0x6b, 0x38, 0x73, 0x00]
Закодоване повідомлення Protobuf з таким IDL:
message Unknown {
// typeMeta повинне містити рядкові значення для "kind" та "apiVersion", як вони встановлені в обʼєкті JSON
optional TypeMeta typeMeta = 1;
// raw містить повний серіалізований обʼєкт у форматі protobuf. Дивіться визначення protobuf у клієнтських бібліотеках для конкретного kind.
optional bytes raw = 2;
// contentEncoding — це кодування, яке використовується для даних raw. Якщо не вказано, кодування відсутнє.
optional string contentEncoding = 3;
// contentType — це метод серіалізації, який використовується для серіалізації 'raw'. Якщо не вказано, використовується application/vnd.kubernetes.protobuf, і зазвичай
// цей параметр пропускається.
optional string contentType = 4;
}
message TypeMeta {
// apiVersion — це група/версія для цього типу
optional string apiVersion = 1;
// kind — це назва схеми обʼєкта. Для цього обʼєкта має існувати визначення protobuf.
optional string kind = 2;
}
application/vnd.kubernetes.protobuf, що не відповідає очікуваному префіксу, повинні відхилити відповідь, оскільки майбутні версії можуть змінити формат серіалізації несумісним чином і зроблять це шляхом зміни префікса.Ви також можете запитувати в цьому кодуванні таблиці та лише метадані.
Не всі типи ресурсів API підтримують кодування Kubernetes Protobuf; зокрема, Protobuf недоступний для ресурсів, які визначені як CustomResourceDefinitions або надаються через рівень агрегації.
Як клієнт, якщо вам може знадобитися працювати з типами розширень, слід вказати кілька типів вмісту в заголовку запиту Accept для підтримки резервного переходу на JSON. Наприклад:
Accept: application/vnd.kubernetes.protobuf, application/json
To use this feature, you (or a cluster administrator) will need to enable the CBORServingAndStorage feature gate for all relevant components in your cluster.
See Enable Or Disable Feature Gates for more information.
З увімкненою функціональною можливістю CBORServingAndStorage тіла запитів і відповідей для всіх вбудованих типів ресурсів і всіх ресурсів, визначених за допомогою CustomResourceDefinition, можуть бути закодовані у двійковий формат даних CBOR. CBOR також підтримується на рівні агрегації, якщо його увімкнено в окремих агрегованих API-серверах.
Клієнти повинні вказувати медіатип IANA application/cbor в заголовку HTTP-запиту Content-Type, коли тіло запиту містить один CBOR-закодований елемент даних, і в заголовку HTTP-запиту Accept, коли вони готові прийняти CBOR-кодований елемент даних у відповіді. API-сервери використовуватимуть application/cbor в заголовку HTTP-відповіді Content-Type, коли тіло відповіді містить CBOR-кодований обʼєкт.
Якщо API-сервер кодує свою відповідь на запит watch за допомогою CBOR, тіло відповіді буде послідовністю CBOR (CBOR Sequence), а в заголовку HTTP-відповіді Content-Type буде використано медіатип IANA application/cbor-seq. Кожен елемент послідовності (якщо такі є) є окремою CBOR-кодованою подією спостереження.
На додаток до наявного медіатипу application/apply-patch+yaml для YAML-кодованих конфігурацій server-side apply, API-сервери, у яких увімкнено CBOR, прийматимуть медіатип application/apply-patch+cbor для CBOR-кодованих конфігурацій server-side apply. Для application/json-patch+json або application/merge-patch+json, або application/strategic-merge-patch+json немає підтримуваного еквівалента в CBOR.
Ви також можете запитувати в цьому кодуванні таблиці та лише метадані.
API Kubernetes дозволяє клієнтам зробити початковий запит на обʼєкт або колекцію, а потім відстежувати зміни з моменту цього початкового запиту: це watch. Клієнти можуть надіслати list або get, а потім зробити наступний запит watch.
Для реалізації цього відстеження змін кожен обʼєкт Kubernetes має поле resourceVersion, яке представляє версію цього ресурсу, що зберігається в базовому шарі постійного зберігання. При отриманні колекції ресурсів (як рівня простору імен, так і кластерного рівня) відповідь від API-сервера містить значення resourceVersion. Клієнт може використовувати це значення resourceVersion для ініціювання watch до API-сервера.
Коли ви надсилаєте запит watch, API-сервер відповідає потоком змін. Ці зміни перераховують результати операцій (таких як create, delete та update), що відбулися після resourceVersion, значення якого було вказане як параметр запиту watch. Загальний механізм watch дозволяє клієнту отримати поточний стан, а потім підписатися на подальші зміни, не пропускаючи жодної події.
Якщо watch клієнта відʼєднується, цей клієнт може розпочати новий watch з останнього повернутого resourceVersion; клієнт також може виконати новий запит get / list і почати знову. Див. Семантика версій ресурсів для отримання детальнішої інформації.
Наприклад:
Отримати список усіх Podʼів у вказаному просторі імен.
GET /api/v1/namespaces/test/pods
---
200 OK
Content-Type: application/json
{
"kind": "PodList",
"apiVersion": "v1",
"metadata": {"resourceVersion":"10245"},
"items": [...]
}
Починаючи з версії ресурсу 10245, отримувати сповіщення про будь-які операції API
(такі як create, delete, patch або update), що впливають на Podʼи у
просторі імен test. Кожне сповіщення про зміну — це документ JSON. Тіло HTTP-відповіді
(надається як application/json) складається із серії документів JSON.
GET /api/v1/namespaces/test/pods?watch=1&resourceVersion=10245
---
200 OK
Transfer-Encoding: chunked
Content-Type: application/json
{
"type": "ADDED",
"object": {"kind": "Pod", "apiVersion": "v1", "metadata": {"resourceVersion": "10596", ...}, ...}
}
{
"type": "MODIFIED",
"object": {"kind": "Pod", "apiVersion": "v1", "metadata": {"resourceVersion": "11020", ...}, ...}
}
...
Сервер Kubernetes зберігає історичний запис змін лише протягом обмеженого часу. Кластери, що використовують etcd 3, типово зберігають зміни за останні 5 хвилин. Коли запитувані операції watch не вдаються через недоступність історичної версії цього ресурсу, клієнти повинні обробляти цей випадок, розпізнаючи код статусу 410 Gone, очищаючи свій локальний кеш, виконуючи нову операцію get або list і починаючи watch з resourceVersion, яке було повернуто.
Для підписки на колекції клієнтські бібліотеки Kubernetes зазвичай пропонують певну форму стандартного інструменту для логіки «спочатку list, потім watch». (У клієнтській бібліотеці Go це називається Reflector і знаходиться в пакеті k8s.io/client-go/tools/cache.)
Щоб зменшити вплив короткого вікна історії, API Kubernetes надає подію спостереження під назвою BOOKMARK (закладка). Це особливий вид події, що позначає, що всі зміни до вказаної клієнтом resourceVersion вже були надіслані. Документ, що представляє подію BOOKMARK, має тип, який запитується запитом, але містить лише поле .metadata.resourceVersion. Наприклад:
GET /api/v1/namespaces/test/pods?watch=1&resourceVersion=10245&allowWatchBookmarks=true
---
200 OK
Transfer-Encoding: chunked
Content-Type: application/json
{
"type": "ADDED",
"object": {"kind": "Pod", "apiVersion": "v1", "metadata": {"resourceVersion": "10596", ...}, ...}
}
...
{
"type": "BOOKMARK",
"object": {"kind": "Pod", "apiVersion": "v1", "metadata": {"resourceVersion": "12746"} }
}
Як клієнт, ви можете запитувати події BOOKMARK, встановлюючи параметр запиту allowWatchBookmarks=true у запиті watch, але не слід припускати, що закладки повертатимуться з певним інтервалом, і клієнти не можуть очікувати, що API-сервер надішле будь-яку подію BOOKMARK, навіть якщо її було запитано.
У великих кластерах отримання колекції деяких типів ресурсів може призвести до значного збільшення використання ресурсів (переважно RAM) панелі управління. Щоб зменшити вплив і спростити використання шаблону list + watch, у Kubernetes v1.32 переведено в бета-версію функцію, яка дозволяє запитувати початковий стан (який раніше запитувався за допомогою запиту list) як частину запиту watch.
На боці клієнта початковий стан можна запросити, вказавши sendInitialEvents=true як параметр рядка запиту в запиті watch. Якщо його встановлено, API-сервер починає потік спостереження із синтетичних початкових подій (типу ADDED) для побудови всього стану всіх наявних обʼєктів, після чого йде подія BOOKMARK (якщо її запитано через параметр allowWatchBookmarks=true). Подія закладки містить версію ресурсу, до якої виконано синхронізацію. Після надсилання події закладки API-сервер продовжує роботу як для будь-якого іншого запиту watch.
Коли ви встановлюєте sendInitialEvents=true у рядку запиту, Kubernetes також вимагає, щоб ви встановили для resourceVersionMatch значення NotOlderThan. Якщо ви вказали resourceVersion у рядку запиту без значення або не вказали його взагалі, це інтерпретується як запит на узгоджене читання (consistent read); подія закладки надсилається, коли стан синхронізовано щонайменше до моменту узгодженого читання з часу, коли запит почав оброблятися. Якщо ви вказуєте resourceVersion (у рядку запиту), подія закладки надсилається, коли стан синхронізовано щонайменше до вказаної версії ресурсу.
Приклад: ви хочете спостерігати за колекцією Podʼів. Для цієї колекції поточна версія ресурсу становить 10245, і є два Podʼи: foo та bar. Надсилання наступного запиту (який явно запитує узгоджене читання, встановлюючи порожню версію ресурсу за допомогою resourceVersion=) може призвести до такої послідовності подій:
GET /api/v1/namespaces/test/pods?watch=1&sendInitialEvents=true&allowWatchBookmarks=true&resourceVersion=&resourceVersionMatch=NotOlderThan
---
200 OK
Transfer-Encoding: chunked
Content-Type: application/json
{
"type": "ADDED",
"object": {"kind": "Pod", "apiVersion": "v1", "metadata": {"resourceVersion": "8467", "name": "foo"}, ...}
}
{
"type": "ADDED",
"object": {"kind": "Pod", "apiVersion": "v1", "metadata": {"resourceVersion": "5726", "name": "bar"}, ...}
}
{
"type": "BOOKMARK",
"object": {"kind": "Pod", "apiVersion": "v1", "metadata": {"resourceVersion": "10245"} }
}
...
<followed by regular watch stream starting from resourceVersion="10245">
To use this feature, you (or a cluster administrator) will need to enable the ShardedListAndWatch feature gate for all relevant components in your cluster.
See Enable Or Disable Feature Gates for more information.
У великих кластерах контролери, які спостерігають за типами ресурсів з високою кардинальністю (наприклад, Pod або Endpoints), можуть споживати значну частину пропускної здатності мережі та CPU, отримуючи та десеріалізуючи повний потік подій, навіть якщо їм потрібна лише підмножина обʼєктів. Фрагментовані list і watch дозволяють горизонтально масштабованим контролерам розподіляти навантаження так, щоб кожна репліка отримувала лише ті події, за які вона відповідає.
Kubernetes 1.37 впроваджує альфа-функцію, яка дозволяє клієнтам запитувати з API-сервера відфільтрований фрагмент обʼєктів, використовуючи розбиття на основі хешування полів метаданих. Щоб використовувати цю функцію, увімкніть на API-сервері функціональну можливість ShardedListAndWatch. Коли її увімкнено, API-сервер фільтрує як відповіді на list, так і потоки подій watch на боці сервера, доставляючи лише ті обʼєкти та події, хешоване значення метаданих яких потрапляє в запитаний діапазон.
Поле ShardSelector у ListOptions приймає вираз на основі CEL з використанням функції shardRange():
shardRange(<field-path>, '<hex-start>', '<hex-end>')
Де:
<field-path> — це поле метаданих, яке потрібно хешувати, у синтаксисі в стилі CEL з коренем в обʼєкті.
Наразі підтримуються такі шляхи:
object.metadata.uidobject.metadata.namespace<hex-start> — включна нижня межа діапазону хешу у вигляді 16-значного шістнадцяткового рядка в нижньому регістрі з префіксом 0x
(наприклад, '0x0000000000000000').<hex-end> — виключна верхня межа у вигляді шістнадцяткового рядка з префіксом 0x. Максимальне
значення — '0x10000000000000000' (2^64).API-сервер обчислює детермінований 64-бітний хеш FNV-1a вказаного значення поля і повертає лише ті обʼєкти, хеш яких потрапляє в діапазон [start, end). Функція хешування дає однаковий результат для одного й того самого вхідного значення на всіх екземплярах API-сервера, тому фрагментовані запити безпечно використовувати з кількома репліками API-сервера.
Ви можете комбінувати кілька діапазонів за допомогою || (логічне АБО), щоб охопити несуміжні частини простору хешів. Усі діапазони в одному виразі повинні використовувати той самий шлях до поля.
Контролери зазвичай використовують інформери для отримання списку ресурсів і спостереження за ними. Щоб розподілити навантаження між репліками, кожна репліка вставляє поле ShardSelector у ListOptions, які використовуються її інформерами.
Стандартний спосіб зробити це — використовувати WithTweakListOptions при створенні спільної фабрики інформерів. Функція коригування виконується перед кожним викликом list і watch, який робить інформер, тому селектор фрагментів застосовується послідовно:
import (
metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
"k8s.io/client-go/informers"
)
// shardSelector визначається ідентичністю репліки (наприклад, з порядкового номера
// StatefulSet або призначення на основі lease). Кожна репліка отримує
// діапазон простору хешів, що не перетинається з іншими.
shardSelector := "shardRange(object.metadata.uid, '0x0000000000000000', '0x8000000000000000')"
factory := informers.NewSharedInformerFactoryWithOptions(client, resyncPeriod,
informers.WithTweakListOptions(func(opts *metav1.ListOptions) {
opts.ShardSelector = shardSelector
}),
)
З цією конфігурацією кожен інформер, створений фабрикою, отримує список і спостерігає лише за тими обʼєктами, хешований UID яких потрапляє в призначений діапазон. Кожна репліка отримує неперетинну підмножину повної колекції, що зменшує мережевий трафік і використання памʼяті на кожну репліку.
Для розгортання з 2 репліками селектори будуть такими:
// Репліка 0: нижня половина простору хешів
"shardRange(object.metadata.uid, '0x0000000000000000', '0x8000000000000000')"
// Репліка 1: верхня половина простору хешів
"shardRange(object.metadata.uid, '0x8000000000000000', '0x10000000000000000')"
Одна репліка також може обробляти несуміжні діапазони, використовуючи ||:
"shardRange(object.metadata.uid, '0x0000000000000000', '0x4000000000000000') || " +
"shardRange(object.metadata.uid, '0x8000000000000000', '0xc000000000000000')"
Коли API-сервер враховує ShardSelector, відповідь на list містить поле shardInfo у metadata списку. Воно повертає селектор, щоб клієнти могли перевірити, який фрагмент вони отримали. Для потоків watch селектор фрагментів застосовується так само: API-сервер надсилає події лише для обʼєктів, хеш яких потрапляє в запитаний діапазон.
{
"kind": "PodList",
"apiVersion": "v1",
"metadata": {
"resourceVersion": "10245",
"shardInfo": {
"selector": "shardRange(object.metadata.uid, '0x0000000000000000', '0x8000000000000000')"
}
},
"items": [...]
}
shardInfo, представляє відфільтровану підмножину повної колекції. Клієнти не повинні розглядати фрагментовані відповіді на list як повне представлення типу ресурсу.Якщо API-сервер не підтримує фрагментовані list і watch (через те, що функціональну можливість не увімкнено, або сервер має старішу версію), поле ShardSelector ігнорується, і сервер повертає повний, нефільтрований набір результатів. Клієнти можуть виявити це, перевіривши наявність shardInfo у метаданих відповіді на list. Якщо shardInfo відсутнє, сервер не врахував селектор фрагментів, і клієнт отримав повну, нефільтровану колекцію. У цьому випадку клієнт повинен бути готовий обробляти повний набір результатів, наприклад, застосовуючи фільтрацію на боці клієнта, щоб відкинути обʼєкти поза призначеним йому діапазоном фрагментів.
APIResponseCompression — це опція, яка дозволяє API-серверу стискати відповіді на запити get та list, зменшуючи використання пропускної здатності мережі та покращуючи продуктивність великих кластерів. Її типово увімкнено з Kubernetes 1.16, і її можна вимкнути, додавши APIResponseCompression=false у прапорець --feature-gates на API-сервері.
Стиснення відповідей API може значно зменшити розмір відповіді, особливо для великих ресурсів або колекцій. Наприклад, запит list для Podʼів може повернути сотні кілобайт або навіть мегабайти даних, залежно від кількості Podʼів та їхніх атрибутів. Стиснення відповіді дозволяє заощадити пропускну здатність мережі та зменшити затримку.
Щоб перевірити, чи працює APIResponseCompression, ви можете надіслати запит get або list до API-сервера із заголовком Accept-Encoding і перевірити розмір відповіді та заголовки. Наприклад:
GET /api/v1/pods
Accept-Encoding: gzip
---
200 OK
Content-Type: application/json
content-encoding: gzip
...
Заголовок content-encoding вказує, що відповідь стиснута за допомогою gzip.
This is a stable feature in Kubernetes, and has been since the 1.29 release. You can no longer toggle this feature (the associated feature gate has been removed).
У великих кластерах отримання колекції деяких типів ресурсів може призвести до дуже великих відповідей, що може вплинути на сервер і клієнта. Наприклад, у кластері можуть бути десятки тисяч Podʼів, кожен з яких відповідає приблизно 2 КіБ закодованого JSON. Отримання всіх Podʼів в усіх просторах імен може призвести до дуже великої відповіді (10-20 МБ) і спожити багато ресурсів сервера.
API-сервер Kubernetes підтримує можливість розбиття одного великого запиту колекції на багато менших частин, зберігаючи при цьому узгодженість загального запиту. Кожна частина може бути повернута послідовно, що зменшує загальний розмір запиту і дозволяє клієнтам, орієнтованим на користувачів, показувати результати поступово для покращення швидкості реагування.
Ви можете запросити, щоб API-сервер обробляв list, надаючи одну колекцію сторінками (які Kubernetes називає chunks — частинами). Щоб отримати одну колекцію частинами, у запитах до колекцій підтримуються два параметри запиту limit та continue, а поле відповіді continue повертається з усіх операцій list у полі metadata колекції. Клієнт повинен вказати максимальну кількість результатів, яку він бажає отримати в кожній частині, за допомогою limit, і сервер поверне в результаті не більше limit ресурсів та включить значення continue, якщо в колекції є ще ресурси.
Як клієнт API, ви можете передати це значення continue API-серверу в наступному запиті, щоб вказати серверу повернути наступну сторінку (частину) результатів. Продовжуючи доти, доки сервер не поверне порожнє значення continue, ви можете отримати всю колекцію.
Як і у випадку з операцією watch, термін дії токена continue спливає через короткий проміжок часу (типово 5 хвилин), і повертається 410 Gone, якщо більше результатів не може бути повернуто. У цьому випадку клієнту потрібно буде почати спочатку або пропустити параметр limit.
Наприклад, якщо в кластері є 1253 Podʼи і ви хочете отримувати частини по 500 Podʼів за раз, запитуйте ці частини таким чином:
Отримати список усіх Podʼів у кластері, отримуючи до 500 Podʼів за раз.
GET /api/v1/pods?limit=500
---
200 OK
Content-Type: application/json
{
"kind": "PodList",
"apiVersion": "v1",
"metadata": {
"resourceVersion":"10245",
"continue": "ENCODED_CONTINUE_TOKEN",
"remainingItemCount": 753,
...
},
"items": [...] // повертає Podʼи 1-500
}
Продовжити попередній виклик, отримуючи наступний набір з 500 Podʼів.
GET /api/v1/pods?limit=500&continue=ENCODED_CONTINUE_TOKEN
---
200 OK
Content-Type: application/json
{
"kind": "PodList",
"apiVersion": "v1",
"metadata": {
"resourceVersion":"10245",
"continue": "ENCODED_CONTINUE_TOKEN_2",
"remainingItemCount": 253,
...
},
"items": [...] // повертає Podʼи 501-1000
}
Продовжити попередній виклик, отримуючи останні 253 Podʼи.
GET /api/v1/pods?limit=500&continue=ENCODED_CONTINUE_TOKEN_2
---
200 OK
Content-Type: application/json
{
"kind": "PodList",
"apiVersion": "v1",
"metadata": {
"resourceVersion":"10245",
"continue": "", // токен continue порожній, тому що ми досягли кінця списку
...
},
"items": [...] // повертає Podʼи 1001-1253
}
Зверніть увагу, що resourceVersion колекції залишається незмінним у кожному запиті, що вказує на те, що сервер показує вам узгоджений знімок Podʼів. Podʼи, що створюються, оновлюються або видаляються після версії 10245, не будуть показані, якщо ви не зробите окремий запит list без токена continue. Це дозволяє вам розбивати великі запити на менші частини, а потім виконувати операцію watch для повного набору, не пропускаючи жодного оновлення.
remainingItemCount — це кількість наступних елементів у колекції, які не включені в цю відповідь. Якщо запит list містив селектори міток або полів, тоді кількість решти елементів невідома, і API-сервер не включає поле remainingItemCount у свою відповідь. Якщо list завершено (або тому, що отримання частинами не використовується, або тому, що це остання частина), то елементів більше не залишилося, і API-сервер не включає поле remainingItemCount у свою відповідь. Призначення remainingItemCount — оцінка розміру колекції.
У термінології Kubernetes відповідь, яку ви отримуєте від list, є колекцією. Однак Kubernetes визначає конкретні види (kind) для колекцій різних типів ресурсів. Колекції мають вид, названий за видом ресурсу, з доданим List.
Коли ви надсилаєте запит до API для певного типу, всі елементи, повернуті цим запитом, мають цей тип. Наприклад, коли ви виконуєте list для Services, відповідь-колекція має kind, встановлений у ServiceList; кожен елемент у цій колекції представляє один Service. Наприклад:
GET /api/v1/services
{
"kind": "ServiceList",
"apiVersion": "v1",
"metadata": {
"resourceVersion": "2947301"
},
"items": [
{
"metadata": {
"name": "kubernetes",
"namespace": "default",
...
"metadata": {
"name": "kube-dns",
"namespace": "kube-system",
...
В API Kubernetes визначено десятки типів колекцій (таких як PodList, ServiceList та NodeList). Більше інформації про кожен тип колекції можна отримати з документації API Kubernetes.
Деякі інструменти, такі як kubectl, представляють механізм колекцій Kubernetes трохи інакше, ніж сам API Kubernetes. Оскільки вивід kubectl може включати відповіді кількох операцій list на рівні API, kubectl представляє список елементів, використовуючи kind: List. Наприклад:
kubectl get services -A -o yaml
apiVersion: v1
kind: List
metadata:
resourceVersion: ""
selfLink: ""
items:
- apiVersion: v1
kind: Service
metadata:
creationTimestamp: "2021-06-03T14:54:12Z"
labels:
component: apiserver
provider: kubernetes
name: kubernetes
namespace: default
...
- apiVersion: v1
kind: Service
metadata:
annotations:
prometheus.io/port: "9153"
prometheus.io/scrape: "true"
creationTimestamp: "2021-06-03T14:54:14Z"
labels:
k8s-app: kube-dns
kubernetes.io/cluster-service: "true"
kubernetes.io/name: CoreDNS
name: kube-dns
namespace: kube-system
Памʼятайте, що API Kubernetes не має kind з назвою List.
kind: List — це внутрішня деталь реалізації на боці клієнта для обробки колекцій, які можуть містити обʼєкти різних видів. Уникайте залежності від kind: List в автоматизації або іншому коді.
Коли ви запускаєте kubectl get, типовим форматом виводу є просте табличне представлення одного або кількох екземплярів певного типу ресурсу. У минулому клієнти повинні були відтворювати табличний і описовий вивід, реалізований у kubectl, щоб виконувати прості переліки обʼєктів. Серед обмежень цього підходу — нетривіальна логіка при роботі з певними обʼєктами. Крім того, типи, що надаються через агрегацію API або сторонні ресурси, невідомі під час компіляції. Це означає, що для типів, які не розпізнаються клієнтом, мали бути загальні реалізації.
Щоб уникнути можливих обмежень, описаних вище, клієнти можуть запитувати табличне представлення обʼєктів (Table), делегуючи серверу конкретні деталі виводу. API Kubernetes реалізує стандартне узгодження типів вмісту HTTP: передача заголовка Accept, що містить значення application/json;as=Table;g=meta.k8s.io;v=v1, з викликом GET попросить сервер повернути обʼєкти з типом вмісту Table.
Наприклад, отримати список усіх Podʼів у кластері у форматі Table.
GET /api/v1/pods
Accept: application/json;as=Table;g=meta.k8s.io;v=v1
---
200 OK
Content-Type: application/json
{
"kind": "Table",
"apiVersion": "meta.k8s.io/v1",
...
"columnDefinitions": [
...
]
}
Для типів ресурсів API, які не мають власного визначення Table, відомого панелі управління, API-сервер повертає типову відповідь Table, яка складається з полів name та creationTimestamp ресурсу.
GET /apis/crd.example.com/v1alpha1/namespaces/default/resources
---
200 OK
Content-Type: application/json
...
{
"kind": "Table",
"apiVersion": "meta.k8s.io/v1",
...
"columnDefinitions": [
{
"name": "Name",
"type": "string",
...
},
{
"name": "Created At",
"type": "date",
...
}
]
}
Не всі типи ресурсів API підтримують відповідь Table; наприклад, CustomResourceDefinitions можуть не визначати відповідність полів таблиці, а APIService, що розширює основний API Kubernetes, може взагалі не надавати відповіді Table. Якщо ви створюєте клієнта, що використовує інформацію Table і повинен працювати з усіма типами ресурсів, включно з розширеннями, вам слід робити запити, які вказують кілька типів вмісту в заголовку Accept. Наприклад:
Accept: application/json;as=Table;g=meta.k8s.io;v=v1, application/json
Якщо клієнт вказує, що приймає тільки ...;as=Table;g=meta.k8s.io;v=v1, сервери, які не підтримують табличні відповіді, повернуть код помилки 406.
Якщо в цьому випадку бажано повернутися до повних обʼєктів, клієнти можуть додати ,application/json (або будь-яке інше підтримуване кодування) до свого заголовка Accept і обробляти у відповіді як таблиці, так і повні обʼєкти:
Accept: application/json;as=Table;g=meta.k8s.io;v=v1,application/json`
Для отримання додаткової інформації про узгодження типу вмісту див. MDN Content Negotiation.
Щоб отримати часткові метадані обʼєкта, ви можете запросити відповіді лише з метаданими в заголовку Accept. API Kubernetes реалізує варіант узгодження типу вмісту HTTP. Як клієнт, ви можете надати заголовок Accept з бажаним медіатипом, а також параметрами, які вказують, що ви хочете отримати лише метадані. Наприклад: Accept: application/json;as=PartialObjectMetadata;g=meta.k8s.io;v=v1 для JSON для конкретного обʼєкта та Accept: application/json;as=PartialObjectMetadataList;g=meta.k8s.io;v=v1 для списку.
as=PartialObjectMetadata слід використовувати в запитах до конкретних ресурсів, а as=PartialObjectMetadataList — для запитів list.Наприклад, щоб отримати список усіх Podʼів у кластері, в усіх просторах імен, але повернути лише метадані для кожного Podʼа:
GET /api/v1/pods
Accept: application/json;as=PartialObjectMetadataList;g=meta.k8s.io;v=v1
---
200 OK
Content-Type: application/json
{
"kind": "PartialObjectMetadataList",
"apiVersion": "meta.k8s.io/v1",
"metadata": {
"resourceVersion": "...",
},
"items": [
{
"apiVersion": "meta.k8s.io/v1",
"kind": "PartialObjectMetadata",
"metadata": {
"name": "pod-1",
...
}
},
{
"apiVersion": "meta.k8s.io/v1",
"kind": "PartialObjectMetadata",
"metadata": {
"name": "pod-2",
...
}
}
]
}
На запит колекції API-сервер повертає PartialObjectMetadataList. На запит окремого обʼєкта API-сервер повертає представлення PartialObjectMetadata цього обʼєкта. В обох випадках повернуті обʼєкти містять лише поле metadata. Поля spec та status пропускаються.
Ця функція корисна для клієнтів, яким потрібно лише перевірити наявність обʼєкта або лише прочитати його метадані. Вона може значно зменшити розмір відповіді від API-сервера.
Ви можете запросити отримання лише метаданих для всіх доступних медіатипів (JSON, YAML, CBOR і Kubernetes Protobuf). Для Protobuf заголовок Accept буде таким:
application/vnd.kubernetes.protobuf;as=PartialObjectMetadata;g=meta.k8s.io;v=v1.
API-сервер Kubernetes підтримує часткове отримання майже для всіх своїх вбудованих API. Однак ви можете використовувати Kubernetes для доступу до інших API-серверів через рівень агрегації, і ці API можуть не підтримувати часткове отримання.
Якщо клієнт використовує заголовок Accept, щоб запросити лише відповідь ...;as=PartialObjectMetadata;g=meta.k8s.io;v=v1, і звертається до API, який не підтримує часткові відповіді, Kubernetes відповідає помилкою HTTP 406.
Якщо в цьому випадку бажано повернутися до повних обʼєктів, клієнти можуть додати ,application/json (або будь-яке інше підтримуване кодування) до свого заголовка Accept і обробляти у відповіді або PartialObjectMetadata, або повні обʼєкти. Варто вказати, що перевага надається частковій відповіді, використовуючи параметр q (quality — якість). Наприклад:
Accept: application/json;as=PartialObjectMetadata;g=meta.k8s.io;v=v1, application/json;q=0.9
Для отримання додаткової інформації про узгодження типу вмісту див. MDN Content Negotiation.
Коли ви виконуєте delete для ресурсу, цей процес проходить у два етапи.
{
"kind": "ConfigMap",
"apiVersion": "v1",
"metadata": {
"finalizers": ["url.io/neat-finalization", "other-url.io/my-finalizer"],
"deletionTimestamp": nil,
}
}
Коли клієнт вперше надсилає delete, щоб запросити вилучення ресурсу, .metadata.deletionTimestamp встановлюється на поточний час. Після встановлення .metadata.deletionTimestamp зовнішні контролери, які працюють із завершувачами (finalizers), можуть почати виконувати свою роботу з очищення в будь-який час, у будь-якому порядку.
Порядок між завершувачами не встановлюється примусово, оскільки це створило б значний ризик застрягання .metadata.finalizers.
Поле .metadata.finalizers є спільним: будь-який учасник із відповідним дозволом може змінювати його порядок.
Якби список завершувачів оброблявся по порядку, це могло б призвести до ситуації, коли компонент, відповідальний за перший завершувач у списку, чекає на якийсь сигнал (значення поля, зовнішню систему або інше), що створюється компонентом, відповідальним за завершувач, розташований далі у списку, що призводить до взаємного блокування.
Без примусового впорядкування завершувачі можуть вільно впорядковуватися між собою і не є вразливими до змін порядку у списку.
Після вилучення останнього завершувача ресурс фактично видаляється з etcd.
Увімкнувши опцію видалення ignoreStoreReadErrorWithClusterBreakingPotential, користувач може виконати небезпечну операцію примусового delete для ресурсу, який неможливо розшифрувати або який пошкоджено. Ця опція доступна, коли увімкнено функціональну можливість AllowUnsafeMalformedObjectDeletion, що є типовим, починаючи з Kubernetes v1.37. Оператор кластера може вимкнути цю поведінку, встановивши параметр командного рядка --feature-gates=AllowUnsafeMalformedObjectDeletion=false.
Ресурс вважається пошкодженим, якщо його неможливо успішно отримати зі сховища через:
API-сервер спочатку намагається виконати звичайне видалення, і якщо воно завершується помилкою пошкодженого ресурсу (corrupt resource), він запускає примусове видалення. Операція примусового delete є небезпечною, оскільки вона ігнорує обмеження завершувачів і пропускає перевірку передумов.
Типове значення для цієї опції — false, що забезпечує зворотну сумісність. Для запиту delete з параметром ignoreStoreReadErrorWithClusterBreakingPotential, встановленим у true, поля dryRun, gracePeriodSeconds, orphanDependents, preconditions і propagationPolicy слід залишити не встановленими.
ignoreStoreReadErrorWithClusterBreakingPotential, встановленим у true, для ресурсу, який в іншому разі можна прочитати, API-сервер перериває запит з помилкою.Дієслова API Kubernetes get, create, update, patch, delete та proxy підтримують лише окремі ресурси. Ці дієслова з підтримкою окремих ресурсів не підтримують надсилання кількох ресурсів разом в упорядкованому або неупорядкованому списку чи транзакції.
Коли клієнти (включно з kubectl) виконують дії з набором ресурсів, клієнт робить серію API-запитів до окремих ресурсів, а потім, за потреби, агрегує відповіді.
На відміну від цього, дієслова API Kubernetes list і watch дозволяють отримувати кілька ресурсів, а deletecollection дозволяє видаляти кілька ресурсів.
Kubernetes завжди перевіряє тип полів. Наприклад, якщо поле в API визначене як число, ви не можете встановити для нього текстове значення. Якщо поле визначене як масив рядків, ви можете надати лише масив. Деякі поля можна пропустити, інші поля є обовʼязковими. Пропуск обовʼязкового поля в запиті API є помилкою.
Якщо ви зробите запит з додатковим полем, яке не розпізнається панеллю управління кластера, тоді поведінка API-сервера складніша.
Типово API-сервер відкидає поля, які він не розпізнає, з отриманих вхідних даних (наприклад, з тіла JSON запиту PUT).
Є дві ситуації, коли API-сервер відкидає поля, які ви надали в HTTP-запиті.
Ці ситуації такі:
x-kubernetes-preserve-unknown-fields).This is a stable feature in Kubernetes, and has been since the 1.27 release. You can no longer toggle this feature (the associated feature gate has been removed).
Починаючи з версії 1.25, нерозпізнані або дубльовані поля в обʼєкті виявляються через валідацію на сервері, коли ви використовуєте HTTP-дієслова, які можуть надсилати дані (POST, PUT та PATCH). Можливі рівні валідації: Ignore, Warn (типово) та Strict.
IgnoreWarnWarning:, додаючи один елемент попередження для кожного невідомого або дубльованого поля. Для отримання додаткової інформації про попередження та API Kubernetes дивіться статтю блогу Warning: Helpful Warnings Ahead.StrictРівень валідації полів встановлюється параметром запиту fieldValidation.
Якщо ви надсилаєте запит, у якому вказано нерозпізнане поле і який також є недійсним з іншої причини (наприклад, запит надає рядкове значення там, де API очікує ціле число для відомого поля), тоді API-сервер відповідає помилкою 400 Bad Request, але не надає жодної інформації про невідомі або дубльовані поля (лише про ту фатальну помилку, яку він виявив першою).
У цьому випадку ви завжди отримаєте відповідь з помилкою, незалежно від того, який рівень валідації полів ви запросили.
Інструменти, які надсилають запити на сервер (такі як kubectl), можуть встановлювати власні типові значення, які відрізняються від рівня валідації Warn, що типово використовується API-сервером.
Інструмент kubectl використовує прапорець --validate для встановлення рівня валідації полів. Він приймає значення ignore, warn та strict, а також значення true (еквівалентно strict) і false (еквівалентно ignore). Типове налаштування валідації для kubectl — --validate=true, що означає сувору валідацію полів на боці сервера.
Коли kubectl не може підключитися до API-сервера з валідацією полів (API-сервери до Kubernetes 1.27), він повертається до використання валідації на боці клієнта. Валідацію на боці клієнта буде повністю вилучено в майбутній версії kubectl.
kubectl --validate використовувався як булевий прапорець для увімкнення або вимкнення валідації на боці клієнта.Починаючи з v1.33, Kubernetes (включно з v1.37) пропонує спосіб визначення валідації полів за допомогою декларативних теґів. Це корисно для тих, хто бере участь у розробці самого Kubernetes, а також актуально, якщо ви пишете власний API з використанням бібліотек Kubernetes. Щоб дізнатися більше, див. Декларативна валідація API.
This is a stable feature in Kubernetes, and has been since the 1.19 release. You can no longer toggle this feature (the associated feature gate has been removed).
Коли ви використовуєте HTTP-дієслова, які можуть змінювати ресурси (POST, PUT, PATCH і DELETE), ви можете надіслати свій запит у режимі пробного запуску (dry run). Режим пробного запуску допомагає оцінити запит на типових етапах обробки запиту (ланцюжок допуску, валідація, конфлікти злиття) аж до збереження обʼєктів у сховищі. Тіло відповіді на запит максимально наближене до відповіді на звичайний запит (без пробного запуску). Kubernetes гарантує, що запити пробного запуску не будуть збережені в сховищі і не матимуть жодних інших побічних ефектів.
Пробний запуск активується встановленням параметра запиту dryRun. Цей параметр є рядком, працює як перелік (enum), і єдині прийнятні значення:
?dryRun або ?dryRun&pretty=true. Відповіддю є остаточний обʼєкт, який було б збережено, або помилка, якщо запит не може бути виконаний.AllКоли ви встановлюєте ?dryRun=All, усі відповідні контролери допуску виконуються, контролери допуску з валідацією перевіряють запит після мутації, для PATCH виконується злиття, полям встановлюються типові значення, і проводиться валідація схеми. Зміни не зберігаються в базовому сховищі, але остаточний обʼєкт, який було б збережено, все одно повертається користувачеві разом зі звичайним кодом статусу.
Якщо звичайна версія запиту (без пробного запуску) викликала б контролер допуску, який має побічні ефекти, запит буде відхилено, щоб не ризикувати небажаними побічними ефектами. Усі вбудовані втулки контролю допуску підтримують пробний запуск. Крім того, вебхуки допуску можуть оголосити у своєму обʼєкті конфігурації, що вони не мають побічних ефектів, встановивши поле sideEffects у None.
sideEffects слід встановити у "NoneOnDryRun". Ця зміна доречна за умови, що вебхук також модифіковано, щоб він розумів поле DryRun в AdmissionReview і запобігав побічним ефектам для будь-якого запиту, позначеного як пробний запуск.Ось приклад запиту пробного запуску, який використовує ?dryRun=All:
POST /api/v1/namespaces/test/pods?dryRun=All
Content-Type: application/json
Accept: application/json
Відповідь виглядатиме так само, як для звичайного запиту (без пробного запуску), але значення деяких згенерованих полів можуть відрізнятися.
Деякі значення обʼєкта зазвичай генеруються перед його збереженням. Важливо не покладатися на значення цих полів, встановлені запитом пробного запуску, оскільки ці значення в режимі пробного запуску, ймовірно, відрізнятимуться від значень під час виконання реального запиту. Деякі з цих полів:
name: якщо встановлено generateName, name матиме унікальне випадкове імʼяcreationTimestamp / deletionTimestamp: фіксує час створення/видаленняUID: унікально ідентифікує
обʼєкт і генерується випадково (недетерміновано)resourceVersion: відстежує збережену версію обʼєктаService: порти або IP-адреси, які kube-apiserver призначає обʼєктам ServiceАвторизація для запитів пробного запуску та звичайних запитів ідентична. Отже, щоб виконати запит пробного запуску, ви повинні мати дозвіл на виконання звичайного запиту.
Наприклад, щоб виконати пробний запуск patch для Deployment, ви повинні мати дозвіл на виконання цього patch. Ось приклад правила для Kubernetes RBAC, що дозволяє застосовувати patch до Deployment:
rules:
- apiGroups: ["apps"]
resources: ["deployments"]
verbs: ["patch"]
Дивіться Огляд авторизації.
Kubernetes надає декілька способів оновлення наявних обʼєктів. Ви можете прочитати розділ вибір механізму оновлення, щоб дізнатися, який підхід найкраще підходить для вашого випадку.
Ви можете перезаписати (update) наявний ресурс, наприклад ConfigMap, використовуючи HTTP PUT. Для запиту PUT відповідальність за вказання resourceVersion (взятого з обʼєкта, що оновлюється) лежить на клієнті. Kubernetes використовує інформацію resourceVersion, щоб API-сервер міг виявляти втрачені оновлення і відхиляти запити від клієнта, дані якого застаріли відносно кластера. Якщо ресурс змінився (resourceVersion, надана клієнтом, застаріла), API-сервер повертає відповідь з помилкою 409 Conflict.
Замість надсилання запиту PUT клієнт може надіслати API-серверу інструкцію застосувати patch до наявного ресурсу. patch зазвичай доречний, якщо зміна, яку клієнт хоче внести, не залежить від наявних даних. Клієнтам, яким потрібне ефективне виявлення втрачених оновлень, слід розглянути можливість зробити свій запит умовним щодо наявного resourceVersion (як HTTP PUT, так і HTTP PATCH), а потім обробляти будь-які повторні спроби, які можуть знадобитися у разі конфлікту.
API Kubernetes підтримує чотири різні операції PATCH, які визначаються відповідним заголовком HTTP Content-Type:
application/apply-patch+yamlapplication/json-patch+json{"op": "add", "path": "/a/b/c", "value": [ "foo", "bar" ]}.
Для Kubernetes це операція patch.
patch з використанням application/json-patch+json може містити умови для
перевірки узгодженості, що дозволяє операції завершитися невдачею, якщо ці умови
не виконуються (наприклад, щоб уникнути втраченого оновлення).
application/merge-patch+jsonapplication/strategic-merge-patch+jsonapplication/strategic-merge-patch+json з будь-яким API,
визначеним за допомогою CustomResourceDefinition.
Функція Server Side Apply Kubernetes дозволяє панелі управління відстежувати керовані поля для новостворених обʼєктів. Server Side Apply надає чіткий шаблон для управління конфліктами полів, пропонує операції apply та update на боці сервера і замінює функціональність kubectl apply на боці клієнта.
Для Server-Side Apply Kubernetes обробляє запит як create, якщо обʼєкт ще не існує, і як patch в іншому разі. Для інших запитів, які використовують PATCH на рівні HTTP, логічною операцією Kubernetes завжди є patch.
Дивіться Server Side Apply для отримання додаткової інформації.
Операція update (HTTP PUT) проста в реалізації та гнучка, але має недоліки:
resourceVersion обʼєкта змінюється між моментом його читання вашим клієнтом і спробою записати його назад. Kubernetes завжди виявляє конфлікт, але вам як авторові клієнта потрібно реалізувати повторні спроби.Оновлення через patch корисне, оскільки:
PATCH.PUT), ваші зміни можуть відбутися відразу, навіть якщо часто змінюються неповʼязані поля: зазвичай вам не потрібно повторювати спроби.
resourceVersion (щоб відповідати наявному обʼєкту), якщо ви хочете бути особливо обережними, щоб уникнути втрачених оновленьПроте:
Server-Side Apply має деякі очевидні переваги:
GET.
UPSERT у деяких діалектах SQL).Проте:
.metadata), а Server-Side Apply стосується лише обʼєктів Kubernetes.Версії ресурсів — це рядки, які ідентифікують внутрішню версію обʼєкта на сервері. Клієнти можуть використовувати версії ресурсів, щоб визначати, коли обʼєкти змінилися, або щоб виражати вимоги до узгодженості даних під час отримання ресурсів, отримання їхнього списку та спостереження за ними. Версії ресурсів повинні передаватися назад на сервер без змін.
Рядки версій ресурсів можна впорядкувати як монотонно зростаючі цілі числа в межах одного типу ресурсів для всіх типів, що обслуговуються kube-apiserver. Сюди входять вбудовані типи API та типи, що базуються на визначеннях власних ресурсів. Обидві версії ресурсів повинні належати обʼєктам однієї групи API та одного типу ресурсів. Наприклад, можна порівняти версії ресурсів двох Deployment з групи API apps, але не можна порівняти версії ресурсів Pod і Deployment. За умови, що два обʼєкти отримано з одного типу ресурсів API, їх можна порівнювати, навіть якщо вони знаходяться в різних просторах імен.
Якщо ви використовуєте ресурси API, що обслуговуються API-сервером розширення, клієнт повинен перевірити, чи розбирається рядок версії ресурсу як десяткове число (докладніше про це в наступних кількох абзацах). Якщо будь-який із двох рядків версії ресурсу не розбирається як десяткове число, ці два рядки можна перевірити на рівність, але не можна покладатися на порівняння для впорядкування.
Починаючи з Kubernetes 1.35, можливість впорядкування версій ресурсів для всіх типів Kubernetes включено до вимог Certified Kubernetes. Базові обʼєкти API та власні ресурси повинні впорядковуватися як монотонно зростаюче ціле число в будь-якій реалізації APIServer 1.35+, щоб пройти тести на відповідність.
Щоб порівняти два рядки версій ресурсів:
Переконайтеся, що вони відповідають таким вимогам:
Щоб порівняти їх, не покладаючись на фіксовану розрядність, можна порівнювати їх як рядки. Не слід припускати, що розрядність має якесь фіксоване значення.
Натомість можна використовувати лексикографічне порівняння, як показано тут:
Деякі приклади порівнянь версій ресурсів, які повинні працювати:
Для виконання цього порівняння в client-go доступний допоміжний метод.
resourceVersion в метаданихКлієнти знаходять версії ресурсів у ресурсах, включно з ресурсами з потоку відповіді для watch або при використанні list для переліку ресурсів.
v1.meta/ObjectMeta —
metadata.resourceVersion екземпляра ресурсу ідентифікує версію ресурсу, на якій екземпляр було востаннє змінено.
v1.meta/ListMeta —
metadata.resourceVersion колекції ресурсів (відповіді на list) ідентифікує версію ресурсу, на якій було сформовано колекцію.
resourceVersion у рядках запитівОперації get, list та watch підтримують параметр resourceVersion. Починаючи з версії v1.19, API-сервери Kubernetes також підтримують параметр resourceVersionMatch у запитах list.
API-сервер інтерпретує параметр resourceVersion по-різному залежно від операції, яку ви запитуєте, та від значення resourceVersion. Якщо ви встановлюєте resourceVersionMatch, то це також впливає на спосіб зіставлення.
Для get та list семантика resourceVersion така:
get:
| resourceVersion не встановлено | resourceVersion="0" | resourceVersion="{значення, відмінне від 0}" |
|---|---|---|
| Найновіша | Будь-яка | Не старша ніж |
list:
Починаючи з версії v1.19, API-сервери Kubernetes підтримують параметр resourceVersionMatch у запитах list. Якщо ви встановлюєте як resourceVersion, так і resourceVersionMatch, то параметр resourceVersionMatch визначає, як API-сервер інтерпретує resourceVersion.
Вам завжди слід встановлювати параметр resourceVersionMatch, коли ви встановлюєте resourceVersion у запиті list. Однак будьте готові обробляти випадок, коли API-сервер, що відповідає, не знає про resourceVersionMatch і ігнорує його.
Якщо у вас немає суворих вимог до узгодженості, бажано використовувати resourceVersionMatch=NotOlderThan та відому resourceVersion, оскільки це може забезпечити кращу продуктивність і масштабованість вашого кластера, ніж залишати resourceVersion і resourceVersionMatch невстановленими, що вимагає кворумного читання для обслуговування.
Встановлення параметра resourceVersionMatch без встановлення resourceVersion є недійсним.
Ця таблиця пояснює поведінку запитів list з різними комбінаціями resourceVersion та resourceVersionMatch:
| Параметр resourceVersionMatch | Параметри розбиття на сторінки | resourceVersion не встановлено | resourceVersion="0" | resourceVersion="{значення, відмінне від 0}" |
|---|---|---|---|---|
| не встановлено | limit не встановлено | Найновіша | Будь-яка | Не старша ніж |
| не встановлено | limit=<n>, continue не встановлено | Найновіша | Будь-яка | Точна |
| не встановлено | limit=<n>, continue=<token> | Продовження | Продовження | Недійсно, HTTP 400 Bad Request |
resourceVersionMatch=Exact |
limit не встановлено | Недійсно | Недійсно | Точна |
resourceVersionMatch=Exact |
limit=<n>, continue не встановлено | Недійсно | Недійсно | Точна |
resourceVersionMatch=NotOlderThan |
limit не встановлено | Недійсно | Будь-яка | Не старша ніж |
resourceVersionMatch=NotOlderThan |
limit=<n>, continue не встановлено | Недійсно | Будь-яка | Не старша ніж |
resourceVersionMatch, поведінка буде такою самою, як якщо б ви його не встановили.Значення семантики get та list таке:
resourceVersion. Перевага надається найновішим
доступним даним, але можуть бути надані будь-які дані, не старші за надану resourceVersion.
Для запитів list до серверів, які враховують параметр resourceVersionMatch, це
гарантує, що .metadata.resourceVersion колекції не старша за запитану
resourceVersion, але не дає жодних гарантій щодо .metadata.resourceVersion будь-яких
елементів у цій колекції.
Завжди обслуговується з кешу спостереження, що покращує продуктивність і зменшує навантаження на etcd.resourceVersion
недоступна, сервер відповідає HTTP 410 Gone. Для запитів list до серверів, які враховують
параметр resourceVersionMatch, це гарантує, що .metadata.resourceVersion колекції
збігається з resourceVersion, яку ви запросили в рядку запиту. Ця гарантія
не поширюється на .metadata.resourceVersion будь-яких елементів у цій колекції.
Коли функціональна можливість ListFromCacheSnapshot типово увімкнена,
API-сервер намагатиметься надати відповідь зі знімка, якщо доступний знімок з resourceVersion, старішою за запитану.
Це покращує продуктивність і зменшує навантаження на etcd. API-сервер запускається без знімків,
створює новий знімок на кожну подію спостереження і зберігає їх, доки не виявить ущільнення (compaction) etcd або доки кеш не заповниться подіями, старшими за 75 секунд.
Якщо надана resourceVersion недоступна, сервер звернеться до etcd.resourceVersion, встановленою початковим запитом у послідовності.
Відповідь на запити list з limit містить токен continue, який кодує resourceVersion і останню спостережувану позицію, з якої слід продовжити список.
Якщо resourceVersion у наданому токені continue недоступна, сервер відповідає HTTP 410 Gone.
Коли функціональна можливість ListFromCacheSnapshot типово увімкнена,
API-сервер намагатиметься надати відповідь зі знімка, якщо доступний знімок з resourceVersion, старішою за запитану.
Це покращує продуктивність і зменшує навантаження на etcd. API-сервер запускається без знімків,
створює новий знімок на кожну подію спостереження і зберігає їх, доки не виявить ущільнення (compaction) etcd або доки кеш не заповниться подіями, старшими за 75 секунд.
Якщо resourceVersion у наданому токені continue недоступна, сервер звернеться до etcd..metadata.resourceVersion відстежує, коли цей обʼєкт було востаннє оновлено, а не те, наскільки актуальним є обʼєкт на момент надання.Коли використовується resourceVersionMatch=NotOlderThan і встановлено limit, клієнти повинні обробляти відповіді HTTP 410 Gone. Наприклад, клієнт може повторити спробу з новішою resourceVersion або повернутися до resourceVersion="".
Коли використовується resourceVersionMatch=Exact і limit не встановлено, клієнти повинні перевіряти, що .metadata.resourceVersion колекції збігається із запитаною resourceVersion, і обробляти випадок, коли це не так. Наприклад, клієнт може повернутися до запиту зі встановленим limit.
Для watch семантика версії ресурсу така:
watch:
| resourceVersion не встановлено | resourceVersion="0" | resourceVersion="{значення, відмінне від 0}" |
|---|---|---|
| Отримати стан і почати з найновішої | Отримати стан і почати з будь-якої | Почати з точної |
Значення цієї семантики watch таке:
Сервери не зобовʼязані надавати всі старіші версії ресурсів і можуть повернути код статусу HTTP 410 (Gone), якщо клієнт запитує resourceVersion, старішу, ніж та, що зберігається на сервері. Клієнти повинні бути готові обробляти відповіді 410 (Gone). Дивіться розділ Ефективне виявлення змін для отримання додаткової інформації про те, як обробляти відповіді 410 (Gone) під час спостереження за ресурсами.
Якщо ви запитуєте resourceVersion за межами допустимого діапазону, то, залежно від того, чи обслуговується запит з кешу чи ні, API-сервер може відповісти HTTP-відповіддю 410 Gone.
Сервери не зобовʼязані обслуговувати нерозпізнані версії ресурсів. Якщо ви запитуєте list або get для версії ресурсу, яку API-сервер не розпізнає, то API-сервер може або:
504 (Gateway Timeout), якщо надана версія ресурсу не стане доступною
протягом розумного часу;Retry-After, який вказує, скільки секунд клієнт
повинен зачекати перед повторною спробою запиту.Якщо ви запитуєте версію ресурсу, яку API-сервер не розпізнає, kube-apiserver додатково позначає свої відповіді з помилками повідомленням Too large resource version.
Якщо ви робите запит watch для нерозпізнаної версії ресурсу, API-сервер може чекати невизначено довго (до тайм-ауту запиту), поки версія ресурсу стане доступною.
Щоб запобігти перевантаженню панелі управління та голодуванню API Priority and Fairness (APF) під час ініціалізації або повторної ініціалізації кешу спостереження, API-сервер Kubernetes застосовує два захисні механізми:
/readyz), доки кожен зареєстрований кеш спостереження не завершить свою початкову синхронізацію з etcd. Це запобігає передчасному спрямуванню клієнтського трафіку балансувальниками навантаження на API-сервер, усуваючи масові одночасні читання під час запуску (thundering herd), які інакше оминали б неготовий кеш і потрапляли б безпосередньо в etcd.WATCH та запити LIST без розбиття на сторінки або з фільтрацією (будь-який запит списку без limit для розбиття на сторінки або із селектором міток чи полів) негайно відхиляються з кодом статусу HTTP 429 Too Many Requests та динамічним заголовком Retry-After. Це запобігає зависанню goroutine, голодуванню місць APF та вичерпанню памʼяті etcd.GET та запити LIST з розбиттям на сторінки і без фільтрації (limit > 0 без селектора міток чи полів) делегуються безпосередньо до etcd як безпечний запасний варіант.Клієнти (включно з власними контролерами та операторами) мають бути розроблені так, щоб коректно обробляти відповіді HTTP 429 Too Many Requests, поважаючи заголовки Retry-After та реалізуючи експоненційну затримку повторних спроб.