Ctrl+K
Ctrl+K
Ctrl+K

Ansible Builder

Ansible Builder#

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

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

Установка#

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

  1. Подключите репозиторий Astra Automation.

    Инструкция по подключению репозитория

    1. В каталоге /etc/apt/sources.list.d/ создайте файл astra-automation.list со ссылкой на репозиторий Astra Automation:

      deb https://dl.astralinux.ru/aa/aa-debs-for-alse-1.8 <version> main

      Вместо <version> необходимо подставить версию устанавливаемой платформы, например, 1.2-upd1.

      Доступные версии продукта опубликованы в таблице История обновлений.

    2. Обновите список доступных пакетов:

      sudo apt update

  2. Установите пакет ansible-builder:

    sudo apt install ansible-builder --yes

  3. Установите и настройте Podman (рекомендуется) или Docker.

Установка при отсутствии доступа к интернету описана в документе Средства разработки.

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

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

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

  • version;

  • build_arg_defaults;

  • dependencies;

  • images;

  • additional_build_files;

  • additional_build_steps;

  • options.

Пример заполнения файла определения среды исполнения
execution-environment.yml#
---
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 включает две фазы.

  1. Подготовка контекста сборки при выполнении команды create:

    ansible-builder create

    В результате выполнения этой команды Ansible Builder формирует каталог context/, содержащий файл с командами сборки и вспомогательные материалы. Этот этап не выполняет сборку образа, а лишь подготавливает все необходимые артефакты. Созданная структура необходима для корректной работы инструмента контейнеризации на следующем этапе.

    Содержимое каталога context/ зависит от содержимого файла определения среды исполнения.

    Пример структуры файлов и каталогов контекста#
    context/
├── _build/
│   ├── requirements.yml
│   └── scripts/
│       ├── assemble
│       ├── check_ansible
│       ├── check_galaxy
│       ├── entrypoint
│       ├── install-from-bindep
│       ├── introspect.py
│       └── pip_install
└── Containerfile

    Здесь:

    • Containerfile – файл с инструкциями сборки образа с помощью Podman. Содержит последовательность директив, управляющих сборкой конечного образа.

      Примечание

      При использовании Docker файл называется Dockerfile.

    • _build/requirements.yml – объединенный список зависимостей Ansible, составленный на основе входных данных.

    • _build/scripts/assemble – сценарий сборки окружения. Выполняется на завершающем этапе сборки и объединяет установленные компоненты в рабочее окружение.

    • _build/scripts/check_ansible – проверка корректности установки Ansible в образе.

    • _build/scripts/check_galaxy – проверка доступности и настроек ansible-galaxy внутри образа.

    • _build/scripts/entrypoint – точка входа контейнера. Этот сценарий выполняется при запуске контейнера с собранным образом.

    • _build/scripts/install-from-bindep – установка системных зависимостей, определенных в файле bindep.txt. Используется для обеспечения необходимых библиотек на уровне ОС.

    • _build/scripts/introspect.py – сценарий анализа среды. Выполняет диагностику и подготовку информации о текущем окружении.

    • _build/scripts/pip_install – сценарий для установки модулей Python, указанных в списке зависимостей requirements.txt или других конфигурационных файлах.

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

  2. Сборка образа при выполнении команды build:

    ansible-builder build -t <name>:<tag>

    Здесь <name> и <tag> соответственно название и тег создаваемого образа.

    Внутри этой фазы Ansible Builder передает управление инструменту контейнеризации, который выполняет все инструкции, описанные в Containerfile (при использовании Docker – Dockerfile), и формирует итоговый образ.

    Команда build может быть вызвана сразу, без предварительного выполнения create – в этом случае обе фазы выполняются последовательно: сначала создается контекст сборки, затем запускается сборка образа.

    Пример команды сборки образа#
    ansible-builder build -v 3 -t my-project-ee:1.0.0

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

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

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

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

  2. Galaxy: устанавливает коллекции Ansible, определенные в списке зависимостей.

  3. Builder: устанавливает пакеты Python и системные пакеты, определенные в списке зависимостей.

  4. Final: производит окончательную сборку образа.

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

Все зависимости определяются в настройках блока dependencies. Они определяют пакеты, библиотеки и коллекции, которые необходимо добавить в образ. Для установки зависимостей используется соответствующий инструмент – системный менеджер пакетов, PIP или ansible-galaxy.

Настройка

Описание

Менеджер пакетов

dependencies.ansible_core

