This post is going to explain how to upgrade Tableau server on Windows from version 2018.2 or higher to a higher version. This is also known as a tsm-to-tsm upgade. At the moment of writing this post the highest version is 2021.3 and the maintenance for Tableau servers version 2020.3 and lower is about to end in less than a month: https://kb.tableau.com/articles/issue/Early-End-of-Maintenance-for-Tableau-Products This post is going to have two parts. First part is a bunch of checks you have to perform before upgrading your server and the second part is the instruction on how to upgrade. The more time you spend doing pre-upgrade tasks, the smoother the upgrade will go, so don't ignore them!
1) You are logged in as a user who is explicitly added to the Administrators group
The upgrade has to be performed by a user who is added to the Administrators group. Sometimes you are added to the AD group which is a member of the Administrators group. If that is the case please add yourself directly to the group. Go to Computer Management, choose 'Local Users and groups', then Groups and double-click on the Administrators group. Your username should be displayed as a member of the Administrators group directly.
If you don't know what user you are logged in as, click on start and hover over a little person's logo. It will give you the username.
2) Are the appropriate ports open?
If your firewall is off, you don't need to do anything. You can check this by going to Windows Defender Firewall with Advanced Security. It is off if your Domain Profile, Private Profile and Public Profile says it is off. It should look like this:
If it looks any different (some of the things are in red, some in green), you need to open specific ports. This is especially important if you have a cluster. Open 80, 443, 8850, 8060, 8061 for a single node install and 80, 443, 8000-9000, 27000-27009 for a cluster. More about it here: https://help.tableau.com/current/server/en-us/ports.htm
To open ports, click on Inbound Rules, New Rule… on the right-hand side. In a new pop-up window choose Port. Click next. In the next window paste all the ports at once for example 80,443, 8000-9000, 27000-27009 for a cluster. Click next. Choose: Allow the connection, click next, choose all 3 checkboxes: Domain, Private, Public. Click next. Name the rule Tableau server ports or something along those lines and click Finish.
If you are using a proxy, make sure the 'Bypass proxy server for local addresses' is checked in your Internet Options
3)Non-default directory permissions
If your Tableau server is installed in non-default directory, you need to check your permissions. If you are running Tableau server as a custom domain account like MYDOMAIN\\svc_tableau, that user has to have access to Tableau directories. Add that user into Tableau Server folder and make sure the permissions are applied recursively to all subfolders. In addition 3 Windows accounts have to have access to your non-default folder: System, Networking Service and Local Service. Follow this if you have more questions: https://help.tableau.com/current/server/en-us/runas_confirm_read_ex.htm
4) Licenses
Make sure your licenses are valid. It means the maintenance end date has to be in the future, otherwise the upgrade will fail. Use tsm licenses list command in the Command Prompt to check. You can also check in the TSM web UI on port 8850 under: Configuration->Licensing or logged in to the Tableau web UI as server administrator. If you have many sites, go to 'Manage all sites'. Click on Settings, choose Licences and look for License Expires date.
5) Backup and settings.json files
Make sure you have TWO Tableau supported backups of your environment AKA .tsbak files. You are probably doing backup of your environment every day/week/month, so one of them can be the latest one and the other one can be run before the upgrade. To generate it, use tsm maintenance backup -f upgrade command. Why two and not just one file? If there is an issue with the upgrade, you have to restore the backup and it fails you will have another one to check if it's because of the backup file or your new Tableau environment. As .tsbak file only restores the metadata of Tableau server and not the topology or configuration, you will need the settings.json to restore those. To generate that file run tsm settings export -f settings.json. Put that file and your backups somewhere outside of Tableau server paths.
6) Antivirus
If the antivirus is running on your server, two things have to happen. You need to exclude Tableau directories from the scan and you need to exclude Tableau processes from on-access scanning.
7) Certificates, logos and other custom files
Make sure the certificates you used for SSL, logos and other custom images are stored outside of Tableau server directories.
Now we can start upgrading our server!
Download the appropriate installer from here: https://www.tableau.com/en-gb/support/releases/server For Windows, it is going to be in the Windows section called TableauServer-64bit-VERSION.exe and about 2GB in size. Once you download it right-click on it and run as Administrator. Your server can still be running at this point. First screen is going to ask you to accept terms and conditions, click on the checkbox and click next.
It will detect already existing location of your Tableau server install, click next
It will tell you that you are going to upgrade your existing Tableau version, click next:
For product activation type, there is nothing to check, click on Install.
Here you might get a warning if your computer does not meet the hardware recommendations: https://help.tableau.com/current/server/en-us/server_hardware_min.htm It can be a hard stop if your computer doesn't meet minimum hardware requirements. If you are upgrading from 2019.1, make sure you have 16GB of RAM available, otherwise you won't be able to upgrade. Click on OK if you are ready to upgrade and the installation will start.
It takes some time. Be prepared for 10-20 min of progress bar.
Last page has a very important checkbox on it: 'Automatically launch the upgrade script.' If you are installing on a cluster, go to other nodes and install the new version on them. Make sure you uncheck that box on additional nodes before clicking on OK. Once all nodes have this new version, stop your Tableau server. You can do that with the tsm stop command. Some versions of the upgrade scripts offer to stop the server for you, but I am not sure if all of them have this option, so the best is to stop the Tableau server and then check the checkbox and click OK. It will launch new window when the ugprade-tsm script will run. It will run for several hours and have many loops going from 1-100%. If you want to monitor your upgrade with tsm jobs list, there will be about 14 different jobs running one after another and at some point the tsm jobs list command might not work.
If you forget to click the checkbox, you can run that job by going to your Tableau server install directory for example C:\\Program Files\\Tableau\\Tableau Server\\packages\\scripts.<version_code>\\ and run upgrade-tsm script (remember to open the Command Prompt as Administrator)
All done successfully? Close the Command Prompt and open it again. Now you can run tsm version to check if all looks good and then the tsm start for your server.
Something went wrong? You can try googling it and fix the issue. Most of the issues have to do with the lack of disk space and you can recover from some of them. If not, you need to move all the files you collected throughout this tutorial (backups, settings.json files, logos, certs etc) to a network drive or another safe location away from tablau directories, then you are going to remove the server (this will remove everything from your ccomputer) with the obliterate script: https://help.tableau.com/current/server/en-us/remove_tableau.htm Then you will install a new version and restore your backup.tsbak and settings.json file. I will try to expand this section in the future.