awatertrevi/infisical
1
0
Fork 0
mirror of https://github.com/awatertrevi/infisical.git synced 2026-09-22 13:39:35 +00:00
Code Issues Packages Projects Releases Wiki Activity

Merge branch 'main' into doc/infisical-package

Browse Source
This commit is contained in:
Maidul Islam
2025-04-24 14:12:01 -07:00
committed by GitHub
parent c97a3f07a7 8bf5b0f457
commit aff318cf3c
3899 changed files with 220383 additions and 92295 deletions
Download Patch File Download Diff File Expand all files Collapse all files

145
docs/self-hosting/configuration/envars.mdx
View File

@@ -30,13 +30,52 @@ Used to configure platform-specific security and operational settings
</ParamField>
<ParamField query="TELEMETRY_ENABLED" type="string" default="true" optional>
Telemetry helps us improve Infisical but if you want to dsiable it you may set this to `false`.
Telemetry helps us improve Infisical but if you want to disable it you may set
this to `false`.
</ParamField>
<ParamField
query="ALLOW_INTERNAL_IP_CONNECTIONS"
type="bool"
default="false"
optional
>
Determines whether App Connections and Dynamic Secrets are permitted to
connect with internal/private IP addresses.
</ParamField>
## CORS
Cross-Origin Resource Sharing (CORS) is a security feature that allows web applications running on one domain to access resources from another domain.
The following environment variables can be used to configure the Infisical Rest API to allow or restrict access to resources from different origins.
<ParamField query="CORS_ALLOWED_ORIGINS" type="string" optional>
Specify a list of origins that are allowed to access the Infisical API.
An example value would be `CORS_ALLOWED_ORIGINS=["https://example.com"]`.
Defaults to the same value as your `SITE_URL` environment variable.
</ParamField>
<ParamField query="CORS_ALLOWED_METHODS" type="string" optional>
Array of HTTP methods allowed for CORS requests.
Defaults to reflecting the headers specified in the request's Access-Control-Request-Headers header.
</ParamField>
## Data Layer
The platform utilizes Postgres to persist all of its data and Redis for caching and backgroud tasks
### PostgreSQL
<Info>
Please note that the database user must have **CREATE** privileges along with ability to create and modify tables. This is needed for Infisical to run schema migrations.
</Info>
<ParamField query="DB_CONNECTION_URI" type="string" default="" required>
Postgres database connection string.
</ParamField>
@@ -47,10 +86,6 @@ The platform utilizes Postgres to persist all of its data and Redis for caching
`echo "<certificate>" | base64`
</ParamField>
<ParamField query="REDIS_URL" type="string" default="none" required>
Redis connection string.
</ParamField>
<ParamField query="DB_READ_REPLICAS" type="string" default="" optional>
Postgres database read replica connection strings. It accepts a JSON string.
```
@@ -65,12 +100,19 @@ DB_READ_REPLICAS=[{"DB_CONNECTION_URI":""}]
Use the command below to encode your certificate:
`echo "<certificate>" | base64`
If not provided it will use master SSL certificate.
If not provided it will use master SSL certificate.
</ParamField>
</Expandable>
</ParamField>
## Email service
### Redis
<ParamField query="REDIS_URL" type="string" default="none" required>
Redis connection string.
</ParamField>
## Email Service
Without email configuration, Infisical's core functions like sign-up/login and secret operations work, but this disables multi-factor authentication, email invites for projects, alerts for suspicious logins, and all other email-dependent features.
@@ -350,8 +392,9 @@ Optional (for TLS/SSL):
TLS: Available on the same ports (2525, 80, 25, 8025, or 587)
SSL: Available on ports 465, 8465, and 443
</Note>
</Accordion>
</Accordion>
## Authentication
@@ -415,7 +458,56 @@ When set, all visits to the Infisical login page will automatically redirect use
information.
</Accordion>
## Native secret integrations
## App Connections
You can configure third-party app connections for re-use across Infisical Projects.
<Accordion title="AWS Assume Role Connection">
<ParamField query="INF_APP_CONNECTION_AWS_ACCESS_KEY_ID" type="string" default="none" optional>
The AWS IAM User access key ID for assuming roles
</ParamField>
<ParamField query="INF_APP_CONNECTION_AWS_SECRET_ACCESS_KEY" type="string" default="none" optional>
The AWS IAM User secret key for assuming roles
</ParamField>
</Accordion>
<Accordion title="GitHub App Connection">
<ParamField query="INF_APP_CONNECTION_GITHUB_APP_ID" type="string" default="none" optional>
The ID of the GitHub App
</ParamField>
<ParamField query="INF_APP_CONNECTION_GITHUB_APP_SLUG" type="string" default="none" optional>
The slug of the GitHub App
</ParamField>
<ParamField query="INF_APP_CONNECTION_GITHUB_APP_CLIENT_ID" type="string" default="none" optional>
The client ID for the GitHub App
</ParamField>
<ParamField query="INF_APP_CONNECTION_GITHUB_APP_CLIENT_SECRET" type="string" default="none" optional>
The client secret for the GitHub App
</ParamField>
<ParamField query="INF_APP_CONNECTION_GITHUB_APP_PRIVATE_KEY" type="string" default="none" optional>
The private key for the GitHub App
</ParamField>
</Accordion>
<Accordion title="GitHub OAuth Connection">
<ParamField query="INF_APP_CONNECTION_GITHUB_OAUTH_CLIENT_ID" type="string" default="none" optional>
The OAuth2 client ID for GitHub OAuth Connection
</ParamField>
<ParamField query="INF_APP_CONNECTION_GITHUB_OAUTH_CLIENT_SECRET" type="string" default="none" optional>
The OAuth2 client secret for GitHub OAuth Connection
</ParamField>
</Accordion>
## Native Secret Integrations
To help you sync secrets from Infisical to services such as Github and Gitlab, Infisical provides native integrations out of the box.
@@ -489,7 +581,7 @@ To help you sync secrets from Infisical to services such as Github and Gitlab, I
</ParamField>
</Accordion>
<Accordion title="AWS">
<Accordion title="AWS Integration">
<ParamField query="CLIENT_ID_AWS_INTEGRATION" type="string" default="none" optional>
The AWS IAM User access key for assuming roles.
</ParamField>
@@ -518,3 +610,36 @@ To help you sync secrets from Infisical to services such as Github and Gitlab, I
OAuth2 client secret for Gitlab integration
</ParamField>
</Accordion>
## Observability
You can configure Infisical to collect and expose telemetry data for analytics and monitoring.
<ParamField
query="OTEL_TELEMETRY_COLLECTION_ENABLED"
type="string"
default="false"
>
Whether or not to collect and expose telemetry data.
</ParamField>
<ParamField query="OTEL_EXPORT_TYPE" type="enum" optional>
Supported types are `prometheus` and `otlp`.
If export type is set to `prometheus`, metric data will be exposed in port 9464 in the `/metrics` path.
If export type is set to `otlp`, you will have to configure a value for `OTEL_EXPORT_OTLP_ENDPOINT`.
</ParamField>
<ParamField query="OTEL_EXPORT_OTLP_ENDPOINT" type="string">
Where telemetry data would be pushed to for collection. This is only
applicable when `OTEL_EXPORT_TYPE` is set to `otlp`.
</ParamField>
<ParamField query="OTEL_COLLECTOR_BASIC_AUTH_USERNAME" type="string">
The username for authenticating with the telemetry collector.
</ParamField>
<ParamField query="OTEL_COLLECTOR_BASIC_AUTH_PASSWORD" type="string">
The password for authenticating with the telemetry collector.
</ParamField>

35
docs/self-hosting/configuration/requirements.mdx
View File

@@ -22,33 +22,34 @@ The actual resource requirements will vary in direct proportion to the operation
Infisical doesn’t require file storage as all persisted data is saved in the database.
However, its logs and metrics are saved to disk for later viewing. As a result, we recommend provisioning 1-2 GB of storage.
### CPU
### CPU and Memory (Per Container/Instance)
CPU requirements vary heavily on the volume of secret operations (reads and writes) you anticipate.
Processing large volumes of secrets frequently and consistently will require higher CPU.
Infisical is stateless and scales horizontally by running across multiple containers/instances. Each instance typically does **not** need more than **2–4 CPU cores** and **4–8 GB** of memory.
If you need additional capacity, simply increase the **number** of containers/instances running in parallel.
Recommended minimum CPU hardware for different sizes of deployments:
| **Deployment Size** | **CPU (Cores, per container)** | **Memory (GB, per container)** | **Recommended Number of Containers** |
|---------------------|--------------------------------|--------------------------------|--------------------------------------|
| **Small** | 2 | 4 | 2+ |
| **Medium** | 2–4 | 4–8 | 5+ |
| **Large** | 2–4 | 4–8 | 10+ |
- **small:** 2-4 core is the **recommended** minimum
- **large:** 4-8 cores are suitable for larger deployments
### Memory Allocation
Memory needs depend on expected workload, including factors like user activity, automation level, and the frequency of secret operations.
Recommended minimum memory hardware for different sizes of deployments:
- **small:** 4-8 GB is the **recommended** minimum
- **large:** 16-32 GB are suitable for larger deployments
> **Note:**
> - Adding more containers (horizontal scaling) is generally the best way to handle spikes in secret operations.
> - If you prefer, you can increase CPU/memory on a single container (vertical scaling), but horizontal scaling is more flexible and resilient.
## Database & caching layer
### Postgres
PostgreSQL is the only database supported by Infisical. Infisical has been extensively tested with Postgres version 16. We recommend using versions 14 and up for optimal compatibility.
The compute required for Postgres is largely dependent on the number of secret operations (reads and writes) you expect. The more frequently you read and write secrets, the more compute you will need.
You'll notice that storage requirements are high and this is because audit logs are by default stored in the database.
Recommended resource allocation based on deployment size:
- **small:** 2 vCPU / 8 GB RAM / 20 GB Disk
- **large:** 4vCPU / 16 GB RAM / 100 GB Disk
Recommended resource allocation based on deployment size. You may require more resources if you have a large number of secrets or high transaction volume:
- **small:** 2 vCPU / 8 GB RAM / 100 GB Disk
- **medium:** 4vCPU / 16 GB RAM / 200 GB Disk
- **large:** 8vCPU / 32 GB RAM / 500 GB Disk
### Redis

60
docs/self-hosting/configuration/schema-migrations.mdx
View File

@@ -1,60 +0,0 @@
---
title: "Schema migration"
description: "Learn how to run Postgres schema migrations."
---
Running schema migrations is a requirement before deploying Infisical.
Each time you decide to upgrade your version of Infisical, it's necessary to run schema migrations for that specific version.
The guide below outlines a step-by-step guide to help you manually run schema migrations for Infisical.
### Prerequisites
- Docker installed on your machine
- An active PostgreSQL database
- Postgres database connection string
<Steps>
<Step title="Pull the Infisical Docker Image">
First, ensure you have the correct version of the Infisical Docker image. You can pull it from Docker Hub using the following command:
```bash
docker pull infisical/infisical:<version>
```
Replace `<version>` with the specific version number you intend to deploy. View available versions [here](https://hub.docker.com/r/infisical/infisical/tags)
</Step>
<Step title="Set Up the Environment Variable">
The Docker image requires a `DB_CONNECTION_URI` environment variable. This connection string should point to your PostgreSQL database. The format generally looks like this: `postgresql://username:password@host:port/database`.
</Step>
<Step title="Run the Migration ">
To run the schema migration for the version of Infisical you want to deploy, use the following Docker command:
```bash
docker run --env DB_CONNECTION_URI=<your_connection_string> infisical/infisical:<version> npm run migration:latest
```
Replace `<your_connection_string>` with your actual PostgreSQL connection string, and `<version>` with the desired version number.
</Step>
<Step title="Verify the Migration">
After running the migration, it's good practice to check if the migration was successful. You can do this by checking the logs or accessing your database to ensure the schema has been updated accordingly.
</Step>
<Step title="Rollback If Needed">
If you need to rollback a migration by one step, use the following command:
```bash
docker run --env DB_CONNECTION_URI=<your_connection_string> infisical/infisical:<version> npm run migration:rollback
```
</Step>
<Step title="Repeat for Each Version">
It's important to run schema migrations for each version of the Infisical you deploy. For instance, if you're updating from `infisical/infisical:1` to `infisical/infisical:2`, ensure you run the schema migrations for `infisical/infisical:2` before deploying it.
</Step>
</Steps>
<Tip>
In a production setting, we recommend a more structured approach to deploying migrations prior to upgrading Infisical. This can be accomplished via CI automation.
</Tip>
### Additional discussion
- Always back up your database before running migrations, especially in a production environment.
- Test the migration process in a staging environment before applying it to production.
- Keep track of the versions and their corresponding migrations to avoid any inconsistencies.

