From b4c76fd68f9fcade50d2320fd4e278ffa714a415 Mon Sep 17 00:00:00 2001
From: Alexey Pyltsyn <lex61rus@gmail.com>
Date: Mon, 6 Apr 2020 12:27:25 +0300
Subject: [PATCH] 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 %}}