Role Examples
  • Dark
    Light
  • PDF

Role Examples

  • Dark
    Light
  • PDF

Referenced below are several Automation Gateway roles, including examples of request and response objects.

itential_cli

Description: Execute CLI commands on a network device. This role also provides support for handling commands that are required to respond to a prompt in order to complete the command.


Note: 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.


Sample Request Object

{
  "hosts": [
    "ios_aws"
  ],
  "args": {"command": ["show clock"]}
}

Sample Response Object

[
    {
        "role": "itential_cli",
        "task": "itential_cli response",
        "host": "ios_host",
        "status": "SUCCESS",
        "argument_warnings": null,
        "results": {
            "stdout_lines": [
                [
                    "*08:45:04.200 UTC Fri Nov 8 2019"
                ]
            ],
            "stdout": [
                "*08:45:04.200 UTC Fri Nov 8 2019"
            ],
            "changed": false
        }
    }
]

Sample Request Object for Command Prompts

{
  "hosts": [
    "ios_aws"
  ],
  "args":{"command": [{"command": "clear counters GigabitEthernet2", "prompt": ["confirm"], "answer": ["y"]}]}
}

Sample Response Object for Command Prompts

[
    {
        "role": "itential_cli",
        "task": "itential_cli response",
        "host": "ios_aws",
        "status": "SUCCESS",
        "argument_warnings": null,
        "results": {
            "stdout_lines": [
                [
                    "Clear \"show interface\" counters on this interface [confirm]y"
                ]
            ],
            "stdout": [
                "Clear \"show interface\" counters on this interface [confirm]y"
            ],
            "changed": false
        }
    }
]

itential_get_info

Description: Retrieve information about a device including OS type, serial number, and the MAC address for all network interfaces.

Sample Request Object

{
  "hosts": [
    "ios_aws"
  ],
  "args": {}
}

Sample Response Object

{
        "role": "itential_get_info",
        "task": "itential_get_info response",
        "host": "ios_aws",
        "status": "SUCCESS",
        "argument_warnings": null,
        "results": {
            "serial_number": "9IKZMWL4K0X",
            "raw_ansible_facts": {
                "ansible_net_serialnum": "9IKZMWL4K0X",
                "ansible_net_all_ipv4_addresses": [
                    "10.11.0.72"
                ],
                "ansible_net_model": "CSR1000V",
                "ansible_net_hostname": "ph10894c",
                "ansible_net_gather_subset": [
                    "hardware",
                    "default",
                    "interfaces"
                ],
                "ansible_net_interfaces": {
                    "GigabitEthernet1.1": {
                        "macaddress": "0e4e.fc45.d044",
                        "lineprotocol": "down ",
                        "description": null,
                        "duplex": null,
                        "mediatype": null,
                        "mtu": 1500,
                        "operstatus": "deleted",
                        "bandwidth": 1000000,
                        "ipv4": [],
                        "type": "CSR vNIC"
                    },
                    "GigabitEthernet1": {
                        "macaddress": "0e4e.fc45.d044",
                        "lineprotocol": "up ",
                        "description": null,
                        "duplex": "Full",
                        "mediatype": "RJ45",
                        "mtu": 1500,
                        "operstatus": "up",
                        "bandwidth": 1000000,
                        "ipv4": [
                            {
                                "subnet": "24",
                                "address": "10.11.0.72"
                            }
                        ],
                        "type": "CSR vNIC"
                    }
                },
                "ansible_net_version": "03.16.02.S",
                "ansible_net_all_ipv6_addresses": [],
                "ansible_net_memtotal_mb": 1672835,
                "ansible_net_filesystems": [
                    "bootflash:"
                ],
                "ansible_net_image": "bootflash:packages.conf",
                "ansible_net_memfree_mb": 1442035
            },
            "interfaces": {
                "GigabitEthernet1.1": {
                    "macaddress": "0e4e.fc45.d044",
                    "lineprotocol": "down ",
                    "description": null,
                    "duplex": null,
                    "mediatype": null,
                    "mtu": 1500,
                    "operstatus": "deleted",
                    "bandwidth": 1000000,
                    "ipv4": [],
                    "type": "CSR vNIC"
                },
                "GigabitEthernet1": {
                    "macaddress": "0e4e.fc45.d044",
                    "lineprotocol": "up ",
                    "description": null,
                    "duplex": "Full",
                    "mediatype": "RJ45",
                    "mtu": 1500,
                    "operstatus": "up",
                    "bandwidth": 1000000,
                    "ipv4": [
                        {
                            "subnet": "24",
                            "address": "10.11.0.72"
                        }
                    ],
                    "type": "CSR vNIC"
                }
            },
            "os_version": "03.16.02.S",
            "changed": false
        }
    }

itential_get_health

Description: Retrieve CPU and memory statistics for a device. The itential_get_health response task returns a memory usage statistics object and an array of CPU usage objects.

The memory object contains the total memory and free memory values in megabytes. Each object in the cpu_stats array reflects a sample period during which the 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.

Key Description
value CPU utilization (percentage) or load average.
type Utilization or loading.
period Sample space (in seconds) in which the value was calculated.

Sample Request Object

{
  "hosts": [
    "ios_aws"
  ],
  "args": {}
}

Sample Response Object

