Getting started with automation hub

Red Hat Ansible Automation Platform 2.1

Configuring Red Hat Automation Hub as your default server for Ansible collections content

Red Hat Customer Content Services

Abstract

This guide walks you through the initial steps required to use Red Hat automation hub as the default source for certified Ansible collections content.
Providing Feedback:
If you have a suggestion to improve this documentation, or find an error, please contact technical support at https://access.redhat.com to create an issue on the Ansible Automation Platform Jira project using the Docs component.

Preface

Red Hat Ansible automation hub provides a place for Red Hat subscribers to quickly find and use content that is supported by Red Hat and our technology partners to deliver additional reassurance for the most demanding environments.

The Ansible Galaxy client, ansible-galaxy, manages roles and collections from the command line. To ensure that the ansible-galaxy client uses certified, supported Ansible collections whenever possible, you should update your ansible.cfg file to use Red Hat automation hub as your primary source of Ansible collections.

This guide walks you through the steps required to configure your ansible.cfg file to use Red Hat automation hub as the default source for certified Ansible collections content.

Making open source more inclusive

Red Hat is committed to replacing problematic language in our code, documentation, and web properties. We are beginning with these four terms: master, slave, blacklist, and whitelist. Because of the enormity of this endeavor, these changes will be implemented gradually over several upcoming releases. For more details, see our CTO Chris Wright’s message.

Chapter 1. Creating the Red Hat automation hub API token

Before you can interact with automation hub by uploading or downloading collections, you need to create an API token. The automation hub API token authenticates your ansible-galaxy client to the Red Hat automation hub server.

You can create an API token using automation hub Token management.

Prerequisites

  • Valid subscription credentials for Red Hat Ansible Automation Platform.

Procedure

  1. Navigate to https://cloud.redhat.com/ansible/automation-hub/token/.
  2. Click Load Token.
  3. Click copy icon to copy the API token to the clipboard.
  4. 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.

1.1. Keeping your offline token active

Keeping an offline token active is useful when an application needs to perform action on behalf of the user, even when the user is offline. For example, a routine data backup.

Offline tokens expire after 30 days of inactivity. You can keep your offline token from expiring by periodically refreshing your offline token.

Note

Once your offline token expires, you must request a new one.

Run the following command periodically 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

Chapter 2. Configuring Red Hat automation hub as the primary source for content

Configure Red Hat automation hub as your primary source of content to access Ansible Certified Content Collections. You can configure automation hub in the command-line interface (CLI) or the web console.

2.1. Configuring Red Hat automation hub as the primary source for content using the CLI

Configure Red Hat automation hub as your primary source of content by using the CLI. To configure automation hub, you must modify the ansible.cfg configuration file. With automation hub, you have access to certified, supported collections.

Prerequisites

Creating a new token revokes any previous tokens
generated for Private Automation Hub. Ensure that you update any Controller or scripts that you created with the previous token.

Procedure

  1. Add the server_list option under the [galaxy] section and provide one or more server names.
  2. Create a new section for each server name:

    [galaxy_server._<server_name>_]
  3. Set the url option for each server name. You must include the api/galaxy/ subdirectory in the server URL:

    https://<server_fully_qualified_domain_name>/api/galaxy/
  4. Optional: Set the auth_url option. The community Ansible Galaxy does not require an auth_url.
  5. Set the API token for the automation hub server.

The following ansible.cfg configuration file example shows how to configure multiple servers in prioritized order, with automation hub configured as your primary source and an Ansible Galaxy server as a secondary source:

ansible.cfg

[galaxy]
server_list = automation_hub, my_org_hub

[galaxy_server.automation_hub]
url=https://cloud.redhat.com/api/automation-hub/api/galaxy/ 1 2
auth_url=https://sso.redhat.com/auth/realms/redhat-external/protocol/openid-connect/token

token=my_ah_token

[galaxy_server.my_org_hub]
url=https://automation.my_org/api/galaxy/ 3
username=my_user
password=my_pass

1
Include a trailing slash / after the server URL.
2
Include the /api/galaxy/ subdirectory in the Ansible Galaxy server URL.
3
Include the /api/galaxy/ subdirectory in the automation hub server URL.
Note

