Upgrading between versions of AE5¶

Due to the potential complexity of your custom configuration, please contact Anaconda Support before initiating the upgrade.

After you have determined the topology for your Anaconda Enterprise cluster, and verified that your system meets all of the installation requirements, you’re ready to upgrade the cluster.

Before you begin:

Configure your A record in DNS for the master node with the actual domain name you will use for your Anaconda Enterprise installation.
If you are using a firewall for network security, we recommend you temporarily disable it while you upgrade Anaconda Enterprise.
When installing Anaconda Enterprise on a system with multiple nodes, verify that the clock of each node is in sync with the others prior to starting the installation process, to avoid potential issues. We recommend using the Network Time Protocol (NTP) to synchronize computer system clocks automatically over a network. See instructions here.
Back up the anaconda-enterprise-anaconda-platform.yml file used to configure the platform, as config map settings such as external Git configuration are not automatically migrated to the new cluster as part of the upgrade process.
Back up your custom cas-mirror and anaconda-enterprise-cli configurations (see Step 4 below), as $HOME/cas-mirror will be overwritten during the upgrade process. To avoid any compatibility issues, we recommend you upgrade your mirror tools as part of the upgrade process. Afterwards, simply copy over the configuration files you backed up to restore your custom configuration.

Warning

After the upgrade has begun, it won’t be possible to capture or back up data for any open sessions or deployments. We therefore recommend that you ask all users to save their work, stop any sessions and deployments, and log out of the platform during the upgrade window.

Anaconda Enterprise supports in-place upgrades. The upgrade process varies slightly, depending on your current version and which version you’re installing. To update an existing Anaconda Enterprise installation to a newer version, follow the process that corresponds to your particular scenario:

Upgrading from AE 5.4.x to 5.5.0
Upgrading from AE 5.3.x to 5.5.0
Upgrading from AE 5.3.0/5.3.1 to 5.4.x
Upgrading from AE 5.2.x/5.3.0 to 5.3.1

Upgrading from AE 5.4.x to 5.5.0¶

Ensure that all AE users have closed any open sessions, stopped any deployed applications, and logged out of the platform. The backup.sh script that runs as part of the upgrade process will restart all pods, so if they don’t, they will lose any unsaved work.
On the master node running your current installation of AE, download and decompress the new installer, and then cd into the install directory, replacing <location_of_installer> with the location of the installer, and <version> with your installer version:
```
curl -O <location_of_installer>.tar.gz
tar xvzf anaconda-enterprise-<version>.tar.gz
```
Run the following command as a pre-flight check:
```
sudo ./gravity check
```
If the pre-flight check failed, make the applicable corrections as seen on our Installation requirements page.
Run the following command to start the upload and upgrade process:
```
sudo ./upload
sudo ./gravity upgrade
```
Depending on your implementation, the upgrade process may take an hour or more to complete. This is primarily due to the upload step. You can check the status of the upgrade process by running the following:
```
watch sudo ./gravity status
OR
watch sudo ./gravity plan
```
Even after the upgrade process is completed, it will still take some time for the pods to come up. You can monitor those with the following command:
```
watch kubectl get pods
```
If you encounter errors while upgrading, you can check the status of the operation by running sudo ./gravity plan. You can then roll back any step in the upgrade process by running the rollback command against the name of the phase, as it’s listed in the Phase column:
```
sudo ./gravity rollback --phase=/<name-of-phase>
```
After addressing the error(s), you can resume the upgrade by running the following command:
```
sudo ./gravity upgrade --resume --force
```

After the upgrade process completes, follow the steps to verify that your upgrade was successful.

After you’ve confirmed that your upgrade was successful—and everything works as expected—you can run a script to remove images leftover from the previous installation and free up space. This will help prevent the cluster from running out of disk space on the master node.

Upgrading from AE 5.3.x to 5.5.0¶

Anaconda Enterprise 5.3.x and later support in-place upgrades, so you can follow these simple steps to update your 5.3.0 or 5.3.1 installation to the latest version.

Ensure that all AE users have closed any open sessions, stopped any deployed applications, and logged out of the platform. The backup.sh script that runs as part of the upgrade process will restart all pods, so if they don’t, they will lose any unsaved work.
On the master node running your current installation of AE, download and decompress the new installer, and then cd into the install directory, replacing <location_of_installer> with the location of the installer, and <version> with your installer version:
```
curl -O <location_of_installer>.tar.gz
tar xvzf anaconda-enterprise-<version>.tar.gz
```

Curl the shim download and untar the shim download. Then, cd into the shim:

curl -O <location_of_shim>.tar.gz
tar xvzf anaconda-enterprise-<version>-gravity-only.tar.gz
cd anaconda-enterprise-<version>-gravity-only

Run the following command as a pre-flight check:
```
sudo ./gravity check
```
If the pre-flight check failed, make the applicable corrections as seen on our Installation requirements page.
Run the following command to start the upload and upgrade process:
```
sudo ./upload
sudo ./gravity upgrade
```
Depending on your implementation, the upgrade process may take an hour or more to complete. This is primarily due to the upload step. You can check the status of the upgrade process by running the following:
```
watch sudo ./gravity status
OR
watch sudo ./gravity plan
```
Once the upgrade process has completed, change directory to the install directory and rerun the previous step:
```
cd ../anaconda-enterprise-<version>
sudo ./upgrade
```
Depending on your implementation, the upgrade process may take an hour or more to complete. This is primarily due to the upload step. You can check the status of the upgrade process by running the following:
```
watch sudo ./gravity status
```
Even after the upgrade process is completed, it will still take some time for the pods to come up. You can monitor those with the following command:
```
watch kubectl get pods
```
If you encounter errors while upgrading, you can check the status of the operation by running sudo ./gravity plan. You can then roll back any step in the upgrade process by running the rollback command against the name of the phase, as it’s listed in the Phase column:
```
sudo ./gravity rollback --phase=/<name-of-phase>
```
After addressing the error(s), you can resume the upgrade by running the following command:
```
sudo ./gravity upgrade --resume --force
```

