Последовательность разработки#

Разработка кода Ansible состоит из следующих этапов:

Настройка среды разработки.
Создание структуры проекта.
Разработка кода.
Отладка.
Разработка тестов.
Подготовка к использованию в производственной среде.

Последовательность этапов может отличаться в зависимости от принятого подхода к разработке. На каждом из этих этапов потребуются инструменты, содержащиеся в образе aa-cdk.

Настройка среды разработки#

Проект по разработке контента Ansible необходимо проводить в Visual Studio Code (VS Code). Проект требует предварительной настройки, которую можно выполнить различными способами, один из которых приведен далее:

Создайте рабочий каталог и откройте его в VS Code.
В рабочем каталоге создайте каталог .devcontainer/ и а в нем файл devcontainer.json со следующим содержимым:
```
{
   "name": "Astra Automation Content Development Environment",
   "image": "hub.astra-automation.ru/aa-1.2/aa-cdk:latest",
   "containerUser": "root",
   "privileged": true,
   "customizations": {
      "vscode": {
         "extensions": ["redhat.ansible", "ms-azuretools.vscode-docker"]
      }
   }
}
```
Примечание

В поле image необходимо указать путь к требуемому образу aa-cdk в любом реестре контейнеров, где он доступен.
Если еще не установлено расширение Dev Containers, VS Code предложит установить расширение Dev Containers. Установите его. Если вы не заметили это уведомление, и расширение не установлено, найдите его в магазине расширений и установите.

Для переключения на использование Podman в качестве системы контейнеризации перейдите в настройки расширения и измените значение параметра Docker Path на podman:
Откройте рабочий каталог в контейнере. Один из способов это сделать – нажать комбинацию клавиш CTRL+SHIFT+P и выбрать Dev Containers: Reopen in Container.

Если вы настраиваете первый такой проект на рабочей станции, в результате этого действия VS Code выполнит следующие операции:
- загрузит образ контейнера aa-cdk из указанного реестра;
- запустит контейнер aa-cdk с подключением (монтированием) к нему каталога проекта;
- установит расширения:
  - Ansible;
  - Docker.
VS Code подключится к контейнеру и все дальнейшие действия будут происходить в его среде.

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

Создание структуры проекта#

Расширение Ansible в VS Code позволяет подготовить типовую структуру каталога для разработки коллекции или playbook. Для этого оно использует утилиту ansible-creator из состава Astra Automation CDK.

Для создания структуры откройте страницу настройки Ansible Development Tools и следуйте следующим рекомендациям в зависимости от типа контента, который вы будете создавать.

../../_images/vscode-playbook-project.png

Создание playbook#

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

В настройках инструментов выберите Playbook project.
Задайте необходимые параметры:
- Destination directory: путь к каталогу проекта внутри контейнера (рекомендуется /workspaces, чтобы сохранить также на рабочей станции);
- Namespace: название пространства имен, например, «my_company»;
- Collection: название коллекции, например, «my_collection».
Установите опцию Overwrite. Это необходимо для обновления файла .devcontainer/devcontainer.json.
Нажмите кнопку Create. Расширение создает необходимую структуру проекта для разработки playbook.

Создание коллекции#

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

В настройках инструментов выберите Collection project.
Задайте необходимые параметры:
- Namespace: название пространства имен, например, «my_company»;
- Collection: название коллекции, например, «my_collection»;
- Init path: путь для создания коллекции внутри контейнера (рекомендуется /workspaces).
Установите опцию Overwrite. Это необходимо для обновления файла .devcontainer/devcontainer.json.
Нажмите кнопку Create. В рабочем каталоге создается структура коллекции.

Дополнительные действия#

В результате создания структуры проекта обновляется файл .devcontainer/devcontainer.json в каталоге проекта.

Если разработка ведется в Microsoft Windows, необходимо добавить следующую строку в этом файле:

"privileged": true,

VS Code обнаружит обновленный файл .devcontainer/devcontainer.json и предложит пересоздать контейнер, с чем следует согласиться. Если соответствующее уведомление пропущено, нужно сделать это вручную, открыв палитру команд сочетанием клавиш CTRL+SHIFT+P и выбрав пункт Rebuild Container.

Разработка кода#

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

Зависимости#

Разрабатываемый код Ansible может зависеть от сторонних компонентов – коллекций Ansible и модулей Python. Установите эти компоненты в образе aa-cdk следующим образом:

Создайте файлы, описывающие зависимости вашего проекта:
- requirements.yml – перечень необходимых коллекций Ansible;
- requirements.txt – перечень необходимых модулей Python.
Для установки требуемых компонентов нажмите комбинацию клавиш Ctrl+Shift+P и выберите Create New Terminal (With Profile). VS Code откроет встроенный терминал. Убедитесь, что вы находитесь в командной строке контейнера, о чем свидетельствует приглашение вида:
```
root@ansible-dev-container:
```
Установите требуемые компоненты стандартными командами:
```
ansible-galaxy install -r requirements.yml
```
```
pip install -r requirements.txt
```

Примечание

Повторяйте приведенные шаги по мере изменения списка зависимостей.
Все последующие действия в командной строке, которые приводятся в этой инструкции, выполняются в оболочке контейнера aa-cdk, аналогично тому, как описано ранее. Описание процесса запуска оболочки в среде aa-cdk в последующих примерах будет опущена.

Проверка#

Во время разработки система будет автоматически проверять код в редакторе на наличие ошибок. Для этого расширение Ansible использует утилиту ansible-lint из состава Astra Automation CDK. Вы можете также вызывать эту утилиту вручную из командной строки. Подробнее о ее использовании см. Ansible Lint.

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

Отладка#

Для проверки и отладки кода Ansible в контейнере aa-cdk предусмотрены несколько способов.

Использование ansible-navigator#

Использование ansible-navigator для запуска и отладки playbook является рекомендованным способом. Эта утилита позволяет запускать код Ansible в двух режимах:

В том окружении, где она непосредственно установлена (рекомендуется на этапе отладки). В данном случае – это среда контейнера aa-cdk, содержащая надежные проверенные утилиты.
В среде исполнения (рекомендуется в производственном процессе).

При создании структуры проекта расширение Ansible создает файл .vscode/settings.json:

{
   "ansible.executionEnvironment.enabled": true,
   "ansible.executionEnvironment.image": "hub.astra-automation.ru/aa-1.2/aa-full-ee:latest",
}

В поле ansible.executionEnvironment.enabled необходимо установить значение false. Это означает, что ansible-navigator будет запускать файлы «локально» в контейнере aa-cdk, как требуется на этапе отладки.

Для запуска playbook с помощью ansible-navigator в интерфейсе VS Code достаточно кликнуть правой клавишей мыши в тексте playbook или на названии файла и выбрать пункт Run Ansible Playbook via… > Run playbook via ansible-navigator.

Ansible Navigator имеет удобные средства отладки для каждой задачи в playbook. После (или во время) выполнения кода можно перемещаться по списку задач и наблюдать весь контекст их запуска, включая значения переменных и другие метаданные. Подробности смотрите в описании Ansible Navigator.

Использование ansible-playbook#

В образе aa-cdk сохранена возможность непосредственного запуска playbook с помощью утилиты ansible-playbook. Вы можете запускать ее следующими способами:

из командной строки служебного контейнера:
```
ansible-playbook -i <inventory> <playbook.yml>
```
из редактора VS Code, кликнув правой клавишей мыши на файле playbook и выбрав Run Ansible Playbook via… > Run playbook via ansible-playbook.

Разработка тестов#

Для тестирования коллекций в контейнере установлено средство тестирования Molecule.

При создании структуры проекта для разработки коллекции в рабочем каталоге уже присутствует шаблон конфигурации для Molecule и тестовый playbook molecule/utils/playbooks/coverge.yml, а также другие файлы. Этот шаблон предусматривает проверки в локальной среде тестирования, однако Molecule в составе Astra Automation CDK поставляется с набором драйверов для различных систем виртуализации, в том числе:

molecule-yandex;
molecule-brest;
molecule-libvirt.

Запускать тесты Molecule рекомендуется в среде контейнера aa-cdk, находясь в корне рабочего каталога, с помощью следующей команды:

molecule test

Подготовка к использованию в производственной среде#

До этого момента запуск разрабатываемого кода происходил в контейнере aa-cdk. При применении проекта в Automation Controller для запуска необходимо использовать среду исполнения, в которой предварительно установлены все компоненты инфраструктурного кода, необходимые для проекта.

Использование среды исполнения дает ряд преимуществ:

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

Сборка среды исполнения#

Для сборки требуемой среды исполнения образ aa-cdk содержит утилиту ansible-builder из состава Astra Automation CDK.

Используйте ее для создания нового образа среды исполнения:

Создайте в корне каталога проекта файл execution-environment.yml со следующим содержимым:
```
---
version: 3

images:
  base_image:
    name: hub.astra-automation.ru/aa-1.2/aa-minimal-ee:1.0.4

dependencies:
  python: requirements.txt
  galaxy: requirements.yml

additional_build_files:
  - src: ansible.cfg
    dest: configs

additional_build_steps:
   prepend_galaxy:
     - COPY _build/configs/ansible.cfg /etc/ansible/ansible.cfg
     - ARG ANSIBLE_GALAXY_SERVER_VALIDATED_TOKEN
```
Здесь:
- aa-minimal-ee – образ, рекомендуемый для сборки собственных образов исполнения;
- dependencies – список файлов с зависимостями, указывающими на компоненты, которые требуется установить в среду исполнения.
Для получения коллекций из приватного реестра коллекций передайте значение токена в переменную среды ANSIBLE_GALAXY_SERVER_VALIDATED_TOKEN. Используйте сохраненный ранее токен доступа к реестру коллекций или создайте новый.
```
export ANSIBLE_GALAXY_SERVER_VALIDATED_TOKEN=<your_token>
```
Создайте файл ansible.cfg, в котором укажите адреса репозиториев, содержащих требуемые коллекции Ansible. Подробный пример приведен в секции Добавление коллекций из Private Automation Hub.
Для сборки среды выполните следующую команду в среде aa-cdk:
```
ansible-builder build -t my-ee:0.0.1 --build-arg ANSIBLE_GALAXY_SERVER_VALIDATED_TOKEN
```

Проверка работы в среде исполнения#

Для проверки работы проекта с помощью ansible-navigator в созданной среде исполнения необходимо выполнить следующие действия:

Приведите файл .vscode/settings.json к следующему виду:

{
   "ansible.executionEnvironment.enabled": true,
   "ansible.executionEnvironment.image": "localhost/my-ee:0.0.1",
}

Выполните playbook с помощью ansible-navigator.

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

Публикация среды исполнения#

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

Авторизуйтесь в приватном реестре:
```
podman login -u=<username> -p=<password> <hub>
```
Задайте образу правильное название, которое содержит доменное имя приватного реестра (<hub>):
```
podman tag my-ee:0.0.1 <hub>/my-ee:0.0.1
```
Загрузите образ в приватный реестр:
```
podman push <hub>/my-ee:0.0.1
```

Публикация коллекции#

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

Упакуйте коллекцию в формате tarball, выполнив следующую команду в среде контейнера aa-cdk:
```
ansible-galaxy collection build
```
Эта команда создает файл с расширением .tar.gz – архив коллекции.
Настройте утилиту ansible-galaxy из состава aa-cdk на работу с приватным реестром, как описано в настройке проекта.
Загрузите упакованную коллекцию в реестр коллекций командой:
```
ansible-galaxy collection publish --server https://<hub>/<repository> <file-name>.tar.gz [--token <token>]
```
Здесь:
- <hub> – доменное имя приватного реестра коллекций.
- <repository> – полный путь к репозиторию, в котором необходимо разместить коллекцию. Репозиторий должен быть создан заранее с помощью графического пользовательского интерфейса. Если необходимо согласование, то подставьте api/galaxy.
- <file-name> – название файла, содержащего упакованную коллекцию.
- <token> – токен доступа к приватному реестру.
Токен доступа к приватному реестру можно предоставить различными способами:
- в командной строке (не рекомендуется, поскольку это наименее защищенный способ);
- поместив его в ansible.cfg.

Публикация проекта#

После разработки playbook его следует сделать доступным в системе контроля исходного кода (SCM, Source Code Management), в качестве которой обычно используется Git. Playbook должен быть помещен в репозиторий SCM в составе отдельного проекта или добавлен в существующий проект вместе с сопутствующими каталогами и файлами. В таком виде он будет доступен для дальнейшего использования в Automation Controller.

Заключение#

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

Последовательность разработки

Содержание

Последовательность разработки#

Настройка среды разработки#

Создание структуры проекта#

Создание playbook#

Создание коллекции#

Дополнительные действия#

Разработка кода#

Зависимости#

Проверка#

Отладка#

Использование ansible-navigator#

Использование ansible-playbook#

Разработка тестов#

Подготовка к использованию в производственной среде#

Сборка среды исполнения#

Проверка работы в среде исполнения#

Публикация среды исполнения#

Публикация коллекции#

Публикация проекта#

Заключение#