Це багатосторінковий друкований вигляд цього розділу. Натисність щоб друкувати.

Повернутися до звичайного перегляду сторінки.

Оновлення довідкової документації

Тематика цього розділу описує, як генерувати довідники Kubernetes.

Щоб створити довідкову документацію, ознайомтесь з наступним посібником:

1 - Швидкий старт з довідковою документацією

Ця сторінка показує, як використовувати скрипт update-imported-docs.py для генерації довідкової документації Kubernetes. Скрипт автоматизує налаштування збірки та генерує довідкову документацію для релізу.

Перш ніж ви розпочнете

Вимоги:

  • Вам потрібна машина, що працює під управлінням Linux або macOS.

  • Вам потрібно встановити ці інструменти:

  • Ваша змінна середовища PATH повинна включати необхідні інструменти для збірки, такі як бінарники Go та python.

  • Вам потрібно знати, як створити pull request до репозиторію на GitHub. Це включає створення власного форку репозиторію. Для отримання додаткової інформації дивіться Робота з локальним клоном.

Отримання репозиторію документації

Переконайтеся, що ваш форк репозиторію website синхронізований з віддаленим репозиторієм kubernetes/website на GitHub (гілка main), і клонуйте ваш форк website собі локально.

mkdir github.com
cd github.com
git clone git@github.com:<your_github_username>/website.git

Визначте базову теку вашого клону. Наприклад, якщо ви слідували попередньому кроку для отримання репозиторію, ваша базова тека — github.com/website. Наступні кроки посилаються на вашу базову теку як <web-base>.

Огляд update-imported-docs

Скрипт update-imported-docs.py розташований у теці <web-base>/update-imported-docs/.

Скрипт будує наступні довідки:

  • Довідкові сторінки компонентів та інструментів
  • Довідка по команді kubectl
  • Довідка по API Kubernetes

Скрипт update-imported-docs.py генерує довідкову документацію Kubernetes з вихідного коду Kubernetes. Скрипт створює тимчасову теку в /tmp на вашій машині та клонує потрібні репозиторії: kubernetes/kubernetes та kubernetes-sigs/reference-docs у цю теку. Скрипт встановлює вашу змінну середовища GOPATH на цю тимчасову теку. Встановлюються три додаткові змінні середовища:

  • K8S_RELEASE
  • K8S_ROOT
  • K8S_WEBROOT

Скрипт потребує два аргументи для успішного виконання:

  • YAML конфігураційний файл (reference.yml)
  • Версія релізу, наприклад: 1.17

Конфігураційний файл містить поле generate-command. Поле generate-command визначає серію інструкцій для збірки з kubernetes-sigs/reference-docs/Makefile. Змінна K8S_RELEASE визначає версію релізу.

Скрипт update-imported-docs.py виконує наступні кроки:

  1. Клонування повʼязаних репозиторіїв, зазначених у конфігураційному файлі. Для генерації довідкових документів типово клонуються kubernetes-sigs/reference-docs.
  2. Запуск команд під час клонування репозиторіїв для підготовки генератора документації та генерація HTML і Markdown файлів.
  3. Копіювання згенерованих HTML і Markdown файлів до локального клону репозиторію <web-base> за вказаними в конфігураційному файлі шляхами.
  4. Оновлення посилань команд kubectl з kubectl.md у секції в довідці по команді kubectl.

Коли згенеровані файли знаходяться у вашому локальному клоні репозиторію <web-base>, ви можете подати їх у pull request до <web-base>.

Формат конфігураційного файлу

Кожен конфігураційний файл може містити кілька репозиторіїв, які будуть імпортовані разом. За необхідності, ви можете налаштувати конфігураційний файл, редагуючи його вручну. Можна створювати нові конфігураційні файли для імпорту інших груп документів. Ось приклад YAML конфігураційного файлу:

repos:
- name: community
  remote: https://github.com/kubernetes/community.git
  branch: master
  files:
  - src: contributors/devel/README.md
    dst: docs/imported/community/devel.md
  - src: contributors/guide/README.md
    dst: docs/imported/community/guide.md

Окремі Markdown документи, імпортовані за допомогою інструмента, повинні відповідати Посібнику зі стилю документації.

