Утилиты

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

ansible

Утилита ansible предназначена для выполнения отдельных (ad-hoc) команд на одном или нескольких управляемых узлах без необходимости создания сценариев.

Запуск команд осуществляется удаленно, поэтому необходимо настроить управляемые узлы. На управляемых узлах не требуется установка Ansible или каких-либо специфических компонентов – достаточно доступного интерпретатора Python. На управляющем узле должен быть установлен Ansible Core.

Утилита ansible всегда требует указания целевых узлов (одного, группы или ключевого слова all), модуля (-m) и, при необходимости, аргументов к модулю (-a).

Утилита не сохраняет состояние и не определяет, выполнена ли уже та или иная операция. Каждая команда выполняется однократно, без анализа предыдущих действий или зависимости между задачами. По этой причине ansible не подходит для сложных конфигурационных изменений и не заменяет полноценные наборы сценариев.

Наиболее эффективно утилита используется для:

• первичной настройки серверов;

• диагностики и быстрой проверки инфраструктуры;

• запуска операций из внешних скриптов;

• отладки задач перед оформлением в виде сценария.

Примеры использования:

Установка утилиты htop на всех узлах

ansible all -m package -a "name=htop state=present" -b

Здесь:

• all – цель команды: применить ко всем узлам из инвентарного файла;

• -m package – модуль package автоматически определяет подходящий пакетный менеджер в зависимости от дистрибутива;

• -a "name=htop state=present" – аргументы для модуля: установить пакет htop, если он еще не установлен;

• -b – выполнение команды с повышенными привилегиями.

Перезапуск службы nginx на группе узлов web

ansible web -m systemd -a "name=nginx state=restarted enabled=yes" -b

Здесь:

• web – название группы узлов, определенной в файле инвентаря;

• -m systemd – использование модуля systemd для управления системными службами;

• -a "name=nginx state=restarted enabled=yes" – название службы, требуемое состояние и параметр включения автоматического запуска;

• -b – выполнение команды с повышенными привилегиями.

Получение информации о времени работы всех управляемых узлов

ansible all -a "uptime" -u ansible -b

Здесь:

• all – применение команды ко всем узлам;

• -a "uptime" – выполнение команды на управляемом узле;

• -u ansible – подключение с использованием учетной записи ansible;

• -b – выполнение команды с повышенными привилегиями.

Копирование файла на целевые узлы

ansible app_servers -m ansible.builtin.copy -a "src=/opt/config.ini dest=/etc/myapp/config.ini mode=0644" -b

Здесь:

• app_servers – группа узлов, на которые будет применена операция;

• -m ansible.builtin.copy – модуль для копирования файлов;

• src=/opt/config.ini – путь к локальному файлу;

• dest=/etc/myapp/config.ini – целевой путь на управляемом узле;

• mode=0644 – установка права доступа;

• -b – выполнение команды с повышенными привилегиями.

Полный набор аргументов утилиты ansible представлен в справочнике.

ansible-config

Утилита ansible-config позволяет работать с конфигурацией Ansible, определяя, какие параметры задействованы в текущем окружении, откуда они были загружены, и как можно изменить их поведение. Основное назначение этой утилиты – помощь в диагностике, настройке и отладке конфигурации Ansible.

Команда предоставляет несколько режимов работы. Наиболее часто используется режим – dump. Он позволяет вывести итоговые значения всех параметров Ansible вместе с указанием их происхождения, например, из переменной окружения, файла ansible.cfg, параметров CLI или встроенных значений по умолчанию.

Примеры использования:

Получение полной конфигурации с указанием источников параметров

ansible-config dump --only-changed

Здесь:

• dump – режим отображения всех параметров Ansible;

• --only-changed – отображение только тех параметров, чьи значения были переопределены (отличаются от значений по умолчанию).

Проверка пути поиска конфигурационных файлов

ansible-config list

Здесь list – режим отображения всех возможных параметров и информации о том, где они могут быть заданы.

Поиск конкретного параметра конфигурации

ansible-config dump | grep DEFAULT_FORKS

Здесь:

• DEFAULT_FORKS – название параметра, отвечающего за количество параллельных подключений;

