Custom Extended Roles in IAG 2023.1 & IAG 2022.1

This guide explains how to pull configuration from a NETCONF device and provide it in XML format within IAP Configuration Manager. The ability to check the state of the device also is detailed.

Quick-Start Ansible Roles

Itential Automation Gateway contains several pre-defined Ansible roles for the most commonly used devices in customer networks:

• Aruba
• ASA
• BigIP
• EOS
• IOS
• IOSXR
• Junos
• NX-OS
• SROS

IAG Device Inventory Field to Trigger Custom Roles

For custom roles, Automation Gateway (IAG) uses the ansible_network_os device inventory field to trigger which specific role to use. In the example below (Figure 1), the netconf-device is the device type that will be used to trigger the new role.

Figure 1

Process to Extend Custom Roles

Follow these steps to extended the device roles through custom roles.

Note: In the example process, a Cisco-IOS router has been configured to communicate via NETCONF.

Copy Extensible Device Roles Directory to Itential Home Directory

1. From the command prompt of the IAG server, find the location of the /automation_gateway/integrations/extensible_device_roles directory using the find command.

   find / -type d -name "automation_gateway" -ls
   

2. Copy the entire directory to the Itential home directory. This maintains the custom roles when IAG is upgraded, and you can easily find them later.

   cp -rf .../automation_gateway/integrations/extensible_device_roles/home/itential
   

3. Once copying is complete, change to the Itential directory.

   cd /home/Iential/
   

4. Issue the tree command to display the directory tree structure (Figure 2).

   tree
   

   
   

   Figure 2
   

   
   

Copy Role Directories to Device

In this part of the process, the focus is primarily on two role directories: iag_get_config and iag_get_state.

1. Copy the iag_get_config/include/ios directory to netconf-device.

   cd /home/itential/extensible_device_roles/iag_get_config/includes
   
   cp -rf ios netconf-device
   
   vi netconf-device/get_config.yml
   

2. Replace the contents of the get_config.yml file with the config below.

   ---
   - name: execute "show running-config" on ios platform
     ios_command:
       commands: "show running-config"
     register: config_results
     when: ansible_connection == "network_cli"
   
   - name: execute "get config" on ios platform
     ansible.netcommon.netconf_rpc:
       rpc: get-config
       content:
         <source><running/></source>
       display: pretty
     register: config_results_netconf
     when: ansible_connection == "netconf"
   
   - name: itential_get_config response
     itential_ios_get_config_response_builder:
       get_config_results: "{{ config_results }}"
     delegate_to: localhost
     when: ansible_connection == "network_cli"
   
   - name: itential_get_config response
     itential_ios_netconf_get_config_response_builder:
       get_config_results: "{{ config_results_netconf }}"
     delegate_to: localhost
     when: ansible_connection == "netconf"
   

3. Copy the iag_get_state/includes/ios directory to netconf-device.

   cd /home/itential/extensible_device_roles/iag_get_state/includes
   
   cp -rf ios netconf-device
   
   vi netconf-device/get_state.yml
   

4. Replace the contents of the get_state.yml file with the config below.

   ---
   - name: itential_get_state response
     ios_command:
       commands: "show version"
     when: ansible_connection == "network_cli"
   
   - name: itential_get_state response from netconf-device
     ansible.netcommon.netconf_rpc:
       rpc: get-config
       content:
         <source><running/></source>
     when: ansible_connection == "netconf"
   

Modify Ansible Configuration to Discover Extended Roles

After updating to the .yml files in the previous steps, make sure the extended roles are discovered by IAG. This is accomplished by making updates to the system configuration section of the IAG UI.

1. Login to Automation Gateway and expand the Configuration section in the side navbar.
2. In the Automation Gateway module, select "Ansible". The Ansible Configuration page displays.
3. Go to the Extended Device Role Path field.
4. Click "+ Row" and input the /home/itential/extensible_device_roles path to the customized roles (Figure 3).
5. Click the save icon at the top of the page under Ansible Configuration to retain your change. This will ensure IAG goes through a rediscover process to find the updated role assets.

Figure 3

Add Device Configuration Variables

Next, add the necessary device configuration to communicate via netconf with the Ansible Device inventory.

1. Navigate back to the Automation Gateway home page.

2. Expand the Ansible section in the left navbar.

3. Expand the Devices collection and refresh the inventory.

4. Select the netconf device inventory.

5. Click Edit to open the configuration editor.

6. Add the device variables to the inventory. Use the example entry below.

   {
       "ansible_port": "830",
       "ansible_host": "192.168.0.248",
       "ansible_network_os": "netconf-device",
       "ansible_user": "cisco",
       "ansible_connection": "netconf",
       "ansible_password": "cisco",
       "get_state_command": "<hello>"
   }
   

7. Click Save to retain your changes.

8. Once the device is added to the inventory, validate that IAG is using the newly created extended role by clicking the Test Connection button at the bottom of the UI.

   Figure 4
   

9. If the device is configured to communicate via netconf on port 830 and the roles are successfully updated, a success message displays (Figure 5).

   Figure 5
   

   
   

Validate Extended Roles

Once configuration testing is complete, additional tests can be performed to validate the role is pulling the configuration in the netconf XML format.

1. From the Ansible section within IAG, click on Roles to expand the list.

2. Select the itential_get_config role.

3. Select the Execute tab and then click the run ( ► ) button to validate the configuration is being pulled via the custom role that was created.

   Figure 6
   

4. If validation is successfully executed, a "Success" status displays.

   Figure 7
   

   
   

Validate Device in IAP

As a final step, go to IAP and validate the device was added to Configuration Manager.

