Власні Ресурси

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

Власні ресурси

Ресурс — це точка доступу в API Kubernetes, яка зберігає колекцію обʼєктів API певного виду; наприклад, вбудований ресурс pods містить колекцію обʼєктів Pod.

Власний ресурс — це розширення API Kubernetes, яке не обовʼязково доступне в типовій установці Kubernetes. Він представляє собою налаштування конкретного встановлення Kubernetes. Однак багато основних функцій Kubernetes тепер побудовані з використанням власних ресурсів, що робить Kubernetes більш модульним.

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

Власні контролери

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

Декларативний API Kubernetes забезпечує розділення обовʼязків. Ви оголошуєте бажаний стан вашого ресурсу. Контролер Kubernetes підтримує поточний стан обʼєктів Kubernetes відповідно до вашого оголошеного бажаного стану. Це відрізняється від імперативного API, де ви вказуєте серверу, що робити.

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

Чи слід додавати власний ресурс до мого кластера Kubernetes?

При створенні нового API розгляньте можливість агрегування вашого API з API кластера Kubernetes або дозвольте вашому API залишитися незалежним.

Розгляньте агрегацію API, якщо:Віддайте перевагу незалежному API, якщо:
Ваш API є Декларативним.Ваш API не відповідає моделі Декларативного API.
Ви хочете, щоб ваші нові типи були доступні для читання та запису за допомогою kubectl.Підтримка kubectl не є необхідною.
Ви хочете бачити свої нові типи в UI Kubernetes, такому як панель управління, поряд з вбудованими типами.Підтримка UI Kubernetes не є необхідною.
Ви розробляєте новий API.Ви вже маєте програму, яка обслуговує ваш API та працює добре.
Ви готові прийняти обмеження формату, які Kubernetes накладає на шляхи REST ресурсів, такі як групи API та простори імен. (Дивіться Огляд API.)Вам потрібні специфічні шляхи REST для сумісності з уже визначеним REST API.
Ваші ресурси природно обмежені кластером або просторами імен кластера.Ресурси, обмежені кластером або простором імен, погано підходять; вам потрібен контроль над специфікою шляхів ресурсів.
Ви хочете повторно використовувати функції підтримки API Kubernetes.Вам не потрібні ці функції.

Декларативні API

У декларативному API зазвичай:

  • Ваш API складається з відносно невеликої кількості відносно невеликих обʼєктів (ресурсів).
  • Обʼєкти визначають конфігурацію застосунків або інфраструктури.
  • Обʼєкти оновлюються відносно рідко.
  • Люди часто мають читати та записувати обʼєкти.
  • Основні операції з обʼєктами — це CRUD (створення, читання, оновлення та видалення).
  • Транзакції між обʼєктами не потрібні: API представляє бажаний стан, а не точний стан.

Імперативні API не є декларативними. Ознаки того, що ваш API може не бути декларативним, включають:

  • Клієнт каже "зробіть це", і потім отримує синхронну відповідь, коли це виконано.
  • Клієнт каже "зробіть це", а потім отримує ідентифікатор операції назад і повинен перевірити окремий обʼєкт операції, щоб визначити завершення запиту.
  • Ви говорите про виклики віддалених процедур (RPC).
  • Пряме зберігання великої кількості даних; наприклад, > кілька кБ на обʼєкт, або > 1000 обʼєктів.
  • Потрібен високий доступ до пропускної здатності (десятки запитів на секунду тривалий час).
  • Збереження даних кінцевого користувача (наприклад, зображень, PII тощо) або інших великих обсягів даних, оброблених застосунками.
  • Природні операції з обʼєктами не є CRUD-подібними.
  • API не легко моделюється як обʼєкти.
  • Ви вибрали представлення очікуючих операцій за допомогою ідентифікатора операції або обʼєкта операції.

Чи слід використовувати ConfigMap або власний ресурс?

Використовуйте ConfigMap, якщо застосовується будь-який з наступних пунктів:

  • Існує вже відомий, добре задокументований формат файлу конфігурації, такий як mysql.cnf або pom.xml.
  • Ви хочете помістити всю конфігурацію в один ключ ConfigMap.
  • Основне використання файлу конфігурації — для програми, що працює у Pod у вашому кластері, для використання файлу для самоналаштування.
  • Споживачі файлу вважають за краще отримувати його через файл у Pod або змінну оточення у Pod, а не через Kubernetes API.
  • Ви хочете виконувати послідовне оновлення за допомогою Deployment тощо, коли файл оновлюється.