Налаштування reference.yml

Відкрийте <web-base>/update-imported-docs/reference.yml для редагування. Не змінюйте вміст поля generate-command, якщо не розумієте, як команда використовується для побудови довідок. Оновлення reference.yml зазвичай не потрібне. Іноді зміни в upstream вихідному коді можуть вимагати змін у конфігураційному файлі (наприклад: залежності версій golang та зміни сторонніх бібліотек). Якщо ви стикаєтеся з проблемами збірки, зверніться до команди SIG-Docs у #sig-docs Kubernetes Slack.

У reference.yml, files містить список полів src та dst. Поле src містить розташування згенерованого Markdown файлу у теці збірки kubernetes-sigs/reference-docs, а поле dst визначає, куди скопіювати цей файл у клонованому репозиторії kubernetes/website. Наприклад:

repos:
- name: reference-docs
  remote: https://github.com/kubernetes-sigs/reference-docs.git
  files:
  - src: gen-compdocs/build/kube-apiserver.md
    dst: content/en/docs/reference/command-line-tools-reference/kube-apiserver.md
  ...

Зверніть увагу, що коли є багато файлів для копіювання з одного джерела в одну й ту ж теку призначення, ви можете використовувати шаблони в значенні src. Ви повинні надати назву теки як значення для dst. Наприклад:

  files:
  - src: gen-compdocs/build/kubeadm*.md
    dst: content/en/docs/reference/setup-tools/kubeadm/generated/

Запуск інструмента update-imported-docs

Ви можете запустити інструмент update-imported-docs.py наступним чином:

cd <web-base>/update-imported-docs
./update-imported-docs.py <configuration-file.yml> <release-version>

Наприклад:

./update-imported-docs.py reference.yml 1.17

Конфігураційний файл release.yml містить інструкції для виправлення відносних посилань. Щоб виправити відносні посилання у ваших імпортованих файлах, встановіть властивість gen-absolute-links на true. Ви можете знайти приклад цього в release.yml.

Додавання та коміт змін у репо kubernetes/website

Перегляньте файли, що були згенеровані та скопійовані до <web-base>:

cd <web-base>
git status

Вивід показує нові та змінені файли. Згенеровані результати варіюються залежно від змін, внесених у upstream вихідний код.

Згенеровані файли компонентів інструментів

content/en/docs/reference/command-line-tools-reference/cloud-controller-manager.md
content/en/docs/reference/command-line-tools-reference/kube-apiserver.md
content/en/docs/reference/command-line-tools-reference/kube-controller-manager.md
content/en/docs/reference/command-line-tools-reference/kube-proxy.md
content/en/docs/reference/command-line-tools-reference/kube-scheduler.md
content/en/docs/reference/setup-tools/kubeadm/generated/kubeadm.md
content/en/docs/reference/kubectl/kubectl.md

Згенеровані файли довідки команди kubectl

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/css/font-awesome.min.css

Згенеровані теки та файли довідки по Kubernetes API

static/docs/reference/generated/kubernetes-api/v1.32/index.html
static/docs/reference/generated/kubernetes-api/v1.32/js/navData.js
static/docs/reference/generated/kubernetes-api/v1.32/js/scroll.js
static/docs/reference/generated/kubernetes-api/v1.32/js/query.scrollTo.min.js
static/docs/reference/generated/kubernetes-api/v1.32/css/font-awesome.min.css
static/docs/reference/generated/kubernetes-api/v1.32/css/bootstrap.min.css
static/docs/reference/generated/kubernetes-api/v1.32/css/stylesheet.css
static/docs/reference/generated/kubernetes-api/v1.32/fonts/FontAwesome.otf
static/docs/reference/generated/kubernetes-api/v1.32/fonts/fontawesome-webfont.eot
static/docs/reference/generated/kubernetes-api/v1.32/fonts/fontawesome-webfont.svg
static/docs/reference/generated/kubernetes-api/v1.32/fonts/fontawesome-webfont.ttf
static/docs/reference/generated/kubernetes-api/v1.32/fonts/fontawesome-webfont.woff
static/docs/reference/generated/kubernetes-api/v1.32/fonts/fontawesome-webfont.woff2

