Itential Docs & Guides | Drive Automation for Modern Networks

This guide provides information pertaining to configuration for Itential Automation Gateway.

Choose Inventory Mode

Before configuring Itential Automation Gateway, determine which inventory mode you require. For existing Ansible users, specify your inventory file in the inventory_file property to maintain all existing device variables and groups as used within your current Ansible® environment. Automation Gateway (AG) considers this mode external inventory. Conversely, internal inventory (i.e. an empty inventory_file property) allows manipulation of inventory information and management of your inventory (including management of inventory variables) via Automation Gateway.

One important factor to determine which mode to run Automation Gateway in depends on the desired mechanism for managing inventory:

Internal - Management via Automation Gateway API.
External - Management via file manipulation as with any Ansible installation.

Consider each approach, the inventory mode you desire, and choose accordingly.

Setup Script

Automation Gateway includes a set-up script named automation-gateway-setup.sh that is located at /usr/bin/automation-gateway-setup.sh.

The script must be run with sudo. It takes the following arguments:

Argument	Description
`--setup`	This signifies to setup Automation Gateway. Mutually exclusive with clean.
`--clean`	This signifies to clean Automation Gateway. Mutually exclusive with setup.
`--install-dir=*`	This optional argument is used to create the install location of Automation Gateway. Replace the '`*`' with the desired install directory. The path can be absolute or relative. Used with setup and clean.
`--role-dir=*`	This optional argument is used to create the role location for Automation Gateway. Replace the '`*`' with the desired role directory. The path can be absolute or relative. Used with setup.
`--playbook-dir=*`	This optional argument is used to create the playbook location for Automation Gateway. Replace the '`*`' with the desired playbook directory. The path can be absolute or relative. Used with setup.
`--user=*`	This optional argument is used to create the owner of the Automation Gateway process. Replace the '`*`' with the custom user. Used with setup.
`--systemd`	This optional argument, if passed in, signifies for the Automation Gateway process to be run as a 'Systemd' service. Used with setup.
`--start-on-boot`	This optional argument, if passed in, signifies that Automation Gateway will automatically start on system boot up. Systemd argument also must be passed in for this argument to work. Used with setup.
`--force`	This argument signifies to override confirmation statements during the `--clean` argument. Used with clean.

If any arguments are not passed in, the user will be prompted to input them or use defaults.

An example call for setup:

sudo ./automation-gateway-setup.sh --setup --user=itential --install-dir=/opt/automation-gateway --role-dir=/usr/share/ansible/roles --playbook-dir=/user/share/ansible/playbooks --systemd --start-on-boot

After setup, modify the properties file that is generated with any additional changes needed for your environment.

An example call for clean:

sudo ./automation-gateway-setup.sh --clean --install-dir=/opt/automation-gateway --force

Property Settings

Configuration parameters for Itential Automation Gateway are stored in a YAML file located at the install directory specific to the startup script.

