Разработка сценариев установки#

Содержание#

• Экспресс описание Installer

  • Сценарии и этапы

    • Параметры этапа

    • Параметры шага

    • Параметры блока служебных параметров (service_data)

    • Параметры Cmd шага

    • Скрытые параметры, через которые можно управлять из файла параметров

    • Параметры шага JenkinsRemote

    • Параметры шага Groovy

    • Дополнительные параметры

• Общая информация

  • Назначение

  • Структура Installer

  • Сценарий установки

• Базовая инструкция работы Installer

  • Структура сценария

  • Параметризация и шаблонизация сценария

    • Хранение параметров сценария в блоке „vars“

    • Хранение параметров сценария в отдельном файле параметров

    • Передача параметров сценария через аргументы запуска Autoinstaller

  • Выполнение команды в командной строке

  • Импорт дополнительного файла в сценарии

• Настройка Installer на полигоне

• Часто встречающиеся проблемы и пути их устранения

• Ссылки

Экспресс описание Installer#

Сценарии и этапы#

Каждый из исполняемых сценариев состоит из этапов. Любой этап может включать в себя дочерние этапы или состоять из шагов. Главное отличие этапа от шага - наличие параметра steps (списка шагов) и отсутствие параметра step_params.

К содержанию

Параметры этапа#

К содержанию

Параметры шага#

К содержанию

Параметры блока служебных параметров (service_data)#

У шага, в отличие от этапа, есть блок step_params (также поддерживается старый вариант: params). Это уже параметры, относящиеся непосредственно к шагу установки, они описаны далее в этом документе.

Помимо этого, всегда можно указать параметр import, значением которого является путь до другого JSON-файла, по сути являющегося частью данного сценария, вынесенной в отдельный файл.

К содержанию

Параметры Cmd шага#

К содержанию

Скрытые параметры, через которые можно управлять из файла параметров#

К содержанию

Параметры шага JenkinsRemote#

К содержанию

Параметры шага Groovy#

К содержанию

Дополнительные параметры#

Задаются в основном через файл параметров, или параметры запуска.

К содержанию

Общая информация#

Назначение#

В основном инсталляционная система служит для запуска скриптов и методов. Однако, она также управляет запуском, обработкой статусов и ошибок, итерациями, параметрами, межмодульным взаимодействием и многим другим. Другими словами, это прежде всего инструмент, под который можно дописывать и модифицировать логику обработки почти любого артефакта. Для упрощения работы такой инструмент уже содержит в себе необходимые скрипты (которые в рамках Installer называются «рецептами»), используемые для решения типовых задач. Подробнее об этом написано в разделе Рецепты по использованию Installer.

К содержанию

Структура Installer#

В состав Installer входят следующие элементы:

• Ядро Installer, которое содержит логику обработки пакета установки и некоторые служебные функции.

• Модули, которые содержат логику работы с определенным типом артефактов/сервисами, зависимости и пр.

• Файл параметров (опционален), который содержит данные о режимах, пути до пакета установки и различные параметры установки.

• Общие скрипты – утилиты-рецепты для решения типовых задач установки.

• Общие шаги – небольшие сценарии, оформленные в виде импортируемых в сценарий шагов, которые являются своего рода методами для решения типовых задач установки.

• Пакет установки, который содержит сценарий, его импортируемые части, и потенциально может содержать дополнительные артефакты, например: используемые сценарием скрипты.

• Сценарий, который описывает шаги установки, их последовательность и ссылки на параметры.

• Документация, которая содержит данный документ актуальной для данного дистрибутива версии.

• Журнал изменений по версиям (changelog).

• Список запланированных изменений (tasklist).

К содержанию

Сценарий установки#

Сценарий - это JSON-файл определенной структуры, который описывает шаги установки. По умолчанию это файл tasks.json, располагающийся в корне инсталляционного пакета. Изменить путь к файлу сценария можно указав в настройках секции Properties Content переменную scenarioFile=./путь_к_файлу.json.

К содержанию

Базовая инструкция работы Installer#

Структура сценария#

