DO457 - ch06s10

Bookmark this page

Guided Exercise: Installing and Using an Ansible Content Collection

Install an Ansible Content Collection and use a role or module from it in a playbook.

Outcomes

Configure various collection sources on a system to install collections.
Install collections from a private automation hub using a requirements file.
Create a playbook that uses a role provided by a collection.

As the student user on the workstation machine, use the lab command to prepare your system for this exercise. This command also creates a project directory with the files needed for the exercise.

[student@workstation ~]$ lab start simplify-collections

Instructions

Browse the Ansible Content Collections available from the classroom's private automation hub. Access the details for the validated network.ospf collection.
1. Use a browser to navigate to the private automation hub at https://hub.lab.example.com, and then log in as student using redhat123 as the password.
2. Navigate to Collections → Collections to browse the Ansible Content Collections. Because the network.ospf collection is a validated collection, select Validated from the Filter by repository menu.
3. Search for the collection by entering ospf in the search field. When the search completes, click the ospf tile.
4. Notice that the UI displays an ansible-galaxy collection install network.ospf command that you can use to install the collection. Click the Documentation tab. The Readme file provides information on how to use the run role included in the collection. The playbooks in this exercise use examples from the Readme file.
Open the /home/student/simplify-collections directory in VS Code. Configure the Ansible project in that directory to use collections installed in the collections subdirectory.
1. Open VS Code and click File → Open Folder.
2. Navigate to Home → simplify-collections and click Open.
  Note
  If prompted, select Trust the authors of all files in the parent folder 'student', and then click Yes, I trust the authors.
3. Switch to the Terminal tab in VS Code, or change to the /home/student/simplify-collections directory in a GNOME terminal:
```
[student@workstation ~] cd ~/simplify-collections
```
  Important
  You need to run the ansible-galaxy commands in this exercise from the /home/student/simplify-collections directory, which contains the Ansible project. This helps ensure that you use the correct configuration file and install Ansible Content Collections to the correct location.
4. Use the mkdir command to create the collections directory:
```
[student@workstation simplify-collections]$ mkdir collections
```
5. Create the ansible.cfg file with the following content:
```
[defaults]
collections_paths = ./collections:/usr/share/ansible/collections
```
  This collections_paths line indicates that collections are found in the project collections directory and the /usr/share/ansible/collections directory (where collections exist within an automation execution environment).
Configure the Ansible project in the /home/student/simplify-collections directory so that the ansible-galaxy command retrieves collections from the classroom's private automation hub. Enable access to the rh-certified and validated repositories.
1. From the private automation hub web UI, navigate to Collections → Repository Management. This page has the parameters that you need for configuring the ansible.cfg file. Click the Copy to clipboard icon in the CLI configuration column and the rh-certified row.
  Do not close your web browser window.
  Note
  You might need to collapse the web UI navigation bar or zoom out in your web browser to see the Copy to clipboard icon for the CLI configuration column.
  Figure 6.3: Copy settings for the Red Hat certified repository
2. Update the ansible.cfg file and add the lines that you copied to the clipboard in the preceding step. The updated ansible.cfg file contains the following content:
```
[defaults]
collections_paths = ./collections:/usr/share/ansible/collections

[galaxy]
server_list = rh-certified_repo

[galaxy_server.rh-certified_repo]
url=https://hub.lab.example.com/api/galaxy/content/rh-certified/
token=<put your token here>
```
3. Return to the Repo Management page in the private automation hub web UI. Click the Copy to clipboard icon in the CLI configuration column and the validated row.
  Do not close your web browser window.
  Figure 6.4: Copy settings for the validated repository
4. Update the ansible.cfg file to append the lines that you copied to the clipboard in the preceding step. The updated ansible.cfg file now contains the following content:
```
[defaults]
collections_paths = ./collections:/usr/share/ansible/collections

[galaxy]
server_list = rh-certified_repo

[galaxy_server.rh-certified_repo]
url=https://hub.lab.example.com/api/galaxy/content/rh-certified/
token=<put your token here>

[galaxy]
server_list = validated_repo

[galaxy_server.validated_repo]
url=https://hub.lab.example.com/api/galaxy/content/validated/
token=<put your token here>
```
  You added a second [galaxy] section to the file, but there can only be one [galaxy] section. You correct that problem in the next step.
5. Update the ansible.cfg file so that it only contains one [galaxy] section. Update the first [galaxy] section so that it lists both the rh-certified_repo and the validated_repo repositories. Remove the second [galaxy] section. The updated ansible.cfg file now contains the following content:
```
[defaults]
collections_paths = ./collections:/usr/share/ansible/collections

[galaxy]
server_list = rh-certified_repo, validated_repo

[galaxy_server.rh-certified_repo]
url=https://hub.lab.example.com/api/galaxy/content/rh-certified/
token=<put your token here>

[galaxy_server.validated_repo]
url=https://hub.lab.example.com/api/galaxy/content/validated/
token=<put your token here>
```
6. Return to the private automation hub web UI. Navigate to Collections → API token management and then click Load token. Copy the API token.
  Important
  Loading a new token invalidates any of your previous tokens.
