IAG Container Image
  • 05 Feb 2024
  • Dark
    Light
  • PDF

IAG Container Image

  • Dark
    Light
  • PDF

Article Summary

IAG Containerization

Itential Automation Gateway (IAG) can now be deployed using a containerized method of deployment.

Prerequisites

Before proceeding, the following prerequisites must be met:

  • OCI compliance
  • Docker repository access
  • AWS CLI on the host OS

Container Management Platform

IAG 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, falls outside the scope of this guide.

Docker Repository Access

IAG 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

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 IAG containers, you must log into the Itential Docker repository. To do so, issue the following command.

export AWS_ACCESS_KEY=<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-gateway
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.

Starting an IAG Container

To start an IAG container, issue the following commands.

Create Docker Network

docker network create itential-network

Start Container

docker run --name iag_2023_1 -d --network itential-network -p 127.0.0.1:8083:8083/tcp 497639811223.dkr.ecr.us-east-2.amazonaws.com/automation-gateway:2023.1

IAG Dependencies

The following IAG 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 IAG application.

IAG and IAP must be on the same docker network for each application to communicate with the other.

Using the IAG Image

To start an IAG container, issue the following command:

docker run --name some_IAG -d --network some_network \
-p host_machine_ip:host_port_number:container_port_number/tcp \
497639811223.dkr.ecr.us-east-2.amazonaws.com/automation-gateway:<tag>
Parameter Description
some_IAG The desired name of the container.
some_network The Docker network to run the container in. If this network does not already exist, it will need to be created using the docker network create some_network command.
tag The desired version of IAG to run. This can also be used to upgrade the IAG image.

The host_machine_ip, host_port_number and container_port_number fields should be added and should match the IAP container docs. The IAG port is 8083.

⚠ Warning

Referring to a feature release version of IAG (e.g., 'automation-gateway:2023.1') will result in the latest maintenance release of that version being run. As such, Itential recommends using a specific maintenance release version (e.g., 'automation-gateway:2023.1.2') in production environments.

Default IAG Setup

Below is a list of the default environment settings for the IAG image.

Setting Default
automation_gateway_ansible_enabled false
automation_gateway_data_file sqlite:////opt/automation-gateway/data/automation-gateway.db
automation_gateway_audit_db_file sqlite:////opt/automation-gateway/data/automation-gateway_audit.db
automation_gateway_exec_history_db_file sqlite:////opt/automation-gateway/data/automation-gateway_exec_history.db

Setup IAG Database Persistence

The default behavior of the IAG container is to reset the IAG database once the container is stopped using the docker-compose down command.

For the IAG database to persist so that it is still available if the container is restarted or stopped, a volume needs to be setup to host the database on the host machine.

  1. Create the mount location on the host machine.

    mkdir -p ./volumes/iag/data
    
  2. Setup the mount reference in the docker-compose file.

    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/iag/data,target=/opt/itential/automation-gateway/data \
    497639811223.dkr.ecr.us-east-2.amazonaws.com/automation-gateway:<tag>
    

Running Scripts to Install Packages and Configure IAG

Any scripts mounted to the /docker-entrypoint-init-iag.d/* location will run the first time the IAG image is started. The scripts will only run the first time the IAG image is started and only scripts with commands that do not require root access will work.

If you need to customize the container by making install packages that require root access then you will have to build a new image using a Dockerfile to install the packages.

Building a Customized IAG Image

The base IAG image does not have root access. Therefore scripts that run by being mounted to the /docker-entrypoint-init-iag.d/* location cannot run if they require root access.
If you need to customize the container by making changes that require root access you will have to create a Dockerfile that builds a new image that adds those changes.

Below is a Dockerfile example that builds a new IAG image that adds the git package to it.

## base the image on the automation gateway image
##
FROM 497639811223.dkr.ecr.us-east-2.amazonaws.com/automation-gateway:<tag>
USER root
RUN mkdir -p /opt/ansible/logs && \
chown itential:itential /opt/ansible/logs && \
apk add git
USER itential

Adding Custom Ansible and Terraform Scripts to the Container

Custom Ansible and Terraform scripts can be loaded in IAG using the /opt/custom mount point.

  1. Create the mount locations on the host machine.

    mkdir -p ./volumes/iag/automation-gateway-custom
    mkdir -p ./volumes/iag/install_scripts
    
  2. Create the following folder structure based on the type of files being added in the ./volumes/iag/install_scripts location.

    - ansible
      - collections
      - playbooks
      - roles
    - terraform
    
  3. Create a script to install Ansible and Terraform.

    cd ./volumes/iag/install_scripts
    touch install_scripts.sh
    
  4. Open the install_scripts.sh file and add the code to install Ansible and Terraform.

    Example Code

    echo "Installing Ansible using pip"
    pip install ansible-core==2.15
    echo "Installing Terraform"
    wget https://releases.hashicorp.com/terraform/1.5.4/terraform_1.5.4_linux_386.zip
    unzip terraform_1.5.4_linux_386.zip
    rm terraform_1.5.4_linux_386.zip
    mv ./terraform ~/.local/bin
    

    Only non-root commands can be used in this file. If you need to run root command then create a new image and install the script in the dockerFile.

  5. Update the script to have execute rights.

    chmod u+rwx ./volumes/iag/install_scripts/install_scripts.sh
    
  6. Setup the mount references and environment variables for the Ansible, Terraform file locations.

    docker run --name some_IAG -d --network some_network \
    -p host_machine_ip:host_port_number:container_port_number/tcp \
    -e automation_gateway_ansible_enabled='true' \
    -e automation_gateway_playbook_pat="/opt/custom/ansible/playbooks" \
    -e automation_gateway_role_path="['/opt/custom/ansible/roles']" \
    -e automation_gateway_collection_path="['/opt/custom/ansible/collections']" \
    --mount type=bind,source=./volumes/iag/automation-gateway-custom,target=/opt/custom \
    --mount type=bind,source=./volumes/iag/install_scripts,target=/docker-entrypoint-init-iag.d/ \
    497639811223.dkr.ecr.us-east-2.amazonaws.com/automation-gateway:<tag>
    

Environment Variables

Environment variables can be set to configure and change the startup behavior of IAG.

WAIT_FOR

If set the container will wait for a service to come up before trying to start IAG.

Example

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

WAIT_FOR_DELAY

Sets how long to wait before checking again if the service listed in the WAIT_FOR variable is up.

Example

docker run --name some_IAG -d --network some_network \
-p host_machine_ip:host_port_number:container_port_number/tcp \
-e WAIT_FOR_DELAY:120 \
497639811223.dkr.ecr.us-east-2.amazonaws.com/automation-gateway:<tag>

WAIT_FOR_TIMEOUT

Sets the timeout for waiting on the service listed in the WAIT_FOR variable to come up.

Example

docker run --name some_IAG -d --network some_network \
-p host_machine_ip:host_port_number:container_port_number/tcp \
-e WAIT_FOR_TIMEOUT:300 \
497639811223.dkr.ecr.us-east-2.amazonaws.com/automation-gateway:<tag>

IAG Properties

All the properties listed in properties.yml can be configured using environment variables.

For each property the text automation_gateway_ needs to be placed in front of the IAG property name.

Example

environment:
  ## configure logging
  automation_gateway_logging_level: 'INFO'
  ## enable ansible and provide the paths to the playbooks, collections, and roles
  automation_gateway_ansible_enabled: 'true'
  automation_gateway_terraform_enabled: 'true'

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?

What's Next
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.