Red Hat Summit Red Hat SummitSuporteConsoleDesenvolvedoresComeçar um testeContato

Este conteúdo não está disponível no idioma selecionado.

Chapter 2. Using Ansible Builder

2.1. Installing Ansible Builder
Copiar o link

You can install Ansible Builder using Red Hat Subscription Management (RHSM) to attach your Red Hat Ansible Automation Platform subscription. Attaching your Red Hat Ansible Automation Platform subscription allows you to access subscription-only resources necessary to install ansible-builder. Once you attach your subscription, the necessary repository for ansible-builder is automatically enabled.

Note

You must have valid subscriptions attached on the host before installing ansible-builder.

Procedure

  1. In your terminal, run the following command to activate your Ansible Automation Platform repo: 

    $ dnf config-manager --enable ansible-automation-platform-2.1-for-rhel-8-x86_64-rpms
    Copy to Clipboard Toggle word wrap

  2. Then enter the following command to install Ansible Builder: 

    $ dnf install ansible-builder
    Copy to Clipboard Toggle word wrap

2.2. Building a definition file
Copiar o link

Once you have Ansible Builder installed, we will need to create a definition file which Ansible Builder will use to create your automation execution environment image. The high level process to build an automation execution environment image is for Ansible Builder to read and validate your definition file, then create a Containerfile, and finally pass the Containerfile to Podman which then packages and creates your automation execution environment image. The definition file we will create for Ansible Builder is in yaml format and contains different sections which we will discuss in further detail.

The following is an example of a definition file:

Example 2.1. A definition file

version: 1

build_arg_defaults:
1 

  ANSIBLE_GALAXY_CLI_COLLECTION_OPTS: "-v"

ansible_config: 'ansible.cfg'
2 


dependencies:
3 

  galaxy: requirements.yml
  python: requirements.txt
  system: bindep.txt

additional_build_steps:
4 

  prepend: |
    RUN whoami
    RUN cat /etc/os-release
  append:
    - RUN echo This is a post-install command!
    - RUN ls -la /etc
Copy to Clipboard Toggle word wrap
1
Lists default values for build arguments
2
Specifies the ansible.cfg file path
3
Specifies the location of various requirements files
4
Commands for additional custom build steps

For more information about these definition file parameters, please see this section.

2.3. Executing the build and creating commands
Copiar o link

Prerequisites

  • You have created a definition file

Procedure

To build an automation execution environment image, run: 

$ ansible-builder build
Copy to Clipboard Toggle word wrap

By default, Ansible Builder will look for a definition file named execution-environment.yml but a different file path can be specified as an argument via the -f flag: 

$ ansible-builder build -f definition-file-name.yml
Copy to Clipboard Toggle word wrap

where definition-file-name specifies the name of your definition file.

2.4. Breakdown of definition file content
Copiar o link

A definition file is necessary for building automation execution environments with Ansible Builder, as it specifies the content which will be included in the automation execution environment container image.

The following sections breaks down the different parts of a definition file.

2.4.1. Build args and base image
Copiar o link

The build_arg_defaults section of the definition file is a dictionary whose keys can provide default values for arguments to Ansible Builder. See the following table for a list of values that can be used in build_arg_defaults:

Expand
ValueDescription

ANSIBLE_GALAXY_CLI_COLLECTION_OPTS

  • Allows the user to pass the –pre flag to enable the installation of pre-releases collections
  • -c is the equivalent of setting verify_ssl to false

EE_BASE_IMAGE

Specifies the parent image for the automation execution environment, enabling a new image to be built that is based off of an already-existing image

EE_BUILDER_IMAGE

Specifies the image used for compiling-type tasks

The values given inside build_arg_defaults will be hard-coded into the Containerfile, so these values will persist if podman build is called manually.

Note

If the same variable is specified in the CLI --build-arg flag, the CLI value will take higher precedence.

2.4.2. Ansible config file path
Copiar o link

When using an ansible.cfg file to pass a token and other settings for a private account to an automation hub server, list the config file path (relative to where the definition file is located) as a string to enable it as a build argument in the initial phase of the build.

The ansible.cfg file should be formatted like the following example:

Example 2.2. An ansible.cfg file

[galaxy]
server_list = automation_hub

