@itentialopensource/iag-device-onboarding v1.0.6-2023.1.0

IAG Device Onboarding

Table of Contents

• IAG Device Onboarding
  • Table of Contents
  • Overview
  • Supported IAP Versions
  • Getting Started
    • Prerequisites
    • Capabilities
    • How to Install
    • Testing
  • Using this Pre-Built
    • Input Schema
    • Output Schema
  • Additional Information

Overview

The IAG Device Onboarding pre-built provides the ability to onboard a list of devices onto an IAG instance through the IAG adapter.

Estimated Run Time: < 1 minute for single device

Supported IAP Versions

Itential pre-builts are built and tested on particular versions of IAP. In addition, pre-builts that work with devices are often dependent on certain orchestration systems (e.g. NSO and IAG). As such, these pre-builts will have dependencies on these other systems. This version of the IAG Device Onboarding pre-built has been tested with:

• IAP 2023.1.x

Getting Started

These instructions will help you get a copy of the pre-built in your local machine for testing in your environment. Reading this section is also helpful for deployments as it provides you with pertinent information on prerequisites and capabilities.

Prerequisites

Users must satisfy the following prerequisites to install and run this pre-built:

• Itential Automation Platform
  • ^2023.1.x
• Itential Automation Gateway
  • ^3.227.0+2023.1.15
• An instantiated IAP IAG adapter

Capabilities

• Ability to onboard a list of devices.
• Ability to onboard a list of device types (Currently only supports HTTP Request and Ansible device types).
• Ability to onboard a single device through operations manager.

How to Install

To install this pre-built:

• Verify that you are running the documented prerequisites in order to install the pre-built.

• Follow the instructions on the Itential Documentation site for importing a pre-built.

Testing

While Itential tests this pre-built and its capabilities, it is often the case the customer environments offer their own unique circumstances. Therefore, it is our recommendation that you deploy this pre-built into a development/testing environment in which you can test the pre-built.

Using this Pre-Built

This pre-built can be run as a standalone automation or in a childJob task.

Note: The entry point workflow to this pre-built is called IAGDO: Onboard Devices. Use this worklow name if running the pre-built in a childJob task.

Running this pre-built depends on providing correct input so that the onboarding operations against the intended devices run as expected. The input to and possible outputs from this pre-built are described here.

Note: This pre-built can also be ran as an automation through Operations Manager. The Operations Manager automation to run this pre-built is called IAGDO: Onboard With Form. When onboarding an HTTP device through this form a user must pass properties for params, data, headers, cookies, auth, timeout, and proxies as JSON object to correctly pass these additional fields.

Input Schema

Ansible Device Onboarding:

{
    "device": [
        {
            "deviceName": "Ansible_Test_Device",
            "inventoryType": "ansible",
            "iagAdapterInstance": "IAG-2021.2",
            "onboarding": {
                "ipaddress": "1.1.1.1",
                "port": "22",
                "user": "user",
                "password": "password",
                "device-type": "network_cli",
                "ostype": "ios",
                "become": "true",
                "become_method": "enable",
                "become_user": "user",
                "become_pass": "password"
            }
        }
    ],
    "options": {
        "verbose": false
    }
}

The following table details the property keys for an Ansible Device.

The following table details the IAP vs Ansible Inventory type mapping. For additional documentation related to Ansible inventory, please see the official Ansible Inventory Guide, and for additional documentation for IAP Ansible createDevice mapping, please see the offcial createDevice documentation.

HTTP Request Device Onboarding:

{
    "device": [
        {
            "deviceName": "Http_Test_Device",
            "inventoryType": "http_requests",
            "iagAdapterInstance": "IAG-2021.2",
            "onboarding": {
                "base_url": "1.1.1.1:1/mgmt",
                "protocol": "https",
                "endpoint": "/tm/ltm/pool",
                "method": "",
                "params": {},
                "data": {},
                "headers": {},
                "cookies": {},
                "auth": {
                    "username": "user",
                    "password": "password"
                },
                "timeout": {},
                "allowRedirects": true,
                "proxies": {},
                "verify": false
            }
        }
    ],
    "options": {
        "verbose": false
    }
}

The following table details the property keys for a HTTPRequests Device.

Output Schema

The ReturnStatus job variable returned from the run pre-built reports the success or failure of the onboarding process for the list of devices provided to the pre-built. Below are example outputs of scenarios were a device does not exist on the IAG instance, a device does exist on an IAG instance, an invalid inventory type, and a failure with the Get Device Details child job.

Device Does Not Already Exist on IAG:

{
  "ReturnStatus": {
    "details": [
      {
        "response": {
          "get_device": {
            "icode": "AD.500",
            "IAPerror": {
              "origin": "IAG-2021.2-connectorRest-handleEndResponse",
              "displayString": "Error 404 received on request",
              "recommendation": "Verify the request is accurate via debug logs and postman",
              "code": 404,
              "raw_response": {
                "status": "success",
                "code": 404,
                "headers": {
                  "server": "gunicorn/20.0.4",
                  "date": "Thu, 22 Dec 2022 15:29:28 GMT",
                  "connection": "close",
                  "content-type": "application/json;",
                  "content-length": "52",
                  "last-modified": "2022-12-22 10:29:28.511166",
                  "cache-control": "no-store, no-cache, must-revalidate, post-check=0, pre-check=0, max-age=0",
                  "pragma": "no-cache",
                  "expires": "-1",
                  "x-frame-options": "DENY",
                  "x-xss-protection": "1",
                  "x-content-type-options": "nosniff"
                },
                "response": "{\"code\": 404, \"status\": 404, \"message\": \"Not Found\"}",
                "redirects": 0,
                "tripTime": "38ms",
                "reqHdr": {
                  "Content-Type": "application/json",
                  "Accept": "application/json"
                }
              }
            },
            "metrics": {
              "code": 404,
              "timeouts": 0,
              "redirects": 0,
              "retries": 0,
              "tripTime": 38,
              "isThrottling": false,
              "capabilityTime": "172ms"
            },
            "response": {
              "code": 404,
              "status": 404,
              "message": "Not Found"
            }
          },
          "addDevice": {
            "name": "Ansible_Test_Device",
            "device-type": "network_cli",
            "ipaddress": "172.20.102.131",
            "port": "22",
            "ostype": "cisco-nx",
            "become": "true",
            "become_method": "enable",
          }
        },
        "device": "Ansible_Test_Device",
        "message": "Successfully onboarded device to IAG",
        "status": "SUCCESS",
        "errors": []
      }
    ],
    "errors": [],
    "number_failure": 0,
    "number_successfully_onboarded_devices": 1,
    "number_already_onboarded_devices": 0,
    "status": "SUCCESS",
    "number_success": 1,
    "message": "0 devices found already onboarded to IAG, 1 devices successfully onboarded to IAG, 0 devices failed to onboard to IAG"
  }
}

Device Already Found on IAG:

{
  "ReturnStatus": {
    "details": [
      {
        "response": {
          "get_device": {
            "name": "Ansible_Test_Device",
            "inventory_type": "ansible",
            "device-type": "network_cli",
            "ipaddress": "1.1.1.1",
            "port": "22",
            "ostype": "cisco-nx",
            "become": "true",
            "become_method": "enable"
          }
        },
        "device": "Ansible_Test_Device",
        "inventory_type": "ansible",
        "message": "Device already exists on IAG",
        "status": "SUCCESS",
        "errors": []
      }
    ],
    "errors": [],
    "number_failure": 0,
    "number_successfully_onboarded_devices": 0,
    "number_already_onboarded_devices": 1,
    "status": "SUCCESS",
    "number_success": 1,
    "message": "1 devices found already onboarded to IAG, 0 devices successfully onboarded to IAG, 0 devices failed to onboard to IAG"
  }
}

Given Invalid Inventory Type:

{
  "ReturnStatus": {
    "details": [
      {
        "response": {
          "get_device": "Invalid inventory type"
        },
        "device": "Ansible_Test_Device",
        "inventory_type": "anible",
        "message": "Invalid inventory type",
        "status": "FAILED",
        "errors": [
          {
            "message": "Invalid inventory type",
            "error_details": {}
          }
        ]
      }
    ],
    "errors": [],
    "number_failure": 1,
    "number_successfully_onboarded_devices": 0,
    "number_already_onboarded_devices": 0,
    "status": "FAILED",
    "number_success": 0,
    "message": "0 devices found already onboarded to IAG, 0 devices successfully onboarded to IAG, 1 devices failed to onboard to IAG"
  }
}

Get Device Details Error or Any Other Adapter Error:

{
  "ReturnStatus": {
    "details": [
      {
        "response": {
          "get_device": "Cannot forward message to corral:IAG-2021.2"
        },
        "device": "Ansible_Test_Device",
        "inventory_type": "ansible",
        "message": "Cannot forward message to corral:IAG-2021.2",
        "status": "FAILED",
        "errors": [
          {
            "message": "Cannot forward message to corral:IAG-2021.2",
            "error_details": {}
          }
        ]
      }
    ],
    "errors": [],
    "number_failure": 1,
    "number_successfully_onboarded_devices": 0,
    "number_already_onboarded_devices": 0,
    "status": "FAILED",
    "number_success": 0,
    "message": "0 devices found already onboarded to IAG, 0 devices successfully onboarded to IAG, 1 devices failed to onboard to IAG"
  }
}

The following table details the property keys of the ReturnStatus output object:

Additional Information

Please use your Itential Customer Success account if you need support when using this pre-built.