• утилита grep используется для фильтрации вывода.

Проверка корректности файла конфигурации

ansible-config validate

Здесь validate – режим проверки синтаксиса и структуры текущего конфигурационного файла ansible.cfg.

Все параметры, которые обрабатываются ansible-config, соответствуют возможностям системы конфигурации Ansible и могут быть заданы в:

• файле ansible.cfg;

• переменных окружения;

• параметрах командной строки;

• переменных инвентаря и других источниках.

Последовательность обработки источников можно проследить через вывод ansible-config dump.

Полный набор аргументов утилиты ansible-config представлен в справочнике.

ansible-console

Утилита ansible-console предоставляет интерактивную оболочку (REPL – Read-Eval-Print Loop) для управления инфраструктурой с помощью Ansible в режиме реального времени.

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

Работа с консолью начинается с запуска команды ansible-console. После запуска пользователь попадает в интерактивный режим, где может выполнять команды в формате <цель> <модуль> <аргументы>.

В интерактивной сессии также доступны команды для смены инвентаря, переключения пользователя, задания переменных и выполнения произвольных shell-команд.

Примеры использования:

Запуск интерактивной консоли

ansible-console

Здесь:

• запускается оболочка по умолчанию с использованием стандартного инвентаря;

• по умолчанию цель команд – all.

Установка пакета vim на группу серверов web (в интерактивной сессии)

web package name=vim state=present -b

Здесь:

• web – название группы узлов;

• package – модуль установки пакетов;

• name=vim state=present – аргументы модуля, описывающие требуемое состояние;

• -b – выполнение команды с повышенными привилегиями.

Получение информации о всех узлах группы db (в интерактивной сессии)

db setup -b

Здесь:

• setup – модуль, собирающий факты о системе;

• db – название целевой группы узлов;

• -b – выполнение команды с повышенными привилегиями.

Выполнение команды оболочки на всех узлах (в интерактивной сессии)

all command cmd='uptime' -b

Здесь:

• command – модуль для выполнения системной команды;

• cmd='uptime' – команда для выполнения;

• -b – выполнение команды с повышенными привилегиями.

Полный набор аргументов утилиты ansible-console и команд оболочки представлен в справочнике.

ansible-doc

Утилита ansible-doc используется для просмотра документации по расширениям, модулям (как тип расширения) и другим компонентам Ansible прямо из командной строки.

С ее помощью можно изучать доступные модули, просматривать документацию по их использованию, выявлять допустимые аргументы и значения по умолчанию, а также определять местоположение исходного кода каждого компонента.

Инструмент полезен при написании сценариев и отладке задач, чтобы быстро уточнить синтаксис модуля или назначение его параметров, не обращаясь к веб-документации.

При вызове ansible-doc без параметров открывается интерактивный просмотр с возможностью поиска и навигации по модулям.

Примеры использования:

Просмотр документации по модулю copy

ansible-doc copy

Здесь copy – название интересующего модуля.

Поиск модулей, содержащих ключевое слово file

ansible-doc -l | grep file

Здесь:

• -l – список всех доступных модулей;

• grep используется для фильтрации по ключевому слову.

Просмотр только параметров и их значений по умолчанию для модуля user

ansible-doc -s user

Здесь -s – вывод шаблона задачи с параметрами, допустимыми значениями и значениями по умолчанию.

Получение информации о подключаемом расширении типа strategy

ansible-doc -t strategy linear

Здесь:

• -t strategy – указание типа компонента (в данном случае: стратегия выполнения задач);

• linear – название стратегии по умолчанию.

Получение пути к исходному файлу модуля

ansible-doc -F setup

Здесь -F – краткая форма вывода с указанием пути к Python-файлу с исходным кодом модуля.

С помощью ansible-doc можно также изучать пользовательские расширения, добавленные в проект через собственные коллекции или указанные пути.

Полный набор аргументов утилиты ansible-doc представлен в справочнике.

ansible-galaxy

Утилита ansible-galaxy используется для управления переиспользуемыми компонентами автоматизации – ролями и коллекциями. Это основной инструмент для установки, публикации и структурирования таких компонентов, а также для управления зависимостями в проектах Ansible.

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

