Breaking the Myths - Tableau Server Upgrade to version 2020.3.x

This blog covers detailed steps to upgrade Tableau Server to version 2020.3.x (latest version available at the time of writing this blog) from version 2019.2.x. Though upgrade process is very well documented on tableau website but would also like to share my experience which can make process smoother for others planning their tableau upgrade in coming time. The process is not very different for other versions as well and most part of this blog will cover almost all the scenarios and enterprise level recommendations.

Audience: This blog is intended for Tableau Server Administrators, Tableau Server Architects and Tableau Developers having prior understanding of managing tableau server and it's upgrade process.

Follow along this blog if your setup also consists of following:

    1. Using Linux version of tableau deployment.

    2. Tableau server version 2019.2.x.

    3. Single Node Installation (for Multi node installation major steps remains same).

Any deviation from above would request to review the tableau documentation but flow and most of the steps remains same.

Blogger Special Note : Most critical part of doing an upgrade is the preparation before that, better you prepare, perform all checks and pre-requisites, the upgrade will be smoother. 

Here is the list down of all the checks, which you need to perform prior to upgrade tableau server:

Step1: Blue Print Upgrade planning - This steps includes various sub sections are discussed as below:

    a) Tableau servers updates comes every quarter and it can also include some architectural changes. That would also mean any upgrade would be first needs to be tested in lower environment prior to production and then move to higher environments. Running the upgrade once in test environments not only make you familiar with entire upgrade process but it will also tell you how your content behaves to new architectural changes and version upgrade.

    b) Communication Upgrade : Since almost all the organizations are using tableau as a central solution, isolated based on projects or sites. It's important to communicate the upgrade dates and timelines to developers, support team and end users. This can be done by any mode of your liking but tableau also provides a way of doing it.

    Under "Server setting =>  General". There is a section named "sign in customization". We can place the message in this section which will notify every user which logs in to the tableau server site. Important to note this only works in 2020 as per my experience (not at least with 2019.2), hence can be used next time you upgrade.

    c) Other Vital Factors : There are other factors which needs to be considered in blue print planning:

            1. Verify what all new features are added between the version you are upgrading from.

            2. Verify the changes in upgrade process from tableau documentations.

            3. Validate needed capacity available for upgrade.

            4. Provision the hardware needed for the process if migration and in case of in-place upgrade verify the minimum requirement for the version you are upgrading to (discussed in next step).

For more details on this section reach out to tableau website : Preparing for Upgrade - Tableau

Step2: Hardware Requirements - In order to upgrade to version 2020.3.x for Single node installation we would need minimum of:

    a) CPU - 8 Core 2.0 GHz or Higher

    b) Memory - 32 GB or Higher

    c) Storage - 50 GB or Higher

Check the documentation for multiple node type installations. Also check the OS compatibility with the tableau software. Normally RHEL7 are well suited for tableau 2020.3.x installations.

For more details on this section reach out to tableau webiste : Server Upgrade - Minimum Hardware Recommendations - Tableau

Step3: Change Review - It's important to know all the features and changes between the version you are upgrading from and to the version you are upgrading to. This will give you good insight in understanding features and changes, to be able to guide you are the expectations from the upgrade. Another important place to review is open issues with the current version which you are planning to upgrade. I would always suggest to upgrade to N-1 version (one version lesser to latest one) but situations and things would not be same in all cases and you need to use your own judgment. Some influencing factors for your decision would be features you want to use and stability of the version.

Below are some important links to help you in above decisions:

    Latest release: Tableau Server Release Notes and Download (Link)

    All releases: All Tableau Server Release Notes(Link)

    Known issues: Tableau Server Known Issues(Link)

Step4: Gather Configuration Details - In case of any upgrade failure one may need the details of configuration prior to upgrade. Normally for in-place upgrade usually configuration is kept same but it make sense to have details of configuration for your tableau server and that can be referenced in case of any eventuality.

    a) Taken screen shots of pages and tab under TSM Web UI and Tableau Server Admin Area.

    b) Record Object counts - Project, workbooks, views, data sources, users and groups.

    c) Asset Files - Supporting files for your tableau configuration. Not all may be applicable in your case but preserve ones which is used in your setup.

            SAML certificate file

            SAML key file

            SAML IdP metadata file

            The custom certificate installed by tsm security custom-cert add

            OpenID.static.file

            Kerberos.keytab file

            LDAP Kerberos keytab file

            LDAP Kerberos conf file

            Mutual SSL certificate file

            Mutual SSL revocation file

            Customization header logo file

            Customization sign-in logo file

            Customization compact logo file

    d) Gather custom configuration information

    e) SMTP Configuration

        tsm configuration get -k svcmonitor.notification.smtp.ssl_ciphers

    f) Analytics Extension 

        tsm security vizql-extsvc-ssl list

    g) Port customization

        tsm topology list-ports

    h) Record firewall configuration

        firewall-cmd --list-all (as root)

    i) Verify TSM Controller Certificate Expiry

         openssl s_client -connect <machine name>:8850

         echo | openssl s_clinet -connect <machine name>:8850 2>/dev/null | openssl x509 -noout -dates

    In case certificate is expired reach out to tableau support before proceeding for upgrade.

Step5: Validate License - Prior to upgrade compare the product keys and it's expiration with customer portal. In case of any discrepancy it needs to be corrected prior to upgrade.