Використовуйте власний ресурс (CRD або Aggregated API), якщо застосовується більшість з наступних пунктів:

  • Ви хочете використовувати бібліотеки та CLI Kubernetes для створення та оновлення нового ресурсу.
  • Ви хочете отримати підтримку на вищому рівні від kubectl; наприклад, kubectl get my-object object-name.
  • Ви хочете побудувати нову автоматизацію, яка стежить за оновленнями нового обʼєкта, а потім виконує CRUD інших обʼєктів, або навпаки.
  • Ви хочете написати автоматизацію, яка обробляє оновлення обʼєкта.
  • Ви хочете використовувати конвенції Kubernetes API, такі як .spec, .status, та .metadata.
  • Ви хочете, щоб обʼєкт був абстракцією над колекцією контрольованих ресурсів або узагальненням інших ресурсів.

Додавання власних ресурсів

Kubernetes надає два способи додавання власних ресурсів до вашого кластера:

  • CRD (Custom Resource Definition) є простим і може бути створений без будь-якого програмування.
  • API Aggregation потребує програмування, але надає більший контроль над поведінкою API, такою як зберігання даних та конвертація між версіями API.

Kubernetes надає ці два варіанти, щоб задовольнити потреби різних користувачів, щоб ні зручність використання, ні гнучкість не зазнавали утисків.

Агреговані API є підлеглими API-серверами, які розташовані позаду основного API-сервера, який діє як проксі. Ця організація називається API Aggregation(AA). Для користувачів API Kubernetes виглядає розширеним.

CRD дозволяють користувачам створювати нові типи ресурсів без додавання іншого API-сервера. Вам не потрібно розуміти API Aggregation, щоб використовувати CRD.

Незалежно від того, як вони встановлені, нові ресурси називаються Custom Resources, щоб відрізняти їх від вбудованих ресурсів Kubernetes (наприклад, Pod).

CustomResourceDefinitions

API-ресурс CustomResourceDefinition дозволяє вам визначати власні ресурси. Визначення обʼєкта CRD створює новий власний ресурс з імʼям і схемою, яку ви вказуєте. API Kubernetes обслуговує та обробляє зберігання вашого власного ресурсу. Назва самого обʼєкта CRD повинна бути дійсною назвою піддомену DNS, утвореною від визначеної назви ресурсу та його API групи; для детальнішої інформації дивіться як створити CRD. Крім того, назва обʼєкта, чий тип/ресурс визначається CRD, також повинна бути дійсною назвою піддомену DNS.

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

Для прикладу того, як зареєструвати новий власний ресурс, для роботи з екземплярами вашого нового типу ресурсу та використовувати контролер для обробки подій, дивіться приклад власного контролера.

Агрегація сервера API

Зазвичай кожен ресурс в API Kubernetes вимагає коду, який обробляє REST-запити та керує постійним зберіганням обʼєктів. Основний сервер API Kubernetes обробляє вбудовані ресурси, такі як Pod та Service, а також узагальнено може керувати власними ресурсами через CRD.

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

Вибір методу для додавання власних ресурсів

CRD простіші у використанні. Агреговані API більш гнучкі. Виберіть метод, який найкраще відповідає вашим потребам.

Зазвичай CRD підходять, якщо:

  • У вас багато полів.
  • Ви використовуєте ресурс у своїй компанії або як частину невеликого відкритого проєкту (на відміну від комерційного продукту).

Порівняння простоти використання

Створення CRD простіше, ніж Aggregated APIs.

CRDAggregated API
Не потребує програмування. Користувачі можуть вибрати будь-яку мову для контролера CRD.Вимагає програмування та створення бінарного файлу та образу.
Немає додаткової служби для запуску; CRD обробляються сервером API.Додаткова служба для створення, яка може зазнати невдачі.
Немає підтримки після створення CRD. Будь-які виправлення помилок виконуються як частина звичайних оновлень майстра Kubernetes.Може вимагати періодичного отримування виправлення помилок від постачальника та перебудови та оновлення сервера Aggregated API.
Не потрібно керувати декількома версіями вашого API; наприклад, коли ви контролюєте клієнта для цього ресурсу, ви можете оновлювати його синхронно з API.Потрібно керувати декількома версіями вашого API; наприклад, коли розробляєте розширення для спільного використання.

Розширені функції та гнучкість

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

