При написании новой роли задумался о теме данной статьи — как проверять набор минимально необходимых параметров (аргументов, переменных, всё в Ansible сводится к переменным) для выполнения роли и как обычно пошел изучать документацию.
С приятным удивлением обнаружил механизм, который в Ansible появился с релизом ansible-core 2.11 (апрель 2021) и называется он Role argument validation. Исходя из собственного опыта написания модулей Ansible, я предполагаю, что в данном механизме используется тот же самый код, что и при валидации аргументов модуля (по крайней мере, всё на это указывает).
Более того, этот механизм позволяет, помимо валидации аргументов, документировать вашу роль. После добавления файла, описывающего Ваш набор переменных, Вы получаете документированную роль, документацию по которой можно вызвать при помощи ansible-doc.
ansible-doc --type role --roles-path <you roles path> <role_name>Пример вызова такой роли:
Реализация
Для создания подобной функциональности используется файл meta/argument_specs.yml. Его формат описан в документации и довольно прост. Более того, у Вашей роли может быть не одна точка входа (по умолчанию это main.yml) но и дополнительные, возможно для вызова через ansible.builtin.import_role или ansible.builtin.include_role, набор параметров для каждой точки входа можно описать в этом файле. Также параметры можно пометить обязательными, указать тип данных (набор типов данных, которые умеет проверять AnsibleModule тут), который должен содержаться в параметре, его значение по умолчанию (если оно находится в ../defaults/<entry-point>.yml, например) ну и, конечно же, описание (short_description и description для точки входа и description для каждого параметра).
В дальнейшем роль, имеющая такое описание параметров при вызове будет проверять набор необходимых параметров автоматически отдельным таском.
При вызове роли через ansible.builtin.import_role или ansible.builtin.include_role есть возможность отключить проверку аргументов, используя параметр rolespec_validate установленный в false.