Виконайте git add та git commit, щоб зафіксувати файли.

Створення pull request

Створіть pull request до репозиторію kubernetes/website. Слідкуйте за вашим pull request і відповідайте на коментарі рецензентів за потреби. Продовжуйте слідкувати за вашим pull request до його злиття.

Через кілька хвилин після злиття вашого pull request, ваша оновлена довідкова документація буде видна в опублікованій документації.

Що далі

Щоб згенерувати окрему довідкову документацію, вручну налаштувавши необхідні репозиторії та запустивши цільові завдання збірки, дивіться наступні посібники:

2 - Внесок у код Kubernetes

Ця сторінка показує, як зробити внесок у проєкт kubernetes/kubernetes. Ви можете виправити помилки, знайдені в документації API Kubernetes або вмісті компонентів Kubernetes, таких як kubeadm, kube-apiserver та kube-controller-manager.

Якщо ви хочете відновити довідкову документацію для API Kubernetes або компонентів kube-* з коду upstream, перегляньте наступні інструкції:

Перш ніж ви розпочнете

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

  • Ваша змінна середовища GOPATH повинна бути встановлена, а розташування etcd повинно бути у вашій змінній середовища PATH.

  • Вам потрібно знати, як створити pull request у репозиторій GitHub. Зазвичай це включає створення форку репозиторію. Для отримання додаткової інформації дивіться Створення Pull Request та Стандартний Workflow Fork & Pull Request на GitHub.

Загальна картина

Довідкова документація для API Kubernetes та компонентів kube-*, таких як kube-apiserver, kube-controller-manager, автоматично генерується з вихідного коду в upstream Kubernetes.

Коли ви бачите помилки в згенерованій документації, ви можете розглянути можливість створення патчу для виправлення помилки в upstream проєкті.

Клонування репозиторію Kubernetes

Якщо ви ще не маєте репозиторію kubernetes/kubernetes, отримайте його зараз:

mkdir $GOPATH/src
cd $GOPATH/src
go get github.com/kubernetes/kubernetes

Визначте базову теку вашого клону репозиторію kubernetes/kubernetes. Наприклад, якщо ви слідували попередньому кроку для отримання репозиторію, ваша базова тека — $GOPATH/src/github.com/kubernetes/kubernetes. Наступні кроки посилаються на вашу базову теку як <k8s-base>.

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

Редагування вихідного коду Kubernetes

Довідкова документація API Kubernetes автоматично генерується з OpenAPI специфікації, яка створюється з вихідного коду Kubernetes. Якщо ви хочете змінити довідкову документацію API, перший крок — змінити один або кілька коментарів у вихідному коді Kubernetes.

Документація для компонентів kube-* також генерується з вихідного коду upstream. Ви повинні змінити код, повʼязаний з компонентом, який ви хочете виправити, щоб виправити згенеровану документацію.

Зробіть зміни у вихідному коді upstream

Ось приклад редагування коментаря у вихідному коді Kubernetes.

У вашому локальному репозиторії kubernetes/kubernetes, перейдіть на основну гілку і переконайтеся, що вона оновлена:

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

Припустимо, що у цьому вихідному файлі в основній гілці є помилка "atmost":

kubernetes/kubernetes/staging/src/k8s.io/api/apps/v1/types.go

У вашому локальному середовищі відкрийте types.go і змініть "atmost" на "at most".

Перевірте, що ви змінили файл:

git status

Вивід показує, що ви в основній гілці та що вихідний файл types.go був змінений:

On branch master
...
    modified:   staging/src/k8s.io/api/apps/v1/types.go

Збережіть відредагований файл

Виконайте git add і git commit, щоб зберегти зміни, які ви внесли до цього моменту. У наступному кроці ви зробите другий коміт. Важливо зберігати ваші зміни в окремих комітах.

Перейдіть до <k8s-base> і запустіть ці скрипти:

./hack/update-codegen.sh
./hack/update-openapi-spec.sh

Виконайте git status, щоб побачити, що було згенеровано.

