Skip to content

Upgrade existing clusters on from version 2.4 or newer (AWS)#

This guide shows you how to upgrade your existing Hopsworks cluster to a newer version of Hopsworks.

Step 1: Make sure your cluster is running#

It is important that your cluster is Running. Otherwise you will not be able to upgrade. As soon as a new version is available an upgrade notification will appear.

You can proceed by clicking the Upgrade button.

New version notification
A new Hopsworks version is available

Step 2: Add backup permissions to your cross account role#


You can skip this step if you already have the following permissions in your cross account role:

[ "ec2:RegisterImage", "ec2:DeregisterImage", "ec2:DescribeImages", "ec2:CreateSnapshot", "ec2:DeleteSnapshot", "ec2:DescribeSnapshots"]

We require some extra permissions to be added to the role you have created when connecting your AWS account as described in getting started guide. These permissions are required to create a snapshot of your cluster before proceeding with the upgrade.

First, check which role or access key you have added to, you can go to the Settings tab, and then click Edit next to the AWS cloud account

AWS account settings
Cloud Accounts

Once you have clicked on Edit, you will be able to see the current assigned role

AWS cross-account role
AWS Cross-Account Role

Once you get your role name, navigate to AWS management console, then click on Roles and then search for your role name and click on it. Go to the Permissions tab, click on Add inline policy, and then go to the JSON tab. Paste the following snippet, click on Review policy, name it, and click Create policy.

    "Version": "2012-10-17",
    "Statement": [
            "Sid": "HopsworksAIBackup",
            "Effect": "Allow",
            "Action": [
            "Resource": "*"

Step 3: Run the upgrade process#

You need to click on Upgrade to start the upgrade process. You will be prompted with the screen shown below to confirm your intention to upgrade:


No need to worry about the following message since this is done already in Step 2

Make sure that your cross-account role which you have connected to has the following permissions: [ "ec2:RegisterImage", "ec2:DeregisterImage", "ec2:DescribeImages", "ec2:CreateSnapshot", "ec2:DeleteSnapshot", "ec2:DescribeSnapshots"]

AWS Upgrade Prompt
Upgrade confirmation

Check the Yes, upgrade cluster checkbox to proceed, then the Upgrade button will be activated as shown below:


Currently, we only support upgrade for the head node and you will need to recreate your workers once the upgrade is successfully completed.

AWS Upgrade Prompt
Upgrade confirmation

Depending on how big your current cluster is, the upgrade process may take from 1 hour to a few hours until completion.


We don't delete your old cluster until the upgrade process is successfully completed.

AWS Upgrade starting
Upgrade is running

Once the upgrade is completed, you can confirm that you have the new Hopsworks version by checking the version on the Details tab of your cluster.

Error handling#

There are two categories of errors that you may encounter during an upgrade. First, a permission error due to missing permission or a misconfigured policy in your cross-account role, see Error 1. Second, an error during the upgrade process running on your cluster, see Error 2.

Error 1: Missing backup permissions#

If one or more backup permissions are missing, or if the resource is not set correctly, you will be notified with an error message as shown below:

AWS Upgrade Retry
Upgrade permissions are missing

Update you cross account role as described in Step 2, then click Start. Once the cluster is up and running, you can try running the upgrade again.

Error 2: Upgrade process error#

If an error occurs during the upgrade process, you will have the option to rollback to your old cluster as shown below:

Error during upgrade
Error occurred during upgrade

Click on Rollback to recover your old cluster before upgrade.

Rollback prompt
Upgrade rollback confirmation

Check the Yes, rollback cluster checkbox to proceed, then the Rollback button will be activated as shown below:

Rollback prompt
Upgrade rollback confirmation

Once the rollback is completed, you will be able to continue working as normal with your old cluster.


The old cluster will be stopped after the rollback. You have to click on the Start button.