Исполнение проекта в Automation Controller

Содержание

Исполнение проекта в Automation Controller#

В Astra Automation проекты с отлаженными сценариями автоматизации должны исполняться с помощью Automation Controller.

Проект Ansible может содержать наборы сценариев, роли, вспомогательные файлы, переменные и файл описания инвентаря. При переносе такого проекта в Astra Automation важно определить, откуда Automation Controller должен получать описание инвентаря:

из репозитория Git;
из данных, созданных вручную в интерфейсе Automation Controller;
из репозитория Git с дополнительными переменными, заданными в Automation Controller.

Выбор способа влияет на использование group_vars/, host_vars/, Ansible Vault и правил приоритета переменных.

Примечание

Astra Automation не меняет базовые правила разрешения переменных Ansible. Automation Controller определяет, какие данные будут переданы Ansible как описание инвентаря, переменные описания инвентаря, переменные групп, переменные узлов и дополнительные переменные. Подробности о порядке присвоения значений см. в разделе Правило присвоения значения.

Способы исполнения#

Следующая таблица содержит возможные сценарии и рекомендуемые способы исполнения существующего проекта Ansible в Automation Controller:

Сценарий	Рекомендуемый способ	Что учитывать
Проект уже содержит файлы описания инвентаря, `group_vars/` и `host_vars/`	Импортировать описание инвентаря из проекта через Sourced from a Project	Структура проекта сохраняется. Синхронизация описания инвентаря с репозиторием Git
Описание инвентаря создают администраторы платформы	Создать описание инвентаря, группы и узлы в Automation Controller	`group_vars/` рядом с файлом описания инвентаря в репозитории Git не используются автоматически. Переменные необходимо задавать в Automation Controller или явно загружать в наборе сценариев
Нужно хранить базовое описание инвентаря в репозитории Git и переопределять отдельные значения в Automation Controller	Использовать смешанную схему	Нужно контролировать параметры Перезаписать (Overwrite) и Перезаписать переменные (Overwrite variables)
В `group_vars/` или `host_vars/` есть файлы, зашифрованные Ansible Vault	Перенести секреты на уровень выполнения задания или настроить безопасную доставку пароля Vault в среду исполнения	Полномочия типа Vault для шаблона задания не передаются автоматически в процесс синхронизации источника Sourced from a Project

Импортирование описания инвентаря из проекта#

В этом варианте Automation Controller получает описание инвентаря из репозитория Git. Для этого необходимо создать описание инвентаря с источником типа Sourced from a Project.

Такой способ рекомендуется для существующих проектов Ansible, которые ранее запускались локально через утилиту ansible-playbook или ansible-navigator.

Пример структуры проекта#

Пример структуры проекта при таком способе:

project/
├── ansible.cfg
├── environments/
│   ├── prod/
│   │   ├── inventory.yml
│   │   ├── group_vars/
│   │   │   ├── all.yml
│   │   │   └── web.yml
│   │   └── host_vars/
│   └── test/
│       ├── inventory.yml
│       ├── group_vars/
│       └── host_vars/
├── playbooks/
├── roles/
├── vars/
└── files/

При этом методе Automation Controller синхронизирует описание инвентаря с источником Sourced from a Project с учетом переменных, определенных в каталогах group_vars/ и host_vars/ проекта.

Такой вариант сохраняет привычную структуру проекта и делает поведение близким к прямому запуску через командную строку.

Важно

В шаблоне задания необходимо выбрать описание инвентаря, синхронизированное из источника Sourced from a Project. Если выбрать описание инвентаря, созданное вручную в интерфейсе Automation Controller, файлы group_vars/ и host_vars/ из репозитория Git автоматически использоваться не будут.

Настройка источника типа Sourced from a Project#

Перед настройкой источника убедитесь, что репозиторий Git уже подключен к Automation Controller как проект. Если репозиторий приватный, для проекта должны быть настроены полномочия типа Source Control.

Для импорта описания инвентаря из проекта выполните следующие действия:

После успешной синхронизации Automation Controller импортирует группы, узлы и доступные переменные из файла описания инвентаря и связанных каталогов group_vars/ и host_vars/.

Примечание

Если проект содержит несколько файлов описания инвентаря или файл находится в подкаталоге, укажите путь к конкретному файлу в поле Инвентарный файл (Inventory file).

Создание описания инвентаря в Automation Controller#

В этом варианте описание инвентаря, группы, узлы и переменные создаются в интерфейсе Automation Controller. Файл описания инвентаря из репозитория Git не используется как источник групп, узлов и переменных.

Пример структуры проекта:

project/
├── ansible.cfg
├── playbooks/
│   └── site.yml
├── roles/
├── vars/
└── files/

Такой вариант подходит в следующих случаях:

список узлов сопровождается администраторами платформы;
переменные должны редактироваться через интерфейс Automation Controller;
описание инвентаря поступает из внешнего источника, отличного от репозитория Git.

Если в репозитории Git есть файл group_vars/web.yml на любом уровне структуры проекта и в Automation Controller вручную создана группа web, переменные из этого файла не становятся переменными группы web автоматически.

Это происходит потому, что рассматриваемые группа и файл не связаны между собой.

Для такого варианта используйте один из следующих подходов:

задавайте переменные в Automation Controller на уровне описания инвентаря, группы или узла;
храните общие переменные в vars/ и подключайте их через vars_files или include_vars;
переносите переменные, которые должны применяться ко всем запускам набора сценариев, в свойства шаблона задания;
используйте опрос пользователя или дополнительные переменные при запуске, если значение должно задаваться перед выполнением задания.

Важно

Если описание инвентаря создано вручную в Automation Controller, переменные из каталогов group_vars/ и host_vars/, расположенных рядом с файлом описания инвентаря в репозитории Git, автоматически не используются.

Чтобы сохранить загрузку таких переменных из проекта, импортируйте описание инвентаря через источник Sourced from a Project.

Смешанная схема#

В смешанной схеме базовое описание инвентаря импортируется из репозитория Git, а часть переменных или параметров задается в Automation Controller.

Пример:

группы и узлы импортируются из файла environments/prod/inventory.yml через источник Sourced from a Project;
часть переменных группы или узла задается вручную в Automation Controller;
шаблон задания использует импортированное описание инвентаря.

Такой вариант полезен в следующих случаях:

структура групп и узлов должна храниться в репозитории Git;
отдельные значения отличаются между стендами и не должны попадать в репозиторий Git;
часть переменных часто меняют администраторы платформы;
требуется временно переопределить переменные без изменения репозитория.

Поведение смешанной схемы зависит от следующих параметров источника:

Перезаписать (Overwrite).

Если параметр включен, при синхронизации Automation Controller удаляет импортированные ранее группы и узлы, которые были удалены в источнике. Группы и узлы, не привязанные к источнику, не удаляются, а перемещаются в первую найденную группу, созданную вручную, или остаются в группе all. Используйте этот параметр, если репозиторий Git должен быть единственным источником групп и узлов.
Перезаписать переменные (Overwrite variables).

Если параметр включен, переменные, заданные в Automation Controller для тех же объектов, удаляются и заменяются переменными из источника. Если параметр отключен, Automation Controller объединяет переменные из источника и переменные, заданные в интерфейсе платформы.
Обновить при запуске (Update on launch).

Если параметр включен, Automation Controller обновляет описание из источника перед запуском задания, которое использует это описание инвентаря. Это помогает запускать задания на актуальной версии описания инвентаря из репозитория Git.

Важно

При смешанной схеме заранее определите, где находится желаемый источник для каждого типа данных. Например, группы и узлы можно хранить в репозитории Git, а локальные секреты и параметры окружения – в Automation Controller.

Не храните одно и то же значение одновременно в репозитории Git и в Automation Controller без понятного правила перезаписи. Иначе результат синхронизации может отличаться от ожидаемого.

