Ansible Builder#
Ansible Builder – это инструмент командной строки, предназначенный для создания образов среды исполнения (EE, execution environment) с использованием метаданных, указанных в специальном файле определения среды исполнения.
Для управления средами исполнения (контейнерами) рекомендуется использовать Podman.
Установка#
Для установки Ansible Builder выполните следующие действия:
Подключите репозиторий Astra Automation.
Инструкция по подключению репозитория
В каталоге
/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
.Доступные версии продукта опубликованы в таблице История обновлений.
Обновите список доступных пакетов:
sudo apt update
Установите пакет
ansible-builder
:sudo apt install ansible-builder --yes
Установите Podman (рекомендуется) или Docker.
Важно
Для управления средами исполнения (контейнерами) рекомендуется использовать Podman. Необходимо учесть, что Podman версии 4.3.1 следует настроить на использование рекомендуемого драйвера хранилища.
При использовании Podman для корректной работы
ansible-builder
добавьте в секцию[engine]
конфигурационного файла.config/containers/containers.conf
строку:cgroup_manager = "cgroupfs"
Если такой файл отсутствует, создайте его.
При использовании 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 на примерах. Предварительно выполните следующие действия:
Обеспечьте доступ к реестрам Astra 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 type: git source: ssh://git@hub.astra-automation.ru:2222/aa-gca/ARFA/nginx.git
Здесь:
name
– полное название коллекции, включая пространство имен;type
– тип источника;source
– путь к источнику коллекции.
Загрузите коллекцию:
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.7.1.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 type: git source: ssh://git@hub.astra-automation.ru:2222/aa-gca/ARFA/nginx.git
Создайте новый образ:
ansible-builder build -t my-ee:0.3.0 -v 3
Проверьте наличие нового образа с помощью команды:
ansible-navigator images