Коллекции – это более крупные элементы, которые включают в себя не только роли, но и расширения, фильтры, документацию и тесты. Коллекции позволяют распространять и переиспользовать целые наборы функциональности как единое целое.

Утилита ansible-galaxy используется в следующих сценариях:

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

• Фиксация зависимостей – фиксация версий ролей и коллекций в файле requirements.yml и установка зависимостей через него.

• Публикация собственных решений – разработка и публикация ролей и коллекций в общедоступные (Ansible Galaxy) или частные реестры (Private Automation Hub).

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

• Автоматизация CI/CD – управление зависимостями коллекций и ролей в рамках автоматизации.

Примеры использования:

Установка коллекции community.general

ansible-galaxy collection install community.general

Здесь:

• collection install – команда для установки коллекции;

• community.general – название коллекции в формате <namespace>.<name>.

Установка зависимостей из requirements.yml

ansible-galaxy install -r requirements.yml

Здесь:

• install – установка зависимостей (ролей и коллекций);

• -r requirements.yml – путь к файлу со списком зависимостей.

Пример requirements.yml:

collections:
  - name: community.mysql
    version: 3.7.0
roles:
  - name: geerlingguy.nginx
    version: 3.3.0

Здесь:

• collections и roles – секции, определяющие, какие компоненты нужно загрузить;

• name – полное название роли или коллекции;

• version – требуемая версия коллекции или роли.

Инициализация новой коллекции

ansible-galaxy collection init my_namespace.my_collection

Здесь:

• collection init – команда для создания шаблона новой коллекции;

• my_namespace.my_collection – полное название, включающее пространство имен (namespace) и название коллекции. Используется для формирования структуры файлов и каталогов коллекции.

Сборка и публикация коллекции

ansible-galaxy collection build
ansible-galaxy collection publish my_namespace-my_collection-1.0.0.tar.gz --api-key <ключ>

Здесь:

• collection build – команда для упаковки коллекции в архив .tar.gz. Архив содержит весь код, метаданные и документацию.

• collection publish – публикация ранее собранного архива в Ansible Galaxy или на другой указанный сервер.

• my_namespace-my_collection-1.0.0.tar.gz – название архива, сформированное в процессе сборки.

• --api-key <ключ> – токен аутентификации для доступа к реестру коллекций Galaxy.

Полный набор аргументов утилиты ansible-galaxy представлен в справочнике.

ansible-inventory

Утилита ansible-inventory предоставляет доступ к данным из файла инвентаря, определяющим, какие узлы участвуют в автоматизации, как они сгруппированы и какие переменные к ним относятся. Это основной инструмент для диагностики и исследования инвентаря как в процессе разработки, так и на этапе эксплуатации.

В Ansible инвентарь представляет собой структуру, описывающую инфраструктуру: узлы, группы, переменные и их взаимосвязи. Он может быть реализован в виде статического YAML- или INI-файла или с помощью динамического источника, основанного на внешнем API. Утилита ansible-inventory позволяет работать с обеими формами инвентаря и отображать их в удобочитаемом виде.

Часто ansible-inventory используется для отладки содержимого инвентаря как при ручной настройке, так и в CI/CD-конвейерах, где требуется гарантировать корректность структуры и значений перед запуском сценариев. Также инструмент полезен при работе с динамическими источниками – он позволяет получить полную картину, которую формирует расширение, не дожидаясь выполнения задач.

Инвентарь можно просматривать в различных форматах. Например, вывод в YAML позволяет легко читать структуру, тогда как JSON подходит для последующей обработки скриптами. ansible-inventory имеет визуализации групп и узлов в виде дерева, чтобы оценить, как организованы вложенные группы. Также можно запросить переменные, связанные с конкретным узлом, или просмотреть все доступные узлы с учетом объединения нескольких источников инвентаря.

Кроме диагностики, ansible-inventory может использоваться в автоматизированных системах – например, для генерации списка узлов при интеграции с внешними инструментами мониторинга или оркестрации.

Примеры использования:

Просмотр инвентаря в формате YAML

ansible-inventory -i ./inventories/prod.yaml --list --yaml

