Kubernetes API развиваются и периодически обновляются. Когда готов улучшенный API на замену старому, старый удаляют. См. политику Kubernetes по удалению API.

Скоро будет удалено несколько API. Это беты, которые еще можно использовать в текущих версиях Kubernetes, но они уже deprecated. Им на смену придут обновленные стабильные версии API ("GA", General Availability).

В Kubernetes 1.22 (релиз ожидается в августе 2021 года) будет удалено несколько deprecated API. На странице релиза Kubernetes 1.22 можно посмотреть его график.

Удаленные API версии в Kubernetes 1.22

В релизе 1.22 не будут поддерживаться версии API из списка ниже. Все это бета-версии, их заменят обновленные и более стабильные версии API.

Бета-версии API ValidatingWebhookConfiguration и MutatingWebhookConfiguration (версии API admissionregistration.k8s.io/v1beta1)
Бета-версия API CustomResourceDefinition (apiextensions.k8s.io/v1beta1)
Бета-версия API APIService (apiregistration.k8s.io/v1beta1)
Бета-версия API TokenReview (authentication.k8s.io/v1beta1)
Бета-версии API SubjectAccessReview, LocalSubjectAccessReview, SelfSubjectAccessReview (версии API из authorization.k8s.io/v1beta1)
Бета-версия API CertificateSigningRequest (certificates.k8s.io/v1beta1)
Бета-версия API Lease (coordination.k8s.io/v1beta1)
Все бета-версии API Ingress (extensions/v1beta1 и networking.k8s.io/v1beta1)

В документации Kubernetes описывается удаление API в релизе 1.22 и объясняется, чем бета-версии отличаются от стабильных.

Что делать

Ниже подробно описано, на какие ресурсы повлияет удаление и что нужно делать.

Ingress

Мигрируйте на API networking.k8s.io/v1 Ingress (доступно с v1.19). Связанный API IngressClass дополняет Ingress, позволяя настраивать разные виды Ingress в одном кластере. Если сейчас вы используете аннотацию kubernetes.io/ingress.class, замените ее полем .spec.ingressClassName.

Переводя Ingress на API v1, изучите каждое правило в этом Ingress. Предыдущие Ingress используют старый тип пути ImplementationSpecific. Вместо ImplementationSpecific переключите path matching на Prefix или Exact. Одно из преимуществ перехода на альтернативные типы путей — простота миграции между разными классами Ingress.

Вам нужно не только обновить свои методы использования Ingress API, но и убедиться, что каждый контроллер ingress, который вы используете, совместим с Ingress API v1. См. предварительные требования для Ingress, чтобы узнать больше об Ingress и контроллерах ingress.

ValidatingWebhookConfiguration и MutatingWebhookConfiguration

Используйте API v1, чтобы извлечь или обновить существующие объекты API, даже если они были созданы с использованием более старых версий API.

Перейдите на версии admissionregistration.k8s.io/v1 для API ValidatingWebhookConfiguration и MutatingWebhookConfiguration, доступные с релиза 1.16.Используйте API v1, чтобы извлечь или обновить существующие объекты API, даже если они были созданы с использованием более старых версий API.

CustomResourceDefinition

Перейдите на API CustomResourceDefinition apiextensions.k8s.io/v1, доступный с v1.16.

Если вы используете внешние CustomResourceDefinitions, переключите существующие манифесты на новые версии API с помощью kubectl convert. Между бета- и стабильной версиями CustomResourceDefinitions есть функциональные различия, поэтому лучше протестировать их, чтобы убедиться, что после апгрейда все работает корректно.

APIService

Перейдите на API apiregistration.k8s.io/v1 APIService, доступный с 1.10.Если у вас уже есть агрегирование API с помощью объекта APIService, это агрегирование будет работать после апгрейда.

TokenReview

Перейдите на API authentication.k8s.io/v1 TokenReview, доступный с 1.10.

Предоставляя этот API через HTTP, сервер Kubernetes API использует тот же формат для отправки TokenReviews в вебхуки. Релиз 1.22 продолжает использовать v1beta1 API для TokenReviews, отправляемых в вебхуки. См. дальнейшие планы, где приводятся советы по переходу на стабильный API.

SubjectAccessReview, SelfSubjectAccessReview и LocalSubjectAccessReview

Перейдите на версии authorization.k8s.io/v1 этих API авторизации, доступные с v1.6.

CertificateSigningRequest

Перейдите на API certificates.k8s.io/v1 CertificateSigningRequest, доступные с v1.19.

Lease

Перейдите на версию coordination.k8s.io/v1 для API Lease, доступную с v1.14.

kubectl convert

Существует плагин для kubectl, который предоставляет подкоманду kubectl convert. Это официальный плагин, который можно скачать с Kubernetes. Подробности см. на странице о загрузке Kubernetes.

Используйте kubectl convert, чтобы указать в файлах манифестов другую версию API. Например, если в системе контроля версий у вас есть манифест, который использует бета-версию Ingress API, выгрузите это определение и выполните команду kubectl convert -f <manifest> --output-version <group>/<version>. Используйте команду kubectl convert, чтобы автоматически преобразовать существующий манифест.

