Огляд API

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

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

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

Для отримання загальної інформації, читайте 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 або стабільного, якщо версія API рівня beta застаріє та більше не буде обслуговуватися.

  Примітка:

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

• Stable:

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

Групи API

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

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

• core (також називається legacy) група знаходиться за REST-шляхом /api/v1. Основна група не вказується як частина поля 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.