Здесь:

• -i ./inventories/prod.yaml – указание файла инвентаря;

• --list – вывод полной структуры инвентаря;

• --yaml – вывод в формате YAML.

Получение полной информации о конкретном узле

ansible-inventory -i inventories/prod.yaml --host db01.internal

Здесь --host db01.internal указывает конкретный узел для получения информации о нем.

Визуализация структуры групп и вложенности

ansible-inventory -i inventories/prod.yaml --graph

Здесь --graph – вывод дерева групп и вложенных в них узлов.

Проверка работы динамического инвентаря

ansible-inventory -i ./scripts/aws_inventory_plugin.yaml --list --export

Здесь:

• -i ./scripts/aws_inventory_plugin.yaml – путь к файлу формата YAML расширения динамического инвентаря;

• --export – преобразование вывода в более компактную структуру для экспорта.

Комбинирование с jq для анализа переменных

Пример извлекает список всех подгрупп, вложенных в группу web.

ansible-inventory -i inventories/prod.yaml --list | jq `.web.children`

Здесь jq – утилита для обработки данных в формате JSON.

Полный набор аргументов утилиты ansible-inventory представлен в справочнике.

ansible-playbook

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

Сценарии позволяют задать четкую последовательность действий, определить условия выполнения задач, сгруппировать действия в роли и обеспечить повторное использование логики.

Утилита ansible-playbook принимает набор сценариев в качестве аргумента и поддерживает множество параметров для тонкой настройки процесса выполнения: выбор файла инвентаря, ограничение набора узлов, фильтрация по тегам, выполнение в режиме предварительной проверки, журналирование, детализация вывода и прочее.

Примеры использования:

Запуск набора сценариев с произвольным инвентарем, переменными и тегами

ansible-playbook -i inventories/prod.yaml site.yml \
  --extra-vars "env=production version=3.2.1" \
  --limit web_servers \
  --tags "deploy,nginx" \
  --check \
  --diff

Здесь:

• -i inventories/prod.yaml – указание файла инвентаря в формате YAML;

• site.yml – основной набор сценариев;

• --extra-vars "env=production version=3.2.1" – передача переменных в набор сценариев;

• --limit web_servers – ограничение области действия команд до группы web_servers;

• --tags "deploy,nginx" – выбор задач с указанными тегами;

• --check – режим предварительной проверки, без фактического внесения изменений;

• --diff – отображение различий между текущим и предполагаемым состоянием.

Повторный запуск набора сценариев после ошибки с продолжением с определенной задачи

ansible-playbook site.yml --start-at-task="Install backend dependencies"

Здесь выполнение задач начинается с Install backend dependencies. Все предыдущие задачи пропускаются.

Использование собственного пользователя SSH и включение подробного вывода

ansible-playbook site.yml \
  -i hosts.ini \
  -u deploy \
  --become \
  --ask-become-pass \
  -vvv

Здесь:

• -u deploy – использование пользователя deploy для подключения по SSH;

• --become – выполнение команды с повышенными привилегиями;

• --ask-become-pass – интерактивный ввод пароля для become;

• -vvv – включение подробного вывода для отладки.

Запуск с загрузкой дополнительных переменных из файла

ansible-playbook site.yml --extra-vars "@vars/prod.json"

Здесь --extra-vars @vars/prod.json – файл в формате JSON, содержащий переменные.

Ограничение выполнения по названию узла и журналирование

ansible-playbook -i inventory.yaml site.yml \
  --limit "web01.example.com" \
  --log-path ./logs/deploy.log

Здесь:

• --limit "web01.example.com" – запуск задач только на указанном узле;

• --log-path ./logs/deploy.log – запись детального журнала выполнения в указанный файл.

Полный набор аргументов утилиты ansible-playbook представлен в справочнике.

ansible-pull

Утилита ansible-pull представляет собой альтернативный подход к выполнению сценариев Ansible, при котором управление происходит не централизованно (как в случае с ansible или ansible-playbook), а на стороне управляемого узла. В отличие от стандартного подхода, при котором управление осуществляется с управляющего узла, утилита ansible-pull позволяет самим управляемым узлам инициировать выполнение – они самостоятельно загружают наборы сценариев из удаленного репозитория и запускают их локально. При необходимости он может периодически запускаться по расписанию для обеспечения актуальности конфигурации.

