github/infisical
1
0
Fork 0
mirror of https://github.com/Infisical/infisical.git synced 2026-01-10 07:58:15 -05:00
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #4706 from Infisical/improve-relay-docs

Browse Source 
Improve relay docs
This commit is contained in:
Andre
2025-10-21 02:12:07 -04:00
committed by GitHub
parent 7224ff9ece 57fc8cdaec
commit 80aa473bca
5 changed files with 71 additions and 48 deletions
Download Patch File Download Diff File Expand all files Collapse all files

12
docs/cli/commands/gateway.mdx
View File

@@ -31,6 +31,7 @@ If you are moving from Gateway v1 to Gateway v2, this is NOT a drop-in switch. G
## Subcommands & flags
<AccordionGroup>
<Accordion title="infisical gateway start" defaultOpen="true">
Run the Infisical gateway component within your the network where your target resources are located. The gateway establishes an SSH reverse tunnel to the specified relay server and provides secure access to private resources within your network.
@@ -245,6 +246,7 @@ The Relay supports multiple authentication methods. Below are the available auth
### Other Flags
<AccordionGroup>
<Accordion title="--relay">
The name of the relay that this gateway should connect to. The relay must be running and registered before starting the gateway.
@@ -276,6 +278,7 @@ The Relay supports multiple authentication methods. Below are the available auth
```
</Accordion>
</AccordionGroup>
</Accordion>
<Accordion title="infisical gateway systemd install">
@@ -293,6 +296,7 @@ sudo infisical gateway systemd install --token=<token> --domain=<domain> --name=
### Flags
<AccordionGroup>
<Accordion title="--token">
The machine identity access token to authenticate with Infisical.
@@ -334,6 +338,7 @@ sudo infisical gateway systemd install --token=<token> --domain=<domain> --name=
```
</Accordion>
</AccordionGroup>
### Service Details
@@ -360,9 +365,11 @@ sudo systemctl disable infisical-gateway # Disable auto-start on boot
```
</Accordion>
</AccordionGroup>
## Legacy Gateway Commands
<AccordionGroup>
<Accordion title="infisical gateway (deprecated)">
<Warning>
**This command is deprecated and will be removed in a future release.**
@@ -579,6 +586,7 @@ The Infisical CLI supports multiple authentication methods. Below are the availa
### Other Flags
<AccordionGroup>
<Accordion title="--domain">
Domain of your self-hosted Infisical instance.
@@ -588,6 +596,7 @@ The Infisical CLI supports multiple authentication methods. Below are the availa
```
</Accordion>
</AccordionGroup>
</Accordion>
<Accordion title="infisical gateway install (deprecated)">
@@ -614,6 +623,7 @@ sudo infisical gateway install --token=<token> --domain=<domain>
### Flags
<AccordionGroup>
<Accordion title="--token">
The machine identity access token to authenticate with Infisical.
@@ -635,6 +645,7 @@ sudo infisical gateway install --token=<token> --domain=<domain>
```
</Accordion>
</AccordionGroup>
### Service Details
@@ -659,3 +670,4 @@ sudo systemctl disable infisical-gateway # Disable auto-start on boot
```
</Accordion>
</AccordionGroup>

10
docs/cli/commands/relay.mdx
View File