Например, чтобы конвертировать старое определение Ingress в networking.k8s.io/v1, выполните команду:

kubectl convert -f ./legacy-ingress.yaml --output-version networking.k8s.io/v1

Подготовка к апгрейду

Если вы управляете серверным компонентом API в кластере, попробуйте удалить эти API до апгрейда до Kubernetes 1.22.

Добавьте следующие аргументы kube-apiserver:

--runtime-config=admissionregistration.k8s.io/v1beta1=false,apiextensions.k8s.io/v1beta1=false,apiregistration.k8s.io/v1beta1=false,authentication.k8s.io/v1beta1=false,authorization.k9s.io/v1=false,certificates.k8s.io/v1beta=false,coordination.k8s.io/v1beta1=false,extensions/v1beta1/ingresses=false,networking.k8s.io/v1beta1=false

(Побочный эффект — отключится EndpointSlice v1beta1, обратите на это внимание при тестировании).

Когда вы переключите все kube-apiserver в кластере на этот параметр, бета-версии этих API будут удалены. Проверьте, что клиенты API (kubectl, инструменты деплоймента, кастомные контроллеры и т. д.) по-прежнему работают корректно. Если нужно, можно отменить изменения без сложного плана перехода на предыдущую версию.

Совет для разработчиков

Это совет для разработчиков расширений или других компонентов, которые интегрируются с Kubernetes.

Если вы работаете над контроллером Ingress, аутентификатором вебхуков, агрегацией API или другими инструментами, которые используют deprecated API, вы уже наверняка начали переход на новые.

Руководствуйтесь советами в разделе Подготовка к апгрейду, чтобы в вашем кластере Kubernetes использовались только новые API, и убедитесь, что код работает нормально. Укажите в документации, что должны сделать пользователи в связи с апгрейдом Kubernetes до 1.22.

По возможности помогите пользователям уже сейчас опробовать новые API (можно в тестовой среде), чтобы они сообщили вам о проблемах, если они возникнут.

В Kubernetes 1.25 будут еще deprecation, так что планируйте заранее.

Удаление Kubernetes API

Почему из Kubernetes удаляются некоторые API и что дают новые стабильные версии.

У Kubernetes есть политика deprecation для функций, включая Kubernetes API. Эта политика используется, чтобы заменять стабильные API (GA) в Kubernetes. В соответствии с этой политикой стабильные API заменяются только на новые стабильные версии тех же API.

Гарантии стабильности важны: если вы используете стабильный Kubernetes API, вас никогда не заставят перейти с него на альфа- или бета-версию.

Сначала выходит альфа, которая еще не до конца проработана и пока тестируется. Альфа-версии почти всегда отключены по умолчанию. Если ничего не получилось, они удаляются.

После альфы идет бета. Бета-версии обычно включены по умолчанию. Если тестирование проходит нормально, они становятся стабильными версиями. Если нет — дорабатываются.

В прошлом году Kubernetes официально принял политику для API, которые достигли бета-версии:

Если Kubernetes REST API доходит до бета-версии, начинается обратный отсчет. Затем у беты API два пути:
- выпускается GA, а бета признается deprecated — или
- выпускается новая бета-версия (а прежняя признается deprecated).

Раньше на три релиза в Kubernetes уходило примерно девять месяцев. Сейчас Kubernetes принял новый график, по которому выходит три релиза за календарный год.

Когда API удаляется, потому что переводится из бета-версии в стабильную или потому что оказался неудачным, Kubernetes следует политике deprecation и документирует варианты миграции.

Дальнейшие планы

Если вы используете проверки аутентификации для вебхуков, в будущем релизе Kubernetes объекты TokenReview будут отправляться в вебхуки с помощью authentication.k8s.io/v1 по умолчанию. Сейчас поведение по умолчанию — отправлять authentication.k8s.io/v1beta1 TokenReviews в вебхуки, и в Kubernetes 1.22 этот вариант останется дефолтным. Но вы можете перейти на стабильный API прямо сейчас: добавьте --authentication-token-webhook-version=v1 в параметры командной строки для kube-apiserver и убедитесь, что вебхуки для аутентификации работают корректно.

Если все нормально, можно оставить --authentication-token-webhook-version=v1 на всей control plane.

В релизе 1.25, который ожидается в следующем году, не будут поддерживаться бета-версии некоторых Kubernetes API, которые сейчас стабильны. Еще в v1.25 будет удалена PodSecurityPolicy, которая считается deprecated и не перейдет в стабильную версию. См. PodSecurityPolicy Deprecation: прошлое, настоящее и будущее.

Официальный список удаляемых API для Kubernetes 1.25:

Бета-версия API CronJob (batch/v1beta1)
Бета-версия API EndpointSlice (networking.k8s.io/v1beta1)
Бета-версия API PodDisruptionBudget (policy/v1beta1)
Бета-версия API PodSecurityPolicy (policy/v1beta1)

Нужно больше подробностей?

О deprecated функциях сообщается в заметках к релизам Kubernetes: 1.19, 1.20 и 1.21.

Больше о deprecation и удалении см. в официальной политике Kubernetes.

Какие API и функции Kubernetes будут удалены в релизе 1.22