Property	Sample Value	Description
`ansible_enabled`	`true`	A true/false value that enables Ansible support on the AG server.
`scripts_enabled`	`true`	A true/false value that enables Scripts support on the AG server.
`terraform_enabled`	`false`	A true/false value that enables Terraform support on the AG server.
`netmiko_enabled`	`false`	A true/false value that enables Netmiko support on the AG server.
`nornir_enabled`	`false`	A true/false value that enables Nornir support on the AG server.
`vault_password_file`	`/opt/ansible/.vault_password_file`	The path to a file containing the vault password. The file should be secured with 0400 permissions. This property is only required if vault passwords are being used.
`inventory_file`	`~/.ansible/hosts`	The path to an existing Ansible inventory file or script. If there is no existing Ansible inventory, you may omit this property and add devices directly to the Automation Gateway database.
`module_path`	`/usr/local/lib/python3.6/site-packages/ansible/modules/network`	The path to Ansible network modules that will be discovered by Itential Automation Gateway. It can be set to either a single path or a list of paths. A list of module paths has the format `['/path1', /path2', '/path3']`.
`role_path`	`/usr/share/ansible/roles`	The path to Ansible roles that will be discovered by Itential Automation Gateway. It can be set to either a single path or a list of paths. A list of role paths has the format `['/path1', /path2', '/path3']`.
`playbook_path`	`/usr/share/ansible/playbooks`	The path to Ansible playbooks that will be discovered by Itential Automation Gateway. It can be set to either a single path or a list of paths. A list of playbook paths has the format `['/path1', '/path2', '/path3']`.
`script_path`	`/usr/share/scripts`	The path to a set of scripts to invoke from Automation Gateway. It can be set to either a single path or a list of paths. A list of script paths has the format `['/path1', '/path2', '/path3']`.
`terraform_path`	`/usr/share/terraform/scripts`	The path to a set of Terraform modules/scripts to invoke from Automation Gateway. It can be set to either a single path or a list of paths. A list of script paths has the format `['/path1', '/path2', '/path3']`.
`authentication_disabled`	`false`	Set this property to `false` in shared network environments. You may choose to disable authentication if running in a virtual machine (VM) on your laptop.
`authentication_max_sessions`	`5`	How many concurrent sessions are allowed for each user.
`authentication_idle_timeout`	`600`	The duration of the user session when no activity occurs.
`data_file`	`sqlite:////opt/automation-gateway/data/automation-gateway.db`	URL to a SQLite database file. The file should be located on a persistent volume so it is not lost across server restarts. When referencing an absolute path, four slash marks `/` must be present in the URL.
`strict_args`	`true`	Whether or not schema validation should be performed when invoking Ansible modules. This value should be set to `true`.
`external_address`	`http://automation-gateway.example.com:8080`	For use with an external proxy and for generating redirects.
`ansible_debug`	`true`	Set this property to `true` to log additional debug messages when executing Ansible modules, roles, or playbooks.
`no_cleanup`	`true`	Set this property to `true` to maintain temporary files created during the execution of Ansible modules, roles, or playbooks.
`logging_level`	`INFO`	The logging level of the Automation Gateway Server. The associated logging levels (in order of ascending severity) are DEBUG, INFO, WARNING, ERROR, or CRITICAL. JSON formatted log messages are sent to the console.

Configuring Optional Subsystems

Starting in Release 2020.2, all subsystems supported by Automation Gateway (i.e., Ansible, Scripts, Terraform) are optional and enabled/disabled by setting the configuration parameters found in properties.yml. See the Property Settings section for more information.

Note: To help ease the transition for existing Automation Gateway users, Ansible and Scripts are enabled by default and do not require any additional configuration. A future release of Automation Gateway will require that all subsystems be configured so it is suggested that the parameters for those subsystems be set right away if currently being utilized.

Additional Requirements for Settings

Configure the vault_password_file and inventory_file properties if an existing Ansible inventory will be used.
Configure the role_path and playbook_path properties to point to your custom Ansible roles and playbooks.
Configure the data_file to be located on your persistent volume.

Sample Properties File

An example properties.yml file is shown below.

---

#
# Port on which the Automation Gateway server will listen for requests.
#
port: 8083

#
# Address to bind to.
# For ipv4 only use "0.0.0.0"
# For ipv6 and ipv4 use "[::]"
#
# bind_address: [::]

#
# List of addresses and ports to bind to.
# This setting will override both 'port' and 'bind_address'
#
# bind_list: ['0.0.0.0:8083', '[::]:8083']

#
# Path to the Automation Gateway sqlite database file.
# Be sure to place this file on a persistent volume.
#
data_file: 'sqlite:////opt/automation-gateway/data/automation-gateway.db'

#
# A true/false value that enables Ansible support on the AG server.
#
# Ansible support will be ENABLED if this parameter is absent or misconfigured.
#
#ansible_enabled: true

