From b4c76fd68f9fcade50d2320fd4e278ffa714a415 Mon Sep 17 00:00:00 2001 From: Alexey Pyltsyn Date: Mon, 6 Apr 2020 12:27:25 +0300 Subject: [PATCH 1/2] Translate The Kubernetes API page into Russian --- .../docs/concepts/overview/kubernetes-api.md | 117 ++++++++++++++++++ 1 file changed, 117 insertions(+) create mode 100644 content/ru/docs/concepts/overview/kubernetes-api.md diff --git a/content/ru/docs/concepts/overview/kubernetes-api.md b/content/ru/docs/concepts/overview/kubernetes-api.md new file mode 100644 index 0000000000..5aea5818af --- /dev/null +++ b/content/ru/docs/concepts/overview/kubernetes-api.md @@ -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` (the default content-type is `application/json` for `*/*` or not passing this header) +Accept-Encoding | `gzip` (not passing this header is acceptable) + +До версии 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 %}} From 7c839798a18dd16656c3405b816b4da2ab2b7ff8 Mon Sep 17 00:00:00 2001 From: Alexey Pyltsyn Date: Fri, 10 Apr 2020 13:33:13 +0300 Subject: [PATCH 2/2] Translate comments --- content/ru/docs/concepts/overview/kubernetes-api.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/content/ru/docs/concepts/overview/kubernetes-api.md b/content/ru/docs/concepts/overview/kubernetes-api.md index 5aea5818af..c3812c8469 100644 --- a/content/ru/docs/concepts/overview/kubernetes-api.md +++ b/content/ru/docs/concepts/overview/kubernetes-api.md @@ -40,8 +40,8 @@ Kubernetes как таковой состоит из множества комп Заголовок | Возможные значения ------ | --------------- -Accept | `application/json`, `application/com.github.proto-openapi.spec.v2@v1.0+protobuf` (the default content-type is `application/json` for `*/*` or not passing this header) -Accept-Encoding | `gzip` (not passing this header is acceptable) +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.