Ansible Builder#

Ansible Builder – это инструмент командной строки, предназначенный для создания образов контейнеров, используемых в качестве среды исполнения (EE, execution environment). Непосредственное создание образов осуществляется с помощью Podman (рекомендуемый вариант) или Docker (например, когда необходима настройка размера разделяемой памяти, --shm-size).

Создаваемый образ необходимо описать с помощью метаданных в специальном файле определения среды исполнения.

Установка#

Для установки 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.

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

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

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

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

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

Файл определения среды исполнения (EE definition) содержит описание создаваемого образа среды исполнения. По умолчанию Ansible Builder использует для сборки образа описание из файла 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: hub.astra-automation.ru/aa/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

Сборка образа#

Для запуска сборки образа в корневом каталоге проекта выполните команду:

ansible-builder build \
  -t <image>:<tag>

Здесь:

<image> – название создаваемого образа;
<tag> – метка образа.

Полный перечень возможных команд и опций см. в справочнике.

Примеры#

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

Настройте доступ к Private Automation Hub.
Создайте каталог для хранения файлов проекта.

Примечание

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

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

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

Создайте файл зависимостей Python requirements.yml и заполните его в соответствии с требованиями PEP 508, например:
requirements.yml#
```
yamllint
black==24.10.0
```

Файл определения среды исполнения заполните следующим образом:

execution-environment.yml#

---
version: 3
images:
  base_image:
    name: registry.astralinux.ru/aa/aa-base-ee:latest
depdendencies:
  python: requirements.yml

Запустите сборку образа.

Добавление коллекции из архива#

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

Создайте файл со списком зависимостей Ansible, например:
requirements.yml#
```
---
collections:
  - name: astra.ald_pro
  - name: astra.nginx
    version: 1.8.2
```
Загрузите коллекции:
```
ansible-navigator exec -- ansible-galaxy collection download -r requirements.yml
```
В каталоге проекта будет создан подкаталог collections/, в который будут загружены указанные коллекции.

Файл определения среды исполнения заполните следующим образом:

execution-environment.yml#

---
version: 3

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

dependencies:
  galaxy: collections/requirements.yml

Создайте контекст сборки:
```
ansible-builder create
```
Скопируйте загруженные коллекции в контекст сборки:
```
cp collections/*.tar.gz context/_build/
```
Запустите сборку образа.

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

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

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

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

Примечание

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

Создайте файл зависимостей Ansible, например:

requirements.yml#

---
collections:
  - name: my.collection
    url: https://git.example.com/private/my-collection.git

Файл определения среды исполнения заполните следующим образом:

execution-environment.yml#

---
version: 3

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

dependencies:
  galaxy: requirements.yml

additional_build_files:
  - src: id_rsa
    dest: ssh

additional_build_steps:
  prepend_galaxy:
    - RUN mkdir /root/.ssh/
    - RUN printf 'Host git.example.com\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

Запустите сборку образа.

Добавление коллекций из Private Automation Hub#

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

Создайте токен для доступа к Private Automation Hub согласно инструкции.
Создайте подкаталог files/, а в нем – файл ansible.cfg с настройками подключения к репозиториям Private Automation Hub, например:
```
[galaxy]
server_list = galaxy, validated

[galaxy_server.galaxy]
url = https://galaxy.ansible.com/

[galaxy_server.validated]
url = https://private-hub.example.com/api/galaxy/content/validated/
```
Здесь указаны публично доступны репозиторий Ansible Galaxy и репозиторий validated, размещенный в Private Automation Hub.

Создайте файл зависимостей Ansible, например:

requirements.yml#

collections:
  - name: astra.ald_pro
    version: 2.0.0
  - name: astra.cups
    version: 1.3.3
  - name: astra.rubackup
  - name: astra.rupost

Файл определения среды исполнения заполните следующим образом:
execution-environment.yml#
```
---
version: 3

dependencies:
  galaxy: requirements.yml

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

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
```
Для получения доступа к Private Automation Hub используется токен, заданный в переменной окружения ANSIBLE_GALAXY_SERVER_VALIDATED_TOKEN. Значение этой переменной импортируется в образ из хостовой системы.

Название переменной окружения, в которой хранится токен для доступа к реестру, формируется по шаблону:
```
ANSIBLE_GALAXY_SERVER_<NAME>_TOKEN
```
Здесь <NAME> – набранное в верхнем регистре название сервера, указанное в ansible.cfg. Например, если бы серверы назывались published и testing_dev, соответствующие переменные окружения имели бы названия ANSIBLE_GALAXY_SERVER_PUBLISHED_TOKEN и ANSIBLE_GALAXY_SERVER_TESTING_DEV_TOKEN.
Экспортируйте токен для доступа к Private Automation Hub в соответствующую переменную окружения:
```
export ANSIBLE_GALAXY_SERVER_VALIDATED_TOKEN=<token>
```
Запустите сборку образа, передав в аргументе --build-arg название переменной окружения, в которой хранится токен для доступа к Private Automation Hub:
```
ansible-navigator builder build \
  -t <image>:<tag> \
  --build-arg ANSIBLE_GALAXY_SERVER_VALIDATED_TOKEN
```

Ansible Builder

Содержание

Ansible Builder#

Установка#

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

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

Сборка образа#

Примеры#

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

Добавление коллекции из архива#

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

Добавление коллекций из Private Automation Hub#