Resources
🤖 For AI agents: The complete documentation index is available at /docs/llms.txt. A markdown version of this page is available at /docs/cloud/upgrade-a-deployment.md.

Upgrade a Deployment

Edit on GitHub
View Markdown

If your deployment is not running the latest version of FusionAuth, you may upgrade to a newer version. We recommend running the latest released version of FusionAuth for access to the latest fixes, security updates, and features.

However, you will not be forced to upgrade on a certain schedule. Upgrades are optional and controlled by you.

The upgrade process described in this section updates the version of FusionAuth; for help modifying other attributes of your deployment, such as the region, the deployment size, or the service tier, see Alter a Deployment.

Upgrade Process#

caution

You cannot downgrade a FusionAuth Cloud deployment version. After an upgrade, you can only roll back to a backup of an earlier version. This permanently loses any new or changed user or configuration data since the backup.

Please test upgrades before performing them on your production system.

To upgrade a deployment from version 1.x-1 to version 1.x:

  1. Test 1.x on a staging or development environment.
  2. Select a time that works for your users, your team, and your applications.
  3. Log into your account at account.fusionauth.io.
  4. Record the time you began the upgrade.
  5. Navigate to the Hosting tab. Manage the deployment, then choose the Upgrade option. Select 1.x from the Version dropdown.
  6. Confirm you want to start the upgrade.
  7. After confirmation, the deployment will enter an Upgrading state until finished. To monitor the upgrade, navigate to the Hosting tab. To programmatically monitor the upgrade, call the System Status API.
  8. Your upgrade is complete when the user interface deployment has a status of Active, or when the System Status API returns success.

Upgrade Duration#

This upgrade process takes between 5 minutes and 60 minutes of time. The exact duration of system downtime depends on the type of deployment, amount of data in your system, and database changes required by the version upgrade.

Hosting OptionDuration of UpgradeExpected Downtime
Basic Cloud5 to 60 minutes5 to 60 minutes
Business Cloud5 to 60 minutes5 to 60 minutes
HA Cloud5 to 60 minutesseconds

HA systems have significantly lower downtime during an upgrade because the system has two or more nodes. They are upgraded one at a time and can continue to receive traffic during the upgrade.

Upgrade Considerations#

Consult the relevant release notes for functional changes. Such changes may require updates or modifications to your code, whether to take advantage of new features or, occasionally, to handle changes in FusionAuth functionality.

Due to the downtime, it is recommended that you schedule the upgrade for a low traffic period. Test the upgrade process on development or test servers first.

Roll Back to a Backup#

Business and High Availability deployments retain backups for 30 days after an upgrade. Basic deployments do not retain backups.

If an upgrade is problematic, and you identify the issue during the timeframe of your plan's backup retention period, open a support ticket, including the following information:

  • The version from which you were upgrading. This will be the version of your restored instance.
  • The approximate time the upgrade began, including timezone, so that the correct backup can be restored.

Both production and non-production environments can be rolled back if on a plan with backups.

Production rollbacks will be treated the same as a production outage.

Non-production rollbacks will be completed within two business days, and will be handled during normal FusionAuth business hours (9am-5pm Mountain time, Monday-Friday). Non-production rollbacks will not be treated as a production outage.

All rollbacks will have data loss; the amount of data loss depends on when the upgrade began and when the rollback was requested.