7. Using the copied token, update both token lines in the ansible.cfg file. Your token is different from the token displayed in this example. Save and close the file when done:
```
[defaults]
collections_paths = ./collections:/usr/share/ansible/collections

[galaxy]
server_list = rh-certified_repo, validated_repo

[galaxy_server.rh-certified_repo]
url=https://hub.lab.example.com/api/galaxy/content/rh-certified/
token=c4f21af7090f0f9cb74d3c3f9e1748884ecdc180

[galaxy_server.validated_repo]
url=https://hub.lab.example.com/api/galaxy/content/validated/
token=c4f21af7090f0f9cb74d3c3f9e1748884ecdc180
```
Create a requirements.yml file in the project collections directory and then install the required collections.
1. Create the /home/student/simplify-collections/collections/requirements.yml file. Add the following content to require the 1.0.0 version of the network.ospf collection and the 2.0.0 version of the network.base collection:
```
---
collections:
  - name: network.ospf
    version: 1.0.0
  - name: network.base
    version: 2.0.0
```
2. In the /home/student/simplify-collections directory, use the ansible-galaxy command to install the required collections. Add the -r option to specify the location of the collections/requirements.yml file and add the --no-deps option so that the command does not install dependencies. The dependent collections are already available within the ee-supported-rhel8 automation execution environment.
```
[student@workstation simplify-collections]$ ansible-galaxy collection install \
-r collections/requirements.yml --no-deps
...output omitted...
network.ospf:1.0.0 was installed successfully
...output omitted...
network.base:2.0.0 was installed successfully
```
3. List the installed collections:
```
[student@workstation simplify-collections]$ ansible-galaxy collection list

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

# /home/student/simplify-collections/collections/ansible_collections
Collection        Version
----------------- -------
network.base      2.0.0
network.ospf      1.0.0
```
  Important
  The output in the /usr/share/ansible/collections/ansible_collections section displays collections installed on the local system, which is different from collections installed in an automation execution environment.
  To see collections available to automation content navigator from the project directory, run the following command:
```
[student@workstation simplify-collections]$ ansible-navigator collections \
-m interactive
```

View the provided /home/student/simplify-collections/ospf_deploy.yml playbook and then run the playbook to verify that it runs without errors.

View the ospf_deploy.yml playbook. This playbook configures Open Shortest Path First (OSPF) on the managed network nodes in the ios inventory group. The network.ospf.run role uses inventory variables defined in the inventory/hosts_vars directory.

---
- name: Deploy OSPF Configuration
  hosts: ios
  gather_facts: false
  tasks:
  - name: OSPF Manager (deploy)
    ansible.builtin.include_role:
      name: network.ospf.run
    vars:
      actions:
        - name: deploy
      inventory_directory: ./

Run the ospf_deploy.yml playbook. The playbook succeeds and the play summary indicates a change to both the iosxe1.lab.example.com and iosxe2.lab.example.com managed nodes.

[student@workstation simplify-collections]$ ansible-navigator run ospf_deploy.yml
...output omitted...
PLAY RECAP *********************************************************************
iosxe1.lab.example.com     : ok=19   changed=1    unreachable=0    failed=0  ...
iosxe2.lab.example.com     : ok=19   changed=1    unreachable=0    failed=0  ...

View the ospf_gather.yml playbook. This playbook uses the network.ospf.run role to display the OSPF configuration for managed network nodes in the ios inventory group.

---
- name: Gather OSPF Configuration
  hosts: ios
  gather_facts: false
  tasks:
  - name: OSPF Manager (gather)
    ansible.builtin.include_role:
      name: network.ospf.run
    vars:
      actions:
        - name: gather
      inventory_directory: ./

Run the ospf_gather.yml playbook to display the OSPF configuration.

Note

It might take a minute or two for the OSPF configuration changes to start and converge. If you do not see the expected output, then wait for a minute or two and try again.

[student@workstation simplify-collections]$ ansible-navigator run \
ospf_gather.yml
...output omitted...
TASK [network.base.resource_manager : Resource Facts] **************************
ok: [iosxe1.lab.example.com] => {
    "msg": {
        "ansible_connection": "ansible.netcommon.network_cli",
        "ansible_network_os": "cisco.ios.ios",
        "changed": false,
        "failed": false,
        "gathered": {
            "processes": [
                {
                    "network": [
                        {
                            "address": "172.25.250.0",
                            "area": "0",
                            "wildcard_bits": "0.0.0.255"
                        }
                    ],
                    "process_id": 110,
                    "router_id": "1.1.1.1"
                }
            ]
        },
        "resource_module_name": "cisco.ios.ios_ospfv2"
    }
}
ok: [iosxe2.lab.example.com] => {
    "msg": {
        "ansible_connection": "ansible.netcommon.network_cli",
        "ansible_network_os": "cisco.ios.ios",
        "changed": false,
        "failed": false,
        "gathered": {
            "processes": [
                {
                    "network": [
                        {
                            "address": "172.25.250.0",
                            "area": "0",
                            "wildcard_bits": "0.0.0.255"
                        }
                    ],
                    "process_id": 110,
                    "router_id": "2.2.2.2"
                }
            ]
        },
        "resource_module_name": "cisco.ios.ios_ospfv2"
    }
}
...output omitted...

Close the /home/student/simplify-collections directory in VS Code, or run the cd command in a GNOME terminal to return to the student home directory:
```
[student@workstation simplify-collections]$ cd
```

Finish

On the workstation machine, use the lab command to complete this exercise. This step is important to ensure that resources from previous exercises do not impact upcoming exercises.

[student@workstation ~]$ lab finish simplify-collections

Discuss Network Automation with Red Hat Ansible Automation Platform

Go to community

Welcome to the Red Hat Ansible for Network Automation (DO457) group!

Syed

26 wrz 2023

We are excited to launch a space dedicated to the Red Hat Training course Red Hat Ansible for Network Automation! To gain the most value from this group - click the "Join Group" button in the upper right hand corner of the group home page.We encourage group members to collaborate in this group to discuss topics, ask questions, share best practices and tips, provide course feedback, and share their accomplishments as it relates to DO457.Read more about Red Hat Ansible for Network Automation here.

3120

Revision: do457-2.3-7cfa22a

Network Automation with Red Hat Ansible Automation Platform

Guided Exercise: Installing and Using an Ansible Content Collection

Note

Important

Note

Important

Important

Note