Chapter 2. Using Ansible Builder

Procedure

1. Create a directory to store your custom execution environment build artifacts. Any new files created with the following steps are created under this directory.

   $ mkdir $HOME/custom-ee $HOME/custom-ee/files
   $ cd $HOME/custom-ee/

2. Create an execution-environment.yml file that defines the requirements for your custom execution environment.

   Note

   Version 3 of the execution environment definition format is required, so ensure the execution-environment.yml file contains version: 3 explicitly before continuing.

   1. Override the base image to point to the minimal execution environment available in your private automation hub.

   2. Define the additional build files needed to point to any disconnected content sources that will be used in the build process. Your custom execution-environment.yml file should look similar to the following example:

      version: 3
      
      images:
        base_image:
          name: private-hub.example.com/ee-minimal-rhel8:latest
      
      dependencies:
        python: requirements.txt
        galaxy: requirements.yml
      
      additional_build_files:
        - src: files/ansible.cfg
          dest: configs
        - src: files/pip.conf
          dest: configs
        - src: files/hub-ca.crt
          dest: configs
        # uncomment if custom RPM repositories are required
        #- src: files/custom.repo
        #  dest: configs
      
      additional_build_steps:
        prepend_base:
          # copy a custom pip.conf to override the location of the PyPI content
          - ADD _build/configs/pip.conf /etc/pip.conf
          # remove the default UBI repository definition
          - RUN rm -f /etc/yum.repos.d/ubi.repo
          # copy the hub CA certificate and update the trust store
          - ADD _build/configs/hub-ca.crt /etc/pki/ca-trust/source/anchors
          - RUN update-ca-trust
          # if needed, uncomment to add a custom RPM repository configuration
          #- ADD _build/configs/custom.repo /etc/yum.repos.d/custom.repo
      
        prepend_galaxy:
          - ADD _build/configs/ansible.cfg ~/.ansible.cfg
      
      ...

3. Create an ansible.cfg file under the files/ subdirectory that points to your private automation hub.

   $ cat files/ansible.cfg
   [galaxy]
   server_list = private_hub
   
   [galaxy_server.private_hub]
   url = /https://private-hub.example.com/api/galaxy/

4. Create a pip.conf file under the files/ subdirectory which points to the internal PyPI mirror (a web server or something similar to Nexus):

   $ cat files/pip.conf
   [global]
   index-url = https://<pypi_mirror_fqdn>/
   trusted-host = <pypi_mirror_fqdn>

5. Optional: If you use a bindep.txt file to add RPMs the custom execution environment, create a custom.repo file under the files/ subdirectory that points to your disconnected Satellite or other location hosting the RPM repositories. If this step is necessary, uncomment the steps in the example execution-environment.yml file that correspond with the custom.repo file.

   The following example is for the UBI repositories. Other local repositories can be added to this file as well. The URL path might need to change depending on where the mirror content is located on the web server.

   $ cat files/custom.repo
   [ubi-8-baseos]
   name = Red Hat Universal Base Image 8 (RPMs) - BaseOS
   baseurl = http://<ubi_mirror_fqdn>/repos/ubi-8-baseos
   enabled = 1
   gpgkey = file:///etc/pki/rpm-gpg/RPM-GPG-KEY-redhat-release
   gpgcheck = 1
   
   [ubi-8-appstream]
   name = Red Hat Universal Base Image 8 (RPMs) - AppStream
   baseurl = http://<ubi_mirror_fqdn>/repos/ubi-8-appstream
   enabled = 1
   gpgkey = file:///etc/pki/rpm-gpg/RPM-GPG-KEY-redhat-release
   gpgcheck = 1

6. Add the CA certificate used to sign the private automation hub web server certificate. If the private automation hub uses self-signed certificates provided by the installation program

   1. Copy the file /etc/pulp/certs/pulp_webserver.crt from your private automation hub and name it hub-ca.crt.
   2. Add the hub-ca.crt file to the files/ subdirectory.

7. If the private automation hub uses user-provided certificates signed by a certificate authority:

   1. Make a copy of that CA certificate and name it hub-ca.crt.
   2. Add the hub-ca.crt file to the files/` subdirectory.

8. When you have completed the preceding steps, create your python requirements.txt and ansible collection requirements.yml files, with the content needed for your custom execution environment image.

   Note

   Any required collections must already be uploaded into your private automation hub.

   The following files should exist under the custom-ee/ directory, with bindep.txt and files/custom.repo being optional:

   $ cd $HOME/custom-ee
   $ tree .
   .
   ├── bindep.txt
   ├── execution-environment.yml
   ├── files
   │   ├── ansible.cfg
   │   ├── custom.repo
   │   ├── hub-ca.crt
   │   └── pip.conf
   ├── requirements.txt
   └── requirements.yml
   
   1 directory, 8 files

Procedure

1. To build an automation execution environment image, run the following from the command line:

   $ ansible-builder build

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

   For example:

   $ ansible-builder build -f definition-file-name.yml

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

Procedure

1. Log in to Ansible Automation Platform.

2. Create a container registry credential for your private automation hub:

   1. From the navigation panel, select Automation Execution Infrastructure Credentials.
   2. Click Create credential.

   3. Enter your credential information:

      • Name: Enter a name, such as Private Hub Registry.
      • Credential Type: Select Container Registry.
      • Authentication URL: Enter the URL of your private automation hub, such as https://automationhub.example.org.
      • Username: Enter your private automation hub username.
      • Password or Token: Enter your private automation hub password or authentication token.
      • Verify SSL: Clear this checkbox if your private automation hub uses self-signed certificates.
   4. Click Create credential.

3. Update the default execution environments to use images from your private automation hub:

   1. From the navigation panel, select Automation Execution Infrastructure Execution Environments.
   2. Locate the Default execution environment and click to edit it.
   3. In the Image field, update the image path to point to your private automation hub, such as automationhub.example.org/ee-supported-rhel9:latest.
   4. In the Registry Credential field, select the container registry credential that you created.
   5. Click Save execution environment.
   6. Locate the Minimal execution environment and click to edit it.
   7. In the Image field, update the image path to point to your private automation hub, such as automationhub.example.org/ee-minimal-rhel9:latest.
   8. In the Registry Credential field, select the container registry credential that you created.
   9. Click Save execution environment.
   10. Repeat these steps for any other execution environments that you want to update to use images from your private automation hub.

Verification

1. From the navigation panel, select Automation Execution Infrastructure Execution Environments.
2. Verify that your private automation hub execution environments appear in the list.
3. Optional: Create a test job template that uses one of the new execution environments and run it to confirm that automation controller can successfully pull and use the image from your private automation hub.

1. During the base build stage, the specified base image is (optionally) customized with components required by other build stages, including Python, pip, ansible-core, and ansible-runner. The resulting image is then validated to ensure that the required components are available (as they can have already been present in the base image). Ephemeral copies of the resulting customized base image are used as the base for all other build stages.
2. During the galaxy build stage, collections specified by the definition file are downloaded and stored for later installation during the final build stage. Python and system dependencies declared by the collections, if any, are also collected for later analysis.
3. During the builder build stage, Python dependencies declared by collections are merged with those listed in the definition file. This final set of Python dependencies is downloaded and built as Python wheels and stored for later installation during the final build stage.
4. During the final build stage, the previously-downloaded collections are installed, along with system packages and any previously-built Python packages that were declared as dependencies by the collections or listed in the definition file.