Upgrading

How to upgrade Infisical deployment using linux package

Planning an upgrade? Use the Infisical Upgrade Tool to map out your upgrade path and review notable changes between your current and target versions.

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:

   Debian/Ubuntu

   sudo apt-get update && sudo apt-get install -y infisical-core
   

   RHEL/CentOS/Amazon Linux

   sudo yum update infisical-core
   

   To upgrade to a specific version:

   Debian/Ubuntu

   sudo apt-get install -y infisical-core=<version>
   

   RHEL/CentOS/Amazon Linux

   sudo yum install 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:

   NGINX

   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
   

   HAProxy

   If using HAProxy, you can put the server in maintenance mode:

   # Using the HAProxy socket command
   echo "disable server infisical_backend/infisical-node1" | socat stdio /var/lib/haproxy/stats
   

   AWS ALB/ELB

   Deregister the instance from the load balancer using the AWS console or CLI

   Other load balancers

   Follow your load balancer’s documentation for instructions on draining procedure

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:

   Debian/Ubuntu

   sudo apt-get update && sudo apt-get install -y infisical-core
   

   RHEL/CentOS/Amazon Linux

   sudo yum update infisical-core
   

   To upgrade to a specific version:

   Debian/Ubuntu

   sudo apt-get install -y infisical-core=<version>
   

   RHEL/CentOS/Amazon Linux

   sudo yum install 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:

   Debian/Ubuntu

   sudo apt-get update && sudo apt-get install -y infisical-core
   

   RHEL/CentOS/Amazon Linux

   sudo yum update infisical-core
   

   To upgrade to a specific version:

   Debian/Ubuntu

   sudo apt-get install -y infisical-core=<version>
   

   RHEL/CentOS/Amazon Linux

   sudo yum install 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

Migration Issues

If you encounter database migration issues:

1. Check the logs:

   infisical-ctl tail
   

2. Ensure the database user has sufficient privileges to create/modify tables.

3. If migrations fail repeatedly, consider restoring from the backup you took prior to upgrading.

Service Won't Start After Upgrade

1. Check for configuration errors:

   infisical-ctl tail
   infisical-ctl status
   

2. Verify all required environment variables are set in your /etc/infisical/infisical.rb file.