Migrating Your Aviatrix Controller


The Aviatrix multi-cloud networking platform is delivered via two images, a Controller image and a gateway image. Both should be maintained with the latest version for managing security and support for the product. Aviatrix intends to publish 2 new images per year.

You may need to migrate your Aviatrix Controller in the following situations:

  • If your Controller uses an old machine image and you are trying to upgrade to a new software version that requires the latest image.
  • If you need to transition to a newer machine image for your Controller based on a recommendation from Aviatrix Support.


A machine image is named an “AMI (Amazon Machine Image) in AWS, a “VM image” (Virtual Machine Image) in Azure, a “machine image” in GCP, and a “custom image” in OCI.

The Controller Migration process involves three main steps:

  • Fulfill the prerequisites, including backing up your old Controller.
  • Delete your old Controller in the CSP Account from which you originally launched it: AWS, Azure, GCP, or OCI.
  • Launch a new Controller from the relevant CSP marketplace.
  • Restore the data from your old Controller to your new Controller.

This document explains how to migrate from one type of machine image to another for each CSP.


In a Disaster Recovery (DR) situation in which you cannot access the old Controller, please see the Controller Migration During Disaster Recovery section below.


  • Make sure you have the relevant CSP storage container (an AWS S3 bucket, Azure Blob Storage, Google Cloud Storage, or OCI Object storage service) linked with your Aviatrix Controller. This storage container enables you to back up your data.

As a security best practice, enable versioning on the destination storage container to preserve, retrieve, and restore every version of every object stored.

  • (For AWS, Azure, and GCP Controllers) Get your Customer ID either through Controller > Settings > Controller > License or from your Aviatrix Account Manager. If you are migrating a metered image, subscribe to the Aviatrix Secure Networking Platform Metered 2208-Universal 24x7 Support offer to receive your Customer ID by email.
  • Run an audit on the Controller’s primary access account and all the remaining secondary accounts to make sure that the IAM roles and policies are set up as suggested. In your Controller, go to Accounts > Access Accounts > select an account > click Audit. Repeat these steps for all access accounts for the CSP where your Controller instance is located (AWS, Azure, GCP, or OCI).
  • Enable a Controller backup using the access account for the CSP from which you launched the Controller (Azure, GCP, or OCI).


In case of a Disaster Recovery (DR) scenario, considering keeping current backups in separate regions of each CSP.

  • Back up your existing Controller. In your Controller, go to Settings > Maintenance > Backup & Restore > Backup. Click Backup now.


As a security best practice: * When the backup completes, verify that it is the correct size. * Make a local copy of the backup file (object).

  • Schedule the migration during a maintenance window.
  • Walk through the pre-op checklist.
  • Upgrade to the latest build of your current release. Note that Aviatrix software version upgrade is a version-to-version upgrade. Therefore, you may need to perform multiple upgrades until you reach the latest version on your existing Controller.
  • Disable your Controller’s HA configuration if HA is set up. You can reenable HA on the new Controller once migration is complete.


Deleting your HA configuration is crucial. If you do not delete your HA configuration before migration, the backup configuration may become corrupted, and the migration may fail.

  • If you are using SAML login for either the Controller login (Settings/Controller/SAMLLogin) and/or for openvpn authentication (OpenVPN/Advanced/SAML), please make sure that the endpoints configured on the Controller and the SAML applications in the IdP match exactly.


Do not add any new configurations to your old Controller before migrating, as those updates may be lost in the migration process.

Migrating an AWS Controller

For Controllers launched from AWS, there are two methods you can use to migrate your Controller AMI (Amazon Machine Image):

  1. Controller-driven method (simplest method) - You can easily migrate your AMI directly from the Controller. Note that you can only migrate between AMIs with the same license (BYOL, Metered, or another license) using this method.
  2. Manual method (longer method which offers more visibility) - You can migrate your Controller by going through the AWS marketplace and stopping your Controller instance, disassociating your EIP, and so on. This method requires more steps but allows you to see the network and account changes involved in each step. You can also use this method to change licenses if needed.


