DO457 - ch04s08

Bookmark this page

Guided Exercise: Using Filters to Parse Command Output

Use filters to process the output of commands.

Outcomes

Use options to modify the output of the ansible.utils.ipaddr filter.
Use filters to extract data gathered by querying the automation controller API.

As the student user on the workstation machine, use the lab command to prepare your system for this exercise, and to ensure that all required resources are available. This command also creates a project directory with the files needed for the exercise.

[student@workstation ~]$ lab start manage-filters

Instructions

Use the provided playbooks to explore options to the ansible.utils.ipaddr filter and to query information about automation controller. These playbooks use the ansible.builtin.debug module to apply filters and return output.

Open the /home/student/manage-filters directory in VS Code and view the filter_data.yml playbook.

Open VS Code and navigate to File → Open Folder.
Navigate to Home → manage-filters 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.

Click the filter_data.yml playbook. The possible_options variable defines the options that this playbook accepts for the ansible.utils.ipaddr filter. The top of the playbook displays sample commands with each of these options.

---
# Sample commands:
# ansible-navigator run filter_data.yml -e option=host
# ansible-navigator run filter_data.yml -e option=net
# ansible-navigator run filter_data.yml -e option=private
# ansible-navigator run filter_data.yml -e option=public
- name: Play for the "Filtering Data" section of the lecture
  hosts: localhost
  gather_facts: false
  vars:
    samples: 
      - 192.168.2.1
      - 10.0.0.128/25
      - 172.24.10.0/255.255.255.0
      - 172.24.10.0/255.255.255.255
      - ff02::1
      - ::1
      - 2001::1/64
      - 2001::/64
      - learn.spidernet.pl
    possible_options:
      - host    # Return valid hosts and use a CIDR prefix
      - net     # Return valid networks and use a CIDR prefix
      - private # Return hosts and networks in the private range of addresses
      - public  # Return hosts and networks in the public range of addresses
  tasks:
    - name: Fail if the 'option' variable is not defined or is invalid 
      ansible.builtin.assert:
        that:
          - option is defined
          - option in possible_options
        fail_msg: >-
          The 'option' variable must be defined and have one of the following
          values {{ possible_options }}.

    - name: Display the 'samples' variable 
      ansible.builtin.debug:
        var: samples

    - name: Use the "ansible.utils.ipaddr('{{ option }}')" filter expression 
      ansible.builtin.debug:
        var: samples | ansible.utils.ipaddr(option)

	The `samples` variable includes IPv4 and IPv6 hosts and networks. If desired, then you can add hosts and networks to the list.
	This playbook assumes that you pass the `option` variable, such as `-e option=host`. In this task, the `ansible.builtin.assert` module checks that the `option` variable has been defined and that the value of the variable matches one of four possible values.
	The playbook displays the `samples` variable so that you can compare the original value with the value returned by the filter.
	This task displays the result of using a filter expression on the `samples` variable.

Run the filter_data.yml playbook and set the value of the option variable to one of the choices in the possible_options variable.
1. Switch to the Terminal tab in VS Code, or change to the /home/student/manage-filters directory in a GNOME terminal:
```
[student@workstation ~]$ cd ~/manage-filters
[student@workstation manage-filters]$
```
2. Use the host option to the ansible.utils.ipaddr filter so that the filter only returns list items that are hosts. Notice that the filter ensures that each host contains a CIDR prefix.
```
[student@workstation manage-filters]$ ansible-navigator run filter_data.yml \
-e option=host

...output omitted...
TASK [Use the "ansible.utils.ipaddr('host')" filter expression] ****************
ok: [localhost] => {
    "samples | ansible.utils.ipaddr(option)": [
        "192.168.2.1/32",
        "172.24.10.0/32",
        "ff02::1/128",
        "::1/128",
        "2001::1/64"
    ]
}
...output omitted...
```
3. (Optional) Run the filter_data.yml playbook to explore the net, private, and public options to the ansible.utils.ipaddr filter. The top of the filter_data.yml playbook provides sample commands for you to run.

Run the manipulate.yml playbook to explore options to the ansible.utils.ipaddr filter that manipulate or extract components of a host address. The playbook sends a single host address to the ansible.utils.ipaddr filter and expects that you set the value of the option variable to one of the choices in the possible_options variable.

Click the manipulate.yml playbook in VS Code. This playbook uses options to the ansible.utils.ipaddr filter to return a component of the sample_address variable.

