Документация

• 1: Документация по Kubernetes
• 1.1: Версии Kubernetes с поддержкой документации
• 2: Настройка
• 2.1: Среда обучения
• 2.1.1: Установка Kubernetes с помощью Minikube
• 2.1.2: Установка Kubernetes с помощью Kind
• 2.2: Пользовательские облачные решения
• 3: Концепции
• 3.1: Обзор
• 3.1.1: Что такое Kubernetes
• 3.1.2: Компоненты Kubernetes
• 3.1.3: API Kubernetes
• 3.1.4: Работа с объектами Kubernetes
• 3.1.4.1: Изучение объектов Kubernetes
• 3.1.4.2: Управление объектами Kubernetes
• 3.1.4.3: Имена и идентификаторы объектов
• 3.1.4.4: Пространства имён
• 3.1.4.5: Метки и селекторы
• 3.1.4.6: Аннотации
• 3.1.4.7: Селекторы полей
• 3.1.4.8: Рекомендуемые метки
• 3.2: Кластерная Архитектура
• 3.2.1: Узлы
• 4: Руководства
• 4.1: Привет, Minikube
• 4.2: Основы Kubernetes
• 4.2.1: Создание кластера
• 4.2.1.1: Использование Minikube для создания кластера
• 4.2.1.2: Интерактивный урок - Создание кластера
• 4.2.2: Развёртывание приложения
• 4.2.2.1: Использование kubectl для развёртывания приложения
• 4.2.2.2: Интерактивный урок - Развёртывание приложения
• 4.2.3: Изучение приложения
• 4.2.3.1: Изучение подов и узлов
• 4.2.3.2: Интерактивный урок - Изучение приложения
• 4.2.4: Открытие доступа к приложению
• 4.2.4.1: Создание сервиса для открытия доступа к приложению
• 4.2.4.2: Интерактивный урок - Открытие доступа к приложению
• 4.2.5: Масштабирование приложения
• 4.2.5.1: Запуск нескольких экземпляров приложения
• 4.2.5.2: Интерактивный урок - Масштабирование приложения
• 4.2.6: Обновление приложения
• 4.2.6.1: Выполнение плавающего обновления
• 4.2.6.2: Интерактивный урок - Обновление приложения
• 5: Ссылки
• 5.1: Стандартизированный глоссарий
• 5.2: kubectl CLI
• 5.2.1: Обзор kubectl
• 5.2.2: Поддержка JSONPath
• 5.2.3: kubectl
• 5.2.4: kubectl для пользователей Docker
• 5.2.5: Команды kubectl
• 5.2.6: Шпаргалка по kubectl
• 6: Участие в документации Kubernetes
• 6.1: Участие для начинающих
• 6.2: Участие для продвинутых
• 6.3: Участие для опытных
• 6.4: Обзор оформления документации
• 6.4.1: Руководство по оформлению документации
• 6.4.2: Руководство по содержанию документации
• 6.4.3: Написание новой темы
• 6.4.4: Использование шаблонов страниц
• 6.4.5: Организация контента
• 6.4.6: Пользовательские макрокоды Hugo
• 6.5: Обзор справочной документации
• 6.5.1: Участие в основном коде Kubernetes
• 6.5.2: Руководство по быстрому старту
• 6.5.3: Генерация справочной документации для API Kubernetes
• 6.5.4: Генерация справочной документации для команд kubectl
• 6.5.5: Генерация справочных страниц для компонентов и инструментов Kubernetes
• 6.6: Локализация документации Kubernetes
• 6.7: Участие в SIG Docs

1 - Документация по Kubernetes

1.1 - Версии Kubernetes с поддержкой документации

На сайте можно найти документацию для текущей и четырёх прошлых версий Kubernetes.

Текущая версия

Текущая версия: v1.20.

Предыдущие версии

• v1.24
• v1.23
• v1.22
• v1.21

2 - Настройка

Используйте информацию на этой странице, чтобы найти наиболее подходящее для вас решение по установке и настройке.

Решение о том, как запускать Kubernetes, зависит от доступных ресурсов и необходимого уровня гибкости использования. Запуск Kubernetes возможен практически на чём угодно, от вашего ноутбука или виртуальных машины у облачного провайдера и до физических серверов. Решения позволяют как настроить полностью управляемый кластер запуском единственной команды так и создать пользовательский кластер на физических серверах.

Решения для запуска на локальной машине

Запуск на локальной машине позволяет легко начать работу с Kubernetes. Можно создавать и тестировать кластер Kubernetes не беспокоясь о трате облачных ресурсов и квотах.

Вам следует выбрать запуск на локальной машине, если вы:

• Пробуете или начинаете работу с Kubernetes
• Локально разрабатываете и тестируете кластер

Выбрать решение для запуска на локальной машине.

Управляемые решения

Управляемые решения позволяют надёжно и удобно создавать и поддерживать кластеры Kubernetes. Они настраивают и управляют кластером самостоятельно, не требуя ручного вмешательства.

Вам следует выбрать управляемое решение, если вы:

• Хотите получить полностью самоуправляемое решение
• Хотите сконцентрироваться на разработке собственных приложений или сервисов
• Хотите получить высокую доступность, но у вас нет выделенной команды по обеспечению надёжности приложения (SRE).
• Не имеете ресурсов для размещения и мониторинга собственных кластеров

Выбрать управляемое решение.

Облачные решения "под ключ"

Такие решения позволяют создавать кластеры Kubernetes с помощью небольшого количества команд. Эти решения имеют большую поддержку сообществом и активно развиваются. Они могут быть размещены на разнообразных IaaS облачных провайдерах, при этом предлагая большую свободу и гибкость в обмен на приложенные усилия.

Вам следует выбрать облачное решение "под ключ", если вы:

• Хотите получить больший контроль над кластерами, чем позволяют размещённые решения
• Хотите получить больше контроля над операциями

Выбрать облачное решение "под ключ"

Местное резервное решение "под ключ"

Такие решения позволяют с помощью небольшого количества команд создавать кластеры Kubernetes в ваших внутренних, защищённых облачных сетях.

Вам следует выбрать местное резервное решение "под ключ", если:

• Вы хотите развернуть кластер в приватной облачной сети
• У вас есть выделенная команда SRE-специалистов
• У вас есть ресурсы для размещения и мониторинга собственных кластеров

Выбрать местное резервное решение "под ключ".

Пользовательские решения

Пользовательские решения позволяют достичь наибольшей свободы в управлении кластерами, но при этом требуют наибольшей экспертизы. Можно найти такие решения как для размещения на физических серверах, так и у облачных провайдеров на разных операционных системах.

Выбрать пользовательское решение.

Что дальше

Перейти к выбору подходящего решения, чтобы ознакомить с полным списком доступных решений.

2.1 - Среда обучения

2.1.1 - Установка Kubernetes с помощью Minikube

Minikube — это инструмент, позволяющий легко запускать Kubernetes на локальной машине. Для тех, кто хочет попробовать Kubernetes или рассмотреть возможность его использования в повседневной разработке, Minikube станет отличным вариантом, потому что он запускает одноузловой кластер Kubernetes внутри виртуальной машины (VM) на компьютере пользователя.

Возможности Minikube

Minikube поддерживает следующие возможности Kubernetes:

• DNS
• Сервисы NodePort
• Словари конфигурации (ConfigMaps) и секреты (Secrets)
• Панель управления (Dashboard)
• Среда выполнения контейнера: Docker, CRI-O и containerd
• Поддержка CNI (Container Network Interface)
• Ingress

Установка

Посмотрите страницу Установка Minikube.

Краткое руководство

Эта простая демонстрация поможет запустить, использовать и удалить Minikube на локальной машине. Следуйте перечисленным ниже шагам, чтобы начать знакомство с Minikube.

1. Запустите Minikube и создайте кластер:

   minikube start
   

   Вывод будет примерно следующим:

   Starting local Kubernetes cluster...
   Running pre-create checks...
   Creating machine...
   Starting local Kubernetes cluster...
   

   Дополнительную информацию о запуске кластера в определенной версии Kubernetes, виртуальной машине или среде выполнения контейнера смотрите в разделе Запуск кластера.

2. Теперь вы можете работать со своим кластером через CLI-инструмент kubectl. Для получения дополнительной информации смотрите раздел Работа с кластером.

   Давайте создадим развёртывание (Deployment) в Kubernetes, используя существующий образ echoserver, представляющий простой HTTP-сервер, и сделаем его доступным на порту 8080 с помощью --port.

   kubectl create deployment hello-minikube --image=k8s.gcr.io/echoserver:1.10
   

   Вывод будет примерно следующим:

   deployment.apps/hello-minikube created
   

3. Чтобы получить доступ к объекту Deployment hello-minikube извне, создайте объект сервиса (Service):

   kubectl expose deployment hello-minikube --type=NodePort --port=8080
   

   Опция --type=NodePort определяет тип сервиса.

   Вывод будет примерно следующим:

   service/hello-minikube exposed
   

4. Под (Pod) hello-minikube теперь запущен, но нужно подождать, пока он начнёт функционировать, прежде чем обращаться к нему.

   Проверьте, что под работает:

   kubectl get pod
   

   Если в столбце вывода STATUS выводится ContainerCreating, значит под все еще создается:

   NAME                              READY     STATUS              RESTARTS   AGE
   hello-minikube-3383150820-vctvh   0/1       ContainerCreating   0          3s
   

   Если в столбце STATUS указано Running, то под теперь в рабочем состоянии:

   NAME                              READY     STATUS    RESTARTS   AGE
   hello-minikube-3383150820-vctvh   1/1       Running   0          13s
   

5. Узнайте URL-адрес открытого (exposed) сервиса, чтобы просмотреть подробные сведения о сервисе:

   minikube service hello-minikube --url
   