Версия Python-пакета ansible-core в формате PEP 508

PIP

dependencies.ansible_runner

Версия Python-пакета ansible-runner в формате PEP 508.

PIP

dependencies.galaxy

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

ansible-galaxy

dependencies.python

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

PIP

dependencies.system

Системные пакеты

Системный менеджер пакетов

Важно

Образы EE, используемые в Astra Automation текущей версии, основаны на операционной системе Astra Linux Special Edition 1.8. При создании новых образов на базе этих EE необходимо обеспечить доступ к репозиториям DEB-пакетов Astra Linux Special Edition 1.8, если вы используете зависимости типа system. Это особенно важно помнить при развертывании платформы Astra Automation в закрытом контуре c использованием Astra Linux Special Edition 1.7.

Операции с файлами#

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

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

additional_build_files:
  - src: <source>
    dest: <target>

Здесь:

  • <source> – путь к файлу или каталогу в локальной файловой системе;

  • <target> – путь назначения внутри контекста сборки, относительно корня каталога context/.

Все файлы, указанные в этой настройке, будут скопированы в соответствующее место в каталоге context/_build и будут доступны во время сборки. Для обращения к этим файлам в additional_build_steps или в командах RUN и COPY внутри Containerfile (при использовании Docker – Dockerfile) укажите относительный путь от корня контекста с указанием каталога _build/.

Например, чтобы скопировать файл ansible.cfg из локальной файловой системы в расположение /etc/ansible/ansible.cfg внутри образа, настройте файл среды исполнения следующим образом:

additional_build_files:
  - src: ansible.cfg
    dest: config/
additional_build_steps:
  prepend_galaxy:
    - COPY _build/config/ansible.cfg /etc/ansible/ansible.cfg

В данном случае файл будет размещен в каталоге context/_build/config/ansible.cfg и будет скопирован в файловую систему образа с помощью инструкции COPY перед выполнением этапа Galaxy.

Дополнительные шаги#

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

Список настроек в порядке выполнения в соответствии с этапами сборки:

  1. prepend_base – до выполнения всех инструкций базового контейнера;

  2. append_base – после выполнения всех инструкций базового контейнера;

  3. prepend_galaxy – до установки зависимостей Ansible;

  4. append_galaxy – после установки зависимостей Ansible;

  5. prepend_builder – до установки зависимостей Python;

  6. append_builder – после установки зависимостей Python;

  7. prepend_final – до финальной сборки;

  8. append_final – после финальной сборки.

Например, с помощью append_builder можно установить дополнительные системные пакеты. В следующем примере после этапа установки требуемых пакетов Python добавляется команда для установки утилиты htop через apt:

additional_build_steps:
  append_builder:
    - RUN apt-get update && apt-get install -y htop

В следующем примере с помощью prepend_final до финального этапа сборки в образ копируется и выполняется пользовательская инструкция:

additional_build_steps:
   prepend_final:
      - COPY scripts/setup.sh /usr/local/bin/setup.sh
      - RUN chmod +x /usr/local/bin/setup.sh && /usr/local/bin/setup.sh

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

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

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

Здесь:

  • <image> – название создаваемого образа;

  • <tag> – метка образа.

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

Особенности использования в окружении без доступа к интернету#

Установка требуемых компонентов в окружении без доступа к Интернету имеет следующие особенности:

  • Для корректной работы PIP необходим доступ к индексу пакетов Python. По умолчанию PIP использует индекс PyPi, доступный по адресу https://pypi.org/simple/. Чтобы использовать собственный индекс, укажите его в формате PEP 503 в одной из переменных окружения:

    • PIP_INDEX_URL – вместо PyPi;

    • PIP_EXTRA_INDEX_URL – в дополнение к PyPi.

    Подробности см. в документации PIP.

  • Для корректной работы системного менеджера пакетов необходим доступ к соответствующему репозиторию или его зеркалу. Настройку системного менеджера пакетов рекомендуется выполнять с помощью команд дополнительного этапа additional_build_steps.prepend_base. Пример настройки см. ниже.

  • Для загрузки зависимостей Ansible с помощью ansible-galaxy укажите в файле ansible.cfg параметры доступа к реестрам коллекций. Пример настройки для загрузки зависимостей Ansible из Private Automation Hub см. ниже.

Примеры#

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

  1. Настройте доступ к Private Automation Hub.

  2. Создайте каталог для хранения файлов проекта.

    Примечание

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

Установка системных пакетов из репозиториев#