The Controller-driven method can only migrate between AMIs using the same license. To change your license, use the manual method.

  • To migrate to a BYOL license model, please contact your Aviatrix Sales Account Manager or email sales@aviatrix.com to acquire the appropriate BYOL license. Make sure you already have subscribed to the BYOL AMI.
  • To migrate to a metered license, subscribe to the Aviatrix Secure Networking Platform Metered 2208-Universal 24x7 Support offer on the AWS Marketplace.

AWS Method 1: Migrating your Controller AMI and Gateway Image Directly from Your Controller

To migrate to the most current AMI directly from your Controller, use the following steps. Note that this method only applies to AWS Controllers.


Because HA (High Availability) ensures that your Controller is consistently available through any change or loss of service, HA is not compatible with image migration. If your account uses an HA configuration, disable HA before using the following steps to do an image migration.

  1. Go to your Controller > Settings > Maintenance > Software Upgrade. Make sure you are on the right software version for the migration. If not, upgrade your software version.
  2. Go to Settings > Maintenance > Backup & Restore. Make sure you have a backup of your current settings.


In case of a Disaster Recovery (DR) scenario in which an entire AWS region goes down, considering backing up your Controller to at least two separate regions.

  1. Go to Settings > Maintenance > Migration.
  • Enter your Customer ID in the field provided.

  • If you want to resize your Controller in this migration, click on the Instance Size dropdown menu and select a new size. To use the same size, leave this field at the default, “current.”

  • Click Migrate to migrate your Controller to the latest image.



Migrating your Controller does not impact your network data plane. Your existing Gateways should continue operating during migration.

AWS: Upgrading Your Gateway Image from Your Controller

To implement the latest Gateway image:

  1. Go to your Controller > Troubleshoot > Diagnostics > Gateway > Gateway Replace.
  2. Select each Gateway and click Replace. (More info on Gateway Replace operation.)

AWS Method 2: Manually Migrating Your Controller

The steps below describe how to manually migrate your Controller. The Controller-driven and manual methods for migration are the same, but the manual method allows you to see each step of the process.


In a Disaster Recovery (DR) scenario in which you cannot access the old Controller at all, please see the Controller Migration during Disaster Recovery section below.

AWS: Stop the Current Aviatrix Controller Instance


If the Controller has HA enabled, you must first disable the Controller HA.


To make best use of time, it is encouraged to launch the new Controller before stopping the old Controller.

In AWS, proceed to Stop the existing Aviatrix Controller instance.

AWS: Disassociate EIP

On the AWS console, go to EC2 > Network & Security > Elastic IPs. Disassociate the EIP from the existing Aviatrix AWS Marketplace Controller instance.


Make sure your browser cache is cleared before the next step to avoid connecting to an old stale session.

AWS: Launch the New Aviatrix Controller


Make sure you already have subscribed to the Aviatrix Secure Networking Platform Metered 2208-Universal 24x7 Support license. Please refer to the Subscribe to an Aviatrix AMI for detailed instructions.

Launch a new Aviatrix Controller. Please see the AWS Startup Guide for instructions.


A best practice is to launch the new Controller before stopping the old Controller.

AWS: Associate EIP

In AWS, go to EC2 > Network & Security > Elastic IPs, and associate the same EIP from the old Controller to the new Aviatrix Controller.

If you have your old Controller behind an ELB, please note that you would have to remove the old Controller instance from the listening group and add the new Controller instance in its place.

AWS: Upgrade Controller

Log in to the new Controller and perform the initialization. Make sure your new Aviatrix Controller is upgraded to same version (latest) by validating it at Settings > Maintenance > Upgrade tab. Please note that Aviatrix only supports Controller backup and restore within the same software version.

AWS: Check Security Groups

Make sure the Security Groups of the new Controller match those of the previous Controller. Then, back up the configuration again.


If you used an ELB (Elastic Load Balancer) for your old Controller, remove the old Controller instance from the ELB’s target group. Then, register the new Controller instance to the target group.

See the Post-Migration Tasks section below to finish the migration steps from within your new Controller.

Controller Migration in Azure

