Running Containers

Itential Platform Containerization

While Itential Platform can be deployed using a traditional server architecture, in which each server runs a single instance of Itential Platform, many benefits arise from its containerization:

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

• The prerequisites for running Itential Platform containers.
• How to run Itential Platform containers.
• How to configure Itential Platform containers.

Prerequisites

Before proceeding, the following prerequisites must be met:

Container Management Platform

Itential Platform 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

Itential Platform 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).

Logging into the Itential Docker Repository

Before you can begin working with Itential Platform 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

...in which:

Pulling Container Images

To download images from the container registry, issue a Docker Pull command:

docker pull 497639811223.dkr.ecr.us-east-2.amazonaws.com/<bundle_name>:<tag>

...in which:

Starting an Itential Platform Container

To start an Itential Platform container, issue the following command:

docker run -d -p 3000:3000 -p 3443:3443 \
    -e ITENTIAL_ENCRYPTION_KEY="encryption_key" \
    497639811223.dkr.ecr.us-east-2.amazonaws.com/<bundle_name>:<tag>

Environment Variables

Itential Platform configuration, including profile properties and service config properties can be set using environment variables starting in Platform 6.

For a list of environment variables in Itential Platform, see Platform Environment Variables.

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

docker run -d -p 3000:3000 -p 3443:3443 \
  -e ITENTIAL_SERVER_ID="server1" \
  -e ITENTIAL_ENCRYPTION_KEY="encryption_key" \
  497639811223.dkr.ecr.us-east-2.amazonaws.com/<bundle_name>:<tag>

Encryption Keys

Starting in Platform 6, an encryption key is required to start the Itential Platform. For information on how to generate an encryption key, see Create the Encryption Key.

Once a key is generated, you can start the container with the newly created encryption key by passing in the ITENTIAL_ENCRYPTION_KEY environment variable. For example:

docker run -d -p 3000:3000 -p 3443:3443 \
  -e ITENTIAL_ENCRYPTION_KEY="encryption_key" \
  497639811223.dkr.ecr.us-east-2.amazonaws.com/<bundle_name>:<tag>

Encrypting Values

To generate an encrypted value in Platform 6 using containers, run the following command:

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

...in which <password_value> is the plaintext password to be encrypted.

Common Configuration Tasks

The following changes are common in production environments.

Mounting Itential Platform Logs to the Host OS

By default, any logs stored by Itential Platform 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. The default log_directory within the container is /var/log/itential/platform, but this can be modified via configuration.

   mkdir -p ./itential/platform/logs
   

2. Use a bind mount to mount the directory into your Itential Platform container.

   docker run -d -p 3000:3000 -p 3443:3443 \\
     -e ITENTIAL_ENCRYPTION_KEY="encryption_key" \\
     --mount type=bind,source=./itential/platform/logs,target=/var/log/itential/platform \\
     497639811223.dkr.ecr.us-east-2.amazonaws.com/<bundle_name>:<tag>
   

Adding SSH Keys and Certificates to Itential Platform

To add custom SSH keys and certificates to Itential Platform:

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 Itential Platform here.

   mkdir -p ./itential/platform/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
   chmod 0400 custom_key.cert
   

3. Use a bind mount to mount the directory containing the keys into your Itential Platform container and set the ITENTIAL_WEBSERVER_HTTPS_CERT and ITENTIAL_WEBSERVER_HTTPS_KEY environment variables to specify the cert and key locations. For example:

   docker run -d -p 3000:3000 -p 3443:3443 \\
     --mount type=bind,source=./itential/platform/keys,target=/opt/itential/platform/keys \\
     -e ITENTIAL_ENCRYPTION_KEY="encryption_key" \\
     -e ITENTIAL_WEBSERVER_HTTPS_CERT="/opt/itential/platform/keys/custom_key.cert" \\
     -e ITENTIAL_WEBSERVER_HTTPS_KEY="/opt/itential/platform/keys/custom_key.key" \\
     497639811223.dkr.ecr.us-east-2.amazonaws.com/<bundle_name>:<tag>
   

Implementing High Availability (HA) for Itential Platform

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

• Each Itential Platform container must be bound to a unique port.
• Each Itential Platform instance must be connected to the same Mongo and Redis in an HA environment.

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

# IAP_instance1
local_port_node_1_http=3000
local_port_node_1_https=3443
docker run -d -p $local_port_node_1_http:3000 -p $local_port_node_1_https:3443 \
  -e ITENTIAL_ENCRYPTION_KEY="encryption_key" \
  -e ITENTIAL_MONGO_URL=mongodb://host.docker.internal:27017 \
  -e ITENTIAL_REDIS_HOST=host.docker.internal \
  --name IAP_instance1
  497639811223.dkr.ecr.us-east-2.amazonaws.com/<bundle_name>:<tag>

# IAP_instance2
local_port_node_2_http=3001
local_port_node_2_https=3444
docker run -d -p $local_port_node_2_http:3000 -p $local_port_node_2_https:3443 \
  -e ITENTIAL_ENCRYPTION_KEY="encryption_key" \
  -e ITENTIAL_MONGO_URL=mongodb://host.docker.internal:27017 \
  -e ITENTIAL_REDIS_HOST=host.docker.internal \
  --name IAP_instance2
  497639811223.dkr.ecr.us-east-2.amazonaws.com/<bundle_name>:<tag>

Adding Adapters and Custom Applications to Itential Platform

To add open source adapters and custom applications to Itential Platform:

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 Itential Platform to this directory. The same logic would apply to custom apps, just in a different directory.

   mkdir -p ./itential/platform/custom_adapters_apps/@itentialopensource
   cd ./itential/platform/custom_adapters_apps/@itentialopensource
   
   # Clone your open source adapter / application here. Then, install it:
   
   cd open_source_adapter
   npm install --install-strategy=nested --prod
   

2. Use a bind mount to mount the directory into your Itential Platform container. Modify the source path to be relative to where this is being run.

   docker run -d -p 3000:3000 -p 3443:3443 \\
   -e ITENTIAL_ENCRYPTION_KEY="encryption_key" \\
   -e ITENTIAL_SERVICE_DIRECTORY="/opt/itential/platform/custom" \\
   --mount type=bind,source=./itential/platform/custom_adapters_apps/@itentialopensource,target=/opt/itential/platform/custom \\
   497639811223.dkr.ecr.us-east-2.amazonaws.com/<bundle_name>:<tag>
   

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.