Network Automation with Red Hat Ansible Automation Platform

When Ansible was first developed, all the modules that it used were included as part of the core software package. As the number of modules increased, it became harder for the upstream project to manage all these modules. Every module required a unique name and synchronizing module updates with updates to the core Ansible code.

With Ansible Content Collections, Ansible code updates are separated from updates to modules and plug-ins. An Ansible Content Collection provides a set of related modules, roles, and other plug-ins that you can use in your playbooks. This approach enables vendors and developers to maintain and distribute their collections at their own pace, independently of Ansible releases.

For example:

Ansible Content Collections also provide flexibility. You can install only the content you need instead of installing all supported modules.

You can also select a specific version of a collection (possibly an earlier or later one) or choose between a version of a collection supported by Red Hat or vendors, or one provided by the community.

Ansible 2.9 and later support Ansible Content Collections. Upstream Ansible unbundled most modules from the core Ansible code in Ansible Base 2.10 and Ansible Core 2.11 and placed them in collections. Red Hat Ansible Automation Platform 2.3 provides automation execution environments based on Ansible Core 2.14 that inherit this feature.

Before your playbooks can use content from an Ansible Content Collection, you must ensure that the collection is available in your automation execution environment.

The Ansible configuration collections_paths setting specifies a colon-separated list of paths on the system where Ansible looks for installed collections.

You can set this directive in the ansible.cfg configuration file.

[defaults]
collections_paths = ./collections:/usr/share/ansible/collections

The following example uses the ansible-galaxy collection install command to download and install the network.ospf Ansible Content Collection. The -p collections option installs the collection in the local collections subdirectory.

[user@controlnode ~]$ ansible-galaxy collection install network.ospf \
-p collections

The ansible-galaxy command can also install a collection from a local or a remote .tar file, or a Git repository. A Git repository must have a valid galaxy.yml or MANIFEST.json file that provides metadata about the collection, such as its namespace and version number. For example, see the ansible.netcommon collection at https://github.com/ansible-collections/ansible.netcommon.

[user@controlnode ~]$ ansible-galaxy collection install \
/tmp/ansible-netcommon-5.1.0.tar.gz -p collections
...output omitted...
[user@controlnode ~]$ ansible-galaxy collection install \
http://www.example.com/network-bgp-2.0.0.tar.gz -p collections
...output omitted...
[user@controlnode ~]$ ansible-galaxy collection install \
git@git.example.com:organization/repo_name.git -p collections

---
collections: 
  - name: network.ospf 

  - name: network.base
    version: 2.0.0 

  - name: /tmp/ansible-netcommon-5.1.0.tar.gz 

  - name: http://www.example.com/network-bgp-2.0.0.tar.gz 

  - name: git+https://github.com:redhat-cop/network.vpn.git 
    version: main

[user@controlnode ~]$ ansible-galaxy collection install \
-r collections/requirements.yml -p collections

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

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

export ANSIBLE_GALAXY_SERVER_<SERVER_ID>_<KEY>=value

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

After you install an Ansible Content Collection in your Ansible project, you can use it with that project's Ansible Playbooks.

You can use the ansible-navigator collections -m interactive command in your Ansible project directory to list all the collections that are installed in your automation execution environment. This includes the Ansible Content Collections in your project's collections subdirectory.

You can select the line number of the collection in the interactive mode of ansible-navigator to view its contents. Then, you can select the line number of a module, role, or other plug-in to see its documentation. You can also use other tools, such as ansible-navigator doc, with the fully qualified collection name of a module to view that module's documentation.

The following playbook invokes the cli_config module from the ansible.netcommon collection for a task.

---
- name: Update the configuration on junos1.lab.example.com
  hosts: junos1.lab.example.com

  tasks:
    - name: Ensure the proper configuration is in place
      ansible.netcommon.cli_config:
        replace: /var/home/ansible/junos01.cfg

The following playbook uses the run role from the network.ospf collection.

- name: Perform health checks
  hosts: ios
  gather_facts: false

  tasks:
  - name: OSPF Manager
    ansible.builtin.include_role:
      name: network.ospf.run
    vars:
      actions:
        - name: health_check
          vars:
            details: true
            checks:
              - name: all_neighbors_up
              - name: all_neighbors_down
              - name: min_neighbors_up
                min_count: 1
              - name: ospf_status_summary