mirror of
https://github.com/awatertrevi/infisical.git
synced 2026-09-22 13:39:35 +00:00
add linux upgrade docs
This commit is contained in:
Maidul Islam
@@ -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",
|
||||
|
||||
358
docs/self-hosting/deployment-options/linux-upgrade.mdx
Normal file
358
docs/self-hosting/deployment-options/linux-upgrade.mdx
Normal file
@@ -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 <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:
|
||||
|
||||
<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 changes">
|
||||
```bash
|
||||
infisical-ctl reconfigure
|
||||
```
|
||||
</Step>
|
||||
|
||||
<Step title="Start Infisical">
|
||||
```bash
|
||||
infisical-ctl start
|
||||
```
|
||||
</Step>
|
||||
|
||||
<Step title="Verify the upgrade">
|
||||
```bash
|
||||
infisical-ctl status
|
||||
```
|
||||
|
||||
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:
|
||||
|
||||
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:
|
||||
<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>
|
||||
|
||||
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:
|
||||
|
||||
<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>
|
||||
|
||||
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:
|
||||
|
||||
<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>
|
||||
|
||||
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=<previous-version>
|
||||
```
|
||||
|
||||
For RHEL/CentOS/Amazon Linux:
|
||||
```bash
|
||||
sudo yum downgrade infisical-core-<previous-version>
|
||||
```
|
||||
|
||||
3. Restore your database from backup.
|
||||
|
||||
4. Start the service:
|
||||
```bash
|
||||
infisical-ctl reconfigure
|
||||
```
|
||||
|
||||
5. Verify the rollback:
|
||||
```bash
|
||||
infisical-ctl status
|
||||
```
|
||||
Reference in New Issue
Block a user