> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.itential.com/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 `` 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 @:/tmp ``` 2. Log in to the Gateway server: ```bash ssh -i @ ``` 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/ ``` 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' ```