Ansible collection to install and run Gateway 5
An IAG5 environment is composed of several applications working in conjunction with one another.
The Itential IAG5 collection can deploy all supported Itential IAG5 architectures. It will only install and configure the IAG5 components listed above; it does not handle installing/configuring Etcd or DynamoDB.
The Itential IAG5 collection is an Ansible collection and as such requires running on a control node. That node has its own set of dependencies.
Itential recommends using a dedicated node running the requirements listed below as the Ansible control node. That node should meet or exceed the following specifications:
| Component | Value |
|---|---|
| OS | RHEL8/9 or Rocky 8/9 |
| RAM | 4 GB |
| CPUs | 2 |
| Disk | 20 GB |
The Ansible Control Node must have the following installed:
Python
Ansible
To see which Ansible version is currently installed, execute the ansible --version command as
shown below.
ansible [core 2.15.13]
config file = None
configured module search path = ['/home/<USER>/.ansible/plugins/modules', '/usr/share/ansible/plugins/modules']
ansible python module location = /home/<USER>/.local/lib/python3.9/site-packages/ansible
ansible collection location = /home/<USER>/.ansible/collections:/usr/share/ansible/collections
executable location = /home/<USER>/.local/bin/ansible
python version = 3.9.21 (main, Jun 27 2025, 00:00:00) [GCC 11.5.0 20240719 (Red Hat 11.5.0-5)] (/usr/bin/python3)
jinja version = 3.1.6
libyaml = True ⓘ Note: The Itential IAG5 project is an Ansible collection. As such, a familiarity with basic Ansible concepts is suggested before proceeding.
On the Ansible control node, the Ansible Python module and the IAG5 collection will need to be installed.
On the target servers, the IAG5 collection will install RPM packages using the standard YUM repositories. When packages are not available for the distribution, the IAG collection will either install the required repository or download the packages.
| Server | Location | Notes |
|---|---|---|
| Ansible Control Node | https://pypi.org | |
| Ansible Control Node | https://galaxy.ansible.com | |
| IAG5 | https://registry.aws.itential.com | |
| IAG5 | https://itential.jfrog.io | |
| IAG5 | https://galaxy.ansible.com | When Ansible is enabled |
| IAG5 | https://python.org | When Python is enabled |
| IAG5 | https://pythonhosted.org | When Python is enabled |
| IAG5 | https://pypi.org | When Python is enabled |
| IAG5 | https://packages.opentofu.org | When OpenTofu is enabled |
| IAG5 | https://get.opentofu.org | When OpenTofu is enabled |
[! WARNING] Neither the IAG5 collection nor the maintainers of the project can not know if any of the above URLs will result in a redirect. If a customer is using a proxy or other such method to restrict access this list may not represent the final URLs or IP addresses that are required.
To verify connectivity to the "IAG5" rows above from the target hosts (excluding the Ansible
Control Node rows, which are the control node's own responsibility), run the verify playbook:
ansible-playbook itential.iag5.verify -i <inventory> See docs/verify.md for details.
In a clustered environment where components are installed on more than one host, the following network traffic flows need to be allowed.
| Source | Destination | Port | Protocol | Description |
|---|---|---|---|---|
| IAG5 | Itential Gateway Manager | 8080 | TCP | IAG5 connection to Itential Gateway Manager (on-prem) |
| IAG5 | Itential Gateway Manager | 443 | TCP | IAG5 connection to Itential Gateway Manager (cloud) |
| IAG5 Client | IAG5 Server | 50051 | TCP | IAG5 Client connection to IAG5 Server |
| IAG5 Server | IAG5 Runner | 50051 | TCP | IAG5 Server connection to IAG5 Runner |
| IAG5 Server/Runner | DynamoDB | 443 | TCP | IAG5 Server/Runner connection to DynamoDB |
| IAG5 Server/Runner | Etcd | 2379 | TCP | IAG5 Server/Runner connection to Etcd |
Notes
The IAG5 collection is not responsible for creating any TLS certificates that may be used to further tighten security in the Itential ecosystem. However, if these certificates are provided it can upload and configure the platform to use them. The table below describes the certificates that can be used and what their purpose is.
| Certificate | Description |
|---|---|
| Gateway Manager | Enables secure communication with the Itential Gateway Manager. |
| IAG5 Client | |
| IAG5 Server | |
| IAG5 Runner |
The IAG5 collection will create several user accounts in the dependent systems. It uses default passwords in all cases and those passwords can be overridden with the defined ansible variables. To override these variables just define the variable in the IAG5 inventory.
The IAG5 artifacts are hosted on the Itential Nexus repository. An account is required to access Itential Nexus. If you do not have an account, contact your Itential Sales representative.
The Itential IAG5 collection can be installed via the ansible-galaxy utility.
On your control node, execute the following command to install the collection:
ansible-galaxy collection install itential.iag5 This should also install the required Ansible dependencies. When a new version of the IAG5 collection is available, you can upgrade using the following command:
ansible-galaxy collection install itential.iag5 --upgrade If your control node does not have internet connectivity, the IAG5 collection and its dependencies can be downloaded via another system, copied to your control node, and installed manually.
ⓘ Note:
Some of the following collections may already be installed on your control node. To verify, use the
ansible-galaxy collection list command.
TODO
Copy the downloaded collections to your control node.
Install the collections using the following command:
ansible-galaxy collection install <COLLECTION>.tar.gz Once you have have installed the IAG5 collection, run it to begin deploying IAG5 to your environment. This section details a basic deployment using required variables only.
Before running the IAG5 collection we must ensure the following:
ansible_user must have administrative privileges on managed
nodes.ⓘ Note: Although the IAG5 collection can be used to configure nodes that use any supported operating system, it is optimized for Rocky/RHEL 8/9.
The IAG5 collection will be installed into the user's collection directory. Because the IAG5 collection will be overwritten when it is upgraded, users should not store any inventory files, binaries or artifacts in the IAG5 collection directory. Instead, users should create a working directory to store those files.
The working directory can be any directory on the control node and will be referred to as the
WORKING-DIR in this guide.
Determine what directory the IAG5 collection is installed to by using the ansible-galaxy collection list command. In the following example, the IAG5 collection directory is
/home/<USER>/.ansible/collections/ansible_collections/itential/iag5.
% ansible-galaxy collection list
# //home/<USER>/.ansible/collections/ansible_collections
Collection Version
----------------- -------
itential.iag5 1.0.0 The IAG5 collection directory will be referred to as the IAG5-DIR in this guide.
The inventories directory should be a sub-directory of the working directory. It will contain
the hosts files.
cd <WORKING-DIR>
mkdir inventories Choose one of the following installation methods based on your requirements:
files
directory. The IAG5 collection will move these artifact files to the target nodes.The files directory should be a sub-directory of the working directory. It will contain the
Itential binaries and artifacts.
cd <WORKING-DIR>
mkdir files Download the IAG5 RPMs/tarballs from the Itential Nexus Repository to local storage.
ⓘ Note: If you are unsure which files should be downloaded for your environment, contact your Itential Professional Services representative.
Next, copy the files downloaded in the previous step to the files subdirectory.
cd <WORKING-DIR>/files
cp ~/Downloads/iagctl*.rpm . Navigate to the playbooks directory in the IAG5 directory and create a symlink to the files directory in the working directory.
cd <IAG5-DIR>/playbooks
ln -s <WORKING-DIR>/files . You can obtain the download URL from either a Sonatype Nexus Repository or JFrog. Follow the steps below based on the repository type:
This download method supports both the IAG5 RPM and tarball files.
Depending on the repository you are using, you will need to provide the appropriate credentials:
repository_username and repository_password variables.repository_api_key variable.ⓘ Note: To secure sensitive information like passwords or API keys, consider using Ansible Vault to encrypt these variables.
Using a text editor, create an inventory file that defines your deployment environment. To do this, assign your managed nodes to the relevant groups according to what components you would like to install on them. In the following example:
ⓘ Note: Itential recommends that all inventories follow the best practices outlined in the Ansible documentation.
cd <WORKING-DIR>
mkdir -p inventories/dev
vi inventories/dev/hosts all:
vars:
ansible_user: <ANSIBLE-USER>
# Nexus
repository_username: <NEXUS-USERNAME>
repository_password: <NEXUS-PASSWORD>
children:
gateway_all:
children:
iag5_servers:
iag5_clients:
vars:
gateway_pki_src_dir: <PKI-DIR>
gateway_servers:
children:
iag5_servers:
vars:
gateway_server_packages:
- <IAGCTL-RPM>
gateway_server_secrets_encrypt_key: <ENCRYPT-KEY>
iag5_servers:
hosts:
<IAG5-SERVER-HOSTNAME>:
ansible_host: <IAG5-SERVER-IP>
vars:
gateway_server_connect_hosts: <GATEWAY-MANAGER-IP>:8080
iag5_clients:
hosts:
<IAG5-CLIENT-HOSTNAME>:
ansible_host: <IAG5-CLIENT-IP>
vars:
gateway_client_host: <IAG5-SERVER-IP>
gateway_client_packages:
- <IAGCTL-TARBALL> Before running the installation, run the pre-flight verification playbook to confirm that all target nodes meet OS, hardware, and TLS requirements:
cd <WORKING-DIR>
ansible-playbook itential.iag5.verify -i inventories/<env> All checks must pass before proceeding. See the verify guide for a full description of checks and how to interpret failures.
Navigate to the working directory and execute the following run command.
cd <WORKING-DIR>
ansible-playbook itential.iag5.site -i inventories/dev After the IAG5 playbook is finished running, perform the following checks on each component to confirm successful installation.
$ sudo systemctl status iagctl In addition to the site playbook, there are playbooks for running the individual components.
cd <WORKING-DIR>
ansible-playbook itential.iag5.clients -i inventories/dev cd <WORKING-DIR>
ansible-playbook itential.iag5.servers -i inventories/dev cd <WORKING-DIR>
ansible-playbook itential.iag5.runners -i inventories/dev Verifies OS, hardware, and TLS file requirements across all node types before installation or upgrade. Can be run at any time — does not require IAG5 to be installed.
cd <WORKING-DIR>
ansible-playbook itential.iag5.verify -i inventories/dev See the verify guide for full details.
Runs a full post-deployment certification of the IAG5 installation. Run this playbook manually after a deployment completes. It performs two certifications in sequence per node:
A markdown report is generated per node and fetched to ./certify_reports/ on the control node.
cd <WORKING-DIR>
ansible-playbook itential.iag5.certify -i inventories/dev Each certification can be run independently using tags:
| Tag | What runs |
|---|---|
certify-iag5 | Both installation + TLS certification (default) |
certify-install | Installation certification only |
certify | TLS certification only |
# Installation certification only
ansible-playbook itential.iag5.certify -i inventories/dev --tags certify-install
# TLS certification only
ansible-playbook itential.iag5.certify -i inventories/dev --tags certify Reports are fetched to ./certify_reports/ relative to the directory where ansible-playbook is
run. Two report files are produced per node:
| Report | Remote path | Control node filename |
|---|---|---|
| Installation | /tmp/certify-iag5-<node_type>-report-<hostname>.md | certify-iag5-<node_type>-report-<hostname>.md |
| TLS | /tmp/certify-tls-<hostname>.md | certify-tls-<hostname>.md |
See the certify guide for a full description of all checks and how to interpret results.
Runs deep TLS certificate validation across all node types without the installation forensics. Validates certificate chains, cert/key matching, SANs, mTLS enforcement, and live handshake tests. Can be run standalone at any time after deployment.
cd <WORKING-DIR>
ansible-playbook itential.iag5.certify-tls -i inventories/dev See the certify guide for full details.
Below are simplified sample host files that describe the basic configurations to produce the supported architectures. These are intended to be starting points only.
# Notes:
# - All example inventory_hostname entries must be replaced with the actual server hostnames.
# - All hostnames must be resolvable.
all:
vars:
ansible_user: <ANSIBLE-USER>
# Itential Nexus repository credentials
repository_username: <NEXUS-USERNAME>
repository_password: <NEXUS-PASSWORD>
gateway_secrets_encrypt_key: <ENCRYPT-KEY>
gateway_pki_src_dir: <PKI-DIR>
children:
iag5_servers:
hosts:
gateway-server01.example.com:
ansible_host: <GATEWAY-SERVER01-IP>
vars:
gateway_server_connect_hosts: <GATEWAY-MANAGER-IP>:8080
gateway_server_packages:
- <IAGCTL-RPM>
iag5_clients:
hosts:
gateway-client01.example.com:
ansible_host: <GATEWAY-CLIENT01-IP>
gateway_client_host: <GATEWAY-SERVER01-IP>
vars:
gateway_client_packages:
- <IAGCTL-TARBALL> # Notes:
# - All example inventory_hostname entries must be replaced with the actual server hostnames.
# - All hostnames must be resolvable.
# - Backend 'dynamodb' is also supported; see Reference Guide for details.
all:
vars:
ansible_user: <ANSIBLE-USER>
# Itential Nexus repository credentials
repository_username: <NEXUS-USERNAME>
repository_password: <NEXUS-PASSWORD>
gateway_secrets_encrypt_key: <ENCRYPT-KEY>
gateway_pki_src_dir: <PKI-DIR>
children:
iag5_servers:
hosts:
gateway-server01.example.com: # active gateway server
ansible_host: <GATEWAY-SERVER01-IP>
gateway-server02.example.com: # standby gateway server
ansible_host: <GATEWAY-SERVER02-IP>
vars:
gateway_server_connect_hosts: <GATEWAY-MANAGER-IP>:8080
gateway_server_packages:
- <IAGCTL-RPM>
gateway_server_store_backend: etcd
gateway_server_store_etcd_hosts: <ETCD-SERVER01-IP>:2379 <ETCD-SERVER02-IP>:2379 <ETCD-SERVER03-IP>:2379
iag5_clients:
hosts:
gateway-client01.example.com:
ansible_host: <GATEWAY-CLIENT01-IP>
gateway_client_host: <GATEWAY-SERVER01-IP>
vars:
gateway_client_packages:
- <IAGCTL-TARBALL> # Notes:
# - All example inventory_hostname entries must be replaced with the actual server hostnames.
# - All hostnames must be resolvable.
# - Backend 'etcd' is also supported; see Reference Guide for details.
# - gateway_server_store_dynamodb_aws_session_token is only needed for temporary/STS credentials; omit for long-lived IAM keys.
all:
vars:
ansible_user: <ANSIBLE-USER>
# Itential Nexus repository credentials
repository_username: <NEXUS-USERNAME>
repository_password: <NEXUS-PASSWORD>
gateway_secrets_encrypt_key: <ENCRYPT-KEY>
gateway_pki_src_dir: <PKI-DIR>
children:
iag5_servers:
hosts:
gateway-server01.example.com: # active gateway server
ansible_host: <GATEWAY-SERVER01-IP>
gateway-server02.example.com: # standby gateway server
ansible_host: <GATEWAY-SERVER02-IP>
vars:
gateway_server_connect_hosts: <GATEWAY-MANAGER-IP>:8080
gateway_server_packages:
- <IAGCTL-RPM>
gateway_server_store_backend: dynamodb
gateway_server_store_dynamodb_table_name: <DYNAMODB-TABLE-NAME>
gateway_server_store_dynamodb_aws_region: <AWS-REGION>
gateway_server_store_dynamodb_aws_access_key_id: <AWS-ACCESS-KEY-ID>
gateway_server_store_dynamodb_aws_secret_access_key: <AWS-SECRET-ACCESS-KEY>
iag5_clients:
hosts:
gateway-client01.example.com:
ansible_host: <GATEWAY-CLIENT01-IP>
gateway_client_host: <GATEWAY-SERVER01-IP>
vars:
gateway_client_packages:
- <IAGCTL-TARBALL> # Notes:
# - All example inventory_hostname entries must be replaced with the actual server hostnames.
# - All hostnames must be resolvable.
# - Backend 'dynamodb' is also supported; see Reference Guide for details.
all:
vars:
ansible_user: <ANSIBLE-USER>
# Itential Nexus repository credentials
repository_username: <NEXUS-USERNAME>
repository_password: <NEXUS-PASSWORD>
gateway_secrets_encrypt_key: <ENCRYPT-KEY>
gateway_pki_src_dir: <PKI-DIR>
children:
iag5_servers:
hosts:
gateway-server01.example.com:
ansible_host: <GATEWAY-SERVER01-IP>
vars:
gateway_server_connect_hosts: <GATEWAY-MANAGER-IP>:8080
gateway_server_distributed_execution: true
iag5_runners:
hosts:
gateway-runner01.example.com:
ansible_host: <GATEWAY-RUNNER01-IP>
gateway-runner02.example.com:
ansible_host: <GATEWAY-RUNNER02-IP>
gateway-runner03.example.com:
ansible_host: <GATEWAY-RUNNER03-IP>
iag5_servers_runners:
hosts:
gateway-server01.example.com:
gateway-runner01.example.com:
gateway-runner02.example.com:
gateway-runner03.example.com:
vars:
gateway_server_packages:
- <IAGCTL-RPM>
gateway_server_store_backend: etcd
gateway_server_store_etcd_hosts: <ETCD-SERVER01-IP>:2379 <ETCD-SERVER02-IP>:2379 <ETCD-SERVER03-IP>:2379
iag5_clients:
hosts:
gateway-client01.example.com:
ansible_host: <GATEWAY-CLIENT01-IP>
gateway_client_host: <GATEWAY-SERVER01-IP>
vars:
gateway_client_packages:
- <IAGCTL-TARBALL> # Notes:
# - All example inventory_hostname entries must be replaced with the actual server hostnames.
# - All hostnames must be resolvable.
# - Backend 'dynamodb' is also supported; see Reference Guide for details.
all:
vars:
ansible_user: <ANSIBLE-USER>
# Itential Nexus repository credentials
repository_username: <NEXUS-USERNAME>
repository_password: <NEXUS-PASSWORD>
gateway_secrets_encrypt_key: <ENCRYPT-KEY>
gateway_pki_src_dir: <PKI-DIR>
children:
iag5_servers:
hosts:
gateway-server01.example.com: # active gateway server
ansible_host: <GATEWAY-SERVER01-IP>
gateway-server02.example.com: # standby gateway server
ansible_host: <GATEWAY-SERVER02-IP>
vars:
gateway_server_connect_hosts: <GATEWAY-MANAGER-IP>:8080
gateway_server_distributed_execution: true
iag5_runners:
hosts:
gateway-runner01.example.com:
ansible_host: <GATEWAY-RUNNER01-IP>
gateway-runner02.example.com:
ansible_host: <GATEWAY-RUNNER02-IP>
gateway-runner03.example.com:
ansible_host: <GATEWAY-RUNNER03-IP>
iag5_servers_runners:
hosts:
gateway-server01.example.com:
gateway-server02.example.com:
gateway-runner01.example.com:
gateway-runner02.example.com:
gateway-runner03.example.com:
vars:
gateway_server_packages:
- <IAGCTL-RPM>
gateway_server_store_backend: etcd
gateway_server_store_etcd_hosts: <ETCD-SERVER01-IP>:2379 <ETCD-SERVER02-IP>:2379 <ETCD-SERVER03-IP>:2379
iag5_clients:
hosts:
gateway-client01.example.com:
ansible_host: <GATEWAY-CLIENT01-IP>
gateway_client_host: <GATEWAY-SERVER01-IP>
vars:
gateway_client_packages:
- <IAGCTL-TARBALL> # Notes:
# - All example inventory_hostname entries must be replaced with the actual server hostnames.
# - All hostnames must be resolvable.
# - Backend 'dynamodb' is also supported; see Reference Guide for details.
all:
vars:
ansible_user: <ANSIBLE-USER>
# Itential Nexus repository credentials
repository_username: <NEXUS-USERNAME>
repository_password: <NEXUS-PASSWORD>
gateway_secrets_encrypt_key: <ENCRYPT-KEY>
gateway_pki_src_dir: <PKI-DIR>
children:
iag5_servers:
hosts:
cluster1-server01.example.com:
ansible_host: <CLUSTER1-SERVER01-IP>
cluster2-server01.example.com:
ansible_host: <CLUSTER2-SERVER01-IP>
vars:
gateway_server_connect_hosts: <GATEWAY-MANAGER-IP>:8080
gateway_server_distributed_execution: true
iag5_runners:
hosts:
cluster1-runner01.example.com:
ansible_host: <CLUSTER1-RUNNER01-IP>
cluster1-runner02.example.com:
ansible_host: <CLUSTER1-RUNNER02-IP>
cluster1-runner03.example.com:
ansible_host: <CLUSTER1-RUNNER03-IP>
cluster2-runner01.example.com:
ansible_host: <CLUSTER2-RUNNER01-IP>
cluster2-runner02.example.com:
ansible_host: <CLUSTER2-RUNNER02-IP>
cluster2-runner03.example.com:
ansible_host: <CLUSTER2-RUNNER03-IP>
iag5_servers_runners:
hosts:
cluster1-server01.example.com:
cluster1-runner01.example.com:
cluster1-runner02.example.com:
cluster1-runner03.example.com:
cluster2-server01.example.com:
cluster2-runner01.example.com:
cluster2-runner02.example.com:
cluster2-runner03.example.com:
vars:
gateway_server_packages:
- <IAGCTL-RPM>
gateway_server_store_backend: etcd
iag5_cluster1_all:
hosts:
cluster1-client01.example.com:
cluster1-server01.example.com:
cluster1-runner01.example.com:
cluster1-runner02.example.com:
cluster1-runner03.example.com:
vars:
gateway_cluster_id: cluster_1
iag5_cluster1_servers_runners:
hosts:
cluster1-server01.example.com:
cluster1-runner01.example.com:
cluster1-runner02.example.com:
cluster1-runner03.example.com:
vars:
gateway_server_store_etcd_hosts: <CLUSTER1-ETCD-SERVER1-IP>:2379 <CLUSTER1-ETCD-SERVER2-IP>:2379 <CLUSTER1-ETCD-SERVER3-IP>:2379
iag5_cluster2_all:
hosts:
cluster2-client01.example.com:
cluster2-server01.example.com:
cluster2-runner01.example.com:
cluster2-runner02.example.com:
cluster2-runner03.example.com:
vars:
gateway_cluster_id: cluster_2
iag5_cluster2_servers_runners:
hosts:
cluster2-server01.example.com:
cluster2-runner01.example.com:
cluster2-runner02.example.com:
cluster2-runner03.example.com:
vars:
gateway_server_store_etcd_hosts: <CLUSTER2-ETCD-SERVER1-IP>:2379 <CLUSTER2-ETCD-SERVER2-IP>:2379 <CLUSTER2-ETCD-SERVER3-IP>:2379
iag5_clients:
hosts:
cluster1-client01.example.com:
ansible_host: <CLUSTER1-CLIENT01-IP>
gateway_client_host: <CLUSTER1-SERVER01-IP>
cluster2-client01.example.com:
ansible_host: <CLUSTER2-CLIENT01-IP>
gateway_client_host: <CLUSTER2-SERVER01-IP>
vars:
gateway_client_packages:
- <IAGCTL-TARBALL> All IAG5 collection variables are documented in the IAG Reference Guide.
To patch IAG5, simply replace the the current artifacts (RPM or tarball) in the inventory with the new artifacts and re-run the appropriate playbook.