> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.itential.com/itential-gateway/4/upgrade/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.itential.com/_mcp/server.

# Upgrade Gateway

> Instructions for upgrading Itential Gateway using pip3 with JFrog or Nexus software repositories.

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](#upgrade-to-gateway-44) 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](#software-repository-and-registry-credentials).

> **Warning**
>
> **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](./python-virtual-environment).

> **Note**
>
> **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.

### Recommended: Upgrade with the Gateway deployer

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.

**Prerequisites:** Deployer version 4.2 or later.

> **Note**
>
> Gateway 4.4 requires a Python upgrade. Run the `itential.deployer.gateway` playbook. Do not run `itential.deployer.patch_gateway`.

During the upgrade, the deployer backs up your current Gateway `properties.yml` file and generates a new one. If you manually modified `properties.yml`, the upgrade overwrites those changes. Compare the latest backup to the new properties file and reapply any manual changes. For example, if you previously enabled LDAP, you must re-enable it manually.

For more information, see the [Itential deployer documentation](https://github.com/itential/itential.deployer#overview).

### 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.

> **Note**
>
> 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:
   ```bash
   scp -i <path-to-ssh-key> <path-to-automation-gateway-whl-file> <username>@<gateway-server-address>:/tmp
   ```

2. Log in to the Gateway server:
   ```bash
   ssh -i <path-to-ssh-key> <username>@<gateway-server-address>
   ```

3. Switch to the root user:
   ```bash
   sudo su
   ```

4. Change to the Gateway installation directory:
   ```bash
   cd /opt/automation-gateway
   ```

5. Back up your current Python 3.9 virtual environment by freezing its installed packages:
   ```bash
   pip freeze > requirements.txt
   ```

6. Leave the current virtual environment:
   ```bash
   deactivate
   ```

7. Stop the Gateway service:
   ```bash
   service automation-gateway status
   service automation-gateway stop
   ```

8. Install Python 3.12:
   ```bash
   dnf install python3.12 python3.12-devel
   ```

9. Delete the old Python 3.9 virtual environment:
   ```bash
   rm -rf .venv
   ```

10. Create a new virtual environment using Python 3.12:
    ```bash
    python3.12 -m venv .venv
    ```

11. Activate the new virtual environment:
    ```bash
    source /opt/automation-gateway/.venv/bin/activate
    ```

12. Install the Gateway 4.4 `.whl` file:
    ```bash
    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.

    ```bash
    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:
    ```bash
    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.

```bash
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**.

```bash
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.

```bash
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**.

```bash
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'
```

> Instructions for upgrading Itential Gateway using pip3 with JFrog or Nexus software repositories.