On branch master
...
    modified:   api/openapi-spec/swagger.json
    modified:   api/openapi-spec/v3/apis__apps__v1_openapi.json
    modified:   pkg/generated/openapi/zz_generated.openapi.go
    modified:   staging/src/k8s.io/api/apps/v1/generated.proto
    modified:   staging/src/k8s.io/api/apps/v1/types_swagger_doc_generated.go

Перегляньте вміст api/openapi-spec/swagger.json, щоб переконатися, що помилка виправлена. Наприклад, ви можете виконати git diff -a api/openapi-spec/swagger.json. Це важливо, оскільки swagger.json є вхідними даними для другого етапу процесу генерації документації.

Виконайте git add і git commit, щоб зберегти ваші зміни. Тепер у вас є два коміти: один з відредагованим файлом types.go, і один, що містить згенеровану OpenAPI специфікацію та супутні файли. Залишить ці два коміти окремо. Тобто, не зливайте ваші коміти.

Подайте свої зміни як pull request до основної гілки репозиторію kubernetes/kubernetes. Слідкуйте за вашим pull request і відповідайте на коментарі рецензентів за потреби. Продовжуйте слідкувати за вашим pull request, поки він не буде злитий.

PR 57758 є прикладом pull request, який виправляє помилку в коді Kubernetes.

Cherry-pick вашого коміту у релізну гілку

У попередньому розділі ви відредагували файл в основній гілці та потім запустили скрипти для генерації OpenAPI специфікації та супутніх файлів. Потім ви подали свої зміни у pull request до основної гілки репозиторію kubernetes/kubernetes. Тепер припустимо, що ви хочете повернути вашу зміну в релізну гілку. Наприклад, якщо основна гілка використовується для розробки версії Kubernetes 1.32, і ви хочете повернути вашу зміну у гілку release-1.31.

Згадайте, що ваш pull request має два коміти: один для редагування types.go і один для файлів, згенерованих скриптами. Наступний крок — запропонувати cherry pick вашого першого коміту у гілку release-1.31. Ідея полягає в тому, щоб зробити cherry-pick коміту, що редагував types.go, але не коміту, що має результати запуску скриптів. Для інструкцій дивіться Запропонувати Cherry Pick.

Коли у вас є pull request для cherry-pick вашого коміту у гілку release-1.31, наступний крок — запустити ці скрипти в гілці release-1.31 у вашому локальному середовищі.

./hack/update-codegen.sh
./hack/update-openapi-spec.sh

Тепер додайте коміт до вашого cherry-pick pull request, що містить нещодавно згенеровану OpenAPI специфікацію та супутні файли. Слідкуйте за вашим pull request, поки він не буде злитий у гілку release-1.31.

На цьому етапі й основна гілка, й гілка release-1.31 містять ваш оновлений файл types.go та набір згенерованих файлів, що відображають зміну, яку ви внесли в types.go. Зазначте, що згенерована OpenAPI специфікація та інші згенеровані файли в гілці release-1.31 не обовʼязково будуть такими ж, як згенеровані файли в основній гілці. Згенеровані файли в гілці release-1.31 містять API елементи лише з Kubernetes 1.31. Згенеровані файли в основній гілці можуть містити API елементи, які не є в 1.31, але розробляються для 1.32.

Генерація опублікованих довідкових документів

Попередній розділ показав, як редагувати вихідний файл і потім згенерувати декілька файлів, включаючи api/openapi-spec/swagger.json у репозиторії kubernetes/kubernetes. Файл swagger.json є файлом визначення OpenAPI, який використовується для генерації документації API.

Тепер ви готові слідувати посібнику Генерація довідкової документації для API Kubernetes, щоб згенерувати опубліковану довідкову документацію API Kubernetes.

Що далі

3 - Генерація документації для API Kubernetes

Ця сторінка демонструє, як оновити документацію API Kubernetes.

Документація API Kubernetes формується на основі специфікації OpenAPI Kubernetes з використанням коду генерації з kubernetes-sigs/reference-docs.

Якщо ви знайшли помилки у згенерованій документації, вам потрібно виправити їх на upstream.

Якщо вам потрібно тільки згенерувати документацію з OpenAPI, продовжте читати цю сторінку.

Перш ніж ви розпочнете

