Динамічні змінні у документації

Загальний опис

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

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

Сценарії адміністрування налаштувань реєстру

  • Вибір демо-реєстру для платформи у control plane

Сценарії використання змінних у документації

  • Формування актуальних посилань та текстових описів

Цільовий дизайн управління налаштуваннями

Компоненти системи та їх призначення в рамках дизайну рішення

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

Компонент Службова назва Призначення / Суть змін

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

ddm-architecture

Зміни в структурі файлів що використовують змінні, оновлення пайплайнів розгортання

Control plane консоль

control-plane-console

Додати можливість позначати реєстр як демо-реєстр та обрати демо реєстр за замовчуванням

План змін

Рішення має враховувати наступні факти:

  • актуальні змінні не відомі на момент build фази документації

  • частина змінних відома на момент встановлення платформи

  • інша частина залежить від налаштуваннь платформи у процесі експлуатації (наприклад, посилання на демо-реєстр)

  • у випадку посиланнь на демо-реєстр необхідно залишити у документації інформацію про те, як формується це посилання

  • посилання на демо-реєстр враховуючи попердній пункт будуть мати однакову структуру тому треба знайти підхід який спростить формування таких посиланнь

Необхідні зміни у репозиторію документації

1. Використання змінних

У adoc файлах документації знайдено наступні змінні (на другому рівні те, як ці змінні використовувались у самих файлах):

  • krrt-stage

    • <cluster-name>

    • <назва-кластера>

  • demo-registry

    • <registry-name>

    • <registry_name>

    • <REGISTRY-NAME>

    • <назва-реєстру>

    • <openshift-project-name>

    • <project-name>

    • {NAME_REGISTRy}

    • {CP-NAMESPACE}

    • <службова-назва-реєстру>

  • apps.krrt-stage.ncr.gov.ua

    • {DNS-WILDCARD}

    • <dns-wildcard>

    • <base-domain>

    • <dnsWildcard>

    • .dnsWildcard

    • <registry.platform-domain>

План дій:

  • Всі змінні треба привести до єдиної конвенції:

Нова змінна: {{{my-variable}}}

  • Створення окремої папки ROOT/partials/links у якій розмістити файли для посиланнь

  • Використати include цих файлів де це необхідно

  • Заміна текста документації з адаптацію до нової можливості використання змінних де це необхідно

Приклад використання include:

include::ROOT:partials$/links/nexus.adoc

Приклад файла для посилання на jenkins nexus.adoc:

https://nexus-krrt-stage.apps.krrt-stage.ncr.gov.ua/ footnote:[cluster-name -- назва namespace (простору імен) у Nexus; dns-wildcard -- значення dns-wildcard;]

krrt-stage та apps.krrt-stage.ncr.gov.ua трансформуються у актуальні дані в процесі розгортання.

2. Зміни процесу розгортання

Всі змінні які підходять під паттерн обраний на минулому кроці треба замінити на актуальні дані у процесі розгортання документації. Таким чином ми уникнемо помилок та легко досягнемо необхідного рівня гнучкості (а саме, можливості змінювати посилання у процесі життя платформи). Це включає:

  • додавання відомих змінних у структуру ddm-architecture/deploy-templates/values.yaml

    • Наразі це тільки registry-name

    • для кожної змінної треба задати значення за замовчуванням

  • написання скрипта якій замінить усі входження змінних за паттерном

    • паттерн - {{{variable}}}

    • при відсутності даних для зазначеної назви змінної - залишити текст без змін

    • значення змінних беруться з environment змінних (див. наступний крок)

  • застосування скрипта для розгортання платформи

    • зміни стосуються файла ddm-architecture/deploy-templates/templates/deployment.yaml

    • у секції env цього файлу треба додати змінні які заповнюються з values.yaml чи з інших джерел (якщо це платформені змінні):

      • cluster-name - {{ env "dnsWildcard" }}

      • dns-wildcard - {{ env "clusterNameShort" }}

  • застосування скрипта для зовнішього розгортання документації (github)

    • зміни стосуються файла ddm-architecture/.github/workflows/antora-build.yml

    • тут використовуються лише змінні за замовчуванням із файла ddm-architecture/deploy-templates/values.yaml

    • перед застосуванням цих змін у master необхідно перевірити разгортання документації через github

Control plane

1. Вибір демо-реєстру за замовчуванням

  • У вкладці КЕРУВАННЯ ПЛАТФОРМОЮ при переході у редагування треба додати нову вкладку ДОКУМЕНТАЦІЯ.

  • На цій новій вкладці ДОКУМЕНТАЦІЯ додати компонент Select, який буде дозволяти обрати зі всіх наявних реєстрів

  • Опції для вибору треба взяти з переліку Codebase ресурсів

  • Зберігати обране значення треба у файлі values.yaml репозиторія cluster-mgmt разом з іншими параметрами платформи вкладки КЕРУВАННЯ ПЛАТФОРМОЮ

  • Назва параметра - registry-name

  • Зміни цього values.yaml вже перерозгортають документацію тому додатково змін до цього процесу не передбачується

demo default

Якщо реєстр який обрано демо-реєстром за замовчуванням був видалений, то це ніяк не впливає на values.yaml репозиторія cluster-mgmt. Тому всі змінні у документації продавжать посилатись на обраний реєстр, бо користувач сам повинен обрати новий актуальний демо реєстр, що унеможливлює заповнення актуального значення автоматично.

Помилка у разі того, якщо обраний раніше демо реєстр вже не актуальний:

demo missing