Типовой проект

Использование типовой структуры проектов Ansible позволяет упростить их создание, использование и поддержку.

Структура проекта зависит от того, как в компании организованы стадии развития проекта и где хранится описание инвентаря.

Типовыми стадиями являются разработка (development), промежуточная стадия (staging) и промышленная эксплуатация (production). На каждой стадии используют разное рабочее окружение с соответствующим инвентарем. Для применения проекта к инвентарю существуют следующие типовые подходы:

• проект содержит отдельный файл инвентаря для каждого окружения;

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

• описание инвентаря создается в Automation Controller.

Файлы и каталоги

Структура типового проекта Ansible, для запуска которого используется Automation Controller или Ansible Navigator, имеет следующий вид:

project/
├── playbooks/
│   ├── playbook1.yml
│   ├── playbook2.yml
│   │   ...
│   └── playbookK.yml
├── environments/
│   ├── dev/
│   ├── stage/
│   │   ...
│   └── prod/
│       ├── group_vars/
│       │   ├── main.yml
│       │   ├── smth.yml
│       │   └── smth_else.yml
│       └── inventory.yml
├── vars/
│   ├── vars1.yml
│   ├── vars2.yml
│   │   ...
│   └── varsN.yml
└── files/
    ├── file1
    ├── file2
    │   ...
    └── fileM

Указанные файлы и каталоги используются для следующих целей:

• playbooks/.

  Каталог с файлами наборов сценариев. Под каждый файл создают отдельный шаблон задания в Automation Controller. Если проект содержит только один набор сценариев, допускается разместить файл с ним в корневом каталоге проекта.

• environments/.

  Каталог с файлами для различных окружений. Каталог environments/ содержит отдельные подкаталоги для окружений dev/, stage/, prod/; допускается использовать другой принцип группировки.

  Для каждого окружения можно разместить:

  • файл описания инвентаря, например inventory.yml;

  • каталог group_vars/ с файлами переменных для групп узлов;

  • каталог host_vars/ с файлами переменных для отдельных узлов.

  Примечание

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

  Если проект разрабатывается под одно окружение, каталог environments/ и его подкаталоги можно не создавать, а его содержимое разместить в корневом каталоге проекта:

  Структура проекта для одного окружения

  project/
  ├── playbooks/
  │   ├── playbook1.yml
  │   ├── playbook2.yml
  │   │   ...
  │   └── playbookK.yml
  ├── group_vars/
  │   ├── main.yml
  │   ├── smth.yml
  │   └── smth_else.yml
  ├── host_vars/
  │   ├── node1.yml
  │   └── node2.yml
  ├── inventory.yml
  ├── vars/
  │   ├── vars1.yml
  │   ├── vars2.yml
  │   │   ...
  │   └── varsN.yml
  └── files/
      ├── file1
      ├── file2
      │   ...
      └── fileM
  

  Рекомендуемое название файла описания инвентаря в этом случае – inventory.yml.

• vars/.

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

  Если все переменные хранятся в одном файле, допускается разместить его в корневом каталоге проекта. Рекомендуемое название файла в этом случае – vars.yml.

• files/.

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

• roles/.

  Каталог с ролями, разрабатываемыми в составе проекта. Роли, устанавливаемые как зависимости, размещать в проекте не требуется.

• ansible.cfg.

  Файл настроек Ansible в корневом каталоге проекта, задающий, например, путь к файлу описания инвентаря по умолчанию. Файл используется при локальном запуске проекта, в том числе через Ansible Navigator.

Примечание

Если для указания зависимостей используется файл requirements.yml, поместите его в корневой каталог проекта.

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

Проект Ansible можно организовать несколькими способами. Выбор варианта зависит от того, как разделяются окружения и нужно ли запускать проект одинаково через Ansible Navigator и Automation Controller.

Отдельный файл описания инвентаря для каждого окружения

Используйте этот вариант, если проект ориентирован на постоянный состав окружений. Для каждого окружения создавайте отдельный каталог, например dev/, stage/ и prod/, с собственным файлом инвентаря.

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

project/
├── playbooks/
│   └── site.yml
├── environments/
│   ├── dev/
│   │   ├── inventory.yml
│   │   ├── group_vars/
│   │   │   ├── all.yml
│   │   │   └── web.yml
│   │   └── host_vars/
│   ├── stage/
│   │   ├── inventory.yml
│   │   ├── group_vars/
│   │   └── host_vars/
│   └── prod/
│       ├── inventory.yml
│       ├── group_vars/
│       └── host_vars/
├── vars/
└── files/

В этом варианте каждый файл инвентаря (inventory.yml) содержит описание узлов только для определенного окружения. Переменные из group_vars/ и host_vars/ располагаются в одном каталоге с файлом описания инвентаря соответствующего окружения.

Пример выполнения сценариев автоматизации для окружения dev/ через Ansible Navigator:

ansible-navigator run playbooks/site.yml -i environments/dev/inventory.yml

Аналогично можно запустить исполнение сценариев для другого окружения.

Для запуска такого проекта в Automation Controller создайте отдельное описание инвентаря для каждого окружения и добавьте к нему источник типа Sourced from a Project. В поле Инвентарный файл (Inventory file) укажите путь к файлу описания инвентаря конкретного окружения, например environments/prod/inventory.yml.

Такой вариант удобен, если для окружений нужны разные наборы узлов, разные переменные и разные шаблоны заданий.