Этот механизм может быть использован в инфраструктуре с ограниченным доступом. Например, новый управляемый узел может при запуске выполнить ansible-pull из cron или systemd и тем самым настроить себя по текущему состоянию инфраструктуры.

Пример использования:

Самонастройка узла с помощью ansible-pull

ansible-pull -U https://git.example.com/infra-config.git \
  -i localhost, \
  site.yml \
  --checkout main \
  --accept-host-key \
  --directory /etc/ansible/pull \
  --extra-vars "node_id=web01 region=eu-west"

Здесь:

• -U https://git.example.com/infra-config.git – URL удаленного репозитория, содержащего набор сценариев и связанные файлы;

• -i localhost, – указание инвентаря (в данном примере используется текущий узел);

• site.yml – название набора сценариев, который должен быть выполнен после клонирования;

• --checkout main – переключение на ветку main перед запуском;

• --accept-host-key – автоматическое добавление SSH-ключа репозитория в known_hosts;

• --directory /etc/ansible/pull – путь, куда будет клонирован репозиторий;

• --extra-vars "node_id=web01 region=eu-west" – передача переменных в набор сценариев.

ansible-pull иногда используется совместно с планировщиком задач (например, cron), чтобы выполнять автоматическую периодическую синхронизацию:

*/15 * * * * root ansible-pull -U git@github.com:company/infra.git -i localhost, site.yml

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

Полный набор аргументов утилиты ansible-pull представлен в справочнике.

ansible-vault

Утилита ansible-vault предназначена для защиты конфиденциальных данных, используемых в Ansible: пароли, токены доступа, ключи API, закрытые ключи SSH и тому подобное. Утилита дает возможность хранить зашифрованные значения прямо в сценариях или файлах переменных без риска компрометации при совместной работе с репозиториями.

Утилита ansible-vault позволяет:

• создавать новые зашифрованные файлы с переменными;

• шифровать уже существующие файлы;

• расшифровывать их для просмотра или редактирования;

• изменять ключ шифрования;

• редактировать зашифрованные файлы и повторно шифровать их после сохранения изменений;

• использовать несколько источников ключей, в том числе отдельные файлы и внешние скрипты.

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

Примеры использования:

Редактирование зашифрованного файла с указанием файла ключа

ansible-vault edit group_vars/prod/secrets.yml --vault-password-file ~/.vault_key.txt

Здесь:

• ansible-vault edit – команда для открытия файла с последующим шифрованием после закрытия;

• group_vars/prod/secrets.yml – путь к зашифрованному файлу;

• --vault-password-file ~/.vault_key.txt – путь к сохраненному файлу с ключом.

Изменение ключа шифрования для нескольких файлов с указанием старого и нового ключей

ansible-vault rekey \
  --vault-password-file ~/.old_key.txt \
  --new-vault-password-file ~/.new_key.txt \
  group_vars/prod/*.yml

Здесь:

• ansible-vault rekey – команда замены ключа шифрования;

• --vault-password-file ~/.old_key.txt – текущий ключ шифрования, необходимый для расшифровки;

• --new-vault-password-file ~/.new_key.txt – файл с новым ключом, которым будут повторно зашифрованы файлы;

• group_vars/prod/*.yml – файлы, который будут зашифрованы заново.

Расшифровка файла с переменными с помощью ввода ключа вручную

ansible-vault decrypt --ask-vault-pass group_vars/production/db_credentials.yml

Здесь:

• ansible-vault decrypt – команда для расшифровки файла;

• --ask-vault-pass – указание вручную ввести ключ для расшифровки;

• group_vars/production/db_credentials.yml – путь к зашифрованному файлу.

Для шифрования отдельных значений в рамках незащищенного файла можно использовать встроенную поддержку vault-блоков, но для надежности рекомендуется изолировать все чувствительные переменные в отдельных зашифрованных файлах, например, в каталоге group_vars/.

Полный набор аргументов утилиты ansible-vault представлен в справочнике.