Prepare for the Upgrade
To properly prepare for a Tableau Server upgrade, gather the following information about your existing installation, key files related to your installation and the upgrade, and complete the pre-upgrade tasks.
Gather custom configuration information
If you are upgrading on the existing hardware your configuration will be preserved, but it's a good practice to collect this configuration information about your existing installation for several reasons: you need this information when you configure a test environment, you need this information if you are migrating to new hardware migration as part of the upgrade, and you can use the information to confirm that the upgraded Tableau Server is configured as expected if you notice something unexpected after upgrading.
Collect this information and any associated files and save them to a location that is not on any of the Tableau Server computers.
The following list includes examples of the type of information you should gather:
Customizations This includes non-default ports, timeout values, custom logo images, and fonts.
Also make a note of Windows path environment variables that affect Tableau Server.
For pre-TSM versions of Tableau Server (versions 2018.1 or earlier), you can see your current SMTP configuration on the SMTP Setup tab of the Configuration utility.
For more information, see Configure SMTP Setup.
SSL configuration and certificates.
For pre-TSM versions of Tableau Server (versions 2018.1 or earlier), you can see your SSL configuration on the SSL tab of the Configuration utility. This tab also lists the location of the certificate and certificate key files. You should copy and save these files in a safe location.
For more information, see Configure SSL for External HTTP Traffic to and from Tableau Server.
SAML configuration, certificates and any IdP metadata files.
For pre-TSM versions of Tableau Server (versions 2018.1 or earlier), you can view your current SAML configuration on the SAML tab of the Configuration utility, including the certificate, key, and metadata files. Save copies of these files to a safe location.
For more information, see SAML.
For pre-TSM versions of Tableau Server (versions 2018.1 or earlier), you can see your current Kerberos configuration on the Kerberos tab of the Configuration utility, including the location of the keytab file you should copy and save.
For more information, see Configure Kerberos.
For pre-TSM versions of Tableau Server (versions 2018.1 or earlier), you can find your current OpenID configuration details on the OpenID tab of the Configuration utility.
For more information, see Configure Tableau Server for OpenID Connect.
Additional node configurations. Collect the configurations of any additional Tableau Server nodes, including any certificates or other supporting files that you copied to these nodes.
For pre-TSM versions of Tableau Server (versions 2018.1 or earlier), you can find detailed information about the number of processes configured on each node on the Servers tab of the Configuration utility.
Other values. Note the number of projects, groups, workbooks, views, data sources, and users you have in your production environment. Having this information makes it easy to do a quick check after the upgrade to make sure everything was restored as expected.
Gather the environment configuration
The steps you need to take during the upgrade process depend on whether you're installing the upgrade on the same hardware or you're migrating to new hardware. Upgrading on the same hardware is straightforward and requires a minimum of manual steps (the steps you need to take depend on what version you are upgrading from, what version you are migrating to, and whether or not your existing installation is in the default location). Migrating to new hardware requires you to manually restore your Tableau Server data and reconfigure your settings after you install the new version.
Copy the setup files to a local file share
You will need the following setup files before you upgrade Tableau Server:
Setup programfor your existing version of Tableau Server.
You might not need the
Setup program. However, we recommend that you have it available in case there's a problem during the upgrade. That way you can use the setup program and your server backup to restore your installation to its pre-upgrade state.
Note: If you do not have the
Setup programfor your existing version, you can download it from the Alternate Downloads Site. Save the Setup programin a safe location that is not part of your production or test version of Tableau Server. You will need the Setup program if you need to go back to your existing version after upgrading.
The setup program for the new version of Tableau Server.
A new version of tabcmd is released with every release of Tableau Server. If you install tabcmd on computers that are not part of your Tableau Server installation, you need to update tabcmd on those computers. For more information, see tabcmd.
Back up Tableau Server data
We recommend that you make a backup of your installation of Tableau Server before beginning the upgrade process. This provides data that you'll need to set up a test version of the upgraded environment. It also lets you recover if the upgrade process fails.
Backups from versions of Tableau Server older than version 9.x cannot be used with version 2018.2.x or later. If you are running an older version of Server, you may need to do an intermediate upgrade to version 9.x through 10.x before upgrading to version 2018.2 or later.
We recommend you disable subscriptions and scheduling in your production environment immediately before taking the backup, and reenable them after the backup is complete. Doing this will help avoid having your users receive duplicate subscriptions and email messages when you restore your backup in your test environment.
The full backup can take a while if you have a large installation or a lot of extracts.
Any changes made between the time you took the backup and the time you do the upgrade are lost because they aren't included in the backup.
You can only restore from a backup that has the same type of identity store as the running server. For example, a backup from a server using local authentication can be restored to a Tableau Server initialized with local authentication, but a backup from a server using Active Directory authentication cannot be restored to a server initialized with local authentication.
Generate asset keys file before uninstalling Tableau Server for Windows 2018.1.x or earlier
If you are upgrading from Tableau Server on Windows version 2018.1.x or earlier, and you generated a custom asset key, save a copy of the
asset_keys.yml file before you uninstall your earlier version. Store this file in a safe place that is not part of your Tableau Server installation (a network share for example).
In most cases you will not need this file. The upgrade process updates asset keys automatically when an upgrade is successful. You only need this file if the upgrade fails and you need to install a new version of Tableau Server and manually restore your backup file. In this case, you also need to specify the asset keys file when doing the restore.
Locating an existing asset keys file
If you generated a custom asset key file, you will have an
asset_keys.yml file in the data directory. By default this is:
If you do not see an asset_keys.yml file, you can skip this.
Restoring a pre-2018.2 Tableau Server for Windows backup along with asset keys
To manually restore a backup from Tableau Servers for Windows 2018.1.x or earlier, and include asset keys, use tsm, for example:
tsm maintenance restore --file <backup> --ak <asset_key_file>
For more information, see tsm maintenance restore.
Check your product maintenance status
If you attempt to upgrade a Tableau Server installation that has a product key with expired maintenance, your upgraded Tableau Server will be unlicensed and the upgrade may fail. Before upgrading, make sure that the server's maintenance hasn't expired.
If your maintenance has expired, select the product key and then click Refresh. If this does not update the maintenance date, check the Tableau Customer Portal for a replacement Tableau Server product key with a later maintenance date. For any questions or concerns, please contact Tableau Technical Support. Reactivating the product key will be part of the upgrade process.
For more information, see Activate and Register Tableau Server. If your server doesn’t have internet access, see Activate Tableau Server Offline - Adding a License.
Important: If you are upgrading from Tableau Server version 2018.1 or earlier, make sure the Manage Product Keys application is closed before you uninstall Tableau. Leaving it open may result in a failed upgrade.
Disable your extract refreshes
Beginning in 10.5, extracts use .hyper format instead of .tde. Once the file format has been upgraded to .hyper, it cannot be reverted back to .tde format and cannot be opened in Tableau Desktop version earlier than 10.5. For more information, see Extract Upgrade to .hyper Format.
The following tasks on Tableau Server will upgrade a .tde extract to a .hyper extract:
A scheduled full or incremental extract refresh
Automated refresh tasks that are performed through tabcmd, Extract API 2.0, or through Extract Command Line Utility
Automated append data to an extract using tabcmd or using the Extract Command Line Utility
Note: We recommend that you disable any automated tasks and schedules that result in an extract upgrade. If you have desktop versions that have not yet been upgraded to 10.5, your desktop users will not be able to open the upgraded .hyper extracts. You may also want to first test a few extracts manually after doing the server upgrade, and then reenable any schedules or automated refresh tasks.
For more information about extract refresh scheduling, see Enable Extract Refresh Scheduling and Failure Notification.
Ensure that your license has enough user capacity
When upgrading from a Tableau 2018.1 or earlier license with legacy site roles, all users are automatically mapped to their current equivalent site role. Before upgrading, it’s important to make sure that your new license supports the number of users you have. Otherwise, some users may become unlicensed after the upgrade.
The following table shows the mapping of the legacy site roles to the current site roles.
|2018.1 legacy site role||2018.1 user-based site role||2018.2 and later site role|
|Server Administrator||Server Administrator||Server Administrator|
|Site Administrator||Site Administrator Explorer||Site Administrator Explorer|
|Publisher||Explorer (can publish)||Explorer (can publish)|
Users always use the highest level role they have on any site, which is called the Maximum Site Role. You can view the Maximum Site Role is for users before you convert your license. For more information, see Permissions.
If you have more users than licenses for your current roles, you should reallocate or balance users to the available roles by changing their role, unlicensing users, or moving users. You can use the following steps to synchronize groups of new users after upgrading to 2018.2 or later:
Unlicense all users.
Create five Active Directory (AD) groups (one for each site role).
Import users into the correct AD group for the appropriate site role, and then sync those groups with Tableau Server. For more information, see Create Groups via Active Directory.
Restart Tableau Server. Users are automatically migrated into their new site roles. Content permissions are not affected.
Plan your strategy if you use virtual machines (VMs)
If you run Tableau Server on VMs, either locally, or in the cloud, be aware of the potential for complications related to licensing. If you are simply upgrading Tableau Server on the VM, you do not need to take any extra action related to licensing. If you plan to clone the VM to create either a new production or test environment to upgrade, you need to deactivate any Tableau Server licenses before cloning. If you do not do this, the new VM environment can end up with an untrusted license, and any attempts to upgrade will fail. You may also end up hitting the maximum number of activations for the licenses.
To avoid issues with licensing on VMs, deactivate all Tableau licenses before cloning a VM or allowing it to be permanently shut down.