IAP Container Image
  • 24 Oct 2023
  • Dark
    Light
  • PDF

IAP Container Image

  • Dark
    Light
  • PDF

Article Summary

IAP Containerization

While Itential Automation Platform (IAP) can be deployed using a traditional server architecture, in which each server runs a single instance of IAP, there is also the option and benefit of containerizing IAP.

Benefit Description
Performance and Horizontal Scaling Additional IAP containers can be created and destroyed according to workload demands.
Deployment Automation IAP containers can be deployed dynamically without manual intervention.
Fault Tolerance IAP containers can substitute for one another in the event of a container failure.
Blue-Green Deployment IAP environment upgrades can be completed with minimum production downtime.
Hybrid Deployments IAP containers can integrate with both on-premise and cloud-based resources seamlessly.

To facilitate containerization, Itential provides pre-made images of IAP. In this guide, you will learn:

  • The prerequisites for running IAP containers.
  • How to run IAP containers.
  • How to configure IAP containers.

Prerequisites

Before proceeding, the following prerequisites must be met.

Container Management Platform

IAP images are compliant with Open Container Initiative (OCI) specifications; however, this guide assumes the use of Docker. Specific instruction for using technologies that manage OCI containers, such as Docker Compose and Kubernetes, falls outside the scope of this guide.

Docker Repository Access

IAP images are hosted on the Itential Docker repository. Contact your Itential Account Manager to obtain the credential information needed to download images from this repository, including your:

  • Access key ID
  • Secret access key
  • Bundle name

AWS Command Line Interface

Amazon Web Services Command Line Interface (AWS CLI) must be installed on your host operating system (OS).

IAP Dependencies

The following IAP dependencies must be running in your environment. This guide assumes these dependencies will be hosted via containers. However, dependencies may also be hosted via stand-alone servers, as they would be in a non-containerized IAP application.

⚠ Warning

The dependency configurations provided below will work with the default configuration of the IAP container, but they are not secure. Itential recommends that configuration changes are made to improve the security of the dependencies before they are used in a production environment. For more information, refer to the documentation of each dependency image; links are provided in the relevant sections.

MongoDB

To work with the default configuration of the IAP container, MongoDB containers must be configured as follows.

Setting Value Description
Container Name mongodb The name of the container.
Authentication None The MONGO_INITDB_ROOT_USERNAME and MONGO_INITDB_ROOT_PASSWORD environment variables are not set for the container.
Exposed Ports 27017 The port the IAP container will use to communicate with the MongoDB container.
Docker Network The same Docker network as the IAP container. All containers must be on the same Docker network to allow communication.

RabbitMQ

To work with the default configuration of the IAP container, RabbitMQ containers must be configured as follows.

Setting Value Description
Container Name rabbitmq The name of the container.
Authentication None The RABBITMQ_DEFAULT_USER and RABBITMQ_DEFAULT_PASS environment variables are not set for container.
Exposed Ports 5672
15672
The ports the IAP container will use to communicate with the RabbitMQ container.
Docker Network The same Docker network as the IAP container. All containers must be on the same Docker network to allow communication.

Redis

To work with the default configuration of the IAP container, Redis containers must be configured as follows.

Setting Value Description
Container Name redis The name of the container.
Authentication None A password is not set via configuration file for the Redis container.
Exposed Ports 6379 The port the IAP container will use to communicate with the Redis container.
Docker Network The same Docker network as the IAP container. All containers must be on the same Docker network to allow communication.

Logging into the Itential Docker Repository

Before you can begin working with IAP containers, you must log into the Itential Docker repository. To do so, issue the following command.

export AWS_ACCESS_KEY_ID=<access_key_id>
export AWS_SECRET_ACCESS_KEY=<secret_access_key>

aws ecr get-login-password --region us-east-2 | docker login --username AWS --password-stdin 497639811223.dkr.ecr.us-east-2.amazonaws.com/automation-platform-<bundle_name>
Parameter Description
<access_key_id> The AWS access key ID provided by your Itential Account Manager.
<secret_access_key> The AWS secret access key provided by your Itential Account Manager.
<bundle_name> The bundle name provided by your Itential Account Manager.

