Creating and using execution environments

1. Lists default values for build arguments.
2. Specifies the location of various requirements files.
3. Specifies the base image to be used. Red Hat support is only provided for the redhat.registry.io base image.
4. Specifies options that can affect builder runtime functionality.
5. Commands for additional custom build steps.

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/

   Copy to Clipboard Toggle word wrap

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
      
      ...

      Copy to Clipboard Toggle word wrap

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/

   Copy to Clipboard Toggle word wrap

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

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

   Copy to Clipboard Toggle word wrap

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

   Copy to Clipboard Toggle word wrap

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 installer:

   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

   Copy to Clipboard Toggle word wrap

Procedure

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

   $ ansible-builder build

   Copy to Clipboard Toggle word wrap

   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

   Copy to Clipboard Toggle word wrap

   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 may 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.

Procedure

1. Log in to registry.redhat.io using Podman:

   $ podman login -u="[username]" -p="[token/hash]" registry.redhat.io

   Copy to Clipboard Toggle word wrap

2. Ensure that you can pull the required automation execution environment base image:

   podman pull registry.redhat.io/ansible-automation-platform-24/ee-minimal-rhel8:latest

   Copy to Clipboard Toggle word wrap

3. Configure your Ansible Builder files to specify the required base image and any additional content to add to the new execution environment image.

   1. For example, to add the Kubernetes Core Collection from Galaxy to the image, use the Galaxy entry:

      collections:
        - kubernetes.core

      Copy to Clipboard Toggle word wrap
   2. For more information about definition files and their content, see the Breakdown of definition file content section.

4. In the execution environment definition file, specify the original ee-minimal container’s URL and tag in the EE_BASE_IMAGE field. In doing so, your final execution-environment.yml file appears similar to the following:

   Example 5.1. A customized execution-environment.yml file

   version: 3
   
   images:
     base_image:
       name: 'registry.redhat.io/ansible-automation-platform-25/ee-minimal-rhel9:latest'
   
   dependencies:
     galaxy:
       collections:
         - kubernetes.core

   Copy to Clipboard Toggle word wrap
   Note

   Since this example uses the community version of kubernetes.core and not a certified collection from automation hub, we do not need to create an ansible.cfg file or reference that in our definition file.

5. Build the new execution environment image by using the following command:

   $ ansible-builder build -t [username]/new-ee

   Copy to Clipboard Toggle word wrap

   where [username] specifies your username, and new-ee specifies the name of your new container image.

   Note

   If you do not use -t with build, an image called ansible-execution-env is created and loaded into the local container registry.

   • Use the podman images command to confirm that your new container image is in that list:

     The following shows the output of a 'podman images' command with the image new-ee.

     REPOSITORY          TAG     IMAGE ID      CREATED        SIZE
     localhost/new-ee    latest  f5509587efbb  3 minutes ago  769 MB

     Copy to Clipboard Toggle word wrap

6. Verify that the collection is installed:

   $ podman run [username]/new-ee ansible-doc -l kubernetes.core

   Copy to Clipboard Toggle word wrap

7. Tag the image for use in your automation hub:

   $ podman tag [username]/new-ee [automation-hub-IP-address]/[username]/new-ee

   Copy to Clipboard Toggle word wrap

8. Log in to your automation hub using Podman:

   Note

   You must have admin or appropriate container repository permissions for automation hub to push a container. For more information, see Manage containers in private automation hub.

   $ podman login -u="[username]" -p="[token/hash]" [automation-hub-IP-address]

   Copy to Clipboard Toggle word wrap

9. Push your image to the container registry in automation hub:

   $ podman push [automation-hub-IP-address]/[username]/new-ee

   Copy to Clipboard Toggle word wrap

10. Pull your new image into your automation controller instance:

    1. Go to automation controller.
    2. From the navigation panel, select Automation Execution → Infrastructure → Execution Environments.
    3. Click Add.

    4. Enter the appropriate information then click Save to pull in the new image.

       Note

       If your instance of automation hub is password or token protected, ensure that you have the appropriate container registry credential set up.

Procedure

1. First, verify that the execution environment image can be seen in the local podman cache:

   $ podman images --format "table {{.ID}} {{.Repository}} {{.Tag}}"
   IMAGE ID	    REPOSITORY					              TAG
   b38e3299a65e	private-hub.example.com/custom-ee     	  latest
   8e38be53b486	private-hub.example.com/ee-minimal-rhel8  latest

   Copy to Clipboard Toggle word wrap

2. Then log in to the private automation hub’s container registry and push the image to make it available for use with job templates and workflows:

   $ podman login private-hub.example.com -u admin
   Password:
   Login Succeeded!
   $ podman push private-hub.example.com/custom-ee:latest

   Copy to Clipboard Toggle word wrap

1. Pull execution environments for use in automation hub
2. Tag execution environment for use in automation hub
3. Push an execution environment to private automation hub
4. Set up your container repository
5. Add a README to your container repository
6. Provide access to your automation execution environmentss
7. Tag container images
8. Create a credential
9. Pulling images from a container repository
10. Pull an image
11. Sync images from a container repository