@@ -13,7 +13,7 @@ description: "Relay-related commands for Infisical"
```bash
# Install systemd service
sudo infisical relay systemd install --host=<host> --name=<name> --token=<token>
# Uninstall systemd service
sudo infisical relay systemd uninstall
```
@@ -26,6 +26,7 @@ Relay-related commands for Infisical that provide identity-aware relay infrastru
## Subcommands & flags
<AccordionGroup>
<Accordion title="infisical relay start" defaultOpen="true">
Run the Infisical relay component. The relay handles network traffic routing between Infisical and your gateways.
@@ -35,6 +36,7 @@ infisical relay start --host=<host> --name=<name> --auth-method=<auth-method>
### Flags
<AccordionGroup>
<Accordion title="--host">
The host (IP address or hostname) of the instance where the relay is deployed. This must be a static public IP or resolvable hostname that gateways can reach.
@@ -57,6 +59,7 @@ infisical relay start --host=<host> --name=<name> --auth-method=<auth-method>
```
</Accordion>
</AccordionGroup>
### Authentication
@@ -280,6 +283,7 @@ infisical relay systemd <subcommand>
### Subcommands
<AccordionGroup>
<Accordion title="install">
Install and enable systemd service for the relay. Must be run with sudo on Linux systems.
@@ -289,6 +293,7 @@ sudo infisical relay systemd install --host=<host> --name=<name> --token=<token>
#### Flags
<AccordionGroup>
<Accordion title="--host">
The host (IP address or hostname) of the instance where the relay is deployed. This must be a static public IP or resolvable hostname that gateways can reach.
@@ -331,6 +336,7 @@ sudo infisical relay systemd install --domain=http://localhost:8080 --token=<tok
```
</Accordion>
</AccordionGroup>
#### Examples
@@ -386,5 +392,7 @@ sudo infisical relay systemd uninstall
- Cleans up the service configuration
</Accordion>
</AccordionGroup>
</Accordion>
</AccordionGroup>

16
docs/documentation/platform/gateways-deprecated/networking.mdx
View File

@@ -3,7 +3,7 @@ title: "Networking"
description: "Network configuration and firewall requirements for Infisical Gateway"
---
The Infisical Gateway requires outbound network connectivity to establish secure communication with Infisical's relay infrastructure.
The Infisical Gateway requires outbound network connectivity to establish secure communication with Infisical's relay infrastructure.
This page outlines the required ports, protocols, and firewall configurations needed for optimal gateway usage.
## Network Architecture
@@ -67,11 +67,11 @@ The gateway uses QUIC (Quick UDP Internet Connections) for primary communication
## Understanding Firewall Behavior with UDP
Unlike TCP connections, UDP is a stateless protocol, and depending on your organization's firewall configuration, you may need to adjust network rules accordingly.
When the gateway sends UDP packets to a relay server, the return responses need to be allowed back through the firewall.
Modern firewalls handle this through "connection tracking" (also called "stateful inspection"), but the behavior can vary depending on your firewall configuration.
When the gateway sends UDP packets to a relay server, the return responses need to be allowed back through the firewall.
Modern firewalls handle this through "connection tracking" (also called "stateful inspection"), but the behavior can vary depending on your firewall configuration.
### Connection Tracking
### Connection Tracking
Modern firewalls automatically track UDP connections and allow return responses. This is the preferred configuration as it:
- Automatically handles return responses
@@ -100,6 +100,7 @@ Configure security groups to allow:
## Frequently Asked Questions
<AccordionGroup>
<Accordion title="What happens if there is a network interruption?">
The gateway is designed to handle network interruptions gracefully:
@@ -139,7 +140,7 @@ This design maintains security by avoiding the need for inbound firewall rules t
If your firewall has strict UDP restrictions:
1. **Work with your network team** to allow outbound UDP to the specific relay IP addresses
2. **Use explicit IP whitelisting** if connection tracking is disabled
2. **Use explicit IP whitelisting** if connection tracking is disabled
3. **Consider network policy exceptions** for the gateway host
4. **Monitor firewall logs** to identify which specific rules are blocking traffic
@@ -161,8 +162,9 @@ No, relay servers cannot decrypt any traffic passing through them:
- **End-to-end encryption**: All traffic between the gateway and Infisical Cloud is encrypted using mutual TLS with certificate pinning
- **Relay acts as a tunnel**: The relay server only forwards encrypted packets - it has no access to encryption keys
- **No data storage**: Relay servers do not store any traffic or network-identifiable information
- **No data storage**: Relay servers do not store any traffic or network-identifiable information
- **Certificate isolation**: Each organization has its own private PKI system, ensuring complete tenant isolation
The relay infrastructure is designed as a secure forwarding mechanism, similar to a VPN tunnel, where the relay provider cannot see the contents of the traffic flowing through it.
</Accordion>
</Accordion>
</AccordionGroup>

