Информация этой страницы может быть устаревшей
Оригинальная (английская) версия этого документа обновлялась с момента последнего перевода, поэтому информация может быть устаревшей. Если вы читаете на английском, посмотрите на оригинальную версию с наиболее актуальной информацией: The Kubernetes API
API Kubernetes
Общие соглашения API описаны на странице соглашений API.
Конечные точки API, типы ресурсов и примеры описаны в справочнике API.
Удаленный доступ к API обсуждается в Controlling API Access doc.
API Kubernetes также служит основой декларативной схемы конфигурации системы. С помощью инструмента командной строки kubectl можно создавать, обновлять, удалять и получать API-объекты.
Kubernetes также сохраняет сериализованное состояние (в настоящее время в хранилище etcd) каждого API-ресурса.
Kubernetes как таковой состоит из множества компонентов, которые взаимодействуют друг с другом через собственные API.
Изменения в API
Исходя из нашего опыта, любая успешная система должна улучшаться и изменяться по мере появления новых сценариев использования или изменения существующих. Поэтому мы надеемся, что и API Kubernetes будет постоянно меняться и расширяться. Однако в течение продолжительного периода времени мы будем поддерживать хорошую обратную совместимость с существующими клиентами. В целом, новые ресурсы API и поля ресурсов будут добавляться часто. Удаление ресурсов или полей регулируются соответствующим процессом.
Определение совместимого изменения и методы изменения API подробно описаны в документе об изменениях API.
Определения OpenAPI и Swagger
Все детали API документируется с использованием OpenAPI.
Начиная с Kubernetes 1.10, API-сервер Kubernetes основывается на спецификации OpenAPI через конечную точку /openapi/v2
.
Нужный формат устанавливается через HTTP-заголовки:
Заголовок | Возможные значения |
---|---|
Accept | application/json , application/[email protected]+protobuf (по умолчанию заголовок Content-Type установлен в application/json с */* , допустимо также пропускать этот заголовок) |
Accept-Encoding | gzip (можно не передавать этот заголовок) |
До версии 1.14 конечные точки с форматом (/swagger.json
, /swagger-2.0.0.json
, /swagger-2.0.0.pb-v1
, /swagger-2.0.0.pb-v1.gz
) предоставляли спецификацию OpenAPI в разных форматах. Эти конечные точки были объявлены устаревшими и удалены в Kubernetes 1.14.
Примеры получения спецификации OpenAPI:
До 1.10 | С версии Kubernetes 1.10 |
---|---|
GET /swagger.json | GET /openapi/v2 Accept: application/json |
GET /swagger-2.0.0.pb-v1 | GET /openapi/v2 Accept: application/[email protected]+protobuf |
GET /swagger-2.0.0.pb-v1.gz | GET /openapi/v2 Accept: application/[email protected]+protobuf Accept-Encoding: gzip |
В Kubernetes реализован альтернативный формат сериализации API, основанный на Protobuf, который в первую очередь предназначен для взаимодействия внутри кластера. Описание этого формата можно найти в проектом решении, а IDL-файлы по каждой схемы — в пакетах Go, определяющих API-объекты.
До версии 1.14 apiserver Kubernetes также представлял API, который можно использовать для получения спецификации Swagger v1.2 для API Kubernetes по пути /swaggerapi
. Эта конечная точка устарела и была удалена в Kubernetes 1.14
Версионирование API
Чтобы упростить удаления полей или изменение ресурсов, Kubernetes поддерживает несколько версий API, каждая из которых доступна по собственному пути, например, /api/v1
или /apis/extensions/v1beta1
.
Мы выбрали версионирование API, а не конкретных ресурсов или полей, чтобы API отражал четкое и согласованное представление о системных ресурсах и их поведении, а также, чтобы разграничивать API, которые уже не поддерживаются и/или находятся в экспериментальной стадии. Схемы сериализации JSON и Protobuf следуют одним и тем же правилам по внесению изменений в схему, поэтому описание ниже охватывают оба эти формата.
Обратите внимание, что версионирование API и программное обеспечение косвенно связаны друг с другом. Предложение по версионированию API и новых выпусков описывает, как связаны между собой версии API с версиями программного обеспечения.
Разные версии API характеризуются разными уровнями стабильности и поддержки. Критерии каждого уровня более подробно описаны в документации изменений API. Ниже приводится краткое изложение:
- Альфа-версии:
- Названия версий включают надпись
alpha
(например,v1alpha1
). - Могут содержать баги. Включение такой функциональности может привести к ошибкам. По умолчанию она отключена.
- Поддержка функциональности может быть прекращена в любое время без какого-либо оповещения об этом.
- API может быть несовместим с более поздними версиями без упоминания об этом.
- Рекомендуется для использования только в тестировочных кластерах с коротким жизненным циклом из-за высокого риска наличия багов и отсутствия долгосрочной поддержки.
- Названия версий включают надпись
- Бета-версии:
- Названия версий включают надпись
beta
(например,v2beta3
). - Код хорошо протестирован. Активация этой функциональности — безопасно. Поэтому она включена по умолчанию.
- Поддержка функциональности в целом не будет прекращена, хотя кое-что может измениться.
- Схема и/или семантика объектов может стать несовместимой с более поздними бета-версиями или стабильными выпусками. Когда это случится, мы даем инструкции по миграции на следующую версию. Это обновление может включать удаление, редактирование и повторного создание API-объектов. Этот процесс может потребовать тщательного анализа. Кроме этого, это может привести к простою приложений, которые используют данную функциональность.
- Рекомендуется только для неосновного производственного использования из-за риска возникновения возможных несовместимых изменений с будущими версиями. Если у вас есть несколько кластеров, которые возможно обновить независимо, вы можете снять это ограничение.
- Пожалуйста, попробуйте в действии бета-версии функциональности и поделитесь своими впечатлениями! После того как функциональность выйдет из бета-версии, нам может быть нецелесообразно что-то дальше изменять.
- Названия версий включают надпись
- Стабильные версии:
- Имя версии
vX
, гдеvX
— целое число. - Стабильные версии функциональностей появятся в новых версиях.
- Имя версии
API-группы
Чтобы упростить расширение API Kubernetes, реализованы группы API.
Группа API указывается в пути REST и в поле apiVersion
сериализованного объекта.
В настоящее время используется несколько API-групп:
Группа core, которая часто упоминается как устаревшая (legacy group), доступна по пути
/api/v1
и используетapiVersion: v1
.Именованные группы находятся в пути REST
/apis/$GROUP_NAME/$VERSION
и используютapiVersion: $GROUP_NAME/$VERSION
(например,apiVersion: batch/v1
). Полный список поддерживаемых групп API можно увидеть в справочнике API Kubernetes.
Есть два поддерживаемых пути к расширению API с помощью пользовательских ресурсов:
- CustomResourceDefinition для пользователей, которым нужен очень простой CRUD.
- Пользователи, которым нужна полная семантика API Kubernetes, могут реализовать собственный apiserver и использовать агрегатор для эффективной интеграции для клиентов.
Включение или отключение групп API
Некоторые ресурсы и группы API включены по умолчанию. Их можно включить или отключить, установив --runtime-config
для apiserver. Флаг --runtime-config
принимает значения через запятую. Например, чтобы отключить batch/v1, используйте --runtime-config=batch/v1=false
, а чтобы включить batch/v2alpha1, используйте флаг --runtime-config=batch/v2alpha1
.
Флаг набор пар ключ-значение, указанных через запятую, который описывает конфигурацию во время выполнения сервера.
Примечание:
Включение или отключение групп или ресурсов требует перезапуска apiserver и controller-manager для применения изменений--runtime-config
.Включение определённых ресурсов в группу extensions/v1beta1
DaemonSets, Deployments, StatefulSet, NetworkPolicies, PodSecurityPolicies и ReplicaSets в API-группе extensions/v1beta1
по умолчанию отключены.
Например: чтобы включить deployments и daemonsets, используйте флаг --runtime-config=extensions/v1beta1/deployments=true,extensions/v1beta1/daemonsets=true
.
Примечание:
Включение/отключение отдельных ресурсов поддерживается только в API-группеextensions/v1beta1
по историческим причинам.