[
   {
        "role": "itential_get_health",
        "task": "itential_get_health response",
        "host": "ios_aws",
        "status": "SUCCESS",
        "argument_warnings": null,
        "results": {
           "memory": {
                "memtotal_mb": 814,
                "memfree_mb": 556
           },
           "cpu_stats": [
                { "value": 15, "type": "utilization", "period": 5 },
        { "value": 20, "type": "utilization", "period": 60 },
        { "value": 32, "type": "utilization", "period": 300 }
           ],
           "changed": false
        }
   },
   {
        "role": "itential_get_health",
        "task": "itential_get_health response",
        "host": "eos_host",
        "status": "SUCCESS",
        "argument_warnings": null,
        "results": {
           "memory": {
                "memtotal_mb": 1970,
                "memfree_mb": 1120
           },
           "cpu_stats": [
                { "value": 0.8, "type": "loadavg", "period": 60 },
        { "value": 0.2, "type": "loadavg", "period": 300 },
        { "value": 0.2, "type": "loadavg", "period": 900 }
           ],
           "changed": false
        }
   },
]

itential_get_config

Description: Retrieve the current running configuration from a device. The results returned in the config_data field can be directly passed as a value to the config_file parameter of the itential_restore_config role.

Sample Request Object

{
  "hosts": [
    "ios_host"
  ],
  "args": {}
}

Sample Response Object

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

itential_set_config

Description: Add, modify, and delete specific configuration sections and lines on a device. The itential_set_config role takes an array of transactions as an argument.

Each transaction is an object representing a single configuration line that will be applied to the device configuration in the order they appear in the array.

Each transaction will be treated individually and produce its own status and results. A failure on one transaction will not stop the next transaction from being attempted.

A transaction object consists of the following fields.

Field Description
action Configuration action to perform on a device. Possible values are add, modify, and delete.
parents The 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_line The configuration line being acted upon by the device. The line must match the native device configuration syntax.
id Optional. String parameter that can be used to match a transaction request with the corresponding device configuration response. The id string will be return as a key in the config_response results object of the role.

Sample Request Object

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

Sample Response Object

{
        "role": "itential_set_config",
        "task": "itential_set_config response",
        "host": "eos_host",
        "status": "SUCCESS",
        "argument_warnings": null,
        "results": {
            "config_request": {
                "action": "add",
                "config_line": "ip address 10.0.5.17/24",
                "parents": [
                    "interface Management 1"
                ],
                "id": "first"
            },
            "config_response": {
                "failed": false,
                "id": "first"
            },
            "changed": false
        }
    },
    {
        "role": "itential_set_config",
        "task": "itential_set_config response",
        "host": "eos_host",
        "status": "SUCCESS",
        "argument_warnings": null,
        "results": {
            "config_request": {
                "action": "modify",
                "config_line": "ip address 10.0.5.27/24",
                "parents": [
                    "interface Management 1"
                ],
                "id": "second"
            },
            "config_response": {
                "failed": false,
                "id": "second"
            },
            "changed": false
        }
    },
    {
        "role": "itential_set_config",
        "task": "itential_set_config response",
        "host": "eos_host",
        "status": "FAILURE",
        "argument_warnings": null,
        "results": {
            "msg": "Configuration request failed",
            "config_request": {
                "action": "delete",
                "config_line": "ip address 10.0.5.27/24",
                "parents": [
                    ""
                ],
                "id": "third"
            },
            "config_response": {
                "msg": "Error on executing commands ['', 'no ip address 10.0.5.27/24']",
                "failed": true,
                "data": "no ip address 10.0.5.27/24\r\n% Invalid input\r\nlocalhost(config-s-ansibl)#",
                "id": "third"
            },
            "changed": false
        }
    }
]

itential_restore_config

Description: Replace the current running configuration of a device with a completely new version.

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 file in its native format in the key config_data.

The results from that role can be a starting point for configuration modifications or be used "as is" for the argument value in the config_file.

SCP Requirements for IOS (Cisco) and EOS (Arista) Device Types

To execute the restore operation, Cisco IOS and Arista EOS devices require the new configuration file to be present on the system. The itential_restore_config role accomplishes this by using the Ansible scp module to transfer the new configuration file to the device. Below are instructions for SCP and SSH key configuration requirements when using the itential_restore_config role on IOS and EOS devices.

  1. SCP must be enabled using the the following configuration mode command (IOS): # ip scp server enable

  2. For the user account in the device inventory variable ansible_user, SSH keys must be set-up between Automation Gateway and the IOS/EOS device so that a password in not required for device login. Otherwise, the SCP module will timeout and the role will fail.

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

Sample Request Object

{"hosts":["junos_host"],
 "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
        encrypted-password \"$1$Fmd79e7l$0biZFh9lhSt1qb/E06HoL.\";\n    }\n    services {\n        ftp;\n        ssh;\n        netconf {\n            ssh;\n        }\n
    }\n    syslog {\n        user * {\n            any emergency;\n        }\n        file messages {\n            any notice;\n            authorization info;\n
       }\n        file interactive-commands {\n            interactive-commands any;\n        }\n    }\n}\ninterfaces {\n    em0 {\n        unit 0 {\n            family
 inet {\n                address 192.168.32.30/24;\n            }\n        }\n    }\n}\nsnmp {\n    community itential;\n    community redhat;\n}"
       },
 "strict_args": true
 }

Sample Response Object

{
        "role": "itential_restore_config",
        "task": "itential_restore_config response",
        "host": "junos_host",
        "status": "SUCCESS",
        "argument_warnings": null,
        "results": {
            "config_response": {
                "failed": false,
                "changed": true
            },
            "changed": false
        }
    }

What's Next
Changing your password will log you out immediately. Use the new password to log back in.
First name must have atleast 2 characters. Numbers and special characters are not allowed.
Last name must have atleast 1 characters. Numbers and special characters are not allowed.
Enter a valid email
Enter a valid password
Your profile has been successfully updated.