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.
