Execution paths

Depending on the inventory variables present for a device within the IAG Ansible inventory, an Itential role will take one of three different execution paths in the 2023.1 release version and higher. The role execution paths are categorized as follows:

• Fully integrated
• Netmiko customized templates
• Ansible customized templates

Fully integrated

The Fully integrated execution path includes a set of Ansible roles provided by IAG that are utilized for device types found in an internal “integrated device” table. The roles use well known Ansible modules supported by the Ansible community to retrieve operational state data from devices as well as retrieve and set the device configuration. A list of fully integrated devices can be found on this Platform compatibility page. You do not need to make any modifications in order to get the functionality provided by the Fully integrated roles.

Executing a role against a fully integrated device enables you to utilize the full suite of Itential Automation Gateway and Itential Platform features, such as Configuration Manager, Golden Configuration, and Command Templates.

Requirements

The device must be explicitly in the IAG list of integrated devices, and you can successfully connect to the device using Ansible connection parameters.

Important variables

The ansible_network_os variable must match a valid Ansible OS type, and it must be in the list of integrated devices, such as ios for Cisco IOS.

1
{
2
  "name": "Example_IOS",
3
  "ansible_host": "ios.example.com",
4
  "ansible_connection": "network_cli",
5
  "ansible_network_os": "ios",
6
  "ansible_user": "username",
7
  "ansible_password": "password",
8
  "ansible_become": true,
9
  "ansible_become_password": "password"
10
}

Netmiko customized templates

IAG provides a set of Ansible role templates that use the Netmiko library to connect and communicate with devices. The templates can be customized by users in order to communicate with devices that do not fall under the fully integrated category. This is only an option for devices which have prebuilt support from the Netmiko library. The list of devices supported by Netmiko is very large, however it has its own caveats and levels of support from that library. See Netmiko platforms for additional information regarding the device_type variable and options.

Executing a role that has been properly customized to use the Netmiko library enables you to utilize the majority of Itential Automation Gateway and Itential Platform features, such as Configuration Manager, Golden Configuration, and Command Templates.

Requirements

The device is not in the IAG list of integrated devices, and you can successfully connect to the device using Netmiko connection parameters.

Directory path

The templates for the Ansible roles that use the Netmiko library can be found in the IAG release package at the following directory path:

automation_gateway/integrations/extensible_device_roles/ansible_netmiko

The roles should be copied to a new directory on the IAG server before they are modified in order to avoid being overwritten upon the next upgrade of IAG.

$
# ls
$
itential_netmiko_cli  itential_netmiko_get_config  itential_netmiko_get_state  itential_netmiko_load_config  itential_netmiko_set_config
$
# cp -R * /new/path/to/custom/ansible_netmiko

Configuration

In order for the itential_netmiko_* roles to be found at execution time, the directory path where they were saved needs to be configured using the Automation Gateway UI. After logging into IAG, go to the Configuration → Ansible tab, add the full directory path to the Extended Device Role Path parameter, and save the configuration.

Execution

The main Itential roles (i.e., itential_cli, itential_get_config, etc.) are used as an entry point to execute the Ansible roles using the Netmiko library (i.e., itential_netmiko_cli, itential_netmiko_get_config, etc.). The Itential roles decide which code path to execute based on the presence and contents of different Ansible inventory variables. Below is the criteria that will cause the Netmiko customized template roles to be executed along with some example devices with variables that will match the criteria.

Important variables

• The ansible_network_os variable must not match the name of a fully integrated device and should generally be omitted to avoid confusion and ensure the correct execution path is followed.
• A local connection type is required; therefore ansible_connection must be set to local.
• Either provider.device_type or netmiko_device_type must be a valid Netmiko device_type.

Example host (explicit usage)

The following example host shows an explicit set of Netmiko-related variables nested under the provider object so that it is clear that this host is meant to be used only with the Netmiko roles.

