Intential Automation Gateway
  • Dark
    Light
  • PDF

Intential Automation Gateway

  • Dark
    Light
  • PDF

Itential Automation Gateway Adapter

The Itential Automation Gateway (IAG) adapter is used to integrate IAG with IAP through the IAG API. Use the information in this guide to set property values and other parameters for adapter-automation_gateway.

Adapter Properties

Property Type Description
host String Required. The hostname of the Automation Gateway adapter.
port Number Required. The port on which to connect to the adapter. Default port is 443.
version String Required. Used to set the current API version the adapter integrates with. Default is v2.0.
authentication Object Required. Defines the properties used for authentication.
stub Boolean Optional.
protocol String Optional. Notifies the adapter whether to use HTTP or HTTPS. Default is http.
healthcheck Object Required. Defines the types of health check settings currently supported.
throttle Object Optional. Defines the properties used to throttle requests to Automation Gateway.
request Object Defines the properties used to handle requests and responses.
proxy Object Defines the properties used to handle requests and responses.
ssl Object Required. Defines the properties to utilize SSL authentication with Automation Gateway.

Authentication

Property Type Description
auth_method String Defines the authentication methods used for requests: basic user_password (default), static_token, request_token, no_authentication.
username String The username to authenticate with Automation Gateway on every request or when pulling a token that will be used in subsequent requests.
password String The password to authenticate with Automation Gateway on every request or when pulling a token that will be used in subsequent requests. If retrieved through an encrypt password call, use the exact return including the {code}.
token String Defines a static token that can be used on all requests.
token_user_field String The field in the token request where the username credential should be provided.
token_password_field String The field in the token request where the password credential should be provided.
token_result_field String Defines the field in the token response where the actual token will be.
token_URI_path String The API path used to retrieve a token.
token_timeout Number Defines how long a token is valid. Measured in milliseconds. Once a dynamic token is no longer valid, IAP has to pull a new token. Default is set to 0 (zero), which means IAP pulls a token on every request. Maximum value is 3600000.
invalid_token_error Number Defines the HTTP error that is received when a token is invalid. Notifies the adapter to pull a new token and retry the request. Default is 401.
auth_field String Defines the header field in which to place the token.
auth_field_format String Defines the format used to pass the authentication variables.

Healthcheck

The following settings are currently supported.

  • None - Not recommended. IAP will not run a check on Automation Gateway. Consequently, it is unable to determine if Itential can connect with Automation Gateway.
  • Startup - Itential will check for connectivity when the adapter initially comes up, but it will not check afterwards.
  • Intermittent - The adapter will check connectivity to Automation Gateway at the frequency defined in the frequency property
Property Type Description
type String The type of health check to run. Default is Intermittent.
frequency Number Defines how often the health check should run. Measured in milliseconds (minimum = 6000, maximum = 3600000). Default is 300000.
protocol String Defines the protocol (REST, SOAP, RPC, Socket, etc.) to use to check the health of the system. Default is REST.
uri_path String The path used to check the health of Automation Gateway. This call should be a simple request for information that does not require any parameters.

Throttle

Property Type Description
throttle_enabled Boolean Defines if the adapter should use throttling. Default is false.
number_pronghorns Number Defines if throttling is done in a single instance of IAP or whether requests are being throttled across multiple instances of IAP (minimum = 1, maximum = 20). Default is 1. Throttling a single instance uses an in-memory queue so there is less overhead. Throttling across multiple instances requires placing the request and queue information into a shared resource, e.g. a database, so that each instance can determine what is running and what is next to run. Throttling across multiple instances requires additional I/O overhead.
sync_async String Defines if the queue handle requests synchronously or asynchronously.
max_in_queue Number Represents the maximum number of requests Itential should allow into the queue before rejecting requests (minimum = 1, maximum = 5000). Default is 1000.
concurrent_max Number Defines the number of requests that Itential can send to Automation Gateway at one time (minimum = 1, maximum = 1000). Default is 1; each request must be sent to Automation Gateway in a serial manner.
expire_timeout Number Defines the graceful timeout of the request session. After a request has completed, Itential will wait additional time prior to sending the next request. Measured in milliseconds (minimum = 0, maximum = 60000). Default is 0.
avg_runtime Number Represents the approximate average of how long it takes Automation Gateway to handle each request. Measured in milliseconds (minimum = 50, maximum = 60000). Default is 200. This metric has performance implications. If the number is set too low, it puts extra burden on IAP CPU and memory as the requests will continually try to run. If the number is set too high, requests may wait longer than they need to before running. The number does not need to be exact but your throttling strategy depends heavily on this number being within reason. If averages range from 50 to 250 milliseconds you might pick an average run-time somewhere in the middle so that when your Automation Gateway performance is exceptional you might run a little slower than you might like, but when it is poor you still run efficiently.

