Upgrade Dry Run Tool for Avi LoadBalancer upgrade

Products

• VMware Avi Load Balancer

Issue/Introduction

• Upgrading Avi is a routine operation. One of the more frustrating failure modes is discovering, mid-upgrade, that something in your configuration prevents the new version from importing it. 
• The Upgrade Dry-Run Simulator solves this by running the same validations the upgrade process uses, against your real config file, without modifying anything on the controller it is being run on. 

Environment

• The script must run on the Avi Controller itself. It relies on the controller's own Python environment and migration libraries, which are not available on a workstation.
  • If you want to upgrade to 30.2.7 from 22.1.7, you would need a controller deployed on 30.2.7. 
  • This controller does not need to have any special configurations, it just needs to have an admin account created (which is done when the controller is deployed).
• Run the script as root (sudo).
• You need a config export file. 
• If there are no recent backups and you need to generate a new one, refer to the this document.

Resolution

What does the script check?

• The script performs three independent checks in order:
  • Cross-reference integrity - every object in your config that points to another object (a pool referencing a health monitor, a virtual service referencing an SSL certificate, etc.) is verified to actually resolve within the config. Dangling references are flagged as errors.
  • Config migration - your config is run through the same migration engine that the upgrade process uses. This rewrites fields, renames values, and restructures objects to match the target version's schema. If a migration script raises an exception, it is surfaced here with the failing object identified.
  • Import validation - the migrated config is passed through the serializer layer to confirm each object is syntactically valid for the target version. This is where hard-removed fields or enum values (like a deprecated cipher suite) are caught.

Steps to run the script:

• Step 1 - Export your config on the source controller:
  • Get the latest .json backup file found under Administration → System → Configuration → Export. If you exported with a passphrase, have that ready.
  • If you need to get a new backup, please refer to this document.
• Step 2 - Copy the file to the target controller. This is the controller on the version to which you will be upgrading to. 
• Step 3 - SSH into the target controller and run the script.
  • Minimal run examples:
    • No passphrase and report not saved to file:

      sudo python3 upgrade_dry_run_simulator.py --config-file /tmp/configuration_export.json

    • With passphrase and a saved JSON report:

      sudo python3 upgrade_dry_run_simulator.py --config-file /tmp/configuration_export.json --passphrase "your-export-passphrase" --output-file /tmp/validation_report.json

  • All available options:
    

    Flag	Required	Description
    --config-file	Yes	Path to the exported JSON file.
    --passphrase	Optional (Required if you want to validate the encrypted fields like SSL keys, passwords)	Passphrase used during the export.
    --output-file	No	Save the full report as a JSON file.
    --target-version	No	Version to validate against (defaults to the controllers version where it is being run.).
    --check-only	No	Validate references only; skip migration and import simulation.
    --verbose	No	Print advisory deprecations - fields that are deprecated but will not block the upgrade.
    --show-traceback	No	Include full Python tracebacks in migration errors, useful for debugging.

     

Reading the output:

Overall Status: SUCCESS
Errors: 0
Warnings: 2
Advisory deprecations (non-blocking): 5  (use --verbose to expand)

 

• SUCCESS / FAILED - the bottom line. FAILED means at least one error was found.
• Errors - things that will cause the upgrade to fail. Each error includes the object type, name, and UUID so you can find and fix it before upgrading.
• Warnings - informational notices (e.g., no passphrase provided, no migrations needed). These do not block the upgrade.
• Advisory deprecations - fields or enum values that are marked deprecated in the new version's schema but are still accepted by the importer. These will not fail the upgrade. Pass --verbose to see the full list.
• If you saved a --output-file, the JSON contains all four categories in full detail and is useful for scripted pipelines or support tickets.

 

Additional Information

Support & Troubleshooting

• Installation & Execution: If you encounter any issues while setting up or running this script, please reach out to our support team for assistance.
• Output & Configuration: We are here to help if you need assistance interpreting the output or resolving configuration errors.

Upgrade Guidance

• If you are upgrading from the 31.2.x train, we highly recommend leveraging the built-in dry-run functionality. Refer to this document for more details.
• Please Note: This tool is a proactive, best-effort utility developed based on real-world issues observed in the field. While it covers known scenarios, it is continuously evolving. We will actively incorporate fixes for any new issues flagged by our users to keep the tool as robust as possible.