Довідник

• 1: Глосарій
• 2: Огляд API
• 2.1: Концепції API Kubernetes
• 2.2: Загальна мова виразів у Kubernetes
• 3: Керування доступом до API
• 3.1: Авторизація
• 3.2: Використання авторизації ABAC
• 3.3: Автентифікація/авторизація kubelet
• 4: Відомі мітки, анотації та позначки taint
• 5: Інструментування
• 6: Безпека та проблеми Kubernetes
• 6.1: Трекер проблем Kubernetes
• 7: Довідкова інформація про вузли
• 7.1: Стандартні атрибути пристроїв для динамічного виділення ресурсів
• 7.2: Локальні файли та шляхи, які використовує Kubelet
• 7.3: Версії API Kubelet Device Manager
• 7.4: Поведінка свопу на вузлах Linux
• 7.5:
• 8: Довідник з мережі
• 9: Інструменти встановлення
• 9.1: Kubeadm
• 9.1.1: kubeadm alpha
• 10: Інструмент командного рядка (kubectl)
• 10.1: Довідник kubectl
• 10.2: Команди kubectl
• 10.3: Налаштування користувача для kubectl (kuberc)
• 11: Кодування
• 11.1: Довідник KYAML
• 12: Інструменти компонентів
• 13: Налагодження кластера
• 14: Конфігураційні API
• 15: Зовнішні API
• 16: API kubelet
• 17: Планування
• 17.1: Політики планування
• 18: Інші інструменти

1 - Глосарій

2 - Огляд API

Цей розділ містить довідкову інформацію про API Kubernetes.

REST API є фундаментальною основою Kubernetes. Усі операції та комунікації між компонентами та зовнішніми командами користувачів є викликами REST API, які обробляє API-сервер. Внаслідок цього все в Kubernetes обробляється як обʼєкти API та має відповідний запис в API.

Довідник API Kubernetes містить список API для версії Kubernetes v1.37.

Загальні відомості дивіться в розділі API Kubernetes. Контроль доступу до API Kubernetes описує, як клієнти можуть автентифікуватися на API-сервері Kubernetes і як авторизуються їхні запити.

Версіювання API

Схеми серіалізації JSON та Protobuf дотримуються однакових правил щодо змін схеми. Наведені нижче описи стосуються обох форматів.

Версіювання API та версіювання програмного забезпечення опосередковано повʼязані. Пропозиція з версіювання API та релізів описує звʼязок між версіюванням API та версіюванням програмного забезпечення.

Різні версії API вказують на різні рівні стабільності та підтримки. Докладнішу інформацію про критерії кожного рівня можна знайти в документації API Changes.

Ось короткий огляд кожного рівня:

• Alpha:

  • Назви версій містять alpha (наприклад, v1alpha1).
  • Вбудовані версії API рівня alpha типово вимкнені та повинні бути явно увімкнені в конфігурації kube-apiserver для використання.
  • Програмне забезпечення може містити помилки. Увімкнення функції може виявити помилки.
  • Підтримку alpha API може бути припинено будь-коли без попередження.
  • API може змінитися несумісним чином у подальших версіях програмного забезпечення без попередження.
  • Програмне забезпечення рекомендується використовувати лише в короткочасних тестових кластерах через збільшений ризик помилок та відсутність довгострокової підтримки.

• Beta:

  • Назви версій містять beta (наприклад, v2beta3).

  • Вбудовані версії API рівня beta типово вимкнені та повинні бути явно увімкнені в конфігурації kube-apiserver для використання (за винятком бета-версій API, представлених до Kubernetes 1.22, які були типово увімкнені).

  • Вбудовані версії API рівня beta мають максимальний термін існування 9 місяців або 3 мінорні випуски (залежно від того, що довше), починаючи від введення до застаріння, і 9 місяців або 3 мінорні випуски (залежно від того, що довше) від застаріння до вилучення.

  • Програмне забезпечення добре протестоване. Увімкнення функції вважається безпечним.

  • Підтримку функції не буде припинено, хоча деталі можуть змінитися.

  • Схема та/або семантика обʼєктів може змінюватися несумісним чином у подальших версіях API рівня beta або стабільного. Коли це відбувається, надаються інструкції з міграції. Адаптація до наступної версії API рівня beta або стабільного може вимагати редагування чи повторного створення обʼєктів API, і це може бути не простим. Міграція може вимагати перерви у роботі застосунків, які покладаються на цю функцію.

  • Програмне забезпечення не рекомендується для використання в промисловому середовищі. Подальші випуски можуть вносити несумісні зміни. Після того як версію API рівня beta визнано застарілою і вона більше не обслуговується, тим, хто її використовує, доведеться перейти на наступні версії API рівня beta або стабільні.

  Примітка:

  Спробуйте бета-функції та надавайте відгуки. Після того, як функції вийдуть з бета, може бути непрактично вносити більше змін.

• Stable:

  • Назва версії — vX, де X – це ціле число.
  • Стабільні версії API залишаються доступними для всіх майбутніх випусків в межах основної версії Kubernetes, і немає поточних планів щодо ревізії основної версії Kubernetes, що вилучає стабільні API.

Групи API

Групи API спрощують розширення API Kubernetes. Група API вказується в REST-шляху та в полі apiVersion серіалізованого обʼєкта.

У Kubernetes існує кілька груп API:

• Група core (також називається legacy) знаходиться за REST-шляхом /api/v1. Група core не вказується як частина поля apiVersion, наприклад, apiVersion: v1.
• Іменовані групи знаходяться за REST-шляхом /apis/$GROUP_NAME/$VERSION та використовують apiVersion: $GROUP_NAME/$VERSION (наприклад, apiVersion: batch/v1). Повний список підтримуваних груп API можна знайти в довіднику API Kubernetes.

Увімкнення чи вимкнення груп API

Деякі ресурси та групи API типово увімкнені. Ви можете увімкнути чи вимкнути їх, встановивши --runtime-config на API-сервері. Прапорець --runtime-config приймає розділені комами пари <key>[=<value>], що описують конфігурацію запуску API-сервера. Якщо частина =<value> пропущена, вона розглядається так, ніби вказано =true. Наприклад:

• для вимкнення batch/v1 встановіть --runtime-config=batch/v1=false
• для увімкнення batch/v2alpha1 встановіть --runtime-config=batch/v2alpha1
• для увімкнення конкретної версії API, наприклад, storage.k8s.io/v1beta1/csistoragecapacities, встановіть --runtime-config=storage.k8s.io/v1beta1/csistoragecapacities

Збереження

Kubernetes зберігає свій серіалізований стан у вигляді ресурсів API, записуючи їх в etcd.

Що далі

• Дізнайтеся більше про домовленості API
• Прочитайте проєктну документацію агрегатора
• Дізнайтесь про Декларативну перевірку API.

2.1 - Концепції API Kubernetes

API Kubernetes — це програмний інтерфейс на основі ресурсів (RESTful), який надається через HTTP. Він підтримує отримання, створення, оновлення та видалення основних ресурсів за допомогою стандартних HTTP-дієслів (POST, PUT, PATCH, DELETE, GET).

Для деяких ресурсів API включає додаткові субресурси, що дозволяють детальніше налаштовувати авторизацію (наприклад, окремі представлення для деталей Pod та отримання логів), і може приймати та надавати ці ресурси в різних представленнях для зручності або ефективності.

Kubernetes підтримує ефективні сповіщення про зміни ресурсів за допомогою спостережень (watches):

в API Kubernetes watch — це дієслово, яке використовується для відстеження змін обʼєкта в Kubernetes у вигляді потоку. Використовується для ефективного виявлення змін.

Ви можете переглянути довідник API онлайн або прочитати далі, щоб дізнатися про API загалом.

Терміни API Kubernetes

Kubernetes зазвичай використовує загальноприйняту термінологію RESTful для опису концепцій API:

• Тип ресурсу — це назва, що використовується в URL (pods, namespaces, services)
• Усі типи ресурсів мають конкретне представлення (їхню схему обʼєкта), яке називається kind (вид)
• Список екземплярів типу ресурсу називається колекцією
• Окремий екземпляр типу ресурсу називається ресурсом і зазвичай також представляє обʼєкт
• Для деяких типів ресурсів API включає один або більше субресурсів, які представлені як URI-шляхи під ресурсом

Більшість типів ресурсів API Kubernetes є обʼєктами — вони представляють конкретний екземпляр концепції у кластері, як-от Pod або простір імен. Невелика кількість типів ресурсів API є віртуальними, оскільки вони часто представляють операції над обʼєктами, а не самі обʼєкти, такі як перевірка дозволів (використання POST із JSON-кодованим тілом SubjectAccessReview для ресурсу subjectaccessreviews), або субресурс eviction у Pod (використовується для запуску виселення, ініційованого API).

Імена обʼєктів

Усі обʼєкти, які ви можете створити через API, мають унікальне імʼя (name), що дозволяє ідемпотентне створення та отримання, за винятком віртуальних типів ресурсів, які можуть не мати унікальних імен, якщо вони не можуть бути отримані або не залежать від ідемпотентності.

У межах Namespace (простору імен) унікальна ідентичність обʼєкта визначається кортежем з його групи API, ресурсу, простору імен та імені.

• Між групами: Ви можете мати два обʼєкти з однаковим іменем, якщо вони належать до різних груп API (наприклад, apps та example.com).
• Між версіями: Різні версії API (наприклад, v1 та v1beta1) однієї групи та ресурсу представляють ті самі базові дані. Створення обʼєкта з однаковим іменем в іншій версії тієї ж групи призводить до конфлікту імен, оскільки вони мають однакову ідентичність у сховищі.

Деякі обʼєкти не належать до простору імен (наприклад: Nodes), тому їхні імена повинні бути унікальними в межах усього кластера.

Дієслова API

Майже всі типи ресурсів обʼєктів підтримують стандартні 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.

URI ресурсів

Усі типи ресурсів або належать кластеру (/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 — повертає колекцію всіх екземплярів вказаного типу ресурсу в просторі імен NAMESPACE
  • GET /apis/GROUP/VERSION/namespaces/NAMESPACE/RESOURCETYPE/NAME — повертає екземпляр вказаного типу ресурсу з імʼям NAME в просторі імен NAMESPACE

Оскільки простір імен є типом ресурсу кластерного рівня, ви можете отримати перелік («колекцію») всіх просторів імен за допомогою GET /api/v1/namespaces та деталі про конкретний простір імен за допомогою GET /api/v1/namespaces/NAME.

• Субресурс кластерного рівня: GET /apis/GROUP/VERSION/RESOURCETYPE/NAME/SUBRESOURCE
• Субресурс рівня простору імен: GET /apis/GROUP/VERSION/namespaces/NAMESPACE/RESOURCETYPE/NAME/SUBRESOURCE

Підтримувані дієслова для кожного субресурсу будуть відрізнятися залежно від обʼєкта — див. довідник API для отримання додаткової інформації. Немає можливості отримати доступ до субресурсів через декілька ресурсів — зазвичай, якщо це стає необхідним, використовується новий віртуальний тип ресурсу.

HTTP медіатипи

Через 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), оскільки це може негативно вплинути на продуктивність.

Кодування ресурсів у форматі JSON

API Kubernetes типово використовує JSON для кодування тіла HTTP-повідомлень.

Наприклад:

1. Отримати список усіх Podʼів у кластері без вказування бажаного формату

   GET /api/v1/pods
   

   200 OK
   Content-Type: application/json
   
   … JSON encoded collection of Pods (PodList object)
   

2. Створити 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",
     …
   }
   

Ви також можете запитувати в цьому кодуванні таблиці та лише метадані.

Кодування ресурсів у форматі YAML

Kubernetes також підтримує медіатип application/yaml як для запитів, так і для відповідей. YAML можна використовувати для визначення маніфестів Kubernetes та взаємодії з API.

Наприклад:

1. Отримати список усіх Podʼів у кластері у форматі YAML

   GET /api/v1/pods
   Accept: application/yaml
   

   200 OK
   Content-Type: application/yaml
   
   … YAML encoded collection of Pods (PodList object)
   

2. Створити 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

Kubernetes використовує обгортку-конверт для кодування відповідей у форматі Protobuf. Ця обгортка починається з 4-байтового магічного числа, щоб допомогти ідентифікувати вміст на диску або в etcd як Protobuf (на відміну від JSON). За 4-байтовим магічним числом слідує закодоване у форматі Protobuf повідомлення-обгортка, яке описує кодування та тип основного обʼєкта. Усередині повідомлення-обгортки Protobuf дані внутрішнього обʼєкта записуються за допомогою поля raw повідомлення Unknown (дивіться IDL для докладної інформації).

Наприклад:

1. Отримати список усіх 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)
   

2. Створити 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;
  }

Ви також можете запитувати в цьому кодуванні таблиці та лише метадані.

Сумісність із Kubernetes Protobuf

Не всі типи ресурсів API підтримують кодування Kubernetes Protobuf; зокрема, Protobuf недоступний для ресурсів, які визначені як CustomResourceDefinitions або надаються через рівень агрегації.

Як клієнт, якщо вам може знадобитися працювати з типами розширень, слід вказати кілька типів вмісту в заголовку запиту Accept для підтримки резервного переходу на JSON. Наприклад:

Accept: application/vnd.kubernetes.protobuf, application/json

Кодування ресурсів у форматі CBOR

З увімкненою функціональною можливістю 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 і почати знову. Див. Семантика версій ресурсів для отримання детальнішої інформації.

Наприклад:

1. Отримати список усіх Podʼів у вказаному просторі імен.

   GET /api/v1/namespaces/test/pods
   ---
   200 OK
   Content-Type: application/json
   
   {
     "kind": "PodList",
     "apiVersion": "v1",
     "metadata": {"resourceVersion":"10245"},
     "items": [...]
   }
   

2. Починаючи з версії ресурсу 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">

Фрагментовані list і watch

У великих кластерах контролери, які спостерігають за типами ресурсів з високою кардинальністю (наприклад, Pod або Endpoints), можуть споживати значну частину пропускної здатності мережі та CPU, отримуючи та десеріалізуючи повний потік подій, навіть якщо їм потрібна лише підмножина обʼєктів. Фрагментовані list і watch дозволяють горизонтально масштабованим контролерам розподіляти навантаження так, щоб кожна репліка отримувала лише ті події, за які вона відповідає.

Kubernetes 1.37 впроваджує альфа-функцію, яка дозволяє клієнтам запитувати з API-сервера відфільтрований фрагмент обʼєктів, використовуючи розбиття на основі хешування полів метаданих. Щоб використовувати цю функцію, увімкніть на API-сервері функціональну можливість ShardedListAndWatch. Коли її увімкнено, API-сервер фільтрує як відповіді на list, так і потоки подій watch на боці сервера, доставляючи лише ті обʼєкти та події, хешоване значення метаданих яких потрапляє в запитаний діапазон.

Поле shardSelector

Поле ShardSelector у ListOptions приймає вираз на основі CEL з використанням функції shardRange():

shardRange(<field-path>, '<hex-start>', '<hex-end>')

Де:

• <field-path> — це поле метаданих, яке потрібно хешувати, у синтаксисі в стилі CEL з коренем в обʼєкті. Наразі підтримуються такі шляхи:
  • object.metadata.uid
  • object.metadata.namespace
• <hex-start> — включна нижня межа діапазону хешу у вигляді 16-значного шістнадцяткового рядка в нижньому регістрі з префіксом 0x (наприклад, '0x0000000000000000').
• <hex-end> — виключна верхня межа у вигляді шістнадцяткового рядка з префіксом 0x. Максимальне значення — '0x10000000000000000' (2^64).

API-сервер обчислює детермінований 64-бітний хеш FNV-1a вказаного значення поля і повертає лише ті обʼєкти, хеш яких потрапляє в діапазон [start, end). Функція хешування дає однаковий результат для одного й того самого вхідного значення на всіх екземплярах API-сервера, тому фрагментовані запити безпечно використовувати з кількома репліками API-сервера.

Ви можете комбінувати кілька діапазонів за допомогою || (логічне АБО), щоб охопити несуміжні частини простору хешів. Усі діапазони в одному виразі повинні використовувати той самий шлях до поля.

Використання фрагментованих list і watch у контролерах

Контролери зазвичай використовують інформери для отримання списку ресурсів і спостереження за ними. Щоб розподілити навантаження між репліками, кожна репліка вставляє поле 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": [...]
}

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

Якщо 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.

Отримання великих наборів результатів частинами

У великих кластерах отримання колекції деяких типів ресурсів може призвести до дуже великих відповідей, що може вплинути на сервер і клієнта. Наприклад, у кластері можуть бути десятки тисяч 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ʼів за раз, запитуйте ці частини таким чином:

1. Отримати список усіх 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
   }
   

2. Продовжити попередній виклик, отримуючи наступний набір з 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
   }
   

3. Продовжити попередній виклик, отримуючи останні 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

Отримання ресурсів у вигляді таблиць

Коли ви запускаєте 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 для списку.

Наприклад, щоб отримати список усіх 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 для ресурсу, цей процес проходить у два етапи.

1. завершення (finalization)
2. вилучення (removal)

