Merge pull request #20123 from lex111/ru-concepts-overview-kubernetes-api
Translate The Kubernetes API page into Russianpull/20227/head
Kubernetes Prow Robot
GitHub
commit
cd3886c168
|
|
@ -0,0 +1,117 @@
|
|||
---
|
||||
title: API Kubernetes
|
||||
content_template: templates/concept
|
||||
weight: 30
|
||||
card:
|
||||
name: concepts
|
||||
weight: 30
|
||||
---
|
||||
|
||||
{{% capture overview %}}
|
||||
|
||||
Общие соглашения API описаны на [странице соглашений API](https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md).
|
||||
|
||||
Конечные точки API, типы ресурсов и примеры описаны в [справочнике API](/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.
|
||||
|
||||
{{% /capture %}}
|
||||
|
||||
{{% capture 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](/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`.
|
||||
Флаг набор пар ключ-значение, указанных через запятую, который описывает конфигурацию во время выполнения сервера.
|
||||
|
||||
{{< note >}}Включение или отключение групп или ресурсов требует перезапуска apiserver и controller-manager для применения изменений `--runtime-config`.{{< /note >}}
|
||||
|
||||
## Включение определённых ресурсов в группу extensions/v1beta1
|
||||
|
||||
DaemonSets, Deployments, StatefulSet, NetworkPolicies, PodSecurityPolicies и ReplicaSets в API-группе `extensions/v1beta1` по умолчанию отключены.
|
||||
Например: чтобы включить deployments и daemonsets, используйте флаг `--runtime-config=extensions/v1beta1/deployments=true,extensions/v1beta1/daemonsets=true`.
|
||||
|
||||
{{< note >}}Включение/отключение отдельных ресурсов поддерживается только в API-группе `extensions/v1beta1` по историческим причинам.{{< /note >}}
|
||||
|
||||
{{% /capture %}}
|
||||
Loading…
Reference in New Issue