Chapter 3. Manage containers in private automation hub
Chapter 3. Manage containers in private automation hub Learn the administrator workflows and processes for configuring private automation hub container registry and repositories. 3.1. Manage your private automation hub container registry Manage container image repositories in your Ansible Automation Platform infrastructure by using the automation hub container registry. You can perform the following tasks with Automation hub: Control who can access individual container repositories Change tags on images View activity and image layers Provide additional information related to each container repository 3.1.1. Container registries The automation hub container registry is used for storing and managing container images. When you have built or sourced a container image, you can push that container image to the registry portion of private automation hub to create a container repository. steps Push a container image to the automation hub container registry. Create a group with access to the container repository in the registry. Add the new group to the container repository. Add a README to the container repository to provide users with information and relevant links. 3.2. Configuring user access for container repositories in private automation hub To determine who can access and manage images in your Ansible Automation Platform, you must configure user access for container repositories in your private automation hub. 3.2.1. Container registry group permissions You can control how users can interact with containers managed in private automation hub. Use the following list of permissions to create groups with the right privileges for your container registries. Table 3.1. List of group permissions used to manage containers in private automation hub Permission name Description Create new containers Users can create new containers Change container namespace permissions Users can change permissions on the container repository Change container Users can change information on a container Change image tags Users can modify image tags Pull private containers Users can pull images from a private container Push to existing container Users can push an image to an existing container View private containers Users can view containers marked as private 3.2.2. Creating a new group in private automation hub You can create and assign permissions to a group in private automation hub that enables users to access specified features in the system. By default, the Admin group in the automation hub has all permissions assigned and is available on initial login. Use the credentials created when installing private automation hub. For more information, see Creating a new group in private automation hub in the Getting started with automation hub guide. 3.2.3. Assigning permissions to groups By default, new groups do not have any assigned permissions. You can assign permissions to groups in private automation hub that enable users to access specific features in the system. You can add permissions when first creating a group or edit an existing group to add or remove permissions For more information, see Assigning permissions to groups in the Getting started with automation hub guide. Additional resources See Container registry group permissions to learn more about specific permissions. 3.2.4. Adding users to existing groups You can add users to groups when you create a group. But, you can also manually add users to existing groups. For more information, see Adding users to existing groups in the Getting started with automation hub guide. 3.3. Populating your private automation hub container registry By default, private automation hub does not include container images. To populate your container registry, you must push a container image to it. You must follow a specific workflow to populate your private automation hub container registry: Pull images from the Red Hat Ecosystem Catalog (registry.redhat.io) Tag them Push them to your private automation hub container registry Important As of April 1st, 2025 , quay.io is adding three additional endpoints. As a result, customers must adjust the allow/block lists within their firewall systems lists to include the following endpoints: cdn04.quay.io cdn05.quay.io cdn06.quay.io To avoid problems pulling container images, customers must allow outbound TCP connections (ports 80 and 443) to the following hostnames: cdn.quay.io cdn01.quay.io cdn02.quay.io cdn03.quay.io cdn04.quay.io cdn05.quay.io cdn06.quay.io This change should be made to any firewall configuration that specifically enables outbound connections to registry.redhat.io or registry.access.redhat.com . Use the hostnames instead of IP addresses when configuring firewall rules. After making this change, you can continue to pull images from registry.redhat.io or registry.access.redhat.com . You do not require a quay.io login, or need to interact with the quay.io registry directly in any way to continue pulling Red Hat container images. For more information, see Firewall changes for container image pulls 2024/2025 . Ensure that the Network ports and protocols listed in Table 6.4. Execution Environments (EE) are available to avoid problems pulling container images. 3.3.1. Pulling images for use in automation hub Before you can push container images to your private automation hub, you must first pull them from an existing registry and tag them for use. The following example details how to pull an image from the Red Hat Ecosystem Catalog (registry.redhat.io). Prerequisites You have permissions to pull images from registry.redhat.io. Procedure Log in to Podman by using your registry.redhat.io credentials: USD podman login registry.redhat.io Enter your username and password. Pull a container image: USD podman pull registry.redhat.io/ <container_image_name> : <tag> Verification To verify that the image you recently pulled is contained in the list, take these steps: List the images in local storage: USD podman images Check the image name, and verify that the tag is correct. Additional resources See Red Hat Ecosystem Catalog Help for information on registering and getting images. 3.3.2. Tagging images for use in automation hub After you pull images from a registry, tag them for use in your private automation hub container registry. Prerequisites You have pulled a container image from an external registry. You have the FQDN or IP address of the automation hub instance. Procedure Tag a local image with the automation hub container repository: USD podman tag registry.redhat.io/ <container_image_name> : <tag> <automation_hub_hostname> / <container_image_name> Verification List the images in local storage: USD podman images Verify that the image you recently tagged with your automation hub information is contained in the list. 3.3.3. Pushing a container image to private automation hub You can push tagged container images to private automation hub to create new containers and populate the container registry. Prerequisites You have permissions to create new containers. You have the FQDN or IP address of the automation hub instance. Procedure Log in to Podman using your automation hub location and credentials: USD podman login -u= <username> -p= <password> <automation_hub_url> Push your container image to your automation hub container registry: USD podman push <automation_hub_url> / <container_image_name> Troubleshooting The push operation re-compresses image layers during the upload, which is not guaranteed to be reproducible and is client-implementation dependent. This may lead to image-layer digest changes and a failed push operation, resulting in Error: Copying this image requires changing layer representation, which is not possible (image is signed or the destination specifies a digest) . Verification Log in to your automation hub. Navigate to Container Registry . Locate the container in the container repository list. 3.4. Setting up your container repository When you set up your container repository, you must add a description, include a README, add groups that can access the repository, and tag images. 3.4.1. Prerequisites to setting up your container registry You are logged in to a private automation hub. You have permissions to change the repository. 3.4.2. Adding a README to your container repository Add a README to your container repository to provide instructions to your users on how to work with the container. Automation hub container repositories support Markdown for creating a README. By default, the README is empty. Prerequisites You have permissions to change containers. Procedure Log in to automation hub. From the navigation panel, select Execution Environments Execution Environments . Select your container repository. On the Detail tab, click Add . In the Raw Markdown text field, enter your README text in Markdown. Click Save when you are finished. After you add a README, you can edit it at any time by clicking Edit and repeating steps 4 and 5. 3.4.3. Providing access to your container repository Provide access to your container repository for users who need to work with the images. Adding a group allows you to modify the permissions the group can have to the container repository. You can use this option to extend or restrict permissions based on what the group is assigned. Prerequisites You have change container namespace permissions. Procedure Log in to automation hub. From the navigation panel, select Execution Environments Execution Environments . Select your container repository. From the Access tab, click Select a group . Select the group or groups to which you want to grant access and click . Select the roles that you want to add to this execution environment and click . Click Add . 3.4.4. Tagging container images Tag images to add an additional name to images stored in your automation hub container repository. If no tag is added to an image, automation hub defaults to latest for the name. Prerequisites You have change image tags permissions. Procedure From the navigation panel, select Execution Environments Execution Environments . Select your container repository. Click the Images tab. Click the More Actions icon ... , and click Manage tags . Add a new tag in the text field and click Add . Optional: Remove current tags by clicking x on any of the tags for that image. Click Save . Verification Click the Activity tab and review the latest changes. 3.4.5. Creating a credential in automation controller To pull container images from a password or token-protected registry, you must create a credential in automation controller. In earlier versions of Ansible Automation Platform, you were required to deploy a registry to store execution environment images. On Ansible Automation Platform 2.0 and later, the system operates as if you already have a container registry up and running. To store execution environment images, add the credentials of only your selected container registries. Procedure Navigate to automation controller. From the navigation panel, select Resources Credentials . Click Add to create a new credential. Enter an authorization Name , Description , and Organization . Select the Credential Type . Enter the Authentication URL . This is the container registry address. Enter the Username and Password or Token required to log in to the container registry. Optional: To enable SSL verification, select Verify SSL . Click Save . 3.5. Pulling images from a container repository Pull images from the automation hub container registry to make a copy to your local machine. Automation hub provides the podman pull command for each latest image in the container repository. You can copy and paste this command into your terminal, or use podman pull to copy an image based on an image tag. 3.5.1. Pulling an image You can pull images from the automation hub container registry to make a copy to your local machine. Prerequisites You must have permission to view and pull from a private container repository. Procedure If you are pulling container images from a password or token-protected registry, create a credential in automation controller before pulling the image. From the navigation panel, select Execution Environments Execution Environments . Select your container repository. In the Pull this image entry, click Copy to clipboard . Paste and run the command in your terminal. Verification Run podman images to view images on your local machine. 3.5.2. Syncing images from a container repository You can pull images from the automation hub container registry to sync an image to your local machine. To sync an image from a remote container registry, you must first configure a remote registry. Prerequisites You must have permission to view and pull from a private container repository. Procedure From the navigation panel, select Execution Environments Execution Environments . Add https://registry.redhat.io to the registry. Add any required credentials to authenticate. Note Some container registries are aggressive with rate limiting. Set a rate limit under Advanced Options . From the navigation panel, select Execution Environments Execution Environments . Click Add execution environment in the page header. Select the registry you want to pull from. The Name field displays the name of the image displayed on your local registry. Note The Upstream name field is the name of the image on the remote server. For example, if the upstream name is set to "alpine" and the Name field is "local/alpine", the alpine image is downloaded from the remote and renamed to "local/alpine". Set a list of tags to include or exclude. Syncing images with a large number of tags is time consuming and uses a lot of disk space. Additional resources See Red Hat Container Registry Authentication for a list of registries. See the What is Podman? documentation for options to use when pulling images. 3.6. Working with signed containers Automation execution environments are container images used by Ansible automation controller to run jobs. You can download this content to private automation hub, and publish it within your organization. 3.6.1. Deploying your system for container signing Automation hub implements image signing to offer better security for the execution environment container images. To deploy your system so that it is ready for container signing, create a signing script. Note Installer looks for the script and key on the same server where installer is located. Procedure From a terminal, create a signing script, and pass the script path as an installer parameter. Example : #!/usr/bin/env bash # pulp_container SigningService will pass the 4 variables to the script. MANIFEST_PATH=USD1 FINGERPRINT="USDPULP_SIGNING_KEY_FINGERPRINT" IMAGE_REFERENCE="USDREFERENCE" SIGNATURE_PATH="USDSIG_PATH" # Create container signature using skopeo skopeo standalone-sign \ USDMANIFEST_PATH \ USDIMAGE_REFERENCE \ USDFINGERPRINT \ --output USDSIGNATURE_PATH # Optionally pass the passphrase to the key if password protected. # --passphrase-file /path/to/key_password.txt # Check the exit status STATUS=USD? if [ USDSTATUS -eq 0 ]; then echo {\"signature_path\": \"USDSIGNATURE_PATH\"} else exit USDSTATUS fi Review the Ansible Automation Platform installer inventory file for options for container signing that begin with automationhub_* . [all:vars] . . . automationhub_create_default_container_signing_service = True automationhub_container_signing_service_key = /absolute/path/to/key/to/sign automationhub_container_signing_service_script = /absolute/path/to/script/that/signs Once installation is complete, navigate to your automation hub. From the navigation panel, select Signature Keys . Ensure that you have a key titled container-default , or container - anyname . Note The container-default service is created by the Ansible Automation Platform installer. 3.6.2. Adding containers remotely to automation hub You can add containers remotely to automation hub in one of the following two ways: Create Remotes Execution Environment Procedure Log in to automation hub. From the navigation panel, select Execution Environments Remote Registries . Click Add remote registry . In the Name field, enter the name of the registry where the container resides. In the URL field, enter the URL of the registry where the container resides. In the Username field, enter the username if necessary. In the Password field, enter the password if necessary. Click Save . 3.6.3. Adding an execution environment Automation execution environments are container images that make it possible to incorporate system-level dependencies and collection-based content. Each execution environment allows you to have a customized image to run jobs, and each of them contain only what you need when running the job. Procedure From the navigation panel, select Execution Environments Execution Environments . Click Add execution environment . Enter the name of the execution environment. Optional: Enter the upstream name. Under Registry , select the name of the registry from the drop-down menu. Enter tags in the Add tag(s) to include field. If the field is blank, all the tags are passed. You must specify which repository specific tags to pass. The remaining fields are optional: Currently included tags Add tag(s) to exclude Currently excluded tag(s) Description Click Save . Synchronize the image. 3.6.4. Pushing container images from your local environment Use the following procedure to sign images on a local system and push those signed images to the automation hub registry. Procedure From a terminal, log in to Podman, or any container client currently in use: > podman pull <container-name> After the image is pulled, add tags (for example: latest, rc, beta, or version numbers, such as 1.0; 2.3, and so on): > podman tag <container-name> <server-address>/<container-name>:<tag name> Sign the image after changes have been made, and push it back up to the automation hub registry: > podman push <server-address>/<container-name>:<tag name> --tls-verify=false --sign-by <reference to the gpg key on your local> If the image is not signed, it can only be pushed with any current signature embedded. Alternatively, you can use the following script to push the image without signing it: > podman push <server-address>/<container-name>:<tag name> --tls-verify=false Once the image has been pushed, navigate to your automation hub. From the navigation panel, select Execution Environments Execution Environments . To display the new execution environment, click the Refresh icon. Click the name of the image to view your pushed image. Troubleshooting The details page in automation hub indicates whether or not an image has been signed. If the details page indicates that an image is Unsigned , you can sign the image from automation hub using the following steps: Click the image name to navigate to the details page. Click the More Actions icon ... . Three options are available: Use in Controller Delete Sign Click Sign from the drop-down menu. The signing service signs the image. After the image is signed, the status changes to "signed". 3.6.5. Policies with signed images Policies can be used by podman or other image clients to ensure the validity of the image by assigning specific policies to that signature. 3.6.6. Using podman to ensure an image is signed by a specific signature When ensuring a signature is signed by specific signatures, the signature must be on your local environment. Procedure From the navigation panel, select Signature Keys . Click the More Actions icon ... to the signature that you are using. Select Download key from the drop-down menu. A new window opens. In the Name field, enter the name of the key. Click Save . 3.6.7. Configuring the client to verify signatures To ensure a container image pulled from the remote registry is properly signed, you must first configure the image with the proper public key in a policy file. Prerequisites The client must have sudo privileges configured to verify signatures. Procedure Open your terminal and use the following command: > sudo <name of editor> /etc/containers/policy.json The file that is displayed is similar to this: { "default": [{"type": "reject"}], "transports": { "docker": { "quay.io": [{"type": "insecureAcceptAnything"}], "docker.io": [{"type": "insecureAcceptAnything"}], "<server-address>": [ { "type": "signedBy", "keyType": "GPGKeys", "keyPath": "/tmp/containersig.txt" }] } } } This file shows that neither quay.io , or docker.io will perform the verification, because the type is insecureAcceptAnything which overrides the default type of reject . However, <server-address> will perform the verification, because the parameter type is set to "signedBy" . Note The only keyType currently supported is GPG keys. Under the <server-address> entry, modify the keyPath <1> to include the name of your key file. { "default": [{"type": "reject"}], "transports": { "docker": { "quay.io": [{"type": "insecureAcceptAnything"}], "docker.io": [{"type": "insecureAcceptAnything"}], "<server-address>": [{ "type": "signedBy", "keyType": "GPGKeys", "keyPath": "/tmp/<key file name>", "signedIdentity": { "type": "matchExact" } }] } } } Save and close the file. Verification Pull the file using Podman, or your client of choice: > podman pull <server-address>/<container-name>:<tag name> --tls-verify=false This response verifies the image has been signed with no errors. If the image is not signed, the command fails. Additional resources For more information about policy.json, see documentation for containers-policy.json . 3.7. Deleting a container repository Delete a container repository from your private automation hub to manage your disk space. You can delete repositories from the Red Hat Ansible Automation Platform interface in the Container Repository list view. Prerequisites You have permissions to manage repositories. Procedure Navigate to automation hub. From the navigation panel, select Execution Environments Execution Environments . On the container repository that you want to delete, click the More Actions icon ... , and click Delete . When the confirmation message is displayed, click the checkbox and click Delete . Verification Return to the Execution Environments list view. If the container repository has been successfully deleted, the container repository is no longer on the list.
podman login registry.redhat.io podman pull registry.redhat.io/ <container_image_name> : <tag> podman images podman tag registry.redhat.io/ <container_image_name> : <tag> <automation_hub_hostname> / <container_image_name> podman images podman login -u= <username> -p= <password> <automation_hub_url> podman push <automation_hub_url> / <container_image_name> #!/usr/bin/env bash pulp_container SigningService will pass the next 4 variables to the script. MANIFEST_PATH=USD1 FINGERPRINT="USDPULP_SIGNING_KEY_FINGERPRINT" IMAGE_REFERENCE="USDREFERENCE" SIGNATURE_PATH="USDSIG_PATH" Create container signature using skopeo skopeo standalone-sign USDMANIFEST_PATH USDIMAGE_REFERENCE USDFINGERPRINT --output USDSIGNATURE_PATH Optionally pass the passphrase to the key if password protected. --passphrase-file /path/to/key_password.txt Check the exit status STATUS=USD? if [ USDSTATUS -eq 0 ]; then echo {\"signature_path\": \"USDSIGNATURE_PATH\"} else exit USDSTATUS fi [all:vars] . . . automationhub_create_default_container_signing_service = True automationhub_container_signing_service_key = /absolute/path/to/key/to/sign automationhub_container_signing_service_script = /absolute/path/to/script/that/signs > podman pull <container-name> > podman tag <container-name> <server-address>/<container-name>:<tag name> > podman push <server-address>/<container-name>:<tag name> --tls-verify=false --sign-by <reference to the gpg key on your local> > podman push <server-address>/<container-name>:<tag name> --tls-verify=false > sudo <name of editor> /etc/containers/policy.json { "default": [{"type": "reject"}], "transports": { "docker": { "quay.io": [{"type": "insecureAcceptAnything"}], "docker.io": [{"type": "insecureAcceptAnything"}], "<server-address>": [ { "type": "signedBy", "keyType": "GPGKeys", "keyPath": "/tmp/containersig.txt" }] } } } { "default": [{"type": "reject"}], "transports": { "docker": { "quay.io": [{"type": "insecureAcceptAnything"}], "docker.io": [{"type": "insecureAcceptAnything"}], "<server-address>": [{ "type": "signedBy", "keyType": "GPGKeys", "keyPath": "/tmp/<key file name>", "signedIdentity": { "type": "matchExact" } }] } } } > podman pull <server-address>/<container-name>:<tag name> --tls-verify=false