API Kubernetes

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

API Kubernetes дозволяє вам запитувати та змінювати стан обʼєктів API у Kubernetes (наприклад: Pods, Namespaces, ConfigMaps та Events).

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

Кожен кластер Kubernetes публікує специфікацію API, які він обслуговує. Kubernetes використовує два механізми для публікації цих специфікацій API; обидва корисні для забезпечення автоматичної сумісності. Наприклад, інструмент kubectl отримує та кешує специфікацію API для увімкнення функціонала автозавершення командного рядка та інших функцій. Нижче наведено два підтримувані механізми:

• Discovery API надає інформацію про API Kubernetes: назви API, ресурси, версії та операції, які підтримуються. Цей термін є специфічним для Kubernetes, оскільки це окремий API, відмінний від Kubernetes OpenAPI. Він задуманий як короткий огляд доступних ресурсів і не описує детальну схему ресурсів. Довідкові відомості про схеми ресурсів дивіться в документі OpenAPI.
• Документ Kubernetes OpenAPI надає (повні) схеми OpenAPI v2.0 та v3.0 для всіх точок доступу API Kubernetes. OpenAPI v3 є бажаним методом доступу до OpenAPI, оскільки він надає повніше й точніше подання API. Цей варіант містить всі можливі API-шляхи, так само як і всі ресурси, що використовуються та створюються для кожної операції на кожній точці доступу. Тут також є компоненти розширюваності, які підтримує кластер. Дані містять повну специфікацію та значно перевищують за обсягом те, що надає Discovery API.

Discovery API

Kubernetes публікує через Discovery API перелік усіх підтримуваних версій груп і ресурсів. Для кожного ресурсу він містить таке:

• Назва
• Область дії: кластер або простір імен
• URL точки доступу та підтримувані дієслова
• Альтернативні назви
• Група, версія, вид (kind)

API доступний як в агрегованому, так і в неагрегованому вигляді. Агреговане виявлення обслуговує дві точки доступу (endpoint), тоді як неагреговане — окрему точку доступу для кожної версії групи.

Агреговане виявлення

Kubernetes надає стабільну підтримку агрегованого виявлення, публікуючи всі ресурси, які підтримує кластер, через дві точки доступу (/api та /apis). Надсилання запиту до цієї точки доступу різко зменшує кількість запитів, потрібних для отримання даних виявлення з кластера. Ви можете отримати доступ до даних, надсилаючи запити до відповідних точок доступу із заголовком Accept, що вказує на ресурс агрегованого виявлення: Accept: application/json;v=v2;g=apidiscovery.k8s.io;as=APIGroupDiscoveryList.

Якщо тип ресурсу не вказано в заголовку Accept, стандартною відповіддю для точок доступу /api та /apis буде документ неагрегованого виявлення.

Документ виявлення для вбудованих ресурсів можна знайти в репозиторії Kubernetes GitHub. Цей документ GitHub можна використовувати як довідник базового набору доступних ресурсів, якщо кластер Kubernetes недоступний для запитів.

Точка доступу також підтримує ETag і кодування protobuf.

Неагреговане виявлення

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

Список усіх версій груп, підтримуваних кластером, публікується в точках доступу /api та /apis. Наприклад:

{
  "kind": "APIGroupList",
  "apiVersion": "v1",
  "groups": [
    {
      "name": "apiregistration.k8s.io",
      "versions": [
        {
          "groupVersion": "apiregistration.k8s.io/v1",
          "version": "v1"
        }
      ],
      "preferredVersion": {
        "groupVersion": "apiregistration.k8s.io/v1",
        "version": "v1"
      }
    },
    {
      "name": "apps",
      "versions": [
        {
          "groupVersion": "apps/v1",
          "version": "v1"
        }
      ],
      "preferredVersion": {
        "groupVersion": "apps/v1",
        "version": "v1"
      }
    },
    ...
  ]
}

