# API Kubernetes

LLMS index: [llms.txt](/llms.txt)

---

<!-- overview -->

Общие соглашения API описаны на [странице соглашений API](https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md).

Конечные точки API, типы ресурсов и примеры описаны в [справочнике API](/ru/docs/reference).

Удаленный доступ к API обсуждается в [Controlling API Access doc](/docs/reference/access-authn-authz/controlling-access/).

API Kubernetes также служит основой декларативной схемы конфигурации системы. С помощью инструмента командной строки [kubectl](/ru/docs/reference/kubectl/overview/) можно создавать, обновлять, удалять и получать API-объекты.

Kubernetes также сохраняет сериализованное состояние (в настоящее время в хранилище [etcd](https://coreos.com/docs/distributed-configuration/getting-started-with-etcd/)) каждого API-ресурса.

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



<!-- body -->

## Изменения в API

Исходя из нашего опыта, любая успешная система должна улучшаться и изменяться по мере появления новых сценариев использования или изменения существующих. Поэтому мы надеемся, что и API Kubernetes будет постоянно меняться и расширяться. Однако в течение продолжительного периода времени мы будем поддерживать хорошую обратную совместимость с существующими клиентами. В целом, новые ресурсы API и поля ресурсов будут добавляться часто. Удаление ресурсов или полей регулируются [соответствующим процессом](/docs/reference/using-api/deprecation-policy/).

Определение совместимого изменения и методы изменения API подробно описаны в [документе об изменениях API](https://git.k8s.io/community/contributors/devel/sig-architecture/api_changes.md).

## Определения OpenAPI и Swagger

Все детали API документируется с использованием [OpenAPI](https://www.openapis.org/).

Начиная с 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, который в первую очередь предназначен для взаимодействия внутри кластера. Описание этого формата можно найти в [проектом решении](https://github.com/kubernetes/community/blob/master/contributors/design-proposals/api-machinery/protobuf.md), а IDL-файлы по каждой схемы — в пакетах Go, определяющих API-объекты.

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

## Версионирование API

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

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

Обратите внимание, что версионирование API и программное обеспечение косвенно связаны друг с другом. [Предложение по версионированию API и новых выпусков](https://git.k8s.io/community/contributors/design-proposals/release/versioning.md) описывает, как связаны между собой версии API с версиями программного обеспечения.

Разные версии API характеризуются разными уровнями стабильности и поддержки. Критерии каждого уровня более подробно описаны в [документации изменений API](https://git.k8s.io/community/contributors/devel/sig-architecture/api_changes.md#alpha-beta-and-stable-versions). Ниже приводится краткое изложение:

- Альфа-версии:
  - Названия версий включают надпись `alpha` (например, `v1alpha1`).
  - Могут содержать баги. Включение такой функциональности может привести к ошибкам. По умолчанию она отключена.
  - Поддержка функциональности может быть прекращена в любое время без какого-либо оповещения об этом.
  - API может быть несовместим с более поздними версиями без упоминания об этом.
  - Рекомендуется для использования только в тестировочных кластерах с коротким жизненным циклом из-за высокого риска наличия багов и отсутствия долгосрочной поддержки.
- Бета-версии:
  - Названия версий включают надпись `beta` (например, `v2beta3`).
  - Код хорошо протестирован. Активация этой функциональности — безопасна. Поэтому она включена по умолчанию.
  - Поддержка функциональности в целом не будет прекращена, хотя кое-что может измениться.
  - Схема и/или семантика объектов может стать несовместимой с более поздними бета-версиями или стабильными выпусками. Когда это случится, мы даем инструкции по миграции на следующую версию. Это обновление может включать удаление, редактирование и повторное создание API-объектов. Этот процесс может потребовать тщательного анализа. Кроме этого, это может привести к простою приложений, которые используют данную функциональность.
  - Рекомендуется только для неосновного производственного использования из-за риска возникновения возможных несовместимых изменений с будущими версиями. Если у вас есть несколько кластеров, которые возможно обновить независимо, вы можете снять это ограничение.
  - **Пожалуйста, попробуйте в действии бета-версии функциональности и поделитесь своими впечатлениями! После того как функциональность выйдет из бета-версии, нам может быть нецелесообразно что-то дальше изменять.**
- Стабильные версии:
  - Имя версии `vX`, где `vX` — целое число.
  - Стабильные версии функциональностей появятся в новых версиях.

## API-группы

Чтобы упростить расширение API Kubernetes, реализованы [*группы API*](https://git.k8s.io/community/contributors/design-proposals/api-machinery/api-group.md).
Группа API указывается в пути REST и в поле `apiVersion` сериализованного объекта.

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

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

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

Есть два поддерживаемых пути к расширению API с помощью [пользовательских ресурсов](/docs/concepts/api-extension/custom-resources/):

1. [CustomResourceDefinition](/docs/tasks/access-kubernetes-api/extend-api-custom-resource-definitions/) для пользователей, которым нужен очень простой CRUD.
2. Пользователи, которым нужна полная семантика API Kubernetes, могут реализовать собственный apiserver и использовать [агрегатор](/docs/tasks/access-kubernetes-api/configure-aggregation-layer/) для эффективной интеграции для клиентов.

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

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


<div class="alert alert-info" role="note"><h4 class="alert-heading">Примечание:</h4>Включение или отключение групп или ресурсов требует перезапуска apiserver и controller-manager для применения изменений <code>--runtime-config</code>.</div>


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

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


<div class="alert alert-info" role="note"><h4 class="alert-heading">Примечание:</h4>Включение/отключение отдельных ресурсов поддерживается только в API-группе <code>extensions/v1beta1</code> по историческим причинам.</div>