All API URLs must end with a trailing slash / in order to prevent receiving a 301 redirect.

You have now configured automation hub as your primary server using CLI, and can proceed to download and install supported collections.

Additional resources

For more information on server list configuration options and using Ansible Galaxy as an Ansible content source, see the Ansible Galaxy User Guide.

2.2. Configuring Red Hat automation hub as the primary source for content using the web console

Configure Red Hat automation hub as your primary source of content by using the web console. To configure automation hub, you must create a credential and add it to the Organization’s Galaxy Credentials field. With automation hub, you have access to certified, supported collections.

Prerequisites

Creating a new token revokes any previous tokens
generated for Private Automation Hub. Ensure that you update any Controller or scripts that you created with the previous token.

Procedure

  1. Navigate to your Automation Controller.
  2. Create a new credential.

    1. Click Add from the Credentials screen.
    2. Enter the name for your new credential in the Name field.
    3. Optional: Enter a description and enter or select the name of the organization with which the credential is associated.
    4. Under Organization, select the organization that you would like to use the credential for.
    5. Select Ansible Galaxy/Automation Hub API Token as the credential type.
    6. Under Type Details, enter the Galaxy Server URL, Authentication Server URL, and API Token created in the Prerequisite.
    7. Click Save.
  3. Select the credential you created from the Organization’s Galaxy Credentials field.

    1. Navigate to AccessOrganizations.
    2. Select the organization where you’d like to add your Galaxy credentials.
    3. Click Edit.
    4. Under Galaxy Credentials, click the Search icon.
    5. Select the credential you created for automation hub, and place it at the beginning of the list.
    6. Optional: If you have a secondary source of content, such as Ansible Galaxy, place this credential after the credential you created for automation hub.
    7. Click Select.
    8. Click Save.

Verification

To validate the credential, update an existing source control management (SCM)-based project by selecting the project and clicking the Refresh icon.

  1. Navigate to your project repository.
  2. Select a project that uses a collections/requirements.yml file.
  3. Update the project by clicking the refresh icon [refresh icon].

If the status of the project is Successful, then the credential is valid.

You have now configured automation hub as your primary server using the web console, and you can proceed to download and install supported collections.

Additional resources

  1. For more information on server list configuration options and using Ansible Galaxy as an Ansible content source, see the Ansible Galaxy User Guide.
  2. For more information on creating and using credentials, see the Credentials section of Automation Controller User Guide v4.2.1.

Legal Notice

Copyright © 2023 Red Hat, Inc.
The text of and illustrations in this document are licensed by Red Hat under a Creative Commons Attribution–Share Alike 3.0 Unported license ("CC-BY-SA"). An explanation of CC-BY-SA is available at http://creativecommons.org/licenses/by-sa/3.0/. In accordance with CC-BY-SA, if you distribute this document or an adaptation of it, you must provide the URL for the original version.
Red Hat, as the licensor of this document, waives the right to enforce, and agrees not to assert, Section 4d of CC-BY-SA to the fullest extent permitted by applicable law.
Red Hat, Red Hat Enterprise Linux, the Shadowman logo, the Red Hat logo, JBoss, OpenShift, Fedora, the Infinity logo, and RHCE are trademarks of Red Hat, Inc., registered in the United States and other countries.
Linux® is the registered trademark of Linus Torvalds in the United States and other countries.
Java® is a registered trademark of Oracle and/or its affiliates.
XFS® is a trademark of Silicon Graphics International Corp. or its subsidiaries in the United States and/or other countries.
MySQL® is a registered trademark of MySQL AB in the United States, the European Union and other countries.
Node.js® is an official trademark of Joyent. Red Hat is not formally related to or endorsed by the official Joyent Node.js open source or commercial project.
The OpenStack® Word Mark and OpenStack logo are either registered trademarks/service marks or trademarks/service marks of the OpenStack Foundation, in the United States and other countries and are used with the OpenStack Foundation's permission. We are not affiliated with, endorsed or sponsored by the OpenStack Foundation, or the OpenStack community.
All other trademarks are the property of their respective owners.