Вимоги:

  • Вам потрібна машина, що працює під управлінням Linux або macOS.

  • Вам потрібно встановити ці інструменти:

  • Ваша змінна середовища PATH повинна включати необхідні інструменти для збірки, такі як бінарники Go та python.

  • Вам потрібно знати, як створити pull request до репозиторію на GitHub. Це включає створення власного форку репозиторію. Для отримання додаткової інформації дивіться Робота з локальним клоном.

Налаштування локальних репозиторіїв

Створіть локальне робоче середовище і встановіть ваш GOPATH:

mkdir -p $HOME/<workspace>

export GOPATH=$HOME/<workspace>

Отримайте локальну копію наступних репозиторіїв:

go get -u github.com/kubernetes-sigs/reference-docs

go get -u github.com/go-openapi/loads
go get -u github.com/go-openapi/spec

Якщо у вас ще немає репозиторію 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

  • Основна тека вашої копії 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>.

Генерація документації API

Цей розділ демонструє, як згенерувати опубліковану документацію API Kubernetes.

Встановлення змінних для зборки

  • Встановіть K8S_ROOT на <k8s-base>.
  • Встановіть K8S_WEBROOT на <web-base>.
  • Встановіть K8S_RELEASE на версію документації, яку ви хочете зібрати. Наприклад, якщо ви хочете зібрати документацію для Kubernetes 1.17.0, встановіть K8S_RELEASE на 1.17.0.

Наприклад:

export K8S_WEBROOT=${GOPATH}/src/github.com/<your-username>/website
export K8S_ROOT=${GOPATH}/src/k8s.io/kubernetes
export K8S_RELEASE=1.17.0

Створення теки версії та завантаження специфікації Open API

Ціль збірки updateapispec створює теку версії для збірки. Після створення теки, специфікація Open API завантажується з репозиторію <k8s-base>. Ці кроки забезпечують відповідність версій конфігураційних файлів і Kubernetes Open API специфікації з версією релізу. Назва теки версії слідує шаблону v<major>_<minor>.

У теці <rdocs-base>, виконайте наступну ціль збірки:

cd <rdocs-base>
make updateapispec

Збірка документації API

Ціль copyapi будує документацію API та копіює згенеровані файли до теки у <web-base>. Виконайте наступну команду у <rdocs-base>:

cd <rdocs-base>
make copyapi

Перевірте, що ці два файли були згенеровані:

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

Перейдіть до основної теки вашого локального <web-base>, і перегляньте, які файли були змінені:

cd <web-base>
git status

Вихідний результат буде подібним до:

static/docs/reference/generated/kubernetes-api/v1.32/css/bootstrap.min.css
static/docs/reference/generated/kubernetes-api/v1.32/css/font-awesome.min.css
static/docs/reference/generated/kubernetes-api/v1.32/css/stylesheet.css
static/docs/reference/generated/kubernetes-api/v1.32/fonts/FontAwesome.otf
static/docs/reference/generated/kubernetes-api/v1.32/fonts/fontawesome-webfont.eot
static/docs/reference/generated/kubernetes-api/v1.32/fonts/fontawesome-webfont.svg
static/docs/reference/generated/kubernetes-api/v1.32/fonts/fontawesome-webfont.ttf
static/docs/reference/generated/kubernetes-api/v1.32/fonts/fontawesome-webfont.woff
static/docs/reference/generated/kubernetes-api/v1.32/fonts/fontawesome-webfont.woff2
static/docs/reference/generated/kubernetes-api/v1.32/index.html
static/docs/reference/generated/kubernetes-api/v1.32/js/jquery.scrollTo.min.js
static/docs/reference/generated/kubernetes-api/v1.32/js/navData.js
static/docs/reference/generated/kubernetes-api/v1.32/js/scroll.js

Оновлення індексних сторінок документації API

При генерації документації для нового релізу, оновіть файл <web-base>/content/en/docs/reference/kubernetes-api/api-index.md з новим номером версії.

  • Відкрийте <web-base>/content/en/docs/reference/kubernetes-api/api-index.md для редагування, і оновіть номер версії документації API. Наприклад:

    ---
title: v1.17
---

