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

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

Примітка:

Ця тема показує, як згенерувати довідкову документацію для команд kubectl таких як kubectl apply та kubectl taint. Ця тема не показує, як згенерувати сторінку довідки для опцій kubectl. Для інструкцій про те, як згенерувати довідкову сторінку опцій kubectl, дивіться Генерація довідкових сторінок для компонентів та інструментів Kubernetes.

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

Вимоги:

  • Вам потрібна машина, що працює під управлінням Linux або macOS. У Windows використовуйте Підсистема Windows для Linux (WSL), оскільки інструменти збірки покладаються на make та Bash-скрипти.

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

    • Git
    • Go, будь-який нещодавній реліз (Go автоматично завантажує точну версію інструментарію, необхідну генератору)
    • make
    • gcc компілятор/лінкер
    • Docker (Потрібен тільки для локального перегляду вебсайту за допомогою make container-serve)

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

cd <k8s-base>
git checkout v1.35.0
git pull https://github.com/kubernetes/kubernetes 1.35.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.36 і ви хочете повернути вашу зміну до релізної гілки release-1.35. Для інструкцій про те, як це зробити, дивіться Пропонування вибірки.

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

Примітка:

Пропонування вибірки вимагає, щоб ви мали дозвіл на встановлення мітки та віхи у вашому pull request. Якщо у вас немає таких прав, вам знадобиться допомога когось, хто може встановити мітку та віху для вас.

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

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

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

Наприклад:

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

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

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

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

cd <rdocs-base>
make createversiondirs

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

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

cd <k8s-base>
git checkout v1.35.0
git pull https://github.com/kubernetes/kubernetes v1.35.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 оновлені теми довідки стануть видимими в опублікованій документації.

Що далі

Востаннє змінено July 15, 2026 at 12:45 AM PST: [uk] Ukrainian translation (all-in-one) (193b0d4ea4)