Итоговое значение переменной определяется правилами приоритета переменных. Если переменная определена в нескольких местах, значение, заданное на более высоком уровне приоритета, заменяет остальные значения. Подробнее см. Правило присвоения значения.

Использование group_vars и host_vars#

Каталоги group_vars/ и host_vars/ связаны с файлом описания инвентаря. При локальном запуске Ansible загружает эти каталоги, если они расположены рядом с файлом описания инвентаря или в расположении, которое Ansible учитывает при разрешении переменных.

Пример локального запуска:

ansible-playbook playbooks/site.yml -i environments/prod/inventory.yml

Пример структуры:

inventory/
└── prod/
    ├── inventory.yml
    ├── group_vars/
    │   ├── all.yml
    │   └── web.yml
    └── host_vars/
        └── web-01.yml

При импорте через Sourced from a Project Automation Controller обрабатывает файл описания инвентаря из проекта и может импортировать связанные переменные. При ручном создании описания инвентаря в Automation Controller такой связи нет.

Примечание

Проблема не в расположении каталога group_vars/ внутри проекта. Проблема в том, обрабатывает ли Automation Controller файл описания инвентаря, с которым связан этот каталог.

Использование ansible.cfg#

Файл ansible.cfg содержит параметры выполнения Ansible. Полное описание доступных параметров и порядка поиска файла см. в описании Ansible Core.

При выполнении заданий в Automation Controller файл ansible.cfg можно использовать для настройки поведения Ansible в рамках отдельного проекта или среды исполнения. Например, в нем можно задать параметры подключений, пути к расширениям или параметры обработки вывода.

Ansible использует первый найденный файл конфигурации в следующем порядке:

файл, указанный в переменной окружения ANSIBLE_CONFIG;
файл ansible.cfg в текущем рабочем каталоге;
файл ~/.ansible.cfg в домашнем каталоге пользователя;
файл /etc/ansible/ansible.cfg.

В Automation Controller пользовательский файл ansible.cfg размещайте в корне проекта. Automation Controller запускает выполнение проекта из его корневого каталога и использует расположенный там файл ansible.cfg.

Предупреждение

Не размещайте файл ansible.cfg в подкаталоге playbooks/ для выполнения проекта через Automation Controller. Если сценарий находится в подкаталоге проекта, расположенный рядом с ним файл ansible.cfg не используется при запуске задания в Automation Controller.

В следующей таблице приведены варианты использования файла ansible.cfg.

Расположение	Когда использовать	Преимущества	Ограничения
Файл отсутствует	Для проектов, которым достаточно стандартных настроек Ansible и параметров, заданных в Automation Controller	В проекте отсутствуют дополнительные настройки выполнения	Нельзя задать специальные параметры Ansible для конкретного проекта
Корень проекта	Для настроек, которые должны применяться только к конкретному проекту при запуске через Automation Controller	Настройки хранятся вместе с проектом в репозитории Git и применяются при его выполнении в Automation Controller	Изменения файла влияют на все шаблоны заданий, использующие этот проект
`/etc/ansible/ansible.cfg` внутри среды исполнения	Для общих настроек, которые должны применяться к проектам, использующим одну среду исполнения	Позволяет задать единые базовые настройки в образе среды исполнения	Для изменения файла требуется обновить и повторно опубликовать образ среды исполнения. При наличии файла `ansible.cfg` в корне проекта настройки из образа не применяются: Ansible использует только первый найденный файл конфигурации
Рядом со сценарием при локальном запуске через `ansible-navigator`	Для локальной проверки проекта в среде исполнения перед его запуском в Automation Controller	Упрощает воспроизведение выполнения проекта в среде исполнения при локальной разработке	Не используйте этот вариант как способ настройки проекта для выполнения в Automation Controller, если сценарий находится в подкаталоге проекта

Важно

Файл ansible.cfg не связывает описание инвентаря, созданное вручную в Automation Controller, с каталогами group_vars/ или host_vars/ из репозитория Git.

