Using the Itential Deployer
  • 06 Feb 2024
  • Dark
    Light
  • PDF

Using the Itential Deployer

  • Dark
    Light
  • PDF

Article Summary

An Itential environment is composed of several applications working in conjunction with one another, including:

  • Itential Automation Platform (IAP)
  • Itential Automation Gateway (IAG)
  • Redis
  • RabbitMQ
  • MongoDB

In many environments, these applications are installed across multiple systems to improve resiliency and performance. To assist users with such installations, Itential provides the Itential Deployer. In this guide, you will learn:

  • The basic concepts used when operating the Itential Deployer.
  • How to install the Itential Deployer.
  • How to perform deployments using the Itential Deployer.
  • Advanced concepts used to perform more complex deployments.

Itential Deployer Overview

The Itential Deployer is a collection of Ansible playbooks and roles that can be used to deploy the applications of an Itential environment, along with their dependencies, across one or more systems. Its behavior is largely controlled by manipulating Ansible inventory files. This section provides an overview of the concepts used when configuring these inventory files. You will use these concepts later to complete the deployment steps listed in the Deploying Itential section of this guide.

ⓘ Note:

The Itential Deployer is an Ansible collection. As such, a familiarity with basic Ansible concepts is suggested before proceeding.

Groups and Components

The Itential Deployer installs components on managed nodes according to their group memberships as defined in an inventory file. For example, if the managed node host1 is assigned to the platform group, the IAP component will be installed on it. Available groups are referenced in the following table.

Group Description
platform Installs IAP on member managed nodes.
gateway Installs IAG on member managed nodes.
redis Installs Redis on member managed nodes.
rabbitmq Installs RabbitMQ on member managed nodes.
mongodb Installs MongoDB on member managed nodes.
mongodb_arbiter Installs MongoDB on member managed nodes and configures them as MongoDB arbiters.
vault Installs HashiCorp Vault on member managed nodes.

Multiple components can be installed on a managed node by assigning it to the relevant groups. Likewise, if no managed nodes are assigned to a group, the Itential Deployer will not install the related component on any system.

⚠ Warning:

IAP and IAG cannot be installed on the same managed node.

Required Variables

After defining which components should be installed and where via assigned groups, several variables must be defined for those groups in the same inventory file.

When installing only IAP and its dependencies, the following group variables are required.

Variable Group Type Description Example
iap_release all Fixed-point Designates which major release version of IAP to install. 2023.1
iap_bin_file or iap_tar_file platform String The name of the IAP .bin or .tar file to run, respectively. Only one of these variables should be specified simultaneously. itential-premium_2023.1.1.linux.x86_64.bin

When also installing IAG, these additional group variables are required.

Variable Group Type Description Example
iag_release gateway Fixed-point Designates which major release version of IAG to install. 2023.1
iag_whl_file gateway String The name of the IAG .whl file to run. automation_gateway-3.198.19+2023.1.0-py3-none-any.whl

Installing the Itential Deployer

Before deploying Itential to your environment, the Itential Deployer must be installed on your control node.

Prerequisites

The following prerequisites must be met before proceeding with your install.

  • Itential Galaxy Access: The Itential Deployer is hosted on the Itential Galaxy repository. An account is required to access Itential Galaxy. If you do not have an account, contact your Itential Sales representative.
  • Ansible Version: The control node must be running Ansible version 2.11 or later. To see which Ansible version is currently installed, execute the ansible --version command as shown below.

Example: Confirming Ansible Version

$ ansible --version
  ansible [core 2.12.2]
  config file = None
  configured module search path = ['/var/home/yourname/.ansible/plugins/modules', '/usr/share/ansible/plugins/modules']
  ansible python module location = /usr/local/lib/python3.9/site-packages/ansible
  ansible collection location = /var/home/yourname/.ansible/collections:/usr/share/ansible/collections
  executable location = /usr/local/bin/ansible
  python version = 3.9.9 (main, Nov 19 2021, 00:00:00) [GCC 11.2.1 20210728 (Red Hat 11.2.1-1)]
  jinja version = 3.0.3
  libyaml = True

