Політика застарівання Kubernetes

Цей документ описує політику застарівання для різних аспектів системи.

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

Застарівання частин API

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

Конкретний випуск Kubernetes може підтримувати будь-яку кількість груп API та будь-яку кількість версій кожного з них.

Наступні правила регулюють застарівання елементів API. Це включає:

• Ресурси REST (також відомі як обʼєкти API)
• Поля ресурсів REST
• Анотації на ресурсах REST, включаючи "бета" анотації, але не включаючи "альфа" анотації
• Перелічувані або постійні значення
• Структури конфігурації компонентів

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

Правило №1: Елементи API можуть бути видалені лише шляхом інкрементування версії групи API.

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

Правило №2: Обʼєкти API повинні мати можливість переходу між версіями API в даному випуску без втрати інформації, за винятком випадків, коли цілі ресурси REST не існують у деяких версіях.

Наприклад, обʼєкт може бути записаний як v1, потім прочитаний як v2 і перетворений на v1, і отриманий ресурс v1 буде ідентичний оригіналу. Представлення у v2 може відрізнятися від v1, але система повинна вміти конвертувати між ними в обидва боки. Крім того, будь-яке нове поле, додане у v2, повинно мати можливість обміну на v1 і назад, що означає, що v1 можливо доведеться додати еквівалентне поле або представити його як анотацію.

Правило №3: Версія API в даному треку не може бути застарілою на користь менш стабільної версії API.

• GA версії API можуть замінювати бета та альфа версії API.
• Бета версії API можуть замінювати попередні бета та альфа версії API, але не можуть замінювати GA версії API.
• Альфа версії API можуть замінювати попередні альфа версії API, але не можуть замінювати GA або бета версії API.

Правило №4а: Тривалість життя API визначається рівнем стабільності API

• GA версії API можуть бути позначені як застарілі, але не можуть бути видалені в межах основної версії Kubernetes
• Бета версії API застарівають не раніше ніж через 9 місяців або 3 мінорних випуски після впровадження (що довше), і більше не обслуговуються через 9 місяців або 3 мінорних випуски після застарівання (що довше)
• Альфа версії API можуть бути видалені в будь-якому випуску без попереднього повідомлення про застарівання

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

Правило №4б: "Бажана" версія API та "версія зберігання" для даної групи можуть не просуватися до того, як буде зроблено випуск, що підтримує як нову версію, так і попередню версію.

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

Все це найкраще ілюструється прикладами. Уявіть собі випуск Kubernetes, версія X, який вводить нову групу API. Новий випуск Kubernetes виходить приблизно кожні 4 місяці (3 на рік). Наступна таблиця описує, які версії API підтримуються в ряді наступних випусків.

REST ресурси (або обʼєкти API)

Розглянемо гіпотетичний REST ресурс з назвою Widget, який був присутній у версії API v1 у наведеній вище хронології і який потрібно визнати застарілим. Ми документуємо та оголошуємо про його застарівання синхронно з випуском X+1. Ресурс Widget все ще існує у версії API v1 (застарілий), але не у v2alpha1. Ресурс Widget продовжує існувати та функціонувати у випусках до, та включно з, X+8. Лише у випуску X+9, коли API v1 виходить з використання, ресурс Widget перестає існувати та його віповідна поведінка видаляється.

Починаючи з Kubernetes v1.19, виконання запиту до застарілої точки доступу REST API:

1. Повертає заголовок Warning (як визначено у RFC7234, Розділ 5.5) у відповіді API.

2. Додає "k8s.io/deprecated":"true" анотацію до події аудиту, зареєстрованої для запиту.

3. Встановлює метрику apiserver_requested_deprecated_apis gauge у значення 1 у процесі kube-apiserver. Метрика має мітки group, version, resource, subresource, які можна поєднати з метрикою apiserver_request_total, і мітку removed_release, яка вказує випуск Kubernetes, в якому API більше не буде обслуговуватися. Наступний запит Prometheus повертає інформацію про запити, зроблені до застарілих API, які будуть видалені у версії v1.22:

   apiserver_requested_deprecated_apis{removed_release="1.22"} * on(group,version,resource,subresource) group_right() apiserver_request_total
   

Поля REST ресурсів

Як і REST ресурси в цілому, так і окреме поле, яке було присутнє у версії API v1, має існувати та функціонувати до видалення API v1. На відміну від ресурсів в цілому, API v2 можуть вибрати інше представлення для поля, допоки є можливість виконувати перехід між версіями в обидва боки. Наприклад, поле v1 з назвою "magnitude", яке було застарілим, може називатися "deprecatedMagnitude" в API v2. Коли v1 врешті буде видалено, застаріле поле може бути видалене з v2.

Перераховані або константні значення

Як і для REST ресурсу в цілому, так і його полів, константне значення, яке підтримувалося в API v1, має існувати та функціонувати до видалення API v1.

Структури конфігурацій компонентів

Конфігурації компонентів версіонуються та керуються аналогічно до REST ресурсів.

Майбутні роботи

З часом Kubernetes запровадить більш детальні версії API, і тоді ці правила будуть скориговані за потреби.

Застарівання прапорця або CLI

Система Kubernetes складається з кількох різних програм, які співпрацюють між собою. Іноді випуск Kubernetes може видаляти прапорці або команди CLI (загалом "елементи CLI") у цих програмах. Програми природно діляться на дві основні групи — програми для користувачів і програми для адміністраторів, які трохи відрізняються своїми політиками застарівання. Якщо прапорець явно не позначено або задокументовано як "alpha" або "beta", він вважається стабільним (GA).