{
  "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 слід залишити не встановленими.

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-запиті.

Ці ситуації такі:

1. Поле не розпізнається, оскільки воно не входить до схеми OpenAPI ресурсу. (Винятком є CRD, які явно обирають не обрізати невідомі поля через x-kubernetes-preserve-unknown-fields).
2. Поле дублюється в обʼєкті.

Валідація нерозпізнаних або дубльованих полів

Починаючи з версії 1.25, нерозпізнані або дубльовані поля в обʼєкті виявляються через валідацію на сервері, коли ви використовуєте HTTP-дієслова, які можуть надсилати дані (POST, PUT та PATCH). Можливі рівні валідації: Ignore, Warn (типово) та Strict.

Ignore

API-сервер успішно обробляє запит так, ніби помилкові поля не були встановлені, відкидаючи всі невідомі та дубльовані поля і жодним чином не повідомляючи про це.

Warn

(Типово) API-сервер успішно обробляє запит і надсилає клієнту попередження. Попередження надсилається за допомогою заголовка відповіді Warning:, додаючи один елемент попередження для кожного невідомого або дубльованого поля. Для отримання додаткової інформації про попередження та API Kubernetes дивіться статтю блогу Warning: Helpful Warnings Ahead.

Strict

API-сервер відхиляє запит з помилкою 400 Bad Request, коли виявляє будь-які невідомі або дубльовані поля. Повідомлення відповіді від API-сервера вказує всі невідомі або дубльовані поля, які виявив API-сервер.

Рівень валідації полів встановлюється параметром запиту fieldValidation.

Інструменти, які надсилають запити на сервер (такі як kubectl), можуть встановлювати власні типові значення, які відрізняються від рівня валідації Warn, що типово використовується API-сервером.

Інструмент kubectl використовує прапорець --validate для встановлення рівня валідації полів. Він приймає значення ignore, warn та strict, а також значення true (еквівалентно strict) і false (еквівалентно ignore). Типове налаштування валідації для kubectl — --validate=true, що означає сувору валідацію полів на боці сервера.

Коли kubectl не може підключитися до API-сервера з валідацією полів (API-сервери до Kubernetes 1.27), він повертається до використання валідації на боці клієнта. Валідацію на боці клієнта буде повністю вилучено в майбутній версії kubectl.

Починаючи з v1.33, Kubernetes (включно з v1.37) пропонує спосіб визначення валідації полів за допомогою декларативних теґів. Це корисно для тих, хто бере участь у розробці самого Kubernetes, а також актуально, якщо ви пишете власний API з використанням бібліотек Kubernetes. Щоб дізнатися більше, див. Декларативна валідація API.

Пробний запуск (dry-run)

Коли ви використовуєте HTTP-дієслова, які можуть змінювати ресурси (POST, PUT, PATCH і DELETE), ви можете надіслати свій запит у режимі пробного запуску (dry run). Режим пробного запуску допомагає оцінити запит на типових етапах обробки запиту (ланцюжок допуску, валідація, конфлікти злиття) аж до збереження обʼєктів у сховищі. Тіло відповіді на запит максимально наближене до відповіді на звичайний запит (без пробного запуску). Kubernetes гарантує, що запити пробного запуску не будуть збережені в сховищі і не матимуть жодних інших побічних ефектів.

Виконання запиту пробного запуску

Пробний запуск активується встановленням параметра запиту dryRun. Цей параметр є рядком, працює як перелік (enum), і єдині прийнятні значення:

[значення не встановлено]

Дозволити побічні ефекти. Ви запитуєте це за допомогою рядка запиту на кшталт ?dryRun або ?dryRun&pretty=true. Відповіддю є остаточний обʼєкт, який було б збережено, або помилка, якщо запит не може бути виконаний.

All

Кожен етап виконується як зазвичай, за винятком кінцевого етапу збереження, де побічним ефектам запобігають.

Коли ви встановлюєте ?dryRun=All, усі відповідні контролери допуску виконуються, контролери допуску з валідацією перевіряють запит після мутації, для PATCH виконується злиття, полям встановлюються типові значення, і проводиться валідація схеми. Зміни не зберігаються в базовому сховищі, але остаточний обʼєкт, який було б збережено, все одно повертається користувачеві разом зі звичайним кодом статусу.

Якщо звичайна версія запиту (без пробного запуску) викликала б контролер допуску, який має побічні ефекти, запит буде відхилено, щоб не ризикувати небажаними побічними ефектами. Усі вбудовані втулки контролю допуску підтримують пробний запуск. Крім того, вебхуки допуску можуть оголосити у своєму обʼєкті конфігурації, що вони не мають побічних ефектів, встановивши поле sideEffects у None.

Ось приклад запиту пробного запуску, який використовує ?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+yaml

YAML для Server Side Apply (специфічне для Kubernetes розширення на основі YAML). Усі документи JSON є дійсним YAML, тому ви також можете надсилати JSON, використовуючи цей медіатип. Дивіться серіалізацію Server Side Apply для отримання додаткової інформації. Для Kubernetes це операція create, якщо обʼєкт не існує, або операція patch, якщо обʼєкт вже існує.

application/json-patch+json

JSON Patch, як визначено в RFC6902. JSON Patch — це послідовність операцій, які виконуються над ресурсом; наприклад, {"op": "add", "path": "/a/b/c", "value": [ "foo", "bar" ]}. Для Kubernetes це операція patch.

patch з використанням application/json-patch+json може містити умови для перевірки узгодженості, що дозволяє операції завершитися невдачею, якщо ці умови не виконуються (наприклад, щоб уникнути втраченого оновлення).

application/merge-patch+json

JSON Merge Patch, як визначено в RFC7386. JSON Merge Patch фактично є частковим представленням ресурсу. Надісланий JSON поєднується з поточним ресурсом для створення нового, після чого новий ресурс зберігається. Для Kubernetes це операція patch.

application/strategic-merge-patch+json

Strategic Merge Patch (специфічне для Kubernetes розширення на основі JSON). Strategic Merge Patch — це власна реалізація JSON Merge Patch. Ви можете використовувати Strategic Merge Patch лише з вбудованими API або з агрегованими API-серверами, які мають спеціальну підтримку для нього. Ви не можете використовувати application/strategic-merge-patch+json з будь-яким API, визначеним за допомогою CustomResourceDefinition.

Примітка:

Механізм Kubernetes server side apply замінив Strategic Merge Patch.

Функція Server Side Apply Kubernetes дозволяє панелі управління відстежувати керовані поля для новостворених обʼєктів. Server Side Apply надає чіткий шаблон для управління конфліктами полів, пропонує операції apply та update на боці сервера і замінює функціональність kubectl apply на боці клієнта.

Для Server-Side Apply Kubernetes обробляє запит як create, якщо обʼєкт ще не існує, і як patch в іншому разі. Для інших запитів, які використовують PATCH на рівні HTTP, логічною операцією Kubernetes завжди є patch.

Дивіться Server Side Apply для отримання додаткової інформації.

Вибір механізму оновлення

HTTP PUT для заміни наявного ресурсу

Операція update (HTTP PUT) проста в реалізації та гнучка, але має недоліки:

• Потрібно обробляти конфлікти, коли resourceVersion обʼєкта змінюється між моментом його читання вашим клієнтом і спробою записати його назад. Kubernetes завжди виявляє конфлікт, але вам як авторові клієнта потрібно реалізувати повторні спроби.
• Ви можете випадково відкинути поля, якщо декодуєте обʼєкт локально (наприклад, використовуючи client-go, ви можете отримати поля, які ваш клієнт не вміє обробляти, а потім відкинути їх під час оновлення).
• Якщо за обʼєкт відбувається велика конкуренція (навіть за поле або набір полів, які ви не намагаєтеся редагувати), у вас можуть виникнути проблеми з надсиланням оновлення. Проблема гостріша для великих обʼєктів та для обʼєктів з багатьма полями.

HTTP PATCH з використанням JSON Patch

Оновлення через patch корисне, оскільки:

• Оскільки ви надсилаєте лише різницю, вам потрібно надсилати менше даних у запиті PATCH.
• Ви можете робити зміни, які ґрунтуються на наявних значеннях, наприклад, копіювати значення певного поля в анотацію.
• На відміну від update (HTTP PUT), ваші зміни можуть відбутися відразу, навіть якщо часто змінюються неповʼязані поля: зазвичай вам не потрібно повторювати спроби.
  • Вам все ще може знадобитися вказати resourceVersion (щоб відповідати наявному обʼєкту), якщо ви хочете бути особливо обережними, щоб уникнути втрачених оновлень
  • Все ж є доброю практикою додати певну логіку повторних спроб на випадок помилок.
• Ви можете використовувати тестові умови, щоб ретельно сформулювати конкретні умови оновлення. Наприклад, ви можете збільшити лічильник без його читання, якщо наявне значення відповідає вашим очікуванням. Ви можете зробити це без ризику втратити оновлення, навіть якщо обʼєкт змінився іншим чином з моменту вашого останнього запису до нього. (Якщо тестова умова не виконається, ви можете повернутися до читання поточного значення, а потім записати змінене число).

Проте:

• Вам потрібно більше локальної (клієнтської) логіки для створення patch; дуже допомагає, якщо у вас є бібліотечна реалізація JSON Patch або навіть для створення JSON Patch спеціально для Kubernetes.
• Як автору клієнтського програмного забезпечення, вам потрібно бути обережним при створенні patch (тіла HTTP-запиту), щоб не відкинути поля (порядок операцій має значення).

HTTP PATCH з використанням Server-Side Apply

Server-Side Apply має деякі очевидні переваги:

• Один цикл запит-відповідь: рідко потрібно спочатку робити запит GET.
  • і ви все одно можете виявляти конфлікти для неочікуваних змін
  • у вас є можливість примусово перезаписати конфлікт, якщо це доречно
• Клієнтські реалізації легко створювати.
• Ви отримуєте атомарну операцію створення або оновлення без додаткових зусиль (аналогічно UPSERT у деяких діалектах SQL).

Проте:

• Server-Side Apply зовсім не працює для змін полів, які залежать від поточного значення обʼєкта.
• Ви можете застосовувати оновлення лише до обʼєктів. Деякі ресурси в HTTP API Kubernetes не є обʼєктами (вони не мають поля .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+, щоб пройти тести на відповідність.

Щоб порівняти два рядки версій ресурсів:

Переконайтеся, що вони відповідають таким вимогам:

• Обидві версії ресурсів повинні належати до одного типу ресурсів, як описано вище
• Обидві повинні починатися з цифри 1-9 і містити лише цифри 0-9
• Версії ресурсів порівнюються як десяткові цілі числа довільної розрядності

Щоб порівняти їх, не покладаючись на фіксовану розрядність, можна порівнювати їх як рядки. Не слід припускати, що розрядність має якесь фіксоване значення.

Натомість можна використовувати лексикографічне порівняння, як показано тут:

• Якщо вони мають різну довжину, більшою є довша (наприклад, "123" > "23")
• Якщо вони мають однакову довжину, більшою є лексикографічно більша (наприклад, "234" > "123")

Деякі приклади порівнянь версій ресурсів, які повинні працювати:

• "2345678901234567890123456789012345678901" > "345678901234567890123456789012345678901"
• "345678901234567890123456789012345678901" == "345678901234567890123456789012345678901"
• "345678901234567890123456789012345678900" < "345678901234567890123456789012345678901"

Для виконання цього порівняння в 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

Для get та list семантика resourceVersion така:

get:

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:

Значення семантики get та list таке:

Будь-яка

Повернути дані на будь-якій версії ресурсу. Перевага надається найновішій доступній версії ресурсу, але сувора узгодженість не потрібна; можуть бути надані дані на будь-якій версії ресурсу. Запит може повернути дані на значно старішій версії ресурсу, ніж та, яку клієнт спостерігав раніше, особливо в конфігураціях високої доступності, через розділення мережі або застарілі кеші. Клієнти, які не можуть цього допустити, не повинні використовувати цю семантику. Завжди обслуговується з кешу спостереження, що покращує продуктивність і зменшує навантаження на etcd.

Найновіша

Повернути дані на найновішій версії ресурсу. Повернуті дані повинні бути узгодженими (докладніше: обслуговуються з etcd за допомогою кворумного читання). Для etcd v3.4.31+ та v3.5.13+ Kubernetes 1.37 обслуговує читання «найновіших» даних з кешу спостереження: внутрішнього сховища в памʼяті всередині API-сервера, яке кешує та віддзеркалює стан даних, збережених в etcd. Kubernetes запитує сповіщення про прогрес, щоб підтримувати узгодженість кешу з шаром постійного зберігання etcd. Версії Kubernetes з v1.28 до v1.30 також підтримували цю функцію, але як альфа-функція вона не рекомендувалася для промислової експлуатації і не була типово увімкненою до випуску v1.31.

Не старша ніж

Повернути дані, які є щонайменше такими ж новими, як надана 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.

Коли використовується resourceVersionMatch=NotOlderThan і встановлено limit, клієнти повинні обробляти відповіді HTTP 410 Gone. Наприклад, клієнт може повторити спробу з новішою resourceVersion або повернутися до resourceVersion="".

Коли використовується resourceVersionMatch=Exact і limit не встановлено, клієнти повинні перевіряти, що .metadata.resourceVersion колекції збігається із запитаною resourceVersion, і обробляти випадок, коли це не так. Наприклад, клієнт може повернутися до запиту зі встановленим limit.

Семантика для watch

Для watch семантика версії ресурсу така:

watch:

Значення цієї семантики watch таке:

Отримати стан і почати з будь-якої

Почати watch з будь-якої версії ресурсу; перевага надається найновішій доступній версії ресурсу, але це не обовʼязково. Дозволено будь-яку початкову версію ресурсу. watch може початися з набагато старішої версії ресурсу, ніж та, яку клієнт спостерігав раніше, особливо в конфігураціях високої доступності, через розділення мережі або застарілі кеші. Клієнти, які не можуть допустити такого видимого відмотування назад, не повинні починати watch з цією семантикою. Для встановлення початкового стану watch починається із синтетичних подій "Added" для всіх екземплярів ресурсів, які існують на початковій версії ресурсу. Усі подальші події спостереження стосуються всіх змін, що сталися після версії ресурсу, з якої почався watch.

Увага:

watches, ініціалізовані таким чином, можуть повертати довільно застарілі дані. Будь ласка, ознайомтеся з цією семантикою перед використанням і надавайте перевагу іншим семантикам, де це можливо.

Отримати стан і почати з найновішої

Почати watch з найновішої версії ресурсу, яка повинна бути узгодженою (докладніше: обслуговується з etcd за допомогою кворумного читання). Для встановлення початкового стану watch починається із синтетичних подій "Added" для всіх екземплярів ресурсів, які існують на початковій версії ресурсу. Усі подальші події спостереження стосуються всіх змін, що сталися після версії ресурсу, з якої почався watch.

Почати з точної

Почати watch з точної версії ресурсу. Події спостереження стосуються всіх змін після наданої версії ресурсу. На відміну від «Отримати стан і почати з найновішої» та «Отримати стан і почати з будь-якої», watch не починається із синтетичних подій "Added" для наданої версії ресурсу. Вважається, що клієнт вже має початковий стан на початковій версії ресурсу, оскільки клієнт надав цю версію ресурсу.

Відповіді "410 Gone"

Сервери не зобовʼязані надавати всі старіші версії ресурсів і можуть повернути код статусу 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 застосовує два захисні механізми:

• Захист готовності під час запуску: Під час запуску API-сервер затримує повідомлення про готовність (/readyz), доки кожен зареєстрований кеш спостереження не завершить свою початкову синхронізацію з etcd. Це запобігає передчасному спрямуванню клієнтського трафіку балансувальниками навантаження на API-сервер, усуваючи масові одночасні читання під час запуску (thundering herd), які інакше оминали б неготовий кеш і потрапляли б безпосередньо в etcd.
• Відхилення запитів під час ініціалізації кешу: Якщо запити надходять, поки кеш спостереження для типу ресурсу не ініціалізовано — наприклад, під час завантаження сервера (до готовності) або після повторної синхронізації чи відʼєднання кешу під час роботи, — API-сервер не дає дорогим запитам перевантажити 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 та реалізуючи експоненційну затримку повторних спроб.

2.2 - Загальна мова виразів у Kubernetes

Загальна мова виразів (Common Expression Language, CEL) використовується в API Kubernetes для оголошення правил валідації, політик та інших обмежень чи умов.

Вирази CEL оцінюються безпосередньо на API-сервері, що робить CEL зручним альтернативним рішенням для зовнішніх механізмів, таких як вебхуки, для багатьох випадків розширення функціональності. Ваші вирази CEL продовжують виконуватись, поки компонент API-сервера у складі панелі управління залишається доступним.

Огляд мови

Мова CEL має простий синтаксис, який схожий на вирази в C, C++, Java, JavaScript і Go.

CEL була розроблена для вбудовування в застосунки. Кожна "програма" CEL — це один вираз, який обраховується до одного значення. Вирази CEL зазвичай є короткими "однорядковими виразами", що добре вбудовуються в рядкові поля ресурсів API Kubernetes.

Вхідні дані для програми CEL — це "змінні". Кожне поле API Kubernetes, яке містить CEL, декларує в документації API, які змінні доступні для використання для цього поля. Наприклад, у полі x-kubernetes-validations[i].rules у CustomResourceDefinitions доступні змінні self і oldSelf, що відносяться до попереднього та поточного стану даних власного ресурсу користувача, які потрібно перевірити за допомогою виразу CEL. Інші поля API Kubernetes можуть оголошувати різні змінні. Дивіться документацію API для полів API, щоб дізнатися, які змінні доступні для цього поля.

Приклади виразів CEL:

Опції CEL, можливості мови та бібліотеки

CEL налаштовується з наступними опціями, бібліотеками та можливостями мови, введеними у зазначених версіях Kubernetes:

Функції CEL, можливості та налаштування мови підтримують відкат панелі управління Kubernetes. Наприклад, опційні значення CEL були введені у Kubernetes 1.29, і лише API-сервери цієї версії або новіші прийматимуть запити на запис виразів CEL, які використовують опційні значення CEL. Однак, коли кластер відкочується до версії Kubernetes 1.28, вирази CEL, що використовують "опційні значення CEL", які вже збережені в ресурсах API, продовжуватимуть правильно оцінюватись.

Бібліотеки CEL Kubernetes

Крім спільнотних бібліотек CEL, Kubernetes включає бібліотеки CEL, які доступні у всіх місцях використання CEL в Kubernetes.

Бібліотека списків Kubernetes

Бібліотека списків включає indexOf та lastIndexOf, які працюють аналогічно функціям рядків з такими самими назвами. Ці функції повертають перший або останній індекс елемента у списку.

Бібліотека списків також включає min, max та sum. Сума підтримується для всіх типів чисел, а також для типу тривалості. Мінімум та максимум підтримуються для всіх типів, що можна порівняти.

Також надається функція isSorted для зручності та підтримується для всіх типів, які можна порівняти.

Приклади:

Для отримання додаткової інформації дивіться бібліотеку списків Kubernetes godoc.

Бібліотека регулярних виразів Kubernetes

Крім функції matches, наданої стандартною бібліотекою CEL, бібліотека регулярних виразів надає функції find та findAll, що дозволяють виконувати значно ширший спектр операцій з регулярними виразами.

Приклади:

Для отримання додаткової інформації дивіться бібліотеку регулярних виразів Kubernetes godoc.

Бібліотека URL Kubernetes

Для спрощення та безпечної обробки URL надані наступні функції:

• isURL(string) перевіряє, чи є рядок дійсним URL відповідно до пакета net/url у Go. Рядок повинен бути абсолютним URL.
• url(string) URL конвертує рядок в URL або викликає помилку, якщо рядок не є дійсним URL.

Після розбору за допомогою функції url, отриманий обʼєкт URL має наступні методи доступу: getScheme, getHost, getHostname, getPort, getEscapedPath та getQuery.

Приклади:

Для отримання додаткової інформації дивіться бібліотеку URL Kubernetes godoc.

Бібліотека IP-адрес Kubernetes

Щоб зробити обробку IP-адрес простішою і безпечнішою, були додані наступні функції:

• isIP(string) перевіряє, чи є рядок дійсною IP-адресою.
• ip(string) IP конвертує рядок в обʼєкт IP-адреси або викликає помилку, якщо рядок не є дійсною IP-адресою.

Для обох функцій IP-адреса повинна бути адресою IPv4 або IPv6. Зіставлені з IPv4 IPv6-адреси (наприклад, ::ffff:1.2.3.4) не допускаються. IP-адреси з зонами (наприклад, fe80::1%eth0) не допускаються. Початкові нулі в октетах IPv4-адрес не допускаються.

Після розбору за допомогою функції ip отриманий обʼєкт IP має наступну бібліотеку функцій-членів:

Приклади:

Докладнішу інформацію наведено у Бібліотеці IP-адрес Kubernetes godoc.

Бібліотека CIDR Kubernetes

CIDR надає розширення бібліотеки функцій CEL для розбору нотації CIDR.

cidr

Конвертує рядок у нотації CIDR в представлення мережевої адреси або викликає помилку, якщо рядок не є дійсною нотацією CIDR. CIDR повинен бути підмережею IPv4 або IPv6 з маскою. Ведучі нулі в октетах IPv4-адреси не дозволяються. IPv4-адреси, що відображаються в IPv6 (наприклад, ::ffff:1.2.3.4/24), не дозволяються.

cidr(<string>) <CIDR>

Приклади:

isCIDR

Повертає true, якщо рядок є дійсним представленням підмережі з маскою в нотації CIDR. CIDR повинен бути підмережею IPv4 або IPv6 з маскою. Ведучі нулі в октетах IPv4-адреси не дозволяються. IPv4-адреси, що відображаються в IPv6 (наприклад, ::ffff:1.2.3.4/24), не дозволяються.

isCIDR(<string>) <bool>

Приклади:

containsIP / containsCIDR / ip / masked / prefixLength

• containsIP: Повертає true, якщо CIDR містить задану IP-адресу. IP-адреса має бути IPv4 або IPv6. Може приймати як аргумент рядок або IP-адресу.

• containsCIDR: Повертає true, якщо CIDR містить заданий CIDR. CIDR повинен бути підмережею IPv4 або IPv6 з маскою. Може приймати як аргумент рядок або CIDR.

• ip: Повертає представлення IP-адреси CIDR.

• masked: Повертає представлення CIDR мережевої адреси з маскованим префіксом. Це можна використовувати для повернення канонічної форми мережі CIDR.

• prefixLength: Повертає довжину префікса CIDR в бітах. Це кількість бітів у масці.

Приклади:

Докладнішу інформацію можна знайти у Бібліотеці Kubernetes CIDR godoc.

Бібліотека авторизатора Kubernetes

Для виразів CEL в API, де доступна змінна типу Authorizer, авторизатор може використовуватися для виконання перевірок авторизації для принципала (автентифікованого користувача) запиту.

Перевірки ресурсів API виконуються наступним чином:

1. Вкажіть групу та ресурс для перевірки: Authorizer.group(string).resource(string) ResourceCheck
2. Опційно викличте будь-яку комбінацію наступних функцій побудови для подальшого обмеження перевірки авторизації. Зверніть увагу, що ці функції повертають тип отримувача та можуть бути зʼєднані ланцюгом:
   • ResourceCheck.subresource(string) ResourceCheck
   • ResourceCheck.namespace(string) ResourceCheck
   • ResourceCheck.name(string) ResourceCheck
3. Викличте ResourceCheck.check(verb string) Decision, щоб виконати перевірку авторизації.
4. Викличте allowed() bool або reason() string, щоб переглянути результат перевірки авторизації.

Авторизація для нересурсних запитів виконується так:

1. Вкажіть лише шлях: Authorizer.path(string) PathCheck
2. Викличте PathCheck.check(httpVerb string) Decision, щоб виконати перевірку авторизації.
3. Викличте allowed() bool або reason() string, щоб переглянути результат перевірки авторизації.

Для виконання перевірки авторизації для службового облікового запису:

• Authorizer.serviceAccount(namespace string, name string) Authorizer

Для виразів CEL в API, де доступна змінна типу Authorizer, селектори полів і міток можуть бути включені в перевірки авторизації.

Для отримання додаткової інформації дивіться бібліотеку Kubernetes Authz та бібліотеку Kubernetes AuthzSelectors godoc.

Бібліотека форматів Kubernetes

Бібліотека format надає функції для перевірки поширених форматів рядків у Kubernetes. Це може бути корисно у messageExpression правил валідації для надання більш конкретних повідомлень про помилки.

Бібліотека надає функції format() для кожного іменованого формату, а також загальну функцію format.named().

• format.named(string) → ?Format: Повертає обʼєкт Format для заданого імені формату, якщо він існує. Інакше повертає optional.none.
• format.<formatName>() -> Format: Також доступні зручні функції для всіх іменованих форматів. Наприклад, format.dns1123Label() повертає обʼєкт Format для міток DNS-1123.
• <Format>.validate(string) -> list<string>?: Перевіряє рядок на відповідність формату. Повертає optional.none, якщо рядок валідний, інакше — optional, що містить список рядків з помилками валідації.

Доступні формати:

Підтримуються наступні назви форматів:

Приклади:

Докладніше: Бібліотека форматів Kubernetes godoc.

Бібліотека кількостей Kubernetes

У Kubernetes 1.28 додана підтримка обробки рядків кількості (наприклад, 1.5G, 512k, 20Mi).

• isQuantity(string) перевіряє, чи є рядок дійсною кількістю (Quantity) відповідно до resource.Quantity у Kubernetes.
• quantity(string) Quantity конвертує рядок у кількість або викликає помилку, якщо рядок не є дійсною кількістю.

Після розбору за допомогою функції quantity отриманий обʼєкт Quantity має таку бібліотеку функцій-членів:

Приклади:

Бібліотека semver Kubernetes

У Kubernetes v1.34 додано підтримку розбору та порівняння рядків, що відповідають специфікації Semantic Versioning 2.0.0. Докладніше про прийняті патерни дивіться semver.org.

• isSemver(string) перевіряє, чи є рядок валідною семантичною версією.
• semver(string) конвертує рядок у обʼєкт Semver або повертає помилку.

Додатковий булевий аргумент normalize можна передати у isSemver та semver. Якщо true, нормалізація прибирає префікс "v", додає 0 для minor та patch, якщо вказано лише major або major.minor, і прибирає ведучі нулі.

Після розбору через функцію semver отриманий обʼєкт Semver має такі функції-члени:

Приклади:

Докладніше: Бібліотека semver Kubernetes godoc.

Перевірка типів

CEL — це мова з поступовою типізацією.

Деякі поля API Kubernetes містять вирази CEL з повною перевіркою типів. Наприклад, правила валідації CustomResourceDefinitions проходять повну перевірку типів.

Деякі поля API Kubernetes містять вирази CEL з частковою перевіркою типів. Вираз з частковою перевіркою типів — це вираз, у якому деякі змінні статично типізовані, а інші — динамічно типізовані. Наприклад, у виразах CEL ValidatingAdmissionPolicies змінна request типізована, але змінна object динамічно типізована. У звʼязку з цим вираз, що містить request.namex, не пройде перевірку типів, оскільки поле namex не визначене. Однак object.namex пройде перевірку типів навіть тоді, коли поле namex не визначене для видів ресурсів, на які посилається object, оскільки object динамічно типізований.

Макрос has() у CEL можна використовувати у виразах CEL для перевірки наявності поля змінної з динамічною типізацією перед спробою отримати доступ до значення цього поля. Наприклад:

has(object.namex) ? object.namex == 'special' : request.name == 'special'

Використовуйте has() для перевірки наявності поля. Не використовуйте has() для перевірки наявності ключа в map. Наприклад, не пишіть has(object.metadata.labels['example.com/environment']). Для перевірки ключів у map використовуйте оператор in. Наприклад:

has(object.metadata.labels) && 'example.com/environment' in object.metadata.labels

Цей вираз перевіряє, що metadata.labels присутній перед перевіркою наявності ключа example.com/environment у map.

Інтеграція системи типів

Також дивіться: Типи CEL, Типи OpenAPI, Структурні схеми Kubernetes.

Порівняння рівності для масивів з x-kubernetes-list-type типу set або map ігнорує порядок елементів. Наприклад, [1, 2] == [2, 1], якщо масиви представляють значення Kubernetes set.

Конкатенація для масивів з x-kubernetes-list-type використовує семантику типу списку:

set

X + Y виконує обʼєднання, за якого позиції всіх елементів у X у масиві зберігаються, а елементи в Y, що не перетинаються, додаються в кінець зі збереженням їх часткового порядку.

map

X + Y виконує злиття, за якого позиції всіх ключів у X у масиві зберігаються, але значення перезаписуються значеннями з Y, коли множини ключів X і Y перетинаються. Елементи Y з ключами, що не перетинаються, додаються в кінець зі збереженням їх часткового порядку.

Екранування

Тільки імена властивостей ресурсів Kubernetes форми [a-zA-Z_.-/][a-zA-Z0-9_.-/]* доступні з CEL. Доступні імена властивостей екрануються згідно з наступними правилами при доступі у виразі:

Коли ви екрануєте будь-яке з ЗАРЕЗЕРВОВАНИХ ключових слів CEL, збіг повинен точно відповідати імені властивості та використовувати екранування з підкресленням (наприклад, int у слові sprint не буде екрановано, і це не буде необхідно).

Приклади екранування:

Обмеження ресурсів

CEL не є Тюрінг-повною мовою і пропонує різноманітні засоби безпеки для промислової експлуатації, що обмежують час виконання. Функції обмеження ресурсів CEL забезпечують зворотний звʼязок розробникам щодо складності виразів та допомагають захистити API-сервер від надмірного споживання ресурсів під час обчислення. Функції обмеження ресурсів CEL використовуються для запобігання надмірному споживанню ресурсів API-сервера під час обчислення CEL.

Ключовим елементом функцій обмеження ресурсів є одиниця вартості, яку CEL визначає як спосіб відстеження використання CPU. Одиниці вартості незалежні від системного навантаження та апаратного забезпечення. Одиниці вартості також є детермінованими; для будь-якого заданого виразу CEL та вхідних даних обчислення виразу інтерпретатором CEL завжди призведе до однакової вартості.

Багато з основних операцій CEL мають фіксовані витрати. Найпростіші операції, такі як порівняння (наприклад, <), мають вартість 1. Деякі мають вищу фіксовану вартість, наприклад, оголошення літералів списку мають фіксовану базову вартість 40 одиниць вартості.

Виклики функцій, реалізованих у рідному коді, оцінюються на основі часової складності операції. Наприклад, операції, що використовують регулярні вирази, такі як match та find, оцінюються з використанням приблизної вартості length(regexString)*length(inputString). Приблизна вартість відображає найгірший випадок часової складності реалізації RE2 в Go.

Бюджет вартості під час виконання

Усі вирази CEL, які обчислює Kubernetes, обмежені бюджетом вартості під час виконання. Бюджет вартості під час виконання — це оцінка фактичного використання CPU, що обчислюється шляхом інкрементування лічильника одиниць вартості під час інтерпретації виразу CEL. Якщо інтерпретатор CEL виконає занадто багато інструкцій, бюджет вартості під час виконання буде перевищено, виконання виразу буде зупинено і результатом стане помилка.

Деякі ресурси Kubernetes визначають додатковий бюджет вартості під час виконання, який обмежує виконання декількох виразів. Якщо загальна вартість виразів перевищує бюджет, виконання виразів буде зупинено і результатом стане помилка. Наприклад, валідація власного ресурсу користувача має бюджет вартості під час виконання на одну валідацію для всіх правил валідації, які обчислюються для валідації власного ресурсу.

Обмеження оціночної вартості

Для деяких ресурсів Kubernetes API-сервер також може перевірити, чи не буде найгірший випадок оціненого часу виконання виразів CEL надто дорогим для виконання. Якщо так, API-сервер запобігає записуванню виразу CEL у ресурси API, відхиляючи операції створення або оновлення, що містять вираз CEL для ресурсів API. Ця функція пропонує сильнішу гарантію, що вирази CEL, записані у ресурс API, будуть обчислені під час виконання без перевищення бюджету вартості під час виконання.

3 - Керування доступом до API

Вступ до того, як Kubernetes реалізує доступ до API та керує ним, дивіться в Контроль доступу до API Kubernetes.

Довідкова документація:

• Автентифікація
  • Автентифікація за допомогою Bootstrap-токенів
• Контролери допуску
  • Динамічний контроль допуску
  • Контроль допуску на основі маніфесту
• Авторизація
  • Контроль доступу на основі ролей
  • Контроль доступу на основі атрибутів
  • Авторизація вузлів
  • Авторизація за допомогою вебхуків
• Запити на підпис сертифікатів
  • включно зі схваленням CSR та підписуванням сертифікатів
• Службові облікові записи
  • Посібник розробника
  • Адміністрування
• Автентифікація та авторизація kubelet
  • включно з TLS bootstrapping kubelet

3.1 - Авторизація

Авторизація в Kubernetes відбувається після автентифікації. Зазвичай клієнт, що робить запит, має бути автентифікований (увійти в систему), перш ніж його запит може бути дозволений; однак, Kubernetes також дозволяє анонімні запити за деяких обставин.

Для огляду того, як авторизація вписується в ширший контекст контролю доступу до API, читайте Контроль доступу до API Kubernetes.

Вердикти авторизації

Авторизація запитів до API в Kubernetes відбувається всередині API-сервера. API-сервер оцінює всі атрибути запиту щодо всіх політик, потенційно також звертаючись до зовнішніх сервісів, і потім дозволяє або відхиляє запит.

Усі частини запиту до API повинні бути дозволені деяким механізмом авторизації, щоб він міг продовжити виконання. Іншими словами: типово доступ заборонений.

Коли налаштовано кілька модулів авторизації, кожен перевіряється по черзі. Якщо будь-який авторизатор схвалює або відхиляє запит, це рішення негайно повертається і жоден інший авторизатор не перевіряється. Якщо всі модулі не мають думки щодо запиту, то запит відхиляється. Загальний вердикт "відхилено" означає, що API-сервер відхиляє запит і відповідає зі статусом HTTP 403 (Forbidden).

Атрибути запиту, що використовуються для авторизації

Kubernetes розглядає тільки наступні атрибути запиту до API:

• user — Рядок user, наданий під час автентифікації.
• group — Список імен груп, до яких належить автентифікований користувач.
• extra — Map довільних рядкових ключів з рядковими значеннями, надана шаром автентифікації.
• API — Вказує, чи є запит запитом на ресурс API.
• Request path — Шлях до різних нересурсних точок доступу, таких як /api або /healthz.
• API request verb — Дієслова API, такі як get, list, create, update, patch, watch, delete і deletecollection, використовуються для запитів до ресурсів. Щоб визначити дієслово запиту для точки доступу API ресурсу, дивіться дієслова запитів та авторизація.
• HTTP request verb — Методи HTTP в нижньому регістрі, такі як get, post, put і delete, використовуються для нересурсних запитів.
• Resource — Ідентифікатор або імʼя ресурсу, до якого здійснюється доступ (тільки для запитів до ресурсів). Для запитів до ресурсів, що використовують дієслова get, update, patch і delete, ви повинні надати імʼя ресурсу.
• Subresource — Субресурс, до якого здійснюється доступ (тільки для запитів до ресурсів). Це може бути стандартний субресурс (наприклад, status або scale) або синтетичний субресурс, який використовується для детальної авторизації.
• Namespace — Простір імен обʼєкта, до якого здійснюється доступ (тільки для запитів до ресурсів у просторі імен).
• API group — Група API, до якої здійснюється доступ (тільки для запитів до ресурсів). Порожній рядок позначає основну групу API.

Дієслова запиту та авторизація

Нересурсні запити

Запити до точок доступу, відмінних від /api/v1/... або /apis/<group>/<version>/..., вважаються нересурсними запитами та використовують метод HTTP запиту в нижньому регістрі як дієслово. Наприклад, виконання запиту GET за допомогою HTTP до точок доступу, таких як /api або /healthz, буде використовувати get як дієслово.

Ресурсні запити

Щоб визначити дієслово запиту для точки доступу API ресурсу, Kubernetes зіставляє використаний HTTP-метод із дієсловом і враховує, чи діє запит на окремий ресурс чи на колекцію ресурсів:

Іноді Kubernetes перевіряє авторизацію для додаткових дозволів, використовуючи спеціалізовані дієслова. Наприклад:

• Особливі випадки автентифікації
  • Дієслово impersonate для users, groups і serviceaccounts в основній групі API, та userextras у групі API authentication.k8s.io.
• Авторизація CertificateSigningRequests
  • Дієслово approve для CertificateSigningRequests, та update для змін наявних схвалень
• RBAC
  • Дієслова bind та escalate для ресурсів roles та clusterroles у групі API rbac.authorization.k8s.io.
• Динамічне виділення ресурсів (DRA)
  • Синтетичні субресурси, такі як resourceclaims/binding та resourceclaims/driver у групі API resource.k8s.io.
  • Дієслова, що враховують вузол, такі як associated-node:update, associated-node:patch, arbitrary-node:update та arbitrary-node:patch, для оновлень resourceclaims/status драйверами DRA.
• Примусове видалення пошкоджених ресурсів
  • Дієслово unsafe-delete-ignore-read-errors для ресурсу, яке перевіряється додатково до дієслова delete.

Контекст авторизації

Kubernetes очікує атрибути, які є загальними для запитів до REST API. Це означає, що авторизація в Kubernetes працює з наявними системами контролю доступу на рівні організації або хмарного провайдера, які можуть обробляти інші API, крім API Kubernetes.

Режими авторизації

API-сервер Kubernetes може авторизувати запит, використовуючи один з декількох режимів авторизації:

AlwaysAllow

Цей режим дозволяє всі запити, що несе ризики для безпеки. Використовуйте цей режим авторизації тільки якщо вам не потрібна авторизація для ваших запитів до API (наприклад, для тестування).

AlwaysDeny

Цей режим блокує всі запити. Використовуйте цей режим авторизації тільки для тестування.

ABAC (контроль доступу на основі атрибутів)

Режим ABAC в Kubernetes визначає парадигму управління доступом, згідно з якою права доступу надаються користувачам за допомогою політик, які обʼєднують атрибути разом. Політики можуть використовувати будь-який тип атрибутів (атрибути користувача, атрибути ресурсу, обʼєкта, середовища тощо).

RBAC (контроль доступу на основі ролей)

Kubernetes RBAC — це метод регулювання доступу до компʼютерних або мережевих ресурсів на основі ролей окремих користувачів в організації. У цьому контексті доступ — це можливість окремого користувача виконувати певне завдання, наприклад, переглядати, створювати або змінювати файл.
В цьому режимі Kubernetes використовує групу API rbac.authorization.k8s.io для прийняття рішень щодо авторизації, що дозволяє вам динамічно налаштовувати політики дозволів через API Kubernetes.

Node

Спеціальний режим авторизації, який надає дозволи для kubeletʼів на основі Podʼів, запланованих для запуску на них. Щоб дізнатися більше про режим авторизації Node, див. Авторизація вузлів.

Webhook

Режим вебхука Kubernetes для авторизації робить синхронний HTTP-виклик, блокуючи запит до тих пір, поки віддалений HTTP-сервіс не відповість на нього. Ви можете написати власне програмне забезпечення для обробки виклику або використовувати рішення з екосистеми.

Група system:masters

Група system:masters є вбудованою групою Kubernetes, яка надає необмежений доступ до API-сервера. Будь-який користувач, призначений до цієї групи, має повні привілеї адміністратора кластера, обходячи будь-які обмеження авторизації, що накладаються механізмами RBAC або Webhook. Не додавайте користувачів до цієї групи. Якщо вам потрібно надати користувачеві права cluster-admin, ви можете створити ClusterRoleBinding до вбудованої ClusterRole cluster-admin.

Конфігурація режиму авторизації

Ви можете налаштувати ланцюжок авторизаторів API-сервера Kubernetes, використовуючи або лише конфігураційний файл, або аргументи командного рядка.

Ви повинні вибрати один з двох підходів до конфігурації: одночасно задавати шлях --authorization-config і налаштовувати вебхук авторизації за допомогою аргументів командного рядка --authorization-mode та --authorization-webhook-* не дозволяється. Якщо ви спробуєте це зробити, API-сервер повідомить про помилку під час запуску та одразу завершить роботу.

Налаштування API-сервера за допомогою конфігураційного файлу авторизації

Kubernetes дозволяє налаштовувати ланцюжки авторизації, які можуть включати декілька вебхуків. Елементи авторизації в цьому ланцюжку можуть мати чітко визначені параметри, які перевіряють запити в певному порядку, пропонуючи вам тонке налаштування, наприклад, явну відмову (Deny) у разі збоїв.

Підхід з використанням конфігураційного файлу навіть дозволяє вам вказувати правила CEL для попередньої фільтрації запитів перед їх відправленням до вебхуків, допомагаючи вам уникнути непотрібних викликів. API-сервер також автоматично перезавантажує ланцюжок авторизаторів при зміні конфігураційного файлу.

Ви вказуєте шлях до конфігурації авторизації за допомогою аргументу командного рядка --authorization-config.

Якщо ви хочете використовувати аргументи командного рядка замість конфігураційного файлу, це також є дійсним і підтримуваним підходом. Деякі можливості авторизації (наприклад: кілька вебхуків, політика обробки збоїв вебхука та правила попередньої фільтрації) доступні тільки при використанні конфігураційного файлу авторизації.

Приклад конфігурації

---
#
# НЕ ВИКОРИСТОВУЙТЕ КОНФІГУРАЦІЮ ТАК, ЯК ВОНА Є. ЦЕ ПРИКЛАД.
#
apiVersion: apiserver.config.k8s.io/v1
kind: AuthorizationConfiguration
authorizers:
  - type: Webhook
    # Назва, що використовується для опису авторизатора
    # Це явно використовується в механізмі моніторингу для метрик
    # Примітка:
    #   - Перевірка цього поля схожа на перевірку міток K8s на сьогодні.
    # Обовʼязково, немає типового значення
    name: webhook
    webhook:
      # Тривалість кешування відповідей 'authorized' від вебхука
      # авторизатора.
      # Те саме, що і встановлення прапорця `--authorization-webhook-cache-authorized-ttl`
      # Типово: 5m0s
      authorizedTTL: 30s
      # Якщо встановлено в false, відповіді 'authorized' від вебхука не кешуються
      # і вказаний authorizedTTL ігнорується/не має ефекту.
      # Те саме, що і встановлення прапорця `--authorization-webhook-cache-authorized-ttl` в `0`.
      # Примітка: Встановлення authorizedTTL в `0` призводить до використання його типового значення.
      # Типово: true
      cacheAuthorizedRequests: true
      # Тривалість кешування відповідей 'unauthorized' від вебхука
      # авторизатора.
      # Те саме, що і встановлення прапорця `--authorization-webhook-cache-unauthorized-ttl`
      # Типово: 30s
      unauthorizedTTL: 30s
      # Якщо встановлено в false, відповіді 'unauthorized' від вебхука не кешуються
      # і вказаний unauthorizedTTL ігнорується/не має ефекту.
      # Те саме, що і встановлення прапорця `--authorization-webhook-cache-unauthorized-ttl` в `0`.
      # Примітка: Встановлення unauthorizedTTL в `0` призводить до використання його типового значення.
      # Типово: true
      cacheUnauthorizedRequests: true
      # Тайм-аут для запиту вебхука
      # Максимально допустимий: 30s.
      # Обовʼязково, немає типового значення.
      timeout: 3s
      # Версія API SubjectAccessReview з authorization.k8s.io, яка
      # надсилається до вебхука та очікується від нього.
      # Те саме, що і встановлення прапорця `--authorization-webhook-version`
      # Обовʼязково, немає типового значення
      # Допустимі значення: v1beta1, v1
      subjectAccessReviewVersion: v1
      # MatchConditionSubjectAccessReviewVersion визначає версію SubjectAccessReview,
      # за якою обчислюються вирази CEL
      # Допустимі значення: v1
      # Обовʼязково, немає типового значення
      matchConditionSubjectAccessReviewVersion: v1
      # Керує рішенням авторизації, коли запит вебхука не вдалося
      # виконати, або отримано некоректну відповідь, або сталися помилки під час обчислення
      # matchConditions.
      # Допустимі значення:
      #   - NoOpinion: продовжити до наступних авторизаторів, щоб перевірити, чи
      #     дозволяє один з них запит
      #   - Deny: відхилити запит без звернення до наступних авторизаторів
      # Обовʼязково, немає типового значення.
      failurePolicy: Deny
      connectionInfo:
        # Керує тим, як вебхук повинен спілкуватися з сервером.
        # Допустимі значення:
        # - KubeConfigFile: використовувати файл, вказаний у kubeConfigFile, для пошуку
        #   сервера.
        # - InClusterConfig: використовувати внутрішньокластерну конфігурацію для виклику
        #   API SubjectAccessReview, що обслуговується kube-apiserver. Цей режим не
        #   дозволяється для kube-apiserver.
        type: KubeConfigFile
        # Шлях до KubeConfigFile з інформацією про підключення
        # Обовʼязково, якщо connectionInfo.Type є KubeConfigFile
        kubeConfigFile: /kube-system-authz-webhook.yaml
        # matchConditions — це список умов, які повинні бути виконані для того, щоб запит було надіслано до цього
        # вебхука. Порожній список matchConditions відповідає всім запитам.
        # Дозволено не більше 64 умов відповідності.
        #
        # Точна логіка зіставлення така (по порядку):
        #   1. Якщо принаймні одна matchCondition обчислюється як FALSE, тоді вебхук пропускається.
        #   2. Якщо ВСІ matchConditions обчислюються як TRUE, тоді вебхук викликається.
        #   3. Якщо принаймні одна matchCondition обчислюється з помилкою (але жодна не є FALSE):
        #      - Якщо failurePolicy=Deny, тоді вебхук відхиляє запит
        #      - Якщо failurePolicy=NoOpinion, тоді помилка ігнорується, а вебхук пропускається
      matchConditions:
      # expression — це вираз, який буде обчислено CEL. Має повертати булеве значення.
      # Вирази CEL мають доступ до вмісту SubjectAccessReview у версії v1.
      # Якщо версія, вказана в subjectAccessReviewVersion, для змінної request є v1beta1,
      # вміст буде конвертовано у версію v1 перед обчисленням виразу CEL.
      #
      # Документація CEL: https://kubernetes.io/docs/reference/using-api/cel/
      #
      # надсилати до вебхука лише запити до ресурсів
      - expression: has(request.resourceAttributes)
      # перехоплювати лише запити до kube-system
      - expression: request.resourceAttributes.namespace == 'kube-system'
      # не перехоплювати запити від службових облікових записів kube-system
      - expression: "!('system:serviceaccounts:kube-system' in request.groups)"
  - type: Node
    name: node
  - type: RBAC
    name: rbac
  - type: Webhook
    name: in-cluster-authorizer
    webhook:
      authorizedTTL: 5m
      unauthorizedTTL: 30s
      timeout: 3s
      subjectAccessReviewVersion: v1
      failurePolicy: NoOpinion
      connectionInfo:
        type: InClusterConfig

Під час налаштування ланцюжка авторизаторів за допомогою файлу конфігурації переконайтеся, що всі вузли панелі управління мають однаковий вміст файлу. Зверніть увагу на конфігурацію API-сервера при оновленні / зниженні версії вашого кластера. Наприклад, якщо ви оновлюєтеся з Kubernetes 1.36 до Kubernetes 1.37, вам потрібно переконатися, що файл конфігурації має формат, який розуміє Kubernetes 1.37, перш ніж ви оновите кластер. Якщо ви знижуєте версію до 1.36, вам потрібно відповідно налаштувати конфігурацію.

Конфігурація авторизації та перезавантаження

Kubernetes перезавантажує файл конфігурації авторизації, коли API-сервер виявляє зміну у файлі, а також за 60-секундним графіком, якщо події змін не спостерігаються.

Конфігурація режиму авторизації через командний рядок

Ви можете використовувати наступні режими:

• --authorization-mode=ABAC (режим контролю доступу на основі атрибутів)
• --authorization-mode=RBAC (режим контролю доступу на основі ролей)
• --authorization-mode=Node (авторизатор вузлів)
• --authorization-mode=Webhook (режим авторизації вебхуком)
• --authorization-mode=AlwaysAllow (завжди дозволяє запити; несе ризики безпеки)
• --authorization-mode=AlwaysDeny (завжди відхиляє запити)

Ви можете вибрати більше одного режиму авторизації; наприклад: --authorization-mode=Node,RBAC,Webhook

Kubernetes перевіряє модулі авторизації в порядку, в якому ви вказуєте їх у командному рядку API-сервера, тому раніше зазначений модуль має вищий пріоритет для дозволу або відмови в запиті.

Ви не можете поєднувати аргумент командного рядка --authorization-mode з аргументом командного рядка --authorization-config, який використовується для налаштування авторизації за допомогою локального файлу.

Для отримання додаткової інформації про аргументи командного рядка для API-сервера читайте довідник kube-apiserver.

Підвищення привілеїв через створення або редагування робочих навантажень

Користувачі, які можуть створювати/редагувати Podʼи в просторі імен, або безпосередньо, або через обʼєкт, що дозволяє опосередковане управління робочими навантаженнями, можуть мати можливість підвищити свої привілеї в цьому просторі імен. Потенційні шляхи до підвищення привілеїв включають розширення API Kubernetes та повʼязані з ними контролери.

Шляхи підвищення привілеїв

Існують різні способи, за якими зловмисник або ненадійний користувач може отримати додаткові привілеї в межах простору імен, якщо ви дозволяєте їм запускати довільні Podʼи в цьому просторі імен:

• Монтування довільних Secretʼів в цьому просторі імен
  • Може бути використано для доступу до конфіденційної інформації, призначеної для інших робочих навантажень
  • Може бути використано для отримання токена службового облікового запису більш привілейованого ServiceAccount
• Використання довільних ServiceAccountʼів в цьому просторі імен
  • Може виконувати дії API Kubernetes як інше робоче навантаження (імперсонація)
  • Може виконувати будь-які привілейовані дії, які має цей ServiceAccount
• Монтування або використання ConfigMapʼів, призначених для інших робочих навантажень в цьому просторі імен
  • Може бути використано для отримання інформації, призначеної для інших робочих навантажень, такої як імена хостів баз даних.
• Монтування томів, призначених для інших робочих навантажень в цьому просторі імен
  • Може бути використано для отримання інформації, призначеної для інших робочих навантажень, та її зміни.

Перевірка доступу до API

kubectl надає підкоманду auth can-i для швидкого запиту до рівня авторизації API. Команда використовує API SelfSubjectAccessReview, щоб визначити, чи може поточний користувач виконати вказану дію, і працює незалежно від режиму авторизації, який використовується.

kubectl auth can-i create deployments --namespace dev

Вивід подібний до цього:

yes

kubectl auth can-i create deployments --namespace prod

Вивід подібний до цього:

no

Адміністратори можуть поєднувати це з імперсонацією користувача, щоб визначити, які дії можуть виконувати інші користувачі.

kubectl auth can-i list secrets --namespace dev --as dave

Вивід подібний до цього:

no

Так само, щоб перевірити, чи може ServiceAccount з іменем dev-sa в Namespace dev отримати перелік Podʼів у Namespace target:

kubectl auth can-i list pods \
    --namespace target \
    --as system:serviceaccount:dev:dev-sa

Вивід подібний до цього:

yes

SelfSubjectAccessReview є частиною групи API authorization.k8s.io, яка надає доступ до авторизації API-сервера зовнішнім службам. Інші ресурси у цій групі включають:

SubjectAccessReview

Перегляд доступу для будь-якого користувача, не лише поточного. Корисно для делегування рішень про авторизацію API-серверу. Наприклад, kubelet та API-сервери розширень використовують це для визначення доступу користувача до своїх власних API.

LocalSubjectAccessReview

Подібно до SubjectAccessReview, але обмежено конкретним простором імен.

SelfSubjectRulesReview

Перегляд, який повертає набір дій, які користувач може виконати в межах простору імен. Корисно для користувачів для швидкого узагальнення їх власного доступу, або для інтерфейсів користувача для приховування/відображення дій.

Ці API можна опитати, створивши звичайні ресурси Kubernetes, де поле відповіді status поверненого обʼєкта є результатом запиту. Наприклад:

kubectl create -f - -o yaml << EOF
apiVersion: authorization.k8s.io/v1
kind: SelfSubjectAccessReview
spec:
  resourceAttributes:
    group: apps
    resource: deployments
    verb: create
    namespace: dev
EOF

Створений SelfSubjectAccessReview схожий на:

apiVersion: authorization.k8s.io/v1
kind: SelfSubjectAccessReview
metadata:
  creationTimestamp: null
spec:
  resourceAttributes:
    group: apps
    resource: deployments
    namespace: dev
    verb: create
status:
  allowed: true
  denied: false

Що далі

• Щоб дізнатися більше про автентифікацію, перегляньте Автентифікацію.
• Для отримання огляду, перегляньте Керування доступом до API Kubernetes.
• Щоб дізнатися більше про контроль допуску, перегляньте Використання контролерів допуску.
• Дізнайтеся більше про Загальну мову виразів (CEL) у Kubernetes.

3.2 - Використання авторизації ABAC

Керування доступом на основі атрибутів (ABAC) визначає парадигму керування доступом, за якою права доступу надаються користувачам за допомогою політик, які комбінують атрибути.

Формат файлу політики

Для увімкнення режиму ABAC вказуйте --authorization-policy-file=SOME_FILENAME та --authorization-mode=ABAC під час запуску.

Формат файлу — один обʼєкт JSON на рядок. Не повинно бути зовнішнього списку чи map, лише один map на рядок.

Кожний рядок — "обʼєкт політики", де такий обʼєкт є map із такими властивостями:

• Властивості версіювання:
  • apiVersion, типу string; допустимі значення "abac.authorization.kubernetes.io/v1beta1". Дозволяє версіювання та конвертацію формату політики.
  • kind, типу string: допустимі значення "Policy". Дозволяє версіювання та конвертацію формату політики.
• Властивість spec встановлена на map з такими властивостями:
  • Властивості зіставлення субʼєкта:
    • user, типу string; рядок користувача з --token-auth-file. Якщо ви вказуєте user, він повинен збігатися з імʼям користувача автентифікованого користувача.
    • group, типу string; якщо ви вказуєте group, вона повинна збігатися з однією з груп автентифікованого користувача. system:authenticated збігається з усіма автентифікованими запитами. system:unauthenticated збігається з усіма неавтентифікованими запитами.
  • Властивості зіставлення ресурсу:
    • apiGroup, типу string; група API.
      • Наприклад: apps, networking.k8s.io
      • Маска: * збігається з усіма групами API.
    • namespace, типу string; простір імен.
      • Наприклад: kube-system
      • Маска: * збігається з усіма запитами ресурсів.
    • resource, типу string; тип ресурсу
      • Наприклад: pods, deployments
      • Маска: * збігається з усіма запитами ресурсів.
  • Властивості зіставлення нересурсів:
    • nonResourcePath, типу string; шляхи запитів нересурсів.
      • Наприклад: /version або /apis
      • Маска:
        • * збігається з усіма запитами нересурсів.
        • /foo/* збігається з усіма підшляхами /foo/.
  • readonly, типу boolean, якщо true, означає, що політика, що зіставляється з ресурсом, застосовується тільки до операцій get, list, та watch, а політика, що зіставляється з нересурсами, застосовується тільки до операції get.

Алгоритм авторизації

У запиту є атрибути, які відповідають властивостям обʼєкта політики.

Коли отримано запит, визначаються атрибути. Невідомі атрибути встановлюються на нульове значення свого типу (наприклад, порожній рядок, 0, false).

Властивість, встановлена на "*", буде збігатися з будь-яким значенням відповідного атрибута.

Кортеж атрибутів перевіряється на відповідність кожній політиці в файлі політики. Якщо принаймні один рядок відповідає атрибутам запиту, тоді запит авторизований (але може зазнати невдачі під час подальшої перевірки).

Щоб дозволити будь-якому автентифікованому користувачеві зробити щось, створіть політику з властивістю group, встановленою на "system:authenticated".

Щоб дозволити будь-якому неавтентифікованому користувачеві зробити щось, створіть політику з властивістю group, встановленою на "system:unauthenticated".

Щоб дозволити користувачеві зробити все, створіть політику з властивостями apiGroup, namespace, resource та nonResourcePath, встановленими на "*".

Kubectl

Kubectl використовує точки доступу /api та /apis apiserver, щоб виявити типи ресурсів, які обслуговуються, і перевіряє обʼєкти, надіслані до API за допомогою операцій create/update, використовуючи інформацію про схему, розташовану в /openapi/v2.

Під час використання авторизації ABAC ці спеціальні ресурси мають бути явно відкриті за допомогою властивості nonResourcePath в політиці (див. приклади нижче):

• /api, /api/*, /apis та /apis/* для вибору версії API.
• /version для отримання версії сервера через kubectl version.
• /swaggerapi/* для операцій create/update.

Щоб перевірити HTTP-виклики, повʼязані з певною операцією kubectl, ви можете збільшити рівень деталізації:

kubectl --v=8 version

Приклади

1. Alice може робити все з усіма ресурсами:

   {"apiVersion": "abac.authorization.kubernetes.io/v1beta1", "kind": "Policy", "spec": {"user": "alice", "namespace": "*", "resource": "*", "apiGroup": "*"}}
   

2. kubelet може читати будь-які Podʼи:

   {"apiVersion": "abac.authorization.kubernetes.io/v1beta1", "kind": "Policy", "spec": {"user": "kubelet", "namespace": "*", "resource": "pods", "readonly": true}}
   

3. kubelet може читати та записувати події:

   {"apiVersion": "abac.authorization.kubernetes.io/v1beta1", "kind": "Policy", "spec": {"user": "kubelet", "namespace": "*", "resource": "events"}}
   

4. Bob може лише читати Podʼи в просторі імен "projectCaribou":

   {"apiVersion": "abac.authorization.kubernetes.io/v1beta1", "kind": "Policy", "spec": {"user": "bob", "namespace": "projectCaribou", "resource": "pods", "readonly": true}}
   

5. Будь-хто може робити запити тільки для читання на всі нересурсні шляхи:

   {"apiVersion": "abac.authorization.kubernetes.io/v1beta1", "kind": "Policy", "spec": {"group": "system:authenticated", "readonly": true, "nonResourcePath": "*"}}
    {"apiVersion": "abac.authorization.kubernetes.io/v1beta1", "kind": "Policy", "spec": {"group": "system:unauthenticated", "readonly": true, "nonResourcePath": "*"}}
   

Приклад повного файлу

Коротка нотатка про службові облікові записи

Кожен службовий обліковий запис має відповідне імʼя користувача ABAC, і імʼя користувача цього службового облікового запису генерується згідно з такою конвенцією найменування:

system:serviceaccount:<namespace>:<serviceaccountname>

Створення нового простору імен призводить до створення нового службового облікового запису в такому форматі:

system:serviceaccount:<namespace>:default

Наприклад, якщо ви хочете надати типовому (default) службовому обліковому запису (у просторі імен kube-system) повні привілеї в API за допомогою ABAC, додайте цей рядок до файлу політики:

{"apiVersion":"abac.authorization.kubernetes.io/v1beta1","kind":"Policy","spec":{"user":"system:serviceaccount:kube-system:default","namespace":"*","resource":"*","apiGroup":"*"}}

apiserver потрібно перезапустити, щоб він підхопив нові рядки політики.

3.3 - Автентифікація/авторизація kubelet

Огляд

HTTPS-точка доступу kubelet надає API, які дають доступ до даних різного рівня чутливості та дозволяють виконувати операції з різним рівнем повноважень на вузлі та в контейнерах.

У цьому документі описано, як автентифікувати та авторизувати доступ до HTTPS-точки доступу kubelet.

Автентифікація kubelet

Типово запити до HTTPS-точки доступу kubelet, які не відхилені іншими налаштованими методами автентифікації, розглядаються як анонімні запити та отримують імʼя користувача system:anonymous та групу system:unauthenticated.

Щоб вимкнути анонімний доступ та надсилати відповіді 401 Unauthorized на неавтентифіковані запити:

• запустіть kubelet з прапорцем --anonymous-auth=false

Щоб увімкнути автентифікацію за допомогою клієнтських сертифікатів X509 до HTTPS-точки доступу kubelet:

• запустіть kubelet з прапорцем --client-ca-file, передавши набір сертифікатів CA для перевірки клієнтських сертифікатів
• запустіть apiserver з прапорцями --kubelet-client-certificate та --kubelet-client-key
• див. документацію з автентифікації apiserver для отримання додаткових відомостей

Щоб увімкнути використання API-токенів на предʼявника (включаючи токени службових облікових записів) для автентифікації до HTTPS-точки доступу kubelet:

• переконайтеся, що група API authentication.k8s.io/v1 ввімкнена в API-сервері
• запустіть kubelet з прапорцями --authentication-token-webhook та --kubeconfig
• kubelet викликає API TokenReview на налаштованому API-сервері, щоб визначити інформацію про користувача з токенів на предʼявника

Авторизація kubelet

Будь-який запит, який успішно автентифікується (включаючи анонімний запит), потім авторизується. Типовий режим авторизації — AlwaysAllow, який дозволяє всі запити.

Є багато можливих причин розмежувати доступ до API kubelet:

• ввімкнено анонімну автентифікацію, але потрібно обмежити можливості анонімних користувачів викликати API kubelet
• ввімкнено автентифікацію з використанням токенів на предʼявника, але потрібно обмежити можливості довільних користувачів API (наприклад, службових облікових записів) викликати API kubelet
• ввімкнено автентифікацію за допомогою клієнтських сертифікатів, але дозволено використовувати API kubelet тільки деяким сертифікатам клієнтів, які підписані налаштованим кореневим сертифікатом

Щоб розмежувати доступ до API kubelet, делегуйте авторизацію API-серверу:

• переконайтеся, що група API authorization.k8s.io/v1 ввімкнена в API-сервері
• запустіть kubelet з прапорцями --authorization-mode=Webhook та --kubeconfig
• kubelet викликає API SubjectAccessReview на налаштованому API-сервері, щоб визначити, чи авторизований кожний запит

kubelet авторизує запити до API, використовуючи той самий підхід до атрибутів запиту, що й apiserver.

Дієслово визначається з HTTP-дії вхідного запиту:

Ресурс та субресурс визначаються з шляху вхідного запиту:

Атрибути простору імен та групи API завжди є порожніми рядками, а імʼя ресурсу завжди є імʼям обʼєкта API Node цього kubelet.

Під час використання цього режиму переконайтеся, що користувач, визначений прапорцями --kubelet-client-certificate та --kubelet-client-key, переданими до apiserver, авторизований для таких атрибутів:

• verb=*, resource=nodes, subresource=proxy
• verb=*, resource=nodes, subresource=stats
• verb=*, resource=nodes, subresource=log
• verb=*, resource=nodes, subresource=spec
• verb=*, resource=nodes, subresource=metrics

Детальна авторизація

kubelet виконує детальну перевірку перед поверненням до субресурсу proxy для точок доступу /pods, /runningPods, /configz та /healthz. Ресурс і субресурс визначаються за шляхом вхідного запиту:

Коли функціональну можливість KubeletFineGrainedAuthz увімкнено, переконайтеся, що користувач, ідентифікований прапорцями --kubelet-client-certificate та --kubelet-client-key, переданими API-серверу, авторизований для таких атрибутів:

• verb=*, resource=nodes, subresource=proxy
• verb=*, resource=nodes, subresource=stats
• verb=*, resource=nodes, subresource=log
• verb=*, resource=nodes, subresource=metrics
• verb=*, resource=nodes, subresource=configz
• verb=*, resource=nodes, subresource=healthz
• verb=*, resource=nodes, subresource=pods

Якщо використовується авторизація RBAC, увімкнення цієї функціональної можливості також гарантує, що вбудована system:kubelet-api-admin ClusterRole буде оновлена з дозволами на доступ до всіх вищезгаданих субресурсів.

4 - Відомі мітки, анотації та позначки taint

Kubernetes резервує всі мітки, анотації та позначки taint у просторах імен kubernetes.io і k8s.io.

Цей документ слугує як довідником значень, так і точкою координації для їх призначення.

Мітки, анотації та позначки taint, що використовуються в обʼєктах API

apf.kubernetes.io/autoupdate-spec

Тип: Annotation

Приклад: apf.kubernetes.io/autoupdate-spec: "true"

Використовується для: Обʼєктів FlowSchema та PriorityLevelConfiguration

Якщо ця анотація встановлена в значення true для FlowSchema або PriorityLevelConfiguration, то spec для цього обʼєкта управляється kube-apiserver. Якщо API-сервер не розпізнає обʼєкт APF, а ви анотуєте його для автоматичного оновлення, API-сервер видаляє весь обʼєкт. В іншому випадку API-сервер не управляє специфікацією обʼєкта. Докладніше читайте Обслуговування обовʼязкових та рекомендованих обʼєктів конфігурації.

app.kubernetes.io/component

Тип: Label

Приклад: app.kubernetes.io/component: "database"

Використовується для: Всі обʼєкти (зазвичай використовується на ресурсах робочого навантаження).

Компонент в архітектурі застосунку.

Одна з рекомендованих міток.

app.kubernetes.io/created-by (deprecated)

Тип: Label

Приклад: app.kubernetes.io/created-by: "controller-manager"

Використовується для: Всі обʼєкти (зазвичай використовується на ресурсах робочого навантаження).

Контролер/користувач, який створив цей ресурс.

app.kubernetes.io/instance

Тип: Label

Приклад: app.kubernetes.io/instance: "mysql-abcxyz"

Використовується для: Всі обʼєкти (зазвичай використовується на ресурсах робочого навантаження).

Унікальне імʼя, що ідентифікує екземпляр застосунку. Для призначення неунікального імені використовуйте app.kubernetes.io/name.

Одна з рекомендованих міток.

app.kubernetes.io/managed-by

Тип: Label

Приклад: app.kubernetes.io/managed-by: "helm"

Використовується для: Всі обʼєкти (зазвичай використовується на ресурсах робочого навантаження).

Інструмент, що використовується для управління роботою застосунку.

Одна з рекомендованих міток.

app.kubernetes.io/name

Тип: Label

Приклад: app.kubernetes.io/name: "mysql"

Використовується для: Всі обʼєкти (зазвичай використовується на ресурсах робочого навантаження).

Назва застосунку.

Одна з рекомендованих міток.

app.kubernetes.io/part-of

Тип: Label

Приклад: app.kubernetes.io/part-of: "wordpress"

Використовується для: Всі обʼєкти (зазвичай використовується на ресурсах робочого навантаження).

Назва застосунку вищого рівня, частиною якого є цей обʼєкт.

Одна з рекомендованих міток.

app.kubernetes.io/version

Тип: Label

Приклад: app.kubernetes.io/version: "5.7.21"

Використовується для: Всі обʼєкти (зазвичай використовується на ресурсах робочого навантаження).

Поточна версія застосунку.

Загальні форми значень включають:

• семантична версія
• хеш ревізії Git для вихідного коду.

Одна з рекомендованих міток.

applyset.kubernetes.io/additional-namespaces (alpha)

Тип: Annotation

Приклад: applyset.kubernetes.io/additional-namespaces: "namespace1,namespace2"

Використовується для: Обʼєкти, які використовуються як батьки ApplySet.

Використання цієї анотації є альфа-версією. Для Kubernetes версії 1.37 ви можете використовувати цю анотацію на Secrets, ConfigMaps або власних ресурсах, якщо CustomResourceDefinition, що їх визначає, має мітку applyset.kubernetes.io/is-parent-type.

Частина специфікації, яка використовується для реалізації обрізки на основі ApplySet в kubectl. Ця анотація застосовується до батьківського обʼєкта, який використовується для відстеження ApplySet для розширення області застосування ApplySet поза власним простором імен батьківського обʼєкта (якщо є). Значення — це розділений комами список імен просторів імен, відмінних від простору імен батьківського обʼєкта, в яких знаходяться обʼєкти.

applyset.kubernetes.io/contains-group-kinds (alpha)

Тип: Annotation

Приклад: applyset.kubernetes.io/contains-group-kinds: "certificates.cert-manager.io,configmaps,deployments.apps,secrets,services"

Використовується для: Обʼєкти, які використовуються як батьки ApplySet.

Використання цієї анотації є альфа-версією. Для Kubernetes версії 1.37 ви можете використовувати цю анотацію на Secrets, ConfigMaps або власних ресурсах, якщо CustomResourceDefinition, що їх визначає, має мітку applyset.kubernetes.io/is-parent-type.

Частина специфікації, яка використовується для реалізації обрізки на основі ApplySet в kubectl. Ця анотація застосовується до батьківського обʼєкта, який використовується для відстеження ApplySet для оптимізації списку обʼєктів-членів ApplySet. Не є обовʼязковою у специфікації ApplySet, оскільки інструменти можуть виконувати виявлення або використовувати іншу оптимізацію. Однак, починаючи з версії Kubernetes 1.37, kubectl вимагає її наявності. Якщо вона присутня, значення цієї анотації має бути розділеним комами списком group-kind у форматі повної назви, тобто <resource>.<group>.

applyset.kubernetes.io/contains-group-resources (deprecated)

Тип: Annotation

Приклад: applyset.kubernetes.io/contains-group-resources: "certificates.cert-manager.io,configmaps,deployments.apps,secrets,services"

Використовується для: Обʼєкти, які використовуються як батьки ApplySet.

Для Kubernetes версії 1.37 ви можете використовувати цю анотацію на Secrets, ConfigMaps або власних ресурсах, якщо CustomResourceDefinition, що їх визначає, має мітку applyset.kubernetes.io/is-parent-type.

Частина специфікації, яка використовується для реалізації обрізки на основі ApplySet в kubectl. Ця анотація застосовується до батьківського обʼєкта, який використовується для відстеження ApplySet для оптимізації списку обʼєктів-членів ApplySet. Не є обовʼязковою у специфікації ApplySet, оскільки інструменти можуть виконувати виявлення або використовувати іншу оптимізацію. Однак у версії Kubernetes 1.37 kubectl вимагає її наявності. Якщо вона присутня, значення цієї анотації має бути розділеним комами списком group-kind у форматі повної назви, тобто <resource>.<group>.

applyset.kubernetes.io/id (alpha)

Тип: Label

Приклад: applyset.kubernetes.io/id: "applyset-0eFHV8ySqp7XoShsGvyWFQD3s96yqwHmzc4e0HR1dsY-v1"

Використовується для: Обʼєкти, які використовуються як батьки ApplySet.

Використання цієї мітки є альфа-версією. Для Kubernetes версії 1.37 ви можете використовувати цю мітку на Secrets, ConfigMaps або власних ресурсах, якщо CustomResourceDefinition, що їх визначає, має мітку applyset.kubernetes.io/is-parent-type.

Частина специфікації, яка використовується для реалізації обрізки на основі ApplySet в kubectl. Ця мітка робить обʼєкт батьківським обʼєктом ApplySet. Її значенням є унікальний ідентифікатор ApplySet, який походить від ідентифікатора самого батьківського обʼєкта. Цей ідентифікатор повинен бути кодуванням base64 (з використанням безпечного для URL кодування RFC4648) хешу group-kind-name-namespace обʼєкта, на якому він знаходиться, у вигляді: <base64(sha256(<name>.<namespace>.<kind>.<group>))>. Між значенням цієї мітки та UID обʼєкта немає звʼязку.

applyset.kubernetes.io/is-parent-type (alpha)

Тип: Label

Приклад: applyset.kubernetes.io/is-parent-type: "true"

Використовується для: Custom Resource Definition (CRD)

Використання цієї мітки є альфа-версією. Частина специфікації, яка використовується для реалізації обрізки на основі ApplySet в kubectl. Ви можете встановити цю мітку на CustomResourceDefinition (CRD), щоб ідентифікувати тип власного ресурсу, який він визначає (а не сам CRD) як дозволеного батька для ApplySet. Єдиним допустимим значенням для цієї мітки є "true"; якщо ви хочете позначити CRD як такий, що не є дійсним батьком для ApplySets, пропустіть цю мітку.

applyset.kubernetes.io/part-of (alpha)

Тип: Label

Приклад: applyset.kubernetes.io/part-of: "applyset-0eFHV8ySqp7XoShsGvyWFQD3s96yqwHmzc4e0HR1dsY-v1"

Використовується для: Всі обʼєкти.

Використання цієї мітки є альфа-версією. Частина специфікації, яка використовується для реалізації обрізки на основі ApplySet в kubectl. Ця мітка робить обʼєкт членом ApplySet. Значення мітки повинно збігатися зі значенням мітки applyset.kubernetes.io/id у батьківському обʼєкті.

applyset.kubernetes.io/tooling (alpha)

Тип: Annotation

Приклад: applyset.kubernetes.io/tooling: "kubectl/v1.37"

Використовується для: Обʼєкти, які використовуються як батьки ApplySet.

Використання цієї анотації є альфа-версією. Для Kubernetes версії 1.37 ви можете використовувати цю анотацію на Secrets, ConfigMaps або власних ресурсах, якщо CustomResourceDefinition, що їх визначає, має мітку applyset.kubernetes.io/is-parent-type.

Частина специфікації, яка використовується для реалізації обрізки на основі ApplySet в kubectl. Ця анотація застосовується до батьківського обʼєкта, який використовується для відстеження ApplySet, щоб вказати, який інструментарій керує цим ApplySet. Інструментарій повинен відмовлятися змінювати ApplySets, що належать іншим інструментам. Значення має бути у форматі <toolname>/<semver>.

apps.kubernetes.io/pod-index (beta)

Тип: Label

Приклад: apps.kubernetes.io/pod-index: "0"

Використовується для: Pod

Коли контролер StatefulSet створює Pod для StatefulSet, він встановлює цю мітку на Pod. Значення мітки є порядковим індексом створюваного Podʼа.

Дивіться Мітка індексу Podʼа в темі StatefulSet для отримання більш детальної інформації. Зверніть увагу, що для додавання цієї мітки до Podʼів має бути увімкнена функціональна можливість PodIndexLabel.

resource.kubernetes.io/pod-claim-name

Тип: Annotation

Приклад: resource.kubernetes.io/pod-claim-name: "my-pod-claim"

Використовується для: ResourceClaim

Ця анотація призначається згенерованим ResourceClaim. Її значення відповідає назві заявки на ресурс у .spec будь-якого Podʼа (або Podʼів), для якого було створено ResourceClaim. У рамках динамічного виділення ресурсів функція метаданих виявлених пристроїв використовує цю анотацію для привʼязки згенерованого ResourceClaim до імені заявки Podʼа (pod.spec.resourceClaims[].name) для заявок на основі шаблонів. Цією анотацією керує Kubernetes, тому її не слід змінювати.

cluster-autoscaler.kubernetes.io/safe-to-evict

Тип: Annotation

Приклад: cluster-autoscaler.kubernetes.io/safe-to-evict: "true"

Використовується для: Pod

Коли ця анотація має значення "true", автомасштабувальнику кластера дозволяється виселяти Pod навіть якщо інші правила зазвичай забороняють це робити. Автомасштабувальник кластера ніколи не виселяє Podʼи, для яких ця анотація явно встановлена у значення "false"; ви можете встановити це значення для важливого Podʼа, який ви хочете продовжувати виконувати. Якщо цю анотацію не задано, то автомасштабувальник кластера поводитиметься так, як він поводиться на рівні Podʼа.

config.kubernetes.io/local-config

Тип: Annotation

Приклад: config.kubernetes.io/local-config: "true"

Використовується для: Всі обʼєкти

Ця анотація використовується у маніфестах для позначення обʼєкта як локальної конфігурації, яку не слід передавати до API Kubernetes.

Значення "true" для цієї анотації вказує, що обʼєкт використовується лише клієнтськими інструментами і не повинен бути надісланий на API-сервер.

Значення "false" може бути використане для вказівки, що обʼєкт повинен бути надісланий на API-сервер, навіть якщо в іншому випадку він вважався б локальним.

Ця анотація є частиною специфікації функцій Kubernetes Resource Model (KRM), яка використовується Kustomize та подібними сторонніми інструментами. Наприклад, Kustomize видаляє обʼєкти з цією анотацією з кінцевого результату збирання.

container.apparmor.security.beta.kubernetes.io/* (deprecated)

Тип: Annotation

Приклад: container.apparmor.security.beta.kubernetes.io/my-container: my-custom-profile

Використовується для: Pods

Ця анотація дозволяє вам вказати профіль безпеки AppArmor для контейнера в межах Podʼа Kubernetes. Починаючи з версії Kubernetes 1.30, це слід налаштовувати за допомогою поля appArmorProfile. Щоб дізнатися більше, перегляньте підручник з AppArmor. У підручнику показано, як використовувати AppArmor для обмеження можливостей і доступу контейнера.

Вказаний профіль визначає набір правил і обмежень, яких повинен дотримуватися процес у контейнері. Це допомагає забезпечити дотримання політик безпеки та ізоляцію ваших контейнерів.

csi.alpha.kubernetes.io/node-id (deprecated)

Тип: Annotation

Приклад: csi.alpha.kubernetes.io/node-id: "node-12345"

Використовується для: VolumeAttachments

Ця анотація записує ідентифікатор вузла, який використовує драйвер CSI, як резервний варіант, коли обʼєкт CSINode недоступний. Sidecar-контейнер external-attacher CSI заповнює її перед тим, як том буде приєднано.

Вона забезпечує резервний механізм для відʼєднання томів, коли відповідний CSINode відсутній.

Оскільки ця анотація застаріла, проєкт Kubernetes рекомендує не встановлювати її на VolumeAttachment або на будь-який інший обʼєкт.

csi.volume.kubernetes.io/nodeid (deprecated)

Тип: Annotation

Приклад: csi.volume.kubernetes.io/nodeid: "node-12345"

Використовується для: Nodes

Ця анотація визначає ідентифікатор вузла, як його розуміє драйвер Container Storage Interface (CSI). kubelet заповнює цю анотацію, викликаючи метод gRPC NodeGetInfo драйвера CSI, щоб отримати ідентифікатор вузла під час реєстрації драйвера. Sidecar-контейнер external-attacher зчитує цю анотацію, щоб отримати ідентифікатор вузла під час приєднання або відʼєднання томів.

Ця анотація застаріла на користь обʼєкта CSINode, який надає ту саму функціональність через поле spec.drivers[].nodeID.

deployment.kubernetes.io/desired-replicas

Тип: Annotation

Приклад: deployment.kubernetes.io/desired-replicas: "3"

Використовується для: ReplicaSet

Ця анотація встановлюється контролером Deployment на ReplicaSets, якими він керує. Значення представляє бажану кількість реплік (.spec.replicas) з Deployment, якому належить цей ReplicaSet. Контролер Deployment використовує цю анотацію для відстеження бажаного стану під час послідовних оновлень та операцій масштабування.

Це внутрішня анотація, яка використовується контролером Deployment і не повинна змінюватися вручну.

deployment.kubernetes.io/max-replicas

Тип: Annotation

Приклад: deployment.kubernetes.io/max-replicas: "5"

Використовується для: ReplicaSet

Ця анотація встановлюється контролером Deployment на ReplicaSets, якими він керує. Значення представляє максимальну кількість реплік, яку цей ReplicaSet може мати під час послідовного оновлення. Це використовується для реалізації параметра maxSurge стратегії послідовного оновлення Deployment, який контролює, скільки додаткових Podʼів можна створити понад бажану кількість під час оновлення.

Це внутрішня анотація, яка використовується контролером Deployment і не повинна змінюватися вручну.

deployment.kubernetes.io/revision

Тип: Annotation

Приклад: deployment.kubernetes.io/revision: "2"

Використовується для: ReplicaSet

Ця анотація встановлюється контролером Deployment на ReplicaSets, якими він керує. Значення представляє номер ревізії Deployment. Кожного разу, коли шаблон Podʼа (.spec.template) в Deployment змінюється, номер ревізії збільшується. Ця анотація використовується для відстеження історії розгортання та дозволяє повернутися до попередніх ревізій за допомогою kubectl rollout undo.

Номер ревізії також видно при запуску kubectl rollout history deployment/<name>.

Це внутрішня анотація, яка використовується контролером Deployment і не повинна змінюватися вручну.

deployment.kubernetes.io/revision-history

Тип: Annotation

Приклад: deployment.kubernetes.io/revision-history: "1,3"

Використовується для: ReplicaSet

Ця анотація встановлюється контролером Deployment на ReplicaSet, коли відкат призводить до повторного використання ReplicaSet. Значенням є список, розділений комами, усіх попередніх номерів ревізій, які ReplicaSet обслуговував для Deployment, що зберігається як історія, коли анотація deployment.kubernetes.io/revision оновлюється до нового номера ревізії.

Це внутрішня анотація, яка використовується контролером Deployment і не повинна змінюватися вручну.

internal.config.kubernetes.io/* (reserved prefix)

Тип: Annotation

Використовується для: Всі обʼєкти

Цей префікс зарезервований для внутрішнього використання інструментами, які діють як оркестратори відповідно до специфікації функцій Моделі Ресурсів Kubernetes (KRM). Анотації з цим префіксом є внутрішніми для процесу оркестрування та не зберігаються в маніфестах у файловій системі. Іншими словами, інструмент-оркестратор повинен встановлювати ці анотації при зчитуванні файлів з локальної файлової системи та видаляти їх при записі результатів роботи функцій назад у файлову систему.

Функція KRM не повинна змінювати анотації з цим префіксом, якщо не зазначено інше для конкретної анотації. Це дозволяє інструментам оркестрування додавати додаткові внутрішні анотації без необхідності вносити зміни в існуючі функції.

internal.config.kubernetes.io/path

Тип: Annotation

Приклад: internal.config.kubernetes.io/path: "relative/file/path.yaml"

Використовується для: Всі обʼєкти

Ця анотація записує шлях до файлу маніфесту, з якого було завантажено обʼєкт, у вигляді розділеного слешами, незалежного від ОС, відносного шляху. Шлях є відносним до фіксованого розташування у файловій системі, визначеного інструментом-оркестратором.

Ця анотація є частиною специфікації функцій Моделі Ресурсів Kubernetes (KRM), яка використовується Kustomize та подібними сторонніми інструментами.

Функція KRM не повинна змінювати цю анотацію у вхідних обʼєктах, якщо вона не змінює файли, на які посилається. Функція KRM може включати цю анотацію у обʼєкти, які вона генерує.

internal.config.kubernetes.io/index

Тип: Annotation

Приклад: internal.config.kubernetes.io/index: "2"

Використовується для: Всі обʼєкти

Ця анотація записує позицію (нумерація з нуля) YAML-документа, який містить обʼєкт, у файлі маніфесту, з якого було завантажено обʼєкт. Зазначимо, що YAML-документи розділяються трьома тире (---) і кожен може містити один обʼєкт. Якщо ця анотація не вказана, мається на увазі значення 0.

Ця анотація є частиною специфікації функцій Моделі Ресурсів Kubernetes (KRM), яка використовується Kustomize та подібними сторонніми інструментами.

Функція KRM не повинна змінювати цю анотацію у вхідних обʼєктах, якщо вона не змінює файли, на які посилається. Функція KRM може включати цю анотацію в обʼєкти, які вона генерує.

kube-scheduler-simulator.sigs.k8s.io/bind-result

Тип: Annotation

Приклад: kube-scheduler-simulator.sigs.k8s.io/bind-result: '{"DefaultBinder":"success"}'

Використовується для: Pod

Ця анотація записує результат роботи втулків планувальника bind; використовується в https://sigs.k8s.io/kube-scheduler-simulator.

kube-scheduler-simulator.sigs.k8s.io/filter-result

Тип: Annotation

Приклад:

kube-scheduler-simulator.sigs.k8s.io/filter-result: >-
      {"node-282x7":{"AzureDiskLimits":"passed","EBSLimits":"passed","GCEPDLimits":"passed","InterPodAffinity":"passed","NodeAffinity":"passed","NodeName":"passed","NodePorts":"passed","NodeResourcesFit":"passed","NodeUnschedulable":"passed","NodeVolumeLimits":"passed","PodTopologySpread":"passed","TaintToleration":"passed","VolumeBinding":"passed","VolumeRestrictions":"passed","VolumeZone":"passed"},"node-gp9t4":{"AzureDiskLimits":"passed","EBSLimits":"passed","GCEPDLimits":"passed","InterPodAffinity":"passed","NodeAffinity":"passed","NodeName":"passed","NodePorts":"passed","NodeResourcesFit":"passed","NodeUnschedulable":"passed","NodeVolumeLimits":"passed","PodTopologySpread":"passed","TaintToleration":"passed","VolumeBinding":"passed","VolumeRestrictions":"passed","VolumeZone":"passed"}}

Використовується для: Pod

Ця анотація записує результат роботи втулків планувальника filter; використовується в https://sigs.k8s.io/kube-scheduler-simulator.

kube-scheduler-simulator.sigs.k8s.io/finalscore-result

Тип: Annotation

Приклад:

kube-scheduler-simulator.sigs.k8s.io/finalscore-result: >-
      {"node-282x7":{"ImageLocality":"0","InterPodAffinity":"0","NodeAffinity":"0","NodeNumber":"0","NodeResourcesBalancedAllocation":"76","NodeResourcesFit":"73","PodTopologySpread":"200","TaintToleration":"300","VolumeBinding":"0"},"node-gp9t4":{"ImageLocality":"0","InterPodAffinity":"0","NodeAffinity":"0","NodeNumber":"0","NodeResourcesBalancedAllocation":"76","NodeResourcesFit":"73","PodTopologySpread":"200","TaintToleration":"300","VolumeBinding":"0"}}

Використовується для: Pod

Ця анотація записує остаточні бали, які планувальник обчислює з балів, отриманих від втулків планувальника score; використовується в https://sigs.k8s.io/kube-scheduler-simulator.

kube-scheduler-simulator.sigs.k8s.io/permit-result

Тип: Annotation

Приклад: kube-scheduler-simulator.sigs.k8s.io/permit-result: '{"CustomPermitPlugin":"success"}'

Використовується для: Pod

Ця анотація записує результат роботи втулків планувальника permit; використовується в https://sigs.k8s.io/kube-scheduler-simulator.

kube-scheduler-simulator.sigs.k8s.io/permit-result-timeout

Тип: Annotation

Приклад: kube-scheduler-simulator.sigs.k8s.io/permit-result-timeout: '{"CustomPermitPlugin":"10s"}'

Використовується для: Pod

Ця анотація записує таймаути, що повертаються втулками планувальника permit; використовується в https://sigs.k8s.io/kube-scheduler-simulator.

kube-scheduler-simulator.sigs.k8s.io/postfilter-result

Тип: Annotation

Приклад: kube-scheduler-simulator.sigs.k8s.io/postfilter-result: '{"DefaultPreemption":"success"}'

Використовується для: Pod

Ця анотація записує результат роботи втулків планувальника postfilter; використовується в https://sigs.k8s.io/kube-scheduler-simulator.

kube-scheduler-simulator.sigs.k8s.io/prebind-result

Тип: Annotation

Приклад: kube-scheduler-simulator.sigs.k8s.io/prebind-result: '{"VolumeBinding":"success"}'

Використовується для: Pod

Ця анотація записує результат роботи втулків планувальника prebind; використовується в https://sigs.k8s.io/kube-scheduler-simulator.

kube-scheduler-simulator.sigs.k8s.io/prefilter-result

Тип: Annotation

Приклад: kube-scheduler-simulator.sigs.k8s.io/prebind-result: '{"NodeAffinity":"[\"node-\a"]"}'

Використовується для: Pod

Ця анотація записує результат PreFilter роботи втулків планувальника prefilter; використовується в https://sigs.k8s.io/kube-scheduler-simulator.

kube-scheduler-simulator.sigs.k8s.io/prefilter-result-status

Тип: Annotation

Приклад:

kube-scheduler-simulator.sigs.k8s.io/prefilter-result-status: >-
      {"InterPodAffinity":"success","NodeAffinity":"success","NodePorts":"success","NodeResourcesFit":"success","PodTopologySpread":"success","VolumeBinding":"success","VolumeRestrictions":"success"}

Використовується для: Pod

Ця анотація записує результат роботи втулків планувальника prefilter; використовується в https://sigs.k8s.io/kube-scheduler-simulator.

kube-scheduler-simulator.sigs.k8s.io/prescore-result

Тип: Annotation

Приклад:

    kube-scheduler-simulator.sigs.k8s.io/prescore-result: >-
      {"InterPodAffinity":"success","NodeAffinity":"success","NodeNumber":"success","PodTopologySpread":"success","TaintToleration":"success"}

Використовується для: Pod

Ця анотація записує результат роботи втулків планувальника prefilter; використовується в https://sigs.k8s.io/kube-scheduler-simulator.

kube-scheduler-simulator.sigs.k8s.io/reserve-result

Тип: Annotation

Приклад: kube-scheduler-simulator.sigs.k8s.io/reserve-result: '{"VolumeBinding":"success"}'

Використовується для: Pod

Ця анотація записує результат роботи втулків планувальника reserve; використовується в https://sigs.k8s.io/kube-scheduler-simulator.

kube-scheduler-simulator.sigs.k8s.io/result-history

Тип: Annotation

Приклад: kube-scheduler-simulator.sigs.k8s.io/result-history: '[]'

Використовується для: Pod

Ця анотація записує всі минулі результати планування від втулків планувальника; використовується в https://sigs.k8s.io/kube-scheduler-simulator.

kube-scheduler-simulator.sigs.k8s.io/score-result

Тип: Annotation

    kube-scheduler-simulator.sigs.k8s.io/score-result: >-
      {"node-282x7":{"ImageLocality":"0","InterPodAffinity":"0","NodeAffinity":"0","NodeNumber":"0","NodeResourcesBalancedAllocation":"76","NodeResourcesFit":"73","PodTopologySpread":"0","TaintToleration":"0","VolumeBinding":"0"},"node-gp9t4":{"ImageLocality":"0","InterPodAffinity":"0","NodeAffinity":"0","NodeNumber":"0","NodeResourcesBalancedAllocation":"76","NodeResourcesFit":"73","PodTopologySpread":"0","TaintToleration":"0","VolumeBinding":"0"}}

Використовується для: Pod

Ця анотація записує результат роботи втулків планувальника score; використовується в https://sigs.k8s.io/kube-scheduler-simulator.

kube-scheduler-simulator.sigs.k8s.io/selected-node

Тип: Annotation

Приклад: kube-scheduler-simulator.sigs.k8s.io/selected-node: node-282x7

Використовується для: Pod

Ця анотація записує вузол, який обрано циклом планування; використовується в https://sigs.k8s.io/kube-scheduler-simulator.

kubernetes.io/arch

Тип: Label

Приклад: kubernetes.io/arch: "amd64"

Використовується для: Node

Kubelet заповнює це значення за допомогою runtime.GOARCH, як визначено в Go. Це може бути корисним, якщо ви використовуєте змішані вузли ARM і x86.

kubernetes.io/os

Тип: Label

Приклад: kubernetes.io/os: "linux"

Використовується для: Node, Pod

Для вузлів Kubelet заповнює це значення за допомогою runtime.GOOS, як визначено в Go. Це може бути корисним, якщо у вашому кластері використовуються різні операційні системи (наприклад, змішані вузли Linux і Windows).

Ви також можете встановити цю мітку на Pod. Kubernetes дозволяє встановлювати будь-яке значення для цієї мітки; якщо ви використовуєте цю мітку, ви все ж повинні встановити її на рядок Go runtime.GOOS для операційної системи, з якою працює цей Pod.

Якщо значення мітки kubernetes.io/os для Podʼа не відповідає значенню мітки на вузлі, Kubelet на цьому вузлі не прийме Pod. Проте це не враховується планувальником kube-scheduler. Крім того, Kubelet відмовляється запускати Pod, якщо ви вказали операційну систему Podʼа, яка не відповідає операційній системі вузла, на якому працює цей Kubelet. Більше деталей можна знайти в розділі Операційна система Podʼа.

kubernetes.io/metadata.name

Тип: Label

Приклад: kubernetes.io/metadata.name: "mynamespace"

Використовується для: Namespaces

API-сервер Kubernetes (частина панелі управління) встановлює цю мітку на всі простори імен. Значення мітки встановлюється на імʼя простору імен. Ви не можете змінити значення цієї мітки.

Це корисно, якщо ви хочете вказати конкретний простір імен за допомогою селектора міток.

kubernetes.io/limit-ranger

Тип: Annotation

Приклад: kubernetes.io/limit-ranger: "LimitRanger plugin set: cpu, memory request for container nginx; cpu, memory limit for container nginx"

Використовується для: Pod

Типово Kubernetes не надає жодних обмежень на ресурси, тобто, якщо ви явно не визначите обмеження, ваш контейнер може споживати необмежену кількість CPU та памʼяті. Ви можете визначити типовий запит або типове обмеження для Podʼів. Це робиться шляхом створення LimitRange у відповідному просторі імен. Podʼи, розгорнуті після визначення LimitRange, матимуть ці обмеження, застосовані до них. Анотація kubernetes.io/limit-ranger фіксує, що для Podʼа були вказані типові значення ресурсів і їх було успішно застосовано. Для детальнішої інформації читайте про LimitRanges.

kubernetes.io/config.hash

Тип: Annotation

Приклад: kubernetes.io/config.hash: "df7cc47f8477b6b1226d7d23a904867b"

Використовується для: Pod

Коли kubelet створює статичний Pod на основі заданого маніфесту, він додає цю анотацію до статичного Podʼа. Значення анотації — це UID Podʼа. Зверніть увагу, що kubelet також встановлює .spec.nodeName у поточне імʼя вузла, ніби Pod було заплановано на цей вузол.

kubernetes.io/config.mirror

Тип: Annotation

Приклад: kubernetes.io/config.mirror: "df7cc47f8477b6b1226d7d23a904867b"

Використовується для: Pod

Для статичного Podʼа, створеного kubelet на вузлі, на API-сервері створюється дзеркальний Pod. Kubelet додає анотацію, щоб позначити, що цей Pod фактично є дзеркальним Podʼом. Значення анотації копіюється з анотації kubernetes.io/config.hash, яка є UID Podʼа.

При оновленні Podʼа з цією встановленою анотацією анотацію не можна змінити або видалити. Якщо у Podʼа немає цієї анотації, її не можна додати під час оновлення Podʼа.

kubernetes.io/config.source

Тип: Annotation

Приклад: kubernetes.io/config.source: "file"

Використовується для: Pod

Ця анотація додається kubelet, щоб вказати, звідки походить Pod. Для статичних Podʼів значення анотації може бути одним із file або http, залежно від того, де розташований маніфест Podʼа. Для Podʼа, створеного на API-сервері, а потім запланованого на поточний вузол, значення анотації — api.

kubernetes.io/config.seen

Тип: Annotation

Приклад: kubernetes.io/config.seen: "2023-10-27T04:04:56.011314488Z"

Використовується для: Pod

Коли kubelet вперше бачить Pod, він може додати цю анотацію до Podʼа зі значенням поточного часу у форматі RFC3339.

addonmanager.kubernetes.io/mode

Тип: Label

Приклад: addonmanager.kubernetes.io/mode: "Reconcile"

Використовується для: Всі обʼєкти

Для вказання того, як слід керувати надбудовою, ви можете використовувати мітку addonmanager.kubernetes.io/mode. Ця мітка може мати одне з трьох значень: Reconcile, EnsureExists або Ignore.

• Reconcile: Ресурси надбудови періодично будуть зведені до очікуваного стану. Якщо є будь-які відмінності, менеджер надбудов буде створювати заново, змінювати конфігурацію або видаляти ресурси за потреби. Це типовий режим, якщо мітку не вказано.
• EnsureExists: Ресурси надбудов будуть перевірятися лише на наявність, але не будуть змінюватися після створення. Менеджер надбудов створить ресурси або створить їх заново, коли відсутній жоден екземпляр ресурсу з таким імʼям.
• Ignore: Ресурси надбудов будуть ігноруватися. Цей режим корисний для надбудов, які не сумісні з менеджером надбудов або керуються іншим контролером.

Для отримання докладнішої інформації див. Addon-manager.

beta.kubernetes.io/arch (deprecated)

Тип: Label

Ця мітка є застарілою. Використовуйте натомість kubernetes.io/arch.

beta.kubernetes.io/os (deprecated)

Тип: Label

Ця мітка є застарілою. Використовуйте натомість kubernetes.io/os.

kube-aggregator.kubernetes.io/automanaged

Тип: Label

Приклад: kube-aggregator.kubernetes.io/automanaged: "onstart"

Використовується для: APIService

kube-apiserver встановлює цю мітку для будь-якого обʼєкта APIService, який API-сервер створив автоматично. Мітка позначає, як панель управління повинна керувати цим APIService. Ви не повинні додавати, змінювати або видаляти цю мітку самостійно.

Є два можливих значення:

• onstart: APIService повинен бути зведений до очікуваного стану під час запуску API-сервера, але не під час інших операцій.
• true: API-сервер повинен безперервно зводити цей APIService до очікуваного стану.

service.alpha.kubernetes.io/tolerate-unready-endpoints (deprecated)

Тип: Annotation

Використовується для: Service

Ця анотація раніше використовувалася для вказівки, що контролер Endpoints повинен створювати Endpoints для неготових Podʼів. Починаючи з Kubernetes 1.11, кращим API для цієї функції є поле .publishNotReadyAddresses в Service. Ця анотація не має впливу в Kubernetes 1.37.

autoscaling.alpha.kubernetes.io/behavior (deprecated)

Тип: Annotation

Використовується для: HorizontalPodAutoscaler

Ця анотація використовувалася для налаштування поведінки масштабування для HorizontalPodAutoscaler (HPA) у попередніх версіях Kubernetes. Вона дозволяла вказати, як HPA має масштабувати Podʼи вгору або вниз, включаючи встановлення вікон стабілізації та політик масштабування. Встановлення цієї анотації не має жодного ефекту в будь-якому підтримуваному випуску Kubernetes.

kubernetes.io/hostname

Тип: Label

Приклад: kubernetes.io/hostname: "ip-172-20-114-199.ec2.internal"

Використовується для: Node

Kubelet заповнює цю мітку імʼям хоста вузла. Зверніть увагу, що імʼя хоста можна змінити відносно "фактичного" імені хоста за допомогою прапорця --hostname-override для kubelet.

Ця мітка також використовується як частина ієрархії топології. Дивіться topology.kubernetes.io/zone для отримання додаткової інформації.

kubernetes.io/change-cause

Тип: Annotation

Приклад: kubernetes.io/change-cause: "kubectl edit --record deployment foo"

Використовується для: Всі обʼєкти

Ця анотація містить найкраще припущення щодо того, чому щось було змінено.

Вона заповнюється при додаванні параметру --record до команди kubectl, яка може змінити обʼєкт.

kubernetes.io/description

Тип: Annotation

Приклад: kubernetes.io/description: "Description of K8s object."

Використовується для: Всі обʼєкти

Ця анотація використовується для опису конкретної поведінки вказаного обʼєкта.

kubernetes.io/enforce-mountable-secrets (deprecated)

Тип: Annotation

Приклад: kubernetes.io/enforce-mountable-secrets: "true"

Використовується для: ServiceAccount

Значення цієї анотації повинно бути true, щоб вона набула чинності. Коли ви встановлюєте цю анотацію у значення "true", Kubernetes застосовує наступні правила для Podʼів, що працюють з цим ServiceAccount:

1. Secretʼи, змонтовані як томи, повинні бути перелічені в полі secrets ServiceAccount.
2. Secretʼи, на які посилаються у полі envFrom для контейнерів (включно з sidecar-контейнерами та контейнерами ініціалізації), також повинні бути перелічені в полі secrets ServiceAccount. Якщо будь-який контейнер в Podʼі посилається на Secret, який не перелічений в полі secrets ServiceAccount (навіть якщо посилання позначене як optional), то Pod не запуститься, і буде згенеровано помилку, що вказує на невідповідне посилання на секрет.
3. Secretʼи, на які посилаються у полі imagePullSecrets Podʼа, повинні бути присутніми в полі imagePullSecrets ServiceAccount, Pod не запуститься, і буде згенеровано помилку, що вказує на невідповідне посилання на секрет для отримання образу.

Під час створення або оновлення Podʼа перевіряються ці правила. Якщо Pod не відповідає їм, він не запуститься, і ви побачите повідомлення про помилку. Якщо Pod уже працює, і ви змінюєте анотацію kubernetes.io/enforce-mountable-secrets на значення true, або ви редагуєте повʼязаний ServiceAccount для видалення посилання на Secret, який вже використовується Podʼом, Pod продовжить працювати.

node.alpha.kubernetes.io/ttl (deprecated)

Тип: Label

Приклад: node.alpha.kubernetes.io/ttl: "0"

Використовується для: Node

Ця мітка історично використовувалася деякими інструментами (такими як minikube) для встановлення значення часу існування вузлів. Мітка є застарілою і не повинна використовуватися в нових розгортаннях.

node.kubernetes.io/exclude-from-external-load-balancers

Тип: Label

Приклад: node.kubernetes.io/exclude-from-external-load-balancers

Використовується для: Node

Ви можете додати мітки до певних робочих вузлів, щоб виключити їх зі списку серверів бекенда, які використовуються зовнішніми балансувальниками навантаження. Наступна команда може бути використана для виключення робочого вузла зі списку серверів бекенда у наборі серверів бекенда:

kubectl label nodes <node-name> node.kubernetes.io/exclude-from-external-load-balancers=true

controller.kubernetes.io/pod-deletion-cost

Тип: Annotation

Приклад: controller.kubernetes.io/pod-deletion-cost: "10"

Використовується для: Pod

Ця анотація використовується для встановлення Вартості видалення Podʼа, що дозволяє користувачам впливати на порядок зменшення масштабування ReplicaSet. Значення анотації аналізується як тип int32.

cluster-autoscaler.kubernetes.io/enable-ds-eviction

Тип: Annotation

Приклад: cluster-autoscaler.kubernetes.io/enable-ds-eviction: "true"

Використовується для: Pod

Ця анотація контролює, чи повинен бути виселений Pod DaemonSet за допомогою ClusterAutoscaler. Ця анотація повинна бути вказана на Podʼах DaemonSet у маніфесті DaemonSet. Коли ця анотація встановлена в значення "true", ClusterAutoscaler може виселити Pod DaemonSet, навіть якщо інші правила зазвичай цьому запобігли б. Щоб заборонити ClusterAutoscaler виселяти Podʼи DaemonSet, ви можете встановити цю анотацію в значення "false" для важливих Podʼів DaemonSet. Якщо ця анотація не встановлена, тоді ClusterAutoscaler діє згідно зі своєю загальною поведінкою (тобто виселяє DaemonSet на основі своєї конфігурації).

kubernetes.io/ingress-bandwidth

Тип: Annotation

Приклад: kubernetes.io/ingress-bandwidth: 10M

Використовується для: Pod

Ви можете застосувати до Podʼа формування трафіку з урахуванням якості обслуговування та ефективно обмежити його доступну пропускну здатність. Вхідний трафік до Podʼа обробляється шляхом формування черги пакетів для ефективної обробки даних. Щоб обмежити пропускну здатність Podʼа, напишіть файл визначення обʼєкта JSON і вкажіть швидкість передачі даних за допомогою анотації kubernetes.io/ingress-bandwidth. Одиницею, яка використовується для вказівки швидкості вхідної передачі, є біти на секунду, в форматі Кількості. Наприклад, 10M означає 10 мегабіт на секунду.

kubernetes.io/egress-bandwidth

Тип: Annotation

Приклад: kubernetes.io/egress-bandwidth: 10M

Використовується для: Pod

Вихідний трафік з Podʼа обробляється за допомогою застосування політик, які просто відкидають пакети, що перевищують налаштовану швидкість. Обмеження, які ви встановлюєте на Pod, не впливають на пропускну здатність інших Podʼів. Щоб обмежити пропускну здатність Podʼа, напишіть файл визначення обʼєкта JSON і вкажіть швидкість передачі даних за допомогою анотації kubernetes.io/egress-bandwidth. Одиницею, яка використовується для вказівки швидкості вихідної передачі, є біти на секунду, в форматі Кількості. Наприклад, 10M означає 10 мегабіт на секунду.

beta.kubernetes.io/instance-type (deprecated)

Тип: Label

node.kubernetes.io/instance-type

Тип: Label

Приклад: node.kubernetes.io/instance-type: "m3.medium"

Використовується для: Node

Kubelet заповнює це значенням типу екземпляра, як визначено хмарним провайдером. Це буде встановлено лише в разі використання хмарного провайдера. Це налаштування є зручним, якщо ви хочете спрямувати певні робочі навантаження на певні типи екземплярів, але, як правило, ви хочете покладатися на планувальник Kubernetes для виконання планування на основі ресурсів. Ви повинні намагатися планувати на основі властивостей, а не на основі типів екземплярів (наприклад, потребувати GPU, замість потреби в g2.2xlarge).

failure-domain.beta.kubernetes.io/region (deprecated)

Тип: Label

failure-domain.beta.kubernetes.io/zone (deprecated)

Тип: Label

pv.kubernetes.io/bind-completed

Тип: Annotation

Приклад: pv.kubernetes.io/bind-completed: "yes"

Використовується для: PersistentVolumeClaim

Коли ця анотація встановлена на PersistentVolumeClaim (PVC), це вказує на те, що життєвий цикл PVC пройшов через початкове налаштування звʼязування. Коли вона присутня, ця інформація змінює те, як панель управління тлумачить стан обʼєктів PVC. Значення цієї анотації не має значення для Kubernetes.

pv.kubernetes.io/bound-by-controller

Тип: Annotation

Приклад: pv.kubernetes.io/bound-by-controller: "yes"

Використовується для: PersistentVolume, PersistentVolumeClaim

Якщо ця анотація встановлена на PersistentVolume або PersistentVolumeClaim, це вказує на те, що звʼязка зберігання (PersistentVolume → PersistentVolumeClaim або PersistentVolumeClaim → PersistentVolume) була встановлена контролером. Якщо анотація не встановлена, а звʼязка зберігання вже існує, відсутність цієї анотації означає, що звʼязка була встановлена вручну. Значення цієї анотації не має значення.

pv.kubernetes.io/provisioned-by

Тип: Annotation

Приклад: pv.kubernetes.io/provisioned-by: "kubernetes.io/rbd"

Використовується для: PersistentVolume

Ця анотація додається до PersistentVolume (PV), який був динамічно наданий Kubernetes. Її значення — це імʼя втулка тому, який створив том. Вона служить як користувачам (щоб показати, звідки походить PV), так і Kubernetes (щоб розпізнавати динамічно надані PV у своїх рішеннях).

pv.kubernetes.io/migrated-to

Тип: Annotation

Приклад: pv.kubernetes.io/migrated-to: pd.csi.storage.gke.io

Використовується для: PersistentVolume, PersistentVolumeClaim

Ця анотація додається до PersistentVolume (PV) та PersistentVolumeClaim (PVC), які мають бути динамічно надані або видалені відповідним драйвером CSI через функціональну можливість CSIMigration. Коли ця анотація встановлена, компоненти Kubernetes "відступають", і з обʼєктами працюватиме external-provisioner.

statefulset.kubernetes.io/pod-name

Тип: Label

Приклад: statefulset.kubernetes.io/pod-name: "mystatefulset-7"

Використовується для: Pod

Коли контролер StatefulSet створює Pod для StatefulSet, панель управління встановлює цю мітку на Podʼі. Значення мітки — це імʼя створеного Podʼа.

Дивіться Мітка імені Podʼа у темі StatefulSet для отримання більш детальної інформації.

scheduler.alpha.kubernetes.io/node-selector

Тип: Annotation

Приклад: scheduler.alpha.kubernetes.io/node-selector: "name-of-node-selector"

Використовується для: Namespace

PodNodeSelector використовує цей ключ анотації для призначення селекторів вузла до Podʼів у просторах імен.

topology.kubernetes.io/region

Тип: Label

Приклад: topology.kubernetes.io/region: "us-east-1"

Використовується для: Node, PersistentVolume

Див. topology.kubernetes.io/zone.

topology.kubernetes.io/zone

Тип: Label

Приклад: topology.kubernetes.io/zone: "us-east-1c"

Використовується для: Node, PersistentVolume

На Node: kubelet або зовнішній cloud-controller-manager заповнюють мітку інформацією від хмарного провайдера. Мітку буде встановлено лише в разі використання хмарного провайдера. Однак ви можете розглянути можливість встановлення її на вузлах, якщо це має сенс у вашій топології.

На PersistentVolume: засоби надання томів, що враховують топологію, автоматично встановлюють обмеження спорідненості вузла для PersistentVolume.

Зона представляє собою логічний домен відмови. Кластери Kubernetes зазвичай охоплюють декілька зон для підвищення доступності. Хоча точне визначення зони залишається на розсуд реалізацій інфраструктури, загальні властивості зон включають дуже низьку мережеву затримку всередині зони, відсутність вартості мережевого трафіку всередині зони та незалежність від відмов інших зон. Наприклад, вузли всередині зони можуть використовувати один мережевий комутатор, але вузли в різних зонах цього робити не повинні.

Регіон представляє собою більшу область, що складається з однієї або декількох зон. Кластери Kubernetes рідко охоплюють декілька регіонів. Хоча точне визначення зони або регіону залишається на розсуд реалізацій інфраструктури, загальні властивості регіону включають вищу мережеву затримку між регіонами, ніж всередині них, ненульову вартість мережевого трафіку між ними та незалежність від відмов інших зон або регіонів. Наприклад, вузли всередині регіону можуть використовувати спільну інфраструктуру живлення (наприклад, джерело безперебійного живлення або генератор), але вузли в різних регіонах зазвичай ні.

Kubernetes робить кілька припущень щодо структури зон та регіонів:

1. регіони та зони є ієрархічними: зони є строгими підмножинами регіонів, і жодна зона не може бути в двох регіонах;
2. імена зон є унікальними у всіх регіонах; наприклад, регіон "africa-east-1" може складатися з зон "africa-east-1a" та "africa-east-1b".

Можна безпечно припускати, що мітки топології не змінюються. Навіть якщо мітки є строго змінюваними, споживачі можуть припускати, що даний вузол не буде переміщений між зонами без знищення та перестворення.

Kubernetes може використовувати цю інформацію різними способами. Наприклад, планувальник автоматично намагається розподілити Podʼи в ReplicaSet по вузлах в однозонному кластері (щоб зменшити вплив відмови вузла, див. kubernetes.io/hostname). З кластерами, які охоплюють кілька зон, ця поведінка розподілу також застосовується до зон (для зменшення впливу відмови зони). Це досягається за допомогою SelectorSpreadPriority.

SelectorSpreadPriority — це розміщення за принципом найкращих зусиль (best effort). Якщо зони у вашому кластері є гетерогенними (наприклад, різна кількість вузлів, різні типи вузлів або різні вимоги Podʼів до ресурсів), це розміщення може завадити рівномірному розподілу ваших Podʼів між зонами. Якщо це потрібно, ви можете використовувати однорідні зони (однакова кількість і типи вузлів), щоб зменшити ймовірність нерівномірного розподілу.

Планувальник (за допомогою предиката VolumeZonePredicate) також буде забезпечувати, що Podʼи, які вимагають певного тома, будуть розміщені лише в тій же зоні, що й цей том. Томи не можуть бути підключені в різних зонах.

Якщо PersistentVolumeLabel не підтримує автоматичне додавання міток до ваших PersistentVolume, варто розглянути можливість додавання міток вручну (або додавання підтримки PersistentVolumeLabel). З PersistentVolumeLabel планувальник перешкоджає Podʼам монтувати томи в інших зонах. Якщо ваша інфраструктура не має цього обмеження, вам не потрібно додавати мітки зони до томів взагалі.

volume.alpha.kubernetes.io/node-affinity (deprecated)

Тип: Annotation

Використовується для: PersistentVolume

Ця анотація зберігала правила спорідненості вузла для PersistentVolume у вигляді серіалізованого в JSON обʼєкта NodeAffinity. Планувальник використовував ці правила для обмеження вузлів, які могли отримати доступ до тому.

Ця анотація застаріла починаючи з Kubernetes v1.10. Замість неї використовуйте поле nodeAffinity у специфікації PersistentVolume.

volume.beta.kubernetes.io/storage-provisioner (deprecated)

Тип: Annotation

Приклад: volume.beta.kubernetes.io/storage-provisioner: "k8s.io/minikube-hostpath"

Використовується для: PersistentVolumeClaim

Ця анотація застаріла починаючи з v1.23. Дивіться volume.kubernetes.io/storage-provisioner.

volume.beta.kubernetes.io/storage-class (deprecated)

Тип: Annotation

Приклад: volume.beta.kubernetes.io/storage-class: "example-class"

Використовується для: PersistentVolume, PersistentVolumeClaim

Ця анотація може використовуватися для PersistentVolume(PV) або PersistentVolumeClaim(PVC), щоб вказати імʼя StorageClass. Коли вказано і атрибут storageClassName, і анотацію volume.beta.kubernetes.io/storage-class, анотація volume.beta.kubernetes.io/storage-class має перевагу над атрибутом storageClassName.

Ця анотація застаріла. Замість цього встановіть поле storageClassName для PersistentVolumeClaim або PersistentVolume.

volume.beta.kubernetes.io/mount-options (deprecated)

Тип: Annotation

Приклад: volume.beta.kubernetes.io/mount-options: "ro,soft"

Використовується для: PersistentVolume

Адміністратор Kubernetes може вказати додаткові опції монтування, які застосовуються, коли PersistentVolume монтується на вузлі.

volume.kubernetes.io/storage-provisioner

Тип: Annotation

Використовується для: PersistentVolumeClaim

Ця анотація додається до PVC, яка має бути динамічно наданою. Її значення — це імʼя втулка тому, який має надати том для цієї PVC.

volume.kubernetes.io/selected-node

Тип: Annotation

Використовується для: PersistentVolumeClaim

Ця анотація додається до PVC, яка активується планувальником для динамічного надання. Її значення — це імʼя вибраного вузла.

volumes.kubernetes.io/controller-managed-attach-detach

Тип: Annotation

Використовується для: Node

Якщо вузол має анотацію volumes.kubernetes.io/controller-managed-attach-detach, його операції прикріплення та відʼєднання зберігання керуються контролером прикріплення/відʼєднання тому.

Значення анотації не має значення.

node.kubernetes.io/windows-build

Тип: Label

Приклад: node.kubernetes.io/windows-build: "10.0.17763"

Використовується для: Node

Коли kubelet працює на операційній системі Microsoft Windows, він автоматично позначає міткою свій вузол, щоб зафіксувати версію Windows Server, що використовується.

Значення мітки має формат "MajorVersion.MinorVersion.BuildNumber".

storage.alpha.kubernetes.io/migrated-plugins

Тип: Annotation

Приклад:storage.alpha.kubernetes.io/migrated-plugins: "kubernetes.io/cinder"

Використовується для: CSINode (API розширення)

Цю анотацію буде автоматично додано до обʼєкта CSINode, який зіставляється з вузлом, на якому встановлено CSIDriver. Ця анотація показує назву вбудованого втулка, який було перенесено. Її значення залежить від типу сховища вбудованого хмарного провайдера вашого кластера.

Наприклад, якщо тип зберігання вбудованого хмарного провайдера є CSIMigrationvSphere, обʼєкт CSINodes для вузла повинен бути оновлений наступним чином: storage.alpha.kubernetes.io/migrated-plugins: "kubernetes.io/vsphere-volume"

service.kubernetes.io/headless

Тип: Label

Приклад: service.kubernetes.io/headless: ""

Використовується для: EndpointSlice, Endpoints

Панель управління додає цю мітку до обʼєктів EndpointSlice та Endpoints, коли Service, якому вони належать, є headless (як підказка для проксі сервісів, що вони можуть ігнорувати ці точки доступу). Щоб дізнатися більше, прочитайте Headless Services.

service.kubernetes.io/topology-aware-hints (deprecated)

Приклад: service.kubernetes.io/topology-aware-hints: "Auto"

Використовується для: Service

Це застарілий аліас для анотації service.kubernetes.io/topology-mode, яка має таку саму функціональність.

service.kubernetes.io/topology-mode

Тип: Annotation

Приклад: service.kubernetes.io/topology-mode: Auto

Використовується для: Service

Ця анотація надає спосіб визначення того, як Serviceʼи обробляють топологію мережі; наприклад, ви можете налаштувати Service так, щоб Kubernetes віддавав перевагу збереженню трафіку між клієнтом і сервером в межах однієї топологічної зони. У деяких випадках це може допомогти зменшити витрати або покращити роботу мережі.

Дивіться Маршрутизація з урахуванням топології для отримання додаткових відомостей.

kubernetes.io/service-name

Тип: Label

Приклад: kubernetes.io/service-name: "my-website"

Використовується для: EndpointSlice

Kubernetes асоціює EndpointSlices з Services за допомогою цієї мітки.

Ця мітка записує імʼя Service, що його підтримує EndpointSlice. Усі EndpointSlices повинні мати цю мітку встановлену на імʼя їх повʼязаного Service.

kubernetes.io/service-account.name

Тип: Annotation

Приклад: kubernetes.io/service-account.name: "sa-name"

Використовується для: Secret

Ця анотація записує імʼя ServiceAccount, що його представляє токен (збережений у Secret типу kubernetes.io/service-account-token).

kubernetes.io/service-account.uid

Тип: Annotation

Приклад: kubernetes.io/service-account.uid: da68f9c6-9d26-11e7-b84e-002dc52800da

Використовується для: Secret

Ця анотація записує унікальний ідентифікатор ServiceAccount, що його представляє токен (збережений у Secret типу kubernetes.io/service-account-token).

kubernetes.io/legacy-token-last-used

Тип: Label

Приклад: kubernetes.io/legacy-token-last-used: 2022-10-24

Використовується для: Secret

Панель управління додає цю мітку лише до Secretʼів, які мають тип kubernetes.io/service-account-token. Значення цієї мітки записує дату (в форматі ISO 8601, в часовому поясі UTC), коли панель управління востаннє бачила запит, де клієнт автентифікувався за допомогою токена службового облікового запису.

Якщо легасі-токен використовувався останній раз до того, як кластер отримав цю функцію (додану у Kubernetes v1.26), то мітка не встановлена.

kubernetes.io/legacy-token-invalid-since

Тип: Label

Приклад: kubernetes.io/legacy-token-invalid-since: 2023-10-27

Використовується для: Secret

Панель управління автоматично додає цю мітку до автогенерованих Secretʼів з типом kubernetes.io/service-account-token. Ця мітка позначає токен на основі Secret як недійсний для автентифікації. Значення цієї мітки записує дату (в форматі ISO 8601, в часовому поясі UTC), коли панель управління виявляє, що автогенерований Secret не використовувався протягом вказаного періоду (типово — один рік).

endpoints.kubernetes.io/managed-by (deprecated)

Тип: Label

Приклад: endpoints.kubernetes.io/managed-by: endpoint-controller

Використовується для: Endpoints

Ця мітка використовується всередині Kubernetes для позначення обʼєктів Endpoints, які були створені Kubernetes (на відміну від Endpoints, створених користувачами чи зовнішніми контролерами).

endpointslice.kubernetes.io/managed-by

Тип: Label

Приклад: endpointslice.kubernetes.io/managed-by: endpointslice-controller.k8s.io

Використовується для: EndpointSlices

Ця мітка використовується для позначення контролера або сутності, яка керує EndpointSlice. Мета цієї мітки — забезпечити можливість керувати різними обʼєктами EndpointSlice різними контролерами або сутностями в межах одного та самого кластера. Значення endpointslice-controller.k8s.io вказує на обʼєкт EndpointSlice, який було створено автоматично Kubernetes для Service із селекторами.

endpointslice.kubernetes.io/skip-mirror

Тип: Label

Приклад: endpointslice.kubernetes.io/skip-mirror: "true"

Використовується для: Endpoints

Цю мітку можна встановити на значення "true" для ресурсу Endpoints, щоб позначити, що контролер EndpointSliceMirroring не повинен дублювати цей ресурс за допомогою EndpointSlices.

service.kubernetes.io/service-proxy-name

Тип: Label

Приклад: service.kubernetes.io/service-proxy-name: "foo-bar"

Використовується для: Service

Встановлення значення для цієї мітки вказує kube-proxy ігнорувати цей сервіс для проксіювання. Це дозволяє використовувати альтернативні реалізації проксі для цього сервісу (наприклад, запуск DaemonSet, який керує nftables своїм способом). Кілька альтернативних реалізацій проксі можуть бути активними одночасно, використовуючи це поле, наприклад, маючи унікальне значення для кожної альтернативної реалізації проксі, щоб відповідати за свої відповідні сервіси.

experimental.windows.kubernetes.io/isolation-type (deprecated)

Тип: Annotation

Приклад: experimental.windows.kubernetes.io/isolation-type: "hyperv"

Використовується для: Pod

Ця анотація використовується для запуску контейнерів Windows з ізоляцією Hyper-V.

gateway.networking.k8s.io/generator

Тип: Annotation

Приклад: gateway.networking.k8s.io/generator: "ingress2gateway"

Використовується для: Gateway, HTTPRoute та інші ресурси Gateway API

Ця анотація додається інструментами, які автоматично створюють ресурси Gateway API. Значення визначає інструмент, який створив ресурс (наприклад, ingress2gateway). Анотація є лише інформаційною і не впливає на поведінку жодної реалізації Gateway API.

ingressclass.kubernetes.io/is-default-class

Тип: Annotation

Приклад: ingressclass.kubernetes.io/is-default-class: "true"

Використовується для: IngressClass

Якщо ресурс IngressClass має цю анотацію встановлену на значення "true", новим ресурсам Ingress без вказаного класу буде призначено цей типовий клас.

kubernetes.io/ingress.class (deprecated)

Тип: Annotation

Використовується для: Ingress

kubernetes.io/cluster-service (deprecated)

Тип: Label

Приклад: kubernetes.io/cluster-service: "true"

Використовується для: Service

Ця мітка вказує на те, що Service надає послугу кластеру, якщо її значення встановлено у true. Коли ви запускаєте kubectl cluster-info, утиліта запитує Services, для яких цю мітку встановлено у значення true.

Втім, встановлення цієї мітки на будь-якому Service є застарілим.

storageclass.kubernetes.io/is-default-class

Тип: Annotation

Приклад: storageclass.kubernetes.io/is-default-class: "true"

Використовується для: StorageClass

Якщо один ресурс StorageClass має цю анотацію встановлену на значення "true", новим ресурсам PersistentVolumeClaim без вказаного класу буде призначено цей типовий клас.

alpha.kubernetes.io/provided-node-ip (alpha)

Тип: Annotation

Приклад: alpha.kubernetes.io/provided-node-ip: "10.0.0.1"

Використовується для: Node

Kubelet може встановити цю анотацію на вузлі, щоб вказати його налаштовану адресу IPv4 та/або IPv6.

Коли kubelet запускається з прапорцем --cloud-provider, встановленим на будь-яке значення (включно як із зовнішніми, так і з застарілими вбудованими хмарними провайдерами), він встановлює цю анотацію на вузлі, щоб вказати IP-адресу, встановлену прапорцем командного рядка (--node-ip). cloud-controller-manager перевіряє в хмарного провайдера, що ця IP-адреса є дійсною.

batch.kubernetes.io/job-completion-index

Тип: Annotation, Label

Приклад: batch.kubernetes.io/job-completion-index: "3"

Використовується для: Pod

Контролер Job у kube-controller-manager встановлює це як мітку та анотацію для Podʼів, створених з режимом завершення Indexed.

Зверніть увагу, що для того, щоб це було додано як мітку Podʼа, необхідно увімкнути функціональну можливість PodIndexLabel, інакше це буде просто анотацією.

batch.kubernetes.io/cronjob-scheduled-timestamp

Тип: Annotation

Приклад: batch.kubernetes.io/cronjob-scheduled-timestamp: "2016-05-19T03:00:00-07:00"

Використовується для: Jobs та Pods, що керуються через CronJobs

Ця анотація використовується для запису оригінального (очікуваного) часу створення для Job, коли цей Job є частиною CronJob. Панель управління встановлює значення цієї мітки часу у форматі RFC3339. Якщо Job належить до CronJob з вказаною часовою зоною, тоді мітка часу знаходиться в цій часовій зоні. В іншому випадку мітка часу відображається в локальному часі controller-manager.

cronjob.kubernetes.io/instantiate

Тип: Annotation

Приклад: cronjob.kubernetes.io/instantiate: "manual"

Використовується для: Jobs

Коли ви використовуєте kubectl create job з прапорцем --from=cronjob/<cronjob-name> для ручного створення Job з існуючого шаблону CronJob, kubectl встановлює цю анотацію на новостворений Job. Значення цієї анотації завжди дорівнює manual. Ця анотація дозволяє відрізнити Jobs, які були створені на вимогу користувача, від Jobs, які контролер CronJob автоматично створює у запланований час.

kubectl.kubernetes.io/default-container

Тип: Annotation

Приклад: kubectl.kubernetes.io/default-container: "front-end-app"

Значення анотації — це імʼя контейнера, яке є типовим для цього Podʼа. Наприклад, команди kubectl logs або kubectl exec без прапорця -c або --container використовуватимуть цей типовий контейнер.

kubectl.kubernetes.io/default-logs-container (deprecated)

Тип: Annotation

Приклад: kubectl.kubernetes.io/default-logs-container: "front-end-app"

Значення анотації — це імʼя контейнера, яке є типовим для логування для цього Podʼа. Наприклад, команда kubectl logs без прапорця -c або --container використовуватиме цей типовий контейнер.

kubectl.kubernetes.io/last-applied-configuration

Тип: Annotation

Приклад: дивіться наступний фрагмент

    kubectl.kubernetes.io/last-applied-configuration: >
      {"apiVersion":"apps/v1","kind":"Deployment","metadata":{"annotations":{},"name":"example","namespace":"default"},"spec":{"selector":{"matchLabels":{"app.kubernetes.io/name":foo}},"template":{"metadata":{"labels":{"app.kubernetes.io/name":"foo"}},"spec":{"containers":[{"image":"container-registry.example/foo-bar:1.42","name":"foo-bar","ports":[{"containerPort":42}]}]}}}}

Використовується для: Всі обʼєкти

Інструмент командного рядка kubectl використовує цю анотацію як застарілий механізм для відстеження змін. Цей механізм був замінений на Server-Side Apply.

kubectl.kubernetes.io/restartedAt

Тип: Annotation

Приклад: kubectl.kubernetes.io/restartedAt: "2024-06-21T17:27:41Z"

Використовується для: Deployment, ReplicaSet, StatefulSet, DaemonSet, Pod

Ця анотація містить останній час перезапуску ресурсу (Deployment, ReplicaSet, StatefulSet або DaemonSet), під час якого kubectl запустив розгортання для примусового створення нових Podʼів. Команда kubectl rollout restart <RESOURCE> ініціює перезапуск, змінюючи (patch) за допомогою цієї анотації метадані шаблону всіх Podʼів ресурсу. У наведеному вище прикладі останній час перезапуску показано як 21 червня 2024 року о 17:27:41 UTC.

Не слід вважати, що ця анотація відображає дату/час останнього оновлення; окремі зміни могли бути внесені з моменту останнього ручного розгортання.

Якщо ви вручну встановите цю анотацію на Pod, нічого не станеться. Побічний ефект перезапуску зумовлений тим, як працюють керування робочими навантаженнями та шаблони Podʼів.

endpoints.kubernetes.io/over-capacity (deprecated)

Тип: Annotation

Приклад: endpoints.kubernetes.io/over-capacity: truncated

Використовується для: Endpoints

Панель управління додає цю анотацію до обʼєкта Endpoints, якщо повʼязаний Service має понад 1000 точок доступу, що його забезпечують. Анотація вказує на те, що обʼєкт Endpoints перевищив ємність і кількість точок доступу була скорочена до 1000.

Якщо кількість точок доступу бекенду опускається нижче 1000, панель управління видаляє цю анотацію.

endpoints.kubernetes.io/last-change-trigger-time (deprecated)

Тип: Annotation

Приклад: endpoints.kubernetes.io/last-change-trigger-time: "2023-07-20T04:45:21Z"

Використовується для: Endpoints

Ця анотація встановлюється на обʼєкт Endpoints і представляє мітку часу (мітка часу зберігається у форматі рядка дати-часу RFC 3339. Наприклад, '2018-10-22T19:32:52.1Z'). Це мітка часу останньої зміни в деякому обʼєкті Pod або Service, яка спричинила зміну в обʼєкті Endpoints.

control-plane.alpha.kubernetes.io/leader (deprecated)

Тип: Annotation

Приклад: control-plane.alpha.kubernetes.io/leader={"holderIdentity":"controller-0","leaseDurationSeconds":15,"acquireTime":"2023-01-19T13:12:57Z","renewTime":"2023-01-19T13:13:54Z","leaderTransitions":1}

Використовується для: Endpoints

Панель управління раніше використовувала обʼєкт Endpoints для координації призначення лідера для панелі управління Kubernetes. Цей обʼєкт Endpoints містив анотацію з наступними деталями:

• Хто є поточним лідером.
• Час, коли було здобуто поточне лідерство.
• Тривалість оренди (лідерства) у секундах.
• Час, коли поточна оренда (поточне лідерство) повинна бути продовжена.
• Кількість переходів лідерства, які сталися у минулому.

Тепер Kubernetes використовує Leases для керування призначенням лідера для панелі управління Kubernetes.

batch.kubernetes.io/job-tracking (deprecated)

Тип: Annotation

Приклад: batch.kubernetes.io/job-tracking: ""

Використовується для: Jobs

Раніше наявність цієї анотації на обʼєкті Job вказувала на те, що панель управління відстежує статус Job за допомогою завершувачів. Додавання або видалення цієї анотації більше не має впливу (з версії Kubernetes v1.27 і пізніше). Всі Jobs відстежуються за допомогою завершувачів.

job-name (deprecated)

Тип: Label

Приклад: job-name: "pi"

Використовується для: Jobs та Pods, що керуються через Jobs

controller-uid (deprecated)

Тип: Label

Приклад: controller-uid: "$UID"

Використовується для: Jobs та Pods, що керуються через Jobs

batch.kubernetes.io/job-name

Тип: Label

Приклад: batch.kubernetes.io/job-name: "pi"

Використовується для: Jobs та Pods, що керуються через Jobs

Ця мітка використовується як зручний спосіб для отримання Podʼів, що належать Job. job-name походить від name Job і надає простий спосіб отримати Podʼи, що належать Job.

batch.kubernetes.io/controller-uid

Тип: Label

Приклад: batch.kubernetes.io/controller-uid: "$UID"

Використовується для: Jobs та Pods, що керуються через Jobs

Ця мітка використовується як програмний спосіб отримати всі Podʼи, що належать Job. controller-uid є унікальним ідентифікатором, який встановлюється в поле selector, щоб контролер Job міг отримати всі відповідні Podʼи.

scheduler.alpha.kubernetes.io/defaultTolerations

Тип: Annotation

Приклад: scheduler.alpha.kubernetes.io/defaultTolerations: '[{"operator": "Equal", "value": "value1", "effect": "NoSchedule", "key": "dedicated-node"}]'

Використовується для: Namespace

Ця анотація вимагає активування контролера допуску PodTolerationRestriction. Ключ цієї анотації дозволяє призначати tolerations для простору імен, і будь-які нові Podʼи, створені в цьому просторі імен, отримають ці tolerations.

scheduler.alpha.kubernetes.io/tolerationsWhitelist

Тип: Annotation

Приклад: scheduler.alpha.kubernetes.io/tolerationsWhitelist: '[{"operator": "Exists", "effect": "NoSchedule", "key": "dedicated-node"}]'

Використовується для: Namespace

Ця анотація корисна лише тоді, коли активований контролер допуску (Alpha) PodTolerationRestriction. Значення анотації — це JSON-документ, який визначає список дозволених tolerations для простору імен, який анотується. Під час створення Podʼа або зміни його tolerations API-сервер перевіряє tolerations, щоб переконатися, що вони згадуються у списку дозволених. Pod буде допущено лише у випадку успішної перевірки.

scheduler.alpha.kubernetes.io/preferAvoidPods (deprecated)

Тип: Annotation

Використовується для: Node

Ця анотація вимагає активації втулка планування NodePreferAvoidPods. Цей втулок застарів починаючи з Kubernetes 1.22. Замість цього використовуйте Taints та Tolerations.

node.kubernetes.io/not-ready

Тип: Taint

Приклад: node.kubernetes.io/not-ready: "NoExecute"

Використовується для: Node

Контролер Node визначає, чи готовий Node, відстежуючи стан його справності, і відповідно додає або видаляє цю позначку taint.

node.kubernetes.io/unreachable

Тип: Taint

Приклад: node.kubernetes.io/unreachable: "NoExecute"

Використовується для: Node

Контролер Node додає позначку taint на Node, у якого NodeCondition Ready має значення Unknown.

node.kubernetes.io/unschedulable

Тип: Taint

Приклад: node.kubernetes.io/unschedulable: "NoSchedule"

Використовується для: Node

Позначку taint буде додано до вузла під час його ініціалізації, щоб уникнути стану гонитви.

node.kubernetes.io/memory-pressure

Тип: Taint

Приклад: node.kubernetes.io/memory-pressure: "NoSchedule"

Використовується для: Node

Kubelet виявляє тиск на памʼять на основі значень memory.available і allocatableMemory.available, спостережуваних на вузлі. Потім спостережені значення порівнюються з відповідними пороговими значеннями, які можна встановити на kubelet, щоб визначити, чи потрібно додати / видалити умову вузла та позначку taint.

node.kubernetes.io/disk-pressure

Тип: Taint

Приклад: node.kubernetes.io/disk-pressure :"NoSchedule"

Використовується для: Node

Kubelet виявляє тиск на дискову памʼять на основі значень imagefs.available, imagefs.inodesFree, nodefs.available і nodefs.inodesFree (тільки для Linux), спостережуваних на вузлі. Потім спостережені значення порівнюються з відповідними пороговими значеннями, які можна встановити на kubelet, щоб визначити, чи потрібно додати / видалити умову вузла та позначку taint.

node.kubernetes.io/network-unavailable

Тип: Taint

Приклад: node.kubernetes.io/network-unavailable: "NoSchedule"

Використовується для: Node

Це спочатку встановлюється kubelet, коли використовуваний хмарний провайдер вказує на потребу в додатковій конфігурації мережі. Тільки коли маршрут у хмарі налаштований належним чином, хмарний провайдер видаляє позначку taint.

node.kubernetes.io/pid-pressure

Тип: Taint

Приклад: node.kubernetes.io/pid-pressure: "NoSchedule"

Використовується для: Node

Kubelet перевіряє D-значення розміру /proc/sys/kernel/pid_max та PID, використані Kubernetes на вузлі, щоб отримати кількість доступних PID, які вказуються метрикою pid.available. Потім цю метрику порівнюють з відповідним пороговим значенням, яке можна встановити на kubelet, щоб визначити, чи потрібно додати / видалити умову вузла та позначку taint.

node.kubernetes.io/out-of-service

Тип: Taint

Приклад: node.kubernetes.io/out-of-service:NoExecute

Використовується для: Node

Користувач може вручну додати позначку taint на вузол, позначивши його як виведений з експлуатації (out-of-service). Якщо вузол позначено як out-of-service за допомогою цієї позначки taint, Podʼи на вузлі буде примусово видалено, якщо вони не мають відповідних tolerations, а операції відʼєднання томів для Podʼів, що завершуються на вузлі, будуть виконані негайно. Це дозволяє Podʼам на виведеному з експлуатації вузлі швидко відновитися на іншому вузлі.

node.cloudprovider.kubernetes.io/uninitialized

Тип: Taint

Приклад: node.cloudprovider.kubernetes.io/uninitialized: "NoSchedule"

Використовується для: Node

Встановлює цю позначку taint на вузлі, щоб позначити його як непридатний для використання, коли kubelet запускається з "зовнішнім" хмарним провайдером, доки контролер з cloud-controller-manager не ініціалізує цей вузол і потім не прибере позначку taint.

node.cloudprovider.kubernetes.io/shutdown

Тип: Taint

Приклад: node.cloudprovider.kubernetes.io/shutdown: "NoSchedule"

Використовується для: Node

Якщо вузол перебуває у визначеному хмарним провайдером стані вимкнення, вузол отримує відповідну позначку taint node.cloudprovider.kubernetes.io/shutdown з ефектом NoSchedule.

feature.node.kubernetes.io/*

Тип: Label

Приклад: feature.node.kubernetes.io/network-sriov.capable: "true"

Використовується для: Node

Ці мітки використовуються компонентом виявлення функцій вузла (NFD), щоб оголошувати функції на вузлі. Усі вбудовані мітки використовують простір імен мітки feature.node.kubernetes.io та мають формат feature.node.kubernetes.io/<feature-name>: "true". NFD має багато точок розширення для створення міток, специфічних для постачальника або застосунку. Для отримання детальної інформації дивіться посібник з налаштування.

nfd.node.kubernetes.io/master.version

Тип: Annotation

Приклад: nfd.node.kubernetes.io/master.version: "v0.6.0"

Використовується для: Node

Для вузлів, на яких заплановано master виявлення функцій вузла (NFD), ця анотація записує версію майстра NFD. Вона використовується лише для інформаційних цілей.

nfd.node.kubernetes.io/worker.version

Тип: Annotation

Приклад: nfd.node.kubernetes.io/worker.version: "v0.4.0"

Використовується для: Nodes

Ця анотація записує версію робочого процесу виявлення функцій вузла (NFD), якщо він працює на вузлі. Вона використовується лише для інформаційних цілей.

nfd.node.kubernetes.io/feature-labels

Тип: Annotation

Приклад: nfd.node.kubernetes.io/feature-labels: "cpu-cpuid.ADX,cpu-cpuid.AESNI,cpu-hardware_multithreading,kernel-version.full"

Використовується для: Nodes

Ця анотація записує список міток функцій вузла, розділених комами, керованих виявленням функцій вузла (NFD). NFD використовує це для внутрішнього механізму. Ви не повинні редагувати цю анотацію самостійно.

nfd.node.kubernetes.io/extended-resources

Тип: Annotation

Приклад: nfd.node.kubernetes.io/extended-resources: "accelerator.acme.example/q500,example.com/coprocessor-fx5"

Використовується для: Nodes

Ця анотація зберігає розділений комами список розширених ресурсів, керованих виявленням функцій вузла (NFD). NFD використовує це для внутрішнього механізму. Ви не повинні редагувати цю анотацію самостійно.

nfd.node.kubernetes.io/node-name

Тип: Label

Приклад: nfd.node.kubernetes.io/node-name: node-1

Використовується для: Nodes

Мітка вказує, на який вузол націлений обʼєкт NodeFeature. Творці обʼєктів NodeFeature повинні встановлювати цю мітку, а споживачі обʼєктів повинні використовувати її для фільтрації функцій, призначених для певного вузла.

service.beta.kubernetes.io/aws-load-balancer-access-log-emit-interval (beta)

Приклад: service.beta.kubernetes.io/aws-load-balancer-access-log-emit-interval: "5"

Використовується для: Service

Інтеграція менеджера контролера хмарних служб з AWS Elastic Load Balancing налаштовує балансувальник навантаження для Service на основі цієї анотації. Значення визначає, як часто балансувальник навантаження записує записи логу. Наприклад, якщо ви встановите значення на 5, записи логу будуть відбуватися з інтервалом у 5 секунд.

service.beta.kubernetes.io/aws-load-balancer-access-log-enabled (beta)

Приклад: service.beta.kubernetes.io/aws-load-balancer-access-log-enabled: "false"

Використовується для: Service

Інтеграція менеджера контролера хмарних служб з AWS Elastic Load Balancing налаштовує балансувальник навантаження для Service на основі цієї анотації. Ведення логу доступу активується, якщо ви встановите анотацію на значення "true".

service.beta.kubernetes.io/aws-load-balancer-access-log-s3-bucket-name (beta)

Приклад: service.beta.kubernetes.io/aws-load-balancer-access-log-s3-bucket-name: example

Використовується для: Service

Інтеграція менеджера контролера хмарних служб з AWS Elastic Load Balancing налаштовує балансувальник навантаження для Service на основі цієї анотації. Балансувальник навантаження записує логи до корзини S3 з іменем, яке ви вказуєте.

service.beta.kubernetes.io/aws-load-balancer-access-log-s3-bucket-prefix (beta)

Приклад: service.beta.kubernetes.io/aws-load-balancer-access-log-s3-bucket-prefix: "/example"

Використовується для: Service

Інтеграція менеджера контролера хмарних служб з AWS Elastic Load Balancing налаштовує балансувальник навантаження для Service на основі цієї анотації. Балансувальник навантаження записує обʼєкти журналів з префіксом, який ви вказуєте.

service.beta.kubernetes.io/aws-load-balancer-additional-resource-tags (beta)

Приклад: service.beta.kubernetes.io/aws-load-balancer-additional-resource-tags: "Environment=demo,Project=example"

Використовується для: Service

Інтеграція менеджера контролера хмарних служб з AWS Elastic Load Balancing налаштовує теґи (концепція AWS) для балансувальника навантаження на основі розділених комами пар ключ/значення у значенні цієї анотації.

service.beta.kubernetes.io/aws-load-balancer-alpn-policy (beta)

Приклад: service.beta.kubernetes.io/aws-load-balancer-alpn-policy: HTTP2Optional

Використовується для: Service

Контролер балансувальника навантаження AWS використовує цю анотацію. Дивіться анотації у документації контролера балансувальника навантаження AWS.

service.beta.kubernetes.io/aws-load-balancer-attributes (beta)

Приклад: service.beta.kubernetes.io/aws-load-balancer-attributes: "deletion_protection.enabled=true"

Використовується для: Service

Контролер балансувальника навантаження AWS використовує цю анотацію. Для отримання додаткової інформації дивіться анотації у документації контролера балансувальника навантаження AWS.

service.beta.kubernetes.io/aws-load-balancer-backend-protocol (beta)

Приклад: service.beta.kubernetes.io/aws-load-balancer-backend-protocol: tcp

Використовується для: Service

Інтеграція менеджера контролера хмарних служб з AWS Elastic Load Balancing налаштовує прослуховувач балансувальника навантаження на основі значення цієї анотації.

service.beta.kubernetes.io/aws-load-balancer-connection-draining-enabled (beta)

Приклад: service.beta.kubernetes.io/aws-load-balancer-connection-draining-enabled: "false"

Використовується для: Service

Інтеграція менеджера контролера хмарних служб з AWS Elastic Load Balancing налаштовує балансувальник навантаження на основі цієї анотації. Налаштування connection draining балансувальника навантаження залежить від значення, яке ви встановлюєте.

service.beta.kubernetes.io/aws-load-balancer-connection-draining-timeout (beta)

Приклад: service.beta.kubernetes.io/aws-load-balancer-connection-draining-timeout: "60"

Використовується для: Service

Якщо ви налаштовуєте connection draining для Service з type: LoadBalancer, і ви використовуєте хмару AWS, інтеграція налаштовує період draining на основі цієї анотації. Значення, яке ви встановлюєте, визначає тайм-аут draining у секундах.

service.beta.kubernetes.io/aws-load-balancer-ip-address-type (beta)

Приклад: service.beta.kubernetes.io/aws-load-balancer-ip-address-type: ipv4

Використовується для: Service

Контролер балансувальника навантаження AWS використовує цю анотацію. Дивіться анотації у документації контролера балансувальника навантаження AWS.

service.beta.kubernetes.io/aws-load-balancer-connection-idle-timeout (beta)

Приклад: service.beta.kubernetes.io/aws-load-balancer-connection-idle-timeout: "60"

Використовується для: Service

Інтеграція менеджера контролера хмарних служб з AWS Elastic Load Balancing налаштовує балансувальник навантаження на основі цієї анотації. Балансувальник має налаштований період тайм-ауту бездіяльності (у секундах), який застосовується до його зʼєднань. Якщо протягом періоду тайм-ауту бездіяльності не було відправлено або отримано жодних даних, балансувальник закриває зʼєднання.

service.beta.kubernetes.io/aws-load-balancer-cross-zone-load-balancing-enabled (beta)

Приклад: service.beta.kubernetes.io/aws-load-balancer-cross-zone-load-balancing-enabled: "true"

Використовується для: Service

Інтеграція менеджера контролера хмарних служб з AWS Elastic Load Balancing налаштовує балансувальник навантаження на основі цієї анотації. Якщо ви встановите цю анотацію в значення "true", кожен вузол балансувальника навантаження розподіляє запити рівномірно серед зареєстрованих цілей у всіх увімкнених зонах доступності. Якщо ви вимкнете перехресне балансування зон, кожен вузол балансувальника навантаження розподіляє запити рівномірно серед зареєстрованих цілей лише у своїй зоні доступності.

service.beta.kubernetes.io/aws-load-balancer-eip-allocations (beta)

Приклад: service.beta.kubernetes.io/aws-load-balancer-eip-allocations: "eipalloc-01bcdef23bcdef456,eipalloc-def1234abc4567890"

Використовується для: Service

Інтеграція менеджера контролера хмарних служб з AWS Elastic Load Balancing налаштовує балансувальник навантаження на основі цієї анотації. Значення є розділеним комами списком ідентифікаторів виділення еластичних IP-адрес.

Ця анотація має сенс тільки для Service з type: LoadBalancer, де балансувальник навантаження є мережевим балансувальником AWS.

service.beta.kubernetes.io/aws-load-balancer-extra-security-groups (beta)

Приклад: service.beta.kubernetes.io/aws-load-balancer-extra-security-groups: "sg-12abcd3456,sg-34dcba6543"

Використовується для: Service

Інтеграція менеджера контролера хмарних служб з AWS Elastic Load Balancing налаштовує балансувальник навантаження на основі цієї анотації. Значення анотації є розділеним комами списком додаткових груп безпеки AWS VPC для налаштування балансувальника навантаження.

service.beta.kubernetes.io/aws-load-balancer-healthcheck-healthy-threshold (beta)

Приклад: service.beta.kubernetes.io/aws-load-balancer-healthcheck-healthy-threshold: "3"

Використовується для: Service

Інтеграція менеджера контролера хмарних служб з AWS Elastic Load Balancing налаштовує балансувальник навантаження на основі цієї анотації. Значення анотації визначає кількість послідовних успішних перевірок стану для бекенду, щоб вважати його справним для передавання трафіку.

service.beta.kubernetes.io/aws-load-balancer-healthcheck-interval (beta)

Приклад: service.beta.kubernetes.io/aws-load-balancer-healthcheck-interval: "30"

Використовується для: Service

Інтеграція менеджера контролера хмарних служб з AWS Elastic Load Balancing налаштовує балансувальник навантаження на основі цієї анотації. Значення анотації визначає інтервал, в секундах, між запитами перевірки стану, які виконує балансувальник навантаження.

service.beta.kubernetes.io/aws-load-balancer-healthcheck-path (beta)

Приклад: service.beta.kubernetes.io/aws-load-balancer-healthcheck-path: /healthcheck

Використовується для: Service

Інтеграція менеджера контролера хмарних служб з AWS Elastic Load Balancing налаштовує балансувальник навантаження на основі цієї анотації. Значення анотації визначає частину шляху URL, яка використовується для HTTP перевірок стану.

service.beta.kubernetes.io/aws-load-balancer-healthcheck-port (beta)

Приклад: service.beta.kubernetes.io/aws-load-balancer-healthcheck-port: "24"

Використовується для: Service

Інтеграція менеджера контролера хмарних служб з AWS Elastic Load Balancing налаштовує балансувальник навантаження на основі цієї анотації. Значення анотації визначає порт, до якого підключається балансувальник навантаження під час виконання перевірок стану.

service.beta.kubernetes.io/aws-load-balancer-healthcheck-protocol (beta)

Приклад: service.beta.kubernetes.io/aws-load-balancer-healthcheck-protocol: TCP

Використовується для: Service

Інтеграція менеджера контролера хмарних служб з AWS Elastic Load Balancing налаштовує балансувальник навантаження на основі цієї анотації. Значення анотації визначає спосіб, яким балансувальник навантаження перевіряє стан бекендів.

service.beta.kubernetes.io/aws-load-balancer-healthcheck-timeout (beta)

Приклад: service.beta.kubernetes.io/aws-load-balancer-healthcheck-timeout: "3"

Використовується для: Service

Інтеграція менеджера контролера хмарних служб з AWS Elastic Load Balancing налаштовує балансувальник навантаження на основі цієї анотації. Значення анотації вказує кількість секунд до того, як запит, який ще не вдався, автоматично вважається неуспішним.

service.beta.kubernetes.io/aws-load-balancer-healthcheck-unhealthy-threshold (beta)

Приклад: service.beta.kubernetes.io/aws-load-balancer-healthcheck-unhealthy-threshold: "3"

Використовується для: Service

Інтеграція менеджера контролера хмарних служб з AWS Elastic Load Balancing налаштовує балансувальник навантаження на основі цієї анотації. Значення анотації визначає кількість послідовних невдалих перевірок стану, необхідних для того, щоб бекенд вважався несправним для передавання трафіку.

service.beta.kubernetes.io/aws-load-balancer-internal (beta)

Приклад: service.beta.kubernetes.io/aws-load-balancer-internal: "true"

Використовується для: Service

Інтеграція менеджера контролера хмарних служб з AWS Elastic Load Balancing налаштовує балансувальник навантаження на основі цієї анотації. Коли ви встановлюєте цю анотацію у значення "true", інтеграція налаштовує внутрішній балансувальник навантаження.

Якщо ви використовуєте контролер балансувальника навантаження AWS, дивіться service.beta.kubernetes.io/aws-load-balancer-scheme.

service.beta.kubernetes.io/aws-load-balancer-manage-backend-security-group-rules (beta)

Приклад: service.beta.kubernetes.io/aws-load-balancer-manage-backend-security-group-rules: "true"

Використовується для: Service

Контролер балансувальника навантаження AWS використовує цю анотацію. Дивіться анотації у документації контролера балансувальника навантаження AWS.

service.beta.kubernetes.io/aws-load-balancer-name (beta)

Приклад: service.beta.kubernetes.io/aws-load-balancer-name: my-elb

Використовується для: Service

Якщо ви встановлюєте цю анотацію на Service, і також анотуєте цей Service з service.beta.kubernetes.io/aws-load-balancer-type: "external", і ви використовуєте контролер балансувальника навантаження AWS у вашому кластері, тоді контролер балансувальника навантаження AWS встановлює назву цього балансувальника на значення, яке ви встановлюєте для цієї анотації.

Дивіться анотації у документації контролера балансувальника навантаження AWS.

service.beta.kubernetes.io/aws-load-balancer-nlb-target-type (beta)

Приклад: service.beta.kubernetes.io/aws-load-balancer-nlb-target-type: "true"

Використовується для: Service

Контролер балансувальника навантаження AWS використовує цю анотацію. Дивіться анотації у документації контролера балансувальника навантаження AWS.

service.beta.kubernetes.io/aws-load-balancer-private-ipv4-addresses (beta)

Приклад: service.beta.kubernetes.io/aws-load-balancer-private-ipv4-addresses: "198.51.100.0,198.51.100.64"

Використовується для: Service

Контролер балансувальника навантаження AWS використовує цю анотацію. Дивіться анотації у документації контролера балансувальника навантаження AWS.

service.beta.kubernetes.io/aws-load-balancer-proxy-protocol (beta)

Приклад: service.beta.kubernetes.io/aws-load-balancer-proxy-protocol: "*"

Використовується для: Service

Офіційна інтеграція Kubernetes з AWS Elastic Load Balancing налаштовує балансувальник навантаження на основі цієї анотації. Єдине допустиме значення — "*", що вказує на те, що балансувальник навантаження повинен обгортати TCP-зʼєднання до Podʼа бекенду за допомогою протоколу PROXY.

service.beta.kubernetes.io/aws-load-balancer-scheme (beta)

Приклад: service.beta.kubernetes.io/aws-load-balancer-scheme: internal

Використовується для: Service

Контролер балансувальника навантаження AWS використовує цю анотацію. Дивіться анотації у документації контролера балансувальника навантаження AWS.

service.beta.kubernetes.io/aws-load-balancer-security-groups (deprecated)

Приклад: service.beta.kubernetes.io/aws-load-balancer-security-groups: "sg-53fae93f,sg-8725gr62r"

Використовується для: Service

Контролер балансувальника навантаження AWS використовує цю анотацію для вказівки розділеного комами списку груп безпеки, які ви хочете прикріпити до балансувальника навантаження AWS. Підтримуються як імʼя, так і ID груп безпеки, де імʼя відповідає тегу Name, а не атрибуту groupName.

Коли ця анотація додається до Service, контролер балансувальника навантаження прикріплює групи безпеки, на які вказує анотація, до балансувальника навантаження. Якщо ви пропускаєте цю анотацію, контролер балансувальника навантаження AWS автоматично створює нову групу безпеки і прикріплює її до балансувальника навантаження.

service.beta.kubernetes.io/load-balancer-source-ranges (deprecated)

Приклад: service.beta.kubernetes.io/load-balancer-source-ranges: "192.0.2.0/25"

Використовується для: Service

Контролер балансувальника навантаження AWS використовує цю анотацію. Вам слід встановити .spec.loadBalancerSourceRanges для Service замість цього.

service.beta.kubernetes.io/aws-load-balancer-ssl-cert (beta)

Приклад: service.beta.kubernetes.io/aws-load-balancer-ssl-cert: "arn:aws:acm:us-east-1:123456789012:certificate/12345678-1234-1234-1234-123456789012"

Використовується для: Service

Офіційна інтеграція з AWS Elastic Load Balancing налаштовує TLS для Service з type: LoadBalancer на основі цієї анотації. Значення анотації — це імʼя ресурсу AWS (ARN) сертифіката X.509, який повинен використовувати прослуховувач балансувальника навантаження.

(Протокол TLS базується на старішій технології, яку скорочено називають SSL.)

service.beta.kubernetes.io/aws-load-balancer-ssl-negotiation-policy (beta)

Приклад: service.beta.kubernetes.io/aws-load-balancer-ssl-negotiation-policy: ELBSecurityPolicy-TLS-1-2-2017-01

Офіційна інтеграція з AWS Elastic Load Balancing налаштовує TLS для Service з type: LoadBalancer на основі цієї анотації. Значення анотації — це імʼя політики AWS для узгодження TLS з клієнтом.

service.beta.kubernetes.io/aws-load-balancer-ssl-ports (beta)

Приклад: service.beta.kubernetes.io/aws-load-balancer-ssl-ports: "*"

Офіційна інтеграція з AWS Elastic Load Balancing налаштовує TLS для Service з type: LoadBalancer на основі цієї анотації. Значення анотації може бути або "*", що означає, що всі порти балансувальника навантаження повинні використовувати TLS, або це може бути розділений комами список номерів портів.

service.beta.kubernetes.io/aws-load-balancer-subnets (beta)

Приклад: service.beta.kubernetes.io/aws-load-balancer-subnets: "private-a,private-b"

Офіційна інтеграція Kubernetes з AWS використовує цю анотацію для налаштування балансувальника навантаження та визначення, в яких зонах доступності AWS розгорнути керовану службу балансування навантаження. Значення може бути або розділений комами список імен підмереж, або розділений комами список ідентифікаторів підмереж.

service.beta.kubernetes.io/aws-load-balancer-target-group-attributes (beta)

Приклад: service.beta.kubernetes.io/aws-load-balancer-target-group-attributes: "stickiness.enabled=true,stickiness.type=source_ip"

Використовується для: Service

Контролер балансувальника навантаження AWS використовує цю анотацію. Дивіться анотації у документації контролера балансувальника навантаження AWS.

service.beta.kubernetes.io/aws-load-balancer-target-node-labels (beta)

Приклад: service.beta.kubernetes.io/aws-load-balancer-target-node-labels: "kubernetes.io/os=Linux,topology.kubernetes.io/region=us-east-2"

Офіційна інтеграція Kubernetes з AWS використовує цю анотацію для визначення, які вузли у вашому кластері повинні бути розглянуті як дійсні цілі для балансувальника навантаження.

service.beta.kubernetes.io/aws-load-balancer-type (beta)

Приклад: service.beta.kubernetes.io/aws-load-balancer-type: external

Офіційні інтеграції Kubernetes з AWS використовують цю анотацію для визначення того, чи має інтеграція з хмарним провайдером AWS керувати Service з type: LoadBalancer.

Є два допустимі значення:

nlb

менеджер контролера хмарних послуг налаштовує мережевий балансувальник навантаження

external

менеджер контролера хмарних послуг не налаштовує жодного балансувальника навантаження

Якщо ви розгортаєте Service з type: LoadBalancer на AWS і не встановлюєте жодної анотації service.beta.kubernetes.io/aws-load-balancer-type, інтеграція з AWS розгортатиме класичний балансувальник навантаження Elastic Load Balancer. Ця поведінка, коли анотація відсутня, є типовою, якщо ви не вказуєте інше.

Коли ви встановлюєте цю анотацію на значення external на Service з type: LoadBalancer, а у вашому кластері є працююче розгортання контролера балансувальника навантаження AWS, то контролер балансувальника навантаження AWS намагатиметься розгорнути балансувальник навантаження на основі специфікації Service.

service.beta.kubernetes.io/azure-load-balancer-disable-tcp-reset (deprecated)

Приклад: service.beta.kubernetes.io/azure-load-balancer-disable-tcp-reset: "false"

Використовується для: Service

Ця анотація працює лише для Service, підтримуваних стандартним балансувальником навантаження Azure. Вона використовується у Service для вказівки, чи слід вимикати або вмикати скидання TCP при бездіяльності. Якщо увімкнено, це допомагає застосункам працювати більш передбачувано, виявляти обриви зʼєднання, видаляти застарілі зʼєднання та ініціювати нові. Ви можете встановити значення як true або false.

Дивіться Скидання TCP балансувальника навантаження для отримання додаткової інформації.

pod-security.kubernetes.io/enforce

Тип: Label

Приклад: pod-security.kubernetes.io/enforce: "baseline"

Використовується для: Namespace

Значення обовʼязково повинно бути одним із privileged, baseline або restricted, що відповідає рівням стандарту безпеки для Podʼів. Зокрема, мітка enforce забороняє створення будь-якого Podʼа у Namespace з цією міткою, який не відповідає вимогам, визначеним на вказаному рівні.

Для отримання додаткової інформації перегляньте Застосування безпеки Podʼів на рівні простору імен.

pod-security.kubernetes.io/enforce-version

Тип: Label

Приклад: pod-security.kubernetes.io/enforce-version: "1.37"

Використовується для: Namespace

Значення має бути latest або дійсною версією Kubernetes у форматі v<major>.<minor>. Це визначає версію політик стандарту безпеки для Podʼів, які застосовуються при перевірці Podʼа.

Для отримання додаткової інформації дивіться Застосування безпеки Podʼів на рівні простору імен.

pod-security.kubernetes.io/audit

Тип: Label

Приклад: pod-security.kubernetes.io/audit: "baseline"

Використовується для: Namespace

Значення має бути одним із privileged, baseline або restricted, що відповідають рівням стандарту безпеки для Podʼів. Зокрема, мітка audit не перешкоджає створенню Podʼа у Namespace з цією міткою, який не відповідає вимогам, визначеним на вказаному рівні, але додає цю анотацію до Podʼа.

Для отримання додаткової інформації дивіться Застосування безпеки Podʼів на рівні простору імен.

pod-security.kubernetes.io/audit-version

Тип: Label

Приклад: pod-security.kubernetes.io/audit-version: "1.37"

Використовується для: Namespace

Значення повинно бути latest або дійсною версією Kubernetes у форматі v<major>.<minor>. Це визначає версію політик стандарту безпеки для Podʼів, які застосовуються під час перевірки Podʼа.

Для отримання додаткової інформації дивіться Застосування безпеки Podʼів на рівні простору імен.

pod-security.kubernetes.io/warn

Тип: Label

Приклад: pod-security.kubernetes.io/warn: "baseline"

Використовується для: Namespace

Значення має бути одним із privileged, baseline або restricted, що відповідають рівням стандарту безпеки для Podʼів. Зокрема, мітка warn не перешкоджає створенню Podʼа у Namespace з цією міткою, який не відповідає вимогам, визначеним на вказаному рівні, але повертає попередження користувачу після цього. Зверніть увагу, що попередження також відображаються при створенні або оновленні обʼєктів, які містять шаблони Podʼа, такі як Deployments, Jobs, StatefulSets тощо.

Для отримання додаткової інформації дивіться Застосування безпеки Podʼів на рівні простору імен.

pod-security.kubernetes.io/warn-version

Тип: Label

Приклад: pod-security.kubernetes.io/warn-version: "1.37"

Використовується для: Namespace

Значення повинно бути latest або дійсною версією Kubernetes у форматі v<major>.<minor>. Це визначає версію політик стандарту безпеки для Podʼів, які застосовуються при перевірці поданих Podʼів. Зверніть увагу, що попередження також відображаються при створенні або оновленні обʼєктів, які містять шаблони Podʼа, такі як Deployments, Jobs, StatefulSets тощо.

Для отримання додаткової інформації дивіться Застосування безпеки Podʼів на рівні простору імен.

rbac.authorization.kubernetes.io/autoupdate

Тип: Annotation

Приклад: rbac.authorization.kubernetes.io/autoupdate: "false"

Використовується для: ClusterRole, ClusterRoleBinding, Role, RoleBinding

Коли ця анотація встановлена у значення "true" на типових обʼєктах RBAC, створених API-сервером, вони автоматично оновлюються при запуску сервера для додавання відсутніх дозволів та субʼєктів (додаткові дозволи та субʼєкти залишаються на місці). Щоб запобігти автоматичному оновленню певної ролі або привʼязки ролі, встановіть цю анотацію у значення "false". Якщо ви створюєте власні обʼєкти RBAC і встановлюєте цю анотацію у значення "false", kubectl auth reconcile (який дозволяє узгоджувати довільні обʼєкти RBAC у маніфесті) враховує цю анотацію і автоматично не додає відсутні дозволи та субʼєкти.

kubernetes.io/psp (deprecated)

Тип: Annotation

Приклад: kubernetes.io/psp: restricted

Використовується для: Pod

Ця анотація була актуальною лише у випадку використання обʼєктів PodSecurityPolicy. Kubernetes v1.37 не підтримує API PodSecurityPolicy.

Коли контролер допуску PodSecurityPolicy дав дозвіл Podʼу, він модифікував Pod так, щоб мати цю анотацію. Значення анотації було імʼям PodSecurityPolicy, яке використовувалось для валідації.

seccomp.security.alpha.kubernetes.io/pod (non-functional)

Тип: Annotation

Використовується для: Pod

Kubernetes до версії 1.25 дозволяв вам налаштовувати поведінку seccomp за допомогою цієї анотації. Див. Обмеження системних викликів контейнера за допомогою seccomp, щоб дізнатися підтримуваний спосіб вказування обмежень seccomp для Podʼа.

container.seccomp.security.alpha.kubernetes.io/[NAME] (non-functional)

Тип: Annotation

Використовується для: Pod

До версії 1.25 Kubernetes дозволяв налаштовувати поведінку seccomp за допомогою цієї анотації. Дивіться Обмеження системних викликів контейнера за допомогою seccomp, щоб дізнатися підтримуваний спосіб вказування обмежень seccomp для Podʼа.

snapshot.storage.kubernetes.io/allow-volume-mode-change

Тип: Annotation

Приклад: snapshot.storage.kubernetes.io/allow-volume-mode-change: "true"

Використовується для: VolumeSnapshotContent

Значення може бути або true, або false. Це визначає, чи може користувач змінювати режим джерельного тому при створенні PersistentVolumeClaim із VolumeSnapshot.

Зверніться до Зміна режиму тому знімка та Документації розробника Kubernetes CSI для отримання додаткової інформації.

scheduler.alpha.kubernetes.io/critical-pod (deprecated)

Тип: Annotation

Приклад: scheduler.alpha.kubernetes.io/critical-pod: ""

Використовується для: Pod

Ця анотація повідомляє панель управління Kubernetes, що Pod є критичним, щоб descheduler не видаляв цей Pod.

jobset.sigs.k8s.io/jobset-name

Тип: Label, Annotation

Приклад: jobset.sigs.k8s.io/jobset-name: "my-jobset"

Використовується для: Jobs, Pods

Ця мітка/анотація використовується для зберігання назви JobSet, до якого належить Job або Pod. JobSet — це API розширення, яке ви можете розгорнути у своєму кластері Kubernetes.

jobset.sigs.k8s.io/replicatedjob-replicas

Тип: Label, Annotation

Приклад: jobset.sigs.k8s.io/replicatedjob-replicas: "5"

Використовується для: Jobs, Pods

Ця мітка/анотація вказує на кількість реплік для ReplicatedJob.

jobset.sigs.k8s.io/replicatedjob-name

Тип: Label, Annotation

Приклад: jobset.sigs.k8s.io/replicatedjob-name: "my-replicatedjob"

Використовується для: Jobs, Pods

Ця мітка або анотація зберігає імʼя реплікованого завдання, частиною якого є цей Job або Pod.

jobset.sigs.k8s.io/job-index

Тип: Label, Annotation

Приклад: jobset.sigs.k8s.io/job-index: "0"

Використовується для: Jobs, Pods

Ця мітка/анотація встановлюється контролером JobSet для дочірніх Job і Podʼів. Вона містить індекс репліки Job у межах батьківського ReplicatedJob.

jobset.sigs.k8s.io/job-key

Тип: Label, Annotation

Приклад: jobset.sigs.k8s.io/job-key: "0f1e93893c4cb372080804ddb9153093cb0d20cefdd37f653e739c232d363feb"

Використовується для: Jobs, Pods

Контролер JobSet встановлює цю мітку (а також анотацію з тим самим ключем) на дочірніх Job і Podʼах JobSet. Значенням є хеш SHA256 імені Job разом із його простором імен.

alpha.jobset.sigs.k8s.io/exclusive-topology

Тип: Annotation

Приклад: alpha.jobset.sigs.k8s.io/exclusive-topology: "zone"

Використовується для: JobSets, Jobs

Ви можете встановити цю мітку/анотацію на JobSet, щоб забезпечити ексклюзивне розміщення Job для кожної топологічної групи. Ви також можете визначити цю мітку або анотацію в шаблоні реплікованого завдання. Щоб дізнатися більше, прочитайте документацію до JobSet.

alpha.jobset.sigs.k8s.io/node-selector

Тип: Annotation

Приклад: alpha.jobset.sigs.k8s.io/node-selector: "true"

Використовується для: Jobs, Pods

Ця мітка/анотація може бути застосована до JobSet. Коли вона встановлена, контролер JobSet змінює Job і відповідні їм Podʼи, додаючи селектори вузлів і tolerations. Це забезпечує ексклюзивне розміщення завдань у кожному домені топології, обмежуючи планування цих Podʼів конкретними вузлами на основі стратегії.

alpha.jobset.sigs.k8s.io/namespaced-job

Тип: Label

Приклад: alpha.jobset.sigs.k8s.io/namespaced-job: "default_myjobset-replicatedjob-0"

Використовується для: Nodes

Ця мітка встановлюється на вузлах вручну або автоматично (наприклад, кластерним автомасштабувальником). Коли alpha.jobset.sigs.k8s.io/node-selector встановлено у "true", контролер JobSet додає nodeSelector до цієї мітки вузла (разом із toleration до позначки taint alpha.jobset.sigs.k8s.io/no-schedule, описаної далі).

alpha.jobset.sigs.k8s.io/no-schedule

Тип: Taint

Приклад: alpha.jobset.sigs.k8s.io/no-schedule: "NoSchedule"

Використовується для: Nodes

Ця позначка taint встановлюється або вручну, або автоматично (наприклад, кластерним автомасштабувальником) на вузлах. Коли alpha.jobset.sigs.k8s.io/node-selector встановлено у "true", контролер JobSet додає toleration до цієї позначки taint вузла (разом із селектором вузла до мітки alpha.jobset.sigs.k8s.io/namespaced-job, описаної раніше).

jobset.sigs.k8s.io/coordinator

Тип: Annotation, Label

Приклад: jobset.sigs.k8s.io/coordinator: "myjobset-workers-0-0.headless-svc"

Використовується для: Jobs, Pods

Ця анотація/мітка використовується на Job та Podʼах для зберігання стабільної мережевої точки доступу, через яку можна звернутися до Podʼа координатора, якщо у специфікації JobSet визначено поле .spec.coordinator.

Анотації, що використовуються для аудиту

• authorization.k8s.io/decision
• authorization.k8s.io/reason
• insecure-sha1.invalid-cert.kubernetes.io/$hostname
• missing-san.invalid-cert.kubernetes.io/$hostname
• pod-security.kubernetes.io/audit-violations
• pod-security.kubernetes.io/enforce-policy
• pod-security.kubernetes.io/exempt
• validation.policy.admission.k8s.io/validation_failure

Дивіться більше деталей на сторінці Анотації аудиту.

kubeadm

kubeadm.alpha.kubernetes.io/cri-socket (deprecated)

Тип: Annotation

Приклад: kubeadm.alpha.kubernetes.io/cri-socket: unix:///run/containerd/container.sock

Використовується для: Node

kubeadm.kubernetes.io/etcd.advertise-client-urls

Тип: Annotation