This guide explains how to upgrade Infisical Linux package installations to newer versions. The Infisical Linux package includes only the Infisical service component itself, as PostgreSQL and Redis databases are managed separately. Upgrades for PostgreSQL and Redis are not covered in this guide as they depend on your specific database deployment method.

​
Upgrade Options

There are two primary methods to upgrade Infisical:
  1. Standard Upgrade (with brief downtime): The simplest approach that briefly takes Infisical offline during the upgrade.
  2. Minimal-Downtime Upgrade: For multi-node deployments where high availability is required.

​
Before You Begin

​
Checking Your Current Version

Before upgrading, note your current Infisical version: 
cat /opt/infisical-core/version-manifest.txt
Look for infisical component. This will be the version of Infisical currently installed.

​
Prerequisites

  • Verify that your PostgreSQL and Redis instances are up and running
  • Back up your PostgreSQL database before proceeding with any upgrade
  • Review release notes for the version you’re upgrading to

​
Creating a Database Backup

We strongly recommend backing up your database before upgrading. Your backup approach may look different depending on how you configured PostgreSQL and whether it’s self-managed or using a managed service. Here is a sample of how you would perform a manual backup: 
# Example PostgreSQL backup command (adjust parameters as needed)
pg_dump -U <username> -h <db-host> -d <db-name> > infisical_backup.sql

​
Database Migrations During Upgrade

By default, Infisical runs database migrations automatically on startup.
  • It uses database locks to ensure only one instance runs migrations at a time
  • Other instances will wait for the lock to be released before continuing startup
  • This prevents race conditions and database conflicts

​
Standard Upgrade (with Downtime)

This method is suitable for single-node deployments or situations where a brief downtime is acceptable.
1

Stop the Infisical service

infisical-ctl stop
2

Upgrade the Infisical package

To upgrade to the latest version:
sudo apt-get update && sudo apt-get install -y infisical-core
To upgrade to a specific version:
sudo apt-get install -y infisical-core=<version>
3

Apply configuration changes

infisical-ctl reconfigure
4

Start Infisical

infisical-ctl start
5

Verify the upgrade

infisical-ctl status
Check the logs for any issues:
infisical-ctl tail

​
Minimal-Downtime Upgrade

For multi-node setups where you need to maintain availability during upgrades, follow this procedure. This approach requires at least two Infisical nodes behind a load balancer.

​
Understanding Traffic Draining

“Draining” a server means gracefully removing it from the pool of active servers without disrupting existing connections. When you drain a server:
  1. The load balancer stops sending new requests to the server
  2. Existing connections are allowed to complete naturally
  3. Once all connections finish, the server can be safely taken offline for maintenance
This approach ensures users/machines do not experience sudden connection errors during the upgrade process.

​
Preparing for the Upgrade

  1. Designate a deploy node: Choose any single node that will run migrations. This node will be upgraded first.
  2. Configure your load balancer: Ensure your load balancer can perform health checks against Infisical’s api/status endpoint.

​
Upgrade Process

​
On the deploy node:

1

Drain traffic from the node

Drain the traffic on this node gracefully. You can do this in a number of ways depending on the load balancer you have configured. Approaches for some common load balancers are provided below:
If using NGINX as a load balancer, you can remove the server from the upstream pool temporarily:
# Edit your NGINX configuration to comment out or remove the server
sudo nano /path/to/your/nginx-config.conf

# Reload NGINX to apply changes
sudo nginx -s reload
2

Verify no new traffic is arriving

Verify no new traffic is arriving before proceeding with the upgrade.
3

Stop Infisical on this node

infisical-ctl stop
4

Upgrade the Infisical package

To upgrade to the latest version:
sudo apt-get update && sudo apt-get install -y infisical-core
To upgrade to a specific version:
sudo apt-get install -y infisical-core=<version>
5

Apply configuration and start the service

infisical-ctl reconfigure
6

Verify the upgrade and migration success

infisical-ctl tail
Look for successful migration messages in the logs.
7

Return this node to load balancer pool

Re-enable the server in your load balancer using the same method you used to remove it.

​
On all remaining nodes (one at a time):

1

Drain traffic from the node

Follow the same draining procedure as described for the deploy node:
  • Remove the server from your load balancer’s active pool
  • Wait for existing connections to complete
  • Verify the node is no longer receiving traffic
2

Stop Infisical on this node

infisical-ctl stop
3

Upgrade the Infisical package

To upgrade to the latest version:
sudo apt-get update && sudo apt-get install -y infisical-core
To upgrade to a specific version:
sudo apt-get install -y infisical-core=<version>
4

Apply configuration and start the service

infisical-ctl reconfigure
5

Verify the upgrade success

infisical-ctl status
infisical-ctl tail
6

Wait for service to be fully operational

  • Check logs to ensure the service has started successfully
  • Verify it can connect to the database and Redis
7

Return the node to service

Re-enable the server in your load balancer using the same method you used to remove it.
8

Verify traffic is flowing correctly

Check logs and monitoring to ensure traffic is flowing correctly.
9

Repeat for each remaining node

Repeat steps 1-7 for each remaining node, one at a time.
10

Verify application functionality

After all nodes are upgraded, verify that the application is functioning correctly:
  • Test core functionality
  • Check logs for any errors

​
Rolling Back

If you need to roll back to a previous version of Infisical, follow steps below.
1

Stop the Infisical service

infisical-ctl stop
2

Install the previous version

For Debian/Ubuntu:
sudo apt-get install -y infisical-core=<previous-version>
For RHEL/CentOS/Amazon Linux:
sudo yum downgrade infisical-core-<previous-version>
3

Restore your database from backup

Restore your Postgres/Redis database from backup.
4

Start the service

infisical-ctl reconfigure
5

Verify the rollback

infisical-ctl status

​
Troubleshooting