ФункціяОписCRDAggregated API
ВалідаціяДопомагає користувачам уникати помилок та дозволяє вам самостійно розвивати ваше API незалежно від ваших клієнтів. Ці функції найбільш корисні, коли є багато клієнтів, які не можуть всі одночасно оновлюватися.Так. Більшість валідацій можуть бути вказані у CRD за допомогою валідації OpenAPI v3.0. Можливість CRDValidationRatcheting дозволяє ігнорувати валідації, вказані за допомогою OpenAPI, якщо збійна частина ресурсу не була змінена. Будь-яка інша валідація підтримується за допомогою Вебхука валідації.Так, довільні перевірки валідації
Стандартне значенняДив. вищеТак, або через валідацію OpenAPI v3.0 за допомогою ключового слова default (GA в 1.17), або через Вебхук мутації (хоча це не буде виконано при зчитуванні з etcd для старих обʼєктів).Так
МультиверсіонністьДозволяє обслуговувати той самий обʼєкт через дві версії API. Може допомогти спростити зміни API, такі як перейменування полів. Менш важливо, якщо ви контролюєте версії вашого клієнта.ТакТак
Власне сховищеЯкщо вам потрібне сховище з іншим режимом продуктивності (наприклад, база даних часових рядів замість сховища ключ-значення) або ізоляція для безпеки (наприклад, шифрування конфіденційної інформації тощо).НемаєТак
Власна бізнес-логікаВиконуйте довільні перевірки або дії при створенні, читанні, оновленні або видаленні обʼєктаТак, за допомогою Вебхуків.Так
Масштабування SubresourceДозволяє системам, таким як HorizontalPodAutoscaler та PodDisruptionBudget, взаємодіяти з вашим новим ресурсомТакТак
Статус SubresourceДозволяє деталізований контроль доступу, де користувач записує розділ spec, а контролер записує розділ status. Дозволяє інкрементувати Generation обʼєкту при мутації даних власного ресурсу (вимагає окремих розділів spec та status у ресурсі).ТакТак
Інші SubresourcesДодавання операцій крім CRUD, таких як "logs" або "exec".НемаєТак
strategic-merge-patchНові точки доступу підтримують PATCH з Content-Type: application/strategic-merge-patch+json. Корисно для оновлення обʼєктів, які можуть бути змінені як локально, так і сервером. Докладніше див. "Оновлення обʼєктів API на місці за допомогою kubectl patch"НемаєТак
Protocol BuffersНовий ресурс підтримує клієнтів, які хочуть використовувати Protocol BuffersНемаєТак
Схема OpenAPIЧи є схема OpenAPI (swagger) для типів, які можуть бути динамічно завантажені з сервера? Чи захищений користувач від помилок у написанні назв полів, забезпечуючи, що лише дозволені поля встановлені? Чи використовуються типи (іншими словами, не розміщуйте int в string полі?)Так, на основі схеми валідації OpenAPI v3.0 (GA в 1.16).Так
Назва екземпляраЧи накладає цей механізм розширення будь-які обмеження на назви обʼєктів, тип/ресурс яких визначено таким чином?Так, назва такого обʼєкта повинна бути дійсною назвою піддомену DNS.Ні

Загальні функції

При створенні власного ресурсу, будь-то через CRD або AA, ви отримуєте багато функцій для вашого API порівняно з його втіленням поза платформою Kubernetes:

ФункціяОпис
CRUDНові точки доступу підтримують CRUD базові операції через HTTP та kubectl
WatchНові точки доступу підтримують операції Watch Kubernetes через HTTP
DiscoveryКлієнти, такі як kubectl та інтерфейс, автоматично пропонують операції list, display та edit для полів у ваших ресурсах
json-patchНові точки доступу підтримують PATCH з Content-Type: application/json-patch+json
merge-patchНові точки доступу підтримують PATCH з Content-Type: application/merge-patch+json
HTTPSНові точки доступу використовують HTTPS
Вбудована автентифікаціяДоступ до розширення використовує ядро сервера API (рівень агрегації) для автентифікації
Вбудована авторизаціяДоступ до розширення може використовувати авторизацію, яка використовується ядром сервера API; наприклад, RBAC.
FinalizersБлокування видалення ресурсів розширення до тих пір, поки не відбудеться зовнішнє очищення.
Admission WebhooksВстановлення стандартних значень та валідація ресурсів розширення під час будь-якої операції створення/оновлення/видалення.
Відображення в інтерфейсі/CLIKubectl, інтерфейс можуть відображати ресурси розширення.
Не встановлено чи ПорожньоКлієнти можуть розрізняти невстановлені поля від полів з нульовим значенням.
Генерація бібліотек клієнтівKubernetes надає загальні бібліотеки клієнтів, а також інструменти для генерації бібліотек клієнтів для конкретних типів даних.
Мітки та анотаціїЗагальні метадані між обʼєктами, для яких інструменти знають, як їх редагувати для основних та власних ресурсів.