Для отримання документа виявлення для кожної версії групи за адресою /apis/<group>/<version> (наприклад, /apis/rbac.authorization.k8s.io/v1alpha1) потрібні додаткові запити. Ці точки доступу оголошують список ресурсів, що обслуговуються певною версією групи. Ці точки доступу використовуються командою kubectl для отримання списку ресурсів, підтримуваних кластером.

Визначення інтерфейсу OpenAPI

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

Kubernetes працює як з OpenAPI v2.0, так і з OpenAPI v3.0. OpenAPI v3 є бажаним методом доступу до OpenAPI, оскільки він пропонує повніше (без втрат) представлення ресурсів Kubernetes. Через обмеження OpenAPI версії 2 певні поля видалено з опублікованого OpenAPI, включаючи, але не обмежуючись, default, nullable, oneOf.

OpenAPI V2

API-сервер Kubernetes надає агреговану специфікацію OpenAPI v2 через точку доступу /openapi/v2. Ви можете запросити формат відповіді, використовуючи такі заголовки запиту:

OpenAPI V3

Kubernetes підтримує публікацію опису своїх API у форматі OpenAPI v3.

Надається точка доступу /openapi/v3 для перегляду списку всіх доступних груп/версій. Ця точка повертає лише JSON. Ці групи/версії вказані в такому форматі:

{
    "paths": {
        ...,
        "api/v1": {
            "serverRelativeURL": "/openapi/v3/api/v1?hash=CC0E9BFD992D8C59AEC98A1E2336F899E8318D3CF4C68944C3DEC640AF5AB52D864AC50DAA8D145B3494F75FA3CFF939FCBDDA431DAD3CA79738B297795818CF"
        },
        "apis/admissionregistration.k8s.io/v1": {
            "serverRelativeURL": "/openapi/v3/apis/admissionregistration.k8s.io/v1?hash=E19CC93A116982CE5422FC42B590A8AFAD92CDE9AE4D59B5CAAD568F083AD07946E6CB5817531680BCE6E215C16973CD39003B0425F3477CFD854E89A9DB6597"
        },
        ....
    }
}

Відносні URL вказують на незмінний опис OpenAPI для поліпшення кешування на стороні клієнта. Також API-сервер встановлює відповідні заголовки кешування HTTP (Expires на 1 рік вперед та Cache-Control на immutable). При використанні застарілого URL API-сервер повертає перенаправлення на найновіший URL.

API-сервер Kubernetes публікує специфікацію OpenAPI v3 для кожної версії групи Kubernetes через точку доступу /openapi/v3/apis/<group>/<version>?hash=<hash>.

Дивіться таблицю нижче для прийнятних заголовків запиту.

Реалізація Golang для отримання OpenAPI V3 надається в пакунку k8s.io/client-go/openapi3.

Kubernetes 1.37 публікує OpenAPI v2.0 та v3.0; найближчим часом підтримка 3.1 не планується.

Серіалізація Protobuf

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

Постійне зберігання

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

Групи API та версіювання

Щоб полегшити видалення полів або перебудову представлень ресурсів, Kubernetes підтримує кілька версій API, кожна з різним API-шляхом, таким як /api/v1 або /apis/rbac.authorization.k8s.io/v1alpha1.

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

Щоб полегшити еволюцію та розширення свого API, Kubernetes реалізує групи API, які можна увімкнути або вимкнути.

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

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

Зміни в API

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

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

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

Якщо ви використовуєте бета-версію API, вам слід перейти до наступної бета- або стабільної версії API, як тільки це API стане стабільним (GA). Найкращий час для цього — під час періоду застарівання бета-API, оскільки обʼєкти одночасно доступні через обидві версії API. Як тільки бета-API завершить свій період застарівання і більше не буде обслуговуватися, слід використовувати версію API, яка його замінює.

Дивіться довідник з версій API для отримання докладнішої інформації про визначення рівня API.

Розширення API

API Kubernetes можна розширити одним з двох способів:

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

Що далі

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