Ansible Builder#

Ansible Builder – это инструмент командной строки, предназначенный для создания образов среды исполнения (EE, execution environment) с использованием метаданных, указанных в специальном файле определения среды исполнения.

Для управления средами исполнения (контейнерами) рекомендуется использовать Podman.

Установка#

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

Подключите репозиторий Astra Automation.
Инструкция по подключению репозитория
1. В каталоге /etc/apt/sources.list.d/ создайте файл astra-automation.list со ссылкой на репозиторий Astra Automation:
  deb https://dl.astralinux.ru/aa/aa-debs-for-alse-1.7 <version> main
  Вместо <version> необходимо подставить версию устанавливаемой платформы, например, 1.1-upd1.
  
  Доступные версии продукта опубликованы в таблице История обновлений.
2. Обновите список доступных пакетов:
  sudo apt update
Установите пакет ansible-builder:
```
sudo apt install ansible-builder --yes
```
Установите Podman (рекомендуется) или Docker.

Важно

Для управления средами исполнения (контейнерами) рекомендуется использовать Podman. Необходимо учесть, что для корректной работы Podman следует провести дополнительные настройки.
При использовании Docker для корректной работы ansible-builder добавьте активного пользователя в группу docker:
```
sudo usermod -aG docker $USER && newgrp docker
```

Установка при отсутствии доступа к интернету описана в документе Инструменты.

Этапы сборки#

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

Base: использует Docker или Podman для загрузки базового образа, который был определен в файле определения среды исполнения, затем устанавливает версию Python (если она определена и отличается от всех версий Python в базовом образе), pip, ansible-runner и ansible-core или ansible. Все три последующих этапа сборки строятся на выводе этапа Base.
Galaxy: загружает определенные в файле определения среды исполнения коллекции с Galaxy и сохраняет их локально.
Builder: загружает Python-пакеты и системные пакеты, определенные в файле определения среды исполнения, и сохраняет их локально.
Final: производит окончательную сборку образа.

Если необходима настройка размера разделяемой памяти (--shm-size) во время сборки среды исполнения, рекомендуется использовать Docker.

Файл определения среды исполнения#

Файл определения среды исполнения (EE definition) определяет содержимое, которое будет включено в образ контейнера. По умолчанию этот файл называется execution-environment.yml или execution-environment.yaml и может содержать следующие разделы:

version;
build_arg_defaults;
dependencies;
images;
additional_build_files;
additional_build_steps;
options.

Пример заполнения файла определения среды исполнения:

---
version: 3

build_arg_defaults:
  ANSIBLE_GALAXY_CLI_COLLECTION_OPTS: '--pre'

dependencies:
  ansible_core:
    package_pip: ansible-core==2.15.6
  ansible_runner:
    package_pip: ansible-runner
   galaxy: requirements.yml
   python:
     - six
     - psutil
   system: bindep.txt
   exclude:
     python:
       - docker
     system:
       - python3-Cython

images:
  base_image:
    name: aa-cr.artifactory.astralinux.ru/aa-creator-ee:0.1.0

additional_build_files:
    - src: files/ansible.cfg
      dest: configs

additional_build_steps:
  prepend_base:
    - RUN echo This is a prepend base command!

  prepend_galaxy:
    - COPY _build/configs/ansible.cfg /etc/ansible/ansible.cfg

  prepend_final: |
    RUN whoami
    RUN cat /etc/os-release
  append_final:
    - RUN echo This is a post-install command!
    - RUN ls -la /etc

Версия#

Целочисленное значение, которое задает версию схемы файла определения среды исполнения. Значение по умолчанию – 1. При использовании Ansible Builder версии 3.x файл начинается со следующих строк:

---
version: 3

Аргументы сборки#

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

Аргументы сборки:

ANSIBLE_GALAXY_CLI_COLLECTION_OPTS;
ANSIBLE_GALAXY_CLI_ROLE_OPTS;
PKGMGR_PRESERVE_CACHE.

Подробное описание аргументов см. в справочных данных.

Примечание

Значения, заданные с помощью аргумента --build-arg, имеют более высокий приоритет.

Значения, указанные в build_arg_defaults, будут сохранены в Containerfile (файл определения образа для Podman). Эти значения будут использованы при сборке путем прямого вызова утилиты podman, например:

podman build .

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

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

Возможные параметры:

ansible_core;
ansible_runner;
galaxy;
python;
python_interpreter;
system;
exclude.

`ansible_core`#

Версия пакета ansible-core, который необходимо установить. Значение для pip, может быть в любом формате, поддерживаемом pip.

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

ansible_core:
    package_pip: ansible-core
ansible_core:
    package_pip: ansible-core==2.15.6