Starting an IAP Container

To start an IAP container, issue the following command.

docker run --name <some_iap> -d --network <some_network> \
-p <host_machine_ip>:<host_port_number>:<container_port_number>/tcp \
497639811223.dkr.ecr.us-east-2.amazonaws.com/automation-platform-<bundle_name>:<tag>
Parameter Description
<some_iap> The desired name of the container.
<some_network> The Docker network to run the container in. If this network does not already exist, create it using the docker network create <some_network> command.
<host_machine_ip> The IP address of the machine running the container daemon.
<host_port_number>
<container_port_number>
The host and container ports that should be bound to each other, respectively. By default:
- If SSL has been configured, both properties should be set to 3443.
- Otherwise, both properties should be set to 3000.
<bundle_name> The bundle name provided by your Itential Account Manager.
<tag> The desired version of IAP to run. This can also be used to upgrade the IAP container.

Refer to the Examples section of this document for additional information.

⚠ Warning

Referring to a feature release version of IAP (e.g., <bundle_name>:2023.1) will result in the latest maintenance build of that version being run. Itential recommends using a specific maintenance release version (e.g., <bundle_name>:2023.1.2) in production environments.

Environment Variables

The following environment variables can be used to alter the startup behavior of the IAP container.

Variable Type Description Example
IAP_CUSTOM_PROPERTIES String Sets the configuration mode of the IAP container. A "true" value will enable Custom Properties mode, while a "false" value will enable Override mode. "false"
WAIT_FOR String If set, the IAP container will wait until a specified service is available before starting. The service is defined in the container_name:port syntax. "mongodb:27017"
WAIT_FOR_DELAY Integer Specifies how long the IAP container will wait, in seconds, between availability checks against the service defined in the WAIT_FOR environment variable. 120
WAIT_FOR_TIMEOUT Integer Specifies a timeout, in seconds, for availability checks against the service defined in the WAIT_FOR environment variable. 300

To set an environment variable, use the -e flag of the docker run command. For example:

docker run --name <some_iap> -d --network <some_network> \
-p <host_machine_ip>:<host_port_number>:<container_port_number>/tcp \
-e WAIT_FOR:"mongodb:27017" \
497639811223.dkr.ecr.us-east-2.amazonaws.com/automation-platform-<bundle_name>:<tag>

Configuring the IAP Container

Configuration of the IAP container can be customized via the following files.

Configuration File Mount Location Description
RabbitMQ /opt/itential/automation-platform/config/custom-rabbitmq.json Defines custom RabbitMQ properties.
Redis /opt/itential/automation-platform/config/custom-redis.json Defines custom Redis properties.
MongoDB /opt/itential/automation-platform/config/custom-properties.json Defines custom MongoDB properties.
IAP Profile /opt/itential/automation-platform/config/custom-profile.json Defines custom IAP profile properties.
IAP Service Configuration /opt/itential/automation-platform/config/custom-service-configs.json Defines custom IAP service configuration properties.

To use a configuration file, mount it to its corresponding mount location with a bind mount. For example:

docker run --name <some_iap> -d --network <some_network> \
-p <host_machine_ip>:<host_port_number>:<container_port_number>/tcp \
--mount type=bind,source=./volumes/iap/config/custom-properties.json,target=/opt/itential/automation-platform/config/custom-properties.json \
497639811223.dkr.ecr.us-east-2.amazonaws.com/automation-platform-<bundle_name>:<tag>
ⓘ Note

For more information about configuring IAP, refer to the Configuration section of the IAP documentation.

Configuration Modes

How configuration files are applied to the IAP container is dependent on what configuration mode the container is set to. Two configuration modes are available:

  • Override Mode (default): Enabled if the IAP_CUSTOM_PROPERTIES environment variable is set to "false" or is not present. Any configuration file mounted to the /opt/itential/automation-platform/config directory will override the corresponding default configuration file (located in the /opt/itential/automation-platform/defaults directory).
  • Custom Properties Mode: Enabled if the IAP_CUSTOM_PROPERTIES environment variable is set to "true". The image will ignore any default configuration files. As such, all custom configuration files must be present in the /opt/itential/automation-platform/config directory for IAP to start.