В корне располагается главный этап. Любой этап содержит следующие поля:

Также любой этап может иметь поле import, его значение содержит путь до JSON-файла (относительно рабочей директории), содержимое которого будет встроено в данную локацию. Таким образом можно разделить сценарий на набор файлов: основной сценарий и множество импортируемых субсценариев любого уровня вложенности.

Внутри списка шагов могут располагаться как новые этапы (таким образом можно создать дерево любого уровня сложности), так и непосредственно шаги установки.

Каждый шаг и этап содержит в себе блок служебных параметров: service_data. В этом блоке содержатся параметры, необходимые для управления процессом установки, например указать на количество повторных запусков шага при неудаче.
Раньше эти параметры располагались в теле шага/этапа, и такой формат все еще поддерживается, но новые сценарии рекомендуется писать следующим образом:

Пример сценария (с некоторыми необязательными элементами):

{
        "name": "<имя этапа>",
        "service_data": {
            "stage_type": "<тип порядка запуска>",
            "retry": <число_попыток>,
            "timeout": <время_ожидания_между_попытками>,
            "transaction": "<id_связанных_этапов>",
            "enabled": "<режим_включения_этапа>",
            "skip_stage": "<on либо true>"
            "allowed_status": [
                "<допустимый_статус>"
            ]
        },
        "steps": [
            {
            "name": "<имя шага>",
            "service_data": {
                "type": "<тип_шага>",
                "delay": "<время_ожидание_перед_запуском>",
                "retry": <число_попыток>,
                "timeout": <время_ожидания_между_попытками>,
                "transaction": "<id_связанных_этапов>",
                "enabled": "<режим_включения_этапа>",
                "allowed_status": [
                    "<допустимый_статус>"
                ],
                "files_for_hash": "<файлы_рассчитываемые_для_хэша>"
            },
            "step_params": {
                "<имя параметра>": "<значение>"
            },
            "vars" {
                "<имя_параметра>": "<значение>"
            }
            }
        ], 
        "vars" {
        "<имя_параметра>": "<значение>"
        }
}

Или то же самое, но с примером заполнения:

{
        "name": "Installer example",
        "service_data": {
            "stage_type": "parallel",
            "retry": 3,
            "timeout": 3000L,
            "transaction": "editConfigsBind",
            "enabled": "on",
            "skip_stage": "on",
            "allowed_status": [
                "unstable"
            ]
        },
        "steps": [
            {
            "name": "Just print value of 'thisval'"
            "service_data": {
                "type": "Cmd",
                "retry": 1,
                "timeout": 1000L,
                "transaction": "editConfigsBind",
                "enabled": "forced",
                "allowed_status": [
                    "error",
                    "unstable"
                ],
                "files_for_hash": "documents;userinfo.txt"
            },  
            "params": {
                "command": "echo ${thisval}"
            }
            },
            {
            "name": "Print 4321",
            "service_data": {
                "type": "Cmd",
            }
            "params": {
                "command": "echo 4321"
            }
            }
        ], 
        "vars" {
        "thisval": "1234"
        }
}

В данном примере будет выведено две строки: "1234" и "4321". Поскольку запуск был настроен параллельным, то строки могут выводиться в разном порядке. При том, что число попыток запуска было указано как 2, но по факту выполняться запуск будет лишь 1 раз, поскольку «ошибочный» статус внесен в список дозволенных, и даже при получении ошибки (хотя в данном примере она исключена), шаги отработают все действия. ID в данном примере не прописаны, поэтому Installer сам дописывает их в файл, проверив перед этим уникальность.

К содержанию

Параметризация и шаблонизация сценария#

На текущий момент установщик поддерживает как шаблонизацию посредством Jinja-шаблонизатора, так и параметризацию.

В этом случае поддерживается весь синтаксис Jinja. Параметризация же оформляется через placeholder-ы ${KEY}.