ansible_core:
    package_pip: https://github.com/example_user/ansible/archive/refs/heads/ansible.tar.gz

`ansible_runner`#

Версия пакета ansible_runner, которую нужно установить.

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

ansible_runner:
    package_pip: ansible-runner
ansible_runner:
    package_pip: ansible-runner==2.3.2
ansible_runner:
    package_pip: https://github.com/example_user/ansible-runner/archive/refs/heads/ansible-runner.tar.gz

`galaxy`#

Параметр galaxy указывает на файл зависимостей Ansible для следующей команды:

ansible-galaxy collection install -r <requirements>

<requirements> – абсолютный или относительный путь к файлу зависимостей Ansible. Относительный путь начинается от каталога, содержащего файл определения среды исполнения.

Рекомендуемое название файла зависимостей Ansible – requirements.yml.

Пример содержимого файла зависимостей Ansible:

collections:
  - geerlingguy.java
  - kubernetes.core

`Python`#

Параметр python указывает на файл зависимостей Python для следующей команды:

pip install -r <requirements>

<requirements> – абсолютный или относительный путь к файлу зависимостей Python. Относительный путь начинается от каталога, содержащего файл определения среды исполнения.

Рекомендуемое название файла зависимостей Python – requirements.txt.

Содержимое файла зависимостей Python должно удовлетворять требованиям менеджера пакетов PIP.

`python_interpreter`#

Параметр определяет название системного пакета Python, который будет установлен ( package_system), или путь к интерпретатору Python, который будет использоваться ( python_path).

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

python_interpreter:
    package_system: "python310"
    python_path: "/usr/bin/python3.10"

`system`#

Параметр определяет системные пакеты в формате bindep (binary dependency), которые необходимо установить. Это может быть название файла или список требований.

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

system: bindep.txt

`exclude`#

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

Возможные параметры:

python – список зависимостей Python.
system – список системных зависимостей.
all_from_collections – исключить все зависимости Python и системы из одной или нескольких коллекций. Укажите список названий коллекций в этом параметре.

Для простого сопоставления названий необходимо указать название требования или коллекции для сопоставления. Все значения будут сравниваться без учета регистра.

Для расширенного сопоставления названий начните строку исключения с символа тильды (~), чтобы указать, что оставшаяся часть строки является регулярным выражением, которое будет использоваться для сопоставления названия требования или коллекции. Регулярное выражение не чувствительно к регистру.

Примечание

Регулярное выражение должно соответствовать полному названию требования или коллекции. Например, ~foo. не полностью соответствует названию foobar, а ~foo.+ – соответствует.

При обеих формах сопоставления строка исключения будет сравниваться с простым названием зависимости Python или системы. Например, если вам нужно исключить системное требование, которое отображается как foo [!platform:gentoo] внутри включенной коллекции, то ваша строка исключения должна быть foo. Чтобы исключить требование Python bar == 1.0.0, строка должна иметь значение bar.

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

dependencies:
 exclude:
     python:
         - docker
     system:
         - python3-Cython
     all_from_collections:
         # Regular expression to exclude all from community collections
         - ~community\..+

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

dependencies:
 python: requirements.txt
 system: bindep.txt
 galaxy: requirements.yml
 ansible_core:
     package_pip: ansible-core==2.15.6
 ansible_runner:
     package_pip: ansible-runner==2.3.1
 python_interpreter:
     package_system: "python310"
     python_path: "/usr/bin/python3.10"

В этом примере используются встроенные значения:

dependencies:
 python:
   - pywinrm
 system:
   - iputils [platform:rpm]
 galaxy:
   collections:
     - name: community.windows
     - name: ansible.utils
       version: 2.10.1
 ansible_core:
     package_pip: ansible-core==2.15.6
 ansible_runner:
     package_pip: ansible-runner==2.3.1
 python_interpreter:
     package_system: "python310"
     python_path: "/usr/bin/python3.10"

Образ#

В разделе image указывается базовый образ, который будет использоваться для сборки контейнера.

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

images:
  base_image:
    name: aa-cr.artifactory.astralinux.ru/aa-creator-ee:0.1.0

`additional_build_files`#

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

Каждый элемент списка должен быть словарем, содержащим следующие (необязательные) ключи:

src – путь к исходному файлу или директории, который необходимо добавить в контекст сборки. Это может быть либо абсолютный путь (например, /home/user/.ansible.cfg), либо путь относительно файла среды исполнения. Относительные пути могут быть глобальным выражением, соответствующим одному или нескольким файлам (например, files/*.cfg).
dest – указывает путь к подкаталогу контекста сборки, который должен содержать исходный файл (например, files/configs). Этот каталог будет создан, если он не существует.

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

additional_build_files:
 - src: files/ansible.cfg
   dest: configs

Дополнительные шаги сборки#

В секции additional_build_steps указываются команды для дополнительных шагов пользовательской сборки.

Команды prepend и append могут быть указаны в секции additional_build_steps. Они добавят в Containerfile команды, которые будут выполняться соответственно до или после выполнения основных шагов сборки.

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

Многострочная запись:

prepend_final: |
   RUN whoami
   RUN cat /etc/os-release

Список:

append_final:
   - RUN echo
   - RUN ls -la /etc

Примеры создания образа среды исполнения#

Изучите использование Ansible Builder на примерах. Предварительно выполните следующие действия:

Настройте доступ к Private Automation Hub.
Создайте каталог проекта и сделайте его текущим, например:
```
mkdir ee-build && cd ee-build
```
Все упомянутые ниже файлы следует создавать в каталоге проекта, если только явно не указано иное.

Установка библиотек Python#

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

Создайте файл execution-environment.yml и в нем укажите параметры образа, в том числе ссылку на образ, используемый в качестве основы:
```
---
version: 3
images:
  base_image:
   name: registry.astralinux.ru/aa/aa-base-ee:0.6.2
dependencies:
  python: requirements.txt
```
Создайте файл requirements.txt и укажите в нем библиотеку Python, которую необходимо добавить в образ, например:
```
yamllint
```
Запустите команду сборки образа:
```
ansible-builder build -t my-ee:0.1.0 -v 3
```
Здесь:
- my-ee – название образа;
- 0.1.0 – версия образа.

Проверьте наличие нового образа с помощью команды:

ansible-navigator images

Добавление коллекции Ansible#

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

Создайте файл зависимостей Ansible requirements.yml, например:
```
---
collections:
  - name: astra.nginx
    version: 1.8.2
```
Здесь:
- name – полное название коллекции, включая пространство имен;
- version – версия коллекции.
Загрузите коллекцию:
```
ansible-navigator exec -- ansible-galaxy collection download -r requirements.yml
```
В каталоге collections появится запрошенная коллекция в формате tar.gz и файл requirements.yml.

Создайте файл execution-environment.yml для настройки Ansible Builder со следующим содержимым:

---
version: 3

images:
  base_image:
    name: registry.astralinux.ru/aa/aa-base-ee:0.6.2

dependencies:
  galaxy: collections/requirements.yml

Создайте контекст сборки:
```
ansible-builder create -v 3
```
Скопируйте коллекцию в контекст сборки, например:
```
cp collections/astra-nginx-1.8.2.tar.gz context/_buid/
```

Создайте новый образ:

ansible-builder build -t my-ee:0.2.0 -v 3

Проверьте наличие нового образа с помощью команды:

ansible-navigator images

Добавление коллекции из защищенного репозитория#

Доступ к приватному репозиторию можно получить разными способами. В данном примере рассматривается использование приватного ключа SSH.

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

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

Примечание

Приватный ключ не должен быть защищен паролем.

В файле execution-environment.yml измените ссылку на файл зависимостей и добавьте строки, обеспечивающие передачу ключа в домашний каталог пользователя root контейнера:

---
version: 3

images:
  base_image:
    name: registry.astralinux.ru/aa/aa-base-ee:0.6.2

dependencies:
  galaxy: requirements.yml

additional_build_files:
  - src: id_rsa
    dest: ssh

additional_build_steps:
  prepend_galaxy: |
    RUN mkdir /root/.ssh/
    RUN printf 'Host hub.astra-automation.ru\n\tIdentityFile /root/.ssh/id_rsa\nStrictHostKeyChecking no\n' > /root/.ssh/config
    COPY --chmod=0600 ./_build/ssh/id_rsa /root/.ssh/id_rsa
  append_galaxy: |
    RUN rm -rf /root/.ssh

В файле requirements.yml укажите параметры источника коллекции, например:
```
---
collections:
  - name: astra.nginx
    varsion: 1.8.2
```

Создайте новый образ:

ansible-builder build -t my-ee:0.3.0 -v 3

Проверьте наличие нового образа с помощью команды:

ansible-navigator images

Ansible Builder

Содержание

Ansible Builder#

Установка#

Этапы сборки#

Файл определения среды исполнения#

Версия#

Аргументы сборки#

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

ansible_core#

ansible_runner#

galaxy#

Python#

python_interpreter#

system#

exclude#

Образ#

additional_build_files#

Дополнительные шаги сборки#

Примеры создания образа среды исполнения#

Установка библиотек Python#

Добавление коллекции Ansible#

Добавление коллекции из защищенного репозитория#

`ansible_core`#

`ansible_runner`#

`galaxy`#

`Python`#

`python_interpreter`#

`system`#

`exclude`#

`additional_build_files`#