Request

Property Type Description
number_retires Number Required. Defines how many times to retry a request that has aborted or reached the limit before returning an error (minimum = 0, maximum = 20). Default is 3.
limit_retry_error Number Optional. Indicates the HTTP error status code. Defines when no capacity is available and after waiting a short interval the adapter can retry the request (minimum = 0, maximum = 1000). Default is set to 0 (zero).
attempt_timeout Number Optional. Defines how long IAP should wait before aborting an attempt to connect. Measured in milliseconds (minimum = 1000, maximum = 300000). Default is 5000.
healthcheck_on_timeout Boolean Defines if the system should run a health check on timeout. Default is false. If set to true, the adapter will abort the request and run a health check until it re-establishes connectivity to Automation Gateway and then it will re-attempt the request.
archiving Boolean Optional. Default is false. Archives each request and response, and corresponding metrics (i.e., wait time, connection time, Automation Gateway time) in the adapterid_results collection in MongoDB. Before enabling this property, develop an archiving strategy for cleaning up the collection in the database so that it does not become too large, especially if the responses are large.

Proxy

Property Type Description
enabled Boolean Defines whether or not there is a proxy. Default is false.
host String The host name of the proxy. Default is localhost.
port Number The port used to connect to the proxy. Default is 443.
protocol String The protocol (i.e., http, https, socks4, socks5, etc.) used to connect to the proxy. Default is http.

SSL

Property Type Description
enabled Boolean Defines whether or not SSL is enabled. Default is false. If SSL required, set to true.
accept_invalid_cert Boolean Defines whether the adapter should accept invalid certificates. Default is false.
ca_file String Defines the path name to the CA file used for SSL.
ciphers String Specifies a list of SSL ciphers to use.

Sample Configuration

The following JSON shows a sample configuration for adapter-automation_gateway.

{
  "name": "Centos8IAGCustomerName",
  "model": "@itential/adapter-automation_gateway",
  "type": "Adapter",
  "properties": {
    "id": "Centos8IAGCustomerName",
    "type": "AutomationGateway",
    "brokers": [
      "device",
      "method"
    ],
    "groups": [],
    "properties": {
      "host": "centos8-iag-customername",
      "port": 8083,
      "base_path": "",
      "version": "v2.0",
      "cache_location": "none",
      "stub": false,
      "protocol": "http",
      "authentication": {
        "auth_method": "request_token",
        "username": "admin@itential",
        "password": "admin",
        "token": "token",
        "token_user_field": "username",
        "token_password_field": "password",
        "token_result_field": "token",
        "token_URI_path": "/api/v2.0/login",
        "token_timeout": 6000,
        "invalid_token_error": 401,
        "auth_field": "header.headers.Authorization",
        "auth_field_format": "{token}",
        "token_cache": "local"
      },
      "healthcheck": {
        "type": "intermittent",
        "frequency": 300000,
        "protocol": "REST",
        "URI_Path": ""
      },
      "throttle": {
        "throttle_enabled": false,
        "number_pronghorns": 1,
        "sync_async": "sync",
        "max_in_queue": 1000,
        "concurrent_max": 1,
        "expire_timeout": 0,
        "avg_runtime": 200
      },
      "request": {
        "number_redirects": 0,
        "number_retries": 3,
        "limit_retry_error": 0,
        "failover_codes": [],
        "attempt_timeout": 5000,
        "global_request": {
          "payload": {},
          "uriOptions": {},
          "addlHeaders": {},
          "authData": {}
        },
        "healthcheck_on_timeout": false,
        "return_raw": false,
        "archiving": false
      },
      "proxy": {
        "enabled": false,
        "host": "",
        "port": 443,
        "protocol": "http"
      },
      "ssl": {
        "ecdhCurve": "",
        "enabled": false,
        "accept_invalid_cert": false,
        "ca_file": "",
        "key_file": "",
        "cert_file": "",
        "secure_protocol": "",
        "ciphers": ""
      },
      "visibility": {
        "module": "all",
        "role": "all",
        "playbook": "certified",
        "script": "all",
        "terraform": "all",
        "collection_module": "all",
        "collection_role": "all",
        "nornir": "all",
        "netconf": "all",
        "netmiko": "all"
      },
      "cluster_name": "",
      "save_metric": false,
      "mongo": {
        "host": "",
        "port": 443,
        "database": "",
        "username": "",
        "password": "",
        "replSet": ""
      }
    }
  },
  "isEncrypted": true,
  "loggerProps": {
    "description": "Logging",
    "log_max_files": 100,
    "log_max_file_size": 1048576,
    "log_level": "warn",
    "log_directory": "/var/log/pronghorn",
    "log_filename": "pronghorn.log",
    "console_level": "warn"
  },
  "virtual": false
}

What's Next