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. Red Hat Ansible content includes two types of content: Ansible Certified Content Collections and Ansible validated content. 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

Ansible validated collections are available in your private automation hub through the Platform Installer. When you download Red Hat Ansible Automation Platform with the bundled installer, validated content is pre-populated into the private automation hub by default, but only if you enable the private automation hub as part of the inventory.

If you are not using the bundle installer, you can use a Red Hat supplied Ansible playbook to install validated content. For further information, see Ansible validated content.

You can update these collections manually by downloading their packages.

Why certify Ansible collections?

The Ansible certification program enables a shared statement of support for Red Hat Ansible Certified Content between Red Hat and the ecosystem partner. An end customer, experiencing trouble with Ansible and certified partner content, can open a support ticket, for example, a request for information, or a problem with Red Hat, and expect the ticket to be resolved by Red Hat and the ecosystem partner.

Red Hat offers go-to-market benefits for Certified Partners to grow market awareness, generate demand, and sell collaboratively.

Red Hat Ansible Certified Content Collections are distributed through Ansible automation hub (subscription required), a centralized repository for jointly supported Ansible Content. As a certified partner, publishing collections to Ansible automation hub provides end customers the power to manage how trusted automation content is used in their production environment with a well-known support life cycle.

For more information about getting started with certifying a solution, see Red Hat Partner Connect.

How do I get a collection certified?

For instructions on certifying your collection, see the Ansible certification policy guide on Red Hat Partner Connect.

How does the joint support agreement on Certified Collections work?

If a customer raises an issue with the Red Hat support team about a certified collection, Red Hat support assesses the issue and checks whether the problem exists within Ansible or Ansible usage. They also check whether the issue is with a certified collection. If there is a problem with the certified collection, support teams transfer the issue to the vendor owner of the certified collection through an agreed upon tool such as TSANet.

Can I create and certify a collection containing only Ansible Roles?

You can create and certify collections that contain only roles. Current testing requirements are focused on collections containing modules, and additional resources are currently in progress for testing collections only containing roles. Contact ansiblepartners@redhat.com for more information.

1.1. Synchronizing Ansible Content Collections in automation hub

Important

As of the 2.4 release you can still synchronize content, but synclists are deprecated, and will be removed in a future version.

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.

You can use Ansible automation hub to distribute the relevant Red Hat Ansible Certified Content Collections to your users by creating synclists or a requirements file. For more information about using requirements files, see Install multiple collections with a requirements file in the Using Ansible collections guide.

1.1.1. Explanation of Red Hat Ansible Certified Content Collections synclists

A synclist is a curated group of Red Hat Certified Collections that is 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 use to designate as a remote source for content in automation hub. You securely access each synclist by using an API token.

1.1.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 CollectionRepositories, 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

  1. Log in to console.redhat.com.
  2. Navigate to Automation HubCollections.
  3. Set the toggle switch on each collection to exclude or include it on your synclist.
  4. To initiate the remote repository synchronization, navigate to automation hub and select CollectionRepositories.
  5. Click the More Actions icon and select Sync to initiate the remote repository synchronization to your private automation hub.
  6. 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.2. 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

As of the 2.4 release you can still synchronize content, but synclists are deprecated, and will be removed in a future version.

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.

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

Collections published to Ansible automation hub are targeted for 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 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:

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.2.1. Reasons to create remote configurations

Each remote configuration located in CollectionsRemotes 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 CollectionRepositories page.

1.2.2. Retrieving the Sync URL and API token for your Red Hat Certified Collection

You can synchronize Ansible Certified Content Collections curated by your organization from console.redhat.com to your private automation hub. The API token is a secret token used to protect your content.

Prerequisites

  • You have organization administrator permissions to create the synclist on console.redhat.com.

Procedure

  1. Log in to console.redhat.com as an organization administrator.
  2. Navigate to Automation HubConnect to Hub.
  3. Under Offline token, click Load token.
  4. Click Copy to clipboard to copy the API token.
  5. Paste the API token into a file and store in a secure location.

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

For more information about using requirements files, see Install multiple collections with a requirements file in the Using Ansible collections guide.

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 Configuring user access for your private automation hub.
  • 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 the Red Hat Ansible Automation Platform Planning Guide.

Procedure

  1. Log in to your private automation hub.
  2. From the navigation panel, select CollectionsRemotes.
  3. In the rh-certified remote repository, click the More Actions icon and click Edit.
  4. In the URL field, paste the Sync URL.
  5. In the Token field, paste the token you acquired from console.redhat.com.
  6. Click Save.

    You can now synchronize collections between your organization synclist on console.redhat.com and your private automation hub.

  7. Click the More Actions icon and select Sync.

Verification

The Sync status notification updates to notify you that the Red Hat Certified Content Collections synchronization is complete.

  • Select Red Hat Certified from the collections content drop-down list to confirm that your collections content has synchronized successfully.

