Огляд 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.