Chapter 1. Red Hat Certified, validated, and Ansible Galaxy content in automation hub Ansible Certified Content Collections are included in your subscription to Red Hat Ansible Automation Platform. Using Ansible automation hub, you can access and curate a unique set of collections from all forms of Ansible content. Red Hat Ansible content contains two types of content: Ansible Certified Content Collections Ansible validated content collections You can use both Ansible Certified Content Collections or Ansible validated content collections to build your automation library. For more information on the differences between Ansible Certified Content Collections and Ansible validated content collections, see the Knowledgebase article Ansible Certified Content Collections and Ansible validated content , or Ansible validated content in this guide. You can update these collections manually by downloading their packages. You can use Ansible automation hub to distribute the relevant Red Hat Ansible Certified Content Collections to your users by creating a requirements file or a synclist. Use a requirements file to install collections to your automation hub, as synclists can only be managed by users with platform administrator privileges. Before you can use a requirements file to install content, you must: Obtain an automation hub API token Use the API token to configure a remote repository in your local hub Then, Create a requirements file . 1.1. Configuring Ansible automation hub remote repositories to synchronize content Use remote configurations to configure your private automation hub to synchronize with Ansible Certified Content Collections hosted on console.redhat.com or with your collections in Ansible Galaxy. Important To synchronize content, you can now upload a manually-created requirements file from the rh-certified remote. Remotes are configurations that allow you to synchronize content to your custom repositories from an external collection source. As of the 2.4 release you can still synchronize content, but synclists are deprecated, and will be removed in a future version. Each remote configuration located in Automation Content Remotes provides information for both the community and rh-certified repository about when the repository was last updated . You can add new content to Ansible automation hub at any time using the Edit and Sync features included on the Automation Content Repositories page. What's the difference between Ansible Galaxy and Ansible automation hub? Collections published to Ansible Galaxy are the latest content published by the Ansible community and have no joint support claims associated with them. Ansible Galaxy is the recommended frontend directory for the Ansible community to access content. Collections published to Ansible automation hub are targeted to joint customers of Red Hat and selected partners. Customers need an Ansible subscription to access and download collections on Ansible automation hub. A certified collection means that Red Hat and partners have a strategic relationship in place and are ready to support joint customers, and that the collections may have had additional testing and validation done against them. How do I request a namespace on Ansible Galaxy? To request a namespace through an Ansible Galaxy GitHub issue, follow these steps: Send an email to ansiblepartners@redhat.com Include the GitHub username used to sign up on Ansible Galaxy. You must have logged in at least once for the system to validate. After users are added as administrators of the namespace, you can use the self-serve process to add more administrators. Are there any restrictions for Ansible Galaxy namespace naming? Collection namespaces must follow Python module name convention. This means collections should have short, all lowercase names. You can use underscores in the collection name if it improves readability. 1.1.1. Token management in automation hub Before you can interact with automation hub by uploading or downloading collections, you must create an API token. The automation hub API token authenticates your ansible-galaxy client to the Red Hat automation hub server. Note automation hub does not support basic authentication or authenticating through service accounts. You must authenticate using token management. Your method for creating the API token differs according to the type of automation hub that you are using: Automation hub uses offline token management. See Creating the offline token in automation hub . Private automation hub uses API token management. See Creating the API token in private automation hub . If you are using Keycloak to authenticate your private automation hub, follow the procedure for Creating the offline token in automation hub . 1.1.1.1. Creating the offline token in automation hub In automation hub, you can create an offline token by using Token management . The offline token is a secret token used to protect your content. Procedure Navigate to Ansible Automation Platform on the Red Hat Hybrid Cloud Console . From the navigation panel, select Automation Hub Connect to Hub . Under Offline token , click Load Token . Click the Copy to clipboard icon to copy the offline token. Paste the API token into a file and store in a secure location. Important The offline token is a secret token used to protect your content. Store your token in a secure location. The offline token is now available for configuring automation hub as your default collections server or for uploading collections by using the ansible-galaxy command line tool. Note Your offline token expires after 30 days of inactivity. For more on obtaining a new offline token, see Keeping your offline token active . 1.1.1.2. Creating the API token in private automation hub In private automation hub, you can create an API token using API token management. The API token is a secret token used to protect your content. Prerequisites Valid subscription credentials for Red Hat Ansible Automation Platform. Procedure Log in to your private automation hub. From the navigation panel, select Automation Content API token . Click Load Token . To copy the API token, click the Copy to clipboard icon. Paste the API token into a file and store in a secure location. Important The API token is a secret token used to protect your content. Store your API token in a secure location. The API token is now available for configuring automation hub as your default collections server or uploading collections using the ansible-galaxy command line tool. Note The API token does not expire. 1.1.1.3. Keeping your offline token active Offline tokens expire after 30 days of inactivity. You can keep your offline token from expiring by periodically refreshing your offline token. Keeping an online token active is useful when an application performs an action on behalf of the user; for example, this allows the application to perform a routine data backup when the user is offline. Note If your offline token expires, you must obtain a new one . Procedure Run the following command to prevent your token from expiring: curl https://sso.redhat.com/auth/realms/redhat-external/protocol/openid-connect/token -d grant_type=refresh_token -d client_id="cloud-services" -d refresh_token="{{ user_token }}" --fail --silent --show-error --output /dev/null 1.1.2. Configuring the rh-certified remote repository and synchronizing Red Hat Ansible Certified Content Collection You can edit the rh-certified remote repository to synchronize collections from automation hub hosted on console.redhat.com to your private automation hub. By default, your private automation hub rh-certified repository includes the URL for the entire group of Ansible Certified Content Collections. To use only those collections specified by your organization, a private automation hub administrator can upload manually-created requirements files from the rh-certified remote. If you have collections A , B , and C in your requirements file, and a new collection X is added to console.redhat.com that you want to use, you must add X to your requirements file for private automation hub to synchronize it. Prerequisites You have valid Modify Ansible repo content permissions. For more information on permissions, see Access management and authentication . You have retrieved the Sync URL and API Token from the automation hub hosted service on console.redhat.com. You have configured access to port 443. This is required for synchronizing certified collections. For more information, see the automation hub table in the Network ports and protocols chapter of Planning your installation. Procedure Log in to your Ansible Automation Platform. From the navigation panel, select Automation Content Remotes . In the rh-certified remote repository, click Edit remote . In the URL field, paste the Sync URL . In the Token field, paste the token you acquired from console.redhat.com. Click Save remote . You can now synchronize collections between your organization synclist on console.redhat.com and your private automation hub. From the navigation panel, select Automation Content Repositories . to rh-certified click the More Actions icon ... and select Sync repository . On the modal that appears, you can toggle the following options: Mirror : Select if you want your repository content to mirror the remote repository's content. Optimize : Select if you want to sync only when no changes are reported by the remote server. Click Sync to complete the sync. Verification The Sync status column updates to notify you whether the Red Hat Certified Content Collections synchronization is successful. Navigate to Automation Content Collections to confirm that your collections content has synchronized successfully. 1.1.3. Configuring the community remote repository and syncing Ansible Galaxy collections You can edit the community remote repository to synchronize chosen collections from Ansible Galaxy to your private automation hub. By default, your private automation hub community repository directs to galaxy.ansible.com/api/ . Prerequisites You have Modify Ansible repo content permissions. For more information on permissions, see Access management and authentication . You have a requirements.yml file that identifies those collections to synchronize from Ansible Galaxy as in the following example: Requirements.yml example Procedure Log in to Ansible Automation Platform. From the navigation panel, select Automation Content Remotes . In the Details tab in the Community remote, click Edit remote . In the YAML requirements field, paste the contents of your requirements.yml file. Click Save remote . You can now synchronize collections identified in your requirements.yml file from Ansible Galaxy to your private automation hub. From the navigation panel, select Automation Content Repositories . to the community repository, click the More Actions icon ... and select Sync repository to sync collections between Ansible Galaxy and Ansible automation hub. On the modal that appears, you can toggle the following options: Mirror : Select if you want your repository content to mirror the remote repository's content. Optimize : Select if you want to sync only when no changes are reported by the remote server. Click Sync to complete the sync. Verification The Sync status column updates to notify you whether the Ansible Galaxy collections synchronization to your Ansible automation hub is successful. Navigate to Automation Content Collections and select Community to confirm successful synchronization. 1.1.4. Configuring proxy settings If your private automation hub is behind a network proxy, you can configure proxy settings on the remote to sync content located outside of your local network. Prerequisites You have valid Modify Ansible repo content permissions. For more information on permissions, see Access management and authentication You have a proxy URL and credentials from your local network administrator. Procedure Log in to Ansible Automation Platform. From the navigation panel, select Automation Content Remotes . In either the rh-certified or Community remote, click the More Actions icon ... and select Edit remote . Expand the Show advanced options drop-down menu. Enter your proxy URL, proxy username, and proxy password in the appropriate fields. Click Save remote . 1.1.5. Creating a requirements file Use a requirements file to add collections to your automation hub. Requirements files are in YAML format and list the collections that you want to install in your automation hub. After you create your requirements.yml file listing the collections you want to install, you will then run the install command to add the collections to your hub instance. A standard requirements.yml file contains the following parameters: name : the name of the collection formatted as <namespace>.<collection_name> version : the collection version number Procedure Create your requirements file. In YAML format, collection information in your requirements file should look like this: collections: name: namespace.collection_name version: 1.0.0 After you have created your requirements file listing information for each collection that you want to install, navigate to the directory where the file is located and run the following command: USD ansible-galaxy collection install -r requirements.yml 1.1.5.1. Installing an individual collection from the command line To install an individual collection to your automation hub, run the following command: USD ansible-galaxy collection install namespace.collection_name 1.2. Synchronizing Ansible Content Collections in automation hub Important To synchronize content, you can now upload a manually-created requirements file from the rh-certified remote. Remotes are configurations that enable you to synchronize content to your custom repositories from an external collection source. As of the 2.4 release you can still synchronize content, but synclists are deprecated, and will be removed in a future version. 1.2.1. Explanation of Red Hat Ansible Certified Content Collections synclists A synclist is a curated group of Red Hat Certified Collections assembled by your organization administrator. It synchronizes with your local Ansible automation hub. Use synclists to manage only the content that you want and exclude unnecessary collections. Design and manage your synclist from the content available as part of Red Hat content on console.redhat.com Each synclist has its own unique repository URL that you can designate as a remote source for content in automation hub. You securely access each synclist by using an API token. 1.2.2. Creating a synclist of Red Hat Ansible Certified Content Collections You can create a synclist of curated Red Hat Ansible Certified Content in Ansible automation hub on console.redhat.com. Your synclist repository is located on the automation hub navigation panel under Automation Content Repositories , which is updated whenever you manage content within Ansible Certified Content Collections. All Ansible Certified Content Collections are included by default in your initial organization synclist. Prerequisites You have a valid Ansible Automation Platform subscription. You have organization administrator permissions for console.redhat.com. The following domain names are part of either the firewall or the proxy's allowlist. They are required for successful connection and download of collections from automation hub or Galaxy server: galaxy.ansible.com cloud.redhat.com console.redhat.com sso.redhat.com Ansible automation hub resources are stored in Amazon Simple Storage. The following domain names must be in the allow list: automation-hub-prd.s3.us-east-2.amazonaws.com ansible-galaxy.s3.amazonaws.com SSL inspection is disabled either when using self signed certificates or for the Red Hat domains. Procedure Log in to console.redhat.com . Navigate to Automation Hub Collections . Set the Sync toggle switch on each collection to exclude or include it on your synclist. Note You will only see the Sync toggle switch if you have administrator permissions. To initiate the remote repository synchronization, navigate to your Ansible Automation Platform and select Automation Content Repositories . In the row containing the repository you want to sync, click the More Actions icon ... and select Sync repository to initiate the remote repository synchronization to your private automation hub. Optional: If your remote repository is already configured, update the collections content that you made available to local users by manually synchronizing Red Hat Ansible Certified Content Collections to your private automation hub. 1.3. Collections and content signing in private automation hub As an automation administrator for your organization, you can configure private automation hub for signing and publishing Ansible content collections from different groups within your organization. For additional security, automation creators can configure Ansible-Galaxy CLI to verify these collections to ensure that they have not been changed after they were uploaded to automation hub. 1.3.1. Configuring content signing on private automation hub To successfully sign and publish Ansible Certified Content Collections, you must configure private automation hub for signing. Prerequisites Your GnuPG key pairs have been securely set up and managed by your organization. Your public-private key pair has proper access for configuring content signing on private automation hub. Procedure Create a signing script that accepts only a filename. Note This script acts as the signing service and must generate an ascii-armored detached gpg signature for that file using the key specified through the PULP_SIGNING_KEY_FINGERPRINT environment variable. The script prints out a JSON structure with the following format. {"file": "filename", "signature": "filename.asc"} All the file names are relative paths inside the current working directory. The file name must remain the same for the detached signature. Example: The following script produces signatures for content: #!/usr/bin/env bash FILE_PATH=USD1 SIGNATURE_PATH="USD1.asc" ADMIN_ID="USDPULP_SIGNING_KEY_FINGERPRINT" PASSWORD="password" # Create a detached signature gpg --quiet --batch --pinentry-mode loopback --yes --passphrase \ USDPASSWORD --homedir ~/.gnupg/ --detach-sign --default-key USDADMIN_ID \ --armor --output USDSIGNATURE_PATH USDFILE_PATH # Check the exit status STATUS=USD? if [ USDSTATUS -eq 0 ]; then echo {\"file\": \"USDFILE_PATH\", \"signature\": \"USDSIGNATURE_PATH\"} else exit USDSTATUS fi After you deploy a private automation hub with signing enabled to your Ansible Automation Platform cluster, new UI additions are displayed in collections. Review the Ansible Automation Platform installer inventory file for options that begin with automationhub_* . [all:vars] . . . automationhub_create_default_collection_signing_service = True automationhub_auto_sign_collections = True automationhub_require_content_approval = True automationhub_collection_signing_service_key = /abs/path/to/galaxy_signing_service.gpg automationhub_collection_signing_service_script = /abs/path/to/collection_signing.sh The two new keys ( automationhub_auto_sign_collections and automationhub_require_content_approval ) indicate that the collections must be signed and approved after they are uploaded to private automation hub. 1.3.2. Using content signing services in private automation hub After you have configured content signing on your private automation hub, you can manually sign a new collection or replace an existing signature with a new one. When users download a specific collection, this signature indicates that the collection is for them and has not been modified after certification. You can use content signing on private automation hub in the following scenarios: Your system does not have automatic signing configured and you must use a manual signing process to sign collections. The current signatures on the automatically configured collections are corrupted and need new signatures. You need additional signatures for previously signed content. You want to rotate signatures on your collections. Procedure Log in to Ansible Automation Platform. From the navigation panel, select Automation Content Collection Approvals . The Approval dashboard opens and displays a list of collections. Click the thumbs up icon to the collection you want to approve. On the modal that appears, check the box confirming that you want to approve the collection, and click Approve and sign collections . Verification Navigate to Automation Content Collections to verify that the collections you signed and approved are displayed. 1.3.3. Downloading signature public keys After you sign and approve collections, download the signature public keys from the Ansible Automation Platform UI. You must download the public key before you add it to the local system keyring. Procedure Log in to Ansible Automation Platform. From the navigation panel, select Automation Content Signature Keys . The Signature Keys dashboard displays a list of multiple keys: collections and container images. To verify collections, download the key prefixed with collections- . To verify container images, download the key prefixed with container- . Choose one of the following methods to download your public key: Click the Download Key icon to download the public key. Click the Copy to clipboard to the public key you want to copy. Use the public key that you copied to verify the content collection that you are installing. 1.3.4. Configuring Ansible-Galaxy CLI to verify collections You can configure Ansible-Galaxy CLI to verify collections. This ensures that downloaded collections are approved by your organization and have not been changed after they were uploaded to automation hub. If a collection has been signed by automation hub, the server provides ASCII armored, GPG-detached signatures to verify the authenticity of MANIFEST.json before using it to verify the collection's contents. You must opt into signature verification by configuring a keyring for ansible-galaxy or providing the path with the --keyring option. Prerequisites Signed collections are available in automation hub to verify signature. Certified collections can be signed by approved roles within your organization. Public key for verification has been added to the local system keyring. Procedure To import a public key into a non-default keyring for use with ansible-galaxy , run the following command. gpg --import --no-default-keyring --keyring ~/.ansible/pubring.kbx my-public-key.asc Note In addition to any signatures provided by automation hub, signature sources can also be provided in the requirements file and on the command line. Signature sources should be URIs. To verify the collection name provided on the CLI with an additional signature, run the following command: ansible-galaxy collection install namespace.collection --signature https://examplehost.com/detached_signature.asc --signature file:///path/to/local/detached_signature.asc --keyring ~/.ansible/pubring.kbx You can use this option multiple times to provide multiple signatures. Confirm that the collections in a requirements file list any additional signature sources following the collection's signatures key, as in the following example. # requirements.yml collections: - name: ns.coll version: 1.0.0 signatures: - https://examplehost.com/detached_signature.asc - file:///path/to/local/detached_signature.asc ansible-galaxy collection verify -r requirements.yml --keyring ~/.ansible/pubring.kbx When you install a collection from automation hub, the signatures provided by the server are saved along with the installed collections to verify the collection's authenticity. (Optional) If you need to verify the internal consistency of your collection again without querying the Ansible Galaxy server, run the same command you used previously using the --offline option. Are there any recommendations for collection naming? Create a collection with company_name.product format. This format means that multiple products can have different collections under the company namespace. How do I get a namespace on automation hub? By default namespaces used on Ansible Galaxy are also used on automation hub by the Ansible partner team. For any queries and clarifications contact ansiblepartners@redhat.com . 1.4. Ansible validated content Red Hat Ansible Automation Platform includes Ansible validated content, which complements existing Red Hat Ansible Certified Content. Ansible validated content provides an expert-led path for performing operational tasks on a variety of platforms from both Red Hat and our trusted partners. 1.4.1. Configuring validated collections with the installer When you download and run the RPM bundle installer, certified and validated collections are automatically uploaded. Certified collections are uploaded into the rh-certified repository. Validated collections are uploaded into the validated repository. You can change the default configuration by using two variables: automationhub_seed_collections is a boolean that defines whether or not preloading is enabled. automationhub_collection_seed_repository`is a variable that enables you to specify the type of content to upload when it is set to `true . Possible values are certified or validated . If this variable is missing, both content sets will be uploaded. Note Changing the default configuration may require further platform configuration changes for other content you may use.