Before migrating your Azure Controller, note the following details so that you can replicate them in your new Controller:

  • The instance’s location, Subscription ID, Size, Public IP address, Virtual network (VNet)/subnet, and Private IP address. In your Azure account, go to Virtual machines > select the Controller instance.


  • The instance’s Display name, Application (client) ID, and Directory (tenant) ID.


  • The instance’s secret value, which could only be accessed directly after the instance is created.
  1. Locate your Customer ID.
  2. Make a Controller backup in a storage container and make a note of Subscription ID, Directory ID, Application Client ID, Application Client Secret, Storage Name, Container Name, File Name.
  3. Launch the new Controller Instance. Please refer to the Azure Startup Guide. Make sure to subscribe to the Aviatrix Secure Networking Platform Metered 2208-Universal 24x7 Support offer on the Azure Marketplace, and then activate that subscription using the Aviatrix Secure Networking Platform BYOL offer.


Launching a new Controller, or migrating Controller images, requires two offers from the Azure Marketplace:

  1. Aviatrix Secure Networking Platform Metered 2208-Universal 24x7 Support
  2. Aviatrix Secure Network Platform BYOL (Bring Your Own License)

Both offers are required. Subscribe to the metered offer to receive your Customer ID, and then subscribe to the BYOL offer to deploy your Controller using that Customer ID. You will only be billed for the metered offer.

  1. Shut down the old Controller instance. Go to your Azure account > Virtual machines and select the old Controller instance. Click Stop.


  1. Dissociate the Public IP address from the old Controller. In your Azure account, go to Network interfaces > select the Network Interface > Select the public IP > click Dissociate.


Click Yes to confirm the dissociation.

  1. Associate this Public IP address to the new Controller instance. On the Public IP address page, click Associate.


  • Under Resource type, select Network interface.
  • Under Network interface, select your new Controller instance.


  1. Set up your Aviatrix Customer ID. Open your new Aviatrix Controller and go to Onboarding > Azure > enter your Aviatrix Customer ID.

Controller Migration in GCP


GCP Controller image in 5.4 versions and higher versions of the Controller image are based on the 18.04 ubuntu distribution.

  1. In your GCP account, make a list of the old Controller’s region, availability zone, instance size, and any specific subnets so that you can use the same parameters to launch the new Controller. To find this information, log into your GCP account > click on the menu in the top left and scroll down to Compute Engine > hover over Compute Engine and select VM instances. On the VM Instances page, find your Controller instance, click on the three dots on the right side of its row in the table, and select View network details.

(Optional) Find and save your old Controller’s Customer ID. In your Aviatrix Controller, go to Settings > Controller > License > Setup Aviatrix Customer ID.

  1. If you do not have a bucket for data storage, create a new one. In your GCP account, go to Cloud Storage > Browser.


  1. Click Create Bucket. Add the necessary information and click Create.
  2. If you have not reserved a static IP for the old Controller and want to do so, go to your GCP account > VPC Network > IP Addresses. Select Reserve External Static Address.


  1. Enter the details of the IP address and click Reserve.
  2. Before stopping this old instance, disassociate the reserved IP address. Click Change. Then, click on the Attach to dropdown menu and select None.


  1. Shut down the old Controller instance.


  1. Launch a new Controller instance in the same region and VPC, of the same size as your old Controller. Review the details you saved from your old Controller to ensure they match. To launch the new instance, go to your GCP account > Marketplace > search for “Aviatrix” > choose your required Aviatrix platform > click Launch. Make sure to replicate the same region, subnet (if required), and size of the old Controller. See the Google Startup Guide for thorough instructions.
  2. Once the new Controller launches, associate the reserved static IP address to this new instance. In your GCP account, go to VPC Network > IP Addresses > select the IP address > change > select the newly launched Controller.

Controller Migration in OCI

  1. Before terminating the old Controller instance, document the following information from your OCI account:
  • The instance’s region, availability domain, and fault domain
  • The instance’s display name
  • Assigned VCN details
  • All private IP addresses, names, subnets, and private DNS name (if any)
  • Any public IP addresses assigned from a reserved public pool
  • Any tags on the instance or attached resources