#
# A true/false value that enables Scripts support on the AG server.
#
# Scripts support will be ENABLED if this parameter is absent or misconfigured.
#
#scripts_enabled: true

#
# A true/false value that enables Terraform support on the AG server.
#
# Terraform support will be DISABLED if this parameter is absent or misconfigured.
#
#terraform_enabled: true

#
# A true/false value that enables netmiko support on the AG server.
#
# Netmiko support will be DISABLED if this parameter is absent or misconfigured.
#
#netmiko_enabled: true

#
# A true/false value that enables Nornir support on the AG server.
#
# Nornir support will be DISABLED if this parameter is absent or misconfigured.
#
#nornir_enabled: true

#
# Path(s) to the Ansible network modules to be discovered by Automation Gateway.
#
# This parameter only needs to be configured if the path reported by 'ansible --version'
# is incorrect or you would like to customize/trim down the set of Ansible modules that
# will be discovered.
#
# The module_path parameter can be set to either a single path or list of paths.
#
# Ansible 2.7.x - 2.9.x
#
#module_path: /usr/local/lib/python3.6/site-packages/ansible/modules/network
#
# Ansible 2.10
#
#module_path: /usr/local/lib/python3.6/site-packages/ansible_collections
#
# This is what a list of paths looks like:
#
#module_path: |
#  ['/usr/local/lib/python3.6/site-packages/ansible/modules/network/ios',
#   '/usr/local/lib/python3.6/site-packages/ansible/modules/network/junos']
#

#
# Path to the set of Ansible roles you would like to invoke from Automation Gateway.
# This can be set to either a single path or a list of paths.
#
# This is what a list of paths looks like:
# role_path: ['/usr/share/ansible/roles', '/usr/share/ansible/roles2']
#

role_path: /usr/share/ansible/roles

#
# Path to the set of Ansible playbooks you would like to invoke from Automation Gateway.
# This can be set to either a single path or a list of paths.
#
# This is what a list of paths looks like:
# playbook_path: ['/usr/share/ansible/playbooks', '/usr/share/ansible/playbooks2']
#

playbook_path: /usr/share/ansible/playbooks

#
# Path to the set of scripts you would like to invoke from Automation Gateway.
# This can be set to either a single path or a list of paths.
#
# This is what a list of paths looks like:
# script_path: ['/path/to/script_dir1', '/path/to/script_dir2']
#

script_path: /usr/share/ansible/scripts

#
# Path to the set of terraform modules/scripts you would like to invoke from Automation Gateway.
# This can either be set to a single path or a list of paths.
#
# This is what a list of paths looks like:
# terraform_path: ['/path/to/terraform_dir1','/path/to/terraform_dir2']
#
#terraform_path: /usr/share/terraform/scripts

#
# Name of Ansible external inventory file.
# Uncomment this property if you will be using an existing Ansible inventory.
#
#inventory_file: ~/.ansible/hosts

#
# Name of the file that contains a password used by ansible-vault to encrypt strings.
# Uncomment this property if you will be using Ansible vault encrypted variables.
# Be sure to secure this file with permissions of 0200 or 0400.
#
#vault_password_file: /opt/automation-gateway/conf/.vault_password_file

#
# Flag that determines whether authentication is disabled or not.
# Warning: only disable authentication on a personal vm environment.
#
authentication_disabled: false

#
# The maximum number of concurrent sessions allowed.
#
authentication_max_sessions: 5000

#
# The idle timeout of each session (in seconds).
#
authentication_idle_timeout: 600

#
# The strict_args property controls whether schema validation will be performed when invoking
# Ansible modules, roles, and playbooks.
# This property may be set to false for development and lab environments while modules,
# roles, playbooks, and scripts are being decorated.
# This property should be set to true for testing and production workloads.
#
strict_args: true

#
# Base of url for external proxy, used for generating redirects:
# external_address: 'http://automation-gateway.example.com:8080'

