From 4e1a5565d817202ff1fde47817232624b4fd051a Mon Sep 17 00:00:00 2001 From: Maidul Islam Date: Tue, 13 May 2025 20:40:29 -0700 Subject: [PATCH] add linux upgrade docs --- docs/mint.json | 3 +- .../deployment-options/linux-upgrade.mdx | 358 ++++++++++++++++++ 2 files changed, 360 insertions(+), 1 deletion(-) create mode 100644 docs/self-hosting/deployment-options/linux-upgrade.mdx diff --git a/docs/mint.json b/docs/mint.json index 46075033a..1fc4b2090 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..2ba8a3f41 --- /dev/null +++ b/docs/self-hosting/deployment-options/linux-upgrade.mdx @@ -0,0 +1,358 @@ +--- +title: "Upgrading Linux Package" +description: "Learn how to upgrade your Infisical deployment on Linux" +--- + +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: + +1. **Drain traffic from the node**: + + Depending on your load balancer, use one of the following approaches to drain the node: + + + 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 + + + +2. **Verify no new traffic is arriving ** before proceeding with the upgrade. + +3. **Stop Infisical on this node**: + ```bash + infisical-ctl stop + ``` + +4. **Upgrade the Infisical package**: + +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- + ``` + + + +5. **Apply configuration and start the service**: + ```bash + infisical-ctl reconfigure + ``` + +6. **Verify the upgrade and migration success**: + ```bash + infisical-ctl tail + ``` + Look for successful migration messages in the logs. + +7. **Return the node to service** once you've verified it's running correctly: + + 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** being upgraded: + + 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**: + ```bash + infisical-ctl stop + ``` + +3. **Upgrade the Infisical package**: + +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- + ``` + + + +4. **Apply configuration and start the service**: + ```bash + infisical-ctl reconfigure + ``` + +5. **Verify the upgrade success**: + ```bash + 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** by checking logs and monitoring. + +8. **Repeat** steps 1-7 for each remaining node, one at a time. + +9. **After all nodes are upgraded**, verify that the application is functioning correctly: + - Test core functionality + - Check logs for any errors + +## Troubleshooting + +### Migration Issues + +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. + +### Service Won't Start After Upgrade + +1. Check for configuration errors: + ```bash + infisical-ctl status + infisical-ctl tail + ``` + +2. Verify all required environment variables are set in your `/etc/infisical/infisical.rb` file. + + +## Rolling Back + +If you need to roll back to a previous version of Infisical, follow steps below. + +1. Stop the Infisical service: + ```bash + infisical-ctl stop + ``` + +2. Install the previous version: + + For Debian/Ubuntu: + ```bash + sudo apt-get install -y infisical-core= + ``` + + For RHEL/CentOS/Amazon Linux: + ```bash + sudo yum downgrade infisical-core- + ``` + +3. Restore your database from backup. + +4. Start the service: + ```bash + infisical-ctl reconfigure + ``` + +5. Verify the rollback: + ```bash + infisical-ctl status + ``` \ No newline at end of file