Единый файл описания инвентаря с настраиваемыми переменными

Используйте этот вариант, если проекту достаточно одного файла описания инвентаря, а окружения удобно представить через группы узлов.

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

project/
├── playbooks/
│   └── site.yml
├── inventory.yml
├── group_vars/
│   ├── all.yml
│   ├── dev.yml
│   ├── stage.yml
│   └── prod.yml
├── host_vars/
├── vars/
└── files/

Пример файла описания инвентаря:

all:
  children:
    dev:
      hosts:
        dev-node-01.example.com:
    stage:
      hosts:
        stage-node-01.example.com:
    prod:
      hosts:
        prod-node-01.example.com:

Требуемую группу узлов выбирают одним из способов:

• указанием группы узлов в сценарии автоматизации (для каждого окружения необходим свой сценарий или один сценарий с выбором группы с помощью переменной);

• с помощью параметра --limit.

Например, для запуска только на группе prod используйте параметр --limit:

ansible-navigator run playbooks/site.yml -i inventory.yml --limit prod

Для запуска такого проекта в Automation Controller можно использовать один объект описания инвентаря, импортированный из проекта через источник типа Sourced from a Project. Для выбора окружения в шаблоне задания укажите ограничение в поле Лимит (Limit) или включите запрос этого поля при запуске.

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

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

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

Описание инвентаря хранится в Automation Controller

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

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

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

Для локальной отладки через Ansible Navigator можно использовать отдельный локальный файл описания инвентаря, который не применяется в Automation Controller:

project/
├── playbooks/
│   └── site.yml
├── roles/
├── vars/
├── files/
└── local-inventory.yml

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

ansible-navigator run playbooks/site.yml -i local-inventory.yml

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

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

Сравнение вариантов

Вариант	Когда использовать	Особенности
Отдельный файл описания инвентаря для каждого окружения	Окружения изолированы и сопровождаются в репозитории Git	Удобно импортировать каждое окружение в Automation Controller как отдельный источник Sourced from a Project. Переменные group_vars/ и host_vars/ располагаются рядом с файлом описания инвентаря окружения.
Единый файл описания инвентаря с группами окружений	Все окружения можно описать в одном файле и выбирать через limit	Удобно использовать один шаблон задания с разными ограничениями запуска. Требуется аккуратно контролировать поле Лимит (Limit).
Описание инвентаря хранится в Automation Controller	Узлы, группы и переменные сопровождаются в интерфейсе платформы	Файл описания инвентаря в проекте не нужен для запуска через Automation Controller. Переменные из group_vars/ рядом с локальным файлом описания инвентаря не используются автоматически.

Рекомендуемый порядок действий

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

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

2. Выберите способ организации описания инвентаря.

   Если проект должен одинаково запускаться через Ansible Navigator и Automation Controller, храните файл описания инвентаря в репозитории Git и импортируйте его в Automation Controller через источник типа Sourced from a Project.

   Если описание инвентаря должно сопровождаться администраторами платформы, создавайте его в Automation Controller и храните в проекте только наборы сценариев, роли и вспомогательные файлы.

3. Разработайте код и отладьте его с помощью Ansible Navigator. В производственной среде в качестве EE рекомендуется использовать образ aa-full-ee. Если он не содержит необходимых коллекций, создайте собственный образ EE и опубликуйте его в приватном реестре образов, как описано в документе Загрузка образов среды исполнения.

4. Опубликуйте код проекта в системе управления исходным кодом (SCM, Source Code Management).

Применение проекта

Для запуска проекта рекомендуется использовать Automation Controller или Ansible Navigator.

Automation Controller

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

1. Создайте полномочия нужного типа, следуя инструкции.

   Понадобятся как минимум следующие полномочия:

   Тип полномочия	Тип ресурса
   Container Registry	Private Automation Hub
   Source Control	Система управления исходным кодом, в которой хранится проект
   Machine	Управляемые узлы
   Vault	Секреты, зашифрованные с помощью Ansible Vault

2. Добавьте в Automation Controller образ среды исполнения, следуя инструкции по загрузке образов.

3. Создайте проект согласно инструкции по созданию проектов.

4. Подготовьте описание инвентаря одним из способов:

   • импортируйте файл описания инвентаря из проекта через источник типа Sourced from a Project;

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

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

   Подробнее см. Исполнение проекта в Automation Controller.

5. Используйте набор сценариев из проекта для создания шаблона задания.

6. Запустите задание, следуя инструкции по запуску заданий на основе шаблона.

Ansible Navigator

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

1. Загрузите код проекта в рабочий каталог.

2. Создайте в корневом каталоге проекта файл ansible.cfg, в котором укажите необходимые настройки, например путь к файлу описания инвентаря. Образ среды исполнения задается в файле настроек ansible-navigator.yml или с помощью параметра --eei при запуске.

3. Для запуска набора сценариев используйте команду:

   ansible-navigator run --eei <image> path/to/playbook.yml
   

   Здесь:

   • <image> – название образа среды исполнения, используемого для запуска заданий;

   • path/to/playbook.yml – путь к файлу набора сценариев относительно корневого каталога проекта.

Если файл описания инвентаря не задан в ansible.cfg, укажите его при запуске через параметр -i:

ansible-navigator run --eei <image> playbooks/site.yml -i environments/prod/inventory.yml

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

ansible-navigator run --eei <image> playbooks/site.yml -i inventory.yml --limit prod