Common Configuration Tasks

Though an IAP application can function without a custom configuration of its component containers, the following changes are common in production environments.

Enabling MongoDB Persistence

By default, MongoDB containers will delete their database when they are stopped. To ensure the database persists when a MongoDB container is stopped or restarted:

  1. Create a mount directory on the host OS (the OS that your container daemon is running on). This is where the database is stored.

    mkdir -p ./volumes/mongodb/data
    
  2. Use a bind mount to mount the directory into your MongoDB container (denoted below as <some_mongo>).

    docker run -d --network <some_network> --name <some_mongo> \
    -p <host_machine_ip>:<host_port_number>:<container_port_number>/tcp \
    --mount type=bind,source=./volumes/mongodb/data,target=/data/db \
    mongo:5.0
    

Mounting IAP Logs to the Host OS

By default, any logs stored by IAP containers are lost when the containers and their volumes are removed. To ensure log persistence:

  1. Create a mount directory on the host OS (the OS that your container daemon is running on). This is where the logs are stored.

    mkdir -p ./volumes/iap/logs
    
  2. Use a bind mount to mount the directory into your IAP container.

    docker run --name <some_iap> -d --network <some_network> \
    -p <host_machine_ip>:<host_port_number>:<container_port_number>/tcp \
    --mount type=bind,source=./volumes/iap/logs,target=/opt/itential/logs \
    497639811223.dkr.ecr.us-east-2.amazonaws.com/automation-platform-<bundle_name>:<tag>
    

Adding SSH Keys and Certificates to IAP

To add custom SSH keys and certificates to IAP:

  1. Create a mount directory on the host OS (the OS that your container daemon is running on). Place any SSH keys and certificates you would like to add to IAP here.

    mkdir -p ./volumes/iap/keys
    
  2. Ensure all SSH keys and certificates have the proper permissions. The file owner should only have read access; all others should have no access (numeric permission 0400).

    chmod 0400 custom_key.key
    
  3. Create another mount directory on the host OS, this time to house a custom IAP Profile configuration file. Create the configuration file, custom-profile.json, here.

    mkdir -p ./volumes/iap/config
    cd ./volumes/iap/config
    touch custom-profile.json
    
  4. Update the custom-profile.json file to reference your custom SSH keys and certificates.

    {
      "expressProps": {
        "description": "Express Server",
        "cacheControl": true,
        "timeout": 600000,
        "express_http": {
          "enable": false,
          "port": 3000
        },
        "express_https": {
          "enable": true,
          "port": 3443,
          "key": "/opt/itential/keys/custom_key.key",
          "cert": "/opt/itential/keys/custom_key.cert",
          "secureProtocol": "TLSv1_2_method",
          "ciphers": "ECDHE-RSA-AES128-GCM-SHA256",
          "client_reneg_limit": 1,
          "client_reneg_window": 600
        }
      }
    }
    
  5. Use bind mounts to mount both directories into your IAP container.

    docker run --name <some_iap> -d --network <some_network> \
    -p <host_machine_ip>:<host_port_number>:<container_port_number>/tcp \
    --mount type=bind,source=./volumes/iap/keys,target=/opt/itential/keys \
    --mount type=bind,source=./volumes/iap/config/custom-profile.json,target=/opt/itential/automation-platform/config/custom-profile.json \
    497639811223.dkr.ecr.us-east-2.amazonaws.com/automation-platform-<bundle_name>:<tag>
    

Implementing High Availability (HA) for IAP

Multiple IAP containers can run in a single application to provide HA. When using such a setup:

  • Each IAP container must be bound to a unique port.
  • IAP containers must be configured to start with staggered timing. This can be accomplished using the WAIT_FOR and WAIT_FOR_TIMEOUT environment variables.

For example, an application containing two IAP containers might be configured as follows:

# IAP_instance1
docker run --name IAP_instance1 -d --network <some_network> \
-p 127.0.0.1:3000:3000/tcp \
497639811223.dkr.ecr.us-east-2.amazonaws.com/automation-platform-<bundle_name>:<tag>

