Itential GatewayDeploy and manageUpgrade

Upgrade Gateway

This topic describes how to upgrade Itential Gateway to a new version.

Most Gateway upgrades follow the same general process: specify the version you want to install, provide your registry credentials, and run pip3 install --upgrade. The general process involves:

  1. Specify the appropriate upgrade version.
  2. Specify the registry credentials to collect the package.
  3. Use pip3 install --upgrade with the appropriate pip/Python versions for your intended installation.

If you’re upgrading from Gateway 4.3 to Gateway 4.4, see Upgrade to Gateway 4.4 first. That upgrade includes a Python runtime change and requires additional steps beyond the general process described above.

Upgrade to Gateway 4.4

Gateway 4.4 upgrades the underlying Python runtime from 3.9 to 3.12 to resolve critical and high severity vulnerabilities in Gateway 4.3’s Python dependencies. Because this is a major runtime change, the 4.3-to-4.4 upgrade works differently than the routine pip3 install --upgrade process.

  • Container-based deployments: The Python version updates automatically within the distributed container. No manual action is required.
  • VM-based deployments: You must install Python 3.12 on your host server and recreate your Gateway virtual environment (VENV) as part of the upgrade.

Once you’re running Gateway 4.4, subsequent 4.4.x maintenance releases use the standard pip3 install --upgrade process described in Software repository and registry credentials.

Custom scripts may break after this upgrade

Custom scripts that share the same global Python environment and library dependencies as Gateway may stop working after you upgrade to Python 3.12. Scripts that already run in their own separate virtual environment shouldn’t be affected. Run custom scripts in a dedicated virtual environment, separate from Gateway’s, to avoid dependency conflicts. For more information, see Python virtual environments.

Note

The name of the Gateway virtual environment differs between the two install methods: manual installs use .venv, while deployer installs use venv (no leading dot). The manual upgrade steps below are written for a .venv environment. You may need to adjust the steps to use a different python virtual environment depending on how Gateway was originally installed.

The Gateway deployer automates the 4.3-to-4.4 upgrade for VM-based deployments, including installing Python 3.12 and recreating your virtual environment. We recommend the deployer as the primary upgrade method for most customers.

Deployer version 4.2 or later is required to upgrade to Gateway 4.4.

For more information, see the Itential deployer documentation.

Manual upgrade for VM-based deployments

If you originally installed Gateway manually, use the following steps to upgrade your VM-based Gateway 4.3 instance to Gateway 4.4. These steps assume a RHEL-based operating system (for example, Rocky Linux) using dnf, and a virtual environment named .venv. Adjust the package manager commands if you’re running a different operating system.

Replace all <placeholder> values below with the details for your environment before running these commands.

  1. Transfer the Gateway 4.4 .whl file to your Gateway server:

    $scp -i <path-to-ssh-key> <path-to-automation-gateway-whl-file> <username>@<gateway-server-address>:/tmp

  2. Log in to the Gateway server:

    $ssh -i <path-to-ssh-key> <username>@<gateway-server-address>

  3. Switch to the root user:

    $sudo su

  4. Change to the Gateway installation directory:

    $cd /opt/automation-gateway

  5. Back up your current Python 3.9 virtual environment by freezing its installed packages:

    $pip freeze > requirements.txt

  6. Leave the current virtual environment:

    $deactivate

  7. Stop the Gateway service:

    $service automation-gateway status
    $service automation-gateway stop

  8. Install Python 3.12:

    $dnf install python3.12 python3.12-devel

  9. Delete the old Python 3.9 virtual environment:

    $rm -rf .venv

  10. Create a new virtual environment using Python 3.12:

    $python3.12 -m venv .venv

  11. Activate the new virtual environment:

    $source /opt/automation-gateway/.venv/bin/activate

  12. Install the Gateway 4.4 .whl file:

    $pip install --upgrade -v /tmp/<automation-gateway-whl-filename>

  13. Check the Gateway service file for any hardcoded python3.9 paths, and update them to python3.12. Not every environment has hardcoded paths in the service file, so treat this as a check rather than a required change.

    $vi /etc/systemd/system/automation-gateway.service

    Environment variables such as ANSIBLE_PYTHON_INTERPRETER and PYTHONPATH are the most common places this occurs:

    [Unit]
    Description=Itential Automation Gateway
    After=network.target
    [Service]
    User=itential
    Restart=always
    Type=simple
    ExecStart=/opt/automation-gateway/.venv/bin/automation-gateway --properties-file=/etc/automation-gateway/properties.yaml
    WorkingDirectory=/tmp
    Environment=MAX_EVENT_RES=35000000
    Environment=PATH=/opt/automation-gateway/.venv/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
    Environment=ANSIBLE_PYTHON_INTERPRETER=/opt/automation-gateway/.venv/bin/python3.12
    Environment=PYTHONPATH=/opt/automation-gateway/.venv/lib64/python3.12/site-packages:/opt/automation-gateway/.venv/bin
    [Install]
    WantedBy=multi-user.target

  14. Start the Gateway service and confirm it’s running:

    $service automation-gateway start
    $service automation-gateway status