---
# Sample commands:
# ansible-navigator run manipulate.yml -e option=address
# ansible-navigator run manipulate.yml -e option=netmask
# ansible-navigator run manipulate.yml -e option=prefix
# ansible-navigator run manipulate.yml -e option=revdns
# ansible-navigator run manipulate.yml -e option=network
# ansible-navigator run manipulate.yml -e option=broadcast
- name: Tasks for the "Manipulating IP Addresses" section of the lecture
  hosts: localhost
  gather_facts: false
  vars:
    sample_address: 192.0.2.1/24
    possible_options:
      - address   # Return the address without a subnet mask or prefix
      - netmask   # Return the variable length subnet mask for the address
      - prefix    # Return the CIDR prefix for the address
      - revdns    # Return the DNS pointer record for the address
      - network   # Return the network address for the network
      - broadcast # Return the broadcast address for the network
  tasks:
    - name: Fail if the 'option' variable is not defined or is invalid
      ansible.builtin.assert:
        that:
          - option is defined
          - option in possible_options
        fail_msg: >-
          The 'option' variable must be defined and have one of the following
          values {{ possible_options }}.

    - name: Display the 'sample_address' variable
      ansible.builtin.debug:
        var: sample_address

    - name: Use the "ansible.utils.ipaddr('{{ option }}')" filter expression
      ansible.builtin.debug:
        var: sample_address | ansible.utils.ipaddr(option)

Run the manipulate.yml playbook to extract the address part of the sample_address variable:

[student@workstation manage-filters]$ ansible-navigator run manipulate.yml \
-e option=address

...output omitted...
TASK [Display the 'sample_address' variable] ***********************************
ok: [localhost] => {
    "sample_address": "192.0.2.1/24"
}

TASK [Use the "ansible.utils.ipaddr('address')" filter expression] *************
ok: [localhost] => {
    "sample_address | ansible.utils.ipaddr(option)": "192.0.2.1"
}
...output omitted...

(Optional) Run the manipulate.yml playbook to explore the netmask, prefix, revdns, network, and broadcast options to the ansible.utils.ipaddr filter. The top of the manipulate.yml playbook provides sample commands for you to run.

Run the controller.yml playbook to query the automation controller API. Rather than providing you with a finished filter expression, the following substeps have you incrementally adjust filters in the playbook to display information about existing credentials.

In VS Code, click the controller.yml playbook to display the playbook:

---
- name: Query automation controller API
  hosts: controller.lab.example.com
  gather_facts: false
  tasks:
    - name: Include controller_auth.yml 
      ansible.builtin.include_vars: vars/controller_auth.yml

    - name: Query for credentials 
      ansible.builtin.uri:
        url: https://{{ controller['host'] }}/api/v2/credentials/
        method: GET
        headers:
          Authorization: >-
            Basic {{ controller['username_password'] | string | b64encode }}
      register: query_credentials

    - name: Show query results 
      ansible.builtin.debug:
        var: query_credentials['json']['results']

	The first task includes a variable file that contains authentication information for the automation controller instance in the lab environment. Although not performed in this exercise, you might consider using Ansible Vault to encrypt files that contain sensitive information.
	The second task queries the automation controller API for information about credentials and saves the results of the query in the `query_credentials` variable.
	The third task displays the results of the query in JSON format. The `query_credentials['json']['results']` variable is an array that contains a list of existing credentials.

Run the controller.yml playbook. The playbook generates several lines of output. Scroll back through the output until you see the start of the output for the Show query results task.

The specific credential displayed in this example is not important and your output might be different. The important thing to notice is that there are different kinds of credentials and each credential has a name and a unique identification number (among other things).

[student@workstation manage-filters]$ ansible-navigator run controller.yml

