Cloud Platform

Upgrading to Cloud Next


Before planning to upgrade from Classic Cloud to Cloud Next, ensure that you see the information in the following sections:

Upgrading to Cloud Next

The upgrade process starts with your non-production environments and consists of the following steps. Acquia owns most of the upgrade process for your application. However, there are a couple of steps that might require your team’s action.

Step #DescriptionCustomer action

Acquia notifies the customer team through a Support ticket that the application is ready to be upgraded to Cloud Next.


As part of the upgrade process, there are potential changes that require customer action. If detected, Acquia updates the ticket indicating the specific customer actions.

Based on Acquia’s update, make the changes to make your platform compatible to be upgraded to Cloud Next. For more information, see Additional changes for Cloud Next readiness.
2Acquia updates the existing Support ticket to share the upgrade scheduling details for the non-production environment. Typically, this happens 2 weeks prior to customer’s non-production environment upgrade.NA

Acquia upgrades the non-production environment on the scheduled date and time. Acquia triggers automated processes that deploy your code, databases, files, and environment settings to the Cloud Next infrastructure. This ensures that your infrastructure can be tested by Acquia’s automated tooling.

During this process, your file system and databases are placed in the read-only mode to prevent the possibility of data loss. However, your site might appear to be online to unauthenticated traffic if cached content is available through Varnish or your CDN. After Acquia’s automated tests are complete, Acquia cuts over traffic to the Cloud Next version of your environment and restores full access to your files and databases if the upgrade is successful. Otherwise, Acquia restores access to your files and databases on your Cloud Classic infrastructure and reschedules the upgrade for a later date and time.


Acquia updates the Support ticket to confirm that the upgrade was successful.


If the non-production environment upgrade fails, Acquia updates the Support ticket to notify the team and provides details of the upgrade and next steps.

5Customers must test the non-production environment.Test the non-production environment to ensure everything works as expected. For information on what to test after the upgrade, see Testing your environments upgrading to Cloud Next
6Acquia creates a new Support ticket to share the upgrade scheduling details for the production environment. Typically, this happens 2 weeks prior to the production environment upgrade.NA
7Acquia upgrades the production environment on the scheduled date and time. Acquia follows a similar process to that of non-production. However, environments with larger file systems and databases might require the use of advanced upgrade tooling. In such cases, there is a pre-sync process prior to the start of the testing and cutover process. Similar to the upgrade on your non-production environment, no visible impact to you or your end users is expected until the final process begins.NA

Acquia updates the existing Support ticket to confirm that the upgrade was successful.


If the production environment upgrade fails, Acquia updates the Support ticket to notify the team and provides details of the upgrade and next steps.

If you face any technical issues after upgrading to Cloud Next, file a Support ticket. For more information, see Technical issues after upgrading to Cloud Next.

For more information about upgrading your application to Cloud Next, see:

Changes that may require customer action

If your environments are being upgraded to Cloud Next from the Classic Cloud version of Cloud Platform, pay attention to the following changes that may require updates to your code, site configuration, or development processes. To make your platform compatible for upgrading to Cloud Next, you must make additional changes. For more information, see Additional changes for Cloud Next readiness.

Acquia contract revisions

All environments, applications, and subscriptions upgraded to Cloud Next are subject to the March 31st, 2021 revisions to Acquia’s Support Users Guide and Acquia’s Products & Services Guides (Legacy Server-based Pricing Model, Current Views/Visits Pricing Model), especially as they pertain to Acquia’s Resource Limits on dynamically auto-scaling infrastructure. See all sections related to the use of shared resources, infrastructure capacity, and capacity management for more details.

MySQL Workbench Management Software

If you have MySQL Workbench installed locally, you might not be able to connect to Cloud Next environments. This issue occurs for a few versions of MySQL Workbench.