Підготовка до встановлення власного ресурсу

Перш ніж додавати власний ресурс до вашого кластера, слід врахувати кілька моментів.

Код від сторонніх розробників та нові точки відмов

Створення CRD не автоматично додає будь-які нові точки відмов (наприклад, за допомогою запуску коду сторонніх розробників на вашому сервері API), проте пакети (наприклад, Charts) або інші збірники для встановлення часто включають CRD, а також Deployment з кодом сторонніх розробників, який реалізує бізнес-логіку для нового власного ресурсу.

Встановлення агрегованого сервера API завжди передбачає запуск нового Deployment.

Зберігання

Власні ресурси споживають місце зберігання так само як і ConfigMaps. Створення занадто великих власних ресурсів може перевантажити простір зберігання сервера API.

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

Автентифікація, авторизація та аудит

CRD завжди використовують ту саму автентифікацію, авторизацію та ведення аудиту, що й вбудовані ресурси вашого сервера API.

Якщо ви використовуєте RBAC для авторизації, більшість ролей RBAC не надають доступ до нових ресурсів (окрім ролі cluster-admin або будь-якої ролі, створеної з шаблонами). Вам потрібно явно надати доступ до нових ресурсів. CRD та агреговані сервери API часто постачаються з новими визначеннями ролей для типів, які вони додають.

Агреговані сервери API можуть або не можуть використовувати ту саму автентифікацію, авторизацію та ведення аудиту, що й основний сервер API.

Доступ до власного ресурсу

Бібліотеки клієнтів Kubernetes можна використовувати для доступу до власних ресурсів. Не всі бібліотеки клієнтів підтримують власні ресурси. Go та Python бібліотеки клієнтів це роблять.

Після додавання власного ресурсу ви можете отримати до нього доступ за допомогою:

  • kubectl
  • Динамічного клієнта Kubernetes.
  • REST-клієнта, який ви напишете.
  • Клієнта, згенерованого за допомогою інструментів генерації клієнта Kubernetes (генерація є складним завданням, але деякі проєкти можуть постачати клієнтів разом з CRD або AA).

Селектори полів власних ресурсів

Селектори полів дозволяють клієнтам вибирати власні ресурси за значенням полів одного чи більше ресурсів.

Всі власні ресурси підтримують селектори полів metadata.name та metadata.namespace.

Поля оголошені у CustomResourceDefinition можуть бути використані з селекторами полів, коли вони вказані у полі spec.versions[*].selectableFields в CustomResourceDefinition.

Поля власних ресурсів, які підтримуються селекторами

СТАН ФУНКЦІОНАЛУ: Kubernetes v1.32 [stable] (стандартно увімкнено: true)

Поле spec.versions[*].selectableFields в CustomResourceDefinition може бути використане для вказівки, які інші поля в власному ресурсі можуть бути використані в полях селекторів.

Наступний приклад додає поля .spec.color та .spec.size, як поля які можна вибирати.

apiVersion: apiextensions.k8s.io/v1
kind: CustomResourceDefinition
metadata:
  name: shirts.stable.example.com
spec:
  group: stable.example.com
  scope: Namespaced
  names:
    plural: shirts
    singular: shirt
    kind: Shirt
  versions:
  - name: v1
    served: true
    storage: true
    schema:
      openAPIV3Schema:
        type: object
        properties:
          spec:
            type: object
            properties:
              color:
                type: string
              size:
                type: string
    selectableFields:
    - jsonPath: .spec.color
    - jsonPath: .spec.size
    additionalPrinterColumns:
    - jsonPath: .spec.color
      name: Color
      type: string
    - jsonPath: .spec.size
      name: Size
      type: string

За допомогою полів селекторів можна отримати лише ресурси color зі значенням blue:

kubectl get shirts.stable.example.com --field-selector spec.color=blue

Вивід повинен бути наступним:

NAME       COLOR  SIZE
example1   blue   S
example2   blue   M

Що далі

Змінено December 17, 2024 at 11:53 AM PST: Sync upstream after v1.32 release (d7b08bbf8e)