Install Procedure

The Itential Deployer can be installed via the ansible-galaxy utility. To do this, configure Ansible to use the Itential and Ansible Galaxy servers when installing collections. On your control node:

  1. Create a blank file named ansible.cfg in your working directory. This will be your new Ansible configuration file.

  2. Open ansible.cfg in a text editor and add the following. Be sure to supply the proper credentials where relevant.

    [galaxy]
    server_list = itential_galaxy, release_galaxy
    
    [galaxy_server.itential_galaxy]
    url=https://registry.aws.itential.com/repository/ansible-galaxy/
    username=<USERNAME>
    password=<PASSWORD>
    
    [galaxy_server.release_galaxy]
    url=https://galaxy.ansible.com/
    
  3. Execute the following command to install the Itential Deployer:

    ansible-galaxy collection install itential.deployer
    

Offline Installations

If your control node does not have Internet connectivity, the Itential Deployer 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.

  1. Download the following collections from the provided links:

  2. Copy the downloaded collections to your control node.

  3. Install the collections using the following command:

    ansible-galaxy collection install <COLLECTION>.tar.gz
    

Deploying Itential

Once you have have installed the Itential Deployer, run it to begin deploying Itential to your environment. This section details a basic deployment using required variables only. An example of a more advanced deployment is provided in the Advanced Deployment Example section.

Prerequisites

The following prerequisites must be met before proceeding.

  • Itential Nexus Repository Access: The IAP and IAG binary files 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 Professional Services representative.
  • Compatible OS: Any managed nodes to be configured by the Itential Deployer must use an operating system that is compatible with the target version of IAP (and, if applicable, IAG). For more information, refer to the Itential Dependencies page.
  • Hostnames: Any hostnames used by managed nodes must be DNS-resolvable.
  • Administrative Privileges: The ansible user must have administrative privileges on managed nodes.
  • SSH Access: The control node must have SSH connectivity to all managed nodes.
  • Additional CentOS 7 Requirements: Ensure that Python setuptools-2.0 is installed on any CentOS 7 managed nodes.
ⓘ Note:

Although the Itential Deployer can be used to configure nodes that use any supported operating system, it is optimized for RHEL 8 and 9.

Step 1: Download Installation Artifacts

Download the IAP binary along with any desired IAP adapters (and, if applicable, the IAG binary) 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.

Step 2: Copy Installation Artifacts into the Files Directory

First, determine what directory the Itential Deployer is installed to by using the ansible-galaxy collection list command. In the following example, the Deployer directory is /Users/<USER>/.ansible/collections/ansible_collections/itential/deployer.

Example: Determining the Deployer Directory

% ansible-galaxy collection list

# /Users/<USER>/.ansible/collections/ansible_collections
Collection        Version
----------------- -------
ansible.netcommon 4.1.0  
ansible.posix     1.5.4  
ansible.utils     2.9.0  
arista.avd        3.8.2  
arista.cvp        3.6.0  
arista.eos        6.0.0  
community.general 7.3.0  
community.mongodb 1.6.1  
itential.deployer 1.0.0  

Next, copy the files downloaded in the previous step to the files subdirectory.

Example: Copying to the Files Directory

$ cd <DEPLOYER-DIR>/files
$ cp ~/Downloads/itential-premium_2023.1.1.linux.x86_64.bin .
$ cp ~/Downloads/automation_gateway-3.198.19+2023.1.0-py3-none-any.whl .

Step 3: Create the Inventory File

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:

  • All required variables have been defined.
  • The managed node example1.host.com has been assigned to all groups, with the exception of the gateway group. As such, all components except IAG will be installed on this node.
  • The managed node example2.host.com has been assigned to the gateway group. As such, IAG will be installed on this node.
ⓘ Note:

Itential recommends that all inventories follow the best practices outlined in the Ansible documentation.

Example: Creating the Inventory File

$ mkdir -p ~/itential-inventories/dev
$ vi ~/itential-inventories/dev/hosts

Example: Inventory File (YAML Format)

all:
  vars:
    iap_release: 2023.1

  children:
    redis:
        hosts:
            example1.host.com:

    rabbitmq:
        hosts:
            example1.host.com:

    mongodb:
        hosts:
            example1.host.com:

    platform:
        hosts:
            example1.host.com:
        vars:
            iap_bin_file: itential-premium_2023.1.1.linux.x86_64.bin

    gateway:
        hosts:
            example2.host.com:
        vars:
            iag_release: 2023.1
            iag_whl_file: automation_gateway-3.227.0+2023.1.9-py3-none-any.whl

Step 4: Run the Itential Deployer

Navigate to the Deployer directory and execute the following run command.

Example: Running the Itential Deployer

$ cd <DEPLOYER-DIR>
$ ansible-playbook site.yml -i ~/itential-inventories/dev -v

Step 5: Confirm Successful Installation

After the Itential Deployer is finished running, perform the following checks on each component to confirm successful installation.

IAP and IAG

Use a web browser to navigate to the login page of your IAP/IAG servers. By default, it is located at http://<hostname>:3000 or http://<hostname>:8083, respectively. If the IAP/IAG login page is displayed, the installation was successful.

If the login page is not displayed, check that the relevant service is running on the affected server using the sudo systemctl status automation-platform or sudo systemctl status automation-gateway command, respectively. The output should look similar to the following examples.

Example Output: IAP System Status

$ sudo systemctl status automation-platform
● automation-platform.service - Itential Automation Platform Service
   Loaded: loaded (/usr/lib/systemd/system/automation-platform.service; enabled; vendor preset: disabled)
   Active: active (running) since Wed 2023-02-01 15:21:45 UTC; 21h ago
 Main PID: 177517 (Pronghorn core)
    Tasks: 203 (limit: 23501)
   Memory: 1.0G
   CGroup: /system.slice/automation-platform.service
           ├─177517 Pronghorn core
           ├─177556 Pronghorn AGManager Application
           ├─177577 Pronghorn AdminEssentials Application
           ├─177588 Pronghorn AppArtifacts Application
           ├─177606 Pronghorn AutomationCatalog Application
           ├─177622 Pronghorn AutomationStudio Application
           ├─177659 Pronghorn ConfigurationManager Application
           ├─177674 Pronghorn FormBuilder Application
           ├─177690 Pronghorn JsonForms Application
           ├─177708 Pronghorn Jst Application
           ├─177725 Pronghorn MOP Application
           ├─177738 Pronghorn OperationsManager Application
           ├─177758 Pronghorn Search Application
           ├─177784 Pronghorn Tags Application
           ├─177800 Pronghorn TemplateBuilder Application
           ├─177820 Pronghorn WorkFlowEngine Application
           ├─177833 Pronghorn WorkflowBuilder Application
           └─177860 Pronghorn local_aaa Adapter

Example Output: IAG System Status

$ sudo systemctl status automation-gateway
● automation-gateway.service - Itential Automation Gateway
   Loaded: loaded (/etc/systemd/system/automation-gateway.service; enabled; vendor preset: disabled)
   Active: active (running) since Tue 2023-01-17 16:48:29 UTC; 1 months 0 days ago
 Main PID: 94842 (automation-gate)
    Tasks: 10 (limit: 23435)
   Memory: 168.8M
   CGroup: /system.slice/automation-gateway.service
           ├─94842 /opt/automation-gateway/venv/bin/python3 /opt/automation-gateway/venv/bin/automation-gateway --properties-file=/etc/automation-gateway/propert>
           └─94844 /opt/automation-gateway/venv/bin/python3 /opt/automation-gateway/venv/bin/automation-gateway --properties-file=/etc/automation-gateway/propert>

