Developing Advanced Automation with Red Hat Ansible Automation Platform

Use the automation hub web UI at https://console.redhat.com/ansible/automation-hub/ to browse its Ansible Content Collections.

Navigate to Automation Hub → Collections to list the collections. Use the Search field to access collections by keywords.

Figure 2.1: Listing collections in automation hub

You can also navigate to Automation Hub → Partners to browse the collections by partners.

Use the ansible-galaxy command to download collections from a number of possible sources, including Ansible Galaxy.

The following example uses the ansible-galaxy command with the collection argument to download and then install the community.crypto collection on the local system.

[user@host ~]$ ansible-galaxy collection install community.crypto

By default, the ansible-galaxy command tries to download the collection from Ansible Galaxy. Configuring ansible-galaxy to use automation hub or a private automation hub to get collections is covered later in this section.

The ansible-galaxy command can also install a collection from a local or a remote .tar file or a Git repository.

[user@host ~]$ ansible-galaxy collection install /tmp/community-dns-1.2.0.tar.gz
[user@host ~]$ ansible-galaxy collection install \
> http://www.example.com/redhat-insights-1.0.5.tar.gz
[user@host ~]$ ansible-galaxy collection install \
> git@github.com:ansible-collections/community.mysql.git

When Ansible runs a playbook, it looks for collections in a collections/ directory in the same directory as the playbook. If it cannot find the required collection in that location, then it uses the collections_paths directive from the ansible.cfg configuration file. That directive specifies a colon-separated list of paths on the system where Ansible looks for installed collections.

By default, the ansible-galaxy command installs the collections in the first directory that the collections_paths directive defines.

The default value for collections_paths is ~/.ansible/collections:/usr/share/ansible/collections. Therefore, the ansible-galaxy command installs collections in the ~/.ansible/collections directory by default.

To install a collection in a different directory, use the --collections-path (or -p) option:

[user@host ~]$ ansible-galaxy collection install community.postgresql \
> -p ~/myproject/collections/

The collections/requirements.yml file is a list of the collections needed to run playbooks in your Ansible project, just like you can create a roles/requirements.yml file to list the roles that you need to install. By adding a collections/requirements.yml file in your Ansible project, your team members can immediately identify the required collections, and they can use ansible-galaxy to manually install them. Automation controller detects the collections/requirements.yml and automatically installs the collections it specifies before running your playbooks.

The following collections/requirements.yml file lists several collections to install. You can target a specific version of an Ansible Content Collection or provide local or remote .tar files or Git repositories as the source of the collection.

---
collections:
  - name: community.crypto

  - name: ansible.posix
    version: 1.2.0

  - name: /tmp/community-dns-1.2.0.tar.gz

  - name: http://www.example.com/redhat-insights-1.0.5.tar.gz

  - name: git@github.com:ansible-collections/community.mysql.git

You can process that file with the ansible-galaxy command to install those collections. Use the --requirements-file (or -r) option to provide the requirements.yml file to the command.

[user@host ~]$ ansible-galaxy collection install -r requirements.yml

The ansible-navigator collections command starts an interactive text-based user interface (TUI) that lists the collections installed in the current automation execution environment.

   Name               Version Shadowed Type      Path
 0│amazon.aws         3.2.0   False    contained /usr/share/ansible/col
 1│ansible.builtin    2.13.0  False    contained /usr/lib/python3.9/sit
 2│ansible.controller 4.2.0   False    contained /usr/share/ansible/col
 3│ansible.netcommon  3.0.0   False    contained /usr/share/ansible/col
 4│ansible.network    1.2.0   False    contained /usr/share/ansible/col
 5│ansible.posix      1.3.0   False    contained /usr/share/ansible/col
 6│ansible.security   1.0.0   False    contained /usr/share/ansible/col
 7│ansible.utils      2.6.1   False    contained /usr/share/ansible/col
 8│ansible.windows    1.9.0   False    contained /usr/share/ansible/col
 9│ansible.yang       1.0.0   False    contained /usr/share/ansible/col
10│arista.eos         5.0.0   False    contained /usr/share/ansible/col
11│cisco.asa          3.0.0   False    contained /usr/share/ansible/col
12│cisco.ios          3.0.0   False    contained /usr/share/ansible/col
13│cisco.iosxr        3.0.0   False    contained /usr/share/ansible/col
14│cisco.nxos         3.0.0   False    contained /usr/share/ansible/col
15│cloud.common       2.1.1   False    contained /usr/share/ansible/col
^b/PgUp page up^f/PgDn page down ↑↓ scrollesc back [0-9] goto:help help

If you enter the line number of a particular collection, ansible-navigator displays detailed information about the content of that collection in the TUI.