After upgrading: check for hardcoded Ansible paths

Check for hardcoded Python 3.9 paths in your Ansible configuration

If your Ansible Module Paths or Collection Paths (Configuration > Automation Gateway > Ansible) reference the virtual environment directly, for example /opt/automation-gateway/.venv/lib/python3.9/site-packages/..., they’ll point to a version of Python that no longer exists after the upgrade. Update any hardcoded python3.9 paths to python3.12 so Ansible can continue to locate its modules and collections. Check this whether you upgraded using the deployer or the manual procedure.

Software repository and registry credentials

Customer accounts are assigned to one of two software repositories: Nexus or JFrog. Customers are informed which repository their account is assigned to in a welcome email that is sent once customer access is granted to the Itential software.

To ensure the Gateway upgrade reflects the correct REGISTRY_URL for your assigned software repository, use the applicable set of instructions presented below.

Customer accounts assigned to JFrog

Run this script to upgrade if assigned to the JFrog repository.

$echo "## CUSTOMIZE THESE VARIABLES BEFORE RUNNING THIS SCRIPT: ##" && \
>export AUTOMATION_GATEWAY_VERSION="" && \
>export REGISTRY_USERNAME="" && \
>export REGISTRY_PASSWORD="" && \
>export REGISTRY_URL="itential.jfrog.io/artifactory/automation-gateway/"
$
$echo "## UPGRADE THE AUTOMATION GATEWAY PIP PACKAGE: ##" && \
>sudo pip3 install --upgrade -v automation-gateway==$AUTOMATION_GATEWAY_VERSION --extra-index-url https://$REGISTRY_USERNAME:$REGISTRY_PASSWORD@$REGISTRY_URL

Upgrade output example (JFrog)

The output of the above commands should roughly match the following code block for customers assigned to JFrog.

$Created temporary directory: /tmp/pip-ephem-wheel-cache-hpp3436z
$Created temporary directory: /tmp/pip-req-tracker-m18dli2n
$Created requirements tracker '/tmp/pip-req-tracker-m18dli2n'
$Created temporary directory: /tmp/pip-install-k11d6prh
$Looking in indexes: https://pypi.org/simple,  https://itential.jfrog.io/artifactory/automation-gateway/
$Collecting automation-gateway==...
$    ...
$    ...
$Successfully installed automation-gateway-...
$Cleaning up...
$Removed build tracker '/tmp/pip-req-tracker-m18dli2n'

Customer accounts assigned to Nexus

Run this script to upgrade if assigned to the Nexus repository.

$echo "## CUSTOMIZE THESE VARIABLES BEFORE RUNNING THIS SCRIPT: ##" && \
>export AUTOMATION_GATEWAY_VERSION="" && \
>export REGISTRY_USERNAME="" && \
>export REGISTRY_PASSWORD="" && \
>export REGISTRY_URL="registry.aws.itential.com/repository/automation-gateway-release/simple"
$
$echo "## UPGRADE THE AUTOMATION GATEWAY PIP PACKAGE: ##" && \
>sudo pip3 install --upgrade -v automation-gateway==$AUTOMATION_GATEWAY_VERSION --extra-index-url https://$REGISTRY_USERNAME:$REGISTRY_PASSWORD@$REGISTRY_URL

Upgrade output example (Nexus)

The output of the above commands should roughly match the following code block for customers assigned to Nexus.

$Created temporary directory: /tmp/pip-ephem-wheel-cache-hpp3436z
$Created temporary directory: /tmp/pip-req-tracker-m18dli2n
$Created requirements tracker '/tmp/pip-req-tracker-m18dli2n'
$Created temporary directory: /tmp/pip-install-k11d6prh
$Looking in indexes: https://pypi.org/simple, https://registry.aws.itential.com/repository/automation-gateway-release/simple
$Collecting automation-gateway==...
$    ...
$    ...
$Successfully installed automation-gateway-...
$Cleaning up...
$Removed build tracker '/tmp/pip-req-tracker-m18dli2n'