diff --git a/docs/mint.json b/docs/mint.json index 9691f4ab8..88868bd6a 100644 --- a/docs/mint.json +++ b/docs/mint.json @@ -350,7 +350,8 @@ "group": "Linux Package", "pages": [ "self-hosting/deployment-options/native/linux-package/installation", - "self-hosting/deployment-options/native/linux-package/commands-configuration" + "self-hosting/deployment-options/native/linux-package/commands-configuration", + "self-hosting/deployment-options/linux-upgrade" ] }, "self-hosting/guides/upgrading-infisical", diff --git a/docs/self-hosting/deployment-options/linux-upgrade.mdx b/docs/self-hosting/deployment-options/linux-upgrade.mdx new file mode 100644 index 000000000..6712626bd --- /dev/null +++ b/docs/self-hosting/deployment-options/linux-upgrade.mdx @@ -0,0 +1,390 @@ +--- +title: "Upgrading" +description: "How to upgrade Infisical deployment using linux package" +--- + +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: + +```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 -h -d > 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. + + + + ```bash + infisical-ctl stop + ``` + + +To upgrade to the latest version: + + + + ```bash + sudo apt-get update && sudo apt-get install -y infisical-core + ``` + + + ```bash + sudo yum update infisical-core + ``` + + + +To upgrade to a specific version: + + + + ```bash + sudo apt-get install -y infisical-core= + ``` + + + ```bash + sudo yum install infisical-core- + ``` + + + + + + ```bash + infisical-ctl reconfigure + ``` + + + + ```bash + infisical-ctl start + ``` + + + + ```bash + infisical-ctl status + ``` + + Check the logs for any issues: + ```bash + 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: + + + + +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: + ```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 + ``` + + + 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 + ``` + + + Deregister the instance from the load balancer using the AWS console or CLI + + + Follow your load balancer's documentation for instructions on draining procedure + + + + + +Verify no new traffic is arriving before proceeding with the upgrade. + + + +```bash +infisical-ctl stop +``` + + + + +To upgrade to the latest version: + + + + ```bash + sudo apt-get update && sudo apt-get install -y infisical-core + ``` + + + ```bash + sudo yum update infisical-core + ``` + + + +To upgrade to a specific version: + + + + ```bash + sudo apt-get install -y infisical-core= + ``` + + + ```bash + sudo yum install infisical-core- + ``` + + + + + +```bash +infisical-ctl reconfigure +``` + + + +```bash +infisical-ctl tail +``` +Look for successful migration messages in the logs. + + + +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): + + + +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 + + + +```bash +infisical-ctl stop +``` + + + +To upgrade to the latest version: + + + + ```bash + sudo apt-get update && sudo apt-get install -y infisical-core + ``` + + + ```bash + sudo yum update infisical-core + ``` + + + +To upgrade to a specific version: + + + + ```bash + sudo apt-get install -y infisical-core= + ``` + + + ```bash + sudo yum install infisical-core- + ``` + + + + + +```bash +infisical-ctl reconfigure +``` + + + +```bash +infisical-ctl status +infisical-ctl tail +``` + + + +- Check logs to ensure the service has started successfully +- Verify it can connect to the database and Redis + + + +Re-enable the server in your load balancer using the same method you used to remove it. + + + +Check logs and monitoring to ensure traffic is flowing correctly. + + + +Repeat steps 1-7 for each remaining node, one at a time. + + + +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. + + + +```bash +infisical-ctl stop +``` + + + +For Debian/Ubuntu: +```bash +sudo apt-get install -y infisical-core= +``` + +For RHEL/CentOS/Amazon Linux: +```bash +sudo yum downgrade infisical-core- +``` + + + +Restore your Postgres/Redis database from backup. + + + +```bash +infisical-ctl reconfigure +``` + + + +```bash +infisical-ctl status +``` + + + +## Troubleshooting + + + +If you encounter database migration issues: + +1. Check the logs: + ```bash + 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. + + + + +1. Check for configuration errors: + ```bash + infisical-ctl tail + infisical-ctl status + ``` + +2. Verify all required environment variables are set in your `/etc/infisical/infisical.rb` file. + + \ No newline at end of file