#
# Set the ansible_debug property to true to log additional debug messages when
# executing Ansible modules, roles, or playbooks.
#
#ansible_debug: true

#
# Set the no_cleanup property to true to maintain temporary files created during the
# execution of Ansible modules, roles, or playbooks.
#
#no_cleanup: true

#
# The logging level of the Automation Gateway Server. Associated logging levels in order
# of ascending severity are DEBUG, INFO, WARNING, ERROR, or CRITICAL. Log messages of
# equal and greater severity will be displayed in the log. For example, a server with a
# logging_level of INFO will display log messages with a severity of INFO, WARNING, ERROR,
# or CRITICAL. The server defaults to a logging level of INFO if this parameter is absent
# or misconfigured.
#
logging_level: INFO

#
# The logging level of the Automation Gateway HTTP Server. Possible logging levels in order
# of ascending severity are DEBUG, INFO, WARNING, ERROR, or CRITICAL. Log messages of
# equal and greater severity will be displayed in the log. For example, a server with a
# logging_level of INFO will display log messages with a severity of INFO, WARNING, ERROR,
# or CRITICAL. The server defaults to a logging level of INFO if this parameter is absent
# or misconfigured.
#
# Note: request details are DEBUG level log messages, it may be useful to set this to DEBUG
#
http_logging_level: INFO

#
# Configure the number of http server threads. This controls the number of threads for
# handling requests. A good starting point is 2-4 x NUM_CORES then adjust based on observed
# workload.
#
# http_server_threads: 8

Configuring Ansible Module Search Paths

By default, Automation Gateway uses information from the ansible --version command to determine the path to search for Ansible network modules. A recursive search of the path is performed at startup time as part of the module discovery process. If for some reason this path is incorrect, the module_path parameter can be configured to override the default Ansible module search path. Starting in Release 2020.2, the module_path configuration parameter has been changed from a single search path entry to a list of directory paths. This allows users to configure a subset of the Ansible directories to be searched in order to trim down the overall number of network modules that will be discovered. Note that a recursive search will be performed on all paths.

Note: Starting in Ansible 2.10, the path returned by the 'ansible --version' command does not match the actual location where the Ansible network modules reside in the release directory structure. The module_path parameter should be set to the following to enable discovery of modules by Automation Gateway.

module_path: /usr/local/lib/python3.6/site-packages/ansible_collections

Support for module search paths outside of the Ansible release directory structure is also available by updating the Ansible Configuration settings. This is done by editing the ansible.cfg configuration file.

Add the library key to the [defaults] section of the ansible.cfg file to expand the list of directories Automation Gateway will search for in addition to the network modules found in the Ansible release directory.

[defaults]

library = /path/to/ansible/modules1:/path/to/ansible/modules2

See the link below for more information on Ansible configuration.

Reference: Ansible Configuration

Start the Automation Gateway Server

Automation Gateway includes a script named automation-gateway that is located in /usr/bin/automation-gateway.

The script is used to start the Automation Gateway server and the path is within the $PATH variable.

$ sudo su itential -c automation-gateway --properties-file=/opt/automation-gateway
Ansible external inventory file: /opt/ansible/inventory/zone1
Automation Gateway starting.
Ansible Version: 2.7.10
Ansible Runner Version: 1.2.0
Ansible device count: 112
Ansible group count: 1
Ansible modules path: /usr/lib/python2.7/site-packages/ansible/modules/network
Ansible modules metadata directory: automation_gateway/metadata/modules
Error reading YAML: /usr/lib/python2.7/site-packages/ansible/modules/network/netscaler/netscaler_lb_monitor.py
Error reading YAML: /usr/lib/python2.7/site-packages/ansible/modules/network/netscaler/netscaler_lb_vserver.py
Ansible module count: 669
Ansible roles path: /usr/share/ansible/roles
Ansible roles metadata directory: automation_gateway/metadata/roles
Ansible role count: 3
Ansible playbooks path: /usr/share/ansible/playbooks
Ansible playbooks metadata directory: automation_gateway/metadata/playbooks
Ansible playbook count: 16
 * Serving Flask app "automation_gateway" (lazy loading)
 * Environment: production
   WARNING: Do not use the development server in a production environment.
   Use a production WSGI server instead.
 * Debug mode: off
 * Running on http://0.0.0.0:8083/ (Press CTRL+C to quit)