# IAP_instance2
docker run --name IAP_instance2 -d --network <some_network> \
-p 127.0.0.1:3001:3001/tcp \
-e WAIT_FOR:"IAP_instance1" \
-e WAIT_FOR_DELAY:60 \
-e WAIT_FOR_TIMEOUT:300 \
497639811223.dkr.ecr.us-east-2.amazonaws.com/automation-platform-<bundle_name>:<tag>

Adding Open Source Adapters and Applications to IAP

To add open source adapters and applications to IAP:

  1. Create a mount directory on the host OS (the OS that your container daemon is running on). Install any open source adapters or applications you would like to add to IAP to this directory.

    mkdir -p ./volumes/iap/opensource_adapters_apps/@itentialopensource
    cd ./volumes/iap/opensource_adapters_apps/@itentialopensource
    
    # Clone your open source adapter / application here. Then, install it:
    
    cd open_source_adapter
    npm install --legacy-bundling --prod
    
  2. Use a bind mount to mount the directory into your IAP container.

    docker run --name <some_iap> -d --network <some_network> \
    -p <host_machine_ip>:<host_port_number>:<container_port_number>/tcp \
    --mount type=bind,source=./volumes/iap/opensource_adapters_apps/@itentialopensource,target=/opt/itential/automation-platform/node_modules/@itentialopensource \
    497639811223.dkr.ecr.us-east-2.amazonaws.com/automation-platform-<bundle_name>:<tag>
    

Adding Custom Adapters and Applications to IAP

To add custom adapters and applications to IAP:

  1. Create a mount directory on the host OS (the OS that your container daemon is running on). Install any custom adapters or applications you would like to add to IAP to this directory.

    mkdir -p ./volumes/iap/automation-platform-custom
    cd ./volumes/iap/automation-platform-custom
    
    # Clone your custom adapter / application here. Then, install it:
    
    cd custom_adapter
    npm install --legacy-bundling --prod
    
  2. Use a bind mount to mount the directory into your IAP container.

    docker run --name <some_iap> -d --network <some_network> \
    -p <host_machine_ip>:<host_port_number>:<container_port_number>/tcp \
    --mount type=bind,source=./volumes/iap/automation-platform-custom,target=/opt/custom/node_modules \
    497639811223.dkr.ecr.us-east-2.amazonaws.com/automation-platform-<bundle_name>:<tag>
    

Encrypting Passwords

By default, some configuration files may contain passwords written in plaintext. To generate an encrypted password value for use in such files, run the following command to use the IAP Encrypt tool. The <password_value> is the plaintext password to be encrypted.

docker run -it --entrypoint node 497639811223.dkr.ecr.us-east-2.amazonaws.com/automation-platform-<bundle_name>:<tag> \ 
/opt/itential/automation-platform/node_modules/@itential/pronghorn-core/utils/encrypt.js <password_value>

Examples

The following examples are provided to address potential deployment scenarios.

⚠ Warning

These examples are provided only to provide further context. They may not translate to your exact needs or environment as-is.

Local Development Environment

This example details a series of commands that might be used to start a local development environment (LDE) that is entirely container-based.

# Creates the Docker network
docker network create itential-network

# Starts the MongoDB container
docker run --name mongodb -d --network itential-network \
-p 127.0.0.1:27017:27017/tcp \
mongo:5.0.0

# Starts the Redis container
docker run --name redis -d --network itential-network \
-p 127.0.0.1:6379:6379/tcp \
redis:7.0.11

# Starts the RabbitMQ container
docker run --name rabbitmq -d --network itential-network \
-p 127.0.0.1:5672:5672/tcp \
rabbitmq:3.11-management

#Starts IAP container
docker run --name iap_base_2023_1 -d --network itential-network \
-p 127.0.0.1:3000:3000/tcp \
-e WAIT_FOR:"mongodb:27017" \
497639811223.dkr.ecr.us-east-2.amazonaws.com/automation-platform-base:2023.1

Further Reading

Example Docker Compose files can be found in the Itential Open Source GitLab repository. Documentation for these examples is provided in the README files located throughout the project.


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.