Генерация справочной документации для команд kubectl

На этой странице показано, как сгенерировать справочник для команды kubectl.

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

Требования:

  • Наличие компьютера под управлением ОС Linux или macOS.

  • Установленные следующие инструменты:

    • Python версии 3.7.x
    • Git
    • Golang версии 1.13+
    • Pip, который потребуется для установки PyYAML
    • PyYAML версии 5.1.2
    • make
    • gcc compiler/linker
    • Docker (требуется только для справочника команды kubectl)

  • В переменной окружении PATH должны прописаны пути до необходимых инструментов сборки, таких как Go и python.

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

Настройка локальных репозиториев

Создайте рабочую область и определите переменную окружения GOPATH.

mkdir -p $HOME/<workspace>

export GOPATH=$HOME/<workspace>

Загрузите локальные копии следующих репозиториев:

go get -u github.com/spf13/pflag
go get -u github.com/spf13/cobra
go get -u gopkg.in/yaml.v2
go get -u kubernetes-sigs/reference-docs

Если у вас ещё нет копии репозитория kubernetes/website, клонируйте её на свой компьютер:

git clone https://github.com/<your-username>/website $GOPATH/src/github.com/<your-username>/website

Склонируйте репозиторий kubernetes/kubernetes по пути k8s.io/kubernetes:

git clone https://github.com/kubernetes/kubernetes $GOPATH/src/k8s.io/kubernetes

Удалите пакет spf13 в $GOPATH/src/k8s.io/kubernetes/vendor/github.com.

rm -rf $GOPATH/src/k8s.io/kubernetes/vendor/github.com/spf13

В репозитории kubernetes/kubernetes использует исходный код kubectl и kustomize.

  • Определите базовую директорию вашей копии репозитория kubernetes/kubernetes. Например, если вы выполнили предыдущий шаг, чтобы получить репозиторий, вашей базовой директорией будет $GOPATH/src/k8s.io/kubernetes. В остальных командах базовая директория будет именоваться как <k8s-base>.

  • Определите базовую директорию вашей копии репозитория kubernetes/website. Например, если вы выполнили предыдущий шаг, чтобы получить репозиторий, вашей базовой директорией будет $GOPATH/src/github.com/<your-username>/website. В остальных команд базовая директория будет именоваться как <web-base>.

  • Определите базовую директорию вашей копии репозитория kubernetes-sigs/reference-docs. Например, если вы выполнили предыдущий шаг, чтобы получить репозиторий, вашей базовой директорией будет $GOPATH/src/github.com/kubernetes-sigs/reference-docs. В остальных команд базовая директория будет именоваться как <rdocs-base>.

В вашем локальном репозитории k8s.io/kubernetes переключитесь в нужную вам ветку и убедитесь, что она в актуальном состоянии. Например, если вам нужно сгенерировать документацию для Kubernetes 1.17, вы можете использовать эти команды:

cd <k8s-base>
git checkout v1.17.0
git pull https://github.com/kubernetes/kubernetes v1.17.0

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

Редактирование исходного кода kubectl

Справочная документация по команде kubectl генерируется автоматически из исходного кода kubectl. Если вы хотите изменить справочную документацию, сначала измените один или несколько комментариев в исходном коде kubectl. Сделайте изменения в локальный репозиторий kubernetes/kubernetes, а затем отправьте пулреквест в ветку master репозитория github.com/kubernetes/kubernetes.

PR 56673 — пример пулреквеста, который исправляет опечатку в исходном коде kubectl.

Отслеживайте пулреквест и по мере необходимости отвечайте на комментарии рецензента. Не забывайте отслеживать активность в пулреквест до тех пор, пока он не будет принят в ветку master репозитория kubernetes/kubernetes.

Применение вашего изменения в ветку выпуска

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

Например, предположим, что ветка master используется для разработки Kubernetes 1.10, а вам нужно бэкпортировать ваше изменение в ветку release-1.15. За инструкциями обратитесь к странице Propose a Cherry Pick.

