Information in this document may be out of date

This document has an older update date than the original, so the information it contains may be out of date. If you're able to read English, see the English version for the most up-to-date information: 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/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-групп:

  1. Группа core, которая часто упоминается как устаревшая (legacy group), доступна по пути /api/v1 и использует apiVersion: v1.

  2. Именованные группы находятся в пути REST /apis/$GROUP_NAME/$VERSION и используют apiVersion: $GROUP_NAME/$VERSION (например, apiVersion: batch/v1). Полный список поддерживаемых групп API можно увидеть в справочнике API Kubernetes.

Есть два поддерживаемых пути к расширению API с помощью пользовательских ресурсов:

  1. CustomResourceDefinition для пользователей, которым нужен очень простой CRUD.
  2. Пользователи, которым нужна полная семантика API Kubernetes, могут реализовать собственный apiserver и использовать агрегатор для эффективной интеграции для клиентов.

Включение или отключение групп API

Некоторые ресурсы и группы API включены по умолчанию. Их можно включить или отключить, установив --runtime-config для apiserver. Флаг --runtime-config принимает значения через запятую. Например, чтобы отключить batch/v1, используйте --runtime-config=batch/v1=false, а чтобы включить batch/v2alpha1, используйте флаг --runtime-config=batch/v2alpha1. Флаг набор пар ключ-значение, указанных через запятую, который описывает конфигурацию во время выполнения сервера.

Включение определённых ресурсов в группу extensions/v1beta1

DaemonSets, Deployments, StatefulSet, NetworkPolicies, PodSecurityPolicies и ReplicaSets в API-группе extensions/v1beta1 по умолчанию отключены. Например: чтобы включить deployments и daemonsets, используйте флаг --runtime-config=extensions/v1beta1/deployments=true,extensions/v1beta1/daemonsets=true.

Изменено March 26, 2022 at 11:55 PM PST: kube_api_typos (6525c0cab5)