Commands:
curl https://sso.redhat.com/auth/realms/redhat-external/protocol/openid-connect/token -d grant_type=refresh_token -d client_id="cloud-services" -d refresh_token="{{ user_token }}" --fail --silent --show-error --output /dev/null
collections: # Install a collection from Ansible Galaxy. - name: community.aws version: 5.2.0 source: https://galaxy.ansible.com
collections: name: namespace.collection_name version: 1.0.0
ansible-galaxy collection install -r requirements.yml
ansible-galaxy collection install namespace.collection_name
file: filename
signature: filename.asc
#!/usr/bin/env bash FILE_PATH=USD1 SIGNATURE_PATH="USD1.asc" ADMIN_ID="USDPULP_SIGNING_KEY_FINGERPRINT" PASSWORD="password" Create a detached signature gpg --quiet --batch --pinentry-mode loopback --yes --passphrase USDPASSWORD --homedir ~/.gnupg/ --detach-sign --default-key USDADMIN_ID --armor --output USDSIGNATURE_PATH USDFILE_PATH Check the exit status STATUS=USD? if [ USDSTATUS -eq 0 ]; then echo {\"file\": \"USDFILE_PATH\", \"signature\": \"USDSIGNATURE_PATH\"} else exit USDSTATUS fi
[all:vars] . . . automationhub_create_default_collection_signing_service = True automationhub_auto_sign_collections = True automationhub_require_content_approval = True automationhub_collection_signing_service_key = /abs/path/to/galaxy_signing_service.gpg automationhub_collection_signing_service_script = /abs/path/to/collection_signing.sh
gpg --import --no-default-keyring --keyring ~/.ansible/pubring.kbx my-public-key.asc
ansible-galaxy collection install namespace.collection --signature https://examplehost.com/detached_signature.asc --signature file:///path/to/local/detached_signature.asc --keyring ~/.ansible/pubring.kbx
requirements.yml collections: - name: ns.coll version: 1.0.0 signatures: - https://examplehost.com/detached_signature.asc - file:///path/to/local/detached_signature.asc ansible-galaxy collection verify -r requirements.yml --keyring ~/.ansible/pubring.kbx