В обоих случаях значения берутся из двух источников: глобальной карты параметров (ее источники описаны ниже), и блока vars. Причем в случае с вложенными этапами, параметризация работает рекурсивно - сперва блок параметризуется посредством vars текущего этапа, затем его родителем и так далее, до корневого vars. При шаблонизации же многоуровневая подмена на данный момент не работает и производится единоразово на самом старте обработки.

К содержанию

Хранение параметров сценария в блоке „vars“#

В корне любого этапа или шага, есть блок vars. В нем можно создавать любые параметры, на которые в дальнейшем можно ссылаться в остальных частях сценариях. В качестве имен параметров может служить любая строка. Формат же ссылки следующий: {{имя_переменной}} или ${имя_переменной}.

Таким образом, если в блоке vars прописано:

    "vars": {
        "myvar": "world!"
    }

, то в любой части сценария (кроме данного блока vars), вы сможете указать это значение, например так:

    "type": "Cmd",
    "params": {
        "command": "echo Hello {{myvar}}"
    }

В этом случае данный шаг выведет строку "Hello world!".

В случае использования вложенных vars (на уровне этапов), приоритет всегда у дочерних vars. Если же аналогичные параметры задаются из других источников (например, из файла installer.properties), то приоритет имеют первые. Однако, этот режим можно реверсировать, задав параметр installer.reversePropPriority = true.

К содержанию

Хранение параметров сценария в отдельном файле параметров#

Параметры можно задавать через два файла: installer.properties (или yaml), или secrets.properties (или yaml) (имена и пути этих файлов можно переопределить, см. ниже).

Это файлы в форматах properties и yaml, т.е. описанные как:

   some.key=value

или

    some:
        key: val