1. Navigate to IAP → Configuration Manager.
2. In the Devices list, select the netconf device to display its Device Details, including the native netconf XML format under the Configuration tab.

Figure 8

Extending Device Roles to Validate a Configuration Push

Throughout this guide, pulling a configuration from a NETCONF enabled device and checking its state was meticulously covered; however, you can also validate that an extensible role configuration is being pushed to the iag_set_config directory via commands sent to iag_cli via NETCONF.

Example: Junos Set Config View

You can use the Junos set_config view to accomplish various tasks such as viewing, adding, updating, and deleting a Junos configuration using the set_config command when working within IAP and IAG.

Copy the Role Directories

Using the above details for building out a NETCONF extended role as a foundation, follow these steps to return a JUNOS set config view instead of an object-oriented view. For this example, the network-os type is junos-set.

1. Copy the iag_get_state/includes/ios directory to junos-set.

   cd /home/itential/extensible_device_roles/iag_get_state/includes
   
   cp -rf ios junos-set
   
   vi junos-set/get_state.yml
   

   
   

2. Replace the contents of the get_state.yml file with the config below.

   ---
   # This task must be named 'itential_get_state response'
   #
   - name: itential_get_state response
     junos_command:
       commands: "show version"
   

   
   

3. Copy the iag_get_config/includes/ios directory to junos-set.

   cd /home/itential/extensible_device_roles/iag_get_config/includes
   
   cp -rf ios junos-set
   
   vi junos-set/get_state.yml
   

   
   

4. Replace the contents of the get_state.yml file with the config below.

   ---
   - name: execute "show configuration" on junos platform
     junos_command:
       commands: "show configuration"
       display: set
     register: config_results
   
   - name: itential_get_config response
     itential_get_config_response_builder:
       get_config_results: "{{ config_results }}"
     delegate_to: localhost
   

   
   

5. Copy the iag_set_config/includes/ios directory to junos-set.

   This is an additional step to add, modify, replace or delete the config when working with automations and other IAP applications.

   cd /home/itential/extensible_device_roles/iag_set_config/includes
   
   cp -rf ios junos-set
   
   vi junos-set/set_config.yml
   

   
   

6. Replace the contents of the set_config.yml file with the config below.

   ---
   - name: execute config module on junos platform
     vars:
        parent_path: "{{ item.parents | join(' ') }}"
   
     junos_config:
       lines: "{{ parent_path + ' ' + item.config_line }}"
       src_format: set
     ignore_errors: True
     register: config_results
     when:  item.action is match("add") or item.action is match("modify")
   
   - name: itential_set_config response
     itential_set_config_response_builder:
       request: "{{ item }}"
       set_config_results: "{{ config_results }}"
     ignore_errors: True
     delegate_to: localhost
     when:  item.action is match("add") or item.action is match("modify")
   
   - name: execute config module on junos platform
     vars:
        parent_path: "{{ item.parents | join(' ') }}"
        delete_config_line: "{{ item.config_line | replace('set','') | replace('delete','') }}"
   
     junos_config:
       lines: "{{ 'delete' + parent_path + delete_config_line }}"
     ignore_errors: True
     register: config_results
     when:  item.action is match("delete")
   
   - name: itential_set_config response
     itential_set_config_response_builder:
       request: "{{ item }}"
       set_config_results: "{{ config_results }}"
     ignore_errors: True
     delegate_to: localhost
     when:  item.action is match("delete")
   
   - name: itential_set_config response
     itential_set_config_response_builder:
       request: "{{ item }}"
       set_config_results: "{{ {'error_msg': 'action: ' + item.action + ' is invalid', 'failed': True} }}"
     ignore_errors: True
     delegate_to: localhost
     when:  item.action != "delete" and item.action != "add" and item.action != "modify"
   

   
   

Modify Ansible Configuration to Discover Junos Roles

After adding and updating all three .yml files, make sure the extended roles are discovered by IAG.

1. Navigate to Automation Gateway → Configuration → Automation Gateway module.
2. Select "Ansible" to open the Ansible Configuration page.
3. Go to the Extended Device Role Path field and click "+ Row".
4. Input the /home/itential/extensible_device_roles path to the customized roles (Figure 9) and click the save icon. This will ensure IAG goes through a rediscover process to find the updated role assets.

Figure 9

Add the Junos Device Configuration

Next, add the device configuration into your inventory to use the new role.

1. Navigate back to Automation Gateway → Ansible → Devices.

2. Select the junos-set device inventory.

3. Click Edit to open the configuration editor.

4. Add the device variables to the inventory. Use the example entry below.

   {
       "ansible_port": "22",
       "ansible_host": "192.168.0.250",
       "ansible_network_os": "junos-set",
       "ansible_user": "root",
       "ansible_connection": "local",
       "ansible_password": "*********",
   }
   

5. Click Save and validate that IAG is using the newly created extended role by clicking the Test Connection button at the bottom.

   Figure 10
   

6. If the device is configured to communicate via junos-set on port 22 and the roles are successfully updated, a success banner displays (Figure 11).

   Figure 11
   

   
   

Validate the Junos Device

Once configuration testing is complete, validate the role is pulling the configuration in the junos-set format.

1. Navigate to Automation Gateway → Ansible → Roles.

2. Select the itential_get_config role.

3. Select the Execute tab and then click the run ( ► ) button to validate the configuration is being pulled via the custom role that was created. If validation is successfully executed, a "Success" banner displays.

   Figure 12
   

   
   

Validate the Junos Device in IAP

As a final step, go to IAP and validate the device was added to Configuration Manager.

1. Navigate to IAP → Configuration Manager → Devices.
2. Select srx_junos_setformat to display its Device Details, including its set_config view under the Configuration tab.

Figure 13