Itential Automation GatewayAnsible

Built-in Ansible roles

Itential Automation Gateway (IAG) includes a collection of built-in Ansible roles that perform device monitoring and configuration tasks on supported device types. The roles use advanced features of the command and configuration networking modules developed, tested, and maintained by the Ansible open-source community. Devices are managed by running CLI and NETCONF commands over SSH. Device connectivity parameters are made available through the IAG inventory management subsystem.

Roles in Itential Automation Gateway

The following roles are distributed with Itential Automation Gateway.

RoleDescription
itential_cliExecute CLI commands on a network device.
itential_get_infoRetrieve the device serial number, OS version, and MAC addresses for all network interfaces.
itential_get_healthRetrieve CPU and memory statistics for a device.
itential_get_configRetrieve the current running configuration for a device.
itential_set_configAdd, modify, and delete specific configuration sections and lines on a device.
itential_load_configSend a raw configuration string to a device.
itential_restore_configReplace the current running configuration of a device with a completely new version.

Role examples

The following examples show request and response objects for select roles distributed with IAG.

itential_cli

This role also supports handling commands that require a prompt response to complete.

As of 2019.3, this role does not support handling command prompts for F5 (BigIP) devices or Junos devices that are configured with the ansible_connection variable set to netconf.

Request object

Sample:

1{
2  "hosts": [
3    "ios_aws"
4  ],
5  "args": {"command": ["show clock"]}
6}

Response object

Sample:

1[
2    {
3        "role": "itential_cli",
4        "task": "itential_cli response",
5        "host": "ios_host",
6        "status": "SUCCESS",
7        "argument_warnings": null,
8        "results": {
9            "stdout_lines": [
10                [
11                    "*08:45:04.200 UTC Fri Nov 8 2019"
12                ]
13            ],
14            "stdout": [
15                "*08:45:04.200 UTC Fri Nov 8 2019"
16            ],
17            "changed": false
18        }
19    }
20]

Request object for command prompts

Sample:

1{
2  "hosts": [
3    "ios_aws"
4  ],
5  "args":{"command": [{"command": "clear counters GigabitEthernet2", "prompt": ["confirm"], "answer": ["y"]}]}
6}

Response object for command prompts

Sample:

1[
2    {
3        "role": "itential_cli",
4        "task": "itential_cli response",
5        "host": "ios_aws",
6        "status": "SUCCESS",
7        "argument_warnings": null,
8        "results": {
9            "stdout_lines": [
10                [
11                    "Clear \"show interface\" counters on this interface [confirm]y"
12                ]
13            ],
14            "stdout": [
15                "Clear \"show interface\" counters on this interface [confirm]y"
16            ],
17            "changed": false
18        }
19    }
20]

itential_get_info

Request object

Sample:

1{
2  "hosts": [
3    "ios_aws"
4  ],
5  "args": {}
6}

Response object

Sample:

1{
2        "role": "itential_get_info",
3        "task": "itential_get_info response",
4        "host": "ios_aws",
5        "status": "SUCCESS",
6        "argument_warnings": null,
7        "results": {
8            "serial_number": "9IKZMWL4K0X",
9            "raw_ansible_facts": {
10                "ansible_net_serialnum": "9IKZMWL4K0X",
11                "ansible_net_all_ipv4_addresses": [
12                    "10.11.0.72"
13                ],
14                "ansible_net_model": "CSR1000V",
15                "ansible_net_hostname": "ph10894c",
16                "ansible_net_gather_subset": [
17                    "hardware",
18                    "default",
19                    "interfaces"
20                ],
21                "ansible_net_interfaces": {
22                    "GigabitEthernet1.1": {
23                        "macaddress": "0e4e.fc45.d044",
24                        "lineprotocol": "down ",
25                        "description": null,
26                        "duplex": null,
27                        "mediatype": null,
28                        "mtu": 1500,
29                        "operstatus": "deleted",
30                        "bandwidth": 1000000,
31                        "ipv4": [],
32                        "type": "CSR vNIC"
33                    },
34                    "GigabitEthernet1": {
35                        "macaddress": "0e4e.fc45.d044",
36                        "lineprotocol": "up ",
37                        "description": null,
38                        "duplex": "Full",
39                        "mediatype": "RJ45",
40                        "mtu": 1500,
41                        "operstatus": "up",
42                        "bandwidth": 1000000,
43                        "ipv4": [
44                            {
45                                "subnet": "24",
46                                "address": "10.11.0.72"
47                            }
48                        ],
49                        "type": "CSR vNIC"
50                    }
51                },
52                "ansible_net_version": "03.16.02.S",
53                "ansible_net_all_ipv6_addresses": [],
54                "ansible_net_memtotal_mb": 1672835,
55                "ansible_net_filesystems": [
56                    "bootflash:"
57                ],
58                "ansible_net_image": "bootflash:packages.conf",
59                "ansible_net_memfree_mb": 1442035
60            },
61            "interfaces": {
62                "GigabitEthernet1.1": {
63                    "macaddress": "0e4e.fc45.d044",
64                    "lineprotocol": "down ",
65                    "description": null,
66                    "duplex": null,
67                    "mediatype": null,
68                    "mtu": 1500,
69                    "operstatus": "deleted",
70                    "bandwidth": 1000000,
71                    "ipv4": [],
72                    "type": "CSR vNIC"
73                },
74                "GigabitEthernet1": {
75                    "macaddress": "0e4e.fc45.d044",
76                    "lineprotocol": "up ",
77                    "description": null,
78                    "duplex": "Full",
79                    "mediatype": "RJ45",
80                    "mtu": 1500,
81                    "operstatus": "up",
82                    "bandwidth": 1000000,
83                    "ipv4": [
84                        {
85                            "subnet": "24",
86                            "address": "10.11.0.72"
87                        }
88                    ],
89                    "type": "CSR vNIC"
90                }
91            },
92            "os_version": "03.16.02.S",
93            "changed": false
94        }
95    }

itential_get_health

The itential_get_health response returns a memory usage statistics object and an array of CPU usage objects.

The memory object contains total and free memory values in megabytes. Each object in the cpu_stats array reflects a sample period during which CPU usage was measured. The number of objects in the array is based on what sample periods are available from each device. Note that some network devices track CPU utilization as a percentage, while others use the concept of load average.

The following keys are contained in each CPU usage object.

KeyDescription
valueCPU utilization (percentage) or load average.
typeUtilization or loading.
periodSample space (in seconds) in which the value was calculated.

Request object

Sample:

1{
2  "hosts": [
3    "ios_aws"
4  ],
5  "args": {}
6}

Response object

Sample:

1[
2   {
3        "role": "itential_get_health",
4        "task": "itential_get_health response",
5        "host": "ios_aws",
6        "status": "SUCCESS",
7        "argument_warnings": null,
8        "results": {
9           "memory": {
10                "memtotal_mb": 814,
11                "memfree_mb": 556
12           },
13           "cpu_stats": [
14                { "value": 15, "type": "utilization", "period": 5 },
15                { "value": 20, "type": "utilization", "period": 60 },
16                { "value": 32, "type": "utilization", "period": 300 }
17           ],
18           "changed": false
19        }
20   },
21   {
22        "role": "itential_get_health",
23        "task": "itential_get_health response",
24        "host": "eos_host",
25        "status": "SUCCESS",
26        "argument_warnings": null,
27        "results": {
28           "memory": {
29                "memtotal_mb": 1970,
30                "memfree_mb": 1120
31           },
32           "cpu_stats": [
33                { "value": 0.8, "type": "loadavg", "period": 60 },
34                { "value": 0.2, "type": "loadavg", "period": 300 },
35                { "value": 0.2, "type": "loadavg", "period": 900 }
36           ],
37           "changed": false
38        }
39   }
40]

itential_get_config

The results returned in the config_data field can be passed directly as the value for the config_file parameter of the itential_restore_config role.

Request object

Sample:

1{
2  "hosts": [
3    "ios_host"
4  ],
5  "args": {}
6}

Response object

Sample:

1{
2        "role": "itential_get_config",
3        "task": "itential_get_config response",
4        "host": "ios_host",
5        "status": "SUCCESS",
6        "argument_warnings": null,
7        "results": {
8            "config_data": "! Last configuration change at 01:11:48 UTC Thu Feb 7 2019 by admin\n!\nversion 15.4\n
9service timestamps debug datetime msec\nservice timestamps log datetime msec\nno platform punt-keepalive disable-kernel-core\n
10platform console virtual\n!\nhostname roland-router\n!\nboot-start-marker\nboot-end-marker\n!\n!\n
11enable secret 5 $1$.U3b$Uoy64G6eZ4qXzCbihv9rd0\nenable password admin\n!\naaa new-model\n!\n!\naaa authentication login default local\n
12aaa authorization exec default local none \n!\n!\n!\n!\n!\naaa session-id common\n!\n!\n!\n!\n!\n!\n!\n\n\n
13ip domain name test.example.com\n!\n!\n!\n!\n!\n!\n!\n!\n!\n!\nsubscriber templating\nmultilink bundle-name authenticated\n
14!\n!\nlicense udi pid CSR1000V sn 9V86NBL1EE6\n!\nusername admin privilege 15 password 0 admin\n!\nredundancy\n mode none\n
15!\n!\n!\nip ssh time-out 60\nip ssh authentication-retries 2\nip ssh version 2\nip ssh pubkey-chain\n  username admin\n
16   key-hash ssh-rsa 3141D7C2ECA54D3611445D83564F8391 roland.provencher@itential.comendend\nip scp server enable\n
17!\n!\n!\n!\ninterface GigabitEthernet1\n ip address 10.0.2.15 255.255.255.0\n negotiation auto\n!\ninterface GigabitEthernet2\n
18 ip address 192.168.32.40 255.255.255.0\n negotiation auto\n!\n!\nvirtual-service csr_mgmt\n!\nip forward-protocol nd\n!\n
19no ip http server\nno ip http secure-server\n!\n!\nsnmp-server community redhat RO\nsnmp-server community REDSOX RO\n
20snmp-server community PATS RO\n!\n!\n!\n!\ncontrol-plane\n!\n!\nline con 0\n stopbits 1\nline aux 0\n stopbits 1\n
21line vty 0 4\n privilege level 15\n password admin\n login authentication local\n transport input ssh\n!\n!\nend",
22            "changed": false,
23            "_ansible_delegated_vars": {
24                "ansible_delegated_host": "localhost",
25                "ansible_host": "localhost"
26            }
27        }
28}

itential_set_config

The itential_set_config role takes an array of transactions as an argument. Each transaction is an object representing a single configuration line applied to the device configuration in the order it appears in the array.

Each transaction is treated individually and produces its own status and results. A failure on one transaction doesn’t stop the next transaction from being attempted.

A transaction object consists of the following fields.

FieldDescription
actionConfiguration action to perform on a device. Possible values are add, modify, and delete.
parentsThe ordered set of parents that uniquely identify the section or hierarchy the configuration line should be applied against. If the parents argument is empty, the configuration line is applied against the root of the configuration tree.
config_lineThe configuration line being acted upon by the device. The line must match the native device configuration syntax.
idOptional. String parameter that can be used to match a transaction request with the corresponding device configuration response. The id string is returned as a key in the config_response results object of the role.

Request object

Sample:

1{"hosts":["eos_host"],
2 "args":{"transactions": [{"action": "add", "parents": ["interface Management 1"], "config_line": "ip address 10.0.5.17/24", "id": "first"},
3                          {"action": "modify", "parents": ["interface Management 1"], "config_line": "ip address 10.0.5.27/24", "id": "second" },
4                          {"action": "delete", "parents": [""], "config_line": "ip address 10.0.5.27/24", "id": "third"}] }, "strict_args": true }

Response object

Sample:

1[
2    {
3        "role": "itential_set_config",
4        "task": "itential_set_config response",
5        "host": "eos_host",
6        "status": "SUCCESS",
7        "argument_warnings": null,
8        "results": {
9            "config_request": {
10                "action": "add",
11                "config_line": "ip address 10.0.5.17/24",
12                "parents": [
13                    "interface Management 1"
14                ],
15                "id": "first"
16            },
17            "config_response": {
18                "failed": false,
19                "id": "first"
20            },
21            "changed": false
22        }
23    },
24    {
25        "role": "itential_set_config",
26        "task": "itential_set_config response",
27        "host": "eos_host",
28        "status": "SUCCESS",
29        "argument_warnings": null,
30        "results": {
31            "config_request": {
32                "action": "modify",
33                "config_line": "ip address 10.0.5.27/24",
34                "parents": [
35                    "interface Management 1"
36                ],
37                "id": "second"
38            },
39            "config_response": {
40                "failed": false,
41                "id": "second"
42            },
43            "changed": false
44        }
45    },
46    {
47        "role": "itential_set_config",
48        "task": "itential_set_config response",
49        "host": "eos_host",
50        "status": "FAILURE",
51        "argument_warnings": null,
52        "results": {
53            "msg": "Configuration request failed",
54            "config_request": {
55                "action": "delete",
56                "config_line": "ip address 10.0.5.27/24",
57                "parents": [
58                    ""
59                ],
60                "id": "third"
61            },
62            "config_response": {
63                "msg": "Error on executing commands ['', 'no ip address 10.0.5.27/24']",
64                "failed": true,
65                "data": "no ip address 10.0.5.27/24\r\n% Invalid input\r\nlocalhost(config-s-ansibl)#",
66                "id": "third"
67            },
68            "changed": false
69        }
70    }
71]

itential_restore_config

The itential_restore_config role takes the argument config_file, which is a string buffer containing the device configuration file in its native format. The itential_get_config role returns the device configuration in its native format in the config_data key — those results can serve as a starting point for configuration modifications or be passed as-is to config_file.

SCP requirements for IOS (Cisco) and EOS (Arista) device types

Cisco IOS and Arista EOS devices require the new configuration file to be present on the system before the restore operation can execute. The itential_restore_config role handles this by using the Ansible scp module to transfer the new configuration file to the device. The following SCP and SSH key configuration requirements apply when using itential_restore_config on IOS and EOS devices.

1

Enable SCP on the device

SCP must be enabled using the following configuration mode command (IOS):

$ip scp server enable
2

Configure SSH keys

For the user account in the device inventory variable ansible_user, SSH keys must be set up between IAG and the IOS/EOS device so that a password isn’t required for device login. Otherwise, the SCP module times out and the role fails.

3

Set the private key file inventory variable

The inventory variable ansible_ssh_private_key_file must be present for the device and set to the path of the private key file created in the previous step.

Request object

Sample:

1{"hosts":["junos_host"],
2 "args":{"config_file": "## Last changed: 2019-01-11 06:31:03 UTC\nversion 12.1R1.9;\ngroups {\n    global;\n}\napply-groups global;\nsystem {\n    root-authentication {\n
3        encrypted-password \"$1$Fmd79e7l$0biZFh9lhSt1qb/E06HoL.\";\n    }\n    services {\n        ftp;\n        ssh;\n        netconf {\n            ssh;\n        }\n
4    }\n    syslog {\n        user * {\n            any emergency;\n        }\n        file messages {\n            any notice;\n            authorization info;\n
5       }\n        file interactive-commands {\n            interactive-commands any;\n        }\n    }\n}\ninterfaces {\n    em0 {\n        unit 0 {\n            family
6 inet {\n                address 192.168.32.30/24;\n            }\n        }\n    }\n}\nsnmp {\n    community itential;\n    community redhat;\n}"
7       },
8 "strict_args": true
9 }

Response object

Sample:

1{
2        "role": "itential_restore_config",
3        "task": "itential_restore_config response",
4        "host": "junos_host",
5        "status": "SUCCESS",
6        "argument_warnings": null,
7        "results": {
8            "config_response": {
9                "failed": false,
10                "changed": true
11            },
12            "changed": false
13        }
14    }