(комментарии поддерживаются в формате: #комментарий).

При этом secrets* - это файл такого же формата, но зашифрованный либо vault, либо в openssl aes-256-cbc. Пароль для его расшифровки нужно передать параметром, одним из доступных способов (рекомендуемый - аргументы запуска).

⚠️ Важно!
Во избежание проблем несовместимости версий openssl, настоятельно рекомендуется при шифровании файла дополнительно указывать опцию -md md5.

К содержанию

Передача параметров сценария через аргументы запуска Autoinstaller#

Параметры можно также передавать через аргументы запуска. Передача осуществляется в формате ключ=значения, разделяя каждую пару параметров пробелом.

Вы можете либо поправить run.sh/run.bat, добавив в конце строки запуска, после ru.sbrf.Main параметры, либо передавать их при запуске, например:

./run.sh user=zaytsev7-as branch=feature/BSIDO-1815

Дополнительно поддерживается использование vm-аргументов, т.е. внутри исполняемого файла можно прописать -Dkey=value.

К содержанию

Передача параметров сценария через переменные окружения#

Четвертый способ передать значение - это переменные окружения.

В этом случае опять же задается некое имя переменной и ее значение.

Независимо от того, каким способом параметры переданы в Installer, они передаются на уровень всех модулей, и доступ к ним осуществляется через шаблон: {{ имя_переменной }}, или placeholder: ${имя_переменной}.

К содержанию

Передача параметров в процессе выполнения#

Пока данный механизм реализован лишь для Jenkins-версии и позволяет задавать переменные прямо в процессе исполнения в ручном режиме. Для этого в блоке служебных параметров соответствующего шага необходимо задать переменную interrupt. Ее значение - это имя переменной, ссылаться на которую можно будет дальше по сценарию. На данном шаге выполнение сценария приостановится и от пользователя запрошен ввод значения.

К содержанию

Использование ответа скриптов в качестве параметров#

Если вы выполняете некий bash-скрипт, то результаты его выполнения возможно использовать в последующих шагах. Для этого достаточно вывести в качестве ответа строку следующего формата:
<здесь может быть любой текст> pass_in_map <ключ>=<значение>, <ключ2>= <значение2>, ...

К содержанию

Выполнение команды в командной строке#

Некоторые задачи можно решить посредством командной оболочки (bash, cmd, powershell* и пр.). В Installer это выполняется модулем Cmd. Если вы хотите выполнить команду на той же машине, где располагается Installer (Windows, или Linux), то шаг установки выглядит весьма просто:

    "step_params": {
        "command": "выполняемая команда"
    }

* Использование powershell не проверялось и вероятно потребует небольших доработок, поэтому в данной версии Installer его использование не рекомендовано.

Если вы хотите выполнить многострочную команду для более удобного отображения в файле сценария, а также оформить это с разбиением на строки, то в качестве значения можно передавать список строк, например:

    "step_params": {
        "command": [
            "for i in ${!array[@]} do",
                "if ! grep -R '^[#]*\\s*${i}: .*' $file > /dev/null",
                    "then echo -e '\n$i: ${array[$i]}' >> $file",
                "else",
                    "sed -ir 's/^[#]*\\s*${i}: .*/$i=${array[$i]}/,' $file",
                "fi",
            "done"
        ]
    }

При этом нужно иметь в виду, что символ ";" перестал добавляться Installer в конце каждой строки и в случае необходимости, должен добавляться вами самостоятельно.

В случае, если у вас получается большой скрипт, то лучше будет вынести его в отдельный файл и вызывать его простой командой: "chmod 755 файл; ./<файл агрументы>".

В случае же, если вам необходимо выполнить команду на удаленном linux сервере, то в качестве параметров необходимо также передать еще и следующие: ip, user, pass, port (если не указать, используется 22).

Например:

"step_params": {
    "ip": "8.8.8.8",
    "user": "${osUser}",
    "pass": "${osPassword}",
    "port": 22,
    "command": [
        "for i in ${!array[@]} do",
            "if ! grep -R '^[#]*\\s*${i}: .*' $file > /dev/null",
                "then echo -e '\n$i: ${array[$i]}' >> $file",
            "else",
                "sed -ir 's/^[#]*\\s*${i}: .*/$i=${array[$i]}/,' $file",
            "fi",
        "done"
    ]
}

Разумеется, вместо написания множества команд всегда можно написать скрипт и вызвать его с нужными параметрами в шаге Installer (этот вариант является рекомендованным).

К содержанию

Импорт дополнительного файла в сценарии#

В сценарии также поддерживается возможность разделять его на несколько отдельных файлов, и объединять посредством переменной import.
Это позволяет выделить, например, сложную логику какого-то шага в отдельный файл, и даже переиспользовать его в нескольких местах одного сценария. Выглядеть это будет в итоге примерно так:

{
    "main": {
        "name": "Основной этап",
        "steps": [
            {
                "import": "newsub1.json"
            },
            {
                "import": "newsub2.json"
            }
        ]
    }
}

К содержанию

Настройка Installer на полигоне#

Для настройки Jenkins job запуска, необходимо настроить Pipeline на репозиторий в используемом домене.

Например:

• https://<...>/projects/DEVOPSEFS/repos/autoinstaller-assembly/browse

• https://<...>/stash/projects/DEVOPSEFS/repos/autoinstaller-assembly/browse

На файл runner-pipeline.groovy в переменных окружения Jenkins можно указать node.

Список параметров, которые необходимо задать:

К содержанию

Часто встречающиеся проблемы и пути их устранения#

1. Если при установке артефакта в Nexus выводится PKIX ошибка, то можно произвести запуск с флагом -Dmaven.wagon.http.ssl.insecure=true.

2. Во избежание проблем несовместимости версий openssl, настоятельно рекомендуется при шифровании файла дополнительно указывать опцию -md md5.

3. В режиме prom, из-за того что параметризация секретных параметров ведется только перед выполнением шага, изменение таких параметров не будет восприниматься Installer, как изменение, что не приведет к перезапуску шага. Если вам требуется, чтобы на такое изменение происходил перезапуск, нужно связать его с каким-либо дополнительным изменением.

4. На некоторых инсталляциях Jenkins данный функционал не может работать корректно из-за ошибки кросс-доменных запросов.

К содержанию

Ссылки#

Подробную информацию о Jenkins job для запуска Installer можно узнать в статье – Installer job.

Продвинутая инструкция работы с Installer.

Рецепты по использованию Installer.

К содержанию