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

misc: doc updates

Browse Source
This commit is contained in:
Sheen Capadngan
2025-09-09 02:57:22 +08:00
parent 43d6c13657
commit 49742b2a4e
8 changed files with 732 additions and 540 deletions
Download Patch File Download Diff File Expand all files Collapse all files

78
docs/documentation/platform/gateways/networking.mdx
View File

@@ -3,17 +3,17 @@ title: "Networking"
description: "Network configuration and firewall requirements for Infisical Gateway"
---
The Infisical Gateway requires outbound network connectivity to establish secure SSH reverse tunnels with proxy servers.
The Infisical Gateway requires outbound network connectivity to establish secure SSH reverse tunnels with relay servers.
This page outlines the required ports, protocols, and firewall configurations needed for optimal gateway usage.
## Network Architecture
The gateway uses SSH reverse tunnels to establish secure connections with end-to-end encryption:
1. **Gateway** connects outbound to **Proxy Servers** using SSH over TCP
1. **Gateway** connects outbound to **Relay Servers** using SSH over TCP
2. **Infisical platform** establishes mTLS connections with gateways for application traffic
3. **Proxy Servers** route the doubly-encrypted traffic (mTLS payload within SSH tunnels) between the platform and gateways
4. **Double encryption** ensures proxy servers cannot access application data - only the platform and gateway can decrypt traffic
3. **Relay Servers** route the doubly-encrypted traffic (mTLS payload within SSH tunnels) between the platform and gateways
4. **Double encryption** ensures relay servers cannot access application data - only the platform and gateway can decrypt traffic
## Required Network Connectivity
@@ -23,34 +23,34 @@ The gateway requires the following outbound connectivity:
| Protocol | Destination | Ports | Purpose |
| -------- | ------------------------------------ | ----- | ------------------------------------------ |
| TCP | Proxy Servers | 2222 | SSH reverse tunnel establishment |
| TCP | Relay Servers | 2222 | SSH reverse tunnel establishment |
| TCP | app.infisical.com / eu.infisical.com | 443 | API communication and certificate requests |
### Proxy Server Connectivity
### Relay Server Connectivity
**For Instance Proxies (Infisical Cloud):** Your firewall must allow outbound connectivity to Infisical-managed proxy servers.
**For Instance Relays (Infisical Cloud):** Your firewall must allow outbound connectivity to Infisical-managed relay servers.
**For Organization Proxies:** Your firewall must allow outbound connectivity to your own proxy server IP addresses.
**For Organization Relays:** Your firewall must allow outbound connectivity to your own relay server IP addresses.
**For Self-hosted Instance Proxies:** Your firewall must allow outbound connectivity to proxy servers configured by your instance administrator.
**For Self-hosted Instance Relays:** Your firewall must allow outbound connectivity to relay servers configured by your instance administrator.
<Tabs>
<Tab title="Instance Proxies (Infisical Cloud)">
Infisical provides multiple managed proxy servers with static IP addresses.
You can whitelist these IPs ahead of time based on which proxy server you
<Tab title="Instance Relays (Infisical Cloud)">
Infisical provides multiple managed relay servers with static IP addresses.
You can whitelist these IPs ahead of time based on which relay server you
choose to connect to. **Firewall requirements:** Allow outbound TCP
connections to the desired proxy server IP on port 2222.
connections to the desired relay server IP on port 2222.
</Tab>
<Tab title="Organization Proxies">
You control the proxy server IP addresses when deploying your own
organization proxies. **Firewall requirements:** Allow outbound TCP
connections to your proxy server IP on port 2222. For example, if your proxy
<Tab title="Organization Relays">
You control the relay server IP addresses when deploying your own
organization relays. **Firewall requirements:** Allow outbound TCP
connections to your relay server IP on port 2222. For example, if your relay
is at `203.0.113.100`, allow TCP to `203.0.113.100:2222`.
</Tab>
<Tab title="Self-hosted Instance Proxies">
Contact your instance administrator for the proxy server IP addresses
<Tab title="Self-hosted Instance Relays">
Contact your instance administrator for the relay server IP addresses
configured for your deployment. **Firewall requirements:** Allow outbound
TCP connections to instance proxy servers on port 2222.
TCP connections to instance relay servers on port 2222.
</Tab>
</Tabs>
@@ -60,7 +60,7 @@ The gateway requires the following outbound connectivity:
The gateway uses SSH reverse tunnels for primary communication:
- **Port 2222**: SSH connection to proxy servers
- **Port 2222**: SSH connection to relay servers
- **Built-in features**: Automatic reconnection, certificate-based authentication, encrypted tunneling
- **Encryption**: SSH with certificate-based authentication and key exchange
@@ -81,7 +81,7 @@ SSH connections over TCP are stateful and handled seamlessly by all modern firew
Since SSH uses TCP, you only need simple outbound rules:
1. **Allow outbound TCP** to proxy servers on port 2222
1. **Allow outbound TCP** to relay servers on port 2222
2. **Allow outbound HTTPS** to Infisical API endpoints on port 443
3. **No inbound rules required** - all connections are outbound only
@@ -91,7 +91,7 @@ Since SSH uses TCP, you only need simple outbound rules:
For corporate environments with strict egress filtering:
1. **Allow outbound TCP** to proxy servers on port 2222
1. **Allow outbound TCP** to relay servers on port 2222
2. **Allow outbound HTTPS** to the Infisical API server on port 443
3. **No inbound rules required** - all connections are outbound only
4. **Standard TCP rules** - simple and straightforward configuration
@@ -100,7 +100,7 @@ For corporate environments with strict egress filtering:
Configure security groups to allow:
- **Outbound TCP** to proxy servers on port 2222
- **Outbound TCP** to relay servers on port 2222
- **Outbound HTTPS** to app.infisical.com/eu.infisical.com on port 443
- **No inbound rules required** - SSH reverse tunnels are outbound only
@@ -109,7 +109,7 @@ Configure security groups to allow:
<Accordion title="What happens if there is a network interruption?">
The gateway is designed to handle network interruptions gracefully:
- **Automatic reconnection**: The gateway will automatically attempt to reconnect to proxy servers if the SSH connection is lost
- **Automatic reconnection**: The gateway will automatically attempt to reconnect to relay servers if the SSH connection is lost
- **Connection retry logic**: Built-in retry mechanisms handle temporary network outages without manual intervention
- **Persistent SSH tunnels**: SSH connections are automatically re-established when connectivity is restored
- **Certificate rotation**: The gateway handles certificate renewal automatically during reconnection
@@ -135,7 +135,7 @@ TCP's reliability and firewall compatibility make it ideal for enterprise enviro
<Accordion title="Do I need to open any inbound ports on my firewall?">
No inbound ports need to be opened. The gateway only makes outbound connections:
- **Outbound SSH** to proxy servers on port 2222
- **Outbound SSH** to relay servers on port 2222
- **Outbound HTTPS** to Infisical API endpoints on port 443
- **SSH reverse tunnels** handle all communication - no return traffic configuration needed
@@ -146,32 +146,32 @@ This design maintains security by avoiding the need for inbound firewall rules t
<Accordion title="What if my firewall blocks SSH connections?">
If your firewall has strict outbound restrictions:
1. **Work with your network team** to allow outbound TCP connections on port 2222 to proxy servers
1. **Work with your network team** to allow outbound TCP connections on port 2222 to relay servers
2. **Allow standard SSH traffic** - most enterprises already have SSH policies in place
3. **Consider network policy exceptions** for the gateway host if needed
4. **Monitor firewall logs** to identify which specific rules are blocking traffic
</Accordion>
<Accordion title="How many proxy servers does the gateway connect to?">
The gateway connects to **one proxy server**:
<Accordion title="How many relay servers does the gateway connect to?">
The gateway connects to **one relay server**:
- **Single SSH connection**: Each gateway establishes one SSH reverse tunnel to its assigned proxy server
- **Named proxy assignment**: Gateways connect to the specific proxy server specified by `--proxy-name`
- **Automatic reconnection**: If the proxy connection is lost, the gateway automatically reconnects to the same proxy
- **Single SSH connection**: Each gateway establishes one SSH reverse tunnel to its assigned relay server
- **Named relay assignment**: Gateways connect to the specific relay server specified by `--relay`
- **Automatic reconnection**: If the relay connection is lost, the gateway automatically reconnects to the same relay
- **Certificate-based authentication**: Each connection uses SSH certificates issued by Infisical for secure authentication
</Accordion>
<Accordion title="Can the proxy servers decrypt traffic going through them?">
No, proxy servers cannot decrypt any traffic passing through them due to end-to-end encryption:
<Accordion title="Can the relay servers decrypt traffic going through them?">
No, relay servers cannot decrypt any traffic passing through them due to end-to-end encryption:
- **Client-to-Gateway mTLS**: Clients establish mTLS connections directly with gateways, encrypting all application traffic
- **SSH tunnel encryption**: The mTLS-encrypted traffic is then transmitted through SSH reverse tunnels to proxy servers
- **Client-to-Gateway mTLS (via TLS-pinned tunnel)**: Clients connect via a proxy that establishes a TLS-pinned tunnel to the gateway; mTLS between the client and gateway is negotiated inside this tunnel, encrypting all application traffic
- **SSH tunnel encryption**: The mTLS-encrypted traffic is then transmitted through SSH reverse tunnels to relay servers
- **Double encryption**: Traffic is encrypted twice - once by client mTLS and again by SSH tunnels
- **Proxy acts as a relay**: The proxy server only routes the doubly-encrypted traffic without access to either encryption layer
- **No data storage**: Proxy servers do not store any traffic or sensitive information
- **Relay only routes traffic**: The relay server only routes the doubly-encrypted traffic without access to either encryption layer
- **No data storage**: Relay servers do not store any traffic or sensitive information
- **Certificate isolation**: Each connection uses unique certificates, ensuring complete tenant isolation
The proxy infrastructure is designed as a secure routing mechanism where only the client and gateway can decrypt the actual application traffic.
The relay infrastructure is designed as a secure routing mechanism where only the client and gateway can decrypt the actual application traffic.
</Accordion>