1
{
2
    "name": "Example_IOS",
3
    "variables": {
4
5
        "**********REQUIRED VARIABLES**********": "",
6
7
        "ansible_connection": "local",
8
        "provider": {
9
            "host": "ios.example.com",
10
            "device_type": "cisco_ios",
11
            "username": "username",
12
            "password": "password"
13
        },
14
15
        "**********END REQUIRED VARIABLES**********": "",
16
17
18
        "**********OPTIONAL VARIABLES**********": "",
19
20
        "end_command": "end",
21
        "save_command": "commit apply",
22
        "get_config_command": "show run",
23
        "get_state_command": "show version",
24
25
        "**********END OPTIONAL VARIABLES**********": ""
26
    }
27
}

Example host (implicit usage)

The following example host shows an implicit set of Netmiko-related variables declared outside of the provider object. This method allows you to use mostly Ansible variables, which are converted into the provider object within the role template, along with the addition of netmiko_device_type so that it is correctly routed to the Netmiko roles.

1
{
2
    "name": "Example_IOS",
3
    "variables": {
4
5
      "**********REQUIRED VARIABLES**********": "",
6
7
      "ansible_connection": "local",
8
      "ansible_host": "ios.example.com",
9
      "ansible_user": "username",
10
      "ansible_password": "password",
11
      "netmiko_device_type": "cisco_ios",
12
13
      "**********END REQUIRED VARIABLES**********": "",
14
15
16
      "**********OPTIONAL VARIABLES**********": "",
17
18
      "ansible_port": 22,
19
      "end_command": "end",
20
      "save_command": "commit apply",
21
      "get_config_command": "show run",
22
      "get_state_command": "show version",
23
24
      "**********END OPTIONAL VARIABLES**********": ""
25
  }
26
}

Ansible customized templates

IAG provides a set of Ansible role templates that can be customized by users to use their Ansible modules of choice to connect and communicate with devices. The templates are available for use with devices that do not fall under the fully integrated list and cannot be configured to work with the Netmiko library.

Executing a role that has been properly customized enables you to utilize the majority of Itential Automation Gateway and Itential Platform features, such as Configuration Manager, Golden Configuration, and Command Templates.

Requirements

• The device cannot be executed against the fully integrated or Netmiko customized roles.
• The ansible_network_os variable must not be in the list of integrated device types and should instead be a custom value that matches the custom role you created (see the templates for additional information).

Directory path

The Ansible customized template roles can be found in the IAG release package at the following directory path:

automation_gateway/integrations/extensible_device_roles/ansible_custom

The roles should be copied to a new directory on the IAG server before they are modified in order to avoid being overwritten upon the next upgrade of IAG.

$
# ls
$
iag_cli  iag_get_config  iag_get_state  iag_load_config  iag_set_config
$
# cp -R * /new/path/to/custom/ansible_custom

Configuration

In order for the iag_* roles to be found at execution time, the directory path where they were saved needs to be configured using the IAG UI. After logging into the UI, go to the Configuration → Ansible tab, add the full directory path to the Extended Device Role Path parameter, and save the configuration.

Execution

The main Itential roles (i.e., itential_cli, itential_get_config, etc.) are used as an entry point to execute the Ansible customized roles (i.e., iag_cli, iag_get_config, etc.). The Itential roles decide which code path to execute based on the presence and contents of different Ansible inventory variables. Below is the criteria that will cause the Ansible customized template roles to be executed along with an example device with variables that will match the criteria.

Important variables

The ansible_network_os variable must not match the name of a fully integrated device, and the variables netmiko_device_type and provider.device_type must not be present.

Example host

The following example host shows a set of Ansible custom variables.

1
{
2
  "name": "Example_IOS",
3
  "ansible_host": "ios.example.com",
4
  "ansible_connection": "network_cli",
5
  "ansible_network_os": "custom_unsupported_ios",
6
  "...any other custom variables for your custom role...": "..."
7
}