Black lives matter.
We stand in solidarity with the Black community.
Racism is unacceptable.
It conflicts with the core values of the Kubernetes project and our community does not tolerate it.
We stand in solidarity with the Black community.
Racism is unacceptable.
It conflicts with the core values of the Kubernetes project and our community does not tolerate it.
Общие соглашения API описаны на странице соглашений API.
Конечные точки API, типы ресурсов и примеры описаны в справочнике API.
Удаленный доступ к API обсуждается в Controlling API Access doc.
API Kubernetes также служит основой декларативной схемы конфигурации системы. С помощью инструмента командной строки kubectl можно создавать, обновлять, удалять и получать API-объекты.
Kubernetes также сохраняет сериализованное состояние (в настоящее время в хранилище etcd) каждого API-ресурса.
Kubernetes как таковой состоит из множества компонентов, которые взаимодействуют друг с другом через собственные API.
Исходя из нашего опыта, любая успешная система должна улучшаться и изменяться по мере появления новых сценариев использования или изменения существующих. Поэтому мы надеемся, что и API Kubernetes будет постоянно меняться и расширяться. Однако в течение продолжительного периода времени мы будем поддерживать хорошую обратную совместимость с существующими клиентами. В целом, новые ресурсы API и поля ресурсов будут добавляться часто. Удаление ресурсов или полей регулируются соответствующим процессом.
Определение совместимого изменения и методы изменения API подробно описаны в документе об изменениях API.
Все детали 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
Чтобы упростить удаления полей или изменение ресурсов, Kubernetes поддерживает несколько версий API, каждая из которых доступна по собственному пути, например, /api/v1
или /apis/extensions/v1beta1
.
Мы выбрали версионирование API, а не конкретных ресурсов или полей, чтобы API отражал четкое и согласованное представление о системных ресурсах и их поведении, а также, чтобы разграничивать API, которые уже не поддерживаются и/или находятся в экспериментальной стадии. Схемы сериализации JSON и Protobuf следуют одним и тем же правилам по внесению изменений в схему, поэтому описание ниже охватывают оба эти формата.
Обратите внимание, что версиоирование API и программное обеспечение косвенно связаны друг с другом. Предложение по версионированию API и новых выпусков описывает, как связаны между собой версии API с версиями программного обеспечения.
Разные версии API имеют характеризуются разной уровнем стабильностью и поддержкой. Критерии каждого уровня более подробно описаны в документации изменений API. Ниже приводится краткое изложение:
alpha
(например, v1alpha1
).beta
(например, v2beta3
).vX
, где vX
— целое число.Чтобы упростить расширение 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 с помощью пользовательских ресурсов:
Некоторые ресурсы и группы API включены по умолчанию. Их можно включить или отключить, установив --runtime-config
для apiserver. Флаг --runtime-config
принимает значения через запятую. Например, чтобы отключить batch/v1, используйте --runtime-config=batch/v1=false
, а чтобы включить batch/v2alpha1, используйте флаг --runtime-config=batch/v2alpha1
.
Флаг набор пар ключ-значение, указанных через запятую, который описывает конфигурацию во время выполнения сервера.
Заметка: Включение или отключение групп или ресурсов требует перезапуска apiserver и controller-manager для применения изменений--runtime-config
.
DaemonSets, Deployments, StatefulSet, NetworkPolicies, PodSecurityPolicies и ReplicaSets в API-группе extensions/v1beta1
по умолчанию отключены.
Например: чтобы включить deployments и daemonsets, используйте флаг --runtime-config=extensions/v1beta1/deployments=true,extensions/v1beta1/daemonsets=true
.
Заметка: Включение/отключение отдельных ресурсов поддерживается только в API-группеextensions/v1beta1
по историческим причинам.