npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

@itentialopensource/iag-device-onboarding

v1.0.6-2023.1.0

Published

Artifact to onboard a device onto IAG internal db

Downloads

9

Readme

IAG Device Onboarding

Table of Contents

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.

| key | type | required | description | |---------------------------------|---------|----------|----------------------------------------------------------| | device | array | yes | list of devices | | device.deviceName | string | yes | device name | | device.inventoryType | enum | yes | inventory type [anisble or http_requests] | | device.iagAdapterInstance | string | yes | IAG adapter devices instance to onboard on | | device.onboarding | object | yes | onboarding parameters | | device.onboarding.device-type | string | yes | NSO instance | | device.onboarding.ipaddress | string | yes | ip address | | device.onboarding.port | string | yes | port | | device.onboarding.ostype | string | no | allows user to manually view and confirm job details | | device.onboarding.user | string | no | user to become through privilege escalation | | device.onboarding.sshKey | string | no | Private key file used by ssh | | device.onboarding.password | string | no | password used to authenticate to host | | device.onboarding.become | string | no | allow to force privilege escalation ("true" or "false") | | device.onboarding.become | string | no | allows to force privilege escalation ("true" or "false") | | device.onboarding.become_method | string | no | allows to set privilege escalation method | | device.onboarding.become_pass | string | no | privilege escalation password | | options | object | yes | additional options | | options.verbose | boolean | yes | verbose | | options | object | yes | additional options | | options.verbose | boolean | yes | verbose |

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.

| IAP Variable | Anisble Variable | |-----------------|------------------------------| | device-type | ansible_connection | | ipaddress | ansible_user | | port | ansible_port | | ostype | ansible_network_os | | user | ansible_user | | sshKey | ansible_ssh_private_key_file | | password | ansible_password | | become | ansible_become | | become_method | ansible_become_method | | become_pass | ansible_become_pass |

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.

| key | type | required | description | |----------------------------------|---------|----------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | device | array | yes | list of devices | | device.deviceName | string | yes | device name | | device.inventoryType | string | yes | inventory type [anisble or http_requests] | | device.iagAdapterInstance | string | yes | IAG adapter devices instance to onboard on | | device.onboarding | object | yes | onboarding parameters | | device.onboarding.base_url | string | yes | The name of a base url to execute against | | device.onboarding.protocol | string | yes | The name of the protocol used to communicate | | device.onboarding.endpoint | string | no | The endpoint to append to the url built from your inventory/host | | device.onboarding.method | enum | no | Request method - one of GET, OPTIONS, HEAD, POST, PUT, PATCH, DELETE | | device.onboarding.params | object | no | Keys/values to convert into the request's query string | | device.onboarding.data | object | no | Keys/values to send as the request's body | | device.onboarding.headers | object | no | Keys/values to send as the request's HTTP headers | | device.onboarding.cookies | object | no | Keys/values to send as the request's cookies | | device.onboarding.auth | object | no | Keys/values to send as the username and password for Basic Authentication | | device.onboarding.timeout | string | no | The connect and read timeouts for the request. See Request HTTP documentation for more detatils | | device.onboarding.allowRedirects | boolean | no | A flag which enables or disables HTTP redirection | | device.onboarding.proxies | object | no | The keys/values which describe proxies to use for the request | | device.onboarding.verify | boolean | no | A flag which enables or disables TLS certificate verification | | options | object | yes | additional options | | options.verbose | boolean | yes | verbose |

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:

| key | type | description | |----------------------------------------------------|---------|---------------------------------------------------------------------| | ReturnStatus.status | enum | status of onboarding list of devices [SUCCESS, FAILED] | | ReturnStatus.errors | array | list of errors encountered returned from running pre-built | | ReturnStatus.number_failure | integer | number of devices that failed to onboard | | ReturnStatus.number_successfully_onboarded_devices | integer | number of successfully onboarded devices | | ReturnStatus.number_already_onboarded_devices | integer | number of already onboarded devices | | ReturnStatus.number_success | integer | number devices found already on IAG or successfully onboarded to IAG | | ReturnStatus.message | string | description of onboarding list of devices result | | ReturnStatus.details[x].response.get_device | object | IAGGDD: Get Device Details Details childJob response | | ReturnStatus.details[x].response.add_Device | object | IAGDO: Onboard Device childJob response | | ReturnStatus.details[x].device | string | device name | | ReturnStatus.details[x].message | string | description of single device result | | ReturnStatus.details[x].status | string | status of single device result [SUCCESS, FAILED] | | ReturnStatus.details[x].errors | array | list of errors encountered onboaring single device |

Additional Information

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