IAG containerized deployment

The following walkthrough demonstrates how to:

• Install and configure an Itential Automation Gateway (IAG) server within a containerized deployment
• Install and configure the CLI client used to interact with your gateway server on your local machine
• Create and configure a gateway cluster in Gateway Manager

Container Management
Itential container 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 Kubernetes, falls outside the scope of this guide.

Prerequisites

Before starting, ensure you have:

• Docker and Docker Compose installed on your local machine
• Access to Itential's software repository
• Access to Gateway Manager
• OpenSSL installed for creating certificates

Accessing IAG container images

Docker Repository Access

Itential container 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.

Run the following command to log in to the Itential Docker repository.

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

Step 1: Download IAG container image

To download the IAG container image, run the following Docker Pull command:

docker pull 497639811223.dkr.ecr.us-east-2.amazonaws.com/automation-gateway5:5.1.0-amd64

Step 2: Create server configuration file

Create a Docker Compose file named docker-compose.yml to configure your gateway server.

Before you copy the following configuration file to your server host machine, update the placeholder GATEWAY_CONNECT_HOSTS value:

1. Identify your Itential Platform server's URL, for example: acme-dev-iap01.iap-prod.itential.io
2. Add -gwm to the server name before the first period (.): acme-dev-iap01-gwm.iap-prod.itential.io
3. Add :443 to the end: acme-dev-iap01-gwm.iap-prod.itential.io:443
   Final result: GATEWAY_CONNECT_HOSTS: "acme-dev-iap01-gwm.iap-prod.itential.io:443"

services:
  gateway5-server:
    container_name: gateway5-server
    image: 497639811223.dkr.ecr.us-east-2.amazonaws.com/automation-gateway5:5.1.0-amd64
    entrypoint:
      - iagctl
      - server
    volumes:
      - type: bind
        source: "./certificates"
        target: "/etc/gateway/certificates"
    environment:
      GATEWAY_CONNECT_HOSTS: ""
      GATEWAY_APPLICATION_CLUSTER_ID: "cluster_1"
      GATEWAY_APPLICATION_MODE: "server"
      GATEWAY_CONNECT_CERTIFICATE_FILE: "/etc/gateway/certificates/gw-manager.pem"
      GATEWAY_CONNECT_PRIVATE_KEY_FILE: "/etc/gateway/certificates/gw-manager-key.pem"
      GATEWAY_CONNECT_INSECURE_TLS: true
      GATEWAY_SERVER_USE_TLS: "false"
      GATEWAY_SERVER_LISTEN_ADDRESS: "0.0.0.0"
      GATEWAY_LOG_LEVEL: "DEBUG"
    ports:
      - "50051:50051"

Step 3: Create Gateway Manager certificates

Gateway Manager uses digital certificates to establish secure, authenticated communication with your gateway cluster. Before connecting to Gateway Manager, you must create certificates that will function as digital IDs. These certificates uniquely identify your gateway cluster.

1. Create a directory for your certificates in the same location as your docker-compose.yml file:

mkdir certificates

2. Generate Gateway Manager certificates using OpenSSL:

openssl req -x509 -newkey rsa:4096 \
               -keyout ./certificates/gw-manager-key.pem \
               -out ./certificates/gw-manager.pem \
               -days 1825 -nodes \
               -subj "/CN=$(hostname)" \
               -addext "basicConstraints=CA:FALSE" \
               -addext "keyUsage=digitalSignature,keyEncipherment" \
               -addext "extendedKeyUsage=serverAuth"

If you use a version before OpenSSL 3.0, use this alternative approach:

cat > my-ssl-conf <<-EOF
[req]
distinguished_name=req_distinguished_name
x509_extensions=custom_ext
[req_distinguished_name]
[custom_ext]
basicConstraints=CA:FALSE
keyUsage=digitalSignature,keyEncipherment
extendedKeyUsage=serverAuth
EOF

openssl req -x509 -newkey rsa:2048 \
      -keyout ./certificates/gw-manager-key.pem \
      -out ./certificates/gw-manager.pem \
      -days 1825 -nodes \
      -subj "/CN=$(hostname)" \
      -config my-ssl-conf

Step 4: Upload Gateway Manager certificate

