Kubernetes API

API Kubernetes служит основой для декларативной схемы конфигурации системы. Инструмент командной строки kubectl можно использовать для создания, обновления, удаления и получения объектов API.

Kubernetes сохраняет свое сериализованное состояние (в настоящее время в etcd) с точки зрения ресурсов API.

Сам Kubernetes раскладывается на несколько компонентов, которые взаимодействуют через его API.

Изменения API

Любая успешная система должна расти и изменяться по мере появления новых вариантов использования или изменения существующих. Поэтому ожидается, что API Kubernetes будет постоянно меняться и расти. Однако будет сохраняться совместимость с существующими клиентами в течение длительного периода времени. В общем, можно ожидать, что новые ресурсы 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 (тип содержимого по умолчанию - 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:

  • До версии Kubernetes 1.10 - GET /swagger.json

    Начиная с Kubernetes 1.10 - GET /openapi/v2 Accept: application/json

  • До версии Kubernetes 1.10 - GET /swagger-2.0.0.pb-v1

    Начиная с Kubernetes 1.10 - GET /openapi/v2 Accept: application/com.github.proto-openapi.spec.v2@v1.0+protobuf

  • До версии Kubernetes 1.10 - GET /swagger-2.0.0.pb-v1.gz

    Начиная с Kubernetes 1.10 - GET /openapi/v2 Accept: application/com.github.proto-openapi.spec.v2@v1.0+protobuf Accept-Encoding: gzip

Kubernetes реализует альтернативный формат сериализации на основе Protobuf для API, который в первую очередь предназначен для внутрикластерной связи, документирован в предложении по разработке, и файлы IDL для каждой схемы находятся в пакетах Go, которые определяют объекты API.

До версии 1.14 apiserver Kubernetes также представлял API, который можно использовать для получения спецификации Swagger v1.2 Kubernetes API в /swaggerapi. Эта конечная точка устарела и будет удалена в Kubernetes 1.14.

Версии API

Чтобы упростить удаление полей или реструктуризацию представлений ресурсов, Kubernetes поддерживает несколько версий API, каждая из которых имеет свой путь API, например /api/v1 или /apis/extensions/v1beta1.

Были выбраны версии на уровне API, а не на уровне ресурсов или полей, чтобы гарантировать, что API предоставляет четкое, согласованное представление о системных ресурсах и поведении, а также обеспечить контроль доступа к API с истекшим сроком эксплуатации и/или экспериментальным API. Схемы сериализации JSON и Protobuf следуют тем же рекомендациям по изменению схемы - все описания ниже охватывают оба формата.

Обратите внимание, что управление версиями API и программного обеспечения связано только косвенно.

Различные версии API предполагают разные уровни стабильности и поддержки. Критерии для каждого уровня более подробно описаны в документации по изменениям API. Они суммированы здесь:

Альфа-уровень:

  • Названия версий содержат alpha (например, v1alpha1).
  • Может быть с ошибками. Включение этой функции может привести к ошибкам. По умолчанию отключено.
  • Поддержка функции может быть прекращена в любое время без предварительного уведомления.
  • API может измениться несовместимыми способами в последующих версиях программного обеспечения без предварительного уведомления.
  • Рекомендуется для использования только в недолговечных кластерах тестирования из-за повышенного риска ошибок и отсутствия долгосрочной поддержки.

Бета-уровень:

  • Названия версий содержат beta (например, v2beta3).
  • Код хорошо протестирован. Включение этой функции считается безопасным. Включено по умолчанию.
  • Поддержка всей функциональности не будет прекращена, хотя детали могут измениться.
  • Схема и/или семантика объектов могут изменяться несовместимыми способами в последующей бета-версии или стабильной версии. Когда это произойдет, будут предоставлены инструкции по переходу на следующую версию. Это может потребовать удаления, редактирования и повторного создания объектов API. Процесс редактирования может потребовать некоторых размышлений. Это может потребовать простоя приложений, использующих этот функционал.
  • Рекомендуется только для не критичного для бизнеса использования из-за возможных несовместимых изменений в последующих выпусках. Если у вас есть несколько кластеров, которые могут быть обновлены независимо, вы можете ослабить это ограничение.

Стабильный уровень:

  • Имя версии vX, где X - целое число.
  • Стабильные версии функций появятся в выпущенном программном обеспечении для многих последующих версий.

API групп

Чтобы упростить расширение API Kubernetes, были внедрены группы API (API groups). Группа API указывается в пути REST и в поле apiVersion сериализованного объекта.

В настоящее время используется несколько групп API:

Основная группа (core group), часто называемая устаревшей группой (legacy group), находится по пути REST /api/v1 и использует apiVersion: v1.

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

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

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

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

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

ВАЖНО: Включение или отключение групп или ресурсов требует перезапуска apiserver и controller-manager для получения изменений --runtime-config.

Включение ресурсов в группы

DaemonSets, Deployments, HorizontalPodAutoscalers, Ingresses, Jobs и ReplicaSets включены по умолчанию. Другие ресурсы расширений можно включить, установив --runtime-config на apiserver. --runtime-config принимает значения через запятую. Например: чтобы отключить deployments и ingress, установите --runtime-config=extensions/v1beta1/deployments=false,extensions/v1beta1/ingresses=false

Читайте также:


Комментарии

Отправить комментарий

Популярные сообщения из этого блога

Контроллеры в Kubernetes: DaemonSet

Изображение
DaemonSet гарантирует, что все (или некоторые) узлы запускают копию Pod. Когда узлы добавляются в кластер, к ним добавляются Pod'ы. Когда узлы удаляются из кластера, эти Pod'ы удаляются. Удаление DaemonSet приведет к очистке созданных им Pod'ов. Некоторые типичные применения DaemonSet : запуск демона кластерного хранилища, такого как glusterd, ceph, на каждом узле. запуск демона сбора журналов на каждом узле, таком как fluentd или logstash. запуск демона мониторинга узла на каждом узле, таком как экспортер узлов Prometheus, агент Sysdig, collectd, Dynatrace OneAgent, агент AppDynamics, агент Datadog, агент New Relic, агент Ganglia gmond или агент Instana. В простом случае один DaemonSet, охватывающий все узлы, будет использоваться для каждого типа демона. Более сложная установка может использовать несколько DaemonSets для одного типа демона, но с разными флагами и/или разными запросами памяти и процессора для разных типов оборудования. Написание спецификации Daemon...
Далее...

Контроллеры в Kubernetes: ReplicaSet

Изображение
Цель контроллера ReplicaSet - поддерживать стабильный набор реплик (экземпляров) Pod'ов, работающих в любой момент времени. Как таковой, он часто используется, чтобы гарантировать наличие определенного количества идентичных Pod'ов. Как работает ReplicaSet ReplicaSet задается полями , включая селектор (selector) , который указывает, как идентифицировать Pod'ы, которые он может приобрести, количество реплик (replicas) , указывающих, сколько Pod'ов он должен поддерживать, и шаблон (template) Pod'ов , указывающий данные новых Pod'ов, которые он должен создать для соответствия критерию количества реплик. Затем ReplicaSet выполняет свое предназначение, создавая и удаляя Pod'ы по мере необходимости для достижения желаемого числа. Когда ReplicaSet нуждается в создании новых Pod'ов, он использует свой шаблон Pod'ов для их создания. Ссылка, которую ReplicaSet имеет на свои Pod'ы, осуществляется через поле metadata.ownerReferences Pod'ов, которое у...
Далее...

Контроллеры в Kubernetes: StatefulSet

Изображение
StatefulSet - это объект workload API, используемый для управления приложениями с отслеживанием состояния. Управляет развертыванием и масштабированием набора Pod'ов, а также предоставляет гарантии относительно порядка и уникальности этих Pod'ов. Подобно Deployment, StatefulSet управляет Pod'ами, основанными на идентичной спецификации контейнера. В отличие от Deployment, StatefulSet поддерживает липкую (sticky) идентификацию для каждого из своих Pod'ов. Эти Pod'ы созданы из одной и той же спецификации, но не являются взаимозаменяемыми: у каждого есть постоянный идентификатор, который он поддерживает при любом перепланировании. StatefulSet работает по тому же шаблону, что и любой другой контроллер. Вы определяете желаемое состояние в объекте StatefulSet, а контроллер StatefulSet делает все необходимые обновления, чтобы получить его из текущего состояния. Использование StatefulSet StatefulSet полезны для приложений, которым требуется одно или несколько из следующ...
Далее...