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

На цій сторінці показано, як можна створити оновлену довідкову документацію для Configuration API Kubernetes. Вона призначена для людей, які роблять внесок у Kubernetes.

Довідка з Configuration API документує формати конфігурації для інструментів та компонентів Kubernetes — наприклад, формати kubelet, kube-apiserver, kube-scheduler, kubeconfig та kubeadm. Опублікована довідка знаходиться за адресою /docs/reference/config-api/.

genref у kubernetes-sigs/reference-docs є генератором, який будує цю довідку. Він читає типи конфігурації Go кожного компонента та рендерить їх у вигляді Markdown.

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

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

Вимоги:

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

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

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

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

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

Вам знадобляться локальні клони kubernetes/website та kubernetes-sigs/reference-docs.

Якщо ви ще не зробили форк та клон kubernetes/website, перегляньте розділ Робота з локальним клоном. Клонуйте reference-docs:

git clone https://github.com/kubernetes-sigs/reference-docs

Наступні кроки посилаються на ваш клон kubernetes/website як <web-base>, а ваш клон reference-docs як <rdocs-base>.

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

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

export K8S_WEBROOT=/шлях/до/вашого/website   # ваш клон website (<web-base>)

Збирання та публікація довідки Configuration API

З <rdocs-base>:

cd <rdocs-base>
make copyconfigapi

Ця команда виконується у два етапи:

  1. configapi — будує та запускає genref, який генерує Markdown у genref/output/md
  2. copyconfigapi — копіює згенеровані файли у ваш клон website за адресою <web-base>/content/en/docs/reference/config-api/.

Перший запуск завантажує залежності модулів Go і може тривати кілька хвилин.

Перевірте, що змінилося у вашому клоні website:

cd <web-base>
git status

Шукайте оновлення, зроблені в content/en/docs/reference/config-api — наприклад:

content/en/docs/reference/config-api/kubelet-config.v1beta1.md
content/en/docs/reference/config-api/kubeadm-config.v1beta4.md
content/en/docs/reference/config-api/apiserver-config.v1.md
content/en/docs/reference/config-api/client-authentication.v1.md

Попередній перегляд website та локальне тестування

Перегляньте ваші оновлення:

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

Потім відкрийте локальний попередній перегляд у вашому вебоглядачі та підтвердьте, що сторінки, які ви оновили, завантажуються належним чином. Hugo показує цей локальний попередній перегляд за адресою http://localhost:1313/ Тож сторінка для перевірки — http://localhost:1313/docs/reference/config-api/

Збереження змін у коміті

Якщо ви повторно згенерували довідку з Configuration API для оновлення релізу, закомітьте змінені файли в content/en/docs/reference/config-api/ у <web-base>, потім відкрийте pull request у kubernetes/website.

Що далі

Востаннє змінено August 02, 2026 at 9:25 PM PST: [uk] Ukrainian translation (all-in-one) (9fa1b6f8e1)