MongoDB, Redis, and RabbitMQ

From the command line of each dependency server, use the sudo systemctl status <service> command to confirm that the relevant service is running. When executing the command, replace <service> with one of the following:

  • MongoDB: mongod
  • Redis: redis
  • RabbitMQ: rabbitmq-server

The output should look similar to the following examples.

Example Output: MongoDB Status

$ sudo systemctl status mongod
● mongod.service - MongoDB Database Server
     Loaded: loaded (/usr/lib/systemd/system/mongod.service; enabled; preset: disabled)
     Active: active (running) since Thu 2023-06-22 04:49:56 CST; 20h ago
       Docs: https://docs.mongodb.org/manual
   Main PID: 54594 (mongod)
     Memory: 156.7M
        CPU: 46.078s
     CGroup: /system.slice/mongod.service
             └─54594 /usr/bin/mongod -f /etc/mongod.conf

Example Output: Redis Status

$ sudo systemctl status redis
● redis.service - Redis persistent key-value database
     Loaded: loaded (/usr/lib/systemd/system/redis.service; enabled; preset: disabled)
    Drop-In: /etc/systemd/system/redis.service.d
             └─limit.conf
     Active: active (running) since Thu 2023-06-22 04:47:39 CST; 20h ago
   Main PID: 15723 (redis-server)
     Status: "Ready to accept connections"
      Tasks: 5 (limit: 22862)
     Memory: 9.7M
        CPU: 13.409s
     CGroup: /system.slice/redis.service
             └─15723 "/usr/bin/redis-server 127.0.0.1:6379"

Example Output: RabbitMQ Status

$ sudo systemctl status rabbitmq-server
● rabbitmq-server.service - RabbitMQ broker
     Loaded: loaded (/usr/lib/systemd/system/rabbitmq-server.service; enabled; preset: disabled)
    Drop-In: /etc/systemd/system/rabbitmq-server.service.d
             └─limits.conf
     Active: active (running) since Thu 2023-06-22 04:48:15 CST; 20h ago
   Main PID: 24244 (beam.smp)
      Tasks: 25 (limit: 22862)
     Memory: 138.6M
        CPU: 1min 28.641s
     CGroup: /system.slice/rabbitmq-server.service
             ├─24244 /usr/lib64/erlang/erts-13.2.2.1/bin/beam.smp -W w -MBas ageffcbf -MHas ageffcbf -MBlmbcs 512 -MHlmbcs 512 -MMmcs 30 -pc uni>
             ├─24257 erl_child_setup 64000
             ├─24284 /usr/lib64/erlang/erts-13.2.2.1/bin/epmd -daemon
             ├─24307 /usr/lib64/erlang/erts-13.2.2.1/bin/inet_gethost 4
             ├─24308 /usr/lib64/erlang/erts-13.2.2.1/bin/inet_gethost 4
             └─24311 /bin/sh -s rabbit_disk_monitor

Advanced Deployment Example

The information provided in the previous sections is sufficient for simple, non-production Itential environments. However, production environments are typically more complex, requiring:

  • Additional variables to be defined in the relevant inventory file.
  • Ports to be opened to allow for communication between systems.

This section details a production configuration that accounts for distribution of components across multiple systems, high availability (HA), and security hardening, among other considerations.

ⓘ Note:

Though the example provided in this section is typical of many production environments, it is not intended to be a universal configuration. Rather, it is provided to showcase the versatility of the Itential Deployer. Configurations should be tailored to the needs of your own environment.

Additional Variables

Each component installed by the Itential Deployer can be granularly configured by defining additional variables in the relevant inventory file. These additional variables are detailed in the following tables.

MongoDB Variables

