Tableau Server Upgrade 2023.3 to 2025.3: We Migrated Regions Under Pressure

Sometimes you plan upgrades months in advance. Sometimes the world makes the decision for you.

This is the first post in a series about how we migrated a client’s entire data stack from AWS Bahrain (me-south-1) to an EU region under pretty stressful circumstances. We’re talking databases, ETL pipelines, BI tools - the whole thing. This post covers the Tableau Server piece specifically - how we upgraded from 2023.3 to 2025.3 and moved it to the new region.

What happened

Our client had their entire data platform running in AWS Bahrain region. Tableau Server, databases, data pipelines - everything was there. The Tableau version was 2023.3 which honestly was already getting long in the tooth and out of Tableau’s support window.

Then the regional conflict escalated. The AWS Bahrain region got impacted and we were staring at a situation where the whole infrastructure was at risk. We needed to act fast.

After a quick discussion with the client’s stakeholders, we made the call - we’re not just moving one thing, we’re moving everything to an EU region. And since we’re rebuilding anyway, lets use this as an opportunity to upgrade Tableau Server from the unsupported 2023.3 to the latest 2025.3.

The full data stack migration is a story for upcoming posts. This one zooms into the Tableau upgrade and migration specifically - which was plenty complicated on its own.

Why blue/green deployment

We went with a blue/green deployment approach for this. For those unfamiliar - blue is your existing production environment, green is the new one you’re building. You run them in parallel, validate the green one, then switch traffic over.

This was the right call here because:

• Zero downtime - the old server (blue) stays running while we build and validate the new one
• Easy rollback - if something goes wrong on green, blue is still there
• OS change required - Tableau 2025.3 dropped support for Amazon Linux 2 and CentOS 7. Our old server was on Amazon Linux 2. So an in-place upgrade wasnt even possible
• Clean slate - starting fresh in a new region meant we could set everything up properly from scratch

Setting up the infrastructure

First things first - this wasn’t just a Tableau migration. We moved the client’s entire data stack to the EU region - databases, ETL pipelines, everything. So Tableau was one piece of a much larger migration. We’ll share the full story of how we migrated the complete data infrastructure in upcoming posts.

Since everything was moving to the same region, we didn’t need any cross-region VPC connectivity hacks. We provisioned the new VPC, subnets, security groups - the usual stuff - and all the data sources were going to be right there in the same region.

For the EC2 instance we went with:

• AMI: amazon/al2023-ami-2023 (Amazon Linux 2023)
• Instance type: r5.8xlarge (Tableau needs serious RAM - 128GB minimum since version 2022.3)
• Storage: 650GB EBS
• Timezone: UTC

Installing Tableau Server 2025.3

This is where things got interesting. Going from 2023.3 to 2025.3 skips a bunch of major versions and there are quite a few breaking changes you need to know about.

Breaking changes we had to deal with

OS support dropped - The biggest one. Tableau 2025.1 onwards dropped support for CentOS 7, RHEL 7, Amazon Linux 2, and older Ubuntu versions. Amazon Linux 2023 is now supported which is what we went with.

Identity service changes - Starting from 2022.1, Tableau introduced a new identity management schema. When you restore a backup from an older version into 2025.3, you’ll hit this error:

“The backup cannot be restored because Tableau Server uses the new identity service tables by default.”

We had to enable legacy identity mode before restoring. More on this later.

Deprecated connectors - Marketo and Oracle Eloqua connectors are deprecated and will be removed in 2026.1. Web Data Connector is also deprecated in favour of the REST API Connector. Worth checking if your workbooks use any of these.

Snowflake heads up - If you’re on 2025.3.1 specifically, there’s a known issue that can break Snowflake live connections and extract refreshes using embedded username/password credentials. Something to watch out for.

Key new features in 2025.3

Not all doom and gloom though. Some genuinely useful stuff landed:

• Tableau Agent is now GA (needs OpenAI API key)
• SCIM provisioning - provision users and groups from your IdP
• SAML REST APIs - programmatic SAML config and certificate rotation
• OpenID Connect single logout support
• Semantic models that you can reuse across workbooks

The actual installation

Created the tableau admin user and set up the basics:

sudo useradd -m tableau-admin
sudo passwd tableau-admin

# Add to sudoers
sudo visudo
# tableau-admin ALL=(ALL) ALL

Downloaded and installed the 2025.3 RPM:

sudo dnf update -y
sudo dnf install wget -y
wget https://downloads.tableau.com/esdalt/2025.3/tableau-server-2025-3-0.x86_64.rpm
sudo dnf install tableau-server-2025-3-0.x86_64.rpm -y

