Roles

Itential Automation Gateway allows users to automate the administration of their network by providing a collection of Ansible roles that perform device monitoring and configuration tasks on supported device types. The roles are designed to utilize advanced features of the command and configuration networking modules that are developed, tested, and maintained by the Ansible open-source community. Devices are managed by running CLI and NETCONF commands over the SSH protocol. The parameters required for device connectivity are made available through the Automation Gateway inventory management subsystem.

The following roles are distributed with the 2019.3 Automation Gateway release.

Background

Roles are a way to automatically load certain Ansible variable files, tasks, and handlers through a known file structure for execution within an Ansible playbook.

Grouping content by roles allows easy sharing of functionality by other Ansible playbooks.

Automation Gateway clients execute roles on a device using the REST /roles/{role_name}/execute route.

The role execution input parameter is a JSON object that contains an array of host strings and an args object that includes a set of key/value pairs that are specific to the role itself.

A JSON schema that describes each role's argument parameters is available via the /roles/{role_name} route.

Detailed documentation on role endpoints can be found in the API Documentation section of the Automation Gateway UI.

Below is a sample role input parameter for the itential_set_config role.

Sample Role Request Object

{
  "hosts":["eos_host"],
  "args":
  {  
    "transactions": [{"action": "add",
                      "parents": ["interface Management 1"],
                      "config_line": "ip address 10.0.5.17/24",
                      "id": "anyIDString"}]
  },
  "strict_args": true
}

An Ansible role consists of a number of tasks, each of which produces its own results object.

Automation Gateway collects the task results objects and returns them as an array in the order in which they were executed.

Task Key Naming Convention

The Itential Ansible roles include a task results object with a task key whose value always takes the form of the "Task key naming convention" shown below:

{role} response

Where {role} is replaced with the name of the role executed.

Example: itential_set_config response

The results object from that response task contains the response data from the role for the device.

All other task results can be ignored and are available for informational and debugging purposes only.

Note that the format of the data contained within the results object will vary per role.

In addition, a status key indicates whether the task succeeded, SUCCESS, or failed, FAILURE.

Roles that contain multiple requests will have multiple response objects, each with their own status and results keys.

Sample Role Response

[
    {
        "role": "itential_set_config",
        "task": "execute config module on eos platform",
        "host": "eos_host",
        "status": "SUCCESS",
        "argument_warnings": null,
        "results": {
            "commands": [
                "interface Management 1",
                "ip address 10.0.5.17/24"
            ],
            "changed": true,
            "session": "ansible_1548718829",
            "updates": [
                "interface Management 1",
                "ip address 10.0.5.17/24"
            ],
            "diff": {
                "prepared": "--- system:/running-config\n+++ session:/ansible_1548718829-session-config\n@@ -27,6 +27,7 @@\n
    ip address 192.168.32.20/24\n !\n interface Management1\n+   ip address 10.0.5.17/24\n !\n ip route 0.0.0.0/0 10.0.2.2\n !"
            }
        }
    },
    {
        "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": "anyIDString"
            },
            "config_response": {
                "failed": false,
                "changed": true,
                "id": "anyIDString"
            },
            "changed": false
        }
    }
]