Отслеживайте ваш пулреквест с применённым изменением до тех пор, пока он не будет объединён в ветку выпуска.

Настройка переменных для сборки

Перейдите на <rdocs-base>. В командной строке установите следующие переменные окружения.

  • K8S_ROOT со значением <k8s-base>.
  • WEB_ROOT со значением <web-base>.
  • K8S_RELEASE со значением нужной версии документации. Например, если вы хотите собрать документацию для Kubernetes версии 1.17, определите переменную окружения K8S_RELEASE со значением 1.17.

Примеры:

export WEB_ROOT=$(GOPATH)/src/github.com/<your-username>/website
export K8S_ROOT=$(GOPATH)/src/k8s.io/kubernetes
export K8S_RELEASE=1.17

Создание версионированной директории

Скрипт сборки createversiondirs создаёт версионированную директорию и копирует туда конфигурационные файлы справочника kubectl. Имя версионированной директории имеет следующий вид: v<major>_<minor>.

В директории <rdocs-base> выполнение следующий скрипт сборки:

cd <rdocs-base>
make createversiondirs

Переход в тег выпуска в k8s.io/kubernetes

В вашем локальном репозитории <k8s-base> перейдите в ветку с версией Kubernetes, для которой вы хотите получить документацию. Например, если вы хотите сгенерировать документацию для Kubernetes 1.17, перейдите в тег v1.17.0. Убедитесь, что ваша локальная ветка содержит актуальные изменения.

cd <k8s-base>
git checkout v1.17.0
git pull https://github.com/kubernetes/kubernetes v1.17.0

Выполнение кода для генерации документации

В вашей локальной директории <rdocs-base> запустите скрипт сборки copycli. Команда выполняется от пользователя root:

cd <rdocs-base>
make copycli

Команда copycli удаляет временную директорию сборки, генерирует файлы команды kubectl и копирует полученную HTML-страницу справочника команде kubectl и ресурсы в <web-base>.

Проверка сгенерированных файлов

Убедитесь в том, что перечисленные ниже два файлы были сгенерированы:

[ -e "<rdocs-base>/gen-kubectldocs/generators/build/index.html" ] && echo "index.html built" || echo "no index.html"
[ -e "<rdocs-base>/gen-kubectldocs/generators/build/navData.js" ] && echo "navData.js built" || echo "no navData.js"

Проверка скопированных файлов

Убедитесь в том, все сгенерированные файлы были скопированы в вашу директорию <web-base>:

cd <web-base>
git status

В выводе должны перечислены изменённые файлы:

static/docs/reference/generated/kubectl/kubectl-commands.html
static/docs/reference/generated/kubectl/navData.js

Также в выводе должно быть:

static/docs/reference/generated/kubectl/scroll.js
static/docs/reference/generated/kubectl/stylesheet.css
static/docs/reference/generated/kubectl/tabvisibility.js
static/docs/reference/generated/kubectl/node_modules/bootstrap/dist/css/bootstrap.min.css
static/docs/reference/generated/kubectl/node_modules/highlight.js/styles/default.css
static/docs/reference/generated/kubectl/node_modules/jquery.scrollto/jquery.scrollTo.min.js
static/docs/reference/generated/kubectl/node_modules/jquery/dist/jquery.min.js
static/docs/reference/generated/kubectl/node_modules/font-awesome/css/font-awesome.min.css

Проверка документации локально

Соберите документацию Kubernetes в вашей директории <web-base>.

cd <web-base>
make docker-serve

Посмотрите локальную предварительную версию сайта.

Добавление и фиксация изменений в kubernetes/website

Выполните команду git add и git commit для фиксации файлов.

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

Создайте пулреквест в репозиторий kubernetes/website. Отслеживайте изменения в пулреквесте и по мере необходимости отвечайте на комментарии рецензента. Не забывайте проверять пулреквест до тех пор, пока он не будет принят.

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

Что дальше

Изменено June 01, 2020 at 9:17 AM PST: add ru pages (1224efaa6f)