66
docs/documentation/platform/gateways/overview.mdx
View File

@@ -11,7 +11,7 @@ The Infisical Gateway provides secure access to private resources within your ne
**Architecture Components:**
- **Gateway**: Lightweight agent deployed within your VPCs that provides access to private resources
- **Proxy**: Identity-aware relay infrastructure that routes encrypted traffic (instance-wide or organization-specific)
- **Relay**: Infrastructure that routes encrypted traffic (instance-wide or organization-specific)
Common use cases include generating dynamic credentials or rotating credentials for private databases.
@@ -26,8 +26,8 @@ Common use cases include generating dynamic credentials or rotating credentials
The Gateway system uses SSH reverse tunnels for secure, firewall-friendly connectivity:
1. **Gateway Registration**: The gateway establishes an outbound SSH reverse tunnel to a proxy server using SSH certificates issued by Infisical
2. **Proxy Routing**: The proxy server acts as an identity-aware relay that routes encrypted traffic between the Infisical platform and gateways
1. **Gateway Registration**: The gateway establishes an outbound SSH reverse tunnel to a relay server using SSH certificates issued by Infisical
2. **Relay Routing**: The relay server routes encrypted traffic between the Infisical platform and gateways
3. **Resource Access**: The Infisical platform connects to your private resources through the established gateway connections
**Key Benefits:**
@@ -39,18 +39,18 @@ The Gateway system uses SSH reverse tunnels for secure, firewall-friendly connec
## Deployment
The Infisical Gateway is integrated into the Infisical CLI under the `network gateway` command, making it simple to deploy and manage.
The Infisical Gateway is integrated into the Infisical CLI under the `gateway` command, making it simple to deploy and manage.
You can install the Gateway in all the same ways you install the Infisical CLI—whether via npm, Docker, or a binary.
For detailed installation instructions, refer to the Infisical [CLI Installation instructions](/cli/overview).
**Prerequisites:**
1. **Proxy Server**: Before deploying gateways, you need a running proxy server:
- **Infisical Cloud**: Instance proxies are already available - no setup needed
- **Self-hosted**: Instance admin must set up shared instance proxies, or organizations can deploy their own
1. **Relay Server**: Before deploying gateways, you need a running relay server:
- **Infisical Cloud**: Instance relays are already available - no setup needed
- **Self-hosted**: Instance admin must set up shared instance relays, or organizations can deploy their own
2. **Machine Identity**: Configure a machine identity with appropriate permissions to create and manage gateways
Once authenticated, the Gateway establishes an SSH reverse tunnel to the specified proxy server, allowing secure access to your private resources.
Once authenticated, the Gateway establishes an SSH reverse tunnel to the specified relay server, allowing secure access to your private resources.
### Get started
@@ -66,25 +66,25 @@ Once authenticated, the Gateway establishes an SSH reverse tunnel to the specifi
You'll need to choose an authentication method to initiate communication with Infisical. View the available machine identity authentication methods [here](/documentation/platform/identities/machine-identities).
</Step>
<Step title="Choose Your Proxy Setup">
You have two options for proxy infrastructure:
<Step title="Choose Your Relay Setup">
You have two options for relay infrastructure:
<Tabs>
<Tab title="Use Instance Proxies (Easiest)">
**Infisical Cloud:** Instance proxies are already running and available - **no setup required**. You can immediately proceed to deploy gateways using these shared proxies.
<Tab title="Use Instance Relays (Easiest)">
**Infisical Cloud:** Instance relays are already running and available - **no setup required**. You can immediately proceed to deploy gateways using these shared relays.
**Self-hosted:** If your instance admin has set up shared instance proxies, you can use them directly. If not, the instance admin can set them up:
**Self-hosted:** If your instance admin has set up shared instance relays, you can use them directly. If not, the instance admin can set them up:
```bash
# Instance admin sets up shared proxy (one-time setup)
export INFISICAL_PROXY_AUTH_SECRET=<instance-proxy-secret>
infisical network proxy --type=instance --ip=<public-ip> --name=<proxy-name>
# Instance admin sets up shared relay (one-time setup)
export INFISICAL_RELAY_AUTH_SECRET=<instance-relay-secret>
infisical relay start --type=instance --ip=<public-ip> --name=<relay-name>
```
</Tab>
<Tab title="Deploy Your Own Organization Proxy">
**Available for all users:** Deploy your own dedicated proxy infrastructure for enhanced control:
<Tab title="Deploy Your Own Organization Relay">
**Available for all users:** Deploy your own dedicated relay infrastructure for enhanced control:
```bash
# Deploy organization-specific proxy
infisical network proxy --type=org --ip=<public-ip> --name=<proxy-name> --auth-method=universal-auth --client-id=<client-id> --client-secret=<client-secret>
# Deploy organization-specific relay
infisical relay start --type=org --ip=<public-ip> --name=<relay-name> --auth-method=universal-auth --client-id=<client-id> --client-secret=<client-secret>
```
**When to choose this:**
@@ -103,7 +103,7 @@ Once authenticated, the Gateway establishes an SSH reverse tunnel to the specifi
<Tab title="Production (systemd)">
For production deployments on Linux, install the Gateway as a systemd service:
```bash
sudo infisical network gateway install --token <your-machine-identity-token> --domain <your-infisical-domain> --name <gateway-name> --proxy-name <proxy-name>
sudo infisical gateway systemd install --token <your-machine-identity-token> --domain <your-infisical-domain> --name <gateway-name> --relay <relay-name>
sudo systemctl start infisical-gateway
```
This will install and start the Gateway as a secure systemd service that:
@@ -170,7 +170,7 @@ Once authenticated, the Gateway establishes an SSH reverse tunnel to the specifi
--from-literal=INFISICAL_AUTH_METHOD=universal-auth \
--from-literal=INFISICAL_UNIVERSAL_AUTH_CLIENT_ID=<client-id> \
--from-literal=INFISICAL_UNIVERSAL_AUTH_CLIENT_SECRET=<client-secret> \
--from-literal=INFISICAL_PROXY_NAME=<proxy-name> \
--from-literal=INFISICAL_RELAY_NAME=<relay-name> \
--from-literal=INFISICAL_GATEWAY_NAME=<gateway-name>
```
@@ -343,8 +343,8 @@ Once authenticated, the Gateway establishes an SSH reverse tunnel to the specifi
In addition to the authentication method above, you **must** include these required variables:
<AccordionGroup>
<Accordion title="INFISICAL_PROXY_NAME">
The name of the proxy server that this gateway should connect to.
<Accordion title="INFISICAL_RELAY_NAME">
The name of the relay server that this gateway should connect to.
</Accordion>
<Accordion title="INFISICAL_GATEWAY_NAME">
The name of this gateway instance.
@@ -357,7 +357,7 @@ Once authenticated, the Gateway establishes an SSH reverse tunnel to the specifi
--from-literal=INFISICAL_AUTH_METHOD=universal-auth \
--from-literal=INFISICAL_UNIVERSAL_AUTH_CLIENT_ID=<client-id> \
--from-literal=INFISICAL_UNIVERSAL_AUTH_CLIENT_SECRET=<client-secret> \
--from-literal=INFISICAL_PROXY_NAME=<proxy-name> \
--from-literal=INFISICAL_RELAY_NAME=<relay-name> \
--from-literal=INFISICAL_GATEWAY_NAME=<gateway-name>
```
@@ -388,8 +388,8 @@ Once authenticated, the Gateway establishes an SSH reverse tunnel to the specifi
INF Starting gateway
INF Starting gateway certificate renewal goroutine
INF Successfully registered gateway and received certificates
INF Connecting to proxy server infisical-start on 152.42.218.156:2222...
INF Proxy connection established for gateway
INF Connecting to relay server infisical-start on 152.42.218.156:2222...
INF Relay connection established for gateway
```
</Tab>
@@ -397,29 +397,29 @@ Once authenticated, the Gateway establishes an SSH reverse tunnel to the specifi
<Tab title="Local Installation (testing)">
For development or testing, you can run the Gateway directly. Log in with your machine identity and start the Gateway in one command:
```bash
infisical network gateway --token $(infisical login --method=universal-auth --client-id=<> --client-secret=<> --plain) --proxy-name=<proxy-name> --name=<gateway-name>
infisical gateway start --token $(infisical login --method=universal-auth --client-id=<> --client-secret=<> --plain) --relay=<relay-name> --name=<gateway-name>
```
Alternatively, if you already have the token, use it directly with the `--token` flag:
```bash
infisical network gateway --token <your-machine-identity-token> --proxy-name=<proxy-name> --name=<gateway-name>
infisical gateway start --token <your-machine-identity-token> --relay=<relay-name> --name=<gateway-name>
```
Or set it as an environment variable:
```bash
export INFISICAL_TOKEN=<your-machine-identity-token>
infisical network gateway --proxy-name=<proxy-name> --name=<gateway-name>
infisical gateway start --relay=<relay-name> --name=<gateway-name>
```
</Tab>
</Tabs>
For detailed information about the network commands and their options, see the [network command documentation](/cli/commands/network).
For detailed information about the gateway commands and their options, see the [gateway command documentation](/cli/commands/gateway).
<Note>
**Requirements:**
- Ensure the deployed Gateway has network access to the private resources you intend to connect with Infisical
- The gateway must be able to reach the proxy server (outbound connection only)
- Replace `<proxy-name>` with the name of your proxy server and `<gateway-name>` with a unique name for this gateway
- The gateway must be able to reach the relay server (outbound connection only)
- Replace `<relay-name>` with the name of your relay server and `<gateway-name>` with a unique name for this gateway
</Note>
</Step>