...output omitted...
TASK [Show query results] ******************************************************
ok: [controller.lab.example.com] => {
    "query_credentials['json']['results']": [
        {
            "cloud": false,
            "created": "2023-04-27T19:27:43.561109Z",
            "credential_type": 18,
            "description": "",
            "id": 2,
            "inputs": {
                "url": "https://galaxy.ansible.com/"
            },
            "kind": "galaxy_api_token",
            "kubernetes": false,
            "managed": true,
            "modified": "2023-04-27T19:27:43.561121Z",
            "name": "Ansible Galaxy",
...output omitted...

Edit the controller.yml playbook so that the last task displays the names of the credentials. You can do this by using the map filter. Ensure that the last task contains the following content and then save the file:
```
...output omitted...
    - name: Show query results
      ansible.builtin.debug:
        var: query_credentials['json']['results'] | map(attribute='name')
```

Run the controller.yml playbook to display the credential names. Your playbook output might be slightly different.

[student@workstation manage-filters]$ ansible-navigator run controller.yml

...output omitted...
TASK [Show query results] ******************************************************
ok: [controller.lab.example.com] => {
    "query_credentials['json']['results'] | map(attribute='name')": [
        "Ansible Galaxy",
        "Automation Hub Community Repository",
        "Automation Hub Container Registry",
        "Automation Hub Published Repository",
        "Automation Hub RH Certified Repository",
        "Automation Hub Validated Repository",
        "Cisco IOS XE Auth",
        "Default Execution Environment Registry Credential",
        "Demo Credential",
        "Git Projects",
        "Juniper Junos Auth"
    ]
}
...output omitted...

Based on the previous output, you might want to display details for the Automation Hub Container Registry credential. You can do this by using the selectattr filter. Edit the controller.yml playbook. Ensure that the last task contains the following content and then save the file:
```
...output omitted...
    - name: Show query results
      ansible.builtin.debug:
        var: >-
          query_credentials['json']['results'] |
          selectattr('name', '==', 'Automation Hub Container Registry')
```
Note
Although not required, this task breaks up the variable into multiple lines. On the var option line, the hyphen after the greater-than (>) sign indicates that a newline character (\n) is not added to the end of the variable.

Run the controller.yml playbook to display information about the Automation Hub Container Registry credential. Your playbook output might be slightly different.

[student@workstation manage-filters]$ ansible-navigator run controller.yml

...output omitted...
TASK [Show query results] ******************************************************
ok: [controller.lab.example.com] => {
    "query_credentials['json']['results'] | selectattr('name', '==', 'Automation Hub Container Registry')": [
        {
            "cloud": false,
            "created": "2023-04-27T19:27:55.024754Z",
            "credential_type": 17,
            "description": "",
            "id": 8,
            "inputs": {
                "host": "hub.lab.example.com",
                "password": "$encrypted$",
                "username": "admin",
                "verify_ssl": true
            },
            "kind": "registry",
...output omitted...

Although automation controller stores a lot of information about each credential, only a small subset of that information might interest you. Based on the previous output, extract the value of the unique identification number of the credential. You can do this by adding the map filter after the selectattr filter.
Ensure that the last task contains the following content and then save the file:
```
...output omitted...
    - name: Show query results
      ansible.builtin.debug:
        var: >-
          query_credentials['json']['results'] |
          selectattr('name', '==', 'Automation Hub Container Registry') |
          map(attribute='id')
```

Run the controller.yml playbook to extract the identification number for the Automation Hub Container Registry credential. The identification number of your credential might be different from the following output:

[student@workstation manage-filters]$ ansible-navigator run controller.yml

...output omitted...
TASK [Show query results] ******************************************************
ok: [controller.lab.example.com] => {
    "query_credentials['json']['results'] |  selectattr('name', '==', 'Automation Hub Container Registry') | map(attribute='id')": [
        8
    ]
}
...output omitted...

Because the previous map filter only creates one array item, you can add another filter to select that item. Based on the previous output, edit the controller.yml playbook to add the first filter to the end of the previous expression.
Ensure that the last task contains the following content and then save the file:
```
...output omitted...
    - name: Show query results
      ansible.builtin.debug:
        var: >-
          query_credentials['json']['results'] |
          selectattr('name', '==', 'Automation Hub Container Registry') |
          map(attribute='id') |
          first
```

Run the controller.yml playbook to extract the previous identification number without the array:

[student@workstation manage-filters]$ ansible-navigator run controller.yml

...output omitted...
TASK [Show query results] ******************************************************
ok: [controller.lab.example.com] => {
    "query_credentials['json']['results'] | selectattr('name', '==', 'Automation Hub Container Registry') | map(attribute='id') | first": "8"
}
...output omitted...

Close the /home/student/manage-filters directory in VS Code and return to the /home/student directory from the CLI if you are using the GNOME terminal.
1. Click File → Close Folder to close the /home/student/manage-filters directory.
2. If you are using the GNOME terminal, run the cd command to return to the student home directory:
```
[student@workstation manage-filters]$ 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 manage-filters

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: Using Filters to Parse Command Output

Note

Note