1.2.4. 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 Configuring user access for your private automation hub.
  • You have a requirements.yml file that identifies those collections to synchronize from Ansible Galaxy as in the following example:

    Requirements.yml example

    collections:
      # Install a collection from Ansible Galaxy.
      - name: community.aws
        version: 5.2.0
        source: https://galaxy.ansible.com

Procedure

  1. Log in to automation hub.
  2. From the navigation panel, select CollectionsRemotes.
  3. In the Community remote, click the More Actions icon and select Edit.
  4. In the YAML requirements field, click Browse and locate the requirements.yml file on your local machine.
  5. Click Save.

    You can now synchronize collections identified in your requirements.yml file from Ansible Galaxy to your private automation hub.

  6. Click the More Actions icon and select Sync to sync collections from Ansible Galaxy and Ansible automation hub.

Verification

The Sync status notification updates to notify you of completion or failure of Ansible Galaxy collections synchronization to your Ansible automation hub.

  • Select Community from the collections content drop-down list to confirm successful synchronization.

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

Procedure

  1. Log in to private automation hub.
  2. From the navigation panel, select CollectionsRemotes.
  3. In either the rh-certified or Community remote, click the More Actions icon and select Edit.
  4. Expand the Show advanced options drop-down menu.
  5. Enter your proxy URL, proxy username, and proxy password in the appropriate fields.
  6. Click Save.

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

  1. 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=$1
    SIGNATURE_PATH="$1.asc"
    
    ADMIN_ID="$PULP_SIGNING_KEY_FINGERPRINT"
    PASSWORD="password"
    
    # Create a detached signature
    gpg --quiet --batch --pinentry-mode loopback --yes --passphrase \
       $PASSWORD --homedir ~/.gnupg/ --detach-sign --default-key $ADMIN_ID \
       --armor --output $SIGNATURE_PATH $FILE_PATH
    
    # Check the exit status
    STATUS=$?
    if [ $STATUS -eq 0 ]; then
       echo {\"file\": \"$FILE_PATH\", \"signature\": \"$SIGNATURE_PATH\"}
    else
       exit $STATUS
    fi

    After you deploy a private automation hub with signing enabled to your Ansible Automation Platform cluster, new UI additions are displayed in collections.

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

  1. Log in to your Ansible Automation Platform.
  2. From the navigation panel, select CollectionsApproval. The Approval dashboard opens and displays a list of collections.
  3. Click Sign and approve for each collection that you want to sign.

Verification

  • Verify that the collections you signed and manually approved are displayed in the Collections tab.

1.3.3. Downloading signature public keys

After you sign and approve collections, download the signature public keys from the automation hub UI. You must download the public key before you add it to the local system keyring.

Procedure

  1. Log in to your automation hub.
  2. From the navigation panel, select 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-.
  3. Choose one of the following methods to download your public key:

    • Select the menu icon and click Download Key to download the public key.
    • Select the public key from the list and click the Copy to clipboard icon.
    • Click the drop-down menu under the Public Key tab and copy the entire public key block.

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

  1. 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 the automation hub, signature sources can also be provided in the requirements file and on the command line. Signature sources should be URIs.

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

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

  4. (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 Ansible automation hub?

By default namespaces used on Ansible Galaxy are also used on Ansible 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 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 to default configuration by using two variables:

  • automationhub_seed_collections is a boolean that defines whether or not preloading is enabled.
  • automationhub_collection_seed_repository. 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 missing both content sets will be uploaded.

1.4.2. Installing validated content using the tarball

If you are not using the bundle installer, you can use a standalone tarball, ansible-validated-content-bundle-1.tar.gz. You can also use this standalone tarball later to update validated contents in any environment, when a newer tarball becomes available, without having to re-run the bundle installer.

Prerequisites

You require the following variables to run the playbook.

NameDescription

automationhub_admin_password

Your administration password.

automationhub_api_token

The API token generated for your automation hub.

automationhub_main_url

For example, https://automationhub.example.com

automationhub_require_content_approval

Boolean (true or false)

This must match the value used during automation hub deployment.

This variable is set to true by the installer.

Procedure

  1. To obtain the tarball, navigate to the Red Hat Ansible Automation Platform download page and select Ansible Validated Content.
  2. Upload the content and define the variables (this example uses automationhub_api_token):

    ansible-playbook collection_seed.yml
    -e automationhub_api_token=<api_token>
    -e automationhub_main_url=https://automationhub.example.com
    -e automationhub_require_content_approval=true
    Note

    Use either automationhub_admin_password or automationhub_api_token, not both.

When complete, the collections are visible in the validated collection section of private automation hub. Users can now view and download collections from your private automation hub.

Additional Resources

For more information on running ansible playbooks, see ansible-playbook.