Variable Group Type Description Example
mongodb_replication all String Designates whether or not a MongoDB replica set is created from all managed nodes assigned to the mongodb group. true
false
mongodb_auth all Boolean Designates whether or not MongoDB servers require authentication via username and password for connections. true
false
mongodb_tls all Boolean Designates whether or not MongoDB servers secure their communications with TLS encryption. true
false
mongo_user_itential_password all String The password of the MongoDB itential user.
mongo_auth_keyfile_source all String The name of the .pem key file to be used for communication between members of the MongoDB replica set. This must be provided; it is not generated by the Itential Deployer. This is only required when mongodb_replication and mongodb_auth are set to true. mongo-replicaset-key.pem
mongo_cert_keyfile_source all String The name of the .pem key file that contains the TLS certificate and key to be used on MongoDB servers. This must be provided; it is not generated by the Itential Deployer. This is only required when mongodb_tls is set to true. mongodb.pem
mongo_root_ca_file_source all String The name of the .pem key file obtained from a certificate authority that contains the root certificate chain. This must be provided; it is not generated by the Itential Deployer. This is only required when mongodb_tls is set to true. rootCA.pem

Redis Variables

Variable Group Type Description Example
redis_replication all Boolean Designates whether or not a Redis cluster is created from all managed nodes assigned to the redis group. If set to true, a cluster is created and Redis Sentinel is used to provide high availability (HA) monitoring. true
false
redis_auth all Boolean Designates whether or not Redis servers require authentication via username and password for connections. true
false

RabbitMQ Variables

Variable Group Type Description Example
rabbitmq_cluster all Boolean Designates whether or not a RabbitMQ cluster is created from all managed nodes assigned to the rabbitmq group. true
false
rabbitmq_ssl all Boolean Designates whether or not RabbitMQ nodes secure their communications with TLS encryption. true
false

Default Dependency User Accounts

The following user accounts are created during the installation of their respective dependencies. Please contact your Itential Professional Services representative for the default passwords of these accounts.

ⓘ Note:

The passwords of these accounts should be changed from their default values according to security best practices.

Default MongoDB Users

Username Description
admin The administrative account of MongoDB.
itential The account used by IAP to connect to MongoDB.
localaaa The account used to log in to MongoDB if LDAP is not configured.

Default Redis Users

Username Description Redis Permissions
admin The Redis administrative account. allkeys allchannels allcommands
itential The account used by IAP to connect to Redis. allkeys allchannels allcommands -asking -cluster -readonly -readwrite -bgrewriteaof -bgsave -failover -flushall -flushdb -psync -replconf -replicaof -save -shutdown -sync
repluser The account used by Redis to perform replication within a Redis cluster. allchannels +psync +replconf +ping
sentineluser The account used by Redis Sentinel to connect to Redis. allchannels +multi +slaveof +ping +exec +subscribe +config|rewrite +role +publish +info +client|setname +client|kill +script|kill

Default Redis Sentinel Users

Username Description Redis Sentinel Permissions
admin The Redis Sentinel administrative account. ~* &* +@all
sentineluser The account used by Redis Sentinel to connect to Redis. &* -@all +auth +client|getname +client|id +client|setname +command +hello +ping +role +sentinel|is-master-down-by-addr +sentinel|get-master-addr-by-name +sentinel|master +sentinel|myid +sentinel|replicas +sentinel|sentinels

Default RabbitMQ Users

Username Description RabbitMQ User Tags
admin The administrative account of RabbitMQ. administrator
itential The account used by IAP to connect to RabbitMQ. monitoring

Additional Ports

In environments where components are installed across multiple systems, the following network traffic flows must be permitted.

Source Application Destination Application Port Description
IAP MongoDB 27017 Allows IAP to connect to MongoDB.
IAP RabbitMQ 5672 Allows IAP to connect to RabbitMQ.
IAP Redis 6379 Allows IAP to connect to Redis.
IAP Redis Sentinel 26379 Allows IAP to connect to Redis Sentinel.
MongoDB MongoDB 27017 Allows database replication between MongoDB servers.
RabbitMQ RabbitMQ 25672 Allows clustering between RabbitMQ nodes.
RabbitMQ RabbitMQ 4369 Allows the Erlang Port Mapping Daemon (EPMD) present on each RabbitMQ node to gather information about other RabbitMQ nodes.
Redis Redis 6379 Allows replication between Redis servers.
Redis Redis Sentinel 26379 Allows Redis to communicate with Redis Sentinel to monitor the health of other Redis servers.