Make sure that the Permanently delete the attached boot volume checkbox is unmarked while terminating. This step saves the old Controller image to use for the new Controller.


  1. Terminate the old Controller instance. In your OCI account, go to Compute > Instances > Controller Instance > More actions > Terminate. Click Terminate instance.


  1. Create a new Controller instance. Go to OCI Console > Menu > Compute > Instances > click Create instance. Refer to these instructions.
  2. The Launching instance page opens. Enter the details of the Controller as per the old Controller instance.
  3. Add the appropriate ssh public key file and click Create to launch the instance.
  4. Move the Controller’s public IP address. Follow the steps below.

Move your OCI Controller’s Public IP Address

  1. Assign the IP from reserved pool to the new Controller instance. Go to your OCI account > Compute > Instance > Controller Instance > Resources > Attached VNICs. Select Primary VNIC.


  1. Under VNIC details > Resources > IPV4 Addresses > select the three dots icon > click Edit.


  1. Go to Public IP type > Select reserved IP address > Select the Reserved public IP radio button. Under Reserved IP Address in Compartment_Name, click on the dropdown menu and select the Public IP address reserved for your Controller. Then, click Update.


Post Migration Tasks

After testing to ensure that the Controller migration is complete and successful, you can delete the old Controller. It can be left in “Stopped” status for a while, but it should never be started. If it is started, this old Controller will reach out to the gateways and the network could have issues with two Controllers trying to monitor/modify the gateways.

Setting up Your New Controller

  1. Log into the newly launched Controller instance.
  • Username - admin
  • Password - the private IP of the newly launched instance
  1. Set a new password and upgrade this Controller to the same version as your old Controller instance. This might take up to 5 minutes.
  2. Log into the new Controller and onboard your primary access account (the CSP account). Make sure to have your CSP credentials available, as you will need them to onboard your CSP account. In your Controller, go to Accounts > Access Accounts > CSP (AWS, Azure, GCP, or OCI).
  3. Onboard your Aviatrix Customer ID.
  4. Once everything is set up and ready, restore the backup from your storage container. In your Controller, go to > Settings > Maintenance > Backup & Restore > Restore > fill in the appropriate details > click Restore.


If you encounter an issue when you try to restore the backup, do not attempt a rollback. Instead, open a ticket with Aviatrix Support.

It will take a few minutes for the backup to be restored. You can verify the dashboard to see if all the configuration from the old Controller has been restored.


Optional: After confirming everything is running correctly, delete the previous Controller instance from the CSP marketplace.

Migrating the Controller IP Address

After migrating to a new Controller, make sure you have migrated your public IP address as well.

  1. In AWS, Azure, GCP, or OCI, disassociate the Static Public IP or Elastic IP address from your old Controller and associate it with your new Controller.
  2. In your new Controller, in the left sidebar, go to Troubleshoot > Diagnostics > scroll down to the Controller IP Address Migration section. If two IPs display under Controller Public IP, click Migrate.

Before Controller IP migration :


After Controller IP migration :


Controller Migration During Disaster Recovery

In a Disaster Recovery (DR) situation in which an entire CSP region is unavailable, you may not be able to access your old Controller to follow the steps above. In this situation, use the steps below to migrate your Controller.

  1. Deploy a new Controller in a different region from the old Controller.
  2. Upgrade this new Controller to the current production version.
  3. If possible, restore your backup. A best practice is to keep a current backup in a separate region from the region in which you deployed the Controller.


If you encounter an issue when you try to restore the backup, do not attempt a rollback. Instead, open a ticket with Aviatrix Support.

  1. In your new Controller, go to Settings > Maintenance > Migration and click Migrate. This migration changes all security group gateways to use the new Controller’s EIP (Elastic IP address).
  2. Run a connectivity and performance test to ensure everything is working correctly.
  3. Deploy CoPilot from the new Controller.
  4. When your old Controller becomes available again, do not restart that instance until you can ensure that all operations are working with the new Controller. Then, you can delete that instance.