17
docs/self-hosting/deployment-options/docker-swarm.mdx
View File

@@ -157,23 +157,6 @@ The [Docker stack file](https://github.com/Infisical/infisical/tree/main/docker-
3lznscvk7k5t infisical_spolo2 replicated 1/1 ghcr.io/zalando/spilo-16:3.2-p2
v04ml7rz2j5q infisical_spolo3 replicated 1/1 ghcr.io/zalando/spilo-16:3.2-p2
```
<Note>
You'll notice that service `infisical_infisical` will not be in running state.
This is expected as the database does not yet have the desired schemas.
Once the database schema migrations have been successfully applied, this issue should be resolved.
</Note>
</Step>
<Step title="Run schema migrations">
Run the schema migration to initialize the database. Follow the [guide here](/self-hosting/configuration/schema-migrations) to learn how.
To run the migrations, you'll need to connect to the Postgres instance deployed on your Docker swarm. The default Postgres user credentials are defined in the Docker swarm: username: `postgres`, password: `postgres` and database: `postgres`.
We recommend you change these credentials when deploying to production and creating a separate DB for Infisical.
<Info>
After running the schema migrations, be sure to update the `.env` file to have the correct `DB_CONNECTION_URI`.
</Info>
</Step>
<Step title="View service status">

12
docs/self-hosting/deployment-options/kubernetes-helm.mdx
View File

@@ -78,18 +78,6 @@ description: "Learn how to use Helm chart to install Infisical on your Kubernete
</Tabs>
</Step>
<Step title="Database schema migration ">
Infisical relies a relational database, which means that database schemas need to be migrated before the instance can become operational.
To automate this process, the chart includes a option named `infisical.autoDatabaseSchemaMigration`.
When this option is enabled, a deployment/upgrade will only occur _after_ a successful schema migration.
<Info>
If you are using in-cluster Postgres, you may notice the migration job failing initially.
This is expected as it is waiting for the database to be in ready state.
</Info>
</Step>
<Step title="Routing traffic to Infisical">
By default, this chart uses Nginx as its Ingress controller to direct traffic to Infisical services.

520
docs/self-hosting/deployment-options/native/high-availability.mdx
View File

@@ -1,520 +0,0 @@
---
title: "Automatically deploy Infisical with High Availability"
sidebarTitle: "High Availability"
---
# Self-Hosting Infisical with a native High Availability (HA) deployment
This page describes the Infisical architecture designed to provide high availability (HA) and how to deploy Infisical with high availability. The high availability deployment is designed to ensure that Infisical services are always available and can handle service failures gracefully, without causing service disruptions.
<Info>
This deployment option is currently only available for Debian-based nodes (e.g., Ubuntu, Debian).
We plan on adding support for other operating systems in the future.
</Info>
## High availability architecture
| Service | Nodes | Configuration | GCP | AWS |
|----------------------------------|----------------|------------------------------|---------------|--------------|
| External load balancer$^1$ | 1 | 4 vCPU, 3.6 GB memory | n1-highcpu-4 | c5n.xlarge |
| Internal load balancer$^2$ | 1 | 4 vCPU, 3.6 GB memory | n1-highcpu-4 | c5n.xlarge |
| Etcd cluster$^3$ | 3 | 4 vCPU, 3.6 GB memory | n1-highcpu-4 | c5n.xlarge |
| PostgreSQL$^4$ | 3 | 2 vCPU, 7.5 GB memory | n1-standard-2 | m5.large |
| Sentinel$^4$ | 3 | 2 vCPU, 7.5 GB memory | n1-standard-2 | m5.large |
| Redis$^4$ | 3 | 2 vCPU, 7.5 GB memory | n1-standard-2 | m5.large |
| Infisical Core | 3 | 8 vCPU, 7.2 GB memory | n1-highcpu-8 | c5.2xlarge |
**Footnotes:**
1. External load balancer: If you wish to have multiple instances of the internal load balancer, you will need to use an external load balancer to distribute incoming traffic across multiple internal load balancers.
Using multiple internal load balancers is recommended for high-traffic environments. In the following guide we will use a single internal load balancer, as external load balancing falls outside the scope of this guide.
2. Internal load balancer: The internal load balancer (a HAProxy instance) is used to distribute incoming traffic across multiple Infisical Core instances, Postgres nodes, and Redis nodes. The internal load balancer exposes a set of ports _(80 for Infiscial, 5000 for Read/Write postgres, 5001 for Read-only postgres, and 6379 for Redis)_. Where these ports route to is determained by the internal load balancer based on the availability and health of the service nodes.
The internal load balancer is only accessible from within the same network, and is not exposed to the public internet.
3. Etcd cluster: Etcd is a distributed key-value store used to store and distribute data between the PostgreSQL nodes. Etcd is dependent on high disk I/O performance, therefore it is highly recommended to use highly performant SSD disks for the Etcd nodes, with _at least_ 80GB of disk space.
4. The Redis and PostgreSQL nodes will automatically be configured for high availability and used in your Infisical Core instances. However, you can optionally choose to bring your own database (BYOD), and skip these nodes. See more on how to [provide your own databases](#provide-your-own-databases).
<Info>
For all services that require multiple nodes, it is recommended to deploy them across multiple availability zones (AZs) to ensure high availability and fault tolerance. This will help prevent service disruptions in the event of an AZ failure.
</Info>
![High availability stack](../../images/self-hosting/deployment-options/native/ha-stack.png)
The image above shows how a high availability deployment of Infisical is structured. In this example, an external load balancer is used to distribute incoming traffic across multiple internal load balancers. The internal load balancers. The external load balancer isn't required, and it will require additional configuration to set up.
### Fault Tolerance
This setup provides N+1 redundancy, meaning it can tolerate the failure of any single node without service interruption.
## Ansible
### What is Ansible
Ansible is an open-source automation tool that simplifies application deployment, configuration management, and task automation.
At Infisical, we use Ansible to automate the deployment of Infisical services. The Ansible roles are designed to make it easy to deploy Infisical services in a high availability environment.
### Installing Ansible
<Steps>
<Step title="Install using the pipx Python package manager">
```bash
pipx install --include-deps ansible
```
</Step>
<Step title="Verify the installation">
```bash
ansible --version
```
</Step>
</Steps>
### Understanding Ansible Concepts
* Inventory _(inventory.ini)_: A file that lists your target hosts.
* Playbook _(playbook.yml)_: YAML file containing a set of tasks to be executed on hosts.
* Roles: Reusable units of organization for playbooks. Roles are used to group tasks together in a structured and reusable manner.
### Basic Ansible Commands
Running a playbook with with an invetory file:
```bash
ansible-playbook -i inventory.ini playbook.yml
```
This is how you would run the playbook containing the roles for setting up Infisical in a high availability environment.
### Installing the Infisical High Availability Deployment Ansible Role
The Infisical Ansible role is available on Ansible Galaxy. You can install the role by running the following command:
```bash
ansible-galaxy collection install infisical.infisical_core_ha_deployment
```
## Set up components
1. External load balancer (optional, and not covered in this guide)
2. [Configure Etcd cluster](#configure-etcd-cluster)
3. [Configure PostgreSQL database](#configure-postgresql-database)
4. [Configure Redis/Sentinel](#configure-redis-and-sentinel)
5. [Configure Infisical Core](#configure-infisical-core)
The servers start on the same 52.1.0.0/24 private network range, and can connect to each other freely on these addresses.
The following list includes descriptions of each server and its assigned IP:
52.1.0.1: External Load Balancer
52.1.0.2: Internal Load Balancer
52.1.0.3: Etcd 1
52.1.0.4: Etcd 2
52.1.0.5: Etcd 3
52.1.0.6: PostgreSQL 1
52.1.0.7: PostgreSQL 2
52.1.0.8: PostgreSQL 3
52.1.0.9: Redis 1
52.1.0.10: Redis 2
52.1.0.11: Redis 3
52.1.0.12: Sentinel 1
52.1.0.13: Sentinel 2
52.1.0.14: Sentinel 3
52.1.0.15: Infisical Core 1
52.1.0.16: Infisical Core 2
52.1.0.17: Infisical Core 3
### Configure Etcd cluster
Configuring the ETCD cluster is the first step in setting up a high availability deployment of Infisical.
The ETCD cluster is used to store and distribute data between the PostgreSQL nodes. The ETCD cluster is a distributed key-value store that is highly available and fault-tolerant.
```yaml example.playbook.yml
- hosts: all
gather_facts: true
- name: Set up etcd cluster
hosts: etcd
become: true
collections:
- infisical.infisical_core_ha_deployment
roles:
- role: etcd
```
```ini example.inventory.ini
[etcd]
etcd1 ansible_host=52.1.0.3
etcd2 ansible_host=52.1.0.4
etcd3 ansible_host=52.1.0.5
[etcd:vars]
ansible_user=ubuntu
ansible_ssh_private_key_file=./ssh-key.pem
ansible_ssh_common_args='-o StrictHostKeyChecking=no'
```
### Configure PostgreSQL database
The Postgres role takes a set of parameters that are used to configure your PostgreSQL database.
Make sure to set the following variables in your playbook.yml file:
- `postgres_super_user_password`: The password for the 'postgres' database user.
- `postgres_db_name`: The name of the database that will be created on the leader node and replicated to the secondary nodes.
- `postgres_user`: The name of the user that will be created on the leader node and replicated to the secondary nodes.
- `postgres_user_password`: The password for the user that will be created on the leader node and replicated to the secondary nodes.
- `etcd_hosts`: The list of etcd hosts that the PostgreSQL nodes will use to communicate with etcd. By default you want to keep this value set to `"{{ groups['etcd'] }}"`
```yaml example.playbook.yml
- hosts: all
gather_facts: true
- name: Set up PostgreSQL with Patroni
hosts: postgres
become: true
collections:
- infisical.infisical_core_ha_deployment
roles:
- role: postgres
vars:
postgres_super_user_password: "your-super-user-password"
postgres_user: infisical-user
postgres_user_password: "your-password"
postgres_db_name: infisical-db
etcd_hosts: "{{ groups['etcd'] }}"
```
```ini example.inventory.ini
[postgres]
postgres1 ansible_host=52.1.0.6
postgres2 ansible_host=52.1.0.7
postgres3 ansible_host=52.1.0.8
```
### Configure Redis and Sentinel
The Redis role takes a single variable as input, which is the redis password.
The Sentinel and Redis hosts will run the same role, therefore we are running the task for both the sentinel and redis hosts, `hosts: redis:sentinel`.
- `redis_password`: The password that will be set for the Redis instance.
```yaml example.playbook.yml
- hosts: all
gather_facts: true
- name: Setup Redis and Sentinel
hosts: redis:sentinel
become: true
collections:
- infisical.infisical_core_ha_deployment
roles:
- role: redis
vars:
redis_password: "REDIS_PASSWORD"
```
```ini example.inventory.ini
[redis]
redis1 ansible_host=52.1.0.9
redis2 ansible_host=52.1.0.10
redis3 ansible_host=52.1.0.11
[sentinel]
sentinel1 ansible_host=52.1.0.12
sentinel2 ansible_host=52.1.0.13
sentinel3 ansible_host=52.1.0.14
```
### Configure Internal Load Balancer
The internal load balancer used is HAProxy. HAProxy will expose a set of ports as listed below. Each port will route to a different service based on the availability and health of the service nodes.
- Port 80: Infisical Core
- Port 5000: Read/Write PostgreSQL
- Port 5001: Read-only PostgreSQL
- Port 6379: Redis
- Port 7000: HAProxy monitoring
These ports will need to be exposed on your network to become accessible from the outside world.
The HAProxy configuration file is generated by the Infisical Core role, and is located at `/etc/haproxy/haproxy.cfg` on your internal load balancer node.
The HAProxy setup comes with a monitoring panel. You have to set the username/password combination for the monitoring panel by setting the `stats_user` and `stats_password` variables in the HAProxy role.
Once the HAProxy role has fully executed, you can monitor your HA setup by navigating to `http://52.1.0.2:7000/haproxy?stats` in your browser.
```ini example.inventory.ini
[haproxy]
internal_lb ansible_host=52.1.0.2
```
```yaml example.playbook.yml
- name: Set up HAProxy
hosts: haproxy
become: true
collections:
- infisical.infisical_core_ha_deployment
roles:
- role: haproxy
vars:
stats_user: "stats-username"
stats_password: "stats-password!"
postgres_servers: "{{ groups['postgres'] }}"
infisical_servers: "{{ groups['infisical'] }}"
redis_servers: "{{ groups['redis'] }}"
```
### Configure Infisical Core
The Infisical Core role will set up your actual Infisical instances.
The `env_vars` variable is used to set the environment variables that Infisical will use. The minimum required environment variables are `ENCRYPTION_KEY` and `AUTH_SECRET`. You can find a list of all available environment variables [here](/docs/self-hosting/configuration/envars#general-platform).
The `DB_CONNECTION_URI` and `REDIS_URL` variables will automatically be set if you're running the full playbook. However, you can choose to set them yourself, and skip the Postgres, etcd, redis/sentinel roles entirely.
<Info>
If you later need to add new environment varibles to your Infisical deployments, it's important you add the variables to **all** your Infisical nodes.<br/>
You can find the environment file for Infisical at `/etc/infisical/environment`.<br/>
After editing the environment file, you need to reload the Infisical service by doing `systemctl restart infisical`.
</Info>
```yaml example.playbook.yml
- hosts: all
gather_facts: true
- name: Setup Infisical
hosts: infisical
become: true
collections:
- infisical.infisical_core_ha_deployment
roles:
- role: infisical
env_vars:
ENCRYPTION_KEY: "YOUR_ENCRYPTION_KEY" # openssl rand -hex 16
AUTH_SECRET: "YOUR_AUTH_SECRET" # openssl rand -base64 32
```
```ini example.inventory.ini
[infisical]
infisical1 ansible_host=52.1.0.15
infisical2 ansible_host=52.1.0.16
infisical3 ansible_host=52.1.0.17
```
## Provide your own databases
Bringing your own database is an option using the Infisical Core deployment role.
By bringing your own database, you're able to skip the Etcd, Postgres, and Redis/Sentinel roles entirely.
To bring your own database, you need to set the `DB_CONNECTION_URI` and `REDIS_URL` environment variables in the Infisical Core role.
```yaml example.playbook.yml
- hosts: all
gather_facts: true
- name: Setup Infisical
hosts: infisical
become: true
collections:
- infisical.infisical_core_ha_deployment
roles:
- role: infisical
env_vars:
ENCRYPTION_KEY: "YOUR_ENCRYPTION_KEY" # openssl rand -hex 16
AUTH_SECRET: "YOUR_AUTH_SECRET" # openssl rand -base64 32
DB_CONNECTION_URI: "postgres://user:password@localhost:5432/infisical"
REDIS_URL: "redis://localhost:6379"
```
```ini example.inventory.ini
[infisical]
infisical1 ansible_host=52.1.0.15
infisical2 ansible_host=52.1.0.16
infisical3 ansible_host=52.1.0.17
```
## Full deployment example
To make it easier to get started, we've provided a full deployment example that you can use to deploy Infisical in a high availability environment.
- This deployment does not use an external load balancer.
- You **must** change the environment variables defined in the `playbook.yml` example.
- You have update the IP addresses in the `inventory.ini` file to match your own network configuration.
- You need to set the SSH key and ssh user in the `inventory.ini` file.
<Steps>
<Step title="Install Ansible">
Install Ansible using the pipx Python package manager.
```bash
pipx install --include-deps ansible
```
</Step>
<Step title="Install the Infisical deployment Ansible Role">
Install the Infisical deployment role from Ansible Galaxy.
```bash
ansible-galaxy collection install infisical.infisical_core_ha_deployment
```
</Step>
<Step title="Setup your hosts">
Create an `inventory.ini` file, and define your hosts and their IP addresses. You can use the example below as a template, and update the IP addresses to match your own network configuration.
Make sure to set the SSH key and ssh user in the `inventory.ini` file. Please see the example below.
```ini example.inventory.ini
[etcd]
etcd1 ansible_host=52.1.0.3
etcd2 ansible_host=52.1.0.4
etcd3 ansible_host=52.1.0.5
[postgres]
postgres1 ansible_host=52.1.0.6
postgres2 ansible_host=52.1.0.7
postgres3 ansible_host=52.1.0.8
[infisical]
infisical1 ansible_host=52.1.0.15
infisical2 ansible_host=52.1.0.16
infisical3 ansible_host=52.1.0.17
[redis]
redis1 ansible_host=52.1.0.9
redis2 ansible_host=52.1.0.10
redis3 ansible_host=52.1.0.11
[sentinel]
sentinel1 ansible_host=52.1.0.12
sentinel2 ansible_host=52.1.0.13
sentinel3 ansible_host=52.1.0.14
[haproxy]
internal_lb ansible_host=52.1.0.2
; This can be defined individually for each host, or globally for all hosts.
; In this case the credentials are the same for all hosts, so we define them globally as seen below ([all:vars]).
[all:vars]
ansible_user=ubuntu
ansible_ssh_private_key_file=./your-ssh-key.pem
ansible_ssh_common_args='-o StrictHostKeyChecking=no'
```
</Step>
<Step title="Setup your Ansible playbook">
The Ansible playbook is where you define which roles/tasks to execute on which hosts.
```yaml example.playbook.yml
---
# Important, we must gather facts from all hosts prior to running the roles to ensure we have all the information we need.
- hosts: all
gather_facts: true
- name: Set up etcd cluster
hosts: etcd
become: true
collections:
- infisical.infisical_core_ha_deployment
roles:
- role: etcd
- name: Set up PostgreSQL with Patroni
hosts: postgres
become: true
collections:
- infisical.infisical_core_ha_deployment
roles:
- role: postgres
vars:
postgres_super_user_password: "<ENTER_SUPERUSER_PASSWORD>" # Password for the 'postgres' database user
# A database with these credentials will be created on the leader node, and replicated to the secondary nodes.
postgres_db_name: <ENTER_DB_NAME>
postgres_user: <ENTER_DB_USER>
postgres_user_password: <ENTER_DB_USER_PASSWORD>
etcd_hosts: "{{ groups['etcd'] }}"
- name: Setup Redis and Sentinel
hosts: redis:sentinel
become: true
collections:
- infisical.infisical_core_ha_deployment
roles:
- role: redis
vars:
redis_password: "<ENTER_REDIS_PASSWORD>"
- name: Set up HAProxy
hosts: haproxy
become: true
collections:
- infisical.infisical_core_ha_deployment
roles:
- role: haproxy
vars:
stats_user: "<ENTER_HAPROXY_STATS_USERNAME>"
stats_password: "<ENTER_HAPROXY_STATS_PASSWORD>"
postgres_servers: "{{ groups['postgres'] }}"
infisical_servers: "{{ groups['infisical'] }}"
redis_servers: "{{ groups['redis'] }}"
- name: Setup Infisical
hosts: infisical
become: true
collections:
- infisical.infisical_core_ha_deployment
roles:
- role: infisical
env_vars:
ENCRYPTION_KEY: "YOUR_ENCRYPTION_KEY" # openssl rand -hex 16
AUTH_SECRET: "YOUR_AUTH_SECRET" # openssl rand -base64 32
```
</Step>
<Step title="Run the Ansible playbook">
After creating the `playbook.yml` and `inventory.ini` files, you can run the playbook using the following command
```bash
ansible-playbook -i inventory.ini playbook.yml
```
This step may take upwards of 10 minutes to complete, depending on the number of nodes and the network speed.
Once the playbook has completed, you should have a fully deployed high availability Infisical environment.
To access Infisical, you can try navigating to `http://52.1.0.2`, in order to view your newly deployed Infisical instance.
</Step>
</Steps>
## Post-deployment steps
After deploying Infisical in a high availability environment, you should perform the following post-deployment steps:
- Check your deployment to ensure that all services are running as expected. You can use the HAProxy monitoring panel to check the status of your services (http://52.1.0.2:7000/haproxy?stats)
- Attempt to access the Infisical Core instances to ensure that they are accessible from the internal load balancer. (http://52.1.0.2)
A HAProxy stats page indicating success will look like the image below
![HAProxy stats page](../../images/self-hosting/deployment-options/native/haproxy-stats.png)
## Security Considerations
### Network Security
Secure the network that your instances run on. While this falls outside the scope of Infisical deployment, it's crucial for overall security.
AWS-specific recommendations:
Use Virtual Private Cloud (VPC) to isolate your infrastructure.
Configure security groups to restrict inbound and outbound traffic.
Use Network Access Control Lists (NACLs) for additional network-level security.
<Note>
Please take note that the Infisical team cannot provide infrastructure support for **free self-hosted** deployments.<br/>If you need help with infrastructure, we recommend upgrading to a [paid plan](https://infisical.com/pricing) which includes infrastructure support.
You can also join our community [Slack](https://infisical.com/slack) for help and support from the community.
</Note>
### Troubleshooting
<Accordion title="Ansible: Failed to set permissions on the temporary files Ansible needs to create when becoming an unprivileged user">
If you encounter this issue, please update your ansible config (`ansible.cfg`) file with the following configuration:
```ini
[defaults]
allow_world_readable_tmpfiles = true
```
You can read more about the solution [here](https://docs.ansible.com/ansible/latest/collections/ansible/builtin/sh_shell.html#parameter-world_readable_temp)
</Accordion>
<Accordion title="I'm unable to connect to access the Infisical instance on the web">
This issue can be caused by a number of reasons, mostly realted to the network configuration. Here are a few things you can check:
1. Ensure that the firewall is not blocking the connection. You can check this by running `ufw status`. Ensure that port 80 is open.
2. If you're using a cloud provider like AWS or GCP, ensure that the security group allows traffic on port 80.
3. Ensure that the HAProxy service is running. You can check this by running `systemctl status haproxy`.
4. Ensure that the Infisical service is running. You can check this by running `systemctl status infisical`.
</Accordion>

5
docs/self-hosting/deployment-options/standalone-infisical.mdx
View File

@@ -22,11 +22,6 @@ The following guide provides a detailed step-by-step walkthrough on how you can
Remember to replace `<version>` with the docker image tag of your choice.
</Step>
<Step title="Run Postgres schema migration ">
Before you can start the instance of Infisical, you need to run the database schema migrations.
Follow the step by [step guide here](/self-hosting/configuration/schema-migrations) on running schema migrations for Infisical.
</Step>
<Step title="Start Infisical">
For a minimal installation of Infisical, you must configure `ENCRYPTION_KEY`, `AUTH_SECRET`, `DB_CONNECTION_URI`, `SITE_URL`, and `REDIS_URL`. [View all available configurations](/self-hosting/configuration/envars).

150
docs/self-hosting/guides/automated-bootstrapping.mdx Normal file
View File

@@ -0,0 +1,150 @@
---
title: "Programmatic Provisioning"
description: "Learn how to provision and configure Infisical instances programmatically without UI interaction"
---
Infisical's Automated Bootstrapping feature enables you to provision and configure an Infisical instance without using the UI, allowing for complete automation through static configuration files, API calls, or CLI commands. This is especially valuable for enterprise environments where automated deployment and infrastructure-as-code practices are essential.
## Overview
The Automated Bootstrapping workflow automates the following processes:
- Creating an admin user account
- Initializing an organization for the entire instance
- Establishing an **instance admin machine identity** with full administrative permissions
- Returning the machine identity credentials for further automation
## Key Concepts
- **Instance Initialization**: Infisical requires [configuration variables](/self-hosting/configuration/envars) to be set during launch, after which the bootstrap process can be triggered.
- **Instance Admin Machine Identity**: The bootstrapping process creates a machine identity with instance-level admin privileges, which can be used to programmatically manage all aspects of the Infisical instance.
![Instance Admin Identity](/images/self-hosting/guides/automated-bootstrapping/identity-instance-admin.png)
- **Token Auth**: The instance admin machine identity uses [Token Auth](/documentation/platform/identities/token-auth), providing a JWT token that can be used directly to make authenticated requests to the Infisical API.
## Prerequisites
- An Infisical instance launched with all required configuration variables
- Access to the Infisical CLI or the ability to make API calls to the instance
- Network connectivity to the Infisical instance
## Bootstrap Methods
You can bootstrap an Infisical instance using either the API or the CLI.
<Tabs>
<Tab title="Using the API">
Make a POST request to the bootstrap endpoint:
```
POST: http://your-infisical-instance.com/api/v1/admin/bootstrap
{
"email": "admin@example.com",
"password": "your-secure-password",
"organization": "your-org-name"
}
```
Example using curl:
```bash
curl -X POST \
-H "Content-Type: application/json" \
-d '{"email":"admin@example.com","password":"your-secure-password","organization":"your-org-name"}' \
http://your-infisical-instance.com/api/v1/admin/bootstrap
```
</Tab>
<Tab title="Using the CLI">
Use the [Infisical CLI](/cli/commands/bootstrap) to bootstrap the instance and extract the token for immediate use in automation:
```bash
infisical bootstrap --domain="http://localhost:8080" --email="admin@example.com" --password="your-secure-password" --organization="your-org-name" | jq ".identity.credentials.token"
```
This example command pipes the output through `jq` to extract only the machine identity token, making it easy to capture and use directly in automation scripts or export as an environment variable for tools like Terraform.
</Tab>
</Tabs>
## API Response Structure
The bootstrap process returns a JSON response with details about the created user, organization, and machine identity:
```json
{
"identity": {
"credentials": {
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZGVudGl0eUlkIjoiZGIyMjQ3OTItZWQxOC00Mjc3LTlkYWUtNTdlNzUyMzE1ODU0IiwiaWRlbnRpdHlBY2Nlc3NUb2tlbklkIjoiZmVkZmZmMGEtYmU3Yy00NjViLWEwZWEtZjM5OTNjMTg4OGRlIiwiYXV0aFRva2VuVHlwZSI6ImlkZW50aXR5QWNjZXNzVG9rZW4iLCJpYXQiOjE3NDIzMjI0ODl9.mqcZZqIFqER1e9ubrQXp8FbzGYi8nqqZwfMvz09g-8Y"
},
"id": "db224792-ed18-4277-9dae-57e752315854",
"name": "Instance Admin Identity"
},
"message": "Successfully bootstrapped instance",
"organization": {
"id": "b56bece0-42f5-4262-b25e-be7bf5f84957",
"name": "dog",
"slug": "dog-v-e5l"
},
"user": {
"email": "admin@example.com",
"firstName": "Admin",
"id": "a418f355-c8da-453c-bbc8-6c07208eeb3c",
"lastName": "User",
"superAdmin": true,
"username": "admin@example.com"
}
}
```
## Using the Instance Admin Machine Identity Token
The bootstrap process automatically creates a machine identity with Token Auth configured. The returned token has instance-level admin privileges (the highest level of access) and should be treated with the same security considerations as a root credential.
The token enables full programmatic control of your Infisical instance and can be used in the following ways:
### 1. Infrastructure Automation
Store the token securely for use with infrastructure automation tools. Due to the sensitive nature of this token, ensure it's protected using appropriate secret management practices:
#### Kubernetes Secret (with appropriate RBAC restrictions)
```yaml
apiVersion: v1
kind: Secret
metadata:
name: infisical-admin-credentials
type: Opaque
data:
token: <base64-encoded-token>
```
#### Environment Variable for Terraform
```bash
export INFISICAL_TOKEN=your-access-token
terraform apply
```
### 2. Programmatic Resource Management
Use the token to authenticate API calls for creating and managing Infisical resources. The token works exactly like any other Token Auth access token in the Infisical API:
```bash
curl -X POST \
-H "Authorization: Bearer ${INFISICAL_TOKEN}" \
-H "Content-Type: application/json" \
-d '{
"projectName": "New Project",
"projectDescription": "A project created via API",
"slug": "new-project-slug",
"template": "default",
"type": "SECRET_MANAGER"
}' \
https://your-infisical-instance.com/api/v2/projects
```
## Important Notes
- **Security Warning**: The instance admin machine identity has the highest level of privileges in your Infisical deployment. The token should be treated with the utmost security and handled like a root credential. Unauthorized access to this token could compromise your entire Infisical instance.
- Security controls prevent privilege escalation: instance admin identities cannot be managed by non-instance admin users and identities
- The instance admin permission of the generated identity can be revoked later in the server admin panel if needed
- The generated admin user account can still be used for UI access if needed, or can be removed if you prefer to manage everything through the machine identity
- This process is designed to work with future Crossplane providers and the existing Terraform provider for full infrastructure-as-code capabilities
- All necessary configuration variables should be set during the initial launch of the Infisical instance

57
docs/self-hosting/guides/upgrading-infisical.mdx Normal file
View File

@@ -0,0 +1,57 @@
---
title: "Upgrade Infisical Instance"
description: "How to upgrade Infisical self-hosted instance"
---
Keeping your Infisical instance up to date is key to making sure you receive the latest performance improvements, security patches, and feature updates.
We release updates approximately once a week, which may include new features, bug fixes, performance enhancements, and critical security patches.
Since secrets management is a critical component of your infrastructure, we aim to avoid disruptive changes that will impact fetching secrets in downstream clients.
If a release requires specific attention, a note will be attached to the corresponding [release](https://github.com/Infisical/infisical/releases) version.
During an upgrade, two key components are updated:
- **Infisical Application:** The core application code is updated.
- **PostgreSQL Database Schema:** Schema migrations run automatically to ensure your database remains in sync with the updated application.
> **Before You Upgrade:**
> **Always back up your database.** While our automated migration system is robust, having a backup ensures you can recover quickly in the event of an issue.
## Automated Schema Migrations
In previous versions (prior to `v0.111.0-postgres`), schema migrations had to be executed manually before starting the application.
Now, migrations run automatically during boot-up. This improvement streamlines the upgrade process, reduces manual steps, and minimizes the risk of inconsistencies between your database schema and application code.
### Benefits of Automated Migrations
- **Seamless Integration:**
Migrations are now part of the boot-up process, removing the need for manual intervention.
- **Synchronous Upgrades:**
In multi-instance deployments, one instance acquires a lock and performs the migration while the others wait. This ensures that if a migration fails, the rollout is halted to prevent inconsistencies.
- **Reduced Room for Error:**
Automatic migrations help ensure that your database schema always remains in sync with your application code.
## Upgrade Steps
1. **Back Up Your Data:**
- Ensure you have a complete backup of your Postgres database.
- Verify that your backup is current and accessible.
2. **Select the Upgrade Version:**
- Visit the [Infisical releases page](https://github.com/Infisical/infisical/releases) for a list of available versions.
- Look for releases with the prefix `infisical/` as there are other releases that are not related to the Infisical instance.
3. **Start the Upgrade Process:**
- Launch the new version of Infisical. During startup, the application will automatically compare the current database schema with the updated schema in the code.
- If any differences are detected, Infisical will apply the necessary migrations automatically.
4. **Multi-Instance Coordination:**
- In environments with multiple instances, one instance will acquire a lock and perform the migration while the other instances wait.
- Once the migration is complete, all instances will operate with the updated schema.
5. **Verify the Upgrade:**
- Review the logs for any migration errors or warnings.

8
docs/self-hosting/reference-architectures/aws-ecs.mdx
View File

@@ -1,5 +1,5 @@
---
title: "AWS ECS"
title: "AWS ECS (HA)"
description: "Reference architecture for self-hosting Infisical on AWS ECS"
---
@@ -48,9 +48,3 @@ This ensures that if there is a failure in one availability zone, the working re
<Accordion title="Can Infisical run in an air-gapped environment without any internet access?" defaultOpen >
Yes, Infisical can function in an air-gapped environment. To do so, update your ECS task to use the publicly available AWS Elastic Container Registry (ECR) image instead of the default Docker Hub image. Additionally, it's necessary to configure VPC endpoints, which allows your system to access AWS ECR via a private network route instead of the internet, ensuring all connectivity remains within the secure, private network.
</Accordion>
<Accordion title="Since RDS is in a private subnet, how do run the Postgres schema migrations?">
Since the Amazon RDS instance is housed within a private network to enhance security, it is not directly accessible from the internet. This means that in order to run the required [Postgres schema migrations](/self-hosting/configuration/schema-migrations), you need to connect to this instance of RDS. There are many approaches you can take:
- To automate schema migrations, you may setup CI/CD pipeline with access to the same RDS network to run the schema migrations before making deployment to ECS. This ensures that if migrations fail, your Infisical instances continues to run.
- If you would like to run the migrations manually, consider using AWS Systems Manager Session Manager to access the RDS within the VPC on your local machine.
- If your organization already has mechanisms in place for secure access to the VPC, such as VPNs or Direct Connect, these can also be utilized for performing database migrations manually.
</Accordion>

114
docs/self-hosting/reference-architectures/google-cloud-run.mdx Normal file
View File

@@ -0,0 +1,114 @@
---
title: "Google Cloud Run"
description: "Reference architecture for self-hosting Infisical on Google Cloud Run."
---
## Overview
This guide outlines a reference architecture for deploying Infisical in a self-hosted configuration using Google Cloud Run.
It is intended to provide a scalable, secure, and production-ready baseline for organizations choosing Google Cloud Platform (GCP) as their infrastructure provider.
## Core Components
- **Cloud Run:** Infisical service is containerized and deployed as fully managed Cloud Run services.
- **Cloud SQL:** Infisical uses Postgres as its persistence layer. As such, Cloud SQL for PostgreSQL is used.
- **MemoryStore for Redis:** To schedule jobs, process audit logs and cache performance, Infisical requires Redis.
## Securing Infisical's root credential
- **Secrets Manager:** To secure Infisical’s root credentials (database connection string, encryption key, etc.),
we highly recommend that you use Google Secrets Manager and only allow the tasks running Infisical to access them.
## High Availability and Scalability
This architecture leverages Google Cloud's managed services to achieve high availability and scalability out of the box:
**Cloud Run:**
- Automatically scales the number of container instances up or down based on incoming request volume.
- Supports rapid scaling during traffic spikes, ensuring low latency.
- Configurable minimum and maximum instances to handle baseline and peak loads.
**Cloud SQL:**
- Provides high availability configurations (regional instances with automatic failover) to ensure database uptime.
- Automated backups, point-in-time recovery, and maintenance.
**MemoryStore:**
- Offers highly available Redis configurations with replication.
- Fully managed with automatic scaling and patching.
**Cloud Load Balancer:**
- Distributes user traffic across available Cloud Run instances.
- Provides SSL termination, global load balancing, and health checks.
<Info>
**Note:** To further improve performance and availability, consider enabling multi-region deployment strategies,
regional VPC Connectors, and database replicas for read-heavy workloads.
</Info>
## Configuration
<Steps>
<Step title="Provision Core Infrastructure">
**Cloud SQL (PostgreSQL):**
- Create a Cloud SQL instance.
- Under `Zonal availability`, select the `Multiple zones` option to ensure High Availability.
- Configure private IP access.
**MemoryStore (Redis):**
- Deploy a Redis instance.
- Configure VPC access.
</Step>
<Step title="Get the Infisical Docker image">
Visit [Docker Hub](https://hub.docker.com/r/infisical/infisical/tags) and select a version of Infisical image you would like to deploy.
Then, within Cloud Run, paste the URL of the specific Infisical Docker image you would like to use within the `Container image URL` field.
![Cloud Run container image settings UI](/images/self-hosting/reference-architectures/google-cloud-run/cloud-run-container-image.png)
Remember to replace `<version>` with the docker image tag of your choice.
</Step>
<Step title="Set the environment variables">
For a minimal installation of Infisical, you must configure the following environment variables:
```bash
ENCRYPTION_KEY=<your_encryption_key>
AUTH_SECRET=<your_auth_secret>
DB_CONNECTION_URI="<your_db_connection_uri>"
SITE_URL="<your_site_url>"
REDIS_URL="<your_redis_url>"
```
[View all available configurations](/self-hosting/configuration/envars).
You will want to setup Postgres and Redis within Google Cloud Platform to connect to Infisical.
Once you have added the required environment variables to the `Environment Variables` section within Cloud Run,
create the container to get Infisical up and running.
![Cloud Run container environment variables settings UI](/images/self-hosting/reference-architectures/google-cloud-run/container-env-vars.png)
<Warning>
The above environment variable values are only to be used as an example and should not be used in production
</Warning>
</Step>
<Step title="Network Configuration">
Enable `Connect to a VPC for outbound traffic`: This enables the service to talk to private resources (e.g., a Cloud SQL database, Redis instance on a private IP) inside your Google Cloud VPC network.
Select `Send traffic directly to a VPC`: It gives lower latency and better performance, but uses more IPs from the subnet.
<Info>
Your Cloud Run revision must be in the same VPC network
</Info>
![Cloud Run container network settings UI](/images/self-hosting/reference-architectures/google-cloud-run/container-network-configuration.png)
Once the container is running, verify the installation by opening your web browser and navigating to the Site URL.
</Step>
</Steps>

383
docs/self-hosting/reference-architectures/linux-deployment-ha.mdx Normal file
View File

@@ -0,0 +1,383 @@
---
title: "Linux (HA)"
description: "Infisical High Availability Deployment architecture for Linux"
---
This guide describes how to achieve a highly available deployment of Infisical on Linux machines without containerization. The architecture provided serves as a foundation for minimum high availability, which you can scale based on your specific requirements.
## Architecture Overview
![High availability stack](/images/self-hosting/deployment-options/native/ha-stack.png)
The deployment consists of the following key components:
| Service | Nodes | Recommended Specs | GCP Instance | AWS Instance |
|---------------------------|-------|---------------------------|-----------------|--------------|
| External Load Balancer | 1 | 4 vCPU, 4 GB memory | n1-highcpu-4 | c5n.xlarge |
| Internal Load Balancer | 1 | 4 vCPU, 4 GB memory | n1-highcpu-4 | c5n.xlarge |
| Etcd Cluster | 3 | 4 vCPU, 4 GB memory | n1-highcpu-4 | c5n.xlarge |
| PostgreSQL Cluster | 3 | 2 vCPU, 8 GB memory | n1-standard-2 | m5.large |
| Redis + Sentinel | 3+3 | 2 vCPU, 8 GB memory | n1-standard-2 | m5.large |
| Infisical Core | 3 | 2 vCPU, 4 GB memory | n1-highcpu-2 | c5.large |
### Network Architecture
All servers operate within the 52.1.0.0/24 private network range with the following IP assignments:
| Service | IP Address |
|----------------------|------------|
| External Load Balancer| 52.1.0.1 |
| Internal Load Balancer| 52.1.0.2 |
| Etcd Node 1 | 52.1.0.3 |
| Etcd Node 2 | 52.1.0.4 |
| Etcd Node 3 | 52.1.0.5 |
| PostgreSQL Node 1 | 52.1.0.6 |
| PostgreSQL Node 2 | 52.1.0.7 |
| PostgreSQL Node 3 | 52.1.0.8 |
| Redis Node 1 | 52.1.0.9 |
| Redis Node 2 | 52.1.0.10 |
| Redis Node 3 | 52.1.0.11 |
| Sentinel Node 1 | 52.1.0.12 |
| Sentinel Node 2 | 52.1.0.13 |
| Sentinel Node 3 | 52.1.0.14 |
| Infisical Core 1 | 52.1.0.15 |
| Infisical Core 2 | 52.1.0.16 |
| Infisical Core 3 | 52.1.0.17 |
## Component Setup Guide
### 1. Configure Etcd Cluster
The Etcd cluster is needed for leader election in the PostgreSQL HA setup. Skip this step if using managed PostgreSQL.
1. Install Etcd on each node:
```bash
sudo apt update
sudo apt install etcd
```
2. Configure each node with unique identifiers and cluster membership. Example configuration for Node 1 (`/etc/etcd/etcd.conf`):
```yaml
name: etcd1
data-dir: /var/lib/etcd
initial-cluster-state: new
initial-cluster-token: etcd-cluster-1
initial-cluster: etcd1=http://52.1.0.3:2380,etcd2=http://52.1.0.4:2380,etcd3=http://52.1.0.5:2380
initial-advertise-peer-urls: http://52.1.0.3:2380
listen-peer-urls: http://52.1.0.3:2380
listen-client-urls: http://52.1.0.3:2379,http://127.0.0.1:2379
advertise-client-urls: http://52.1.0.3:2379
```
### 2. Configure PostgreSQL
For production deployments, you have two options for highly available PostgreSQL:
#### Option A: Managed PostgreSQL Service (Recommended for Most Users)
Use cloud provider managed services:
- AWS: Amazon RDS for PostgreSQL with Multi-AZ
- GCP: Cloud SQL for PostgreSQL with HA configuration
- Azure: Azure Database for PostgreSQL with zone redundant HA
These services handle replication, failover, and maintenance automatically.
#### Option B: Self-Managed PostgreSQL Cluster
Full HA installation guide of PostgreSQL is beyond the scope of this document. However, we have provided an overview of resources and code snippets below to guide your deployment.
1. Required Components:
- PostgreSQL 14+ on each node
- Patroni for cluster management
- Etcd for distributed consensus
2. Documentation we recommend you read:
- [Complete Patroni Setup Guide](https://patroni.readthedocs.io/en/latest/README.html)
- [PostgreSQL Replication Documentation](https://www.postgresql.org/docs/current/high-availability.html)
3. Key Steps Overview:
```bash
# 1. Install requirements on each PostgreSQL node
sudo apt update
sudo apt install -y postgresql-14 postgresql-contrib-14 python3-pip
pip3 install patroni[etcd] psycopg2-binary
# 2. Create Patroni config directory
sudo mkdir /etc/patroni
sudo chown postgres:postgres /etc/patroni
# 3. Create Patroni configuration (example for first node)
# /etc/patroni/config.yml - REQUIRES CAREFUL CUSTOMIZATION
```
```yaml
scope: infisical-cluster
namespace: /db/
name: postgresql1
restapi:
listen: 52.1.0.6:8008
connect_address: 52.1.0.6:8008
etcd:
hosts: 52.1.0.3:2379,52.1.0.4:2379,52.1.0.5:2379
bootstrap:
dcs:
ttl: 30
loop_wait: 10
retry_timeout: 10
maximum_lag_on_failover: 1048576
postgresql:
use_pg_rewind: true
parameters:
max_connections: 1000
shared_buffers: 2GB
work_mem: 8MB
max_worker_processes: 8
max_parallel_workers_per_gather: 4
max_parallel_workers: 8
wal_level: replica
hot_standby: "on"
max_wal_senders: 10
max_replication_slots: 10
hot_standby_feedback: "on"
```
4. Important considerations:
- Proper disk configuration for WAL and data directories
- Network latency between nodes
- Backup strategy and point-in-time recovery
- Monitoring and alerting setup
- Connection pooling configuration
- Security and network access controls
5. Recommended readings:
- [PostgreSQL Backup and Recovery](https://www.postgresql.org/docs/current/backup.html)
- [PostgreSQL Monitoring](https://www.postgresql.org/docs/current/monitoring.html)
### 3. Configure Redis and Sentinel
Similar to PostgreSQL, a full HA Redis setup guide is beyond the scope of this document. Below are the key resources and considerations for your deployment.
#### Option A: Managed Redis Service (Recommended for Most Users)
Use cloud provider managed Redis services:
- AWS: ElastiCache for Redis with Multi-AZ
- GCP: Memorystore for Redis with HA
- Azure: Azure Cache for Redis with zone redundancy
Follow your cloud provider's documentation:
- [AWS ElastiCache Documentation](https://docs.aws.amazon.com/AmazonElastiCache/latest/red-ug/WhatIs.html)
- [GCP Memorystore Documentation](https://cloud.google.com/memorystore/docs/redis)
- [Azure Redis Cache Documentation](https://learn.microsoft.com/en-us/azure/azure-cache-for-redis/)
#### Option B: Self-Managed Redis Cluster
Setting up a production Redis HA cluster requires understanding several components. Refer to these linked resources:
1. Required Reading:
- [Redis Sentinel Documentation](https://redis.io/docs/management/sentinel/)
- [Redis Replication Guide](https://redis.io/topics/replication)
- [Redis Security Guide](https://redis.io/topics/security)
2. Key Steps Overview:
```bash
# 1. Install Redis on all nodes
sudo apt update
sudo apt install redis-server
# 2. Configure master node (52.1.0.9)
# /etc/redis/redis.conf
```
```conf
bind 52.1.0.9
port 6379
dir /var/lib/redis
maxmemory 3gb
maxmemory-policy noeviction
requirepass "your_redis_password"
masterauth "your_redis_password"
```
3. Configure replica nodes (`52.1.0.10`, `52.1.0.11`):
```conf
bind 52.1.0.10 # Change for each replica
port 6379
dir /var/lib/redis
replicaof 52.1.0.9 6379
masterauth "your_redis_password"
requirepass "your_redis_password"
```
4. Configure Sentinel nodes (`52.1.0.12`, `52.1.0.13`, `52.1.0.14`):
```conf
port 26379
sentinel monitor mymaster 52.1.0.9 6379 2
sentinel auth-pass mymaster "your_redis_password"
sentinel down-after-milliseconds mymaster 5000
sentinel failover-timeout mymaster 60000
sentinel parallel-syncs mymaster 1
```
5. Recommended Additional Reading:
- [Redis High Availability Tools](https://redis.io/topics/high-availability)
- [Redis Sentinel Client Implementation](https://redis.io/topics/sentinel-clients)
### 4. Configure HAProxy Load Balancer
Install and configure HAProxy for internal load balancing:
```conf ha-proxy-config
global
maxconn 10000
log stdout format raw local0
defaults
log global
mode tcp
retries 3
timeout client 30m
timeout connect 10s
timeout server 30m
timeout check 5s
listen stats
mode http
bind *:7000
stats enable
stats uri /
resolvers hostdns
nameserver dns 127.0.0.11:53
resolve_retries 3
timeout resolve 1s
timeout retry 1s
hold valid 5s
frontend postgres_master
bind *:5000
default_backend postgres_master_backend
frontend postgres_replicas
bind *:5001
default_backend postgres_replica_backend
backend postgres_master_backend
option httpchk GET /master
http-check expect status 200
default-server inter 3s fall 3 rise 2 on-marked-down shutdown-sessions
server postgres-1 52.1.0.6:5432 check port 8008
server postgres-2 52.1.0.7:5432 check port 8008
server postgres-3 52.1.0.8:5432 check port 8008
backend postgres_replica_backend
option httpchk GET /replica
http-check expect status 200
default-server inter 3s fall 3 rise 2 on-marked-down shutdown-sessions
server postgres-1 52.1.0.6:5432 check port 8008
server postgres-2 52.1.0.7:5432 check port 8008
server postgres-3 52.1.0.8:5432 check port 8008
frontend redis_master_frontend
bind *:6379
default_backend redis_master_backend
backend redis_master_backend
option tcp-check
tcp-check send AUTH\ 123456\r\n
tcp-check expect string +OK
tcp-check send PING\r\n
tcp-check expect string +PONG
tcp-check send info\ replication\r\n
tcp-check expect string role:master
tcp-check send QUIT\r\n
tcp-check expect string +OK
server redis-1 52.1.0.9:6379 check inter 1s
server redis-2 52.1.0.10:6379 check inter 1s
server redis-3 52.1.0.11:6379 check inter 1s
frontend infisical_frontend
bind *:80
default_backend infisical_backend
backend infisical_backend
option httpchk GET /api/status
http-check expect status 200
server infisical-1 52.1.0.15:8080 check inter 1s
server infisical-2 52.1.0.16:8080 check inter 1s
server infisical-3 52.1.0.17:8080 check inter 1s
```
### 5. Deploy Infisical Core
<Tabs>
<Tab title="Debian/Ubuntu">
First, add the Infisical repository:
```bash
curl -1sLf \
'https://dl.cloudsmith.io/public/infisical/infisical-core/setup.deb.sh' \
| sudo -E bash
```
Then install Infisical:
```bash
sudo apt-get update && sudo apt-get install -y infisical-core
```
<Info>
For production environments, we strongly recommend installing a specific version of the package to maintain consistency across reinstalls. View available versions at [Infisical Package Versions](https://cloudsmith.io/~infisical/repos/infisical-core/packages/).
</Info>
</Tab>
<Tab title="RedHat/CentOS/Amazon Linux">
First, add the Infisical repository:
```bash
curl -1sLf \
'https://dl.cloudsmith.io/public/infisical/infisical-core/setup.rpm.sh' \
| sudo -E bash
```
Then install Infisical:
```bash
sudo yum install infisical-core
```
<Info>
For production environments, we strongly recommend installing a specific version of the package to maintain consistency across reinstalls. View available versions at [Infisical Package Versions](https://cloudsmith.io/~infisical/repos/infisical-core/packages/).
</Info>
</Tab>
</Tabs>
Next, create configuration file `/etc/infisical/infisical.rb` with the following:
```ruby
infisical_core['ENCRYPTION_KEY'] = 'your-secure-encryption-key'
infisical_core['AUTH_SECRET'] = 'your-secure-auth-secret'
infisical_core['DB_CONNECTION_URI'] = 'postgres://user:pass@52.1.0.2:5000/infisical'
infisical_core['REDIS_URL'] = 'redis://52.1.0.2:6379'
infisical_core['PORT'] = 8080
```
To generate `ENCRYPTION_KEY` and `AUTH_SECRET` view the [following configurations documentation here](/self-hosting/configuration/envars).
If you are using managed services for either Postgres or Redis, please replace the values of the secrets accordingly.
Lastly, start and verify each node running infisical-core:
```bash
sudo infisical-ctl reconfigure
sudo infisical-ctl status
```
## Monitoring and Maintenance
1. Monitor HAProxy stats: `http://52.1.0.2:7000/haproxy?stats`
2. Monitor Infisical logs: `sudo infisical-ctl tail`
3. Check cluster health:
- Etcd: `etcdctl cluster-health`
- PostgreSQL: `patronictl list`
- Redis: `redis-cli info replication`

231
docs/self-hosting/reference-architectures/on-prem-k8s-ha.mdx Normal file
View File

@@ -0,0 +1,231 @@
---
title: "Kubernetes (HA)"
description: "Reference architecture for self-hosting Infisical on Kubernetes (HA)"
---
Deploying Infisical on-premise with high availability requires expertise in networking, container orchestration, and database management.
This guide serves as a reference architecture and a starting point. Actual deployments may vary depending on your organization's existing infrastructure and capabilities.
## Architecture Overview
{/* ![On premise architecture](/images/self-hosting/reference-architectures/on-premise-architecture.png) */}
```mermaid
flowchart TB
subgraph GLB["Global LB (HAProxy/NGINX)"]
end
subgraph OS["Object Storage"]
direction LR
store["S3/MinIO/Enterprise Storage"]
subgraph store_contents["Storage Contents"]
wal["PostgreSQL WAL"]
pgbackup["PostgreSQL Backups"]
redisbackup["Redis Backups"]
end
end
subgraph DC1["Active Data Center"]
direction TB
subgraph k8s1["Kubernetes Cluster"]
ing1["Ingress Controller"]
app1["Infisical Deployment"]
subgraph db1["CloudNativePG"]
pg1p["PostgreSQL Primary"]
pg1r["PostgreSQL Replicas"]
end
subgraph red1["Redis (Bitnami)"]
rp1["Redis Primary"]
end
end
end
subgraph DC2["Passive Data Center"]
direction TB
subgraph k8s2["Kubernetes Cluster"]
ing2["Ingress Controller"]
app2["Infisical Deployment"]
subgraph db2["CloudNativePG"]
pg2["PostgreSQL Replicas"]
end
subgraph red2["Redis (Bitnami)"]
r2["Redis Standby"]
end
end
end
%% Connections
GLB --> ing1
GLB -.-> ing2
%% Database connections
pg1p --> store
store --> pg2
%% Redis backup flow
rp1 --> store
store -.-> r2
%% Intra-DC connections
ing1 --> app1
app1 --> db1
app1 --> red1
ing2 --> app2
app2 --> db2
app2 --> red2
classDef primary fill:#f96,stroke:#333
classDef replica fill:#69f,stroke:#333
classDef storage fill:#9c6,stroke:#333
classDef lb fill:#c9f,stroke:#333
class pg1p,rp1 primary
class pg1r,pg2,r2 replica
class store,wal,pgbackup,redisbackup storage
class GLB,ing1,ing2 lb
```
The architecture above makes use of Kubernetes for orchestrating both stateless and stateful components.
The architecture spans multiple data centers for increased redundancy, availability and disaster recovery capabilities using an active-passive configuration.
### Stateful vs stateless workloads
While managing databases within Kubernetes has typically been complex, modern operators like [CloudNativePG](https://cloudnative-pg.io/) simplify this process by handling storage provisioning, persistent volume management, and backup/recovery processes.
However, if you lack deep expertise in Kubernetes operators or database management, we recommend a hybrid approach where the database is on a managed service for production deployments.
<Warning>
Managing stateful components like databases can be challenging without deep expertise or a dedicated in-house database management team.
To simplify operations and reduce complexity, we recommend offloading databases to managed services from AWS/GCP.
These managed services automatically handle provisioning, scaling, failover, backups and rollbacks.
</Warning>
## Core Components
### Kubernetes Cluster
Infisical is deployed on a Kubernetes cluster, which allows for container management, auto-scaling, and self-healing capabilities.
A load balancer sits in front of the Kubernetes cluster, directing traffic and making sure there is an even load distribution across the application nodes.
This is the entry point where all other services will interact with Infisical.
### Object Storage
The architecture requires S3-compatible object storage for database backups and cross-datacenter replication. This can be provided by:
- Existing enterprise object storage solution
- Dedicated MinIO deployment
- In-cluster MinIO deployment if neither option above is available
The object storage must be accessible from all Kubernetes clusters and provides:
- Storage for PostgreSQL WAL archiving and backups
- Storage for Redis backups
### CloudNativePG for High Availability PostgreSQL
The database layer is powered by PostgreSQL, managed by CloudNativePG operator for high availability:
- **Redundancy:** CloudNativePG manages a primary-replica setup where the primary handles write operations and replicas handle read operations
- **Failover:** The operator automatically handles failover within a cluster by promoting a replica to primary when needed
- **Backup and Recovery:** Built-in support for backup to S3-compatible storage with point-in-time recovery capabilities
### Redis High Availability
Redis is deployed using the [Bitnami Helm chart](https://github.com/bitnami/charts/tree/main/bitnami/redis) in a simple primary configuration:
- Single Redis instance per cluster without streaming replication
- Regular backups to object storage
- Restore from backup during failover
<Note>
Infisical does not support Redis cluster mode, and since this is an active-passive setup, we use a simple Redis deployment with backup/restore for failover.
</Note>
#### PostgreSQL Backup and Restore
PostgreSQL is the single source of truth for nearly all application data on Infisical.
CloudNativePG provides well defined backup and restore capabilities:
- **Continuous Backup:** The operator continuously archives WAL files to object storage
- **Point-in-Time Recovery:** Supports restoring to any point in time using WAL archiving
- **Regular Testing:** Periodically test backup restoration to exercise the full lifecycle of this process
#### Redis Backup and Restore
Each Redis instance is backed up through a Kubernetes CronJob that:
1. Executes the Redis `SAVE` command
2. Copies the resulting `dump.rdb` to object storage
3. Manages backup retention
<Accordion title="Example Redis backup CronJob">
```yaml
apiVersion: batch/v1
kind: CronJob
metadata:
name: redis-backup
spec:
schedule: "0 * * * *" # Every hour
jobTemplate:
spec:
template:
spec:
containers:
- name: redis-backup
image: bitnami/redis
command:
- /bin/sh
- -c
- |
redis-cli -a $REDIS_PASSWORD save
mc cp /data/dump.rdb object-store/redis-backups/
volumes:
- name: redis-data
persistentVolumeClaim:
claimName: redis-data
```
</Accordion>
During failover, the latest Redis backup is restored from object storage to the passive data center. This process is manual and requires operator intervention.
## Multi Data Center Deployment
Infisical can be deployed across multiple data centers in an active-passive configuration for disaster recovery. In this setup, one data center serves as the active site while others remain as passive standbys.
### Active Data Center
The active data center contains:
- The primary PostgreSQL cluster managed by CloudNativePG handling all write operations
- The active Redis instance handling all traffic
- The active Infisical deployment serving all user traffic
### Passive Data Centers
Passive data centers act as disaster recovery sites. Each contains:
- A replica PostgreSQL cluster that replicates from the active site's primary cluster
- A standby Redis instance (not receiving traffic)
- A standby Infisical deployment (not receiving traffic)
### Traffic Management and Failover
Traffic routing between data centers requires:
1. A global load balancer for traffic management. For on-premises deployments, this can be implemented using:
- HAProxy or NGINX configured as a global load balancer
- Any enterprise network routing solutions you may already have in place
2. Each data center should have its own ingress or load balancer
The global load balancer should be deployed in a highly available configuration across multiple locations to avoid it becoming a single point of failure.
During normal operation:
- The global load balancer routes all traffic to the active data center
- Replica PostgreSQL clusters continuously replicate from the primary cluster
- Redis backups are regularly created and stored in object storage
During failover:
- A human operator must initiate the failover process
- The operator promotes a replica PostgreSQL cluster in the target passive data center to become primary using CloudNativePG's promotion process
- The latest Redis backup is restored from object storage to the passive data center's Redis instance
- Once database failover is complete, the global load balancer is updated to direct traffic to the new active data center
<Note>
This is an active-passive setup where failover must be initiated manually by an operator. Automatic failover between data centers is not recommended as it can lead to split-brain scenarios. The operator should verify the state of both data centers before initiating failover.
</Note>
## Data Replication Across Data Centers
### PostgreSQL Replication
CloudNativePG manages replication across data centers:
- **Replica Clusters:** Each data center runs a replica cluster that replicates from the primary cluster
- **WAL Shipping:** Changes are replicated via WAL shipping to object storage
- **Failover:** The operator can promote a replica cluster to primary during planned switchovers or failures
### Object Storage Configuration
If using MinIO for object storage, ensure:
- High availability deployment if running dedicated MinIO cluster
- Proper access controls and encryption for data at rest
- Regular monitoring of storage capacity and performance
- Backup of object storage data itself if running your own MinIO deployment