[galaxy_server.automation_hub]
url=https://cloud.redhat.com/api/automation-hub/
auth_url=https://sso.redhat.com/auth/realms/redhat-external/protocol/openid-connect/token
token=my_ah_token
Copy to Clipboard Toggle word wrap

For more information on how to download a collection from automation hub, please see the related Ansible documentation page.

2.4.3. Dependencies
Copiar o link

2.4.3.1. Galaxy
Copiar o link

The galaxy entry points to a valid requirements file for the ansible-galaxy collection install -r …​ command.

The entry requirements.yml may be a relative path from the directory of the automation execution environment definition’s folder, or an absolute path.

The content of a requirements.yml file may look like the following:

Example 2.3. A requirements.yml file for Galaxy

collections:
  - geerlingguy.java
  - kubernetes.core
Copy to Clipboard Toggle word wrap

2.4.3.2. Python
Copiar o link

The python entry in the definition file points to a valid requirements file for the pip install -r …​ command.

The entry requirements.txt is a file that installs extra Python requirements on top of what the Collections already list as their Python dependencies. It may be listed as a relative path from the directory of the automation execution environment definition’s folder, or an absolute path. The contents of a requirements.txt file should be formatted like the following example, similar to the standard output from a pip freeze command:

Example 2.4. A requirements.txt file for Python

boto>=2.49.0
botocore>=1.12.249
pytz
python-dateutil>=2.7.0
awxkit
packaging
requests>=2.4.2
xmltodict
azure-cli-core==2.11.1
python_version >= '2.7'
collection community.vmware
google-auth
openshift>=0.6.2
requests-oauthlib
openstacksdk>=0.13
ovirt-engine-sdk-python>=4.4.10
Copy to Clipboard Toggle word wrap

2.4.3.3. System
Copiar o link

The system entry in the definition points to a bindep requirements file, which will install system-level dependencies that are outside of what the collections already include as their dependencies. It may be listed as a relative path from the directory of the automation execution environment definition’s folder, or an absolute path.

To demonstrate this, the following is an example bindep.txt file that adds the libxml2 and subversion packages to a container:

Example 2.5. A bindep.txt file

libxml2-devel [platform:rpm]
subversion [platform:rpm]
Copy to Clipboard Toggle word wrap

2.4.4. Additional custom build steps
Copiar o link

The prepend and append commands may be specified in the additional_build_steps section. These will add commands to the Containerfile which will run either before or after the main build steps are executed.

The syntax for additional_build_steps must be one of the following:

  • a multi-line string

    Example 2.6. A multi-line string entry

    RUN whoami
RUN cat /etc/os-release
    Copy to Clipboard Toggle word wrap

  • a list

    Example 2.7. A list entry

    - RUN echo This is a post-install command!
- RUN ls -la /etc
    Copy to Clipboard Toggle word wrap

2.5. Optional build command arguments
Copiar o link

The -t flag will give your automation execution environment image a specific name. For example, the following command will build an image named my_first_ee_image: 

$ ansible-builder build -t my_first_ee_image
Copy to Clipboard Toggle word wrap

If you have multiple definition files, you can specify which one to use by utilizing the -f flag: 

$ ansible-builder build -f another-definition-file.yml -t another_ee_image
Copy to Clipboard Toggle word wrap

In the example above, Ansible Builder will use the specifications provided in the file another-definition-file.yml instead of the default execution-environment.yml to build an automation execution environment image named another_ee_image.

For other specifications and flags that are possible to use with the build command, enter ansible-builder build --help to see a list of additional options.

2.6. Creating a Containerfile without building an image
Copiar o link

To create a shareable Containerfile without building an image from it, run: 

$ ansible-builder create
Copy to Clipboard Toggle word wrap
Voltar ao topo
Red Hat logoGithubredditYoutubeTwitter

Aprender

Experimente, compre e venda

Comunidades

Sobre a documentação da Red Hat

Ajudamos os usuários da Red Hat a inovar e atingir seus objetivos com nossos produtos e serviços com conteúdo em que podem confiar. Explore nossas atualizações recentes.

Tornando o open source mais inclusivo

A Red Hat está comprometida em substituir a linguagem problemática em nosso código, documentação e propriedades da web. Para mais detalhes veja o Blog da Red Hat.

Sobre a Red Hat

Fornecemos soluções robustas que facilitam o trabalho das empresas em plataformas e ambientes, desde o data center principal até a borda da rede.

Theme

© 2025 Red Hat