Upgrading Gateway Image

A gateway image is a virtual resource or template that contains all the information required to launch, backup, or restore a gateway in your cloud network. Aviatrix periodically releases new gateway images that include updates, enhancements, and security improvements. A best practice is to plan to upgrade your gateways at least once a quarter.

For major security issues or software issues, Aviatrix sends out a field notice to notify you to upgrade to the newest image. You can review past Field Notices and Aviatrix Controller and Gateway Image Release Notes.

You may need to upgrade your gateway image outside of a periodic upgrade in the following situations:

  • Aviatrix has released a new gateway image as part of a security update or product enhancement.

  • A gateway requires significant repair.

This document shows you how to upgrade an Aviatrix Gateway to a new image.

A gateway image upgrade is also known as a gateway replacement. During the Gateway image upgrade, the EIP will remain unchanged.


  • Check the current software version of your Controller. You cannot upgrade your gateways to a newer version than your Controller.

  • Schedule the gateway image upgrade every quarter or if you receive a field notice about a new image.

  • Schedule the gateway image upgrade for an off-peak time on your network or during a maintenance window. These upgrades do require some downtime, but they have minimal impact.

  • Consider enabling HA (High Availability) on the Transit and Spoke Gateways that require an image upgrade, if you have not done so. HA helps minimize downtime.

    • If you do not have HA configured, a gateway image upgrade requires downtime.

    • If you have HA configured, when you perform a gateway image upgrade, your Controller routes all traffic to the gateway that is not being replaced. Performance during the upgrade depends on the size of the gateway and the amount of traffic.

      Before upgrading, consider increasing the size of your gateway, if the traffic load is high.
      Even with HA configured, if you have high traffic during a gateway image upgrade, the gateway that remains up could receive too much traffic. Schedule gateway image upgrades during a low-traffic period.
  • Before upgrading any gateway images, upgrade your Controller to the latest software version. This software upgrade ensures that you can update to the latest gateway image and reduce downtime for gateway image upgrades.

Image Upgrades by Gateway Type

The process and best practices for upgrading a gateway image can differ based on the type of gateway. Review this list to decide how to structure and schedule your gateway image upgrades.

Gateway Type Image Upgrade Notes

OpenVPN Gateway

  • When you have an Open VPN Gateway deployed behind a load balancer, you can upgrade images in batches without causing an outage, depending on the number of users you have.

  • For OpenVPN Gateways that are not deployed with a load balancer, you should expect an outage.

  • If any users are already on an OpenVPN gateway, they will be bumped when the gateway goes through an image upgrade. If you have more than one OpenVPN gateway, the end user can connect immediately to another gateway.

FQDN Gateways with HA (gateways on the Specialty Gateways tab that have 'fqdn' in the name)

The Controller does not reroute all traffic for these gateways.

Public Subnet Filtering (PSF) Gateway

This gateway type does not have HA.

Transit and Spoke Gateways

If your network has many Spoke Gateways, replacing the Transit primary or HA Gateways takes more time. Wait for one group of image upgrades to complete before beginning another.

Site2Cloud Gateways

A best practice is to upgrade one gateway at a time.

Edge Gateways

  • It is not recommended to upgrade your Edge Gateway unless a field notification has been sent to notify you to upgrade to a new image.

  • It is not recommended to change Edge Gateway size.

Upgrade Gateway Image

  1. In your Controller, go to Settings > Maintenance.

  2. In the Selective Gateway Upgrade window, select the gateways that require an upgrade. The system automatically selects the platform controller current software version and the compatible gateway image version for that software version.

    • Your Controller can replace up to 15 gateways in parallel. Try to group your image upgrades in groups of no more than 15.

    • For greater simplicity and efficiency, combine all your HA gateways and all primary gateways in separate operations.

    • To organize multiple image upgrades, consider spreading out groups of upgrades in separate windows on your browser.

  3. Click IMAGE UPGRADE. You can follow the status in the progress window.

Replacing a gateway can take 5-7 minutes. After the gateway is up, it takes more time for the tunnels to come up. The total length of time required varies depending on the number of tunnels. For example, depending on the software version of the Controller, it may take up to one hour to upgrade 4,000 tunnels.

Upgrade Gateway Images in Batch

To upgrade gateway images, you can use batch mode for ActiveMesh gateways and for some non-ActiveMesh gateways. Check if your gateway is ActiveMesh enabled using the instructions in Check Whether a Gateway is ActiveMesh.

For ActiveMesh Gateways

  1. In your Controller, go to Settings > Maintenance.

  2. In the Selective Gateway Upgrade window, select multiple gateways that require an upgrade.


  4. Click OK to confirm the upgrade.

For Non-ActiveMesh Gateways

Before upgrading a non-ActiveMesh gateway, it is important to check whether it has any peerings.

Check Whether a Gateway has any Peerings

Follow the steps below to check whether a gateway has any peerings:

  1. In your Controller, go to NATIVE PEERING > Encrypted.

  2. Scroll down to the display window and check if the gateway you want to upgrade is listed.

  3. If the gateway is listed, it has at least one peering.

Supported Batch Image Upgrade Scenarios for Non-ActiveMesh Gateway

You can upgrade multiple non-ActiveMesh gateways' images in batch mode in these two scenarios:

  • Upgrade multiple non-ActiveMesh gateways without any peerings in a single batch process.

  • Upgrade multiple non-ActiveMesh gateways with at most one of the selected gateways having peering in a batch image-upgrade session.

Only one image-upgrade session is allowed for non-ActiveMesh gateways. This means that all desired gateways must be included in a single upgrade session. However, as mentioned in the scenarios above, multiple non-ActiveMesh gateways can be upgraded simultaneously as part of a single upgrade session.


Verify the gateway upgrade by reviewing the gateway information in the Current Image Version column in the Selective Gateway Upgrade window. For information about migrating your Controller to a new image, see Migrating Your Aviatrix Controller.

Migrating Unmanaged Disk to Managed Disk (Azure)

If you have a gateway deployed on Azure and you intend to migrate your unmanaged disk to a managed disk, it is recommended to follow the process of gateway image upgrade. This gateway image upgrade will automatically migrate the unmanaged disk to a managed disk after the gateway image upgrade.

It is highly recommended to migrate your unmanaged disk to a managed disk as soon as possible, as Azure will be retiring unmanaged disks soon.