Note we’re using dnf here instead of yum - Amazon Linux 2023 uses dnf as the package manager. Small thing but it’ll trip you up if you’re used to the old AL2 workflow.

Initialize TSM and accept the EULA:

cd /opt/tableau/tableau_server/packages/scripts.<version>/
sudo ./initialize-tsm --accepteula
exit
source /etc/profile.d/tableau_server.sh

Activate the license and register:

tsm licenses activate -k <product-key>
tsm register --file registration.json

Configure the identity store and apply:

tsm settings import -f config.json
tsm pending-changes apply
tsm initialize --start-server

Create the initial admin user:

tabcmd initialuser -s localhost -u tableau.admin --password <PASSWORD>

Taking the backup from Bahrain

This part was nerve-wracking given the regional situation. We needed to get a clean backup out as quickly as possible.

# On the old server in Bahrain
tsm maintenance backup --file pre-migration-backup --append-date

# Copy backup to S3
aws s3 cp /var/opt/tableau/tableau_server/data/tabsvc/files/backups/pre-migration-backup-<date>.tsbak s3://<backup-bucket>/

Then from the EU region, pull it down:

# On the new server in EU
cd /var/opt/tableau/tableau_server/data/tabsvc/files/backups
aws s3 cp s3://<backup-bucket>/pre-migration-backup-<date>.tsbak .

Restoring the backup - the identity service gotcha

This is the part where most people get stuck during a major version upgrade. When you try to restore a backup from a pre-2022.1 identity service era into 2025.3, it just refuses.

The fix is to enable legacy identity mode first:

tsm authentication legacy-identity-mode enable
tsm pending-changes apply

Now restore:

tsm stop
tsm maintenance restore --file pre-migration-backup-<date>.tsbak
tsm start

After the restore completes, you need to handle the identity migration:

1. Go to Users > Identity Migration page in the Tableau Server UI
2. Check that migration has started automatically
3. Resolve any identity conflicts (we had a few duplicate users that needed sorting)
4. Wait for Migration Overview to show 100% complete

Then switch back to the new identity service:

tsm authentication legacy-identity-mode disable
tsm pending-changes apply

Installing the data source drivers

Tableau server is only as good as the drivers it can talk to. We needed to install drivers for all the data sources our client connects to. This is one of those things people forget about and then wonder why their dashboards are broken.

# PostgreSQL JDBC driver
wget https://downloads.tableau.com/drivers/linux/postgresql/postgresql-42.7.3.jar
sudo mkdir -p /opt/tableau/tableau_driver/jdbc
sudo cp postgresql-42.7.3.jar /opt/tableau/tableau_driver/jdbc/

# Microsoft SQL Server ODBC
sudo dnf install -y unixODBC-devel
curl https://packages.microsoft.com/config/rhel/9/prod.repo | sudo tee /etc/yum.repos.d/mssql-release.repo
sudo ACCEPT_EULA=Y dnf install -y msodbcsql18

# MySQL ODBC
sudo dnf install -y mysql-connector-odbc

# Oracle JDBC
# Download ojdbc8.jar from Oracle's JDBC downloads page
sudo cp ojdbc8.jar /opt/tableau/tableau_driver/jdbc/

Note: for Amazon Linux 2023 we used the RHEL 9 compatible repos for Microsoft drivers since AL2023 is based on Fedora. The old RHEL 7 repos that worked on Amazon Linux 2 won’t work here.

After installing all drivers, restart Tableau:

tsm stop
tsm start

Configuring SAML

The client uses SAML for SSO so we needed to set that up on the new server. The certificates and metadata from the IdP were already available so this was fairly straightforward:

tsm authentication saml configure \
  --idp-entity-id <entity-id> \
  --idp-return-url https://<new-tableau-url> \
  --cert-file /path/to/saml-cert.crt \
  --key-file /path/to/saml-key.key

tsm authentication saml enable
tsm pending-changes apply

We exported the metadata XML and shared it with the client’s identity team to update their IdP configuration:

tsm authentication saml export-metadata -f tableau-metadata.xml

One nice thing about 2025.3 - there are now SAML REST APIs for programmatic configuration. Didnt use them this time but will definitely leverage that for future setups where we need to automate certificate rotation.

Setting up Google OAuth

Since the client had workbooks connecting to Google Sheets and Google Drive, we needed to configure Google OAuth:

tsm configuration set -k oauth.google.client_id -v <client_id>
tsm configuration set -k oauth.google.client_secret -v <client_secret>
tsm configuration set -k oauth.google.redirect_uri -v https://<new-tableau-url>/auth/add_oauth_token
tsm pending-changes apply
tsm restart