[Kubernetes API v1.17](/docs/reference/generated/kubernetes-api/v1.17/)

  • Відкрийте <web-base>/content/en/docs/reference/_index.md для редагування, і додайте нове посилання на найновішу документацію API. Видаліть найстаріше посилання на версію документації API. Має бути пʼять посилань на найновіші версії документації API.

Локальне тестування документації API

Опублікуйте локальну версію документації API. Перевірте локальний попередній перегляд.

cd <web-base>
git submodule update --init --recursive --depth 1 # якщо ще не зроблено
make container-serve

Коміт змін

У <web-base>, виконайте git add і git commit, щоб зафіксувати зміни.

Подайте ваші зміни як pull request до репозиторію kubernetes/website. Слідкуйте за вашим pull request, і відповідайте на коментарі рецензентів за потреби. Продовжуйте слідкувати за вашим pull request до його злиття.

Що далі

4 - Генерація документації для команд kubectl

Ця сторінка показує, як згенерувати довідкову документацію для команд kubectl.

Перш ніж ви розпочнете

Вимоги:

  • Вам потрібна машина, що працює під управлінням Linux або macOS.

  • Вам потрібно встановити ці інструменти:

  • Ваша змінна середовища PATH повинна включати необхідні інструменти для збірки, такі як бінарники Go та python.

  • Вам потрібно знати, як створити pull request до репозиторію на 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 github.com/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.31.0, ви можете використати ці команди:

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

Якщо вам не потрібно редагувати вихідний код kubectl, дотримуйтесь інструкцій для Налаштування змінних для зборки.

Редагування вихідного коду kubectl

Документація довідки для команд kubectl автоматично генерується з вихідного коду kubectl. Якщо ви хочете змінити довідкову документацію, перший крок — змінити один або кілька коментарів у вихідному коді kubectl. Змініть їх у вашій локальній копії репозиторію kubernetes/kubernetes, а потім подайте pull request до основної гілки github.com/kubernetes/kubernetes.

PR 56673 є прикладом pull requestг, який виправляє помилку в вихідному коді kubectl.

Слідкуйте за вашим pull request і відповідайте на коментарі рецензентів. Продовжуйте слідкувати за вашим pull request до його злиття в цільову гілку репозиторію kubernetes/kubernetes.

Cherry pick вашої зміни до релізної гілки

Ваша зміна тепер знаходиться в основній гілці, яка використовується для розробки наступного випуску Kubernetes. Якщо ви хочете, щоб ваша зміна зʼявилася в документації для версії Kubernetes, яка вже була випущена, вам потрібно запропонувати, щоб вашу зміну було вибрано для релізної гілки.

Наприклад, припустимо, що основна гілка використовується для розробки Kubernetes 1.32 і ви хочете повернути вашу зміну до релізної гілки release-1.31. Для інструкцій про те, як це зробити, дивіться Пропонування вибірки.

Слідкуйте за вашим запитом на вибірку до його злиття в релізну гілку.

Налаштування змінних для збірки

Перейдіть до <rdocs-base>. У командному рядку встановіть наступні змінні середовища.

  • Встановіть K8S_ROOT на <k8s-base>.
  • Встановіть K8S_WEBROOT на <web-base>.
  • Встановіть K8S_RELEASE на версію документації, яку ви хочете зібрати. Наприклад, якщо ви хочете зібрати документацію для Kubernetes 1.31, встановіть K8S_RELEASE на 1.31.

Наприклад:

export K8S_WEBROOT=$GOPATH/src/github.com/<your-username>/website
export K8S_ROOT=$GOPATH/src/k8s.io/kubernetes
export K8S_RELEASE=1.31

Створення теки версії

Ціль збірки createversiondirs створює версійну теку і копіює конфігураційні файли довідки для kubectl до теки версії. Назва теки версії слідує шаблону v<major>_<minor>.

У теці <rdocs-base> виконайте наступну ціль зборки:

cd <rdocs-base>
make createversiondirs

Перевірте теґ релізу у k8s.io/kubernetes

У вашій локальній копії <k8s-base> перевірте гілку, яка містить версію Kubernetes, яку ви хочете задокументувати. Наприклад, якщо ви хочете згенерувати документацію для Kubernetes 1.31.0, перевірте теґ v1.31. Переконайтеся, що ваша локальна гілка актуальна.