After the upgrade process completes, follow the steps to verify that your upgrade was successful.

Upgrading from AE 5.3.0/5.3.1 to 5.4.x¶

Anaconda Enterprise 5.3.0 and 5.3.1 support in-place upgrades, so you can follow these simple steps to update your 5.3.0 or 5.3.1 installation to the latest version.

Ensure that all AE users have closed any open sessions, stopped any deployed applications, and logged out of the platform. The backup.sh script that runs as part of the upgrade process will restart all pods, so if they don’t, they will lose any unsaved work.
On the master node running your current installation of AE, download and decompress the new installer, and then cd into the install directory, replacing <location_of_installer> with the location of the installer, and <version> with your installer version:
```
curl -O <location_of_installer>.tar.gz
tar xvzf anaconda-enterprise-<version>.tar.gz
```

Curl the shim download and untar the shim download. Then, cd into the shim:

curl -O <location_of_shim>.tar.gz
tar xvzf anaconda-enterprise-<version>-gravity-only.tar.gz
cd anaconda-enterprise-<version>-gravity-only

Run the following command to upload the installer to the AE environment:
```
sudo ./upload
```
When the upload process finishes, run the following command to start the upgrade process:
```
sudo ./gravity upgrade
```

Change directory to the install directory and rerun steps 4 and 5 above:

cd ../anaconda-enterprise-<version>
sudo ./upload
sudo ./gravity upgrade

Depending on your implementation, the upgrade process may take an hour or more to complete. You can check the status of the upgrade process by running sudo ./gravity status.

If you encounter errors while upgrading, you can check the status of the operation by running sudo ./gravity plan. You can then roll back any step in the upgrade process by running the rollback command against the name of the phase, as it’s listed in the Phase column:

sudo ./gravity rollback --phase=/<name-of-phase>

After addressing the error(s), you can resume the upgrade by running the following command:

sudo ./gravity upgrade --resume --force

After the upgrade process completes, follow the steps to verify that your upgrade was successful.

Upgrading from AE 5.2.x/5.3.0 to 5.3.1¶

Anaconda Enterprise 5.2.x and 5.3.0 support in-place upgrades, so you can follow these simple steps to update your 5.2.x or 5.3.0 installation to the latest version.

Ensure that all AE users have closed any open sessions, stopped any deployed applications, and logged out of the platform. The backup.sh script that runs as part of the upgrade process will restart all pods, so if they don’t, they will lose any unsaved work.
On the master node running your current installation of AE, download and decompress the new installer, replacing <location_of_installer> with the location of the installer, and <version> with your installer version:
```
curl -O <location_of_installer>.tar.gz
tar xvzf anaconda-enterprise-<version>.tar.gz
cd anaconda-enterprise<version>
```
Run the following command to upload the installer to the AE environment:
```
sudo ./upload
```
When the upload process finishes, run the following command to start the upgrade process:
```
sudo ./gravity upgrade
```
The upgrade process may take up to an hour to complete. You can check the status of the upgrade process by running sudo ./gravity status.

sudo ./gravity rollback --phase=/<name-of-phase>

After addressing the error(s), you can resume the upgrade by running the following command:

sudo ./gravity upgrade --resume --force

After the upgrade process completes, follow the steps to verify that your upgrade was successful.

Verify installation¶

After you’ve verified that all pods are running and updated the Anaconda Enterprise URLs, you can confirm that your upgrade was successful by doing the following:

Return to the Authentication Center and select Users in the Manage menu on the left.
Click View all users and verify that all user data has also been restored.
Access the Anaconda Enterprise user console by visiting this URL in your browser: https://example.anaconda.com/—replacing example.anaconda.com with the FQDN of your server—and logging in using the same credential you used in your previous installation.
Review the Projects list to verify that all project data has been restored.

Note

If you didn’t configure SSL certificates as part of the post-install configuration, do so now. See Updating TLS/SSL certificates for more information.

If you’re upgrading a cluster with external Git configured:

Note

The git section of the anaconda-enterprise-anaconda-platform.yml file used to configure Anaconda Enterprise 5.3.1 includes parameter changes. If you backed up your Anaconda Enterprise config map before upgrading, and copied it onto the newly-updated master node, you’ll need to update your config map with the new information as described here.

If you’re upgrading a Spark/Hadoop configuration:

After you successfully restore your Anaconda Enterprise data, run the following commands on the master node of the newly-installed Anaconda Enterprise server:

kubectl replace -f <path-to-anaconda-config-files-secrets.yaml>

To verify that your configuration upgraded correctly:

Log in to Anaconda Enterprise.
If your configuration uses Kerberos authentication, open a Hadoop terminal and authenticate yourself through Kerberos using the same credentials you used previously. For example, kinit <username>.
Open a Jupyter Notebook that uses Sparkmagic, and verify that it behaves as expected. For example, run the sc command to connect to Sparkmagic and start Spark.

After you’ve confirmed that your upgrade was successful, we recommend you run the following command to remove all unused packages and images from previous versions of the application, and repopulate the registry to include only those images required by the current version of the application:

sudo gravity gc

The command’s progress is displayed in the terminal, so you can watch as it marks packages associated with the latest version as required, and deletes older versions.

If running the command generates an error, you can resume the command (after you fix the issue that caused the error) by running the following command:

sudo gravity gc —-resume