44
docs/documentation/platform/gateways/gateway-deployment.mdx
View File

@@ -3,7 +3,7 @@ title: "Gateway Deployment"
description: "Complete guide to deploying Infisical Gateways including network configuration and firewall requirements"
---
Infisical Gateways enables secure communication between your private resources and the Infisical platform without exposing inbound ports in your network.
Infisical Gateways enables secure communication between your private resources and the Infisical platform without exposing inbound ports in your network.
This guide covers everything you need to deploy and configure Infisical Gateways.
## Deployment Steps
@@ -18,73 +18,73 @@ To successfully deploy an Infisical Gateway for use, follow these steps in order
<AccordionGroup>
<Accordion title="Universal Auth">
Simple and secure authentication using client ID and client secret.
**Environment Variables:**
- `INFISICAL_AUTH_METHOD=universal-auth`
- `INFISICAL_UNIVERSAL_AUTH_CLIENT_ID=<client-id>`
- `INFISICAL_UNIVERSAL_AUTH_CLIENT_SECRET=<client-secret>`
</Accordion>
<Accordion title="Token Auth">
Direct authentication using a machine identity access token.
**Environment Variables:**
- `INFISICAL_TOKEN=<token>`
</Accordion>
<Accordion title="Native Kubernetes">
Authentication using Kubernetes service account tokens.
**Environment Variables:**
- `INFISICAL_AUTH_METHOD=kubernetes`
- `INFISICAL_MACHINE_IDENTITY_ID=<machine-identity-id>`
</Accordion>
<Accordion title="Native AWS IAM">
Authentication using AWS IAM roles.
**Environment Variables:**
- `INFISICAL_AUTH_METHOD=aws-iam`
- `INFISICAL_MACHINE_IDENTITY_ID=<machine-identity-id>`
</Accordion>
<Accordion title="Native GCP ID Token">
Authentication using GCP identity tokens.
**Environment Variables:**
- `INFISICAL_AUTH_METHOD=gcp-id-token`
- `INFISICAL_MACHINE_IDENTITY_ID=<machine-identity-id>`
</Accordion>
<Accordion title="GCP IAM">
Authentication using GCP service account keys.
**Environment Variables:**
- `INFISICAL_AUTH_METHOD=gcp-iam`
- `INFISICAL_MACHINE_IDENTITY_ID=<machine-identity-id>`
- `INFISICAL_GCP_SERVICE_ACCOUNT_KEY_FILE_PATH=<path-to-key-file>`
</Accordion>
<Accordion title="Native Azure">
Authentication using Azure managed identity.
**Environment Variables:**
- `INFISICAL_AUTH_METHOD=azure`
- `INFISICAL_MACHINE_IDENTITY_ID=<machine-identity-id>`
</Accordion>
<Accordion title="OIDC Auth">
Authentication using OIDC identity tokens.
**Environment Variables:**
- `INFISICAL_AUTH_METHOD=oidc-auth`
- `INFISICAL_MACHINE_IDENTITY_ID=<machine-identity-id>`
- `INFISICAL_JWT=<oidc-jwt>`
</Accordion>
<Accordion title="JWT Auth">
Authentication using JWT tokens.
**Environment Variables:**
- `INFISICAL_AUTH_METHOD=jwt-auth`
- `INFISICAL_MACHINE_IDENTITY_ID=<machine-identity-id>`
@@ -111,7 +111,7 @@ To successfully deploy an Infisical Gateway for use, follow these steps in order
| TCP | Infisical instance host (US/EU, other) | 443 | API communication and certificate requests |
For managed relays, allow outbound traffic to the provided relay server IP/hostname. For self-hosted relays, allow outbound traffic to your own relay server address.
If you are in a corporate environment with strict egress filtering, ensure outbound TCP 2222 to relay servers and outbound HTTPS 443 to Infisical API endpoints are allowed.
</Step>
<Step title="Select a Deployment Method">
@@ -185,10 +185,9 @@ To successfully deploy an Infisical Gateway for use, follow these steps in order
</Step>
</Steps>
## Frequently Asked Questions
<AccordionGroup>
<Accordion title="Do I need to open any inbound ports on my firewall?">
No inbound ports need to be opened for gateways. The gateway only makes outbound connections:
@@ -263,3 +262,4 @@ The gateway is designed to handle network interruptions gracefully:
No manual intervention is typically required during network interruptions.
</Accordion>
</AccordionGroup>