The Itential Platform must recognize and trust your certificate before your gateway cluster can establish a secure connection. Upload your certificate to Gateway Manager to establish this trust relationship between your gateway cluster and the Platform.

1. Open Itential Platform in your browser.
2. Select Gateway Manager from the Administration collection in the left-side navigation menu.
3. Upload the certificate:
   1. Navigate to the Certificates tab and click Upload Certificate.
   2. Upload the Gateway Manager certificate you created in Step 3.
   3. Click Add Certificate.

Step 5: Create a gateway cluster

After you upload your certificate, create a gateway cluster.

1. Navigate to the Gateways tab in Gateway Manager.
2. Click Add Gateway Cluster.
3. Set the gateway cluster ID to match the GATEWAY_APPLICATION_CLUSTER_ID defined in your configuration file in Step 2. If you did not modify the cluster ID from the sample configuration file provided in Step 2, enter cluster_1.
4. (Optional) Enter a description
5. Under Access, add at least one authorization group to your gateway cluster.
6. Click Add.

Step 6: Enable your gateway

Gateways are disabled at creation and must be manually enabled. To enable your gateway cluster, you need to connect the certificate that you uploaded in Step 4 to your new gateway cluster. This tells Itential Platform that your gateway is trusted and can run automation tasks.

1. Navigate to the Gateways tab in Gateway Manager.
2. Click your newly created gateway cluster to view the gateway details.
3. Under Linked Certificates, click the Link toggle to associate the certificate you uploaded in Step 4 with your gateway cluster.
4. Select Enabled from the status dropdown menu at the top of the gateway details window to enable your gateway.

Step 7: Start your gateway server

Now that you've configured and registered your gateway, you need to start the gateway server. This creates a persistent connection to Itential Platform that allows the Platform to run your automation services and securely return results.

1. Open a dedicated terminal and run the following command from the directory containing your docker-compose.yml file:

docker compose up --detach

2. Verify that you see successful connection logs similar to the following:

INF connected to gateway manager at some-server:8080
INF negotiated protocol: "json-rpc"
INF received initial message from gateway manager: {init_message:cf692e6c-37c0-45d5-a56f-fef95cd84a43 2.0 GetClusterInfo [ping ack]}

Step 8: Install and configure the gateway client

Install gateway client

Install a gateway client on your local machine to manage the resources on your gateway server.

Mac installation

1. Navigate to your Downloads folder and extract the archive. Before running the following command, update x.y.z and arch to reflect the version you downloaded.

tar -zxvf iagctl-x.y.z_darwin_arch.tar.gz

2. Run the extracted executable:

./iagctl

3. When a security warning appears, click Cancel.
4. Navigate to your System Settings and select Privacy and Security.
5. Under Security, select Allow Anyways where it says "iagctl was blocked from use".
6. Provide your password or fingerprint to confirm.
7. Copy the file to your bin directory:

mv ./iagctl /usr/local/bin/iagctl

Linux installation

1. Navigate to your Downloads folder and extract the archive. Before running the following command, update x.y.z and arch to reflect the version you downloaded.

tar -zxvf iagctl-x.y.z_linux_arch.tar.gz

2. Run the extracted executable:

./iagctl

3. Copy the file to your bin directory:

mv ./iagctl /usr/local/bin/iagctl

You can now run IAG from anywhere using the iagctl command.

Create client configuration file

Configure your gateway client to connect to your gateway server.

1. Create a gateway.conf file at ~/.gateway.d/gateway.conf with the following properties:

[application]
mode                 = client
#working_dir         = ~/.gateway.d

[client]
host              = <gateway-server-hostname>
#port             = 50051
use_tls           = false

[log]
#level = INFO

2. Run the following command to verify your configuration:

iagctl version --show-config

If you are unable to verify your configuration, run iagctl --verbose and look for a log similar to the following:

INF using configuration file at /path/to/gateway.conf

Step 9: Log in to your server

While your gateway server is running, establish a client connection to manage the server. When you log in as an administrator, you can import content, create services, and perform other management tasks.

1. Run the following command from your client:

iagctl login admin

2. Enter admin when prompted for the initial password.
3. Create a new password when prompted. Your password must be longer than 8 characters.
4. Follow the remaining prompts to finish logging in.