cd <k8s-base>
git checkout v1.31.0
git pull https://github.com/kubernetes/kubernetes v1.31.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>
git submodule update --init --recursive --depth 1 # якщо не було зроблено раніше
make container-serve

Перегляньте локальний попередній перегляд.

Додайте та зафіксуйте зміни в kubernetes/website

Запустіть git add та git commit, щоб зафіксувати файли.

Створіть pull request

Створіть pull request до репозиторію kubernetes/website. Слідкуйте за вашим pull request і відповідайте на коментарі рецензентів за потреби. Продовжуйте слідкувати за вашим pull request до його злиття.

Через кілька хвилин після злиття вашого pull request оновлені теми довідки стануть видимими в опублікованій документації.

Що далі

5 - Генерація довідкової документації для метрик

Ця сторінка демонструє, як згенерувати довідкову документацію для метрик.

Перш ніж ви розпочнете

Вимоги:

  • Вам потрібна машина, що працює під управлінням Linux або macOS.

  • Вам потрібно встановити ці інструменти:

  • Ваша змінна середовища PATH повинна включати необхідні інструменти для збірки, такі як бінарники Go та python.

  • Вам потрібно знати, як створити pull request до репозиторію на GitHub. Це включає створення власного форку репозиторію. Для отримання додаткової інформації дивіться Робота з локальним клоном.

Клонування репозиторію Kubernetes

Генерація документації для метрик відбувається в репозиторії Kubernetes. Щоб клонувати репозиторій, перейдіть до теки, де ви хочете, щоб знаходилася клонована копія.

Потім виконайте наступну команду:

git clone https://www.github.com/kubernetes/kubernetes

Це створить теку kubernetes у вашій поточній робочій теці.

Генерація документації для метрик

У клонованому репозиторії Kubernetes знайдіть теку test/instrumentation/documentation. Документація для метрик генерується в цій теці.

З кожним релізом додаються нові метрики. Після того, як ви запустите скрипт генерації документації для метрик, скопіюйте документацію для метрик на вебсайт Kubernetes і опублікуйте оновлену документацію для метрик.

Щоб згенерувати останні метрики, переконайтеся, що ви знаходитесь в кореневій теці клонованого репозиторію Kubernetes. Потім виконайте наступну команду:

./test/instrumentation/update-documentation.sh

Щоб перевірити наявність змін, виконайте команду:

git status

Вивід буде схожий на:

./test/instrumentation/documentation/documentation.md
./test/instrumentation/documentation/documentation-list.yaml

Скопіюйте згенерований файл документації для метрик в репозиторій вебсайту Kubernetes

  1. Встановіть змінну середовища для кореневої теки вебсайту Kubernetes.

    Виконайте наступну команду, щоб встановити кореневу теку вебсайту:

    export WEBSITE_ROOT=<шлях до кореня вебсайту>

  2. Скопіюйте згенерований файл метрик в репозиторій вебсайту Kubernetes.

    cp ./test/instrumentation/documentation/documentation.md "${WEBSITE_ROOT}/content/en/docs/reference/instrumentation/metrics.md"

Створіть pull request

Щоб створити pull request, дотримуйтесь інструкцій у розділі Відкриття pull request.

Що далі

6 - Генерація довідкових сторінок для компонентів та інструментів Kubernetes

Ця сторінка показує, як створювати довідкові сторінки для компонентів та інструментів Kubernetes.

Перш ніж ви розпочнете

Розпочніть з розділу Передумови у довідковому посібнику Quickstart для генерування документації.

Дотримуйтесь інструкцій у довідковому посібнику Quickstart, щоб згенерувати довідкові сторінки для компонентів та інструментів Kubernetes.

Що далі

7 -

Вимоги:

  • Вам потрібна машина, що працює під управлінням Linux або macOS.

  • Вам потрібно встановити ці інструменти:

  • Ваша змінна середовища PATH повинна включати необхідні інструменти для збірки, такі як бінарники Go та python.

  • Вам потрібно знати, як створити pull request до репозиторію на GitHub. Це включає створення власного форку репозиторію. Для отримання додаткової інформації дивіться Робота з локальним клоном.