Start Automation Gateway Server as a Systemd Service

If Automation Gateway was setup as a Systemd Service (see the automation-gatway-setup.sh script), start and stop Automation Gateway by using the following:

$ sudo systemctl start automation-gateway
$ sudo systemctl status automation-gateway
● automation-gateway.service - Itential Automation Gateway
   Loaded: loaded (/etc/systemd/system/automation-gateway.service; disabled; vendor preset: disabled)
   Active: active (running) since Wed 2018-11-07 21:06:43 UTC; 16s ago
 Main PID: 26353 (python3.6)
   CGroup: /system.slice/automation-gateway.service
           └─26353 /bin/python3.6 telegraph.pyc

Nov 07 21:06:56 telegraph01 python3.6[26353]: Ansible role count: 3
Nov 07 21:06:56 telegraph01 python3.6[26353]: Ansible playbooks path: /opt/ansible/playbooks
Nov 07 21:06:56 telegraph01 python3.6[26353]: Ansible playbooks metadata directory: automation_gateway/metadata/playbooks
Nov 07 21:06:56 telegraph01 python3.6[26353]: Ansible playbook count: 16
Nov 07 21:06:56 telegraph01 python3.6[26353]: * Serving Flask app "automation-gateway" (lazy loading)
Nov 07 21:06:56 telegraph01 python3.6[26353]: * Environment: production
Nov 07 21:06:56 telegraph01 python3.6[26353]: WARNING: Do not use the development server in a production environment.
Nov 07 21:06:56 telegraph01 python3.6[26353]: Use a production WSGI server instead.
Nov 07 21:06:56 telegraph01 python3.6[26353]: * Debug mode: off
Nov 07 21:06:56 telegraph01 python3.6[26353]: * Running on http://0.0.0.0:8083/ (Press CTRL+C to quit)

sudo systemctl stop automation-gateway

Note: Automation Gateway uses the Ansible Runner software package to exchange data to and from Ansible. Currently, Ansible Runner has a limit on the size of the results data that can be returned from Ansible. This limit can be be increased by setting the environment variable MAX_EVENT_RES. If the message "No results data available" is received while retrieving operational or configuration data from a device, consider increasing the MAX_EVENT_RES variable:

Edit the /etc/systemd/system/automation-gateway.service file.
Run sudo systemctl daemon-reload.
Restart the Automation Gateway.

A sample file showing the MAX_EVENT_RES configuration is provided below:

sudo vi /etc/systemd/system/automation-gateway.service

[Unit]
Description=Itential Automation Gateway
After=network.target

[Service]
User=itential
Restart=always
Type=simple
ExecStart=/usr/bin/automation-gateway --properties-file=/opt/automation-gateway/conf/properties.yml
WorkingDirectory=/tmp
Environment=MAX_EVENT_RES=15000000

[Install]
WantedBy=multi-user.target

Enable Automation Gateway to Start on System Boot (Optional)

As long as Automation Gateway has been setup as a systemd service properly (see the automation-gateway-setup.sh script), the following commands are used to enable Automation Gateway to start when the system boots.

$ sudo systemctl is-enabled automation-gateway
disabled
$ sudo systemctl enable automation-gateway
Created symlink from /etc/systemd/system/multi-user.target.wants/automation-gateway.service to /etc/systemd/system/automation-gateway.service.

Itential Automation Gateway

Help us improve by sending feedback...

On this page:

Configuration