If you face issues connecting to Cloud Next environments from MySQL Workbench:

  1. Locate the database credentials listed on your Databases page.
  2. Open Terminal on your local machine and run:

    {ssh -L $LOCAL_PORT:$DB_HOST:3306 $SSH_STRING}


    • LOCAL_PORT is the port to which Workbench must connect when using localhost.
    • DB_HOST is the hostname obtained from the Cloud Platform user interface.
    • SSH_STRING is the full connection string from the Cloud Platform user interface. For example, user@something.

Legacy Keys

SSH keys that were manually added to an environment before the October 2018 EOL of per-environment SSH key management will not persist after the upgrade to Cloud Next. If your application was running on Cloud Platform Enterprise before that date, visit the Users & Keys page for each of your application’s environments before they are upgraded. You must ensure that all necessary SSH keys are properly associated with users in your subscription’s Teams & Permissions console.

Failure to do so may result in errors whenever users, scripts, development software, automations, or remote services attempt to access those environments after they are upgraded.

Direct log access

The /var/log/sites directory is no longer available for direct log access or custom log storage. Use /shared/logs for custom log storage instead.

Slow queries

Acquia reserves the right to terminate queries at a certain threshold to preserve the overall experience. As a best practice, Acquia recommends that queries do not run longer than 60 seconds for non-production environments and 5 minutes for production environments. To ensure that your environments complete all long-running transactions as expected, wrap them in a MySQL transaction to avoid the risk of data loss or corruption. If your environments require long-running MySQL queries to complete reports or other complex data management processes, contact your Acquia Accounts team to request a delay to your upgrade to Cloud Next.

Remote Administration

Applications running on Cloud Next should test all Remote Administration patches in a Cloud Next non-production environment before pushing changes to the production environment. This ensures that no differences in Cloud Next and Cloud Classic logic impact the way patches behave after deployment in a Cloud Next environment.

Logic requiring access to a tmp or persistent shared directory must be redirected to $HOME on Cloud Next.

Testing your environments upgrading to Cloud Next

Acquia strongly recommends that you immediately test your non-production environments as soon as they are upgraded to Cloud Next. This not only ensures that any technical issues can be investigated and resolved quickly with the help of the Acquia Support team, but it also reduces the risk of delays or undesired behavior with your production environment upgrade.

When testing your environments through automated tests or manual inspection, review the application behavior that depends on the following:

  • Custom logic in htaccess files

  • Image software such as ffmpeg, imagemagick, or webp

  • System libraries

  • Shell scripts or tools such as curl or wget

  • Scheduled tasks or cron jobs

  • Cloud hooks

  • Custom scripts or commands that run on the SSH pod

In addition, you must monitor application performance in New Relic after the upgrade and compare that with prior performance.

When testing your environments, the following practices are recommended:

  • Ensure that you note down any anomalous behaviors on each environment’s sites prior to the upgrade so that you can clearly differentiate between existing bugs in your application and new bugs introduced since the upgrade.
  • After upgrade, load your sites on each environment and verify that they are behaving the same after being upgraded to Cloud Next as they were before the upgrade took place.
  • Test any custom functionality, focusing on the most critical behaviors of your application, including custom modules, reports, scripts, cron jobs, CI/ CD automations, and connections to remote non-Acquia services.
  • Verify that cron jobs are both running as expected and logging as expected, keeping in mind that Cloud Next has a new directory for cron logs and custom logs that must be routinely pruned to prevent unnecessary growth of your file system:

  • Verify that all necessary scripts, Drush commands, automations, and CLI commands that you require are available and work as expected, by accessing your environment. Some may require updates and adjustments to syntax, and certain CLI commands you had used previously may not be available. A new SSH syntax will be required to access your production environment.
  • If necessary, re-download your Drush aliases to ensure they are compatible with Cloud Next.

For additional recommendations about how to test your application after non-production upgrades, see Common Technical Questions when upgrade to Cloud Next.

Technical issues after upgrading to Cloud Next

If you discover any technical issues after your environments are upgraded to Cloud Next, create a Support ticket and ensure you select an appropriate level of urgency. In the ticket description, include steps to reproduce the problem and a clear summary of how the environment behaved prior to upgrade.


Do not use your maintenance notification Acquia Support ticket to report technical issues.