Чтобы добавить в образ на базе hub.astra-automation.ru/aa-1.2/aa-minimal-ee:latest пакеты из DEB-репозиториев Astra Linux Special Edition, используйте системный менеджер пакетов:

  1. Определите версию Astra Linux Special Edition, на основе которой построен базовый образ:

    podman run --rm <image>:<tag> cat /etc/astra_version

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

  2. Убедитесь, что соответствующие репозитории Astra Linux Special Edition или их зеркала доступны с локальной машины.

  3. Создайте файл bindep.txt со списком системных пакетов.

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

    execution-environment.yml#
    ---
version: 3
images:
  base_image:
    name: hub.astra-automation.ru/aa-1.2/aa-minimal-ee:latest
dependencies:
  system: bindep.txt
additional_build_steps:
  prepend_base:
    - RUN apt-get update
  append_final:
    - RUN apt-get clean && rm -rf /var/lib/apt/lists/*

    При использовании Ansible Builder в закрытом контуре добавьте в блок additional_build_steps.prepend_base дополнительные шаги по настройке APT на работу с собственными зеркалами репозиториев, например:

    execution-environment.yml#
    ---
version: 3
images:
  base_image:
    name: hub.astra-automation.ru/aa-1.2/aa-minimal-ee:latest
dependencies:
  system: bindep.txt
additional_build_steps:
  prepend_base: |
    RUN echo 'deb https://dl.local/astra/stable/main-repository 1.8_x86-64 main non-free contrib' | tee /etc/apt/sources.list
    RUN echo 'deb https://dl.local/astra/stable/extended-repository 1.8_x86-64 main non-free-contrib' | tee -a /etc/apt/sources.list
    RUN apt-get update
  append_final:
    - RUN apt-get clean && rm -rf /var/lib/apt/lists/*

    Здесь:

    1. На дополнительном шаге prepend_base содержимое файла /etc/apt/sources.list заменяется ссылками на локальные зеркала репозиториев, после чего обновляется список доступных пакетов. Это обеспечивает возможность установки с помощью APT пакетов, указанных в файле системных зависимостей bindep.txt.

    2. На этапе prepend_base кеш APT очищается, тем самым позволяя уменьшить размер образа.

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

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

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

  1. Создайте файл зависимостей Python requirements.txt и заполните его в соответствии с требованиями PEP 508, например:

    requirements.txt#
    yamllint
black==24.10.0

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

    execution-environment.yml#
    ---
version: 3
images:
  base_image:
    name: hub.astra-automation.ru/aa-1.2/aa-minimal-ee:latest
dependencies:
  python: requirements.txt

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

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

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

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

    requirements.yml#
    ---
collections:
  - name: astra.ald_pro
  - name: astra.nginx
    version: 1.8.2

  2. Загрузите коллекции:

    ansible-navigator exec -- ansible-galaxy collection download -r requirements.yml

    В каталоге проекта будет создан подкаталог collections/, в который будут загружены указанные коллекции.

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

    execution-environment.yml#
    ---
version: 3

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

dependencies:
  galaxy: collections/requirements.yml

  4. Создайте контекст сборки:

    ansible-builder create

  5. Скопируйте загруженные коллекции в контекст сборки:

    cp collections/*.tar.gz context/_build/

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

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

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

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

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

    Примечание

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

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

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

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

    execution-environment.yml#
    ---
version: 3

images:
  base_image:
    name: hub.astra-automation.ru/aa-1.2/aa-minimal-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

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

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

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

  1. Создайте токен для доступа к Private Automation Hub согласно инструкции.

  2. Создайте подкаталог files/, а в нем – файл ansible.cfg с настройками подключения к репозиториям Private Automation Hub, например:

    ansible.cfg#
    [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.

  3. Создайте файл зависимостей 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

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

    execution-environment.yml#
    ---
version: 3

dependencies:
  galaxy: requirements.yml

images:
  base_image:
    name: hub.astra-automation.ru/aa-1.2/aa-minimal-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.

  5. Экспортируйте токен для доступа к Private Automation Hub в соответствующую переменную окружения:

    export ANSIBLE_GALAXY_SERVER_VALIDATED_TOKEN=<token>

  6. Запустите сборку образа, передав в аргументе --build-arg название переменной окружения, в которой хранится токен для доступа к Private Automation Hub:

    ansible-navigator builder build \
  -t <image>:<tag> \
  --build-arg ANSIBLE_GALAXY_SERVER_VALIDATED_TOKEN
Содержание