Если необходимо использовать переменные из каталогов, расположенных рядом с файлом описания инвентаря в проекте, импортируйте описание инвентаря через источник Взято из проекта (Sourced from a Project).

Не храните в файле ansible.cfg секреты, пароли или значения, которые обеспечивают доступ к инфраструктуре. Для передачи секретов при выполнении задания используйте полномочия Automation Controller.

Параметры vault_password_file и vault_identity_list могут применяться только как технический способ предоставления пароля Vault процессу Ansible. Использование таких параметров требует безопасной доставки файла или скрипта получения пароля в среду исполнения и не является рекомендуемым способом хранения секретов.

Использование Ansible Vault#

Если файлы group_vars/ или host_vars/ зашифрованы с помощью Ansible Vault, синхронизация источника Sourced from a Project может завершиться ошибкой.

Пример ошибки:

Attempting to decrypt but no vault secrets found

Причина заключается в том, что процесс синхронизации источника должен получить пароль Vault для расшифровки переменных. Полномочие Vault, указанное в шаблоне задания, используется при выполнении задания и не передается автоматически в процесс синхронизации источника описания инвентаря.

Для проектов с переменными, зашифрованными через Vault, используйте один из следующих подходов:

храните секреты на уровне выполнения задания и подключайте полномочие Vault в шаблоне задания;
подключайте файлы, зашифрованные через Vault, из набора сценариев через vars_files или include_vars;
переносите секретные значения в переменные Automation Controller, если это соответствует модели безопасности проекта;
настройте отдельную среду исполнения и безопасный механизм доставки пароля Vault в процесс синхронизации источника.

Предупреждение

Не храните файл с паролем Vault в репозитории Git. Такой файл дает доступ к зашифрованным секретам всем пользователям, которые могут прочитать репозиторий.

Технически ansible.cfg может содержать параметры vault_password_file или vault_identity_list:

[defaults]
vault_password_file = /runner/secrets/vault-password

Такой вариант допустим только при безопасной доставке файла или скрипта получения пароля в среду исполнения. Не используйте этот способ как замену штатному управлению секретами.

Настройка шаблона задания#

После подготовки описания инвентаря создайте шаблон задания.

В шаблоне задания укажите:

проект, из которого будет взят набор сценариев;
набор сценариев из каталога playbooks/ или из корня проекта;
среду исполнения;
описание инвентаря;
полномочия для подключения к управляемым узлам;
при необходимости – полномочие Vault;
при необходимости – ограничение запуска в поле Лимит (Limit).

Для проекта с отдельными файлами описания инвентаря на каждое окружение создают отдельный шаблон задания. Например:

Deploy dev использует описание инвентаря, импортированное из environments/dev/inventory.yml;
Deploy stage использует описание инвентаря, импортированное из environments/stage/inventory.yml;
Deploy prod использует описание инвентаря, импортированное из environments/prod/inventory.yml.

Для проекта с единым файлом описания инвентаря можно создать один шаблон задания и использовать поле Лимит (Limit) для выбора группы окружения.

Предупреждение

Если в едином файле описания инвентаря есть группы dev, stage и prod, но в шаблоне задания не задано ограничение запуска, задание будет выполняться на всех узлах, указанных в файле описания инвентаря.

Нестандартные обходные решения#

Некоторые обходные решения могут работать технически, но усложняют сопровождение проекта и не должны быть основной рекомендацией.

К таким решениям относятся:

хранение файла с паролем Vault в репозитории Git;
символические ссылки из playbooks/group_vars/ в каталог environments/<env>/group_vars/;
собственные расширения переменных, которые читают каталоги описания инвентаря;
скрипты, которые копируют секреты в среду исполнения без централизованного контроля доступа.

Используйте такие решения только после отдельной оценки рисков. В среде промышленной эксплуатации предпочтительнее хранить секреты в управляемых механизмах платформы и использовать понятную модель источников переменных.