Елементи CLI фактично є частиною API до системи, але оскільки вони не версіонуються так само, як REST API, правила застарівання наступні:

Правило №5а: Елементи CLI компонентів для користувачів (наприклад, kubectl) повинні функціонувати після оголошення їх застарівання не менше ніж:

• GA: 12 місяців або 2 випуски (залежно від того, що довше)
• Beta: 3 місяці або 1 випуск (залежно від того, що довше)
• Alpha: 0 випусків

Правило №5б: Елементи CLI компонентів для адміністраторів (наприклад, kubelet) повинні функціонувати після оголошення їх застарівання не менше ніж:

• GA: 6 місяців або 1 випуск (залежно від того, що довше)
• Beta: 3 місяці або 1 випуск (залежно від того, що довше)
• Alpha: 0 випусків

Правило №5в: Елементи командного інтерфейсу (CLI) не можуть бути застарілими на користь менш стабільних елементів CLI.

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

Правило №6: Застарілі елементи CLI повинні видавати попередження (можливо, такі, що відключаються) при використанні.

Застарівання функціонала або поведінки

Час від часу випуск Kubernetes потребує визнання застарілим певного функціонала або поведінки системи, яка не контролюється API або CLI. У цьому випадку правила застарівання такі:

Правило №7: Застарілі функції повинні функціонувати не менше 1 року після оголошеного застарівання.

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

Правило №8: Функцію або поведінку не можна визнати застарілою на користь альтернативної реалізації, яка менш стабільна.

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

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

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

Виняток з вищезазначеного правила  — це функціональні можливості. Функціональні можливості — це пари ключ=значення, які дозволяють користувачам увімкнути/вимкнути експериментальні функції.

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

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

• Alpha: функціональні можливості стандартно вимкнені та можуть бути увімкнені користувачем.
• Beta: функціональні можливості стандартно увімкнені та можуть бути вимкнені користувачем.
• GA: функціональні можливості застарілі (див. "Застарівання") і стають нечинними.
• GA, вікно застарівання завершено: функціональні можливості видаляються, і виклики до них більше не приймаються.

Застарівання

Функції можуть бути видалені на будь-якому етапі життєвого циклу до GA. Коли функції видаляються перед виходом GA, їхні повʼязані функціональні можливості також застарівають.

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

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

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

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

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

Правило №9: Функціональні можливості повинні бути визнані застарілими, коли відповідна функція, якою вони керують, переходить на етап життєвого циклу наступним чином. Функціональні можливості повинні функціонувати не менше ніж:

• Від бета-функції до GA: 6 місяців або 2 випуски (залежно від того, що довше)
• Від бета-функції до EOL: 3 місяці або 1 випуск (залежно від того, що довше)
• Від альфа-функції до EOL: 0 випусків

Правило №10: Застарілі функціональні можливості повинні відповідати попередженням при використанні. Коли функціональні можливості застарівають, вони повинні бути задокументовані як в примітках про випуски, так і в відповідній довідці CLI. Як попередження, так і документація повинні вказувати, чи є функціональні можливості нечинними.

Застарівання метрики

Кожен компонент панелі управління Kubernetes використовує метрики (зазвичай за допомогою точки доступу /metrics), які зазвичай обробляються адміністраторами кластера. Не всі метрики однакові: деякі метрики широко використовуються як показники рівня сервісу (SLI) або для визначення SLO, тому вони мають більшу важливість. Інші метрики мають більш експериментальний характер або використовуються переважно у процесі розробки Kubernetes.

Відповідно, метрики поділяються на три класи стабільності (ALPHA, BETA, STABLE); це впливає на видалення метрики під час випуску Kubernetes. Ці класи визначаються важливістю метрики. Правила для застарівання та видалення метрики такі:

Правило №11а: Метрики для відповідного класу стабільності повинні функціонувати не менше ніж:

• STABLE: 4 випуски або 12 місяців (що довше)
• BETA: 2 випуски або 8 місяців (що довше)
• ALPHA: 0 випусків

Правило №11б: Метрики, після їх оголошеного застарівання, повинні функціонувати не менше ніж:

• STABLE: 3 випуски або 9 місяців (що довше)
• BETA: 1 випуск або 4 місяці (що довше)
• ALPHA: 0 випусків

Застарілі метрики будуть мати текст опису, у якому буде префікс з повідомленням про застарівання '(Застаріло з x.y)', і під час реєстрації метрики буде запис в лог з попередженням. Подібно до їх стабільних незастарілих аналогів, застарілі метрики будуть автоматично зареєстровані в точці доступу метрик і, отже, будуть видимими.

У наступному випуску (коли deprecatedVersion метрики дорівнює current_kubernetes_version - 3), застаріла метрика стане прихованою метрикою. На відміну від їх застарілих аналогів, приховані метрики більше не будуть автоматично реєструватися в точці доступу метрик (таким чином, вони будуть приховані). Однак їх можна буде явно увімкнути через прапорець командного рядка (--show-hidden-metrics-for-version=). Це надає адміністраторам кластера можливість виходу зі складностей з міграцією від застарілої метрики, якщо вони не змогли відреагувати на раніше надані попередження щодо застарівання. Приховані метрики повинні бути видалені після одного випуску.

Винятки

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