For example, if ansible-navigator displays the preceding output, and you type 5, then the following output is displayed:

   Ansible.posix     Type     Added Deprecated Description
 0│acl               module   1.0.0 False      Set and retrieve file AC
 1│at                module   1.0.0 False      Schedule the execution o
 2│authorized_key    module   1.0.0 False      Adds or removes an SSH a
 3│cgroup_perf_recap callback None  False      Profiles system activity
 4│csh               shell    None  False      C shell (/bin/csh)
 5│debug             callback None  False      formatted stdout/stderr
 6│firewalld         module   None  False      Manage arbitrary ports/s
 7│firewalld_info    module   None  False      Gather information about
 8│fish              shell    None  False      fish shell (/bin/fish)
 9│json              callback None  False      Ansible screen output as
10│mount             module   1.0.0 False      Control active and confi
11│patch             module   1.0.0 False      Apply patch files using
12│profile_roles     callback None  False      adds timing information
13│profile_tasks     callback None  False      adds time information to
14│seboolean         module   1.0.0 False      Toggles SELinux booleans
15│selinux           module   1.0.0 False      Change policy and state
^f/PgUp page up^b/PgDn page down↑↓ scrollesc back[0-9] goto:help help

From that page, you could type 1 to get documentation and usage examples for the ansible.posix.at module:

Image: ansible.posix.at
Description: Schedule the execution of a command or script file via
 0│---
 1│additional_information: {}
 2│collection_info:
 3│  authors:
 4│  - Ansible (github.com/ansible)
 5│  dependencies: {}
 6│  description: Ansible Collection targeting POSIX and POSIX-ish plat
 7│  documentation: https://github.com/ansible-collections/ansible.posi
 8│  homepage: https://github.com/ansible-collections/ansible.posix
 9│  issues: https://github.com/ansible-collections/ansible.posix
10│  license: []
11│  license_file: COPYING
12│  name: ansible.posix
13│  namespace: ansible
14│  path: /usr/share/ansible/collections/ansible_collections/ansible/po
15│  readme: README.md
^f/PgUp page ^b/PgDn page do↑↓ scroesc ba- previo+ ne[0-9] go:help he

You can also use the ansible-galaxy collection list command to list the collections available in the directories specified by your current collections_paths Ansible configuration directive on your control node. It does not list collections that you might have installed in directories not specified by that directive.

[user@host ~]$ ansible-galaxy collection list

# /home/user/.ansible/collections/ansible_collections
Collection       Version
---------------- ------
ansible.posix    1.3.0
community.crypto 1.9.5
community.dns    1.2.0
community.mysql  2.1.0
redhat.insights  1.0.7

# /usr/share/ansible/collections/ansible_collections
Collection               Version
------------------------ -------
redhat.rhel_system_roles 1.0.1

For the ansible-galaxy command to also use automation hub, add the following directives to the ansible.cfg file.

...output omitted...
[galaxy]
server_list = automation_hub, galaxy  

[galaxy_server.automation_hub]
url=https://console.redhat.com/api/automation-hub/  
auth_url=https://sso.redhat.com/auth/realms/redhat-external/protocol/openid-connect/token 
token=eyJh...Jf0o 

[galaxy_server.galaxy]
url=https://galaxy.ansible.com/

To retrieve the preceding URLs and generate a token, log in to the automation hub web UI and navigate to Automation Hub → Connect to Hub.

Figure 2.2: Generating a token

Instead of a token, you can use the username and password parameters to provide your customer portal username and password.

...output omitted...
[galaxy_server.automation_hub]
url=https://console.redhat.com/api/automation-hub/
username=operator1
password=Sup3r53cR3t
...output omitted...

You might not want to expose your credentials or your token in the ansible.cfg file because the file could potentially get committed using version control. In that case, remove the authentication parameters from the ansible.cfg file and define them as environment variables:

ANSIBLE_GALAXY_SERVER_SERVERID_KEY=value

[user@host ~]$ cat ansible.cfg
...output omitted...
[galaxy_server.automation_hub]
url=https://console.redhat.com/api/automation-hub/
auth_url=https://sso.redhat.com/auth/realms/redhat-external/protocol/openid-connect/token
[user@host ~]$ export \
> ANSIBLE_GALAXY_SERVER_AUTOMATION_HUB_TOKEN='eyJh...Jf0o'
[user@host ~]$ ansible-galaxy collection install redhat.insights

Configuring ansible-galaxy to get content from a private automation hub is similar to how it is configured to use automation hub. The following example includes a new section that configures ansible-galaxy to use a private automation hub installed on hub.example.com.

...output omitted...
[galaxy]
server_list = my_hub, automation_hub, galaxy

[galaxy_server.my_hub]
url=https://hub.example.com/api/galaxy/content/rh-certified/
token=e8e4...b0c2

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

[galaxy_server.galaxy]
url=https://galaxy.ansible.com/

Notice that you do not need the auth_url directive for private automation hub.

Use the private automation hub web UI to retrieve the URL and generate the token.

Navigate to Collections → Repository Management to retrieve the URL. Private automation hub can host collections that you have synchronized from automation hub, from Ansible Galaxy, or that you have created for your teams. Select the URL corresponding to the type of collection you want to install.

To generate a token, either click Get token on the Repo Management page or navigate to Collections → API token management and then click Load token.

Installing and deploying private automation hub is beyond the scope of this course.