6. Чтобы ознакомиться с подробной информацией о локальном кластере, скопируйте и откройте полученный из вывода команды на предыдущем шаге URL-адрес в браузере.

   Вывод будет примерно следующим:

   Hostname: hello-minikube-7c77b68cff-8wdzq
   
   Pod Information:
       -no pod information available-
   
   Server values:
       server_version=nginx: 1.13.3 - lua: 10008
   
   Request Information:
       client_address=172.17.0.1
       method=GET
       real path=/
       query=
       request_version=1.1
       request_scheme=http
       request_uri=http://192.168.99.100:8080/
   
   Request Headers:
       accept=*/*
       host=192.168.99.100:30674
       user-agent=curl/7.47.0
   
   Request Body:
       -no body in request-
   

   Если сервис и кластер вам больше не нужны, их можно удалить.

7. Удалите сервис hello-minikube:

   kubectl delete services hello-minikube
   

   Вывод будет примерно следующим:

   service "hello-minikube" deleted
   

8. Удалите развёртывание hello-minikube:

   kubectl delete deployment hello-minikube
   

   Вывод будет примерно следующим:

   deployment.extensions "hello-minikube" deleted
   

9. Остановите локальный кластер Minikube:

   minikube stop
   

   Вывод будет примерно следующим:

   Stopping "minikube"...
   "minikube" stopped.
   

   Подробности смотрите в разделе Остановка кластера.

10. Удалите локальный кластер Minikube:

    minikube delete
    

    Вывод будет примерно следующим:

    Deleting "minikube" ...
    The "minikube" cluster has been deleted.
    

    Подробности смотрите в разделе Удаление кластера.

Управление кластером

Запуск кластера

Команда minikube start используется для запуска кластера. Эта команда создаёт и конфигурирует виртуальную машину, которая запускает одноузловой кластер Kubernetes. Эта команда также настраивает вашу установку kubectl для взаимодействия с этим кластером.

Заметка:

Если вы работаете из-под веб-прокси, вам нужно указать данные прокси в команде minikube start:

https_proxy=<my proxy> minikube start --docker-env http_proxy=<my proxy> --docker-env https_proxy=<my proxy> --docker-env no_proxy=192.168.99.0/24

К сожалению, установка переменных окружения не cработает.

Minikube также создает контекст "minikube" и устанавливает его по умолчанию в kubectl. Чтобы вернуться к этому контексту, выполните следующую команду: kubectl config use-context minikube.

Указание версии Kubernetes

Вы можете указать используемую версию Kubernetes в Minikube, добавив параметр --kubernetes-version в команду minikube start. Например, чтобы запустить Minikube из-под версии v1.20.15, вам нужно выполнить следующую команду:

minikube start --kubernetes-version v1.20.15

Указание драйвера виртуальной машины

Вы можете изменить драйвер виртуальной машины, добавив флаг --vm-driver=<enter_driver_name> в команду minikube start.

Тогда команда будет выглядеть так:

minikube start --vm-driver=<driver_name>

Minikube поддерживает следующие драйверы:

Заметка: Смотрите страницу DRIVERS для получения подробной информации о поддерживаемых драйверах и как устанавливать плагины.

• virtualbox
• vmwarefusion
• docker (ЭКСПЕРИМЕНТАЛЬНЫЙ)
• kvm2 (установка драйвера)
• hyperkit (установка драйвера)
• hyperv (установка драйвера) Обратите внимание, что указанный IP-адрес на этой странице является динамическим и может изменяться. Его можно получить с помощью minikube ip.
• vmware (установка драйвера) (VMware unified driver)
• parallels (установка драйвера)
• none (Запускает компоненты Kubernetes на хосте, а не на виртуальной машине. Использование этого драйвера требует использование Linux и установленного Docker.)

Внимание: Если вы используете драйвер none, некоторые компоненты Kubernetes запускаются как привилегированные контейнеры, которые имеют побочные эффекты вне окружения Minikube. Эти побочные эффекты означают, что драйвер none не рекомендуется использовать в личных рабочих станций.

Запуск кластера в других средах выполнения контейнеров

Вы можете запустить Minikube в следующих средах выполнения контейнеров.

• containerd
• CRI-O

minikube start \
    --network-plugin=cni \
    --enable-default-cni \
    --container-runtime=containerd \
    --bootstrapper=kubeadm

minikube start \
    --network-plugin=cni \
    --enable-default-cni \
    --extra-config=kubelet.container-runtime=remote \
    --extra-config=kubelet.container-runtime-endpoint=unix:///run/containerd/containerd.sock \
    --extra-config=kubelet.image-service-endpoint=unix:///run/containerd/containerd.sock \
    --bootstrapper=kubeadm

minikube start \
    --network-plugin=cni \
    --enable-default-cni \
    --container-runtime=cri-o \
    --bootstrapper=kubeadm

minikube start \
    --network-plugin=cni \
    --enable-default-cni \
    --extra-config=kubelet.container-runtime=remote \
    --extra-config=kubelet.container-runtime-endpoint=/var/run/crio.sock \
    --extra-config=kubelet.image-service-endpoint=/var/run/crio.sock \
    --bootstrapper=kubeadm

Использование локальных образов путём повторного использования демона Docker

При использовании одной виртуальной машины для Kubernetes легко повторно использовать демон Docker, встроенный в Minikube. В этом случае нет необходимости создавать реестр Docker на вашей хост-машине и отправлять образ туда. Вместо этого вы можете создать реестр внутри того же демона Docker, который использует Minikube, что позволит ускорить локальные запуски.

Заметка: Обязательно пометьте собственным тегом Docker-образ, и затем при получении образа всегда указывайте его. Так как :latest — это тег по умолчанию, поэтому наряду с соответствующей стандартной политикой получения образа, равной Always, в конечном итоге возникнет ошибка при получении образа (ErrImagePull), если Docker-образ не найден в базовом реестре Docker (как правило, в DockerHub).

Для работы с Docker-демоном на вашем хосте под управлением Mac/Linux, запустите последнюю строку из вывода команды minikube docker-env.

Теперь вы можете использовать Docker в командной строке вашего хост-компьютера на Mac/Linux для взаимодействия с демоном Docker внутри виртуальной машины Minikube:

docker ps

Заметка:

На Centos 7 Docker может возникнуть следующая ошибка:

Could not read CA certificate "/etc/docker/ca.pem": open /etc/docker/ca.pem: no such file or directory

Для исправления этой ошибки обновите файл /etc/sysconfig/docker, чтобы учитывались изменения в среде Minikube:

< DOCKER_CERT_PATH=/etc/docker
---
> if [ -z "${DOCKER_CERT_PATH}" ]; then
>   DOCKER_CERT_PATH=/etc/docker
> fi

Конфигурация Kubernetes

Minikube имеет такую возможность как "конфигуратор" ("configurator"), позволяющая пользователям настраивать компоненты Kubernetes произвольными значениями. Чтобы использовать эту возможность, используйте флаг --extra-config в команде minikube start.

Этот флаг можно дублировать, поэтому вы можете указать его несколько раз с несколькими разными значениями, чтобы установить несколько опций.

Этот флаг принимает строку вида component.key=value, где component — это одно из значение в приведённом ниже списка, key — ключ из структуры конфигурации, а value — значение, которое нужно установить.

Допустимые ключи можно найти в документации по componentconfigs в Kubernetes каждого компонента. Ниже вы найдете документации по каждой поддерживаемой конфигурации:

• kubelet
• apiserver
• proxy
• controller-manager
• etcd
• scheduler

Примеры

Чтобы изменить настройку MaxPods на значение 5 в Kubelet, передайте этот флаг --extra-config=kubelet.MaxPods=5.

Эта возможность также поддерживает вложенные структуры. Для изменения настройки LeaderElection.LeaderElect на значение true в планировщике, передайте флаг --extra-config=scheduler.LeaderElection.LeaderElect=true.

Чтобы изменить настройку AuthorizationMode в apiserver на значение RBAC, используйте флаг --extra-config=apiserver.authorization-mode=RBAC.

Остановка кластера

Команда minikube stop используется для остановки кластера. Эта команда выключает виртуальную машины Minikube, но сохраняет всё состояние кластера и данные. Повторный запуск кластера вернет его в прежнее состояние.

Удаление кластера

Команда minikube delete используется для удаления кластера. Эта команда выключает и удаляет виртуальную машину Minikube. Данные или состояние не сохраняются.

Обновление minikube

Смотрите инструкцию по обновлению minikube.

Работа с кластером

Kubectl

Команда minikube start создает контекст kubectl под именем "minikube". Этот контекст содержит конфигурацию для взаимодействия с кластером Minikube.

Minikube автоматически устанавливает этот контекст, но если вам потребуется явно использовать его в будущем, выполните команду ниже:

kubectl config use-context minikube

Либо передайте контекст при выполнении команды следующим образом: kubectl get pods --context=minikube.

Панель управления

Чтобы получить доступ к веб-панели управления Kubernetes, запустите эту команду в командной оболочке после запуска Minikube, чтобы получить адрес:

minikube dashboard

Сервисы

Чтобы получить доступ к сервису, открытой через порт узла, выполните команду в командной оболочке после запуска Minikube, чтобы получить адрес:

minikube service [-n NAMESPACE] [--url] NAME

Организация сети

Виртуальная машина Minikube доступна только хост-системе через IP-адрес, который можно получить с помощью команды minikube ip. Вы можете использовать IP-адрес для доступа к любому сервису типа NodePort.

Чтобы определить NodePort для вашего сервиса, вы можете использовать такую команду kubectl:

kubectl get service $SERVICE --output='jsonpath="{.spec.ports[0].nodePort}"'

Постоянные тома

Minikube поддерживает PersistentVolumes типа hostPath. Эти постоянные тома монтируются в виртуальную машину Minikube.

Виртуальная машина Minikube загружается в файловую систему tmpfs, поэтому большинство директорий не будет сохранено при перезагрузках (minikube stop). Однако Minikube сконфигурирован на сохранение файлов, хранящихся в перечисленных ниже директорий хоста.

• /data
• /var/lib/minikube
• /var/lib/docker

Пример конфигурации PersistentVolume для сохранения данных в директории /data:

apiVersion: v1
kind: PersistentVolume
metadata:
  name: pv0001
spec:
  accessModes:
    - ReadWriteOnce
  capacity:
    storage: 5Gi
  hostPath:
    path: /data/pv0001/

Смонтированные директории хоста

Некоторые драйверы монтируют директорию хоста в виртуальную машину, чтобы можно было легко обмениваться файлами между виртуальной машиной и хостом. В настоящее время это не настраивается и отличается от используемого драйвера и ОС.

Заметка: Совместное использование директории хоста еще не реализовано в драйвере KVM.

Приватные реестры контейнеров

Для доступа к реестру приватных контейнеров, выполните шаги, описанные на этой странице.

Мы рекомендуем использовать ImagePullSecrets, но если вам нужно обратиться к нему из виртуальной машины Minikube, нужно поместить файл .dockercfg в директорию /home/docker или config.json в директорию /home/docker/.docker.

Дополнения

Для того, чтобы Minikube смог запустить или перезапустить пользовательские дополнения, поместите дополнения, которые вы хотите запускать с помощью Minikube, в директорию ~/.minikube/addons. Дополнения в этой директории будут перемещены в виртуальную машину Minikube и запускаться каждый раз при запуске или перезапуске Minikube.

Использование Minikube с помощью HTTP-прокси

Minikube создаёт виртуальную машину, включающая в себя Kubernetes и демон Docker. Когда Kubernetes планирует выполнение контейнеров с использованием Docker, демону Docker может потребоваться доступ к внешней сети для получения контейнеров.

Если вы работаете через HTTP-прокси, вам нужно сконфигурировать настройки прокси для Docker. Для этого нужно передать необходимые переменные окружения в флаги перед выполнением команды minikube start.

Например:

minikube start --docker-env http_proxy=http://$YOURPROXY:PORT \
                 --docker-env https_proxy=https://$YOURPROXY:PORT

Если адрес вашей виртуальной машины 192.168.99.100, то, скорее всего, настройки прокси помешают kubectl обратиться к ней. Чтобы прокси игнорировал этот IP-адрес, нужно скорректировать настройки no_proxy следующим образом:

export no_proxy=$no_proxy,$(minikube ip)

Известные проблемы

Функциональность, для которой требуется несколько узлов, не будет работать в Minikube.

Реализация

Minikube использует libmachine для подготовки виртуальных машин и kubeadm для инициализации кластера Kubernetes.

Для получения дополнительной информации о Minikube посмотрите статью.

Дополнительные ссылки

• Цели: цели проекта Minikube смотрите в дорожной карте.
• Руководство по разработке: посмотрите CONTRIBUTING.md, чтобы ознакомиться с тем, как отправлять пулрексты.
• Сборка Minikube: инструкции по сборке/тестированию Minikube из исходного кода смотрите в руководстве по сборке.
• Добавление новой зависимости: инструкции по добавлению новой зависимости в Minikube смотрите в руководстве по добавлению зависимостей.
• Добавление нового дополнения: инструкции по добавлению нового дополнения для Minikube смотрите в руководстве по добавлению дополнений.
• MicroK8: пользователи Linux, которые не хотят использовать виртуальную машину, могут в качестве альтернативы посмотреть в сторону MicroK8s.

Сообщество

Помощь, вопросы и комментарии приветствуются и поощряются! Разработчики Minikube проводят время на Slack в канале #minikube (получить приглашение можно здесь). У нас также есть список рассылки kubernetes-dev на Google Groups. Если вы отправляете сообщение в список, пожалуйста, начните вашу тему с "minikube: ".

2.1.2 - Установка Kubernetes с помощью Kind

Kind — это инструмент для запуска локальных кластеров Kubernetes с помощью "узлов" контейнера Docker.

Установка

Смотрите страницу по установке Kind.

2.2 - Пользовательские облачные решения

3 - Концепции

Раздел "Концепции" поможет вам узнать о частях системы Kubernetes и об абстракциях, которые Kubernetes использует для представления вашего кластера, и помогает вам глубже понять, как работает Kubernetes.

Краткий обзор

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

После того, как вы установили желаемое состояние, Плоскость управления Kubernetes заставляет текущее состояние кластера соответствовать желаемому состоянию с помощью генератора событий жизненного цикла подов (Pod Lifecycle Event Generator, PLEG). Для этого Kubernetes автоматически выполняет множество задач, таких как запуск или перезапуск контейнеров, масштабирование количества реплик данного приложения и многое другое. Плоскость управления Kubernetes состоит из набора процессов, запущенных в вашем кластере:

• Мастер Kubernetes — это коллекция из трех процессов, которые выполняются на одном узле в вашем кластере, который обозначен как главный узел. Это процессы: kube-apiserver, kube-controller-manager и kube-scheduler.
• Каждый отдельный неосновной узел в вашем кластере выполняет два процесса:
  • kubelet, который взаимодействует с мастером Kubernetes.
  • kube-proxy, сетевой прокси, который обрабатывает сетевые сервисы Kubernetes на каждом узле.

Объекты Kubernetes

Kubernetes содержит ряд абстракций, которые представляют состояние вашей системы: развернутые контейнеризованные приложения и рабочие нагрузки, связанные с ними сетевые и дисковые ресурсы и другую информацию о том, что делает ваш кластер. Эти абстракции представлены объектами в API Kubernetes. См. Понимание объектов Kubernetes для получения более подробной информации.

Основные объекты Kubernetes включают в себя:

• Pod
• Service
• Том
• Namespace

Kubernetes также содержит абстракции более высокого уровня, которые опираются на Контроллеры для создания базовых объектов и предоставляют дополнительные функциональные и удобные функции. Они включают:

• Deployment
• DaemonSet
• StatefulSet
• ReplicaSet
• Job

Плоскость управления Kubernetes

Различные части панели управления Kubernetes, такие как мастер Kubernetes и процессы kubelet, определяют, как Kubernetes взаимодействует с кластером. Плоскость управления поддерживает запись всех объектов Kubernetes в системе и запускает непрерывные циклы управления для обработки состояния этих объектов. В любое время циклы управления панели управления будут реагировать на изменения в кластере и работать, чтобы фактическое состояние всех объектов в системе соответствовало желаемому состоянию, которое вы указали.

Например, когда вы используете API Kubernetes для создания развертывания, вы предоставляете новое желаемое состояние для системы. Плоскость управления Kubernetes записывает создание этого объекта и выполняет ваши инструкции, запуская необходимые приложения и планируя их на узлы кластера, чтобы фактическое состояние кластера соответствовало желаемому состоянию.

Мастер Kubernetes

Мастер Kubernetes отвечает за поддержание желаемого состояния для вашего кластера. Когда вы взаимодействуете с Kubernetes, например, используя интерфейс командной строки kubectl, вы работаете с мастером Kubernetes вашего кластера.

Под "мастером" понимается совокупность процессов, которые управляют состоянием кластера. Обычно все эти процессы выполняются на одном узле кластера, и поэтому этот узел называется главным (master). Мастер также может быть реплицирован для доступности и резервирования.

Узлы Kubernetes

Узлы в кластере - это машины (виртуальные машины, физические серверы и т.д.), на которых работают ваши приложения и облачные рабочие процессы. Мастер Kubernetes контролирует каждый узел; вы редко будете взаимодействовать с узлами напрямую.

Что дальше

Если вы хотите описать концепт, обратитесь к странице Использование шаблонов страниц для получения информации о типе страницы и шаблоне концепции.

3.1 - Обзор

3.1.1 - Что такое Kubernetes

Эта страница посвящена краткому обзору Kubernetes.

Kubernetes — это портативная расширяемая платформа с открытым исходным кодом для управления контейнеризованными рабочими нагрузками и сервисами, которая облегчает как декларативную настройку, так и автоматизацию. У платформы есть большая, быстро растущая экосистема. Сервисы, поддержка и инструменты Kubernetes широко доступны.

Название Kubernetes происходит от греческого, что означает рулевой или штурман. Google открыл исходный код Kubernetes в 2014 году. Kubernetes основывается на десятилетнем опыте работе Google с масштабными рабочими нагрузками, в сочетании с лучшими в своем классе идеями и практиками сообщества.

История

Давайте вернемся назад и посмотрим, почему Kubernetes так полезен.

Традиционная эра развертывания: Ранее организации запускали приложения на физических серверах. Не было никакого способа определить границы ресурсов для приложений на физическом сервере, и это вызвало проблемы с распределением ресурсов. Например, если несколько приложений выполняются на физическом сервере, могут быть случаи, когда одно приложение будет занимать большую часть ресурсов, и в результате чего другие приложения будут работать хуже. Решением этого было запустить каждое приложение на другом физическом сервере. Но это не масштабировалось, поскольку ресурсы использовались не полностью, из-за чего организациям было накладно поддерживать множество физических серверов.

Эра виртуального развертывания: В качестве решения была представлена виртуализация. Она позволила запускать несколько виртуальных машин (ВМ) на одном физическом сервере. Виртуализация изолирует приложения между виртуальными машинами и обеспечивает определенный уровень безопасности, поскольку информация одного приложения не может быть свободно доступна другому приложению.

Виртуализация позволяет лучше использовать ресурсы на физическом сервере и обеспечивает лучшую масштабируемость, поскольку приложение можно легко добавить или обновить, кроме этого снижаются затраты на оборудование и многое другое. С помощью виртуализации можно превратить набор физических ресурсов в кластер одноразовых виртуальных машин.

Каждая виртуальная машина представляет собой полноценную машину, на которой выполняются все компоненты, включая собственную операционную систему, поверх виртуализированного оборудования.

Эра контейнеров: Контейнеры похожи на виртуальные машины, но у них есть свойства изоляции для совместного использования операционной системы (ОС) между приложениями. Поэтому контейнеры считаются легкими. Подобно виртуальной машине, контейнер имеет свою собственную файловую систему, процессор, память, пространство процесса и многое другое. Поскольку они не связаны с базовой инфраструктурой, они переносимы между облаками и дистрибутивами ОС.

Контейнеры стали популярными из-за таких дополнительных преимуществ как:

• Гибкое создание и развертывание приложений: простота и эффективность создания образа контейнера по сравнению с использованием образа виртуальной машины.
• Непрерывная разработка, интеграция и развертывание: обеспечивает надежную и частую сборку и развертывание образа контейнера с быстрым и простым откатом (благодаря неизменности образа).
• Разделение задач между Dev и Ops: создавайте образы контейнеров приложений во время сборки/релиза, а не во время развертывания, тем самым отделяя приложения от инфраструктуры.
• Наблюдаемость охватывает не только информацию и метрики на уровне ОС, но также информацию о работоспособности приложений и другие сигналы.
• Идентичная окружающая среда при разработке, тестировании и релизе: на ноутбуке работает так же, как и в облаке.
• Переносимость облачных и операционных систем: работает на Ubuntu, RHEL, CoreOS, on-prem, Google Kubernetes Engine и в любом другом месте.
• Управление, ориентированное на приложения: повышает уровень абстракции от запуска ОС на виртуальном оборудовании до запуска приложения в ОС с использованием логических ресурсов.
• Слабосвязанные, распределенные, гибкие, выделенные микросервисы: вместо монолитного стека на одной большой выделенной машине, приложения разбиты на более мелкие независимые части, которые можно динамически развертывать и управлять.
• Изоляция ресурсов: предсказуемая производительность приложения.
• Грамотное использование ресурсов: высокая эффективность и компактность.

Зачем вам Kubernetes и что он может сделать?

Контейнеры — отличный способ связать и запустить ваши приложения. В производственной среде необходимо управлять контейнерами, которые запускают приложения, и гарантировать отсутствие простоев. Например, если контейнер выходит из строя, необходимо запустить другой контейнер. Не было бы проще, если бы такое поведение обрабатывалось системой?

Вот тут Kubernetes приходит на помощь! Kubernetes дает вам фреймворк для гибкой работы распределенных систем. Он занимается масштабированием и обработкой ошибок в приложении, предоставляет шаблоны развертывания и многое другое. Например, Kubernetes может легко управлять канареечным развертыванием вашей системы.

Kubernetes предоставляет вам:

• Мониторинг сервисов и распределение нагрузки Kubernetes может обнаружить контейнер, используя имя DNS или собственный IP-адрес. Если трафик в контейнере высокий, Kubernetes может сбалансировать нагрузку и распределить сетевой трафик, чтобы развертывание было стабильным.
• Оркестрация хранилища Kubernetes позволяет вам автоматически смонтировать систему хранения по вашему выбору, такую как локальное хранилище, провайдеры общедоступного облака и многое другое.
• Автоматическое развертывание и откаты Используя Kubernetes можно описать желаемое состояние развернутых контейнеров и изменить фактическое состояние на желаемое. Например, вы можете автоматизировать Kubernetes на создание новых контейнеров для развертывания, удаления существующих контейнеров и распределения всех их ресурсов в новый контейнер.
• Автоматическое распределение нагрузки Вы предоставляете Kubernetes кластер узлов, который он может использовать для запуска контейнерных задач. Вы указываете Kubernetes, сколько ЦП и памяти (ОЗУ) требуется каждому контейнеру. Kubernetes может разместить контейнеры на ваших узлах так, чтобы наиболее эффективно использовать ресурсы.
• Самоконтроль Kubernetes перезапускает отказавшие контейнеры, заменяет и завершает работу контейнеров, которые не проходят определенную пользователем проверку работоспособности, и не показывает их клиентам, пока они не будут готовы к обслуживанию.
• Управление конфиденциальной информацией и конфигурацией Kubernetes может хранить и управлять конфиденциальной информацией, такой как пароли, OAuth-токены и ключи SSH. Вы можете развертывать и обновлять конфиденциальную информацию и конфигурацию приложения без изменений образов контейнеров и не раскрывая конфиденциальную информацию в конфигурации стека.

Чем Kubernetes не является

Kubernetes ― это не традиционная комплексная система PaaS (платформа как услуга). Поскольку Kubernetes работает на уровне контейнеров, а не на уровне оборудования, у него имеется определенные общеприменимые возможности, характерные для PaaS, такие как развертывание, масштабирование, балансировка нагрузки, ведение журналов и мониторинг. Тем не менее, Kubernetes это не монолитное решение, поэтому указанные возможности по умолчанию являются дополнительными и подключаемыми. У Kubernetes есть компоненты для создания платформы разработчика, но он сохраняет право выбора за пользователем и гибкость там, где это важно.

Kubernetes:

• Не ограничивает типы поддерживаемых приложений. Kubernetes стремится поддерживать широкий спектр рабочих нагрузок, включая те, у которых есть или отсутствует состояние, а также связанные с обработкой данных. Если приложение может работать в контейнере, оно должно отлично работать и в Kubernetes.
• Не развертывает исходный код и не собирает приложение. Рабочие процессы непрерывной интеграции, доставки и развертывания (CI/CD) определяются культурой и предпочтениями организации, а также техническими требованиями.
• Не предоставляет сервисы для приложения, такие как промежуточное программное обеспечение (например, очереди сообщений), платформы обработки данных (например, Spark), базы данных (например, MySQL), кеши или кластерные системы хранения (например, Ceph), как встроенные сервисы. Такие компоненты могут работать в Kubernetes и/или могут быть доступны для приложений, работающих в Kubernetes, через переносные механизмы, такие как Open Service Broker.
• Не включает решения для ведения журнала, мониторинга или оповещения. Он обеспечивает некоторые интеграции в качестве доказательства концепции и механизмы для сбора и экспорта метрик.
• Не указывает и не требует настройки языка/системы (например, Jsonnet). Он предоставляет декларативный API, который может быть нацелен на произвольные формы декларативных спецификаций.
• Не предоставляет и не принимает никаких комплексных систем конфигурации, технического обслуживания, управления или самовосстановления.
• Кроме того, Kubernetes — это не просто система оркестрации. Фактически, Kubernetes устраняет необходимость в этом. Техническое определение оркестрации — это выполнение определенного рабочего процесса: сначала сделай A, затем B, затем C. Напротив, Kubernetes содержит набор независимых, компонуемых процессов управления, которые непрерывно переводит текущее состояние к предполагаемому состоянию. Неважно, как добраться от А до С. Не требуется также централизованный контроль. Это делает систему более простой в использовании, более мощной, надежной, устойчивой и расширяемой.

Что дальше

• Изучите Компоненты Kubernetes
• Готовы начать?

3.1.2 - Компоненты Kubernetes

При развёртывании Kubernetes вы имеете дело с кластером.

Кластер Kubernetes cluster состоит из набор машин, так называемые узлы, которые запускают контейнеризированные приложения. Кластер имеет как минимум один рабочий узел.

В рабочих узлах размещены поды, являющиеся компонентами приложения. Плоскость управления управляет рабочими узлами и подами в кластере. В промышленных средах плоскость управления обычно запускается на нескольких компьютерах, а кластер, как правило, развёртывается на нескольких узлах, гарантируя отказоустойчивость и высокую надёжность.

На этой странице в общих чертах описывается различные компоненты, необходимые для работы кластера Kubernetes.

Ниже показана диаграмма кластера Kubernetes со всеми связанными компонентами.

Плоскость управления компонентами

Компоненты панели управления отвечают за основные операции кластера (например, планирование), а также обрабатывают события кластера (например, запускают новый под, когда поле replicas развертывания не соответствует требуемому количеству реплик).

Компоненты панели управления могут быть запущены на любой машине в кластере. Однако для простоты сценарии настройки обычно запускают все компоненты панели управления на одном компьютере и в то же время не позволяют запускать пользовательские контейнеры на этом компьютере. Смотрите страницу Создание высоконадёжных кластеров для примера настройки нескольких ведущих виртуальных машин.

kube-apiserver

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

Основной реализацией API-сервера Kubernetes является kube-apiserver. kube-apiserver предназначен для горизонтального масштабирования, то есть развёртывание на несколько экземпляров. Вы можете запустить несколько экземпляров kube-apiserver и сбалансировать трафик между этими экземплярами.

etcd

Распределённое и высоконадёжное хранилище данных в формате "ключ-значение", которое используется как основное хранилище всех данных кластера в Kubernetes.

Если ваш кластер Kubernetes использует etcd в качестве основного хранилища, убедитесь, что у вас настроено резервное копирование данных.

Вы можете найти подробную информацию о etcd в официальной документации.

kube-scheduler

Компонент плоскости управления, который отслеживает созданные поды без привязанного узла и выбирает узел, на котором они должны работать.

При планировании развёртывания подов на узлах учитываются множество факторов, включая требования к ресурсам, ограничения, связанные с аппаратными/программными политиками, принадлежности (affinity) и непринадлежности (anti-affinity) узлов/подов, местонахождения данных, предельных сроков.

kube-controller-manager

Компонент Control Plane запускает процессы контроллера.

Вполне логично, что каждый контроллер в свою очередь представляет собой отдельный процесс, и для упрощения все такие процессы скомпилированы в один двоичный файл и выполняются в одном процессе.

Эти контроллеры включают:

• Контроллер узла (Node Controller): уведомляет и реагирует на сбои узла.
• Контроллер репликации (Replication Controller): поддерживает правильное количество подов для каждого объекта контроллера репликации в системе.
• Контроллер конечных точек (Endpoints Controller): заполняет объект конечных точек (Endpoints), то есть связывает сервисы (Services) и поды (Pods).
• Контроллеры учетных записей и токенов (Account & Token Controllers): создают стандартные учетные записи и токены доступа API для новых пространств имен.

cloud-controller-manager

cloud-controller-manager запускает контроллеры, которые взаимодействуют с основными облачными провайдерами. Двоичный файл cloud-controller-manager — это альфа-функциональность, появившиеся в Kubernetes 1.6.

cloud-controller-manager запускает только циклы контроллера, относящиеся к облачному провайдеру. Вам нужно отключить эти циклы контроллера в kube-controller-manager. Вы можете отключить циклы контроллера, установив флаг --cloud-provider со значением external при запуске kube-controller-manager.

С помощью cloud-controller-manager код как облачных провайдеров, так и самого Kubernetes может разрабатываться независимо друг от друга. В предыдущих версиях код ядра Kubernetes зависел от кода, предназначенного для функциональности облачных провайдеров. В будущих выпусках код, специфичный для облачных провайдеров, должен поддерживаться самим облачным провайдером и компоноваться с cloud-controller-manager во время запуска Kubernetes.

Следующие контроллеры зависят от облачных провайдеров:

• Контроллер узла (Node Controller): проверяет облачный провайдер, чтобы определить, был ли удален узел в облаке после того, как он перестал работать
• Контроллер маршрутов (Route Controller): настраивает маршруты в основной инфраструктуре облака
• Контроллер сервисов (Service Controller): создаёт, обновляет и удаляет балансировщики нагрузки облачного провайдера.
• Контроллер тома (Volume Controller): создаёт, присоединяет и монтирует тома, а также взаимодействует с облачным провайдером для оркестрации томов.

Компоненты узла

Компоненты узла работают на каждом узле, поддерживая работу подов и среды выполнения Kubernetes.

kubelet

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

Утилита kubelet принимает набор PodSpecs, и гарантирует работоспособность и исправность определённых в них контейнеров. Агент kubelet не отвечает за контейнеры, не созданные Kubernetes.

kube-proxy

kube-proxy — сетевой прокси, работающий на каждом узле в кластере, и реализующий часть концепции сервис.

kube-proxy конфигурирует правила сети на узлах. При помощи них разрешаются сетевые подключения к вашими подам изнутри и снаружи кластера.

kube-proxy использует уровень фильтрации пакетов в операционной системы, если он доступен. В противном случае, kube-proxy сам обрабатывает передачу сетевого трафика.

Среда выполнения контейнера

Среда выполнения контейнера — это программа, предназначенная для выполнения контейнеров.

Kubernetes поддерживает несколько сред для запуска контейнеров: Docker, containerd, CRI-O, и любая реализация Kubernetes CRI (Container Runtime Interface).

Дополнения

Дополнения используют ресурсы Kubernetes (DaemonSet, Deployment и т.д.) для расширения функциональности кластера. Поскольку дополнения охватывают весь кластер, ресурсы относятся к пространству имен kube-system.

Некоторые из дополнений описаны ниже; более подробный список доступных расширений вы можете найти на странице Дополнения.

DNS

Хотя прочие дополнения не являются строго обязательными, однако при этом у всех Kubernetes-кластеров должен быть кластерный DNS, так как многие примеры предполагают его наличие.

Кластерный DNS — это DNS-сервер наряду с другими DNS-серверами в вашем окружении, который обновляет DNS-записи для сервисов Kubernetes.

Контейнеры, запущенные посредством Kubernetes, автоматически включают этот DNS-сервер в свои DNS.

Веб-интерфейс (Dashboard)

Dashboard — это универсальный веб-интерфейс для кластеров Kubernetes. С помощью этой панели, пользователи могут управлять и устранять неполадки кластера и приложений, работающих в кластере.

Мониторинг ресурсов контейнера

Мониторинг ресурсов контейнера записывает общие метрики о контейнерах в виде временных рядов в центральной базе данных и предлагает пользовательский интерфейс для просмотра этих данных.

Логирование кластера

Механизм логирования кластера отвечает за сохранение логов контейнера в централизованном хранилище логов с возможностью их поиска/просмотра.

Что дальше

• Подробнее про узлы
• Подробнее про контроллеры
• Подробнее про kube-scheduler
• Официальная документация etcd

3.1.3 - API Kubernetes

Общие соглашения API описаны на странице соглашений API.

Конечные точки API, типы ресурсов и примеры описаны в справочнике API.

Удаленный доступ к API обсуждается в Controlling API Access doc.

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

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

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

Изменения в API

Исходя из нашего опыта, любая успешная система должна улучшаться и изменяться по мере появления новых сценариев использования или изменения существующих. Поэтому мы надеемся, что и API Kubernetes будет постоянно меняться и расширяться. Однако в течение продолжительного периода времени мы будем поддерживать хорошую обратную совместимость с существующими клиентами. В целом, новые ресурсы API и поля ресурсов будут добавляться часто. Удаление ресурсов или полей регулируются соответствующим процессом.

Определение совместимого изменения и методы изменения API подробно описаны в документе об изменениях API.

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

Все детали API документируется с использованием OpenAPI.

Начиная с Kubernetes 1.10, API-сервер Kubernetes основывается на спецификации OpenAPI через конечную точку /openapi/v2. Нужный формат устанавливается через HTTP-заголовоки:

До версии 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 реализован альтернативный формат сериализации API, основанный на Protobuf, который в первую очередь предназначен для взаимодействия внутри кластера. Описание этого формата можно найти в проектом решении, а IDL-файлы по каждой схемы — в пакетах Go, определяющих API-объекты.

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

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

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

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

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

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

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

API-группы

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

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

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

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

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

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

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

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

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

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

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

Заметка: Включение/отключение отдельных ресурсов поддерживается только в API-группе extensions/v1beta1 по историческим причинам.

3.1.4 - Работа с объектами Kubernetes

3.1.4.1 - Изучение объектов Kubernetes

На этой странице объясняется, как объекты Kubernetes представлены в API Kubernetes, и как их можно определить в формате .yaml.

Изучение объектов Kubernetes

Объекты Kubernetes — сущности, которые хранятся в Kubernetes. Kubernetes использует их для представления состояния кластера. В частности, они описывают следующую информацию:

• Какие контейнеризированные приложения запущены (и на каких узлах).
• Доступные ресурсы для этих приложений.
• Стратегии управления приложения, которые относятся, например, к перезапуску, обновлению или отказоустойчивости.

После создания объекта Kubernetes будет следить за существованием объекта. Создавая объект, вы таким образом указываете системе Kubernetes, какой должна быть рабочая нагрузка кластера; это требуемое состояние кластера.

Для работы с объектами Kubernetes – будь то создание, изменение или удаление — нужно использовать API Kubernetes. Например, при использовании CLI-инструмента kubectl, он обращается к API Kubernetes. С помощью одной из клиентской библиотеки вы также можете использовать API Kubernetes в собственных программах.

Спецификация и статус объекта

Почти в каждом объекте Kubernetes есть два вложенных поля-объекта, которые управляют конфигурацией объекта: spec и status. При создании объекта в поле spec указывается требуемое состояние (описание характеристик, которые должны быть у объекта).

Поле status описывает текущее состояние объекта, которое создаётся и обновляется самим Kubernetes и его компонентами. Плоскость управления Kubernetes непрерывно управляет фактическим состоянием каждого объекта, чтобы оно соответствовало требуемому состоянию, которое было задано пользователем.

Например: Deployment — это объект Kubernetes, представляющий работающее приложение в кластере. При создании объекта Deployment вы можете указать в его поле spec, что хотите иметь три реплики приложения. Система Kubernetes получит спецификацию объекта Deployment и запустит три экземпляра приложения, таким образом обновит статус (состояние) объекта, чтобы он соответствовал заданной спецификации. В случае сбоя одного из экземпляров (это влечет за собой изменение состояние), Kubernetes обнаружит несоответствие между спецификацией и статусом и исправит его, т.е. активирует новый экземпляр вместо того, который вышел из строя.

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

Описание объекта Kubernetes

При создании объекта в Kubernetes нужно передать спецификацию объекта, которая содержит требуемое состояние, а также основную информацию об объекте (например, его имя). Когда вы используете API Kubernetes для создания объекта (напрямую либо через kubectl), соответствующий API-запрос должен включать в теле запроса всю указанную информацию в JSON-формате. В большинстве случаев вы будете передавать kubectl эти данные, записанные в файле .yaml. Тогда инструмент kubectl преобразует их в формат JSON при выполнении запроса к API.

Ниже представлен пример .yaml-файла, в котором заданы обязательные поля и спецификация объекта, необходимая для объекта Deployment в Kubernetes:

application/deployment.yaml

apiVersion: apps/v1 # до версии 1.9.0 нужно использовать apps/v1beta2
kind: Deployment
metadata:
  name: nginx-deployment
spec:
  selector:
    matchLabels:
      app: nginx
  replicas: 2 # запускает 2 пода, созданных по шаблону
  template:
    metadata:
      labels:
        app: nginx
    spec:
      containers:
      - name: nginx
        image: nginx:1.14.2
        ports:
        - containerPort: 80

Один из способов создания объекта Deployment с помощью файла .yaml, показанного выше — использовать команду kubectl apply, которая принимает в качестве аргумента файл в формате .yaml. Например:

kubectl apply -f https://k8s.io/examples/application/deployment.yaml --record

Вывод будет примерно таким:

deployment.apps/nginx-deployment created

Обязательные поля

В файле .yaml создаваемого объекта Kubernetes необходимо указать значения для следующих полей:

• apiVersion — используемая для создания объекта версия API Kubernetes
• kind — тип создаваемого объекта
• metadata — данные, позволяющие идентифицировать объект (name, UID и необязательное поле namespace)
• spec — требуемое состояние объекта

Конкретный формат поля-объекта spec зависит от типа объекта Kubernetes и содержит вложенные поля, предназначенные только для используемого объекта. В справочнике API Kubernetes можно найти формат спецификации любого объекта Kubernetes. Например, формат spec для объекта Pod находится в ядре PodSpec v1, а формат spec для Deployment — в DeploymentSpec v1 apps.

Что дальше

• Обзор API Kubernetes более подробно объясняет некоторые из API-концепций
• Познакомиться с наиболее важными и основными объектами в Kubernetes, например, с подами.
• Узнать подробнее про контролеры в Kubernetes

3.1.4.2 - Управление объектами Kubernetes

В инструменте командной строки kubectl есть несколько разных способов создания и управления объектами Kubernetes. На этой странице рассматриваются различные подходы. Изучите документацию по Kubectl для получения подробной информации по управлению объектами с помощью Kubectl.

Способы управления

Предупреждение: Используйте только один способ для управления объектами Kubernetes. Применение нескольких методов управления к одному и тому же объекту может привести к неопределенному поведению.

Императивные команды

При использовании императивных команд пользователь работает непосредственно с активными (текущими) объектами в кластере. Пользователь указывает выполняемые операции команде kubectl в качестве аргументов или флагов.

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

Примеры

Запустите экземпляр контейнера nginx, посредством создания объекта Deployment:

kubectl run nginx --image nginx

То же самое, но с другим синтаксисом:

kubectl create deployment nginx --image nginx

Плюсы и минусы

Преимущества по сравнению с конфигурацией объекта:

• Простые команды, которые легко выучить и запомнить.
• Для применения изменений в кластер нужно только выполнить команды.

Недостатки по сравнению с конфигурацией объекта:

• Команды не интегрированы с процессом проверки (обзора) изменений.
• У команд нет журнала с изменениями.
• Команды не дают источник записей, за исключением активных объектов.
• Команды не содержат шаблон для создания новых объектов.

Императивная конфигурация объекта

В случае использования императивной конфигурации объекта команде kubectl устанавливают действие (создание, замена и т.д.), необязательные флаги и как минимум одно имя файла. Файл должен содержать полное определение объекта в формате YAML или JSON.

Посмотрите Справочник API для получения более подробной информации про определения объекта.

Предупреждение: Императивная команда replace заменяет существующую спецификацию новой (переданной), удаляя все изменения в объекте, которые не определены в конфигурационном файле. Такой подход не следует использовать для типов ресурсов, спецификации которых обновляются независимо от конфигурационного файла. Например, поле externalIPs в сервисах типа LoadBalancer обновляется кластером независимо от конфигурации.

Примеры

Создать объекты, определенные в конфигурационном файле:

kubectl create -f nginx.yaml

Удалить объекты, определенные в двух конфигурационных файлах:

kubectl delete -f nginx.yaml -f redis.yaml

Обновить объекты, определенные в конфигурационном файле, перезаписав текущую конфигурацию:

kubectl replace -f nginx.yaml

Плюсы и минусы

Преимущества по сравнению с императивными командами:

• Конфигурация объекта может храниться в системе управления версиями, такой как Git.
• Конфигурация объекта может быть интегрирована с процессами проверки изменений и логирования.
• Конфигурация объекта предусматривает шаблон для создания новых объектов.

Недостатки по сравнению с императивными командами:

• Конфигурация объекта требует наличие общего представления об схеме объекта.
• Конфигурация объекта предусматривает написание файла YAML.

Преимущества по сравнению с декларативной конфигурацией объекта:

• Императивная конфигурация объекта проще и легче для понимания.
• Начиная с Kubernetes 1.5, конфигурация императивных объектов стала лучше и совершеннее.

Недостатки по сравнению с декларативной конфигурацией объекта:

• Императивная конфигурация объекта наилучшим образом работает с файлами, а не с директориями.
• Обновления текущих объектов должны быть описаны в файлах конфигурации, в противном случае они будут потеряны при следующей замене.

Декларативная конфигурация объекта

При использовании декларативной конфигурации объекта пользователь работает с локальными конфигурационными файлами объекта, при этом он не определяет операции, которые будут выполняться над этими файлами. Операции создания, обновления и удаления автоматически для каждого объекта определяются kubectl. Этот механизм позволяет работать с директориями, в ситуациях, когда для разных объектов может потребоваться выполнение других операций.

Заметка: Декларативная конфигурация объекта сохраняет изменения, сделанные другими, даже если эти изменения не будут зафиксированы снова в конфигурационный файл объекта. Это достигается путем использования API-операции patch, чтобы записать только обнаруженные изменения, а не использовать для этого API-операцию replace, которая полностью заменяет конфигурацию объекта.

Примеры

Обработать все конфигурационные файлы объектов в директории configs и создать либо частично обновить активные объекты. Сначала можно выполнить diff, чтобы посмотреть, какие изменения будут внесены, и только после этого применить их:

kubectl diff -f configs/
kubectl apply -f configs/

Рекурсивная обработка директорий:

kubectl diff -R -f configs/
kubectl apply -R -f configs/

Плюсы и минусы

Преимущества по сравнению с императивной конфигурацией объекта:

• Изменения, внесенные непосредственно в активные объекты, будут сохранены, даже если они не отражены в конфигурационных файлах.
• Декларативная конфигурация объекта лучше работает с директориями и автоматически определяет тип операции (создание, частичное обновление, удаление) каждого объекта.

Недостатки по сравнению с императивной конфигурацией объекта:

• Декларативную конфигурацию объекта сложнее отладить и понять, когда можно получить неожиданные результаты.
• Частичные обновления с использованием различий приводит к сложным операциям слияния и исправления.

Что дальше

• Управление объектами Kubernetes с помощью императивных команд
• Управление объектами Kubernetes с помощью императивной конфигурации объекта
• Управление объектами Kubernetes с помощью декларативной конфигурации объекта
• Управление объектами Kubernetes с помощью Kustomize (декларативный способ)
• Справочник по командам Kubectl
• Документация Kubectl
• Справочник API Kubernetes

3.1.4.3 - Имена и идентификаторы объектов

Каждый объект в кластере имеет уникальное имя для конкретного типа ресурса. Кроме этого, у каждого объекта Kubernetes есть собственный уникальный идентификатор (UID) в пределах кластера.

Например, в одном и том же пространстве имён может быть только один Pod-объект с именем myapp-1234, и при этом существовать объект Deployment с этим же названием myapp-1234.

Для создания пользовательских неуникальных атрибутов у Kubernetes есть метки и аннотации.

Имена

Клиентская строка, предназначенная для ссылки на объект в URL-адресе ресурса, например /api/v1/pods/some-name.

Указанное имя может иметь только один объект определённого типа. Но если вы удалите этот объект, вы можете создать новый с таким же именем

Ниже перечислены три типа распространённых требований к именам ресурсов.

Имена поддоменов DNS

Большинству типов ресурсов нужно указать имя, используемое в качестве имени поддомена DNS в соответствии с RFC 1123. Соответственно, имя должно:

• содержать не более 253 символов
• иметь только строчные буквенно-цифровые символы, '-' или '.'
• начинаться с буквенно-цифрового символа
• заканчивается буквенно-цифровым символом

Имена меток DNS

Некоторые типы ресурсов должны соответствовать стандарту меток DNS, который описан в RFC 1123. Таким образом, имя должно:

• содержать не более 63 символов
• содержать только строчные буквенно-цифровые символы или '.'
• начинаться с буквенно-цифрового символа
• заканчивается буквенно-цифровым символом

Имена сегментов пути

Определённые имена типов ресурсов должны закодированы для использования в качестве сегмента пути. Проще говоря, имя не может быть "." или "..", а также не может содержать "/" или "%".

Пример файла манифеста пода nginx-demo.

apiVersion: v1
kind: Pod
metadata:
  name: nginx-demo
spec:
  containers:
  - name: nginx
    image: nginx:1.14.2
    ports:
    - containerPort: 80

Заметка: У отдельных типов ресурсов есть дополнительные ограничения именования.

Уникальные идентификаторы

Уникальная строка, сгенерированная самим Kubernetes, для идентификации объектов.

У каждого объекта, созданного в течение всего периода работы кластера Kubernetes, есть собственный уникальный идентификатор (UID). Он предназначен для выяснения различий между событиями похожих сущностей.

Уникальные идентификатор (UID) в Kubernetes — это универсальные уникальные идентификаторы (известные также как Universally Unique IDentifier, сокращенно UUID). Эти идентификаторы стандартизированы под названием ISO/IEC 9834-8, а также как ITU-T X.667.

Что дальше

• Узнать подробнее про метки в Kubernetes.
• Посмотреть архитектуру идентификаторов и имён Kubernetes.

3.1.4.4 - Пространства имён

Kubernetes поддерживает несколько виртуальных кластеров в одном физическом кластере. Такие виртуальные кластеры называются пространствами имён.

Причины использования нескольких пространств имён

Пространства имён применяются в окружениях с многочисленными пользователями, распределенными по нескольким командам или проектам. Пространства имён не нужно создавать, если есть кластеры с небольшим количеством пользователей (например, десяток пользователей). Пространства имён имеет смысл использовать, когда необходима такая функциональность.

Пространства имён определяют область имён. Имена ресурсов должны быть уникальными в пределах одного и того же пространства имён. Пространства имён не могут быть вложенными, а каждый ресурс Kubernetes может находиться только в одном пространстве имён.

Пространства имён — это способ разделения ресурсов кластера между несколькими пользователями (с помощью квоты ресурсов).

По умолчанию в будущих версиях Kubernetes объекты в одном и том же пространстве имён будут иметь одинаковую политику контроля доступа.

Не нужно использовать пространства имён только для разделения слегка отличающихся ресурсов, например, в случае разных версий одного и того же приложения. Используйте метки, чтобы различать ресурсы в рамках одного пространства имён.

Использование пространств имён

Создание и удаление пространств имён описаны в руководстве администратора по пространствам имён.

Просмотр пространств имён

Используйте следующую команду, чтобы вывести список существующих пространств имён в кластере:

kubectl get namespace

NAME          STATUS    AGE
default       Active    1d
kube-system   Active    1d
kube-public   Active    1d

По умолчанию в Kubernetes определены три пространства имён:

• default — пространство имён по умолчанию для объектов без какого-либо другого пространства имён.
• kube-system — пространство имён для объектов, созданных Kubernetes
• kube-public — создаваемое автоматически пространство имён, которое доступно для чтения всем пользователям (включая также неаутентифицированных пользователей). Как правило, это пространство имён используется кластером, если некоторые ресурсы должны быть общедоступными для всего кластера. Главная особенность этого пространства имён — оно всего лишь соглашение, а не требование.

Определение пространства имён для отдельных команд

Используйте флаг --namespace, чтобы определить пространство имён только для текущего запроса.

Примеры:

kubectl run nginx --image=nginx --namespace=<insert-namespace-name-here>
kubectl get pods --namespace=<insert-namespace-name-here>

Определение пространства имён для всех команд

Можно определить пространство имён, которое должно использоваться для всех выполняемых команд kubectl в текущем контексте.

kubectl config set-context --current --namespace=<insert-namespace-name-here>
# Проверка
kubectl config view --minify | grep namespace:

Пространства имён и DNS

При создании сервиса создаётся соответствующая ему DNS-запись. Эта запись вида <service-name>.<namespace-name>.svc.cluster.local означает, что если контейнер использует только <service-name>, то он будет локальным сервисом в пространстве имён. Это позволит применять одну и ту же конфигурацию в нескольких пространствах имен (например, development, staging и production). Если нужно обращаться к другим пространствам имён, то нужно использовать полностью определенное имя домена (FQDN).

Объекты без пространства имён

Большинство ресурсов Kubernetes (например, поды, сервисы, контроллеры репликации и другие) расположены в определённых пространствах имён. При этом сами ресурсы пространства имён не находятся ни в других пространствах имён. А такие низкоуровневые ресурсы, как узлы и persistentVolumes, не принадлежат ни одному пространству имён.

Чтобы посмотреть, какие ресурсы Kubernetes находятся в пространстве имён, а какие — нет, используйте следующие команды:

# Ресурсы в пространстве имён
kubectl api-resources --namespaced=true

# Ресурсы, не принадлежавшие ни одному пространству имён
kubectl api-resources --namespaced=false

Что дальше

• Узнать подробнее про создание нового пространства имён.
• Узнать подробнее про удаление пространства имён.

3.1.4.5 - Метки и селекторы

Метки — это пары ключ-значение, которые добавляются к объектам, как поды. Метки предназначены для идентификации атрибутов объектов, которые имеют значимость и важны для пользователей, но при этом не относятся напрямую к основной системе. Метки можно использовать для группировки и выбора подмножеств объектов. Метки могут быть добавлены к объектам во время создания и изменены в любое время после этого. Каждый объект может иметь набор меток в виде пары ключ-значение. Каждый ключ должен быть уникальным в рамках одного и того же объекта.

"metadata": {
  "labels": {
    "key1" : "value1",
    "key2" : "value2"
  }
}

Метки используются при получении и отслеживании объектов и в веб-панелях и CLI-инструментах. Любая неидентифицирующая информация должна быть записана в аннотации.

Причины использования

Метки позволяют пользователям гибко сопоставить их организационные структуры с системными объектами, не требуя от клиентов хранить эти соответствия.

Развертывания сервисов и процессы пакетной обработки часто являются многомерными сущностями (например, множество разделов или развертываний, несколько групп выпусков, несколько уровней приложения, несколько микросервисов на каждый уровень приложения). Для управления часто требуются сквозные операции, которые нарушают инкапсуляцию строго иерархических представлений, особенно жестких иерархий, определяемых инфраструктурой, а не пользователями.

Примеры меток:

• "release" : "stable", "release" : "canary"
• "environment" : "dev", "environment" : "qa", "environment" : "production"
• "tier" : "frontend", "tier" : "backend", "tier" : "cache"
• "partition" : "customerA", "partition" : "customerB"
• "track" : "daily", "track" : "weekly"

Это всего лишь примеры часто используемых меток; конечно, вы можете использовать свои собственные. Помните о том, что ключ метки должна быть уникальной в пределах одного объекта.

Синтаксис и набор символов

Метки представляют собой пары ключ-значение. Разрешенные ключи метки имеют два сегмента, разделённые слешем (/): префикс (необязательно) и имя. Сегмент имени обязателен и должен содержать не более 63 символов, среди которых могут быть буквенно-цифровые символы ([a-z0-9A-Z]), а также дефисы (-), знаки подчеркивания (_), точки (.). Префикс не обязателен, но он быть поддоменом DNS: набор меток DNS, разделенных точками (.), общей длиной не более 253 символов, за которыми следует слеш (/).

Если префикс не указан, ключ метки считается закрытым для пользователя. Компоненты автоматизированной системы (например, kube-scheduler, kube-controller-manager, kube-apiserver, kubectl или другие сторонние), которые добавляют метки к объектам пользователя, должны указывать префикс.

Префиксы kubernetes.io/ и k8s.io/ зарезервированы для использования основными компонентами Kubernetes.

Например, ниже представлен конфигурационный файл объекта Pod с двумя метками environment: production и app: nginx:

apiVersion: v1
kind: Pod
metadata:
  name: label-demo
  labels:
    environment: production
    app: nginx
spec:
  containers:
  - name: nginx
    image: nginx:1.14.2
    ports:
    - containerPort: 80

Селекторы меток

В отличие от имен и идентификаторов, метки не гарантируют уникальность. Поэтому мы предполагаем, что многие объекты будут иметь одинаковые метки.

С помощью селектора меток клиент/пользователь может идентифицировать набор объектов. Селектор меток — основное средство группировки в Kubernetes.

В настоящее время API поддерживает два типа селекторов: на равенстве и на наборе. Селектор меток может состоять из нескольких условий, разделенных запятыми. В таком случае все условия должны быть выполнены, поэтому запятая-разделитель работает как логический оператор И (&&).

Работа пустых или неопределённых селекторов зависит от контекста. Типы API, которые использует селекторы, должны задокументировать это поведение.

Заметка: Для некоторых API-типов, например, ReplicaSets, селекторы меток двух экземпляров не должны дублироваться в пространстве имен, в противном случае контроллер может рассматривать их как конфликтующие инструкции и не сможет определить количество реплик.

Внимание: Как для условий, основанных на равенстве, так и для условий на основе набора, не существует логического оператора ИЛИ (||). Убедитесь, что синтаксис фильтрации правильно составлен.

Условие равенства

Условия равенства или неравенства позволяют отфильтровать объекты по ключам и значениям меток. Сопоставляемые объекты должны удовлетворять всем указанным условиям меток, хотя при этом у объектов также могут быть заданы другие метки. Доступны три оператора: =,==,!=. Первые два означают равенство (и являются всего лишь синонимами), а последний оператор определяет неравенство. Например:

environment = production
tier != frontend

Первый пример выбирает все ресурсы с ключом environment, у которого значение указано production. Последний получает все ресурсы с ключом tier без значения frontend, а также все ресурсы, в которых нет метки с ключом tier. Используя оператор запятой можно совместить показанные два условия в одно, запросив ресурсы, в которых есть значение метки production и исключить frontend: environment=production,tier!=frontend.

С помощью условия равенства в объектах Pod можно указать, какие нужно выбрать ресурсы. Например, в примере ниже объект Pod выбирает узлы с меткой "accelerator=nvidia-tesla-p100".

apiVersion: v1
kind: Pod
metadata:
  name: cuda-test
spec:
  containers:
    - name: cuda-test
      image: "k8s.gcr.io/cuda-vector-add:v0.1"
      resources:
        limits:
          nvidia.com/gpu: 1
  nodeSelector:
    accelerator: nvidia-tesla-p100

Условие набора

Условие меток на основе набора фильтрует ключи в соответствии с набором значений. Поддерживаются три вида операторов: in, notin и exists (только идентификатор ключа). Например:

environment in (production, qa)
tier notin (frontend, backend)
partition
!partition

В первом примере выбираются все ресурсы с ключом environment и значением production или qa. Во втором примере выбираются все ресурсы с ключом tier и любыми значениями, кроме frontend и backend, а также все ресурсы без меток с ключом tier. Третий пример выбирает все ресурсы, включая метку с ключом partition (с любым значением). В четвертом примере выбираются все ресурсы без метки с ключом partition (с любым значением). Как и логический оператор И работает разделитель в виде запятой. Таким образом, фильтрация ресурсов по ключу partition (вне зависимости от значения) и ключу environment с любым значением, кроме qa, можно получить с помощью следующего выражения: partition,environment notin (qa). Селектор меток на основе набора — основная форма равенства, поскольку environment=production то же самое, что и environment in (production); аналогично, оператор != соответствует notin.

Условия набора могут использоваться одновременно с условия равенства. Например, так: partition in (customerA, customerB),environment!=qa.

API

Фильтрация LIST и WATCH

Операции LIST и WATCH могут использовать параметр запроса, чтобы указать селекторы меток фильтрации наборов объектов. Есть поддержка обоих условий (строка запроса URL ниже показывается в исходном виде):

• Условия на основе равенства: ?labelSelector=environment%3Dproduction,tier%3Dfrontend
• Условия на основе набора: ?labelSelector=environment+in+%28production%2Cqa%29%2Ctier+in+%28frontend%29

Указанные выше формы селектора меток можно использовать для просмотра или отслеживания ресурсов через REST-клиент. Например, apiserver с kubectl, который использует условие равенства:

kubectl get pods -l environment=production,tier=frontend

Либо используя условия на основе набора:

kubectl get pods -l 'environment in (production),tier in (frontend)'

Как уже показывалось, условия набора дают больше возможностей. Например, в них можно использовать подобие оператора И:

kubectl get pods -l 'environment in (production, qa)'

Либо можно воспользоваться исключающим сопоставлением с помощью оператора exists:

kubectl get pods -l 'environment,environment notin (frontend)'

Установка ссылок в API-объекты

Некоторые объекты Kubernetes, такие как services и replicationcontrollers, также используют селекторы меток для ссылки на наборы из других ресурсов, например, подов.

Service и ReplicationController

Набор подов, на которые указывает service, определяется через селектор меток. Аналогичным образом, количество подов, которыми должен управлять replicationcontroller, также формируются с использованием селектора меток.

Селекторы меток для обоих объектов записываются в словарях файлов формата json и yaml, при этом поддерживаются только селекторы с условием равенства:

"selector": {
    "component" : "redis",
}

Или:

selector:
    component: redis

Этот селектор (как в формате json, так и в yaml) эквивалентен component=redis или component in (redis).

Ресурсы, поддерживающие условия набора

Новые ресурсы, такие как Job, Deployment, ReplicaSet и DaemonSet, также поддерживают условия набора.

selector:
  matchLabels:
    component: redis
  matchExpressions:
    - {key: tier, operator: In, values: [cache]}
    - {key: environment, operator: NotIn, values: [dev]}

matchLabels — словарь пар {key,value}. Каждая пара {key,value} в словаре matchLabels эквивалентна элементу matchExpressions, где поле key — "key", поле operator — "In", а массив values содержит только "value". matchExpressions представляет собой список условий селектора пода. В качестве операторов могут быть In, NotIn, Exists и DoesNotExist. В случае использования In и NotIn должны заданы непустые значения. Все условия, как для matchLabels, так и для matchExpressions, объединяются с помощью логического И, поэтому при выборке объектов все они должны быть выполнены.

Выбор наборов узлов

Один из вариантов использования меток — возможность выбора набора узлов, в которых может быть развернут под. Смотрите документацию про выбор узлов, чтобы получить дополнительную информацию.

3.1.4.6 - Аннотации

Аннотации Kubernetes можно использовать для добавления собственных метаданных к объектам. Такие клиенты, как инструменты и библиотеки, могут получить эти метаданные.

Добавление метаданных к объектам

Вы можете использовать метки или аннотации для добавления метаданных к объектам Kubernetes. Метки можно использовать для выбора объектов и для поиска коллекций объектов, которые соответствуют определенным условиям. В отличие от них аннотации не используются для идентификации и выбора объектов. Метаданные в аннотации могут быть маленькими или большими, структурированными или неструктурированными, кроме этого они включать символы, которые не разрешены в метках.

Аннотации, как и метки, являются коллекциями с наборами пар ключ-значение:

"metadata": {
  "annotations": {
    "key1" : "value1",
    "key2" : "value2"
  }
}

Некоторые примеры информации, которая может быть в аннотациях:

• Поля, управляемые декларативным уровнем конфигурации. Добавление этих полей в виде аннотаций позволяет отличать их от значений по умолчанию, установленных клиентами или серверами, а также от автоматически сгенерированных полей и полей, заданных системами автоматического масштабирования.

• Информация о сборке, выпуске или образе, например, метка времени, идентификаторы выпуска, ветка git, номера PR, хеши образов и адрес реестра.

• Ссылки на репозитории логирования, мониторинга, аналитики или аудита.

• Информация о клиентской библиотеке или инструменте, которая может использоваться при отладке (например, имя, версия и информация о сборке).

• Информация об источнике пользователя или инструмента/системы, например, URL-адреса связанных объектов из других компонентов экосистемы.

• Небольшие метаданные развертывания (например, конфигурация или контрольные точки).

• Номера телефонов или пейджеров ответственных лиц или записи в справочнике, в которых можно найти нужную информацию, например, сайт группы.

• Инструкции от конечных пользователей по исправлению работы или использования нестандартной функциональности.

Вместо использования аннотаций, вы можете сохранить такого рода информацию во внешней базе данных или директории, хотя это усложнило бы создание общих клиентских библиотек и инструментов развертывания, управления, самодиагностики и т.д.

Синтаксис и набор символов

Аннотации представляют собой пары ключ-значение. Разрешенные ключи аннотации имеют два сегмента, разделённые слешем (/): префикс (необязательно) и имя. Сегмент имени обязателен и должен содержать не более 63 символов, среди которых могут быть буквенно-цифровые символы([a-z0-9A-Z]), а также дефисы (-), знаки подчеркивания (_), точки (.). Префикс не обязателен, но он быть поддоменом DNS: набор меток DNS, разделенных точками (.), общей длиной не более 253 символов, за которыми следует слеш (/).

Если префикс не указан, ключ аннотации считается закрытым для пользователя. Компоненты автоматизированной системы (например, kube-scheduler, kube-controller-manager, kube-apiserver, kubectl или другие сторонние), которые добавляют аннотации к объектам пользователя, должны указывать префикс.

Префиксы kubernetes.io/ и k8s.io/ зарезервированы для использования основными компонентами Kubernetes.

Например, ниже представлен конфигурационный файл объекта Pod с аннотацией imageregistry: https://hub.docker.com/:

apiVersion: v1
kind: Pod
metadata:
  name: annotations-demo
  annotations:
    imageregistry: "https://hub.docker.com/"
spec:
  containers:
  - name: nginx
    image: nginx:1.14.2
    ports:
    - containerPort: 80

Что дальше

Узнать подробнее про метки и селекторы.

3.1.4.7 - Селекторы полей

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

• metadata.name=my-service
• metadata.namespace!=default
• status.phase=Pending

Следующая команда kubectl выбирает все Pod-объекты, в которых значение поля status.phase равно Running:

kubectl get pods --field-selector status.phase=Running

Заметка:

По сути, селекторы полей являются фильтрами ресурсов. По умолчанию нет установленных селекторов/фильтров, поэтому выбираются ресурсы всех типов. Это означает, что два запроса kubectl ниже одинаковы:

kubectl get pods
kubectl get pods --field-selector ""

Поддерживаемые поля

Доступные селекторы полей зависят от типа ресурса Kubernetes. У всех типов ресурсов есть поля metadata.name и metadata.namespace. При использовании несуществующего селекторов полей приведёт к возникновению ошибки. Например:

kubectl get ingress --field-selector foo.bar=baz

Error from server (BadRequest): Unable to find "ingresses" that match label selector "", field selector "foo.bar=baz": "foo.bar" is not a known field selector: only "metadata.name", "metadata.namespace"

Поддерживаемые операторы

Можно использовать операторы =, == и != в селекторах полей (= и == — синонимы). Например, следующая команда kubectl выбирает все сервисы Kubernetes, не принадлежавшие пространству имен default:

kubectl get services  --all-namespaces --field-selector metadata.namespace!=default

Составные селекторы

Аналогично метки и другим селекторам, несколько селекторы полей могут быть объединены через запятую. Приведенная ниже команда kubectl выбирает все Pod-объекты, у которых значение поле status.phase, отличное от Running, а поле spec.restartPolicy имеет значение Always:

kubectl get pods --field-selector=status.phase!=Running,spec.restartPolicy=Always

Множественные типы ресурсов

Можно использовать селекторы полей с несколькими типами ресурсов одновременно. Команда kubectl выбирает все объекты StatefulSet и Services, не включенные в пространство имен default:

kubectl get statefulsets,services --all-namespaces --field-selector metadata.namespace!=default

3.1.4.8 - Рекомендуемые метки

Вы можете визуализировать и управлять объектами Kubernetes не только с помощью kubectl и панели управления. С помощью единого набора меток можно единообразно описывать объекты, что позволяет инструментам согласованно работать между собой.

В дополнение к существующим инструментам, рекомендуемый набор меток описывают приложения в том виде, в котором они могут быть получены.

Метаданные сосредоточены на понятии приложение. Kubernetes — это не платформа как услуга (PaaS), поэтому не закрепляет формальное понятие приложения. Вместо этого приложения являются неформальными и описываются через метаданные. Определение приложения довольно расплывчатое.

Заметка: Это рекомендуемые для использования метки. Они облегчают процесс управления приложениями, но при этом не являются обязательными для основных инструментов.

Общие метки и аннотации используют один и тот же префикс: app.kubernetes.io. Метки без префикса являются приватными для пользователей. Совместно используемый префикс гарантирует, что общие метки не будут влиять на пользовательские метки.

Метки

Чтобы извлечь максимум пользы от использования таких меток, они должны добавляться к каждому ресурсному объекту.

Для демонстрации этих меток, рассмотрим следующий объект StatefulSet:

apiVersion: apps/v1
kind: StatefulSet
metadata:
  labels:
    app.kubernetes.io/name: mysql
    app.kubernetes.io/instance: wordpress-abcxzy
    app.kubernetes.io/version: "5.7.21"
    app.kubernetes.io/component: database
    app.kubernetes.io/part-of: wordpress
    app.kubernetes.io/managed-by: helm

Приложения и экземпляры приложений

Одно и то же приложение может быть установлено несколько раз в кластер Kubernetes, в ряде случаев — в одинаковое пространство имен. Например, WordPress может быть установлен более одного раза, тогда каждый из сайтов будет иметь собственный установленный экземпляр WordPress.

Имя приложения и имя экземпляра хранятся по отдельности. Например, WordPress имеет ключ app.kubernetes.io/name со значением wordpress, при этом у него есть имя экземпляра, представленное ключом app.kubernetes.io/instance со значением wordpress-abcxzy. Такой механизм позволяет идентифицировать как приложение, так и экземпляры приложения. У каждого экземпляра приложения должно быть уникальное имя.

Примеры

Следующие примеры показывают разные способы использования общих меток, поэтому они различаются по степени сложности.

Простой сервис без состояния

Допустим, у нас есть простой сервис без состояния, развернутый с помощью объектов Deployment и Service. Следующие два фрагмента конфигурации показывают, как можно использовать метки в самом простом варианте.

Объект Deployment используется для наблюдения за подами, на которых запущено приложение.

apiVersion: apps/v1
kind: Deployment
metadata:
  labels:
    app.kubernetes.io/name: myservice
    app.kubernetes.io/instance: myservice-abcxzy
...

Объект Service используется для открытия доступа к приложению.

apiVersion: v1
kind: Service
metadata:
  labels:
    app.kubernetes.io/name: myservice
    app.kubernetes.io/instance: myservice-abcxzy
...

Веб-приложение с базой данных

Рассмотрим случай немного посложнее: веб-приложение (WordPress), которое использует базу данных (MySQL), установленное с помощью Helm. В следующих фрагментов конфигурации объектов отображена отправная точка развертывания такого приложения.

Следующий объект Deployment используется для WordPress:

apiVersion: apps/v1
kind: Deployment
metadata:
  labels:
    app.kubernetes.io/name: wordpress
    app.kubernetes.io/instance: wordpress-abcxzy
    app.kubernetes.io/version: "4.9.4"
    app.kubernetes.io/managed-by: helm
    app.kubernetes.io/component: server
    app.kubernetes.io/part-of: wordpress
...

Объект Service используется для открытия доступа к WordPress:

apiVersion: v1
kind: Service
metadata:
  labels:
    app.kubernetes.io/name: wordpress
    app.kubernetes.io/instance: wordpress-abcxzy
    app.kubernetes.io/version: "4.9.4"
    app.kubernetes.io/managed-by: helm
    app.kubernetes.io/component: server
    app.kubernetes.io/part-of: wordpress
...

MySQL открывается в виде StatefulSet с метаданными как для самого приложения, так и основного (родительского) приложения, к которому принадлежит СУБД:

apiVersion: apps/v1
kind: StatefulSet
metadata:
  labels:
    app.kubernetes.io/name: mysql
    app.kubernetes.io/instance: mysql-abcxzy
    app.kubernetes.io/version: "5.7.21"
    app.kubernetes.io/managed-by: helm
    app.kubernetes.io/component: database
    app.kubernetes.io/part-of: wordpress
...

Объект Service предоставляет MySQL в составе WordPress:

apiVersion: v1
kind: Service
metadata:
  labels:
    app.kubernetes.io/name: mysql
    app.kubernetes.io/instance: mysql-abcxzy
    app.kubernetes.io/version: "5.7.21"
    app.kubernetes.io/managed-by: helm
    app.kubernetes.io/component: database
    app.kubernetes.io/part-of: wordpress
...

Вы заметите, что StatefulSet и Service MySQL содержат больше информации о MySQL и WordPress.

3.2 - Кластерная Архитектура

3.2.1 - Узлы

Kubernetes запускает ваши приложения, помещая контейнеры в Поды для запуска на Узлах (Nodes). В зависимости от кластера, узел может быть виртуальной или физической машиной. Каждый узел содержит сервисы, необходимые для запуска Подов, управляемых плоскостью управления.

Обычно у вас есть несколько узлов в кластере; однако в среде обучения или среде с ограниченными ресурсами у вас может быть только один.

Компоненты на узле включают kubelet, среду выполнения контейнера и kube-proxy.

Управление

Существует два основных способа добавления Узлов в API сервер:

1. Kubelet на узле саморегистрируется в плоскости управления
2. Вы или другой пользователь вручную добавляете объект Узла

После того, как вы создадите объект Узла или kubelet на узле самозарегистируется, плоскость управления проверяет, является ли новый объект Узла валидным (правильным). Например, если вы попробуете создать Узел при помощи следующего JSON манифеста:

{
  "kind": "Node",
  "apiVersion": "v1",
  "metadata": {
    "name": "10.240.79.157",
    "labels": {
      "name": "my-first-k8s-node"
    }
  }
}

Kubernetes создает внутри себя объект Узла (представление). Kubernetes проверяет, что kubelet зарегистрировался на API сервере, который совпадает с значением поля metadata.name Узла. Если узел здоров (если все необходимые сервисы запущены), он имеет право на запуск Пода. В противном случае, этот узел игнорируется для любой активности кластера до тех пор, пока он не станет здоровым.

Заметка:

Kubernetes сохраняет объект для невалидного Узла и продолжает проверять, становится ли он здоровым.

Вы или контроллер должны явно удалить объект Узла, чтобы остановить проверку доступности узла.

Имя объекта Узла дожно быть валидным именем поддомена DNS.

Саморегистрация Узлов

Когда kubelet флаг --register-node имеет значение true (по умолчанию), то kubelet будет пытаться зарегистрировать себя на API сервере. Это наиболее предпочтительная модель, используемая большиством дистрибутивов.

Для саморегистрации kubelet запускается со следующими опциями:

• --kubeconfig - Путь к учетным данным для аутентификации на API сервере.

• --cloud-provider - Как общаться с облачным провайдером, чтобы прочитать метаданные о себе.

• --register-node - Автоматически зарегистрироваться на API сервере.

• --register-with-taints - Зарегистрировать узел с приведенным списком ограничений (taints) (разделенных запятыми <key>=<value>:<effect>).

  Ничего не делает, если register-node - false.

• --node-ip - IP-адрес узла.

• --node-labels - Метки для добавления при регистрации узла в кластере (смотрите ограничения для меток, установленные плагином согласования (admission plugin) NodeRestriction).

• --node-status-update-frequency - Указывает, как часто kubelet отправляет статус узла мастеру.

Когда режим авторизации Узла и плагин согласования NodeRestriction включены, kubelet'ы имеют право только создавать/изменять свой собственный ресурс Узла.

Ручное администрирование узла

Вы можете создавать и изменять объекты узла используя kubectl.

Когда вы хотите создать объекты Узла вручную, установите kubelet флаг --register-node=false.

Вы можете изменять объекты Узла независимо от настройки --register-node. Например, вы можете установить метки на существующем Узле или пометить его неназначаемым.

Вы можете использовать метки на Узлах в сочетании с селекторами узла на Подах для управления планированием. Например, вы можете ограничить Под иметь право на запуск только на группе доступных узлов.

Маркировка узла как неназначаемого предотвращает размещение планировщиком новых подов на этом Узле, но не влияет на существующие Поды на Узле. Это полезно в качестве подготовительного шага перед перезагрузкой узла или другим обслуживанием.

Чтобы отметить Узел неназначемым, выполните:

kubectl cordon $NODENAME

Заметка: Поды, являющиеся частью DaemonSet допускают запуск на неназначаемом Узле. DaemonSets обычно обеспечивает локальные сервисы узла, которые должны запускаться на Узле, даже если узел вытесняется для запуска приложений.

Статус Узла

Статус узла содержит следующие данные:

• Адреса (Addresses)
• Условия (Conditions)
• Емкость и Выделяемые ресурсы (Capacity and Allocatable)
• Информация (Info)

Вы можете использовать kubectl для просмотра статуса Узла и других деталей:

kubectl describe node <insert-node-name-here>

Каждая секция из вывода команды описана ниже.

Адреса (Addresses)

Использование этих полей варьируется в зависимости от вашего облачного провайдера или конфигурации физических серверов (bare metal).

• HostName: Имя хоста, сообщаемое ядром узла. Может быть переопределено через kubelet --hostname-override параметр.
• ExternalIP: Обычно, IP адрес узла, который является внешне маршрутизируемым (доступен за пределами кластера).
• InternalIP: Обычно, IP адрес узла, который маршрутизируется только внутри кластера.

Условия (Conditions)

Поле conditions описывает статус всех Running узлов. Примеры условий включают в себя:

Заметка: Если вы используете инструменты командной строки для вывода сведений об блокированном узле, то Условие включает SchedulingDisabled. SchedulingDisabled не является Условием в Kubernetes API; вместо этого блокированные узлы помечены как Неназначемые в их спецификации.

Состояние узла представлено в виде JSON объекта. Например, следующая структура описывает здоровый узел:

"conditions": [
  {
    "type": "Ready",
    "status": "True",
    "reason": "KubeletReady",
    "message": "kubelet is posting ready status",
    "lastHeartbeatTime": "2019-06-05T18:38:35Z",
    "lastTransitionTime": "2019-06-05T11:41:27Z"
  }
]

Если значение параметра Status для условия Ready остается Unknown или False дольше чем период pod-eviction-timeout(аргумент, переданный в kube-controller-manager), то все Поды на узле планируются к удалению контроллером узла. По умолчанию таймаут выселения пять минут. В некоторых случаях, когда узел недоступен, API сервер не может связаться с kubelet на узле. Решение об удалении подов не может быть передано в kubelet до тех пор, пока связь с API сервером не будет восстановлена. В то же время поды, которые запланированы к удалению, могут продолжать работать на отделенном узле.

Контроллер узла не будет принудительно удалять поды до тех пор, пока не будет подтверждено, что они перестали работать в кластере. Вы можете видеть, что поды, которые могут работать на недоступном узле, находятся в состоянии Terminating или Unknown. В тех случаях, когда Kubernetes не может сделать вывод из основной инфраструктуры о том, что узел окончательно покинул кластер, администратору кластера может потребоваться удалить объект узла вручную. Удаление объекта узла из Kubernetes приводит к удалению всех объектов Подов, запущенных на узле, с API сервера и освобождает их имена.

Контроллер жизненного цикла узла автоматически создает ограничения (taints), которые представляют собой условия. Планировщик учитывает ограничения Узла при назначении Пода на Узел. Поды так же могут иметь допуски (tolerations), что позволяет им сопротивляться ограничениям Узла.

Смотрите раздел Ограничить Узлы по Условию для дополнительной информации.

Емкость и Выделяемые ресурсы (Capacity and Allocatable)

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

Поля в блоке capasity указывают общее количество ресурсов, которые есть на Узле. Блок allocatable указывает количество ресурсовна Узле, которые доступны для использования обычными Подами.

Вы можете прочитать больше о емкости и выделяемых ресурсах, изучая, как зарезервировать вычислительные ресурсы на Узле.

Информация (Info)

Описывает общую информацию об узле, такую как версия ядра, версия Kubernetes (версии kubelet и kube-proxy), версия Docker (если используется) и название ОС. Эта информация соберается Kubelet'ом на узле.

Контроллер узла

Контроллер узла является компонентом плоскости управления Kubernetes, который управляет различными аспектами узлов.

Контроллер узла играет различные роли в жизни узла. Первая - назначение CIDR-блока узлу при его регистрации (если включено назначение CIDR).

Вторая - поддержание в актуальном состоянии внутреннего списка узлов контроллера узла согласно списку доступных машин облачного провайдера. При работе в облачной среде всякий раз, когда узел неисправен, контроллер узла запрашивает облачного провайдера, доступна ли виртуальная машина для этого узла. Если нет, то контроллер узла удаляет узел из своего списка узлов.

Третья - это мониторинг работоспособности узлов. Контроллер узла отвечает за обновление условия NodeReady для NodeStatus на ConditionUnknown, когда узел становится недоступным (т.е. контроллер узла по какой-то причине перестает получать сердцебиения (heartbeats) от узла, например, из-за того, что узел упал), и затем позже выселяет все поды с узла (используя мягкое (graceful) завершение) если узел продолжает быть недоступным. (По умолчанию таймауты составляют 40 секунд, чтобы начать сообщать ConditionUnknown, и 5 минут после, чтобы начать выселять поды.) Контроллер узла проверяет состояние каждого узла каждые --node-monitor-period секунд.

Сердцебиения

Сердцебиения, посылаемые узлами Kubernetes, помогают определить доступность узла.

Существует две формы сердцебиений: обновление NodeStatus и Lease объект. Каждый узел имеет связанный с ним Lease объект в kube-node-lease namespace. Lease - это легковестный ресурс, который улучшает производительность сердцебиений узла при масштабировании кластера.

Kubelet отвечает за создание и обновление NodeStatus и Lease объекта.

• Kubelet обновляет NodeStatus либо когда происходит изменение статуса, либо если в течение настронного интервала обновления не было. По умолчанию интервал для обновлений NodeStatus составляет 5 минут (намного больше, чем 40-секундный стандартный таймаут для недоступных узлов).
• Kubelet созадет и затем обновляет свой Lease объект каждый 10 секунд (интервал обновления по умолчанию). Lease обновления происходят независимо от NodeStatus обновлений. Если обновление Lease завершается неудачно, kubelet повторяет попытку с экспоненциальным откатом, начинающимся с 200 миллисекунд и ограниченным 7 секундами.

Надежность

В большинстве случаев контроллер узла ограничивает скорость выселения до --node-eviction-rate (по умолчанию 0,1) в секунду, что означает, что он не выселяет поды с узлов быстрее чем c 1 узела в 10 секунд.

Поведение выселения узла изменяется, когда узел в текущей зоне доступности становится нездоровым. Контроллер узла проверяет, какой процент узлов в зоне нездоров (NodeReady условие в значении ConditionUnknown или ConditiononFalse) в одно и то же время. Если доля нездоровых узлов не меньше --unhealthy-zone-threshold (по умолчанию 0.55), то скорость выселения уменьшается: если кластер небольшой (т.е. количество узлов меньше или равно --large-cluster-size-threshold - по умолчанию, 50), то выселения прекращаются, в противном случае скорость выселения снижается до --secondary-node-eviction-rate (по умолчанию, 0.01) в секунду. Причина, по которой эти политики реализуются для каждой зоны доступности, заключается в том, что одна зона доступности может стать отделенной от мастера, в то время как другие остаются подключенными. Если ваш кластер не охватывает несколько зон доступности облачного провайдера, то существует только одна зона доступности (весь кластер).

Основная причина разнесения ваших узлов по зонам доступности заключается в том, что приложения могут быть перенесены в здоровые зоны, когда одна из зон полностью становится недоступной. Поэтому, если все узлы в зоне нездоровы, то контроллер узла выселяет поды с нормальной скоростью --node-eviction-rate. Крайний случай - когда все зоны полностью нездоровы (т.е. в кластере нет здоровых узлов). В таком случае контроллер узла предполагает, что существует некоторая проблема с подключением к мастеру, и останавеливает все выселения, пока какое-нибудь подключение не будет восстановлено.

Контроллер узла также отвечает за выселение подов, запущенных на узлах с NoExecute ограничениями, за исключением тех подов, которые сопротивляются этим ограничениям. Контроллер узла так же добавляет ограничения соотвествующие проблемам узла, таким как узел недоступен или не готов. Это означает, что планировщик не будет размещать поды на нездоровых узлах.

Внимание: kubectl cordon помечает узел как 'неназначемый', что имеет побочный эфект от контроллера сервисов, удаляющего узел из любых списков целей LoadBalancer узла, на которые он ранее имел право, эффектино убирая входящий трафик балансировщика нагрузки с блокированного узла(ов).

Емкость узла

Объекты узла отслеживают информацию о емкости ресурсов узла (например, объем доступной памяти и количество CPU). Узлы, которые самостоятельно зарегистировались сообщают о свое емкости во время регистрации. Если вы вручную добавляете узел, то вам нужно задать информацию о емкости узла при его добавлении.

Планировщик Kubernetes гарантирует, что для всех Подов на Узле достаточно ресурсов. Планировщик проверяет, что сумма requests от контейнеров на узле не превышает емкость узла. Эта сумма requests включает все контейнеры, управляемые kubelet, но исключает любые контейнеры, запущенные непосредственно средой выполнения контейнера, а также исключает любые процессы, запущенные вне контроля kubelet.

Заметка: Если вы явно хотите зарезервировать ресурсы для процессов, не связанныз с Подами, смотрите раздел зарезервировать ресурсы для системных демонов.

Топология узла

Если вы включили TopologyManager feature gate, то kubelet может использовать подсказки топологии при принятии решений о выделении ресурсов. Смотрите Контроль Политик Управления Топологией на Узле для дополнительной информации.

Что дальше

• Подробнее прокомпоненты из которых состоит узел.
• Подробнее про Определение API для Узла.
• Подробнее про Узлы of the architecture design document.
• Подробнее про ограничения и допуски.
• Подробнее про автомаштабирование кластера.

4 - Руководства

В данном разделе документации Kubernetes можно найти руководства. В них рассказывается, как достичь определённой цели, а не просто выполнить одну задачу. Большинство уроков состоит из нескольких разделов, каждый из которых включает в себя шаги для последовательного выполнения. Перед тем как приступить к выполнению уроков, может быть полезно ознакомиться со словарем терминов для последующих обращений.

Основы

• Основы Kubernetes - подробное интерактивное руководство, направленное на понимание системы и предлагающее попробовать некоторые основные возможности Kubernetes.

• Масштабируемые микросервисы с Kubernetes (Udacity)

• Введение в Kubernetes (edX)

• Привет, Minikube

Конфигурирование

• Конфигурирование Redis с использованием ConfigMap

Приложения без состояния

• Установка внешнего IP адреса для получения доступа к приложению в кластере

• Пример: развёртывание приложения "Гостевая книга" на PHP с использованием Redis

Приложения с состоянием

• Основы StatefulSet

• Пример: WordPress и MySQL с персистентным хранилищем

• Пример: Развёртывание Cassandra с Stateful Sets

• Запуск ZooKeeper, A CP Distributed System

Кластеры

• AppArmor

Сервисы

• Использование IP

Что дальше

Если вы хотите создать руководство самостоятельно, обратитесь к странице Использование шаблонов страниц, чтобы узнать информацию и посмотреть шаблоны для составления руководств.

4.1 - Привет, Minikube

Это руководство покажет вам, как запустить простое Hello World Node.js приложение на Kubernetes используя Minikube и Katacoda. Katacoda предоставляет бесплатную, встроенную в браузер Kubernetes среду.

Заметка: Вы также можете следовать этому руководству, если вы установили Minikube locally.

Цели

• Разверните hello world приложение в Minikube.
• Запустите приложение.
• Посмотрите логи приложения.

Подготовка к работе

Для этого примера создан образ контейнера, собранный на основе следующих файлов:

minikube/server.js

var http = require('http');

var handleRequest = function(request, response) {
  console.log('Получен запрос на URL: ' + request.url);
  response.writeHead(200);
  response.end('Hello World!');
};
var www = http.createServer(handleRequest);
www.listen(8080);

minikube/Dockerfile

FROM node:6.14.2
EXPOSE 8080
COPY server.js .
CMD [ "node", "server.js" ]

Чтобы получить больше информации по запуску команды docker build, ознакомьтесь с документацией по Docker.

Создание кластера Minikube

1. Нажмите Запуск Терминала

   Launch Terminal

   Заметка: Если у вас локально установлен Minikube, выполните minikube start.

2. Откройте веб-панель Kubernetes в браузере:

   minikube dashboard
   

3. Только для окружения Katacoda: В верхней части панели нажмите знак "плюс", а затем на Select port to view on Host 1 (Выберите порт для отображения на хосте 1).

4. Только для окружения Katacoda: введите 30000, а затем нажмите Display Port (Показать порт).

Создание Deployment

Под Kubernetes - это группа из одного или более контейнеров, связанных друг с другом с целью адмистрирования и организации сети. В данном руководстве под включает в себя один контейнер. Deployment в Kubernetes проверяет здоровье пода и перезагружает контейнер пода в случае его отказа. Deployment-ы являются рекоммендуемым способом организации создания и масштабирования подов.

1. Используйте команду kubectl create для создание деплоймента для управления подом. Под запускает контейнер на основе предоставленного Docker образа.

   kubectl create deployment hello-node --image=k8s.gcr.io/echoserver:1.4
   

2. Посмотреть информацию о Deployment:

   kubectl get deployments
   

   Вывод:

   NAME         DESIRED   CURRENT   UP-TO-DATE   AVAILABLE   AGE
   hello-node   1         1         1            1           1m
   

3. Посмотреть информацию о поде:

   kubectl get pods
   

   Вывод:

   NAME                          READY     STATUS    RESTARTS   AGE
   hello-node-5f76cf6ccf-br9b5   1/1       Running   0          1m
   

4. Посмотреть события кластера:

   kubectl get events
   

5. Посмотреть kubectl конфигурацию:

   kubectl config view
   

   Заметка: Больше информации о командах kubectl можно найти по ссылке обзор kubectl.

Создание сервиса

По-умолчанию под доступен только при обращении по его внутреннему IP адресу внутри кластера Kubernetes. Чтобы сделать контейнер hello-node доступным вне виртульной сети Kubernetes, необходимо представить под как сервис Kubernetes.

1. Сделать под доступным для публичной сети Интернет можно с помощью команды kubectl expose:

   kubectl expose deployment hello-node --type=LoadBalancer --port=8080
   

   Флаг --type=LoadBalancer показывает, что сервис должен быть виден вне кластера.

2. Посмотреть только что созданный сервис:

   kubectl get services
   

   Вывод:

   NAME         TYPE           CLUSTER-IP      EXTERNAL-IP   PORT(S)          AGE
   hello-node   LoadBalancer   10.108.144.78   <pending>     8080:30369/TCP   21s
   kubernetes   ClusterIP      10.96.0.1       <none>        443/TCP          23m
   

   Для облачных провайдеров, поддерживающих балансировщики нагрузки, для доступа к сервису будет предоставлен внешний IP адрес. В Minikube тип LoadBalancer делает сервис доступным при обращении с помощью команды minikube service.

3. Выполните следующую команду:

   minikube service hello-node
   

4. Только для окружения Katacoda: Нажмите на знак "Плюс", затем нажмите Select port to view on Host 1.

5. Только для окружения Katacoda: Введите 30369 (порт указан рядом с 8080 в выводе сервиса), затем нажмите ???.

   Откроется окно браузера, в котором запущено ваше приложение и будет отображено сообщение "Hello World".

Добавление дополнений

В Minikube есть набор встроенных дополнений, которые могут быть включены, выключены и открыты в локальном окружении Kubernetes.

1. Отобразить текущие поддерживаемые дополнения:

   minikube addons list
   

   Вывод:

   addon-manager: enabled
   dashboard: enabled
   default-storageclass: enabled
   efk: disabled
   freshpod: disabled
   gvisor: disabled
   heapster: disabled
   helm-tiller: disabled
   ingress: disabled
   ingress-dns: disabled
   logviewer: disabled
   metrics-server: disabled
   nvidia-driver-installer: disabled
   nvidia-gpu-device-plugin: disabled
   registry: disabled
   registry-creds: disabled
   storage-provisioner: enabled
   storage-provisioner-gluster: disabled
   

2. Включить дополнение, например, metrics-server:

   minikube addons enable metrics-server
   

   Вывод:

   metrics-server was successfully enabled
   

3. Посмотреть Pod и Service, которые вы только что создали:

   kubectl get pod,svc -n kube-system
   

   Вывод:

   NAME                                        READY     STATUS    RESTARTS   AGE
   pod/coredns-5644d7b6d9-mh9ll                1/1       Running   0          34m
   pod/coredns-5644d7b6d9-pqd2t                1/1       Running   0          34m
   pod/metrics-server-67fb648c5                1/1       Running   0          26s
   pod/etcd-minikube                           1/1       Running   0          34m
   pod/influxdb-grafana-b29w8                  2/2       Running   0          26s
   pod/kube-addon-manager-minikube             1/1       Running   0          34m
   pod/kube-apiserver-minikube                 1/1       Running   0          34m
   pod/kube-controller-manager-minikube        1/1       Running   0          34m
   pod/kube-proxy-rnlps                        1/1       Running   0          34m
   pod/kube-scheduler-minikube                 1/1       Running   0          34m
   pod/storage-provisioner                     1/1       Running   0          34m
   
   NAME                           TYPE        CLUSTER-IP      EXTERNAL-IP   PORT(S)             AGE
   service/metrics-server         ClusterIP   10.96.241.45    <none>        80/TCP              26s
   service/kube-dns               ClusterIP   10.96.0.10      <none>        53/UDP,53/TCP       34m
   service/monitoring-grafana     NodePort    10.99.24.54     <none>        80:30002/TCP        26s
   service/monitoring-influxdb    ClusterIP   10.111.169.94   <none>        8083/TCP,8086/TCP   26s
   

4. Отключить metrics-server:

   minikube addons disable metrics-server
   

   Вывод:

   metrics-server was successfully disabled
   

Освобождение ресурсов

Теперь вы можете освободить ресурсы созданного вами кластера:

kubectl delete service hello-node
kubectl delete deployment hello-node

Остановите выполнение виртуальной машины Minikube (опционально):

minikube stop

Удалите виртуальную машину Minikube (опционально):

minikube delete

Что дальше

• Больше об объектах деплоймента.
• Больше о развёртывании приложения.
• Больше об объектах сервиса.

4.2 - Основы Kubernetes

Основы Kubernetes

В данном руководстве вы познакомитесь с основами системы оркестрации кластеров Kubernetes. Каждый модуль содержит краткую справочную информацию по основной функциональности и концепциям Kubernetes, а также включает интерактивные онлайн-уроки. С их помощью вы научитесь самостоятельно управлять простым кластером и контейнеризированными приложениями, которые были в нём развернуты.

Пройдя интерактивные уроки, вы узнаете, как:

• развёртывать контейнеризированное приложение в кластер.
• масштабировать развёртывание.
• обновить контейнеризированное приложение на новую версию ПО.
• отлаживать контейнеризированное приложение.

Все руководства используют сервис Katacoda, поэтому в вашем браузере будет показан виртуальный терминал с работающим Minikube, небольшой локальной средой Kubernetes, которая может работать где угодно. Вам не потребуется устанавливать дополнительное ПО или вообще что-либо настраивать. Каждый интерактивный урок запускается непосредственно в вашем браузере.

Чем может Kubernetes помочь вам?

От современных веб-сервисов пользователи ожидают, что приложения будут доступны 24/7, а разработчики — развёртывать новые версии приложений по нескольку раз в день. Контейнеризация направлена на достижение этой цели, упаковывая ПО и позволяя выпускать и обновлять приложения просто, быстро и без простоев. Kubernetes гарантирует вам, что ваши контейнеризованные приложения будет запущены где угодно и когда угодно, вместе со всеми необходимыми для их работы ресурсами и инструментами. Kubernetes — это готовая к промышленному использованию платформа с открытым исходным кодом, разработанная исходя из накопленного опыта Google по оркестровке контейнеров и лучшими идеями от сообщества.

Учебные модули по основам Kubernetes

1. Создание кластера Kubernetes

2. Развёртывание приложение

3. Изучение приложения

4. Открытие доступа к приложению

5. Масштабирование приложения

6. Обновление приложение

4.2.1 - Создание кластера

4.2.1.1 - Использование Minikube для создания кластера

4.2.1.2 - Интерактивный урок - Создание кластера

4.2.2 - Развёртывание приложения

4.2.2.1 - Использование kubectl для развёртывания приложения

4.2.2.2 - Интерактивный урок - Развёртывание приложения

4.2.3 - Изучение приложения

4.2.3.1 - Изучение подов и узлов

4.2.3.2 - Интерактивный урок - Изучение приложения

4.2.4 - Открытие доступа к приложению

4.2.4.1 - Создание сервиса для открытия доступа к приложению

4.2.4.2 - Интерактивный урок - Открытие доступа к приложению

4.2.5 - Масштабирование приложения

4.2.5.1 - Запуск нескольких экземпляров приложения

Темы

• Масштабирование приложения с помощью kubectl.

Масштабирование приложения

В предыдущих модулях мы создали развёртывание, а затем открыли к нему публичный доступ через сервис. Развёртывание создало только один под, в котором работает наше приложение. По мере увеличения трафика необходимо будет промасштабировать приложение, чтобы оно могло справиться с возросшим потоком пользователей.

Масштабирование осуществляется за счёт изменения количества реплик в развёртывании.

Краткое содержание:

• Масштабирование развёртывания

Количество экземпляров можно указать прямо при создании развёртывания, используя параметр --replicas команды kubectl run

Обзор масштабирования

Предыдущая картинка Следующая картинка

В случае масштабирования развёртывания создаются новые поды, которые распределяются по узлам с доступными ресурсами. Масштабирование увеличит количество подов в соответствии с указанным требуемым состоянием. Kubernetes также поддерживает автоматическое масштабирование подов (не рассматривается в данном уроке). Кроме этого, возможно масштабирование до нуля, тогда завершается работа всех подов в развертывании.

При запуске нескольких экземпляров приложения нужно правильно распределить трафик между ними. У сервисов есть встроенный балансировщик нагрузки, который распределяет сетевой трафик всех подов в открытом извне развертывания. Сервисы постоянно отслеживают запущенные поды через их конечные точки, чтобы направлять трафик только на доступные поды.

Масштабирование выполняется с помощью изменения количества реплик в развертывании.

Имея несколько работающих экземпляров приложения можно выполнять плавающие обновления (rolling updates) без простоев. С ними мы познакомимся в следующем модуле. А пока перейдём к онлайн-терминалу и промасштабируем наше приложение.

Начать интерактивный урок ›

4.2.5.2 - Интерактивный урок - Масштабирование приложения

4.2.6 - Обновление приложения

4.2.6.1 - Выполнение плавающего обновления

Темы

• Выполнение плавающего обновления с помощью kubectl.

Обновление приложения

Пользователи надеются, что приложения будут работать круглосуточно, а разработчики в свою очередь ожидают развёртывать новые версии приложений по нескольку раз в день. В Kubernetes это возможно благодаря механизму плавающих обновлений (rolling updates). Плавающие обновления позволяет обновить развёртывания без простоев, шаг за шагом заменяя старые поды на новые. Новые поды будут запущены на узлах, имеющих достаточно ресурсов.

В предыдущем модуле мы промасштабировали приложение до нескольких экземпляров. Это необходимо сделать, чтобы иметь возможность обновлять приложение, не влияя на его доступность. По умолчанию максимальное количество подов, которое может быть недоступно во время обновления, и максимальное количество новых подов, которое можно создать, равны 1. Эти две опции могут быть определены в абсолютном (числа) или относительном соотношении (проценты). В Kubernetes обновления версионируются, поэтому любое обновление развёртывания можно откатить до предыдущей (стабильной) версии.

Краткое содержание:

• Обновление приложения

Плавающие обновления последовательно заменяют экземпляры подов на новые, тем самым позволяя обновить развёртывания без простоев

Обзор плавающих обновлений

Предыдущая картинка Следующая картинка

Подобно масштабированию приложения, если развёртывание доступно извне, при обновлении сервис будет балансировать трафик только между доступными подами. Доступный под — это экземпляр, который может быть запущен для пользователей приложения.

С помощью плавающих обновлений можно:

• Переводить приложение из одного окружения в другое (через обновления образа контейнера)
• Откатываться к предыдущим версиям
• Осуществлять непрерывную интеграцию и непрерывную доставку приложений без простоев

Если развёртывание было открыто наружу, в процессе обновления сервис будет балансировать нагрузку трафика только на доступные поды.

В следующем интерактивном уроке мы обновим приложение до новой версии, а потом выполним откат, т.е. вернёмся к предыдущей версии

Начать интерактивный урок ›

4.2.6.2 - Интерактивный урок - Обновление приложения

5 - Ссылки

Этот раздел документации Kubernetes содержит ссылки.

Ссылки API

• Обзор Kubernetes API - Обзор API для Kubernetes.
• Версии Kubernetes API
  • 1.17
  • 1.16
  • 1.15
  • 1.14
  • 1.13
  • 1.12

Клиентские библиотеки API

Для вызова API Kubernetes из языка программирования вы можете использовать клиентские библиотеки. Официально поддерживаемые клиентские библиотеки:

• Клиентская библиотека для Go
• Клиентская библиотека для Python
• Клиентская библиотека для Java
• Клиентская библиотека для JavaScript

Ссылки CLI

• kubectl - Основной инструмент CLI для запуска команд и управления кластерами Kubernetes.
  • JSONPath - Документация по синтаксису использования выражений JSONPath с kubectl.
• kubeadm - Инструмент CLI для легкого разворачивания защищенного кластера Kubernetes.
• kubefed - Инструмент CLI для помощи в администрировании федеративных кластеров.

Ссылки на конфигурации

• kubelet - Основной агент ноды, который работает на каждой ноде. Kubelet принимает набор PodSpecs и гарантирует, что описанные контейнеры работают исправно.
• kube-apiserver - REST API, который проверяет и настраивает данные для объектов API, таких как модули, службы, контроллеры и репликации.
• kube-controller-manager - Демон, который встраивает основные контрольные циклы, поставляемые с Kubernetes.
• kube-proxy - Может выполнять простую пересылку запросов TCP/UDP или циклическую переадресацию TCP/UDP через набор бекендов.
• kube-scheduler - Планировщик, который управляет доступностью, производительностью и хранилищем.
• federation-apiserver - Сервер API для федеративных кластеров.
• federation-controller-manager - Демон, который встраивает основные контрольные циклы, поставляемые с Kubernetes.

Дизайн документация

Архив документации по дизайну для функциональности Kubernetes. Начните с Архитектура Kubernetes и Обзор дизайна Kubernetes.

5.1 - Стандартизированный глоссарий

5.2 - kubectl CLI

5.2.1 - Обзор kubectl

Kubectl — это инструмент командной строки для управления кластерами Kubernetes. kubectl ищет файл config в директории $HOME/.kube. Вы можете указать другие файлы kubeconfig, установив переменную окружения KUBECONFIG или флаг --kubeconfig.

На этой странице рассматривается синтаксис kubectl, описаны командные операции и приведены распространённые примеры. Подробную информацию о каждой команде, включая все поддерживаемые в ней флаги и подкоманды, смотрите в справочной документации kubectl. Инструкции по установке находятся на странице Установка и настройка kubectl.

Синтаксис

Используйте следующий синтаксис для выполнения команд kubectl в терминале:

kubectl [command] [TYPE] [NAME] [flags]

где command, TYPE, NAME и flags:

• command: определяет выполняемую операцию с одним или несколькими ресурсами, например, create, get, describe, delete.

• TYPE: определяет тип ресурса. Типы ресурсов не чувствительны к регистру, кроме этого вы можете использовать единственную, множественную или сокращенную форму. Например, следующие команды выведут одно и то же.

  ```shell
  kubectl get pod pod1
  kubectl get pods pod1
  kubectl get po pod1
  ```
  

• NAME: определяет имя ресурса. Имена чувствительны к регистру. Если имя не указано, то отображаются подробности по всем ресурсам, например, kubectl get pods.

  При выполнении операции с несколькими ресурсами можно выбрать каждый ресурс по типу и имени, либо сделать это в одном или нескольких файлов:

  • Выбор ресурсов по типу и имени:

    • Сгруппировать ресурсы, если все они одного типа: TYPE1 name1 name2 name<#>.
      Пример: kubectl get pod example-pod1 example-pod2

    • Выбор нескольких типов ресурсов по отдельности: TYPE1/name1 TYPE1/name2 TYPE2/name3 TYPE<#>/name<#>.
      Пример: kubectl get pod/example-pod1 replicationcontroller/example-rc1

  • Выбор ресурсов по одному или нескольким файлов: -f file1 -f file2 -f file<#>

    • Используйте YAML вместо JSON, так так YAML удобнее для пользователей, особенно в конфигурационных файлов.
      Пример: kubectl get pod -f ./pod.yaml

• flags: определяет дополнительные флаги. Например, вы можете использовать флаги -s или --server, чтобы указать адрес и порт API-сервера Kubernetes.
  

Внимание: Указанные вами флаги из командной строки переопределят значения по умолчанию и связанные переменные окружения.

Если вам нужна помощь, выполните команду kubectl help.

Операции

В следующей таблице приведены краткие описания и общий синтаксис всех операций kubectl:

Примечание: подробную информацию о командных операциях смотрите в справочную документацию kubectl.

Типы ресурсов

В следующей таблице перечислены все доступные типы ресурсов вместе с сокращенными аббревиатурами.

(Это актуальный вывод команды kubectl api-resources с версии Kubernetes 1.13.3.)

Опции вывода

В следующих разделах рассматривается форматирование и сортировка вывода определенных команд. Дополнительные сведения о том, какие команды поддерживают разные варианты вывода, смотрите в справочной документации kubectl.

Форматирование вывода

Стандартный формат вывода всех команд kubectl представлен в человекочитаемом текстовом формате. Чтобы вывести подробности в определенном формате можно добавить флаги -o или --output к команде kubectl.

Синтаксис

kubectl [command] [TYPE] [NAME] -o <output_format>

В зависимости от операции kubectl поддерживаются следующие форматы вывода:

Пример

В данном примере следующая команда выводит подробную информацию по указанному поду в виде объекта в YAML-формате:

kubectl get pod web-pod-13je7 -o yaml

Примечание: подробную информацию о доступных форматах вывода в определенной команде смотрите в справочной документации kubectl.

Пользовательские столбцы

Для определения пользовательских столбцов и вывода в таблицу только нужных данных, можно использовать опцию custom-columns. Вы можете определить пользовательские столбцы в самой опции, либо сделать это в файле шаблона: -o custom-columns=<spec> или -o custom-columns-file=<filename>.

Примеры

Столбцы указаны в самой команде:

kubectl get pods <pod-name> -o custom-columns=NAME:.metadata.name,RSRC:.metadata.resourceVersion

Столбцы указаны в файле шаблона:

kubectl get pods <pod-name> -o custom-columns-file=template.txt

где файл template.txt содержит следующее:

NAME          RSRC
metadata.name metadata.resourceVersion

Результат выполнения любой из показанной выше команды:

NAME           RSRC
submit-queue   610995

Получение вывода с сервера

kubectl может получать информацию об объектах с сервера. Это означает, что для любого указанного ресурса сервер вернет столбцы и строки по этому ресурсу, которые отобразит клиент. Благодаря тому, что сервер инкапсулирует реализацию вывода, гарантируется единообразный и человекочитаемый вывод на всех клиентах, использующих один и тот же кластер.

Эта функциональность включена по умолчанию, начиная с kubectl 1.11 и выше. Чтобы отключить ее, добавьте флаг --server-print=false в команду kubectl get.

Примеры

Для вывода информации о состоянии пода, используйте следующую команду:

kubectl get pods <pod-name> --server-print=false

Вывод будет выглядеть следующим образом:

NAME       READY     STATUS              RESTARTS   AGE
pod-name   1/1       Running             0          1m

Сортировка списка объектов

Для вывода объектов в виде отсортированного списка в терминал используется флаг --sort-by к команде kubectl. Для сортировки объектов нужно указать любое числовое или строковое поле в флаге --sort-by. Для определения поля используйте выражение jsonpath.

Синтаксис

kubectl [command] [TYPE] [NAME] --sort-by=<jsonpath_exp>

Пример

Чтобы вывести список подов, отсортированных по имени, выполните команду ниже:

kubectl get pods --sort-by=.metadata.name

Примеры: распространенные операции

Посмотрите следующие примеры, чтобы ознакомиться с часто используемыми операциями kubectl:

kubectl apply - Внести изменения или обновить ресурс из файла или потока stdin.

# Создать сервис из определения в example-service.yaml.
kubectl apply -f example-service.yaml

# Создать контроллер репликации из определения в example-controller.yaml.
kubectl apply -f example-controller.yaml

# Создать объекты, которые определены в файлах с расширением .yaml, .yml или .json в директории <directory>.
kubectl apply -f <directory>

kubectl get - Вывести один или несколько ресурсов.

# Вывести все поды в текстовом формате вывода.
kubectl get pods

# Вывести все поды в текстовом формате вывода и включить дополнительную информацию (например, имя узла).
kubectl get pods -o wide

# Вывести контроллер репликации с указанным именем в текстовом формате вывода. Совет: вы можете использовать сокращенный псевдоним 'rc' вместо 'replicationcontroller'.
kubectl get replicationcontroller <rc-name>

# Вывести все контроллеры репликации и сервисы вместе в текстовом формате вывода.
kubectl get rc,services

# Вывести все наборы демонов в текстовом формате вывода.
kubectl get ds

# Вывести все поды, запущенные на узле server01
kubectl get pods --field-selector=spec.nodeName=server01

kubectl describe - Показать подробное состояние одного или нескольких ресурсов, по умолчанию также включаются неинициализированные ресурсы.

# Показать информацию об узле с именем <node-name>.
kubectl describe nodes <node-name>

# Показать подробности пода <pod-name>.
kubectl describe pods/<pod-name>

# Показать подробности всех подов, управляемые контроллером репликации <rc-name>.
# Обратите внимание: любые поды, созданные контроллером репликации, имеют префикс с именем контроллера репликации.
kubectl describe pods <rc-name>

# Показать подробности по всем подам
kubectl describe pods

Заметка: Как правило, команда kubectl get используется для получения одного или нескольких ресурсов одного и того же типа. Она поддерживает большой набор флагов, с помощью которых можно настроить формат вывода, например, с помощью флага -o или --output. Вы можете указать флаг -w или --watch, чтобы отслеживать изменения в конкретном объекте. Команда kubectl describe в основном сфокусирована на описание многих взаимосвязанных аспектов указанного ресурса. При генерации вывода для пользователя она может обращаться к API-серверу. К примеру, команда kubectl describe node выдает не только информацию об узле, но и краткий обзор запущенных на нем подов, генерируемых событий и т.д.

kubectl delete - Удалить ресурсы из файла, потока stdin или с помощью селекторов меток, имена, селекторов ресурсов или имен ресурсов.

# Удалить под по типу и имени, указанных в файле pod.yaml.
kubectl delete -f pod.yaml

# Удалить все поды и сервисы с именем метки <label-name>.
kubectl delete pods,services -l name=<label-name>

# Удалить все поды, включая неинициализированные.
kubectl delete pods --all

kubectl exec - Выполнить команду в контейнера пода.

# Получить вывод от запущенной команды 'date' в поде <pod-name>. По умолчанию отображается вывод из первого контейнера.
kubectl exec <pod-name> date

# Получить вывод из запущенной команды 'date' в контейнере <container-name> пода <pod-name>.
kubectl exec <pod-name> -c <container-name> date

# Получить интерактивный терминал (TTY) и запустить /bin/bash в поде <pod-name>. По умолчанию отображается вывод из первого контейнера.
kubectl exec -ti <pod-name> /bin/bash

kubectl logs - Вывести логи контейнера в поде.

# Возвращает текущие логи в поде <pod-name>.
kubectl logs <pod-name>

# Вывод логов в поде <pod-name> в режиме реального времени. Это похоже на команду 'tail -f' Linux.
kubectl logs -f <pod-name>

Примеры: создание и использование плагинов

Посмотрите следующие примеры, чтобы ознакомиться с тем, как писать и использовать плагины kubectl:

# Плагин может быть на на любом языке, а сам исполняемый файл должен начинается с префикса "kubectl-".
cat ./kubectl-hello
#!/bin/bash

# Этот плагин выводит строку "hello world"
echo "hello world"

# Сделать плагин исполняемым
sudo chmod +x ./kubectl-hello

# Переместить его в директорию из PATH
sudo mv ./kubectl-hello /usr/local/bin

# Плагин дял kubectl создан и "установлен".
# Воспользоваться плагином можно через kubectl, вызвав его подобно обычной команды.
kubectl hello

hello world

# "Отмена установки" плагина происходит через удаление его файла из директории в PATH.
sudo rm /usr/local/bin/kubectl-hello

Посмотреть все доступные плагины kubectl можно с помощью подкоманды kubectl plugin list:

kubectl plugin list

The following kubectl-compatible plugins are available:

/usr/local/bin/kubectl-hello
/usr/local/bin/kubectl-foo
/usr/local/bin/kubectl-bar

# Эта команда также может сообщить, что плагин является неисполняемым,
# либо что плагин переопределен другими плагинами

sudo chmod -x /usr/local/bin/kubectl-foo
kubectl plugin list

The following kubectl-compatible plugins are available:

/usr/local/bin/kubectl-hello
/usr/local/bin/kubectl-foo
  - warning: /usr/local/bin/kubectl-foo identified as a plugin, but it is not executable
/usr/local/bin/kubectl-bar

error: one plugin warning was found

Плагины можно рассматривать как способ создания более сложной функциональности поверх существующих команд kubectl:

cat ./kubectl-whoami
#!/bin/bash

# Этот плагин использует команду `kubectl config` для вывода
# информации о текущем пользователе из текущего выбранного контекста
kubectl config view --template='{{ range .contexts }}{{ if eq .name "'$(kubectl config current-context)'" }}Current user: {{ .context.user }}{{ end }}{{ end }}'

Выполнение этого плагина генерирует вывод, содержащий пользователя для текущего выбранного контекста в файле KUBECONFIG:

# Сделать файл исполняемым
sudo chmod +x ./kubectl-whoami

# Перенести файл в директорию из PATH
sudo mv ./kubectl-whoami /usr/local/bin

kubectl whoami
Current user: plugins-user

Чтобы узнать больше о плагинах, изучите пример CLI-плагина.

Что дальше

Начните использовать команды kubectl.

5.2.2 - Поддержка JSONPath

Kubectl поддерживает шаблон JSONPath.

Шаблон JSONPath состоит из выражений JSONPath, заключенных в фигурные скобки {}. Kubectl использует JSONPath-выражения для фильтрации по определенным полям в JSON-объекте и форматирования вывода. В дополнение к оригинальному синтаксису шаблона JSONPath, допустимы следующие функции и синтаксис:

1. Внутри выражений JSONPath текстовые значения заключайте в двойные кавычки.
2. Используйте операторы range, end, конечные операторы для перебора списков.
3. Используйте отрицательные индексы срезов для перехода на предыдущий элемент в списке. Отрицательные индексы не "зацикливаются" в списке и работают пока истинно выражение -index + listLength >= 0.

Заметка:

• Оператор $ необязателен, поскольку по умолчанию выражение всегда начинается с корневого объекта.

• Объект результата выводиться через функцию String().

Все примеры ниже будут ориентироваться на следующий JSON-объект:

{
  "kind": "List",
  "items":[
    {
      "kind":"None",
      "metadata":{"name":"127.0.0.1"},
      "status":{
        "capacity":{"cpu":"4"},
        "addresses":[{"type": "LegacyHostIP", "address":"127.0.0.1"}]
      }
    },
    {
      "kind":"None",
      "metadata":{"name":"127.0.0.2"},
      "status":{
        "capacity":{"cpu":"8"},
        "addresses":[
          {"type": "LegacyHostIP", "address":"127.0.0.2"},
          {"type": "another", "address":"127.0.0.3"}
        ]
      }
    }
  ],
  "users":[
    {
      "name": "myself",
      "user": {}
    },
    {
      "name": "e2e",
      "user": {"username": "admin", "password": "secret"}
    }
  ]
}

Примеры использования kubectl и JSONPath-выражений:

kubectl get pods -o json
kubectl get pods -o=jsonpath='{@}'
kubectl get pods -o=jsonpath='{.items[0]}'
kubectl get pods -o=jsonpath='{.items[0].metadata.name}'
kubectl get pods -o=jsonpath="{.items[*]['metadata.name', 'status.capacity']}"
kubectl get pods -o=jsonpath='{range .items[*]}{.metadata.name}{"\t"}{.status.startTime}{"\n"}{end}'

Заметка:

В Windows нужно заключить в двойные кавычки JSONPath-шаблон, который содержит пробелы (не в одинарные, как в примерах выше для bash). Таким образом, любые литералы в таких шаблонов нужно оборачивать в одинарные кавычки или экранированные двойные кавычки. Например:

kubectl get pods -o=jsonpath="{range .items[*]}{.metadata.name}{'\t'}{.status.startTime}{'\n'}{end}"
kubectl get pods -o=jsonpath="{range .items[*]}{.metadata.name}{\"\t\"}{.status.startTime}{\"\n\"}{end}"

5.2.3 - kubectl

Synopsis

kubectl управляет кластерами Kubernetes.

Более подробная информация по ссылке: https://kubernetes.io/ru/docs/reference/kubectl/overview/

kubectl [flags]

Options

See Also

• kubectl annotate - Обновить аннотации ресурса
• kubectl api-resources - Вывести доступные API-ресурсы на сервере
• kubectl api-versions - Вывести доступные API-версии на сервере в виде "group/version".
• kubectl apply - Внести изменения в конфигурацию ресурса из файла или потока stdin.
• kubectl attach - Присоединиться к запущенному контейнеру
• kubectl auth - Проверить разрешение на выполнение определённых действий
• kubectl autoscale - Автоматически промасштабировать Deployment, ReplicaSet или ReplicationController
• kubectl certificate - Изменить сертификаты ресурсов.
• kubectl cluster-info - Показать информацию по кластеру
• kubectl completion - Вывод кода автодополнения указанной командной оболочки (bash или zsh)
• kubectl config - Изменить файлы kubeconfig
• kubectl convert - Конвертировать конфигурационные файлы в различные API-версии
• kubectl cordon - Отметить узел как неназначаемый
• kubectl cp - Копировать файлы и директории в/из контейнеров.
• kubectl create - Создать ресурс из файла или потока stdin.
• kubectl delete - Удалить ресурсы из файла, потока stdin, либо с помощью селекторов меток, имен, селекторов ресурсов или ресурсов
• kubectl describe - Показать подробную информацию о конкретном ресурсе или группе ресурсов
• kubectl diff - Сравнить действующую версию с новой (применяемой)
• kubectl drain - Вытеснить узел для подготовки к эксплуатации
• kubectl edit - Отредактировать ресурс на сервере
• kubectl exec - Выполнить команду в контейнере
• kubectl explain - Получить документацию ресурсов
• kubectl expose - Создать новый сервис Kubernetes из контроллера репликации, сервиса, развёртывания или пода
• kubectl get - Вывести один или несколько ресурсов
• kubectl kustomize - Собрать ресурсы kustomization из директории или URL-адреса.
• kubectl label - Обновить метки ресурса
• kubectl logs - Вывести логи контейнера в поде
• kubectl options - Вывести список флагов, применяемых ко всем командам
• kubectl patch - Обновить один или несколько полей ресурса, используя стратегию слияния патча
• kubectl plugin - Команда для работы с плагинами.
• kubectl port-forward - Переадресовать один или несколько локальных портов в под
• kubectl proxy - Запустить прокси на API-сервер Kubernetes
• kubectl replace - Заменить ресурс из определения в файле или потоке stdin.
• kubectl rollout - Управление плавающим обновлением ресурса
• kubectl run - Запустить указанный образ в кластере
• kubectl scale - Задать новый размер для Deployment, ReplicaSet или Replication Controller.
• kubectl set - Конфигурировать ресурсы в объектах
• kubectl taint - Обновить ограничения для одного или нескольких узлов
• kubectl top - Показать информацию по использованию системных ресурсов (процессор, память, диск)
• kubectl uncordon - Отметить узел как назначаемый
• kubectl version - Вывести информацию о версии клиента и сервера
• kubectl wait - Экспериментально: ожидать выполнения определенного условия в одном или нескольких ресурсах.

5.2.4 - kubectl для пользователей Docker

Вы можете использовать инструмент командной строки kubectl в Kubernetes для работы с API-сервером. Если вы знакомы с инструментом командной строки Docker, то использование kubectl не составит проблем. Однако команды docker и kubectl отличаются. В следующих разделах показана подкоманда docker и приведена эквивалентная команда в kubectl.

docker run

Для развёртывания nginx и открытия доступа к объекту Deployment используйте команду kubectl run.

docker:

docker run -d --restart=always -e DOMAIN=cluster --name nginx-app -p 80:80 nginx

55c103fa129692154a7652490236fee9be47d70a8dd562281ae7d2f9a339a6db

docker ps

CONTAINER ID        IMAGE               COMMAND                  CREATED             STATUS              PORTS                NAMES
55c103fa1296        nginx               "nginx -g 'daemon of…"   9 seconds ago       Up 9 seconds        0.0.0.0:80->80/tcp   nginx-app

kubectl:

# запустить под, в котором работает nginx
kubectl create deployment --image=nginx nginx-app

deployment "nginx-app" created

# add env to nginx-app
kubectl set env deployment/nginx-app  DOMAIN=cluster

deployment.apps/nginx-app env updated

Заметка: Команды kubectl выводят тип и имя созданного или измененного ресурса, который затем может быть использован в последующих командах. После создания объекта Deployment можно открыть новый сервис Service.

# открыть порт, чтобы иметь доступ к сервису
kubectl expose deployment nginx-app --port=80 --name=nginx-http

service "nginx-http" exposed

С помощью kubectl можно создать объект Deployment, чтобы убедиться, что N подов, запущены под nginx, где N — это количество реплик, указанных в спецификации (по умолчанию — 1). Вы также можете создать сервис с селектором, соответствующим меткам подов. Для получения дополнительной информации перейдите на страницу Use a Service to Access an Application in a Cluster.

По умолчанию образы запускаются в фоновом режиме, аналогично команде docker run -d .... Для запуска в центральном (интерактивном) режиме используйте команду ниже:

kubectl run [-i] [--tty] --attach <name> --image=<image>

В отличие от docker run ..., если вы укажете --attach, то присоедините stdin, stdout and stderr. Нельзя проконтролировать, какие потоки прикрепляются (docker -a ...). Чтобы отсоединиться от контейнера воспользуетесь комбинацией клавиш Ctrl+P, а затем Ctrl+Q.

Так как команда kubectl run запускает развёртывание для контейнера, то оно начнет перезапускаться, если завершить прикрепленный процесс по нажатию Ctrl+C, в отличие от команды docker run -it. Для удаления объекта Deployment вместе с подами, необходимо выполнить команду kubectl delete deployment <name>.

docker ps

Посмотреть, что сейчас запущено можно с помощью команды kubectl get.

docker:

docker ps -a

CONTAINER ID        IMAGE               COMMAND                  CREATED              STATUS                     PORTS                NAMES
14636241935f        ubuntu:16.04        "echo test"              5 seconds ago        Exited (0) 5 seconds ago                        cocky_fermi
55c103fa1296        nginx               "nginx -g 'daemon of…"   About a minute ago   Up About a minute          0.0.0.0:80->80/tcp   nginx-app

kubectl:

kubectl get po

NAME                        READY     STATUS      RESTARTS   AGE
nginx-app-8df569cb7-4gd89   1/1       Running     0          3m
ubuntu                      0/1       Completed   0          20s

docker attach

Чтобы присоединить процесс, который уже запущен в контейнере, используйте команду kubectl attach.

docker:

docker ps

CONTAINER ID        IMAGE               COMMAND                  CREATED             STATUS              PORTS                NAMES
55c103fa1296        nginx               "nginx -g 'daemon of…"   5 minutes ago       Up 5 minutes        0.0.0.0:80->80/tcp   nginx-app

docker attach 55c103fa1296
...

kubectl:

kubectl get pods

NAME              READY     STATUS    RESTARTS   AGE
nginx-app-5jyvm   1/1       Running   0          10m

kubectl attach -it nginx-app-5jyvm
...

Для отсоединения его от контейнера используйте сочетания клавиш Ctrl+P и Ctrl+Q.

docker exec

Для выполнения команды в контейнере используйте команду kubectl exec.

docker:

docker ps

CONTAINER ID        IMAGE               COMMAND                  CREATED             STATUS              PORTS                NAMES
55c103fa1296        nginx               "nginx -g 'daemon of…"   6 minutes ago       Up 6 minutes        0.0.0.0:80->80/tcp   nginx-app

docker exec 55c103fa1296 cat /etc/hostname

55c103fa1296

kubectl:

kubectl get po

NAME              READY     STATUS    RESTARTS   AGE
nginx-app-5jyvm   1/1       Running   0          10m

kubectl exec nginx-app-5jyvm -- cat /etc/hostname

nginx-app-5jyvm

Примеры с командной оболочкой

docker:

docker exec -ti 55c103fa1296 /bin/sh
# exit

kubectl:

kubectl exec -ti nginx-app-5jyvm -- /bin/sh
# exit

Для получения дополнительной информации обратитесь к странице Get a Shell to a Running Container.

docker logs

Для отслеживания логов в потоки stdout/stderr запущенного процесса используйте команду kubectl logs.

docker:

docker logs -f a9e

192.168.9.1 - - [14/Jul/2015:01:04:02 +0000] "GET / HTTP/1.1" 200 612 "-" "curl/7.35.0" "-"
192.168.9.1 - - [14/Jul/2015:01:04:03 +0000] "GET / HTTP/1.1" 200 612 "-" "curl/7.35.0" "-"

kubectl:

kubectl logs -f nginx-app-zibvs

10.240.63.110 - - [14/Jul/2015:01:09:01 +0000] "GET / HTTP/1.1" 200 612 "-" "curl/7.26.0" "-"
10.240.63.110 - - [14/Jul/2015:01:09:02 +0000] "GET / HTTP/1.1" 200 612 "-" "curl/7.26.0" "-"

Есть небольшая разница между подами и контейнерами: по умолчанию поды не прекращают выполнение, если их процессы завершаются. Вместо этого поды перезапускают процесс. Это похоже на опцию --restart=always в Docker, только с одной большой разницей. В Docker вывод каждого вызова процесса объединяется, в отличие от Kubernetes, где каждый вызов является отдельным. Для просмотра вывода предыдущего запуска в Kubernetes, используйте команду ниже:

kubectl logs --previous nginx-app-zibvs

10.240.63.110 - - [14/Jul/2015:01:09:01 +0000] "GET / HTTP/1.1" 200 612 "-" "curl/7.26.0" "-"
10.240.63.110 - - [14/Jul/2015:01:09:02 +0000] "GET / HTTP/1.1" 200 612 "-" "curl/7.26.0" "-"

Для получения дополнительной информации обратитесь к странице Logging Architecture.

docker stop и docker rm

Для завершения и удаления запущенного процесса используйте команду kubectl delete.

docker:

docker ps

CONTAINER ID        IMAGE               COMMAND                CREATED             STATUS              PORTS                         NAMES
a9ec34d98787        nginx               "nginx -g 'daemon of"  22 hours ago        Up 22 hours         0.0.0.0:80->80/tcp, 443/tcp   nginx-app

docker stop a9ec34d98787

a9ec34d98787

docker rm a9ec34d98787

a9ec34d98787

kubectl:

kubectl get deployment nginx-app

NAME         READY   UP-TO-DATE   AVAILABLE   AGE
nginx-app    1/1     1            1           2m

kubectl get po -l app=nginx-app

NAME                         READY     STATUS    RESTARTS   AGE
nginx-app-2883164633-aklf7   1/1       Running   0          2m

kubectl delete deployment nginx-app

deployment "nginx-app" deleted

kubectl get po -l app=nginx-app
# Return nothing

Заметка: При использовании kubectl удалить под напрямую не получится. Для этого сначала нужно удалить объект Deployment, которому принадлежит под. Если вы удалите под напрямую, то объект Deployment пересоздаст под.

docker login

В kubectl нет прямого аналога команды docker login. Если вы планируете использовать Kubernetes с приватным реестром, изучите страницу Using a Private Registry.

docker version

Для получения версии клиента и сервера используйте команду kubectl version.

docker:

docker version

Client version: 1.7.0
Client API version: 1.19
Go version (client): go1.4.2
Git commit (client): 0baf609
OS/Arch (client): linux/amd64
Server version: 1.7.0
Server API version: 1.19
Go version (server): go1.4.2
Git commit (server): 0baf609
OS/Arch (server): linux/amd64

kubectl:

kubectl version

Client Version: version.Info{Major:"1", Minor:"6", GitVersion:"v1.6.9+a3d1dfa6f4335", GitCommit:"9b77fed11a9843ce3780f70dd251e92901c43072", GitTreeState:"dirty", BuildDate:"2017-08-29T20:32:58Z", OpenPaasKubernetesVersion:"v1.03.02", GoVersion:"go1.7.5", Compiler:"gc", Platform:"linux/amd64"}
Server Version: version.Info{Major:"1", Minor:"6", GitVersion:"v1.6.9+a3d1dfa6f4335", GitCommit:"9b77fed11a9843ce3780f70dd251e92901c43072", GitTreeState:"dirty", BuildDate:"2017-08-29T20:32:58Z", OpenPaasKubernetesVersion:"v1.03.02", GoVersion:"go1.7.5", Compiler:"gc", Platform:"linux/amd64"}

docker info

Для получения разной информации про окружение и конфигурации перейдите в раздел kubectl cluster-info.

docker:

docker info

Containers: 40
Images: 168
Storage Driver: aufs
 Root Dir: /usr/local/google/docker/aufs
 Backing Filesystem: extfs
 Dirs: 248
 Dirperm1 Supported: false
Execution Driver: native-0.2
Logging Driver: json-file
Kernel Version: 3.13.0-53-generic
Operating System: Ubuntu 14.04.2 LTS
CPUs: 12
Total Memory: 31.32 GiB
Name: k8s-is-fun.mtv.corp.google.com
ID: ADUV:GCYR:B3VJ:HMPO:LNPQ:KD5S:YKFQ:76VN:IANZ:7TFV:ZBF4:BYJO
WARNING: No swap limit support

kubectl:

kubectl cluster-info

Kubernetes master is running at https://203.0.113.141
KubeDNS is running at https://203.0.113.141/api/v1/namespaces/kube-system/services/kube-dns/proxy
kubernetes-dashboard is running at https://203.0.113.141/api/v1/namespaces/kube-system/services/kubernetes-dashboard/proxy
Grafana is running at https://203.0.113.141/api/v1/namespaces/kube-system/services/monitoring-grafana/proxy
Heapster is running at https://203.0.113.141/api/v1/namespaces/kube-system/services/monitoring-heapster/proxy
InfluxDB is running at https://203.0.113.141/api/v1/namespaces/kube-system/services/monitoring-influxdb/proxy

5.2.5 - Команды kubectl

Справочник команд kubectl

5.2.6 - Шпаргалка по kubectl

Смотрите также: обзор Kubectl и руководство по JsonPath.

Эта команда представляет собой обзор команды kubectl.

kubectl - Шпаргалка

Автодополнение ввода для Kubectl

BASH

source <(kubectl completion bash) # настройка автодополнения в текущую сессию bash, предварительно должен быть установлен пакет bash-completion .
echo "source <(kubectl completion bash)" >> ~/.bashrc # добавление автодополнения autocomplete постоянно в командную оболочку bash.

Вы также можете использовать короткий псевдоним для kubectl, который можно интегрировать с автодополнениями:

alias k=kubectl
complete -F __start_kubectl k

ZSH

source <(kubectl completion zsh)  # настройка автодополнения в текущую сессию zsh
echo "[[ $commands[kubectl] ]] && source <(kubectl completion zsh)" >> ~/.zshrc # add autocomplete permanently to your zsh shell

Контекст и конфигурация kubectl

Установка того, с каким Kubernetes-кластером взаимодействует kubectl и изменяет конфигурационную информацию. Подробную информацию о конфигурационном файле смотрите на странице Authenticating Across Clusters with kubeconfig.

kubectl config view # показать объединённые настройки kubeconfig

# использовать несколько файлов kubeconfig одновременно и посмотреть объединённую конфигурацию из этих файлов
KUBECONFIG=~/.kube/config:~/.kube/kubconfig2

kubectl config view

# получить пароль для пользователя e2e
kubectl config view -o jsonpath='{.users[?(@.name == "e2e")].user.password}'

kubectl config view -o jsonpath='{.users[].name}'    # показать первого пользователя
kubectl config view -o jsonpath='{.users[*].name}'   # получить список пользователей
kubectl config get-contexts                          # показать список контекстов
kubectl config current-context                       # показать текущий контекст (current-context)
kubectl config use-context my-cluster-name           # установить my-cluster-name как контекст по умолчанию

# добавить новую конфигурацию для кластера в kubeconf с базовой аутентификацией
kubectl config set-credentials kubeuser/foo.kubernetes.com --username=kubeuser --password=kubepassword

# сохранить пространство имен для всех последующих команд kubectl в этом контексте.
kubectl config set-context --current --namespace=ggckad-s2

# установить контекст, используя имя пользователя и пространство имен.
kubectl config set-context gce --user=cluster-admin --namespace=foo \
  && kubectl config use-context gce

kubectl config unset users.foo                       # удалить пользователя foo

Apply

apply управляет приложениями с помощью файлов, которые определяют ресурсы Kubernetes. Выполните команду kubectl apply для создания и обновления ресурсов. Это рекомендуемый способ управления приложениями Kubernetes в промышленном окружении. Смотрите Kubectl Book.

Создание объектов

Манифесты Kubernetes могут быть определены в YAML или JSON. Можно использовать расширение файла .yaml, .yml и .json

kubectl apply -f ./my-manifest.yaml            # создать ресурсы
kubectl apply -f ./my1.yaml -f ./my2.yaml      # создать ресурсы из нескольких файлов
kubectl apply -f ./dir                         # создать ресурсы из всех файлов манифеста в директории
kubectl apply -f https://git.io/vPieo          # создать ресурсы из URL-адреса
kubectl create deployment nginx --image=nginx  # запустить один экземпляр nginx
kubectl explain pods                           # посмотреть документацию по манифестам подов

# Создать несколько YAML-объектов из stdin
cat <<EOF | kubectl apply -f -
apiVersion: v1
kind: Pod
metadata:
  name: busybox-sleep
spec:
  containers:
  - name: busybox
    image: busybox
    args:
    - sleep
    - "1000000"
---
apiVersion: v1
kind: Pod
metadata:
  name: busybox-sleep-less
spec:
  containers:
  - name: busybox
    image: busybox
    args:
    - sleep
    - "1000"
EOF

# Создать секрет с несколькими ключами
cat <<EOF | kubectl apply -f -
apiVersion: v1
kind: Secret
metadata:
  name: mysecret
type: Opaque
data:
  password: $(echo -n "s33msi4" | base64 -w0)
  username: $(echo -n "jane" | base64 -w0)
EOF

Просмотр и поиск ресурсов

# Get-команды с основном выводом
kubectl get services                          # Вывести все сервисы в пространстве имён
kubectl get pods --all-namespaces             # Вывести все поды во всех пространств имён
kubectl get pods -o wide                      # Вывести все поды в текущем пространстве имён с подробностями
kubectl get deployment my-dep                 # Вывести определённое развёртывание
kubectl get pods                              # Вывести все поды в пространстве имён
kubectl get pod my-pod -o yaml                # Получить информацию по поду в формате YAML

# Посмотреть дополнительные сведения команды с многословным выводом
kubectl describe nodes my-node
kubectl describe pods my-pod

# Вывести сервисы, отсортированные по имени
kubectl get services --sort-by=.metadata.name

# Вывести поды, отсортированные по количеству перезагрузок
kubectl get pods --sort-by='.status.containerStatuses[0].restartCount'

# Вывести постоянные тома (PersistentVolumes), отсортированные по емкости
kubectl get pv --sort-by=.spec.capacity.storage

# Получить метку версии всех подов с меткой app=cassandra
kubectl get pods --selector=app=cassandra -o \
  jsonpath='{.items[*].metadata.labels.version}'

# Получить все рабочие узлы (с помощью селектора исключаем узлы с меткой 'node-role.kubernetes.io/master')
kubectl get node --selector='!node-role.kubernetes.io/master'

# Получить все запущенные поды в пространстве имён
kubectl get pods --field-selector=status.phase=Running

# Получить внешние IP-адреса (ExternalIP) всех узлов
kubectl get nodes -o jsonpath='{.items[*].status.addresses[?(@.type=="ExternalIP")].address}'

# Вывести имена подов, принадлежащие к определённому RC
# Использование команды "jq" помогает упросить поиск в jsonpath, подробнее смотрите на сайте https://stedolan.github.io/jq/
sel=${$(kubectl get rc my-rc --output=json | jq -j '.spec.selector | to_entries | .[] | "\(.key)=\(.value),"')%?}
echo $(kubectl get pods --selector=$sel --output=jsonpath={.items..metadata.name})

# Показать метки всех подов (или любого другого объекта Kubernetes, которым можно прикреплять метки)
kubectl get pods --show-labels

# Получить готовые узлы
JSONPATH='{range .items[*]}{@.metadata.name}:{range @.status.conditions[*]}{@.type}={@.status};{end}{end}' \
 && kubectl get nodes -o jsonpath="$JSONPATH" | grep "Ready=True"

# Вывод декодированных секретов без внешних инструментов
kubectl get secret my-secret -o go-template='{{range $k,$v := .data}}{{"### "}}{{$k}}{{"\n"}}{{$v|base64decode}}{{"\n\n"}}{{end}}'

# Вывести все секреты, используемые сейчас в поде.
kubectl get pods -o json | jq '.items[].spec.containers[].env[]?.valueFrom.secretKeyRef.name' | grep -v null | sort | uniq

# Вывести все идентификаторы (containerID) контейнеров инициализации (initContainers) во всех подах.
# Это полезно при очистке остановленных контейнеров, не удаляя при этом контейнеры инициализации.
kubectl get pods --all-namespaces -o jsonpath='{range .items[*].status.initContainerStatuses[*]}{.containerID}{"\n"}{end}' | cut -d/ -f3

# Вывести события, отсортированные по временной метке
kubectl get events --sort-by=.metadata.creationTimestamp

# Сравнить текущее состояние кластера с состоянием, в котором находился бы кластер в случае применения манифеста.
kubectl diff -f ./my-manifest.yaml

Обновление ресурсов

Начиная с версии 1.11 подкоманда rolling-update была удалена (см. CHANGELOG-1.11.md), поэтому вместо неё используйте rollout.

kubectl set image deployment/frontend www=image:v2               # Плавающее обновление контейнеров "www" развёртывания "frontend", обновление образа
kubectl rollout history deployment/frontend                      # Проверить историю развёртывания, включая ревизии.
kubectl rollout undo deployment/frontend                         # Откатиться к предыдущему развёртыванию
kubectl rollout undo deployment/frontend --to-revision=2         # Откатиться к определённой ревизии
kubectl rollout status -w deployment/frontend                    # Отслеживать статус плавающего развёртывания "frontend" до его завершения
kubectl rollout restart deployment/frontend                      # Перезапуск плавающего развёртывания "frontend"


# Объявлено устаревшим, начиная с версии 1.11
kubectl rolling-update frontend-v1 -f frontend-v2.json           # (устарело) Плавающее обновление подов frontend-v1
kubectl rolling-update frontend-v1 frontend-v2 --image=image:v2  # (устарело) Изменить имя ресурса и обновить образ
kubectl rolling-update frontend --image=image:v2                 # (устарело) Обновить образ подов frontend
kubectl rolling-update frontend-v1 frontend-v2 --rollback        # (устарело) Отменить выполняющееся обновление

cat pod.json | kubectl replace -f -                              # Заменить под из определения в JSON-файле, переданного в поток stdin

# Принудительно заменить, удалить, а затем пересоздать ресурс. Это приведет к простою приложения
kubectl replace --force -f ./pod.json

# Создать сервис с реплицированным nginx на порту 80, который подключается к контейнерам на порту 8000.
kubectl expose rc nginx --port=80 --target-port=8000

# Обновить версию (метку) образа пода из одного контейнера single до v4
kubectl get pod mypod -o yaml | sed 's/\(image: myimage\):.*$/\1:v4/' | kubectl replace -f -

kubectl label pods my-pod new-label=awesome                      # Добавить метку
kubectl annotate pods my-pod icon-url=http://goo.gl/XXBTWq       # Добавить аннотацию
kubectl autoscale deployment foo --min=2 --max=10                # Автоматически промасштабировать развёртывание "foo"

Обновление ресурсов

# Обновить часть узла
kubectl patch node k8s-node-1 -p '{"spec":{"unschedulable":true}}'

# Обновить образ контейнера; необходимо указать spec.containers[*].name, чтобы произвести слияние
kubectl patch pod valid-pod -p '{"spec":{"containers":[{"name":"kubernetes-serve-hostname","image":"new image"}]}}'

# Обновить образ контейнера через json-патч с позиционными массивами
kubectl patch pod valid-pod --type='json' -p='[{"op": "replace", "path": "/spec/containers/0/image", "value":"new image"}]'

# Удалить развертывание livenessProbe через json-патч с позиционными массивами
kubectl patch deployment valid-deployment  --type json   -p='[{"op": "remove", "path": "/spec/template/spec/containers/0/livenessProbe"}]'

# Добавить нового элемента в позиционный массив
kubectl patch sa default --type='json' -p='[{"op": "add", "path": "/secrets/1", "value": {"name": "whatever" } }]'

Редактирование ресурсов

Вы можете отредактировать API-ресурс в любом редакторе.

kubectl edit svc/docker-registry                      # Отредактировать сервис docker-registry
KUBE_EDITOR="nano" kubectl edit svc/docker-registry   # Использовать другой редактор

Масштабирование ресурсов

kubectl scale --replicas=3 rs/foo                                 # Промасштабировать набор реплик (replicaset) 'foo' до 3
kubectl scale --replicas=3 -f foo.yaml                            # Промасштабировать ресурс в "foo.yaml" до 3
kubectl scale --current-replicas=2 --replicas=3 deployment/mysql  # Если количество реплик в развёртывании mysql равен 2, промасштабировать его до 3
kubectl scale --replicas=5 rc/foo rc/bar rc/baz                   # Промасштабировать несколько контроллеров репликации

Удаление ресурсов

kubectl delete -f ./pod.json                                              # Удалить под по типу и имени в pod.json
kubectl delete pod,service baz foo                                        # Удалить поды и сервисы с одноимёнными именам "baz" и "foo"
kubectl delete pods,services -l name=myLabel                              # Удалить поды и сервисы с именем метки myLabel
kubectl -n my-ns delete pod,svc --all                                     # Удалить все поды и сервисы в пространстве имен my-ns
# Удалить все поды, соответствующие pattern1 или pattern2 в awk
kubectl get pods  -n mynamespace --no-headers=true | awk '/pattern1|pattern2/{print $1}' | xargs  kubectl delete -n mynamespace pod

Работа с запущенными подами

kubectl logs my-pod                                 # вывести логи пода (в stdout)
kubectl logs -l name=myLabel                        # вывести логи пода с меткой myLabel (в stdout)
kubectl logs my-pod --previous                      # вывести логи пода (в stdout) по предыдущему экземпляру контейнера
kubectl logs my-pod -c my-container                 # вывести логи контейнера пода (в stdout, при работе с несколькими контейнерами)
kubectl logs -l name=myLabel -c my-container        # вывести логи пода с меткой myLabel (в stdout)
kubectl logs my-pod -c my-container --previous      # вывести логи контейнера пода (в stdout, при работе с несколькими контейнерами) по предыдущему экземпляру контейнера
kubectl logs -f my-pod                              # вывести логи пода в режиме реального времени (в stdout)
kubectl logs -f my-pod -c my-container              # вывести логи контейнера пода в режиме реального времени (в stdout, при работе с несколькими контейнерами)
kubectl logs -f -l name=myLabel --all-containers    # вывести логи всех подов с меткой myLabel (в stdout)
kubectl run -i --tty busybox --image=busybox -- sh  # запустить под как интерактивную оболочку
kubectl run nginx --image=nginx --restart=Never -n
mynamespace                                         # Запустить под nginx в заданном пространстве имён
kubectl run nginx --image=nginx --restart=Never     # Запустить под nginx и записать его спецификацию в файл pod.yaml
--dry-run -o yaml > pod.yaml

kubectl attach my-pod -i                            # Прикрепить к запущенному контейнеру
kubectl port-forward my-pod 5000:6000               # Переадресовать порт 5000 в локальной машине на порт 6000 в поде my-pod
kubectl exec my-pod -- ls /                         # Выполнить команду в существующем поде (в случае одного контейнера).
kubectl exec my-pod -c my-container -- ls /         # Выполнить команду в существующем поде (в случае нескольких контейнеров)
kubectl top pod POD_NAME --containers               # Показать метрики по заданному поду вместе с его контейнерами

Работа с узлами и кластером

kubectl cordon my-node                                                # Отметить узел my-node как неназначаемый
kubectl drain my-node                                                 # Вытеснить узел my-node, чтобы подготовиться к эксплуатации
kubectl uncordon my-node                                              # Отметить узел my-node как назначаемый
kubectl top node my-node                                              # Показать метрики по заданному узлу
kubectl cluster-info                                                  # Показать адреса главного узла и сервисов
kubectl cluster-info dump                                             # Вывести состояние текущего кластера в stdout
kubectl cluster-info dump --output-directory=/path/to/cluster-state   # Вывести состояние текущего кластера в /path/to/cluster-state

# Если ограничение с заданным ключом и проявлением уже существует, его значение будет заменено указанным
kubectl taint nodes foo dedicated=special-user:NoSchedule

Типы ресурсов

Вывести все поддерживаемые типы ресурсов, включая API-группу, флаг namespaced (организован ли ресурс в пространство имён или нет) и Kind:

kubectl api-resources

Другие варианты команды для анализа API-ресурсов:

kubectl api-resources --namespaced=true      # Все ресурсы с пространством имён
kubectl api-resources --namespaced=false     # Все ресурсы без пространства имён
kubectl api-resources -o name                # Все ресурсы с простым выводом  (только имя ресурса)
kubectl api-resources -o wide                # Все ресурсы с расширенным (с неограниченной длинной) выводом
kubectl api-resources --verbs=list,get       # Все ресурсы, которые поддерживают глаголы запроса "list" и "get"
kubectl api-resources --api-group=extensions # Все ресурсы в API-группе "extensions"

Форматирование вывода

Для вывода подробной информации в окно терминала в определенном формате, добавьте флаг -o (или --output) в команду kubectl, которая поддерживает форматирование.

Уровни детальности вывода и отладки в Kubectl

Уровни детальности вывода Kubectl регулируются с помощью флагов -v или --v, за которыми следует целое число, представляющее уровни логирования. Общие соглашения по логированиия Kubernetes и связанные с ними уровни описаны здесь.

Что дальше

• Подробнее о kubectl на странице обзора.

• Посмотреть опции kubectl.

• Ознакомиться с соглашениями по использованию kubectl, чтобы понять, как использовать его в повторно используемых скриптах.

• Посмотреть шпаргалки по kubectl сообщества.

6 - Участие в документации Kubernetes

Если вы хотите внести свой вклад в документацию или сайт Kubernetes, мы будем рады вашей помощи! Любой может принять участие в проекте, независимо от того, знакомы ли вы с проектом или нет, кроме этого не имеет значения кто вы — разработчик, обычный пользователь или всего лишь тот, кто терпеть не может опечаток.

С деталями о содержании и стиле документации Kubernetes вы можете ознакомиться в Documentation style overview.

Типы участников документации

• Член организации Kubernetes, который подписал CLA и уже поработал в проекте определённое время. Перейдите на страницу Членство в сообществе, чтобы узнать что нужно для вступления в организацию.
• Рецензент документации SIG — член организации Kubernetes, который занимался проверкой пулреквестов в документацию и поэтому был добавлен в соответствующую группу на GitHub, и кроме того является ответственным за файлы, перечисленные в OWNERS в репозитории GitHub.
• Утверждающий документации SIG — участник с хорошей репутацией, который продемонстрировал неизменную приверженность проекту. Утверждающий может принимать пулреквесты и публиковать контент от имени организации Kubernetes. Утверждающие также могут быть представителями документации SIG в более крупном сообществе Kubernetes. Некоторые из обязанностей утверждающего документации SIG, такие как организация нового выпуска, требуют огромного количество времени.

Способы участия в документации

Этот список разделен на то, что может делать каждый, что могут делать члены организации Kubernetes, и то, что требует более высокого уровня доступа и знания процессов документации SIG. Со временем постоянное участие в проекте поможет вам понять некоторые средства и организационные решения, которые уже были приняты.

Это не полный список способов поучаствовать в документации Kubernetes, зато он должен помочь вам начать работу.

• Любой человек
  • Добавление реализуемых задач
• Член
  • Улучшение существующей документации
  • Предложение идей по улучшению документации в Slack или в списке рассылки документации SIG
  • Улучшение доступности документации
  • Составление рекомендаций к пулреквестам в документацию
  • Написание постов в блоге или примеров использования продукта
• Рецензент
  • Документирование новых функциональных возможностей
  • Сортировка и маркировка задач
  • Анализ пулреквестов
  • Создание диаграмм, графических ресурсов и встраиваемых скринкастов и/или видео
  • Локализация
  • Участие в других репозиториях в качестве представителя документации
  • Редактирование пользовательских строк в коде
  • Улучшение комментариев в коде, Godoc
• Утверждающий
  • Публикация материалов участников, проверяя и объединяя пулреквесты
  • Участие в команде по выпуску новых версий Kubernetes в качестве представителя документации
  • Внесение предложений по улучшению руководства по стилю оформлению
  • Внесение предложений по улучшению в тесты документации
  • Внесение предложений по улучшению в сайт Kubernetes website или другие инструменты

Дополнительные способы участия

• Чтобы помочь сообществу Kubernetes с помощью онлайн-форумов, таких как Twitter или Stack Overflow, либо узнать о местных встречах и мероприятиях по Kubernetes, посетите страницу сообщества Kubernetes.
• Чтобы поучаствовать в разработке функциональности, ознакомьтесь со шпаргалкой для участника, чтобы начать.

6.1 - Участие для начинающих

Если вы хотите поучаствовать в работе над документацией Kubernetes, эта страница и связанные с ней темы могут помочь вам начать работу. Вам не нужно быть разработчиком или техническим писателем, чтобы внести вклад в документацию или улучшить сайт Kubernetes! Все, что вам нужно для тем на этой странице, это учетная запись на GitHub и браузер.

Если вы ищете информацию про участие в репозиториях, связанным с кодом Kubernetes, обратитесь к руководству сообщества Kubernetes.

Основные сведения про документацию

Документация Kubernetes написана на Markdown, обработана и развернута при помощи Hugo. Исходные файлы находятся на GitHub по адресу https://github.com/kubernetes/website. Основная часть документации хранится в директории /content/en/docs/. Часть справочной документации автоматически генерируется из скриптов в директории update-imported-docs/.

Вы можете создавать новые задачи, редактировать содержимое и проверять изменения от других участников, — всё это доступно с сайта GitHub. Вы также можете использовать встроенный в GitHub поиск и историю коммитов.

Не все задачи могут быть выполнены с помощью интерфейса GitHub, но некоторые из них обсуждаются в руководствах для продвинутых и опытных участников.

Участие в документации SIG

Документация Kubernetes поддерживается специальной группой (Special Interest Group, SIG) под названием SIG Docs. Мы общаемся с помощью канала Slack, списка рассылки и еженедельных видеозвонков. Будем рады новым участникам. Для получения дополнительной информации обратитесь к странице Участие в SIG Docs.

Руководящие принципы по содержанию

Сообщество SIG Docs разработало правила, которые касаются разрешенных видов контента в документации Kubernetes. Посмотрите руководство по содержанию документации для определения того, допустим ли контент, который вы хотите добавить. Задать вопросы про допустимый контент можно в Slack-канале #sig-docs.

Правила оформления

Мы поддерживаем руководство по оформлению с информацией о выборе, сделанном сообществом SIG Docs в отношении грамматики, синтаксиса, исходного форматирования и типографских соглашений. Прежде чем сделать свой первый вклад, просмотрите руководство по стилю и используйте его, когда у вас есть вопросы.

SIG Docs совместными усилиями вносит изменения в руководство по оформлению. Чтобы предложить изменение или дополнение, добавьте его в повестку дня предстоящей встречи SIG Docs и посетите её, чтобы принять участие в обсуждении. Смотрите руководство для продвинутых участников, чтобы получить дополнительную информацию.

Шаблоны страниц

Мы используем шаблоны страниц, чтобы управлять представление наших страниц документации. Разберитесь как работают эти шаблоны, ознакомившись с разделом Использование шаблонов страниц.

Макрокоды Hugo

Документация Kubernetes с помощью Hugo конвертируется из формата разметки Markdown в HTML. Мы используем встроенные макрокоды Hugo, а также некоторые из своих собственных, созданных специально для документации Kubernetes. Посетите страницу Нестандартные макрокоды Hugo, чтобы узнать, как их использовать.

Мультиязычность

Исходные файлы документации доступны на нескольких языках в директории /content/. Каждый язык имеет свою собственную директорию с двухбуквенным кодом, определенным стандартомISO 639-1 standard. Например, исходники документации для английского языка хранится в директории /content/en/docs/.

Более подробную информацию про участие в работе над документацией на нескольких языках "Localize content" в промежуточном руководстве по добавлению.

Если вы заинтересованы в переводе документации на новый язык, посмотрите раздел "Локализация".

Создание хороших заявок

Любой, у кого есть аккаунт на GitHub, может создать заявку (issue, или отчет об ошибке) в документации Kubernetes. Если вы заметили какую-либо какую-либо ошибку, даже если вы не знаете, как её исправить, откройте ишью. Но не делайте этого, если нашли небольшую ошибку, например, опечатку, которую вы при желании можете исправить самостоятельно. В этом случае можете исправить ее вместо того, чтобы писать об этом.

Как создать заявку

• Для существующей страницы

  Если заметили проблему на существующей странице в документации Kubernetes, перейдите в конец страницы и нажмите кнопку Create an Issue. Если вы ещё не авторизованы в GitHub, сделайте это. После этого откроется страница с форма для создания нового запроса в GitHub с уже предварительно заполненным полями.

  При помощи разметки Markdown опишите как можно подробнее, что хотите. Там, где вы видите пустые квадратные скобки ([ ]), проставьте x между скобками. Если у вас есть предлагаемое решение проблемы, напишите его.

• Запросить новую страницу

  Если вы хотите добавить что-то новое, но вы не уверены, на какую страницу документации это сделать или считаете, что новая информация не вписывается в существующие страницы, всё равно создайте ишью. Вы можете либо перейти на страницу документации, куда, по вашему мнению, нужно добавить новую информацию и создать заявку прямо с этой страницы, либо перейти по адресу https://github.com/kubernetes/website/issues/new/ и написать что вы хотите там.

Как заполнить хорошую заявку

Чтобы нам самим убедиться, что понимаем вас правильно, помните следующее:

• Используйте шаблон ишью и заполните его как можно подробнее.
• Четко изложите суть вашего проблемы, как она сказывается на пользователях.
• Как можно меньше ограничьте охват изменений в вашей заявке. Задачи с большим объемом работы разбейте на более мелкие. Например, "Fix the security docs" не является проблемой, требующей немедленного решения, зато заявка с заголовком "Add details to the 'Restricting network access' topic", вероятно, такой является.
• Если проблема связана с другой заявкой или пулреквестом, вы можете указать сослаться на них, либо по его полному URL-адресу, либо по их номеру с #. Например, Introduced by #987654.
• Будьте уважительны и избегайте жалоб. Например, заголовок ишью "The docs about X suck" явно не несёт ничего полезного или чтобы на него реагировали. Нормы поведения также применяется к общению в GitHub-репозиториях Kubernetes.

Участие в дискуссиях SIG Docs

Команда SIG Docs общается следующими способами:

• Зарегистрируйтесь в Slack-канале Kubernetes, а затем присоединитесь к каналу #sig-docs, где мы в режиме реального времени обсуждаем всё, что связано с документацией. И не забудьте представиться!
• Подпишитесь на список рассылки kubernetes-sig-docs, где проходят более общие дискуссии и принимаются официальные решения.
• Участвуйте в еженедельной видеовстрече IG Docs, которая анонсируется в Slack-канале и списке рассылки. В данный момент эти встречи проводятся в Zoom, поэтому вам необходимо загрузить клиент Zoom или позвонить по телефону.

Заметка: Вы всегда можете узнать когда будет очередное еженедельное собрание SIG Docs в календаре собраний сообщества Kubernetes.

Улучшение существующего текста

Чтобы улучшить текущее содержимое документации, вам нужно открыть пулреквест (pull request, PR) после того, как вы сделаете копию (fork) оригинального репозитория. Эти два термина относятся к GitHub. Для начала работы, которая показана в этом разделе, вам не нужно знать всё про эти понятия, так как вы всё можете делать в своём браузере. Когда вы перейдете к продвинутому руководству участника документации, тогда вам понадобиться пополнить свои знания Git.

Примечание. Разработчики кода Kubernetes. Если вы документируете новую функцию для предстоящего выпуска Kubernetes, ваш процесс будет немного другим. См. Документирование функции для руководства по процессу и информации о сроках.

Заметка: Для разработчиков кода Kubernetes: если вы документируете новую функциональность для новой версии Kubernetes, то процесс рассмотрения будет немного другим. Посетите страницу Документирование функциональности, чтобы узнать про процесс и информацию о крайних сроках.

Подписание CLA-соглашения CNCF

Прежде чем внести вклад в код или документацию Kubernetes, вам обязательно следует прочитать руководство для участников и подписать лицензионное соглашение участника (Contributor License Agreement, CLA). Не переживайте — подписание не займет много времени!

Поиск задач для работы

Если вы уже нашли что исправить, просто следуйте инструкциям ниже. Для этого вам не обязательно создавать ишью (хотя вы, безусловно, пойти этим путём).

Если вы хотите ещё не определились с тем, над чем хотите поработать, перейдите по адресу https://github.com/kubernetes/website/issues и найдите ишью с меткой good first issue (вы можете использовать эту ссылку для быстрого поиска). Прочитайте комментарии, чтобы убедиться что нет открытого пулреквеста для решения текущей ишью, а также, что никто другой не оставил комментарий, что он работает над этой задачей в последнее время (как правило, 3 дня). Добавьте комментарий, что вы хотели бы заняться решением этой задачи.

Выбор правильной ветки в Git

Самым важный момент в создании пулреквестов — это выбор нужной ветки для вашей работы. Используйте эти рекомендации, чтобы принять верное решение:

• Используйте ветку master для исправления ошибок в текущей документации, либо чтобы улучшить существующий текст.
• Используйте ветку master для документирования функциональности в текущей версии Kubernetes, для которой отсутствовала документация. Прежде всего вам нужно написать документацию на английском языке, а затем команды по переводам подхватят это изменение, чтобы актуализировать перевод.
• Если вы работаете над переводом, вам нужно следовать соглашению в этой конкретной локализации. Чтобы понять это, вы можете другие пулреквесты (подсказка: is:pr is:merged label:language/xx)
  • Некоторые команды локализации работают с пулреквестами, которые ориентированы на ветку master
  • Другие команды локализации работают с рядом долговечных веток, периодически сливая их в ветку master. Такая ветка именуется как dev-<version>-<language code>.<team milestone>, например, dev-release-1.24-ja.1.
• Если вы пишете или обновляете документацию к выпуску грядущего изменения, то вам необходимо знать мажорную и минорную версию Kubernetes, в которой это изменение впервые появится.
  • Например, если переключатель возможностей (feature gates) JustAnExample должен измениться с альфа-версии на бета-версию в следующей минорной версии, вам необходимо знать номер этой версии.
  • Найдите ветку выпуска, названную для этой версии. Например, функциональность, которая изменились в выпуске vrelease-1.24, будет документирована в ветке dev-release-1.24.

Если вы все еще не уверены, какую ветку выбрать, спросите в Slack-канале #sig-docs или посетите еженедельную встречу SIG Docs, чтобы внести ясность.

Отправка пулреквеста

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

1. На странице, которую вы хотите отредактировать, щелкните на иконку карандаша в правом верхнем углу. Откроется новая страница на GitHub с небольшой подсказкой.

2. Если вы ранее не делали копию репозитория документации Kubernetes, вам будет предложено это сделать. Создайте копию репозитория под своим логином GitHub, а не в организации, в которой вы состоите. URL-адрес копии репозитория будет выглядит как https://github.com/<username>/website, в случае у вас нет репозитория с таким же названием.

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

3. Откроется редактор GitHub для редактирования исходного файла в формате Markdown. Внесите свои изменения. Под редактором заполните форму Propose file change. Первое поле — краткое содержание вашего сообщения коммита, оно должно содержать не более 50 символов. Второе поле является необязательным, в нём вы можете подробно расписать суть ваших изменений.

   Заметка: Не ссылайте на другие ишью или пулреквесты на GitHub в сообщении коммита. Вы можете сослаться на них в тексте пулреквеста.

   Нажмите на кнопку Propose file change. Изменения в файле записываются в виде коммита в новой ветке вашей копии репозитория, которая автоматически будет иметь имя что-то вроде patch-1.

4. На следующей странице вам будут показаны различия в вашей ветке (поля выбора head fork и compare) с текущим состоянием оригинального репозитория (base fork) в основной ветке (base) (по умолчанию ветка master в репозитории kubernetes/website). Вы можете выбрать другое значение в полях выбора, но не делайте этого сейчас. Сравните различия и если всё верно, нажмите кнопку Create pull request.

   Заметка: Если вы не хотите создавать пулреквест в данный момент, это можно сделать позже, если перейти на страницу репозитория сайта Kubernetes или вашей копии репозитория. На сайте GitHub вам предложит открыть пулреквест, если он обнаружит новую ветку в вашей копии репозитория.

5. Отобразится форма с заголовком Open a pull request. Название пулреквеста будет содержать краткое описание из сообщения коммита, хотя вы можете изменить его при необходимости. В описании пулреквеста будет остальная информация из сообщения коммита (если оно есть) и небольшой шаблон с текстом. Прочитайте текст шаблона и сделайте то, что там описано, а затем удалите этот шаблонный текст. Если вы добавите в описание пулреквест fixes #<000000> или closes #<000000>, где #<000000> - номер связанной заявки, то GitHub автоматически закроет указанную заявку при слиянии пулреквеста. Оставьте флажок Allow edits from maintainers отмеченным. Нажмите на кнопку Create pull request.

   Поздравляем! Ваш пулреквест добавлен в список пулреквестов.

   Через несколько минут вы сможете просмотреть версию сайта с изменениями в вашем пулреквесте. Перейдите в низ страницы пулреквеста на вкладке Conversation и там нажмите на ссылку Details рядом с проверкой deploy/netlify. По умолчанию она откроется в текущей вкладке.

   Заметка: Пожалуйста, открывайте пулреквест, изменения которого затрагивают только один язык. Например, если вам нужно одинаково изменить один и тот же пример кода в нескольких языках, откройте по отдельному пулреквесту для каждого языка.

6. Ожидайте, когда проверят ваш пулреквест. Как правило, рецензенты выбираются авматоматически ботом k8s-ci-robot. Если рецензент попросил изменить пулреквест, вы можете сделать это, если перейдёте на вкладку Files changed и щёлкните на иконку с карандашом на любом изменённом файле в вашем пулреквесте. Сохранение измененного файла оформляется в виде нового коммита в ветке, указанной в пулреквесте. Если вы ожидаете новую проверку изменений от рецензента, заранее попросите его об этом не более одного раза в 7 дней. Вы также можете зайти в Slack-канал #sig-docs — это хорошее место, где можно попросить проверку пулреквеста.

7. Если ваши изменения одобрены, то рецензент объединяет соответствующий пулреквест. Через несколько минут вы сможете сможете увидеть его в действии на сайте Kubernetes.

Это только один из способов отправить пулреквест. Если вы уже опытный пользователь Git и GitHub, вы можете вносить изменения, используя локальный GUI-клиент или Git из терминала вместо того, чтобы использовать интерфейс GitHub для этого. Некоторые основы использования Git-клиента из командной строки обсуждаются в руководстве для продвинутого участника.

Просмотр пулреквестов в документацию

Новички документации могут обозревать пулреквесты. Вы можете изучить кодовую базу и завоевать доверие к себе со стороны коллег-участников. Документация на английском — это первоисточник содержимого. Мы общаемся на английском языке во время еженедельных встреч и в объявлениях сообщества. Владение английским языком может быть разным, поэтому используйте простой и прямой язык в своих обзорах пулреквестов. Полезные обзоры фокусируются как на мелких деталях, так и на потенциальном влиянии изменений.

Обзоры не носят «обязательный характер», это означает, что только ваша проверка не приведет к слиянию пулреквеста. Тем не менее, это не делает ваши обзоры бесполезными. Даже только просмотр изменений в пулреквеста поможет вам понять как происходит рабочий процесс, какие могут быть трудности и проблемы. Перед проверкой пулреквестов ознакомьтесь с руководством по содержанию и руководством по оформлению, чтобы узнать, каким должен быть содержимое и как оно должно быть оформлено..

Рекомендации

• Будьте вежливы, внимательны и помогайте другим
• Не забывайте отмечать также положительные стороны пулреквеста
• Будьте чутким и думайте, как ваши комментарии могут быть восприняты
• Проявите добрые намерения и задавайте уточняющие вопросы
• Опытным участникам: помогайте новым участникам, их работа требует глаз да глаз

Поиск и проверка пулреквеста

1. Перейдите по URL-адресу https://github.com/kubernetes/website/pulls. Вы увидите список всех пулреквестов в репозиторий сайта Kubernetes и его документации.

2. По умолчанию открываются открытые пулреквесты (статус open), поэтому вы не увидите закрытых или принятых пулреквестов. Рекомендуется добавить дополнительный фильтр cncf-cla: yes, а также для вашей первой проверки пулреквеста неплохо применить ещё и size/S и size/XS. Метка с размером назначается автоматически в зависимости от количества изменённых строк кода в пулреквесте. Вы можете применить фильтры, используя поля выбора в верхней части страницы, либо воспользоваться этой ссылкой для просмотра небольших пулреквестов. Все фильтры объединены в логическое AND, поэтому у вас не получиться искать по меткам size/XS и size/S одновременно.

3. Перейдите на вкладку Files changed. Посмотрите изменения, внесенные в PR, а также изучите любые связанные задачи (если есть). Если вы видите ошибку, неточность или хотите внести улучшение, то наведите курсор на строку и щелкните на появившийся символ +.

   Вы можете написать комментарий, после чего нажать на кнопку Add single comment или Start a review. Как правило, лучше начать проверку (review), поскольку тогда вы сможете оставить несколько комментариев и уведомить автора PR только после завершения рецензирования, вместо того, чтобы упоминать его в каждом комментарии.

4. После окончания разбора пулреквеста, нажмите на кнопку Review changes вверху страницы. Вы можете подвести краткий итог своей проверки и выполнить одно из действий: просто прокомментировать, одобрить или запросить изменения. Новым участникам нужно всегда только комментировать (кнопка Comment) пулреквесты.

Спасибо за обзор пулреквеста! Если вы новенький в проекте, рекомендуется попросить кого-нибудь оценить ваш обзор пулреквеста. Slack-канал #sig-docs — отличное место для этого.

Написание постов в блоге

Любой может написать пост в блоге и отправить его на рассмотрение. Посты блога не должны носит коммерческий характер и должны отражать опыт, который может широко применён в сообществе Kubernetes.

Чтобы заявить о посте вы можете отправить его, используя форму блога Kubernetes, либо же выполнить следующие действия.

1. Подпишите CLA, если вы еще этого не сделали.
2. Изучите разметку Markdown у текущих постов блога в репозитории сайта.
3. Напишите свою статью в вашем любимом текстовом редакторе.
4. По ссылке из второго шага нажмите на кнопку Create new file. Скопируйте из своего редактора текст и вставьте в многострочное поле. Назовите файл так, чтобы он соответствовал предлагаемому заголовку статьи в блоге, но не указывайте дату в имени файла. Рецензенты блога будут работать с вами над окончательным именем файла и датой публикации записи.
5. Когда вы сохраните файл, начнётся описанный выше процесс принятия пулреквеста в GitHub.
6. Рецензент блога рассмотрит вашу статью и вместе с вами будет работать над ее улучшением. Когда запись в блоге будет одобрена, будет известна дата публикации вашей статьи.

Отправка примеров использования

В примерах использования показывается, как организации используют Kubernetes для решения собственных реальных проблем. Они написаны в сотрудничестве с маркетинговой командой Kubernetes, которой занимается CNCF.

Ознакомьтесь с существующими примерами использования. Воспользуйтесь формой добавления нового примера использования Kubernetes, чтобы поделиться своим опытом.

Что дальше

Если вы хорошо поняли темы, затронутые в этом разделе, но хотите глубже взаимодействовать с командой документации Kubernetes, прочитайте расширенное руководство по участию в документации.

6.2 - Участие для продвинутых

1

На этой странице предполагается, что вы изучили и понимаете задачи на странице Участие для начинающих и теперь готовы узнать о других способах внести свой вклад.

Заметка: Некоторые задачи требуют использование Git-клиента из командной строки и других инструментов.

Теперь, когда вы уже знаете кое-что и приняли участие в документации Kubernetes, как описано в теме Участие для начинающих, вы можете пойти ещё дальше. Далее пойдут задачи, предусматривающие наличие и желание получить глубокие знания по следующим темам:

• Концепции Kubernetes
• Рабочие процессы документации Kubernetes
• Поиск нужной информации о будущих возможностях Kubernetes
• Сильные аналитические навыки в целом

Эти задачи не такие последовательные, как задачи для начинающих. Поэтому мы не ожидаем, что кто-то в одиночку будет постоянно заниматься всеми ими.

Знакомство с Prow

Prow — это система CI/CD, использующая Kubernetes, которая выполняет задания с пулреквестами (PR). Prow с помощью команд, похожих на те, что есть в чатботах, даёт возможность обрабатывать действия в организации Kubernetes на GitHub. Вы можете выполнять целый ряд действий, такие как добавление и удаление меток, закрытие заявок и назначение утверждающего. Введите Prow-команду в поле для комментария в формате /<command-name>. Некоторые популярные команды:

• /lgtm (looks good to me): добавляет метку lgtm, которая сообщает, что рецензент проверил PR
• /approve: одобряет PR так, чтобы он мог быть принят (эта команда работает только для утверждающих)
• /assign: назначает проверяющего на PR
• /close: закрывает ишью или PR
• /hold: добавляет метку do-not-merge/hold, которая означает, что PR не может быть автоматически принят
• /hold cancel: удаляет метку do-not-merge/hold

Заметка: Не все команды работают для каждого пользователя. Бот Prow сообщит вам, если вы пытаетесь выполнить команду, не разрешенную для вашего уровня.

Детально изучите список команд Prow, прежде чем начать проверять PR или сортировать ишью.

Проверка пулреквестов

Каждую неделю утверждающий доброволец документации сортирует и просматривает пулреквесты и заявки. Такой человек называется "PR Wrangler" на неделю. Расписание ведется с помощью планировщика PR Wrangler. Чтобы поучаствовать в этом списке, посетите еженедельную встречу SIG Docs. Даже если вас не выбрали дежурным по PR на текущую неделю, вы все равно можете проверять пулреквесты (PR), которые еще не были детально просмотрены.

В дополнение к ротации автоматизированная система добавляет в каждый новый PR и предлагает рецензентов и утверждающих для него, основываясь на списке утверждающих и рецензентов в измененных файлах. Ожидается, что автор PR будет следовать указаниям бота, поэтому PR должен быть быстро проверить.

Мы хотим, чтобы пулреквесты принимались и публиковались как можно быстрее. Чтобы документация оставалась точной и актуальной, каждый PR должен проверяться людьми, понимающие суть темы, а также теми, кто имеет опыт написания отличной документации.

Рецензенты и утверждающие должны предоставить конкретную и конструктивную обратную связь, чтобы заинтересованные участники были вовлечены и помогали им улучшаться. Иногда, чтобы помочь новому участнику подготовить свой PR к слиянию, требуется больше времени, чем просто переписать его самостоятельно, но проект лучше в долгосрочной перспективе, когда у нас есть множество активных участников.

Прежде чем приступить к проверке PR, убедитесь, что вы знакомы с руководством по содержанию документации, руководством по оформлению документации и нормы поведения.

Поиск пулреквестов для проверки

Чтобы посмотреть все открытые пулреквесты, перейдите на вкладку Pull Requests в GitHub-репозитории. PR можно проверять только, если он соответствует всем перечисленным ниже критериям:

• Имеет метку cncf-cla:yes
• Не содержит надписи WIP в описании
• Не имеет тег с фразой do-not-merge
• Нет конфликтов для слияния
• Сделан в правильную ветку (обычно это master, за исключением, если PR не относится к невыпущенной ещё функциональности)
• Не проверялся ещё детально другим проверяющим документации (то же самое касается и остальных технических рецензентов), если только этот человек явно не обратился за вашей помощью. В частности, не рекомендуется добавлять много новых комментариев после других циклов рассмотрения PR.

Если PR не имеет условия для проверки, можно оставить комментарий, чтобы сообщить автору о текущих проблемах и предложить помочь решить их. Если автор пулреквеста был оповещён о проблемах и не устранил их в течение нескольких недель или месяцев, то рано или поздно такой PR будет закрыт.

Если вы новичок в проверке пулреквестов или у вас недостаточно времени и возможностей, попробуйте поискать PR с тегом size/XS или size/S. Размер пулреквеста автоматически определяется по количеству изменённых строк в PR.

Рецензенты и утверждающие

В репозитории сайта Kubernetes работа построена иначе, чем в других репозиториях Kubernetes, когда речь идет о роли рецензентов и утверждающих. Для получения дополнительной информации об обязанностях рецензентов и утверждающих см. Участие в SIG Docs. Ниже вы найдете краткий обзор.

• Рецензент проверяет содержание пулреквеста для соблюдения технической точности. Рецензент даёт понять, что PR технически точен, оставляя комментарий с /lgtm к PR.

  Заметка: Не добавляйте /lgtm, если вы не уверены в технической точности документации, измененной или добавленной в PR.

• Утверждающий проверяет содержание запроса на предмет качества и соответствия рекомендациям SIG Docs, приведенным в руководствах по содержанию и оформлению. Только люди, указанные в качестве утверждающих в файле OWNERS, могут одобрить PR. Чтобы одобрить PR, оставьте комментарий /approve к PR.

PR объединяется, когда у него есть комментарий /lgtm от кого-либо из организации Kubernetes и комментарий /approve от утверждающего в группе sig-docs-maintainers, если он не удерживается, а автор PR подписал CLA.

Заметка: Раздел "Участие" содержит больше информации для рецензентов и утверждающих, включая конкретные обязанности для утверждающих.

Проверка PR

1. Изучите описание PR вместе с указанными ишью и ссылками, если они есть. Кратковременные мимолетные обзоры иногда могут наносит больше вреда, чем пользы, поэтому убедитесь, что вы обладаете нужными знаниями, чтобы сделать содержательный обзор.

2. Если кто-то другой может лучше всего проверит определенный PR, упомяните этого человека, добавив комментарий /assign @<github-username>. Если вы обратились за технической проверкой к человеку, который не занимается документацией, но при этом вы хотите сами посмотреть PR как участник группы документации, то не стесняйтесь это делать.

3. Перейдите на вкладку Files changed. Посмотрите на все изменённые строки. Удалённый текст выделен красным, а строки с ним начинаются с символа -. Добавленный текст отмечен зелёным фоном, а строки с ним начинаются с символа +. Внутри строки фактически измененный контент имеет чуть более темный зеленый фон, чем остальная часть строки.

   • В частности, если в PR есть сложное форматирование или он изменяет CSS, JavaScript или другие элементы сайта, вы можете просмотреть сайт, сгенерированный с этими изменениями в PR. Перейдите на вкладку Conversation и нажмите ссылку Details в проверке deploy/netlify в нижней части страницы. По умолчанию ссылка открывается в текущей вкладке браузера, поэтому чтобы потерять частичный отзыв, откройте ссылку в новой вкладке. Вернитесь на вкладку Files changed, чтобы продолжить проверку пулреквеста.

   • Убедитесь, что PR соответствует правилам содержания и оформления; если что-то не так, укажите на этом со ссылкой на раздел в руководстве.

   • Если у вас есть вопрос или вы хотите прокомментировать определённое изменение, наведите курсор мыши на строку и кликните на появившуюся сине-белую кнопку с иконкой +. Напишите свой комментарий и нажмите на кнопку Start a review.

   • Если вам нужно оставить больше одного комментария, сделайте это по аналогии с предыдущим шагом.

   • По соглашению, если вы видите небольшую проблему, не имеющей отношение к основному назначению PR, например, опечатку или лишний пробел, вы можете сообщить о ней, начав комментарий с nit:, чтобы автор знал, что это незначительная ошибка. Хотя это не означает, что автор пулреквеста может проигнорировать такие проблемы.

   • Когда вы всё проверили или у вас не осталось комментариев, прокрутите в верхнюю часть страницы и нажмите на кнопку Review changes. Далее кликните либо на Comment или Request Changes. Напишите краткий итог вашей проверки и добавьте соответствующие Prow-команды по одной на каждой строке в поле Review Summary. SIG Docs следует процессу проверки кода Kubernetes. Все ваши комментарии будут отправлены автору PR в виде одного уведомления.

     • Если вы считаете, что PR в хорошем состоянии, чтобы его принять, добавьте команду /approve в резюме вашей проверки.

     • Если PR не нуждается в дополнительном техническом рассмотрении, добавьте ещё команду /lgtm.

     • Если PR требуется дополнительный технический обзор, добавьте команду /assign и после неё укажите логин человека на GitHub, который должен сделать технический анализ. Посмотрите на поле рецензентов во вступительной (фронтальной) части вверху данного Markdown-файла, чтобы выяснить, кто может провести технический разбор пулреквеста.

     • Чтобы заблокировать слияние PR, используйте команду /hold. Она добавит метку do-not-merge/hold.

     • Если в PR нет конфликтов и есть метки lgtm и approve (и нет метки hold), то он автоматически объединиться.

     • Если PR имеет метки lgtm и/или approve, и появляются новые изменения, эти метки будут автоматически удалены.

       Посмотрите список доступных команд, которые можно использовать в PR.

   • Если вы ранее выбрали нажали на Request changes и затем автор PR решил все указанные проблемы, вы можете обновить статус проверки либо на вкладке Files changed, либо в нижней части вкладки Conversation. Обязательно укажите команду /approve и при необходимости выберите технических рецензентов, чтобы можно было объединить PR.

Редактирование PR другого человека

Добавление комментариев в PR — полезное дело, но могут быть случаи, когда нужно сделать коммит в пулреквест другого человека, а не просто оставить свой отзыв.

Не поддавайтесь желанию выполнить работу за другого человека, если только он явно не попросит вас об этом или вы не захотите оживить давно заброшенный PR. Хотя это может быть быстрее в краткосрочной плане, но это лишает человека возможности внести собственный вклад.

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

Вы не можете отредактировать чужой PR, если выполняется одно из условий:

• Если автор PR отправил свою ветку непосредственно в репозиторий https://github.com/kubernetes/website/, то только рецензент с правом отправки изменений напрямую в репозиторий может вносить изменения в PR. Авторам следует открыть PR из ветки в своей копии репозитория.
• Если автор PR явно запретил редактирование утверждающими, вы не сможете внести изменения в его PR, пока он не изменит эту настройку.

Если файл уже изменён в PR

Этот метод использует интерфейс GitHub. Вы можете использовать командную строку, если вам комфортнее работать в ней, даже если вам нужно изменить файл, который ранее редактировался в PR.

1. Перейдите на вкладку Files changed.
2. Прокрутите к блоку с файлом, который вы хотите отредактировать и нажмите на иконку с карандашом.
3. Внесите изменения, напишите сообщение коммита в соответствующем поле под текстовым редактором и нажмите Commit changes.

После этого ваш коммит отправляется в ветку из PR (скорее всего, в копию репозитория автора), и теперь отображается в PR, а ваши изменения отражаются на вкладке Files changed. Оставьте комментарий, чтобы автор PR знал, что вы что-то сделали в PR.

Если автор использует командную строку, а не сайт GitHub для работы с этим PR, он должен получить изменения со своей копии репозитория и перебазировать свою локальную ветку на ветку своей копии, прежде чем заниматься своим PR.

Если файл ещё не был изменён в PR

Если необходимо внести изменения в файл, который не был отредактирован в рамках конкретного PR, нужно использовать командную строку. Вам придётся по душе такой метод, если вы предпочитаете использовать терминал вместо использования сайта GitHub.

1. Узнайте URL-адрес копии репозитория автора пулреквеста. Вы можете найти его в нижней части вкладки Conversation. Найдите текст Add more commits by pushing to. Первая ссылка после этой надписи ведет на ветку, а вторая ссылка — на саму копию репозитория. Скопируйте вторую ссылку. Запомните название ветки, пригодится впоследствии.

2. Добавьте копию репозитория как новый удаленный репозиторий. В терминале перейдите в директорию своей копии репозитория. Придумайте имя для удаленного репозитория (например, по имени логина автора на GitHub) и добавьте его, используя следующую команду:

   git remote add <name> <url-of-fork>
   

3. Получите информацию о добавленном удаленном репозитории. Это действие не затронет локальные файлы, а только загрузит в вашу копии репозитория информацию о другой копии (например, ветки и теги).

   git remote fetch <name>
   

4. Перейдите в ветку, полученную с удаленного репозитория. Эта команда не получится, если у вас локально уже есть ветка с таким же именем.

   git checkout <branch-from-PR>
   

5. Внесите изменения и добавьте их через git add, а затем зафиксируйте их.

6. Отправьте изменения в удаленный репозиторий автора.

   git push <remote-name> <branch-name>
   

7. Откройте снова сайт GitHub и обновите страницу PR. Вы увидите ваши изменения. Добавьте комментарий для автора, чтобы он был в курсе, что вы изменили его PR.

Если автор использует командную строку, а не интерфейс на GitHub для работы над PR, ему нужно получить новые изменения из своей копии репозитоии и перебазировать свою локальную ветку на ветку своей копии репозитории, прежде чем снова заниматься собственным PR.

Работа из локальной копии

В случае изменений нескольких файлов, либо добавлением новых или перемещением старых, лучше работать из локальной копии Git-репозитория на компьютере, нежели чем использовать для этого GitHub. Следующие инструкции используют командую утилиту git, которая предполагается, что она уже установлена на вашем компьютере. Вы можете воспользоваться ими даже, если пользуетесь графическим Git-клиента.

Клонирование репозитория

Вам нужно только один раз клонировать репозиторий на каждом компьютере, на котором вы работаете с документацией Kubernetes.

1. Создайте копию репозитория kubernetes/website на GitHub. В браузере перейдите по https://github.com/kubernetes/website и нажмите на кнопку Fork. После нескольких секунд вы будете автоматически перенаправлены на URL-адрес вашей копии, которая будет иметь следующий вид: https://github.com/<github_username>/website.

2. В окне термина используйте команду git clone для получения копии репозитория.

   git clone git@github.com/<github_username>/website
   

   После выполнения этой команды в текущей рабочей директории появится новая директория website с содержимым вашего репозитория на GitHub. В данном случае удаленный репозиторий origin будет ссылаться на вашу копию репозитория.

3. Перейдите в новую директорию website. Добавьте новый удалённый репозиторий kubernetes/website под именем upstream.

   cd website
   
   git remote add upstream https://github.com/kubernetes/website.git
   

4. Проверьте ваши репозитории origin и upstream.

   git remote -v
   

   Output is similar to:

   origin	git@github.com:<github_username>/website.git (fetch)
   origin	git@github.com:<github_username>/website.git (push)
   upstream	https://github.com/kubernetes/website (fetch)
   upstream	https://github.com/kubernetes/website (push)
   

Работа в локальном репозитории

Прежде чем начать работать в локальном репозитории, вам нужно выяснить, из какой ветки будет основываться ваша работа. Ответ на этот вопрос зависит от того, что хотите сделать, но можно руководствоваться следующими правилами:

• Для общих улучшений существующего контента создайте собственную ветку от ветки master.
• Для добавления нового контента про функциональность, которая уже есть в текущих версиях Kubernetes, начните с ветки master.
• В случае большой и длительной работы, над которой будут трудиться несколько участников SIG Docs, например, реорганизация контента, создайте отдельную ветку, специально предназначенной для этого.
• Для нового контента про будущие, но ещё не выпущенные версии Kubernetes, работайте в ветке предварительного выпуска, созданной специально для этой версии Kubernetes.

Для получения дополнительной информации обратитесь к разделу Выбор правильной ветки.

После того, как вы определили, с какой ветви начать свою работу (или на какой ветке будет базироваться ваша работа, если говорить в терминологии Git), следуйте определённому ниже рабочему процессу, чтобы ваша работа оставалась актуальной.

1. Когда вы работаете локально, есть три разные копии репозитория: local, upstream и origin. Получите данные по удалённым репозиториям origin и upstream. Эта команда очистит кеш удаленных репозиториях без фактического изменения каких-либо из копии.

   git fetch origin
   git fetch upstream
   

   Этот рабочий процесс отличается от того, который определен в сообществе GitHub. Здесь вам не нужно объединять вашу локальную копию master из репозитория upstream/master, прежде чем отправлять изменения в вашу копию. Этот шаг не требуется в kubernetes/website, потому что ваша ветка базируется на репозитории upstream.

2. Создайте локальную рабочую ветку из наиболее подходящей ветки upstream-репозитория: upstream/dev-1.xx для разработчиков в конкретных версиях или upstream/master для всех остальных участников. В этом примере предполагается, что вы будете работать с ветки upstream/master. Так как ваша локальная ветка master не настроена для отслеживания изменений с upstream/master на предыдущем шаге, поэтому вам нужно явно создать свою ветку от upstream/master.

   git checkout -b <my_new_branch> upstream/master
   

3. После переключения на новую ветку можно начать в ней работать в текстовом редакторе. Используйте команду git status , чтобы посмотреть измененные файлы.

4. Когда вы закончите работу, зафиксируйте изменения. Сначала выполните команду git status, чтобы увидеть, какие изменения будут добавлены в коммит. В выводе этой команды есть две важные секции: Changes staged for commit и Changes not staged for commit. Файлы в последней секции, рядом с которыми есть надпись modified или untracked, необходимо добавить, если вы хотите, чтобы они попали в коммит. Для каждого файла, который нужно добавить, используйте команду git add.

   git add example-file.md
   

   Когда все изменённые файлы добавлены, зафиксируйте их с помощью команды git commit:

   git commit -m "Your commit message"
   

   Заметка: В сообщении коммита не указывайте идентификатор или URL-адрес ишью или пулреквеста на GitHub. Если вы это сделаете, на странице ишью или пулреквеста будет показана информация о коммите всякий раз, когда коммит будет появляться в новой Git-ветке. Вы можете сослаться на ишью и пулреквесты позже на сайте GitHub.

5. При желании вы можете посмотреть, как ваши изменения будут выглядеть на сайте, если запустите сайт на вашей машине с помощью команды hugo. Посмотрите раздел Просмотр ваших изменений локально. Кроме этого, вы увидите свои изменения после создания пулреквеста.

6. Перед тем, как открывать пулреквест с вашими изменениями вам для начала отправить в ветку удаленного репозитория, чем в данном случае является origin.

   git push origin <my_new_branch>
   

   Технически вы можете не указать имя ветки в команде push, но корректное выполнение команды в таком случае зависит от используемой версии Git. Результаты будут более ожидаемыми, если вы напишите название ветки.

7. Перейдите по адресу https://github.com/kubernetes/website в вашем браузере. GitHub определит и укажет вам, что вы загрузили новую ветку в свою копию, и поэтому предложит создать пулреквест. Заполните шаблон запроса.

   • Название должно быть не длиннее 50 символов и отражать краткий итог изменений.
   • Подробное описание должно содержать больше информации про исправление, включая строку типа Fixes #12345, если пулреквест решает проблему на GitHub. Это приведет к автоматическому закрытию указанной ишью после принятия пулреквеста.
   • Вы можете добавить метки или другие метаданные и назначить рецензентов. Смотрите страницу Сортировка и классификация ишью.

   Нажмите на кнопку Create pull request.

8. Начнут выполняться автоматические тесты в зависимости от состояния сайта с вашими изменениями. Если какой-либо из тестов завершился неудачно, нажмите на ссылку Details для получения дополнительной информации. Если тест Netlify прошёл успешно, по ссылке Details вы можете найти предварительную версию сайта Kubernetes с внесенными вашими изменениями. Именно на ней рецензенты будут проверять ваши изменения.

9. Если вам необходимо что-то дополнить, изменить пулреквест в соответствии с выполненной проверкой, либо изменить текст коммита, вы можете использовать команду ниже.

   git commit -a --amend
   

   • -a: зафиксировать все изменения
   • --amend: изменить предыдущий коммит вместо создания нового

   Откроется текстовый редактор, чтобы вы могли отредактировать сообщение коммита, если это нужно.

   Если вы используете git commit -m, как в шаге 4, вы сделаете новый коммит, а не измените исходный (предыдущий) коммит. Создание нового коммита означает, что вам нужно объединить свои коммиты до того, прежде чем пулреквест может быть объединен.

   Следуйте инструкциям в шаге 6, чтобы отправить новый коммит в удаленный репозиторий. После этого новое изменение отобразится в пулреквесте, а дальше снова запустятся тесты, а также произойдет новая сборка предварительной версии сайта на Netlify с последними изменениями.

10. Если рецензент изменяет файлы в вашем пулреквесте, вам нужно получить новые изменения в вашей локальной копии, до того как снова начать что-то делать. Используйте команды ниже, чтобы обновить свою ветку (предполагается, что ветка уже получена с вашей копии репозитория).

    git fetch origin
    git rebase origin/<your-branch-name>
    

    После перебазирования вам нужно добавить флаг --force-with-lease, чтобы принудительно отправить новые изменения в ветке на вашу копию.

    git push --force-with-lease origin <your-branch-name>
    

11. Может возникнуть конфликт, если кто-то, как и вы, изменил те же части файла в ветке, из которой была создана ваша ветка. Если пулреквест показывает, что есть конфликты, которые нужно разрешить, вы можете сделать это либо на сайте GitHub, либо исправить их локально.

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

    Затем обновите репозиторий upstream и перебазируйте вашу ветку на ту, с которой она была создана, в данном случае это upstream/master.

    git fetch upstream
    git rebase upstream/master
    

    Если есть конфликты, которые Git не может разрешить автоматически, вы можете увидеть конфликтующие файлы с помощью команды git status. Отредактируйте каждый конфликтующий файл: найдите в них маркеры конфликта >>>, <<< и ===. Разрешение конфликта происходит путём удаления указанных маркеров конфликта. После это нужно добавить измененные файлы с помощью команды git add <filename> и продолжить перебазирование ветки, используя команду git rebase --continue. Когда всё зафиксировано в репозитории и не осталось неразрешенных конфликтов, команда git status покажет, что вы вышли из состояния перебазирования ветки и нет изменений для фиксации. На этом этапе вам осталось принудительно отправить ветку в свою копию репозитория, после чего на странице пулреквеста не должны быть конфликты.

12. Если у вашего PR отображаются несколько сделанных коммитов после редактирования предыдущих коммитов, вам следует объединить эти несколько коммитов в один коммит, чтобы PR мог быть объединен. Проверить количество коммитов можно на вкладке Commits на странице PR или выполнив git log в терминале. Объединение коммитов (Squashing commits) — это одна из форм перебазирования.

```bash
git rebase -i HEAD~<number_of_commits>
```

Ключ `-i` сообщает git, что вы хотите сделать перебазирование в интерактивном режиме. В этом режиме вы сможете выбрать для git, какие коммиты нужно объединить в один. Например, в вашей ветке есть 3 коммита:

```
12345 commit 4 (2 minutes ago)
6789d commit 3 (30 minutes ago)
456df commit 2 (1 day ago)
```

Вам нужно объединить свои последние три коммита в один-единственный.

```
git rebase -i HEAD~3
```

Эта команда откроет редактор с таким содержимым:

```
pick 456df commit 2
pick 6789d commit 3
pick 12345 commit 4
```

Измените `pick` на `squash` у тех коммитов, которые вы хотите объединить, и проверьте, что коммит с выбранным `pick` находится сверху.

```
pick 456df commit 2
squash 6789d commit 3
squash 12345 commit 4
```

Сохраните и закройте редактор. Затем отправьте объединённый коммит в репозитории с помощью команды `git push --force-with-lease origin <branch_name>`.

Если у вас возникли проблемы с разрешением конфликтов или вы долго не можете что-то разрешить, что связано с вашим пулреквестом, обратитесь за помощью в Slack-канал #sig-docs или в список рассылки kubernetes-sig-docs.

Просмотр изменений локально

• Hugo в контейнере
• Hugo на локальном компьютере

Сортировка и классификация ишью

Люди в SIG Docs отвечают только за сортировку и классификацию ишью, связанных с документацией. Вопросы и проблемы общего характера также хранятся в репозитории kubernetes/website.

Что вы делаете, когда сортируете ишью:

• Проверить ишью
  • Убедитесь, что ишью связана с документацией сайта. Некоторые заявки можно быстро закрыть, ответив на вопрос или указав автору на ресурс. Подробности смотрите в разделе Заявки с помощью или отчёты об ошибке в коде.
  • Рассмотрите, насколько обоснованной является заявка. Добавьте метку triage/needs-information, если в ишью описано мало подробностей, чтобы ее можно было начать решать, либо если шаблон был неправильно заполнен. Закройте заявку, если она имеет метки lifecycle/stale и triage/needs-information.
• Добавьте метку с приоритетом (см. руководство по сортировке заявок, где подробно определены метки)
  • priority/critical-urgent - заниматься нужно прямо сейчас
  • priority/important-soon - нужно выполнить в течение 3 months
  • priority/important-longterm - нужно сделать в течение 6 months
  • priority/backlog - решение можно быть отложено на неопределенный срок indefinitely; самый низкий приоритет; делать, когда будут свободны ресурсы
  • priority/awaiting-more-evidence - указание, что это возможно хорошая задача, которую нужно иметь на виду
• Дополнительно вы можете добавить метку help или good first issue, если определенная заявка может быть решена человеком, мало знакомым с Kubernetes или SIG Docs. В качестве руководства обратитесь к файлу Help Wanted and Good First Issue Labels.
• При желании примите сами участие в ишью и отправьте PR для ее решения (в частности если она может быстро разрешена или вы ранее выполняли нечто подобное).

С помощью этого фильтра можно найти заявки, которые необходимо отсортировать.

Если у вас есть вопросы о про сортировку, спросите в Slack-канале #sig-docs или в списке рассылки kubernetes-sig-docs.

Добавление и удаление меток

Для добавления метки нужен комментарий, содержащий что-то вроде /<label-to-add> или /<label-category> <label-to-add>. Метка уже должна быть создана в репозитории. Если вы попытаетесь добавить несуществующую метку, команда проигнорируется.

Примеры:

• /triage needs-information
• /priority important-soon
• /language ja
• /help
• /good-first-issue
• /lifecycle frozen

Для удаления метки нужен комментарий с /remove-<label-to-remove> или /remove-<label-category> <label-to-remove>.

Примеры:

• /remove-triage needs-information
• /remove-priority important-soon
• /remove-language ja
• /remove-help
• /remove-good-first-issue
• /remove-lifecycle frozen

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

Дополнительные сведения о метках

• Ишью может иметь несколько ярлыков.
• Некоторые метки в своём имени содержат слеш для группировки, это своего рода "подметки". Например, существует множество меток sig/, например, sig/cli и sig/api-machinery (полный список).
• Некоторые метки добавляются автоматически, в зависимости от метаданных файлов из ишью, либо от используемых в комментариях команд со слешем, а также от указанной информации в описании.
• Новые метки могут добавляться вручную человеком, который сортировкой ишью (либо тем, кто создает ишью).
  • kind/bug, kind/feature и kind/documentation: баг (bug) — это проблема в текущем контенте или в функциональности, а возможность (feature) — запрос на добавление нового контента или функциональности. Метка kind/documentation используется редко.
  • Метки language/ja, language/ko и похожие языковые метки добавляются, если ишью относится к локализованному контенту.

Жизненный цикл ишью

Ишью обычно открываются и закрываются в течение относительно короткого промежутка времени. Однако иногда решение заявки после ее создания может и не быть. Иногда ишью может оставаться открытой гораздо дольше, чем 90 дней.

lifecycle/stale: после 90 дней бездействия ишью автоматически помечается как устаревшая (stale). Такая заявка будет автоматически закрыта, если эта метка не будет удалена с помощью команды /remove-lifecycle stale.

lifecycle/frozen: заявка с данной меткой не будет считаться устаревшей после 90 дней отсутствия активности. Пользователь вручную добавляет эту метку к заявкам, которые должны оставаться открытыми значительно дольше 90 дней, например, у ишью с меткой priority/important-longterm.

Обработка специальных типов ишью

Мы встречаем перечисленные ниже типы заявкой достаточно часто, поэтому расписали, как их обрабатывать.

Дублирование заявок

Если для какой-нибудь проблемы есть одна или несколько открытых заявок, решение этой проблемы должно быть вынесено в одну заявку. Вам нужно решить, какую заявку оставить открытой (либо вовсе открыть новую ишью), перенести всю соответствующую информацию и указать связанные заявки. Затем для всех остальных похожих заявок добавьте метку с triage/duplicate и закройте их. Наличие только одной-единственной заявки поможет уменьшить путаницу и избежать дублирования работы над одной и той же проблемой.

Заявки про неработающие ссылки

В зависимости от того, где сообщается о неработающей ссылке, для решения этой проблемы требуются различные действия. Неработающие ссылки в API и документации Kubectl — это заявки, связанные с автоматизацией и поэтому их нужно отмечать меткой /priority critical-urgent, пока проблема не будет полностью проанализирована. Все остальные неработающие ссылки — это ишью, которым нужно заниматься вручную, поэтому им нужно добавить метку /priority important-longterm.

Заявки, связанные с блогом

Записи в блоге Kubernetes будут терять актуальность со временем, поэтому мы поддерживаем записи, опубликованные в течение года. Если заявка сообщает о проблеме в записи блога, которой более одного года, ее следует закрыть без какого-либо исправления.

Заявки с помощью или отчёты об ошибке в коде

Некоторые открытые заявки — это проблемы с основным кодом или просьбы с помощью, когда что-то (например, учебное руководство) не работает. Для заявок, не имеющих отношение к документации, закройте её, проставив метку kind/support и добавив комментарий с ресурсами, где можно найти помощь (Slack, Stack Overflow) и при необходимости укажите, где нужно открыть заявку, чтобы сообщить об ошибке в функциональности (вероятно, репозиторий kubernetes/kubernetes отлично подойдет для этого).

Пример ответа на запрос о помощи:

This issue sounds more like a request for support and less
like an issue specifically for docs. I encourage you to bring
your question to the `#kubernetes-users` channel in
[Kubernetes slack](http://slack.k8s.io/). You can also search
resources like
[Stack Overflow](http://stackoverflow.com/questions/tagged/kubernetes)
for answers to similar questions.

You can also open issues for Kubernetes functionality in
 https://github.com/kubernetes/kubernetes.

If this is a documentation issue, please re-open this issue.

Пример ответа на сообщение об ошибке в коде:

This sounds more like an issue with the code than an issue with
the documentation. Please open an issue at
https://github.com/kubernetes/kubernetes/issues.

If this is a documentation issue, please re-open this issue.

Добавление документации для новой функциональности

Каждый мажорный выпуск Kubernetes несет в себе новую функциональность, для большей части из которой нужно написать хоть краткую документацию, чтобы показать людям, как её использовать.

Зачастую SIG-группа, ответственная за новую функциональность, представляют черновик документацию в виде пулреквеста в соответствующую ветку выпуска в репозитории kubernetes/website, а кто-то из команды SIG Docs могут сделать вычитку или отредактировать черновик напрямую.

Поиск информации о новой функциональности

Чтобы узнать о будущей функциональности, посетите еженедельную встречу sig-release (см. страницу Сообщество, чтобы быть в курсе предстоящих собраний) и отслеживайте документацию к новому релизу в репозитории kubernetes/sig-release. Каждый выпуск имеет поддиректорию в директории /sig-release/tree/master/releases/. Каждая директорию содержит график выхода новой версии, черновик с примечаниями к выпуску, а также документ, в котором перечислена команда, занимающаяся новым выпуском.

• График выпуска содержит ссылки на все другие документы, встречи, протоколы собраний и этапы, связанные с выпуском. Он также содержит информацию о целях и сроках выпуска, а также о любых специальных процессах, используемых этом выпуске. В нижней части документа определены несколько терминов, связанных с выпуском.

  Этот документ также содержит ссылку на лист отслеживания функциональности — это "официальный" способ узнать про новую функциональность, запланированной в выпуске.

• В документе команды выпуска указано, кто какую роль занимает. Если непонятно, с кем можно поговорить об определенной функциональности или вы хотите что-то спросить, то либо посетите встречу по этому выпуску, чтобы задать свой вопрос, либо обратитесь к руководителю.

• Черновик примечаний к выпуску — хорошая отправная точка, где можно узнать чуть больше о конкретной функциональности, изменениях, устаревших возможностях и в целом что-то ещё о выпуске. Содержимое может обновляться до конца цикла выпуска, поэтому будьте начеку.

Лист отслеживания функциональности

В списке отслеживания функциональности для данного выпуска Kubernetes перечислена вся функциональность, запланированная для выпуска. Каждая строка содержит название возможности, ссылку на основную заявку GitHub, уровень стабильности (Alpha, Beta или Stable), группу SIG и ответственного лица за её реализацию, информацию про документацию, черновик примечания для выпуска, а также указание, была ли функциональность уже принята. Имейте в виду следующее:

• Функциональность в состоянии Beta и Stable обычно имеет более высокий приоритет по сравнению с версией Alpha.
• Трудно протестировать (и, следовательно, написать документацию) функциональности, которая не ещё принята или,по крайней мере, считается полнофункциональной в своем PR.
• Определение, нужна ли документировать функциональности, производится вручную, и даже если у функциональности нет метки, что ей нужна документация, это не означает, это действительно так.

Документирование функциональности

Как отмечалось выше, черновик документации для новой функциональности обычно предлагается SIG-группой, ответственной за реализацию новой функциональности. Это означает, вы в данном случае будете больше наблюдающим (куратором) в данной функциональности, нежели чем полноценным автором документации для неё.

После того, как вы выбрали функциональность для документирования/наблюдения, заявите об этом в Slack-канале #sig-docs, на еженедельной встрече sig-docs или напрямую в PR, отправленном SIG. Если вам дали добро, вы можете редактировать PR, используя один из способов, указанных в разделе Редактирование PR другого человека.

Если вам нужно написать новую тему, полезны следующие ссылки:

• Написание новых тем
• Использование шаблонов страниц
• Руководство по оформлению документации
• Руководство по содержанию документации

Члены SIG, участвующие в документировании новой функциональности

Если вы участник SIG-группы, кто разрабатывает новую функциональность для Kubernetes, вам нужно работать с документацией SIG, чтобы убедиться, что на момент новой версии написана документация для этой функциональности. Проверьте электронную таблицу с отслеживанием функциональности или присоединитесь в Slack-канал #sig-release, чтобы узнать информацию о сроках выхода. Некоторые крайние сроки касательно документации:

• Docs deadline - Open placeholder PRs: откройте пулреквест в ветку release-X.Y в репозитории kubernetes/website с небольшим коммитом, который вы позже измените. Используйте команду Prow /milestone X.Y, чтобы назначить PR соответствующему этапу. Это уведомляет человека, который занимается документацией и ответственный за этот выпуск, что выходит документация для новой функциональности. Если функциональность не нуждается в каких-либо изменениях документации, убедитесь, что команда sig-release знает об этом, написав им сообщение в Slack-канале #sig-release. Если для функциональности нужна документация, но PR для этого ещё не создан, функциональность может быть удалена из этапа.
• Docs deadline - PRs ready for review: теперь ваш PR должен содержать первый черновик документации для вашей функциональности. Не беспокойтесь о форматировании или всяких улучшениях. Просто опишите, что делает эта функциональность и как ее использовать. Участник из группы документации, управляющий выпуском новой версии, будет работать вместе с вами, чтобы подготовить контент для публикации. Если вашей функциональности нужна документация и первого черновика с документацией до сих пор нет, эта функциональность может быть удалена из этапа.
• Docs complete - All PRs reviewed and ready to merge: если ваш PR еще не был объединен в ветку release-X.Y к заданному крайнему сроку, обратитесь за помощью к человеку, ответственному за выпуск новой версии. Если вашей функциональности требуется документация, но она ещё не сделана, функциональность может быть удалена из этапа.

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

Участие к других репозиториях

В проекте Kubernetes более 50 самостоятельных репозиториев. Многие из этих репозиториев хранят код или контент, который можно рассматривать как документацию, например, справочный текст для пользователях, сообщения об ошибках, пользовательский текст в справочниках API или даже комментарии кода.

Если вы видите текст и не знаете, откуда он берётся, вы можете использовать поиск GitHub по репозиториям организации Kubernetes, чтобы выяснить, где встречается этот текст. Это поможет вам определиться с тем, куда создать заявку или PR.

У каждого репозитория могут быть определены собственные процессы и правила. До того как открыть проблему или отправить PR, изучите файлы README.md, CONTRIBUTING.md и code-of-conduct.md в репозитории, если они есть.

Большинство репозиториев используют шаблоны для заявок и PR. Просмотрите некоторые открытые заявки и PR, чтобы понять, как устроена работа. Обязательно как можно более подробно заполните шаблоны при открытии заявок или PR.

Локализация контента

Английский является основным языком документации Kubernetes, однако мы хотим, чтобы у людей была возможность читать документацию на своём родном языке. Если вам комфортно писать на другом языке, особенно в теме программного обеспечения, вы можете помочь перевести документацию Kubernetes или помочь с существующим переводом. Посмотрите страницу Локализация и задайте вопрос в списке рассылки kubernetes-sig-docs или в канале #sig-docs на Slack, если вы хотите помочь.

Работа с локализованным контентом

Старайтесь соблюдать эти рекомендации по работе с переведенным контентом:

• В PR должны быть изменения касающиеся только одного языка.

  В каждом языке есть собственные рецензенты и утверждающие.

• Рецензентам: убедитесь, что PR содержат изменения только на одном языке.

  Если PR изменяет файлы на нескольких языках, попросите автора открыть отдельные PR для каждого языка.

Что дальше

Если вы хорошо осознали все задачи, затронутые в этом разделе, и хотите более тесно работать с командой документации Kubernetes, переходите к изучению руководства для опытного участника.

6.3 - Участие для опытных

На этой странице предполагается, что вы изучили темы Участие для начинающих и Участие для опытных и теперь хотите узнать ещё больше про то, как можно помочь проекту. Для решения некоторых задач вам потребуется использовать Git из командной строки и прочие другие инструменты.

Дежурный по PR на неделю

Утверждающие группы SIG Docs регулярно по очереди становятся дежурными по PR в репозитории и поэтому участвуют в графике ротации PR-дежурного на неделю.

В обязанности дежурного по PR входят:

• Ежедневно проверять открытые пулреквесты для контроля качества и соблюдения рекомендаций по оформлению и содержимому.
  • В первую очередь просматривайте самые маленькие пулреквесты (size/XS), и только потом беритесь за самые большие (size/XXL).
  • Проверяйте столько пулреквестов, сколько сможете.
• Проследить, что CLA подписан каждым участником.
  • Помогайте новым участникам подписать CLA.
  • Используйте этот скрипт, чтобы автоматически напомнить участникам, не подписавшим CLA, чтобы они подписали CLA.
• Оставить свое мнение о предложенных изменениях и поспособствовать в проведении технического обзора от членов других SIG-групп.
  • Предложить исправления для измененного контента в PR.
  • Если вы хотите убедиться в правильности контента, прокомментируйте PR и задайте уточняющие вопросы.
  • Добавьте нужны метки с sig/.
  • Если нужно, то назначьте рецензентов из секции reviewers: в фронтальной части файла.
  • Добавьте метки Docs Review и Tech Review для установки статуса проверки PR.
  • Добавьте метку Needs Doc Review или Needs Tech Review для пулреквестов, которые ещё не были проверены.
  • Добавьте метку Doc Review: Open Issues или Tech Review: Open Issues для пулреквестов, которые были проверены и требуют дополнительную информацию и выполнение действия перед слиянием.
  • Добавьте метки /lgtm и /approve для пулреквестов, которые могут быть приняты.
• Объедините пулреквесты, если они готовы, либо закройте те, которые не могут быть приняты.
• Ежедневно отсортируйте и пометьте новые заявки. Обратитесь к странице Участие для опытных для получения информации по использование метаданных SIG Docs.

Полезные ссылки на GitHub для дежурных

Следующие ссылки помогут при дежурстве. После обработки заявок по трём первым ссылкам, как правило, список пулреквестов для проверки сократится. По указанным ссылкам вы найдете PR только в английскую версию, предназначенные для слияния в ветку master (кроме последней ссылки).

• Нет CLA, нет права на слияние: напомните участнику подписать CLA. Если об этом уже напомнил и бот, и человек, то закройте PR и напишите автору, что он может открыть свой PR после подписания CLA. Не проверяйте PR, если их авторы не подписали CLA!
• Требуется LGTM: если нужен проверка с технической точки зрения, попросите её провести одного из рецензентов, который предложил бот. Если требуется просмотр пулреквест со стороны группы документации или вычитка, то предложите изменения, либо сами измените PR, чтобы ускорить процесс принятия пулреквеста.
• Имеет LGTM, нужно одобрение со стороны группы документации: выясните, нужно ли внести какие-либо дополнительные изменения или обновления, чтобы принять PR. Если по вашему мнению PR готов к слияния, оставьте комментарий с текстом /approve.
• Быстрые результаты: если маленький PR направлен в основную ветку и не имеет условий для объединения. (поменяйте "XS" в метке с размером при работе с другими пулреквестами [XS, S, M, L, XL, XXL]).
• Вне основной ветки: если PR отправлен в ветку dev-, значит он предназначается для будущего выпуска. Убедитесь, что release meister знает об этом, добавив комментарий с /assign @<meister's_github-username>. Если он направлен в старую ветку, помогите автору PR изменить на более подходящую ветку.

Когда закрывать пулреквесты

Обзоры и одобрения — это только один из способов, позволяющих держать список PR коротким и актуальным. Закрытие пулреквестов — альтернативный метод для этого.

• Можете закрыть любой PR, если CLA-соглашение не было подписано в течение двух недель. Авторы PR могут повторно открыть PR после подписания CLA, так что это безопасный способ убедиться, что ничто не будет объединено без подписанного CLA.

• Закройте любой PR, если автор не отреагировал на комментарии или проверки в течение 2 или более недель.

Не бойтесь закрывать пулреквесты. Участники с лёгкостью открыть и возобновить незаконченную работу. Зачастую уведомление о закрытии стимулировать автора возобновить и закончить свой вклад.

Чтобы закрыть пулреквест, оставьте комментарий /close в PR.

Заметка: Бот fejta-bot автоматически помечает заявки как устаревшие после 90 дней отсутствия активности, а затем закрывает их после ещё 30 дней простоя, когда они становятся тухлыми. Дежурные по PR должны закрывать заявки после 14-30 дней бездействия.

Внесение улучшений

Члены SIG Docs могут предлагать улучшения.

После того, как вы давно начали работать над документацией Kubernetes, у наверняка появились какие-нибудь идеи по улучшению руководства по оформлению, руководства по оформлению, набору инструментов, который используется для создания документации, стилизации сайта, процессов проверки и объединения пулреквестов. Для максимальной открытости подобные типы предложений по улучшению должны обсуждаться на встречи SIG Docs или в списке рассылки kubernetes-sig-docs. Помимо этого, это поможет разъяснить, как всё устроено в данный момент, и объяснить, почему так было принято, прежде чем предлагать радикальные изменения. Самый быстрый способ узнать ответы на вопросы о том, как в настоящее время работает документация, это задать их на канале #sig-docs Slack на kubernetes.slack.com.

Когда обсуждение состоялось, а SIG-группа согласилась с желаемым результатом, вы можете работать над предлагаемыми изменениями наиболее приемлемым способом. Например, обновление руководства по оформлению или функциональности сайта может включать открытие пулреквеста, а изменение, связанное с тестированием документации, может предполагать взаимодействие с sig-testing.

Координация документации по выпуску Kubernetes

Утверждающие SIG Docs могут координировать документацию для выпуска Kubernetes.

Каждый выпуск Kubernetes координируется командой людей, участвующих в специальной группе (Special Interest Group, SIG) sig-release. Другие члены команды в данном выпуске включают в себя общего руководителя выпуском, а также представителей sig-pm, sig-testing и др. Чтобы узнать больше о процессах выпуска версий Kubernetes, обратитесь к https://github.com/kubernetes/sig-release.

Представитель SIG Docs для данного выпуска координирует следующие задачи:

• Мониторинг электронной таблицы с отслеживанием функциональности на наличие новых или измененных возможностей, затрагивают документацию. Если документация для определенной функциональности не будет готова к выпуску, возможно, она не попадет в выпуск.
• Регулярное посещение встречи sig-release и обновлять информацию о статусе документации в выпуске.
• Проверка и вычитка документации по функциональности, подготовленной SIG-группой, ответственной за реализацию этой функциональности.
• Объединение связанных с выпуском пулреквестов и поддержка Git-ветки выпуска.
• Консультируйте других участников SIG Docs, которые хотят научиться выполнять эту роль в будущем. Это называется сопровождение (shadowing).
• Публикация изменений в документации, связанные с выпуском при размещении артефактов.

Координация выпуска обычно занимает 3-4 месяца, а обязанности распределяются между утверждающими SIG Docs.

Амбассадор нового участника

Утверждающие SIG Docs могут выступать в качестве амбассадоров новых участников.

Амбассадоры новых участников работают бок о бок, чтобы поприветствовать новых участников SIG Docs, предлагать PR новым участникам и консультировать новых участников в их собственных PR.

Обязанности амбассадоров новых участников включают в себя:

• Отвечать на вопросы новых участников на Slack-канале Kubernetes #sig-docs.
• Совместно работать с дежурным по PR, чтобы определять заявки, которые подойдут для решения новыми участниками.
• Консультировать новых участников в их PR.
• Помогать новых участникам в создании более сложных PR, чтобы они могли стать членами Kubernetes.
• Оказывать содействие участникам на их пути становления членом в Kubernetes.

Текущие амбассадоры новых участников объявляются на каждом собрании SIG Docs и на канале #sig-docs в Kubernetes.

Поддержка нового участника

Рецензенты SIG Docs могут содействовать новым участникам в членстве организации.

Если участник сделал 5 значительных пулреквестов в один или несколько репозиториев Kubernetes, он имеет право на членство в организации Kubernetes. Членство участника должно быть поддержано двумя спонсорами, которые уже являются рецензентами.

Новые участники документации могут найти спонсоров в канале #sig-docs в в Slack Kubernetes или в списке рассылки SIG Docs. Если вы осознали полезность работы автора заявки на членство, вы добровольно можете поддержать (спонсировать) его. Когда они подадут заявку на членство, отреагируйте на заявку "+1" и напишите подробный комментарий о том, почему вы считаете, что кандидат отлично вписывается в члены организации Kubernetes.

Сопредседатель SIG

Утверждающие SIG Docs могут быть сопредседателями SIG Docs.

Требования

Сопредседатели должны соответствовать следующим требованиям:

• Быть утверждающим SIG Docs не меньше 6 месяцев
• Руководить выпуском документации Kubernetes или сопровождать два выпуска
• Понимание рабочих процессов и инструментов SIG Docs: git, Hugo, локализация, блог
• Понимать, как другие SIG-группы и репозитории Kubernetes влияют на рабочий процесс SIG Docs, включая: команды в k/org, процессы в k/community, плагины в k/test-infra и роль SIG Architecture.
• Уделять не менее 5 часов в неделю (но зачастую больше) в течение как минимум 6 месяцев для выполнения обязанностей.

Обязанности

Роль сопредседателя посвящена в основном одной из задач: сопредседатели управляют процессом и политикой, планируют и проводят собрания, назначают дежурных по PR и, как правило, делают то, что никто больше не хочет делать, для увеличения количества участников.

Обязанности включают в себя:

• Сосредоточить группу SIG Docs на достижении максимального счастья для разработчиков через отличную документацию
• Быть примером соблюдения [норм поведения сообщества]https://github.com/cncf/foundation/blob/master/code-of-conduct.md) и контролировать их выполнение членами SIG
• Изучение и внедрение передовых практик для SIG-группы, обновляя рекомендации по участию
• Планирование и проведение встреч SIG: еженедельные обновления информации, ежеквартальные ретроспективные/плановые совещания и многое другое
• Планирование и проведение спринтов по документации на мероприятиях KubeCon и других конференциях
• Набирать персонал и выступать в поддержку CNCF и его платиновых партнеров, включая Google, Oracle, Azure, IBM и Huawei.
• Поддерживать нормальную работу SIG

Проведение продуктивных встреч

Для планирования и проведения результативных встреч мы составили рекомендации, которые показывают и объясняют, как лучше всего их подготовить.

Соблюдайте нормы поведения сообщества:

• Привлекайте самый широкий круг участников к дискуссии и уважительно общайтесь между собой, стараясь никого не обидеть.

Сформулируйте четкую повестку дня:

• Определите конкретную цель встречи
• Опубликуйте программу дня заранее

Для еженедельных встреч скопируйте примечания из предыдущей недели в раздел "Past meetings".

Работайте вместе для создания точных примечания:

• Запишите обсуждение встречи
• Подумайте над тем, чтобы делегировать роль стенографист кому-нибудь другому

Определяйте решения по пунктам повестки четко и точно:

• Записывайте решения по пунктам, кто будет ими заниматься и ожидаемую дату завершения

Руководите обсуждением, когда это необходимо:

• Если обсуждение выходит за пределы повестки дня, снова обратите внимание участников на обсуждаемую тему
• Найдите место для различных стилей ведения обсуждения, не отвлекаясь от темы обсуждения и уважая время людей

Уважайте время людей:

• Начинайте и заканчивайте встречи своевременно

Используйте Zoom эффективно:

• Ознакомьтесь с рекомендациями Zoom для Kubernetes
• Попробуйте попроситься быть ведущим в самом начале встречи, введя ключ ведущего

Запись встреч на Zoom

Когда вам потребуется начать запись, нажмите пункт с надписью Record to Cloud.

Если нужно остановить запись, нажмите на кнопку Stop.

Запись автоматически загрузится на YouTube.

6.4 - Обзор оформления документации

Темы в этом разделе содержат рекомендации по написанию, форматированию и организации контента, а также охватывают настройку Hugo в контексте документации Kubernetes.

6.4.1 - Руководство по оформлению документации

На этой странице вы найдёте рекомендации по оформлению написания документации Kubernetes. Это рекомендации, а не правила. Используйте здравый смысл и не стесняйтесь предлагать изменения в этот документ в виде пулреквеста.

Для получения подробной информации о создании нового контента в документацию Kubernetes посмотрите руководство по контенту документации, а также следуйте инструкциям по использованию шаблонов страниц и открытию пулревеста в документацию.

Заметка: В документации Kubernetes используется Blackfriday Markdown Renderer вместе с несколькими макрокодами Hugo для добавления поддержки записей глоссария, вкладок и отображения состояний функциональностей.

Язык

Документация Kubernetes была переведена на несколько языков (см. README-файлы локализаций).

Процесс локализации документации на другие языки описан в соответствующей странице по локализации.

Правила форматирования документации

Используйте верблюжью нотацию для написания объектов API

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

Не разделяйте имя объекта API на отдельные слова. Например, пишите PodTemplateList, а не Pod Template List.

Указывая имена API-объектов, не добавляйте к ним слово "объект", за исключением случаев, когда это только ухудшает читаемость.

Используйте угловые скобки для заполнителей

Используйте угловые скобки для заполнителей. Сообщите читателю, что означает заполнитель.

1. Отобразить информацию о Pod:

    kubectl describe pod <pod-name> -n <namespace>
   

   Если пространство имён пода равняется default, вы можете опустить параметр '-n'.

Используйте полужирное начертание для элементов пользовательского интерфейса

Используйте курсивное начертание для определения или включения новых терминов

Оформляйте как код имена файлов, директории и пути

Используйте международные правила для пунктуации внутри кавычек

Форматирование с использованием однострочного кода

Используйте оформление кода для встроенного кода и команд

Для однострочного (встроенного) блока кода в HTML-документе используйте тег <code>. В файле Markdown используйте обратную кавычку (`).

Заметка: На сайте включена подсветка синтаксиса для примеров кода, хотя указывать язык необязательно. Подсветка синтаксиса в блоке кода должна соответствовать рекомендациям по контрастности.

Имена полей объектов и пространства имён оформляйте как код

Имена компонентов и командного инструмента оформляйте как код

Начинайте предложение с имени инструмента или компонента

Используйте общее описание вместо имени компонента

Cтроковые и целочисленные значения полей пишите в обычном стиле

Для значений полей типа string или integer используйте обычный стиль без кавычек.

Форматирование фрагментов кода

Не добавляйте символ приглашения командной строки

Отделяйте команды от вывода

Убедитесь, что Pod работает на выбранном вами узле:

kubectl get pods --output=wide

Вывод будет примерно таким:

NAME     READY     STATUS    RESTARTS   AGE    IP           NODE
nginx    1/1       Running   0          13s    10.200.0.4   worker0

Версионирование примеров Kubernetes

Примеры кода и примеры конфигурации, которые включают информацию о версии, должны согласовываться с относящемуся к нему тексту.

Если информация зависит от версии, необходимо определить версию Kubernetes в секции prerequisites шаблона задачи или шаблона руководства. После сохранения страницы секция prerequisites отобразится в отдельном блоке с заголовком Подготовка к работе.

Для указания версии Kubernetes для страницы задачи или руководства в фронтальную часть файла добавьте поле min-kubernetes-server-version.

Если YAML-пример определён в отдельном файле, поищите и просмотрите темы, которые ссылаются на него. Убедитесь, что темы с подключённым YAML-файлом содержат соответствующую информацию о версии. Если ни одна из тем не использует какой-либо YAML-файл подумайте над тем, чтобы удалить его вместо того, чтобы обновления.

Например, если вы пишете руководство, предназначенное для использования с версией Kubernetes 1.8, фронтальная часть вашего Markdown-файла должен выглядеть примерно так:

---
title: <your tutorial title here>
min-kubernetes-server-version: v1.8
---

В примерах кода и конфигурации не добавляйте комментарии про альтернативные версии. Убедитесь в том, чтобы в комментариях ваших примеров не содержались некорректные сведения, такие как ниже:

apiVersion: v1 # в более ранних версиях...
kind: Pod
...

Словарь Kubernetes.io

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

Макрокоды

Макрокоды Hugo помогают создавать разного рода обращений к читателю. Наша документация поддерживает три разных макрокода для этого: примечание {{< note >}}, предостережение {{< caution >}} и предупреждение {{< warning >}}.

1. Заключите текст в открывающий и закрывающий макрокод.

2. Используйте следующий синтаксис для определения стиля:

   {{< note >}}
   Вам не нужно указывать надпись; макрокод автоматически добавит её. (Примечание:, Предостережение:, и т.д.)
   {{< /note >}}
   

Результат:

Заметка: Надпись блока будет такой же, как и имя тега.

Примечание

Используйте {{< note >}} для выделения подсказки или части информации, которая может быть полезна для ознакомления.

Например:

{{< note >}}
Вы _также_ можете использовать Markdown внутри этих выносок.
{{< /note >}}

Результат:

Заметка: Вы также можете использовать Markdown внутри этих выносок.

Вы можете использовать {{< note >}} в списке:

1. Используйте макрокод примечания в списке

1. Второй пункт с добавленным блоком примечания

   {{< note >}}
   Макрокоды предупреждения, предостережения и примечания, добавленные в списки, должны содержать отступ в четыре пробела. Смотрите раздел [Распространённые проблемы с шорткодами](#распространённые-проблемы-с-шорткодами).
   {{< /note >}}

1. Третий пункт в списке

1. Четвертый пункт в списке

Результат:

1. Используйте макрокод примечания в списке

2. Второй пункт с добавленным блоком примечания

   Заметка: Макрокоды предупреждения, предостережения и примечания, добавленные в списки, должны содержать отступ в четыре пробела. Смотрите раздел Распространённые проблемы с шорткодами.

3. Третий пункт в списке

4. Четвертый пункт в списке

Предостережение

Используйте {{< caution >}}, чтобы обратить внимание к важной информации, которая поможет избежать подводных камней.

Например:

{{< caution >}}
Оформление выноски применяется только к строке, следующей после тега выше.
{{< /caution >}}

Результат:

Внимание: Оформление выноски применяется только к строке, следующей после тега выше.

Предупреждение

Используйте {{< warning >}} для обозначения предупреждающей информации или такой, которую чрезвычайно важно соблюдать.

Например:

{{< warning >}}
Острожно.
{{< /warning >}}

Результат:

Предупреждение: Острожно.

Встраиваемая среда выполнения Katacoda

С помощью этой кнопки пользователи могут запустить Minikube в своём браузере с помощью терминала Katacoda. Таким образом снижается порог входа, позволяя пользователям попробовать Minikube с помощью одного щелчка мыши, вместо того, чтобы устанавливать Minikube и Kubectl локально.

Встроенная среда выполнения сконфигурирована для выполнения команды minikube start и позволяет пользователям пройти руководство в той же самой вкладке, что и документация.

Внимание: Сессия ограничена 15 минутами.

Например:

{{< kat-button >}}

Результат:

Распространённые проблемы с шорткодами

Упорядоченные списки

Макрокоды сбросят нумерацию в нумерованных списках, если вы не добавите отступ в четыре пробела перед уведомлением и тегом.

Например:

1. Разогреть духовку до 350˚F

1. Подготовить тесто и вылить её в формочку для выпечки.
   {{< note >}}Для лучшего результата смажьте формочку.{{< /note >}}

1. Выпекать 20-25 minutes или пока тесто не зарумянится.

Результат:

1. Разогреть духовку до 350˚F

2. Подготовить тесто и вылить её в формочку для выпечки.

   Заметка: Для лучшего результата смажьте формочку.

3. Выпекать 20-25 minutes или пока тесто не зарумянится.

Выражения для вставок

Макрокоды внутри include-выражений нарушит процесс сборки. Поэтому они должны быть вставлены в родительский документ до и после вызова include. Например:

{{< note >}}
{{< include "task-tutorial-prereqs.md" >}}
{{< /note >}}

Элементы Markdown

Переносы строк

Добавляйте одну новую строку для разделения содержимого таких блоков, как заголовки, списки, изображения, многострочный код и т.д. Исключение составляют заголовки второго уровня, которые должны быть разделены двумя переводами строки. Заголовки второго уровня следуют за первым уровнем (или названием страницы). Две пустые строки помогает лучше наглядно представить общую структуру содержимого в редакторе кода.

Заголовки

Люди, просматривающие документацию, могут использовать программу чтения с экрана или другую вспомогательную технологию (Assistive technologies, AT). Программы чтения с экрана — устройства вывода, которые выводят элементы на странице по очереди. Если на странице много текста, вы можете использовать заголовки, чтобы придать странице внутреннюю структуру. Хорошая структура страницы помогает всем читателям легко перемещаться по странице или выбрать интересующие темы.

Параграфы

Ссылки

Списки

Сгруппируйте пункты в списке так, чтобы они были связаны друг с другом и следовали в определённом порядке, либо чтобы они сохраняли взаимосвязь между несколькими элементами. Когда программа чтения с экрана встречает нумерованный или неупорядоченный список, пользователю будет проинформирован, что существует группа из элементов списка. Затем пользователь может использовать клавиши-стрелки для перемещения между разными элементами в списке. Навигационные ссылки по сайту также могут быть помечены как элементы списка; в конечном счёте, все они просто группа связанных ссылок.

• Заканчивайте каждый элемент в списке точкой, если один или несколько элементов в списке являются законченными предложениями. Как правило, для согласованности либо все элементы должны быть целыми предложениями, либо ни один из них.

  Заметка: Упорядоченные списки, которые являются частью неполного вступительного предложения, могут быть написаны в нижнем регистре и оканчиваться на точку, как если бы каждый элемент был составляющей вступительного предложения.

• Используйте цифру один (1.) для упорядоченных списков.

• Используйте (+), (*) или (-) для неупорядоченных списков.

• Добавьте пустую строку после каждого списка.

• Во вложенных списках добавьте отступ в четыре пробела (например, ⋅⋅⋅⋅).

• Элементы списка могут содержать несколько абзацев. Каждый последующий абзац в элементе списка должен иметь отступ в четыре пробела или один символ табуляции.

Таблицы

Семантическая цель таблицы данных состоит в представлении данных в табличном виде. Пользователи с нормальным зрением могут бегло просмотреть таблицу, однако программа для чтения с экрана сканирует таблицу построчно. Заголовок таблицы используется для создания информативного заголовка для табличных данных. Инструменты вспомогательных технологий (Assistive technologies, AT) используют элемент заголовка HTML-таблицы, чтобы идентифицировать для пользователей, какие на странице есть таблицы.

• Добавьте подписи к таблицам с помощью соответствующих макрокодов Hugo.

Рекомендации по написанию контента

В этом разделе перечислены рекомендации для написания ясного, лаконичного и единообразного текста документации.

Используйте настоящее время

Исключение: используйте будущее или прошедшее время, если требуется передать правильный смысл.

Используйте действительный залог

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

Используйте простой и понятный язык

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

Обращайтесь к читателю на "вы"

Избегайте использования латинских фраз

Вместо латинских аббревиатур используйте соответствующие выражения на английском.

Исключение: используйте "etc." вместо "et cetera".

Ошибки, которые следует избегать

Избегайте использования "мы"

Использование "мы" в предложении может сбить с толку, так так неясно, кто под этим "мы" подразумевается (имеется ли в виду сам читатель при этом).

Избегайте жаргона и идиомы

Некоторые читатели говорят на английском как на втором языке. Избегайте жаргона и идиом, чтобы облегчить им понимание.

Избегайте выражений о будущем

Не давайте обещаний или намеков на будущее. Если вам нужно рассказать про функциональность в альфа-версии, под соответствующем заголовком напишите поясняющий текст, что информация относится к альфа-версии.

Избегайте выражений, которые могут потерять актуальность

Избегайте таких слов, как "в настоящее время" и "новый". Новая функциональность в настоящее время не будет таковой через несколько месяцев.

Что дальше

• Подробнее про написание новой темы.
• Подробнее про использование шаблонов страниц.
• Подробнее про создание пулреквеста).

6.4.2 - Руководство по содержанию документации

Эта страница содержит рекомендации по добавлению контента в документацию Kubernetes. Если у вас есть вопросы по поводу допустимого контента, обратитесь к каналу #sig-docs в Slack Kubernetes и задайте свои вопросы! Поступайте на своё усмотрение и не стесняйтесь вносить изменения в этот документ через пулреквест.

Для получения дополнительной информации о создании нового контента для документации Kubernetes следуйте инструкциям в руководстве по оформлению.

Участие в контенте

Документация Kubernetes включает содержимое из оригинального репозитория kubernetes/website. Документация Kubernetes находится в директории kubernetes/website/content/<language_code>/docs, большая часть которой относится к проекту Kubernetes. Документация Kubernetes может также включать содержимое их проектов в GitHub-организациях kubernetes и kubernetes-sigs, если у этих проектов нет собственной документации. Всегда можно ссылаться на действующие проекты kubernetes, kubernetes-sigs и (CNCF) в документации Kubernetes, но перелинковка с продуктами определённого разработчика не допускается. Проверьте списки проектов CNCF (Graduated/Incubating, Sandbox, Archived), если вы не уверены в статусе CNCF проекта