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/com.github.proto-openapi.spec.v2@v1.0+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/com.github.proto-openapi.spec.v2@v1.0+protobuf |
| GET /swagger-2.0.0.pb-v1.gz | GET /openapi/v2 Accept: application/com.github.proto-openapi.spec.v2@v1.0+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по историческим причинам.