Advanced Inventory File Example

The file example below differs from that given in the Deploying Itential section in the following ways:

  • IAP components are installed on a wider selection of dedicated managed nodes.
  • High availability options are configured for all components that support them.
  • Security hardening options, such as requiring authentication for communications and encrypting communications with TLS, are configured for all components that support them.

Example: Advanced Inventory File (INI Format)

[all:vars]
iap_release=2023.1

mongodb_replication=true
mongodb_auth=true
mongodb_tls=true
mongo_user_itential_password=*****
mongo_auth_keyfile_source=mongo-replicaset-key.pem
mongo_cert_keyfile_source=mongodb.pem
mongo_root_ca_file_source=rootCA.pem

redis_replication=true
redis_auth=true

rabbitmq_cluster=true
rabbitmq_ssl=true

[redis]
redis1.host.com
redis2.host.com
redis3.host.com

[rabbitmq]
rabbitmq1.host.com
rabbitmq2.host.com
rabbitmq3.host.com

[mongodb]
mongodb1.host.com
mongodb2.host.com
mongodb3.host.com

[mongodb_arbiter]

[vault]

[platform]
iap1.host.com
iap2.host.com

[platform:vars]
iap_bin_file=itential-premium_2023.1.0.linux.x86_64.bin

[gateway]
iag1.host.com

[gateway:vars]
iag_release=2023.1
iag_whl_file=automation_gateway-3.227.0+2023.1.0-py3-none-any.whl

Upgrading Itential Deployments

Instances of IAP and IAG that are created by the Itential Deployer also rely on the Deployer for upgrades. To upgrade IAP or IAG to a new maintenance release:

  1. Download the binary files for the target maintenance release from the Itential Nexus Repository. The files downloaded in this step should align with those downloaded during the initial deployment process. If you are unsure which files to download, contact your Itential Professional Services representative.
  2. Copy the new binaries to the Itential Deployer files subdirectory.
  3. Update the relevant variables in your inventory file to reference the new binaries. For example, if upgrading IAG, edit the value of iag_whl_file accordingly.
  4. Run the following commands to upgrade IAP or IAG, respectively:

IAP Upgrade Command

$ cd <DEPLOYER-DIR>
$ ansible-playbook patch-iap.yml -i <inventory>

IAG Upgrade Command

$ cd <DEPLOYER-DIR>
$ ansible-playbook patch-iag.yml -i <inventory>
ⓘ Note:

By default, MongoDB backups are created during the IAP upgrade process. To disable them, add mongo_backup to your inventory file as a platform group variable and assign it a value of false.

⚠ Warning:

The Itential Deployer only supports maintenance release upgrades. For assistance with upgrading IAP or IAG to a new feature release, contact your Itential Professional Services representative.

Upgrading the Itential Deployer

To upgrade the Itential Deployer to the latest version, execute the following command on your control node:

ansible-galaxy collection install itential.deployer -U
⚠ Warning:

Any files stored in the Deployer directory will be deleted when the Deployer is upgraded.

Offline Upgrades

If your control node does not have Internet connectivity, download the latest version of the Itential Deployer via another system, copy it to your control node, and execute the following command:

ansible-galaxy collection install itential-deployer-<VERSION>.tar.gz -U

Further Reading

For a complete list of actions executed by the Itential Deployer during installation, refer to the Itential Deployer Manual Steps document.


Was this article helpful?

Changing your password will log you out immediately. Use the new password to log back in.
First name must have atleast 2 characters. Numbers and special characters are not allowed.
Last name must have atleast 1 characters. Numbers and special characters are not allowed.
Enter a valid email
Enter a valid password
Your profile has been successfully updated.