Upgrading - Infisical

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:

Standard Upgrade (with brief downtime): The simplest approach that briefly takes Infisical offline during the upgrade.
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:

bash

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:

bash

# 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.

<Steps> <Step title="Stop the Infisical service"> ```bash infisical-ctl stop ``` </Step> <Step title="Upgrade the Infisical package"> To upgrade to the latest version: <Tabs> <Tab title="Debian/Ubuntu"> ```bash sudo apt-get update && sudo apt-get install -y infisical-core ``` </Tab> <Tab title="RHEL/CentOS/Amazon Linux"> ```bash sudo yum update infisical-core ``` </Tab> </Tabs>

To upgrade to a specific version:

Check the logs for any issues:

bash

infisical-ctl tail

</Step> </Steps>

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:

The load balancer stops sending new requests to the server
Existing connections are allowed to complete naturally
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

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

Upgrade Process

On the deploy 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:

<Tabs> <Tab title="NGINX"> If using NGINX as a load balancer, you can remove the server from the upstream pool temporarily: ```bash # 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
  ```

</Tab> <Tab title="HAProxy"> If using HAProxy, you can put the server in maintenance mode: ```bash # Using the HAProxy socket command echo "disable server infisical_backend/infisical-node1" | socat stdio /var/lib/haproxy/stats ``` </Tab> <Tab title="AWS ALB/ELB"> Deregister the instance from the load balancer using the AWS console or CLI </Tab> <Tab title="Other load balancers"> Follow your load balancer's documentation for instructions on draining procedure </Tab> </Tabs> </Step> <Step title="Verify no new traffic is arriving"> Verify no new traffic is arriving before proceeding with the upgrade. </Step> <Step title="Stop Infisical on this node"> ```bash infisical-ctl stop ``` </Step> <Step title="Upgrade the Infisical package">

To upgrade to the latest version:

<Tabs> <Tab title="Debian/Ubuntu"> ```bash sudo apt-get update && sudo apt-get install -y infisical-core ``` </Tab> <Tab title="RHEL/CentOS/Amazon Linux"> ```bash sudo yum update infisical-core ``` </Tab> </Tabs>

To upgrade to a specific version:

On all remaining nodes (one at a time):

<Steps> <Step title="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 </Step>

<Step title="Stop Infisical on this node"> ```bash infisical-ctl stop ``` </Step> <Step title="Upgrade the Infisical package"> To upgrade to the latest version: <Tabs> <Tab title="Debian/Ubuntu"> ```bash sudo apt-get update && sudo apt-get install -y infisical-core ``` </Tab> <Tab title="RHEL/CentOS/Amazon Linux"> ```bash sudo yum update infisical-core ``` </Tab> </Tabs>

To upgrade to a specific version:

<Tabs> <Tab title="Debian/Ubuntu"> ```bash sudo apt-get install -y infisical-core=<version> ``` </Tab> <Tab title="RHEL/CentOS/Amazon Linux"> ```bash sudo yum install infisical-core-<version> ``` </Tab> </Tabs> </Step> <Step title="Apply configuration and start the service"> ```bash infisical-ctl reconfigure ``` </Step> <Step title="Verify the upgrade success"> ```bash infisical-ctl status infisical-ctl tail ``` </Step> <Step title="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 </Step> <Step title="Return the node to service"> Re-enable the server in your load balancer using the same method you used to remove it. </Step> <Step title="Verify traffic is flowing correctly"> Check logs and monitoring to ensure traffic is flowing correctly. </Step> <Step title="Repeat for each remaining node"> Repeat steps 1-7 for each remaining node, one at a time. </Step> <Step title="Verify application functionality"> After all nodes are upgraded, verify that the application is functioning correctly: - Test core functionality - Check logs for any errors </Step> </Steps>

Rolling Back

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

<Steps> <Step title="Stop the Infisical service"> ```bash infisical-ctl stop ``` </Step> <Step title="Install the previous version"> For Debian/Ubuntu: ```bash sudo apt-get install -y infisical-core=<previous-version> ```

For RHEL/CentOS/Amazon Linux:

bash

sudo yum downgrade infisical-core-<previous-version>

</Step> <Step title="Restore your database from backup"> Restore your Postgres/Redis database from backup. </Step> <Step title="Start the service"> ```bash infisical-ctl reconfigure ``` </Step> <Step title="Verify the rollback"> ```bash infisical-ctl status ``` </Step> </Steps>

Troubleshooting

<AccordionGroup> <Accordion title="Migration Issues"> If you encounter database migration issues:

Check the logs:
bash
```
infisical-ctl tail
```
Ensure the database user has sufficient privileges to create/modify tables.
If migrations fail repeatedly, consider restoring from the backup you took prior to upgrading.

</Accordion> <Accordion title="Service Won't Start After Upgrade"> 1. Check for configuration errors: ```bash infisical-ctl tail infisical-ctl status ```

Verify all required environment variables are set in your /etc/infisical/infisical.rb file. </Accordion>

</AccordionGroup>