Itential Automation Gateway

Updated on 01 Apr 2024

Dark

Light
PDF

Article Summary

Share feedback

Thanks for sharing your feedback!

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.
`strip_escapes`	Boolean	Optional. Strips out additional backslashes from all API calls. The default setting is off, `false`. To enable, change to `true`. The default setting is recommended unless an issue arises where extra escape characters (i.e., backslashes) are added to API calls that should be removed.

Authentication

Property	Type	Description
`auth_method`	String	Defines the authentication method used in requests. Valid authentication methods include `request_token` (default), `static_token`, and `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 -1 (minus one), 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 = 360000). 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 is 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",
        "grpc": "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
}

Note:

The "playbook": "certified" in the example JSON above references the manual validation of Ansible playbooks by Itential. This was due to insufficient or inaccurate documentation of community produced playbooks or collections. Beginning with IAG 2023.1, Itential has stopped this practice as the content quality for community-produced modules and collections has reached sufficient levels that Itential’s practice of certification is no longer required.

Was this article helpful?

What's Next

Table of contents

Automation Gateway Adapter
Sample Configuration