37
docs/documentation/platform/gateways/relay-deployment.mdx
View File

@@ -32,73 +32,73 @@ To successfully deploy an Infisical Relay for use, follow these steps in order.
<AccordionGroup>
<Accordion title="Universal Auth">
Simple and secure authentication using client ID and client secret.
**Environment Variables:**
- `INFISICAL_AUTH_METHOD=universal-auth`
- `INFISICAL_UNIVERSAL_AUTH_CLIENT_ID=<client-id>`
- `INFISICAL_UNIVERSAL_AUTH_CLIENT_SECRET=<client-secret>`
</Accordion>
<Accordion title="Token Auth">
Direct authentication using a machine identity access token.
**Environment Variables:**
- `INFISICAL_TOKEN=<token>`
</Accordion>
<Accordion title="Native Kubernetes">
Authentication using Kubernetes service account tokens.
**Environment Variables:**
- `INFISICAL_AUTH_METHOD=kubernetes`
- `INFISICAL_MACHINE_IDENTITY_ID=<machine-identity-id>`
</Accordion>
<Accordion title="Native AWS IAM">
Authentication using AWS IAM roles.
**Environment Variables:**
- `INFISICAL_AUTH_METHOD=aws-iam`
- `INFISICAL_MACHINE_IDENTITY_ID=<machine-identity-id>`
</Accordion>
<Accordion title="Native GCP ID Token">
Authentication using GCP identity tokens.
**Environment Variables:**
- `INFISICAL_AUTH_METHOD=gcp-id-token`
- `INFISICAL_MACHINE_IDENTITY_ID=<machine-identity-id>`
</Accordion>
<Accordion title="GCP IAM">
Authentication using GCP service account keys.
**Environment Variables:**
- `INFISICAL_AUTH_METHOD=gcp-iam`
- `INFISICAL_MACHINE_IDENTITY_ID=<machine-identity-id>`
- `INFISICAL_GCP_SERVICE_ACCOUNT_KEY_FILE_PATH=<path-to-key-file>`
</Accordion>
<Accordion title="Native Azure">
Authentication using Azure managed identity.
**Environment Variables:**
- `INFISICAL_AUTH_METHOD=azure`
- `INFISICAL_MACHINE_IDENTITY_ID=<machine-identity-id>`
</Accordion>
<Accordion title="OIDC Auth">
Authentication using OIDC identity tokens.
**Environment Variables:**
- `INFISICAL_AUTH_METHOD=oidc-auth`
- `INFISICAL_MACHINE_IDENTITY_ID=<machine-identity-id>`
- `INFISICAL_JWT=<oidc-jwt>`
</Accordion>
<Accordion title="JWT Auth">
Authentication using JWT tokens.
**Environment Variables:**
- `INFISICAL_AUTH_METHOD=jwt-auth`
- `INFISICAL_MACHINE_IDENTITY_ID=<machine-identity-id>`
@@ -168,7 +168,6 @@ To successfully deploy an Infisical Relay for use, follow these steps in order.
```bash
infisical relay start \
--type=<type> \
--host=<host> \
--name=<name> \
--auth-method=<auth-method>
@@ -185,6 +184,7 @@ To successfully deploy an Infisical Relay for use, follow these steps in order.
## Frequently Asked Questions
<AccordionGroup>
<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:
@@ -241,3 +241,4 @@ Relay server outages affect gateway connectivity:
For production environments, consider deploying multiple relay servers to avoid single points of failure.
</Accordion>
</AccordionGroup>