Custom branding

We copied over the client’s custom logo from the old server and applied it:

tsm customize --logo "client-logo.jpeg"
tsm pending-changes apply

Small thing but the users notice when their branding disappears. See our guide on how to customize your Tableau Server logo for more details on this.

Enabling repository access

For monitoring and reporting purposes, we enabled readonly access to the Tableau repository:

tsm data-access repository-access enable --repository-username readonly --repository-password <PASSWORD>

This is handy if you want to build custom admin dashboards or pipe Tableau metadata into your monitoring stack.

Validation and testing

After everything was setup, we immediately disabled all scheduled extract refreshes and subscriptions on the new server. You dont want the green environment firing off duplicate jobs while you’re still validating.

Our testing checklist:

• User authentication - SAML login working, all user groups present
• Dashboard rendering - spot checked key dashboards across different sites
• Data connections - verified live connections and extracts for each data source type
• Extract refreshes - manually triggered a few to confirm drivers work
• Subscriptions - tested email delivery with SSL enabled
• Logs - checked tsm status -v and reviewed logs for any errors
• Search index - sometimes groups disappear after an upgrade restore. If that happens, rebuild the search index:

tsm stop
tsm maintenance reindex-search
tsm start

The non-prod rehearsal

Before doing any of this in production, we ran through the entire process on a non-prod environment first. Same steps, same backup, same configuration. This let us:

• Identify the identity service migration issue before it hit us in prod
• Time the whole process so we could give stakeholders a realistic maintenance window
• Validate that all data source drivers were accounted for
• Make sure SAML was going to work with the new URL

If you’re planning a similar migration, dont skip this step. Seriously. The few days it takes to do a dry run will save you from a lot of pain during the actual cutover.

The cutover

Once everything was validated on non-prod and the client’s stakeholders signed off, we scheduled the production cutover. The process:

1. Took a final backup from the blue (Bahrain) server
2. Restored it to the green (EU) server
3. Ran through the abbreviated test checklist
4. Re-enabled all schedules and subscriptions
5. Updated DNS to point to the new server
6. Monitored for 48 hours before decommissioning the old server
7. Deactivated the old license keys

The whole cutover window was about 4 hours. Most of that was the backup/restore and validation - the actual DNS switch was minutes.

Lessons learned

A few things we’d do differently or want to call out:

1. Document your drivers - Before you start, get a complete list of every data source type used in Tableau. Missing one driver means broken dashboards and angry users.

2. The identity migration is real - Don’t ignore it. If you’re jumping multiple major versions, you will hit the identity service change. Enable legacy mode, restore, migrate, then disable legacy mode.

3. Amazon Linux 2023 is not Amazon Linux 2 - Package managers are different (dnf vs yum), repo paths are different, some packages have different names. Don’t assume your old scripts will work.

4. Test SAML early - IdP teams often need lead time to update their configuration. Start that conversation early in the process.

5. S3 cross-region copy - When your backup file is large (ours was ~80GB), the S3 transfer between regions takes time. Plan for it.

6. Keep the old server running - Having the blue environment available as a fallback gave everyone confidence during the cutover. Don’t rush to tear it down.

Wrapping up

What started as an emergency turned into a solid upgrade. The client is now on a supported Tableau version with better performance, running in a stable EU region, with all the new 2025.3 features available to them.

But like we said - Tableau was just one piece of the puzzle. In upcoming posts we’ll cover how we migrated the rest of the data stack to the EU region - the databases, the ETL pipelines, the networking, all of it. Stay tuned for those.

If you’re still running Tableau Server on an older version or on a deprecated OS like CentOS 7 or Amazon Linux 2, its worth planning the upgrade now rather then waiting for a crisis to force your hand. The blue/green approach makes it manageable even for large deployments.

For more Tableau tips, check out our posts on backing up Tableau to S3, creating personal access tokens, and connecting Tableau to Athena.

---

Need help upgrading your Tableau Server?

Upgrading across multiple major versions while changing OS and region is not something you want to figure out on a Friday afternoon. We have been there, done that, and have the battle scars to prove it.

Our team provides Tableau professional services to help you with:

• Major version upgrades with blue/green deployment for zero-downtime migrations
• Cross-region migrations including full infrastructure setup and network configuration
• SAML/SSO configuration and identity service migrations
• Performance tuning and ongoing managed support

We work with Tableau Server deployments of all sizes and have deep experience with AWS hosted environments.

Talk to our Tableau team about your upgrade ->