In order to view the current license on the server run:

    tsm licenses list

If needed you can refresh the licenses through:
    a)   Open TSM in a browser:

        https://<machine name>:8850

    b) Click Configuration and Licensing and Click Refresh All.

If this also doesn't fixes any discrepancy in licenses, reach out to Tabeau support.

Step6: Backup Tableau Server - This is one of most critical steps before the Tableau server upgrade and would highly recommend to take mandatory take full backup backup, which will enable us to restore the tableau server back to previous version in case of any rollback scenarios.

Taking full tableau server backup also have certain considerations:

    a) Disable any schedule or subscription prior to backup and re-enable them once backup is completed. This will avoid duplicate notification in case of restoration of backup set on any test server and comes under good practice.

    b) Full backup can take long time based on your environment and extracts,  so plan the backup accordingly. This may lead to frustration on the upgrade day and can take couple of hours, would suggest to use to previous end of the day backup and also notify users not to make any changes after that if possible (this may not be possible in all situations, so decide based on your suitability). Any change done post backup, the changes will be lost in case of any restore scenarios.

    c)  Backup should be kept outside local filesystem (probably NAS) as in some scenarios obliterate script would wipe out entire directory which includes your backup. To keep backup safe is critical and should be seriously taken.

    d) Take tableau server repository backup

        tsm maintenance backup -f <backup_file> -d

    e) Take tableau server configuration backup

        tsm settings export -f <file_name>.json

Step7: Download Software - In order to upgrade tableau server one would need to download the software binary from tableau website. If you use tabcmd client utility it would be good idea to get that as well and upgrade the clients post upgrade.

Along with Server side software, one would need to download upgraded version of tableau desktop, tableau reader and tableau prep based on your usage.

Software can be downloaded from tableau website - Link

Step8: Understand How upgrade works - While upgrading from tableau server version 2018.2 and later we don't need to un-install the earlier tableau version before upgrade on the tableau server.

We would need to install 2020.3.x binary along with old binary and can be done in advance to upgrade. Both old and new binary can co-exists. Later post upgrade tableau will switch to new binaries and old binary can be removed. In case you un-install previous version before upgrade process, upgrade may fail or you may not even allow you to upgrade.

Actual downtime starts when you run the upgrade script, until now all the steps can be done keeping your existing tableau server up and running. 

Blogger Special Note: In order to keep downtime minimum perform binary installation prior stopping the process as it's an online operation and no impact on existing binaries.

During the tableau server upgrade tableau server services need to be stopped and re-started later. In order to install binaries one can use yum method or for custom directory installation use rpm. In this case we are showing example of custom directory installation using rpm method. Before rpm installation, identify & install all the dependencies else rpm installation will fail. In order to identify dependency for a tableau server rpm use following:

    yum deplist <tableau-server>.rpm

Once dependencies are in place install the binaries using rpm based method for custom installation:

    sudo rpm -i --prefix /preferred/install/patch <tableau-sever>.rpm

Step9: Perform Tableau Server Upgrade - Performing actual tableau server upgrade process is very easy and will be smooth for you if you have performed all the previous steps mentioned earlier in the blog. All the steps for actual upgrade process are listed as following:

    a) Complete Upgrade Preparation - Make sure all steps mentioned in this blog from Step1 to Step8 are done. Don't proceed if they are not done and revisit them.

    b) Disable if any scheduler jobs are present.

    c) Single Node Installation - This blog mention single node upgrade steps (for Multi node upgrade there are additional steps and one may need to visit tableau upgrade guide for more details)

    d) Stop the tableau server services running the older version.

        tsm stop

    d) Run the tableau server setup with upgrade script.

        sudo /tableau directory/packages/scripts.<version>/upgrade-tsm --accepteula

    Note : In case one want to use help use upgrade-tsm -h, this will list down all options for upgrade tsm script. This step may take time based on your tableau server setup and size. Review the upgrade logs for any errors reported.

After upgrade is completed successfully, logout and login with new terminal for setting new environment variables.

    e) Start the tableau server services post upgrade from new binaries:

        tsm start

    e) Verify the upgrade

            1. Verify all the setting and configuration preserved in pre-steps and make sure they looks similar.

            2. Enable subscription and scheduling.

            3. Verify user access.

            4. View Published workbooks

            5. Publish workbooks and data sources and verify once.

            6. Verify tableau prep builder (if used).

            7. Verify count of tableau objects.

            8. Verify API functionality

            9. Compatibility testing. 

Step10: Post Upgrade Cleanup : Un-install previous tableau server binaries, this step is not mandated to be done immediately and can be done later as needed. This will just make sure to clear down space being utilized by these old version binaries. 

    rpm -e <tableau serer rpm>  (for non default installation)

Step11: Upgrade Client Tools : Ask developers to upgrade their Tableau Desktop to same version to that of tableau server. It's very important to develop on the same version software similar to server to avoid compatibility issues. 

It would need to upgrade tabcmd clients in case used to the version 2020.3.x.

This completes the server upgrade process and you can see the entire upgrade process is straight forward and simple. The only bullet point for upgrading successfully if to perform a test upgrade and run through all pre-upgrade steps properly.

Reference Links:

    Tableau Upgrade - Preparing for Upgrade - Tableau