diff --git a/docs/cli/commands/gateway.mdx b/docs/cli/commands/gateway.mdx index 99d0e1086..4ae660cf5 100644 --- a/docs/cli/commands/gateway.mdx +++ b/docs/cli/commands/gateway.mdx @@ -9,7 +9,7 @@ description: "Run the Infisical gateway or manage its systemd service" infisical gateway start --name= --relay= --auth-method= ``` - + ```bash sudo infisical gateway systemd install --token= --domain= --name= --relay= ``` diff --git a/docs/cli/commands/relay.mdx b/docs/cli/commands/relay.mdx index 66bed96da..7530ee99d 100644 --- a/docs/cli/commands/relay.mdx +++ b/docs/cli/commands/relay.mdx @@ -9,7 +9,7 @@ description: "Relay-related commands for Infisical" infisical relay start --type= --host= --name= --auth-method= ``` - + ```bash # Install systemd service sudo infisical relay systemd install --type= --host= --name= --token= diff --git a/docs/docs.json b/docs/docs.json index c9c2527f4..9eeeea500 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -173,8 +173,8 @@ "group": "Gateway", "pages": [ "documentation/platform/gateways/overview", - "documentation/platform/gateways/deployment", - "documentation/platform/gateways/networking", + "documentation/platform/gateways/gateway-deployment", + "documentation/platform/gateways/relay-deployment", "documentation/platform/gateways/security", { "group": "Gateway (Deprecated)", diff --git a/docs/documentation/platform/gateways/deployment.mdx b/docs/documentation/platform/gateways/gateway-deployment.mdx similarity index 50% rename from docs/documentation/platform/gateways/deployment.mdx rename to docs/documentation/platform/gateways/gateway-deployment.mdx index 3f392dd22..f939744c3 100644 --- a/docs/documentation/platform/gateways/deployment.mdx +++ b/docs/documentation/platform/gateways/gateway-deployment.mdx @@ -1,120 +1,27 @@ --- -title: "Deployment Guide" -description: "Complete guide to deploying Infisical Gateways and Relays" +title: "Gateway Deployment" +description: "Complete guide to deploying Infisical Gateways including network configuration and firewall requirements" --- -This guide covers everything you need to deploy and configure both Infisical Gateways and Relay Servers, including prerequisites, step-by-step instructions, and troubleshooting. +This guide covers everything you need to deploy and configure Infisical Gateways, including prerequisites, step-by-step deployment instructions, network configuration, and troubleshooting. ## Prerequisites -Before deploying gateways or relays, ensure you have: +Before deploying gateways, ensure you have: 1. **Machine Identity** - Configured with appropriate permissions to create and manage gateways -2. **Network Access** - Proper connectivity between components -3. **Relay Server** - A running relay server before deploying gateways +2. **Relay Server** - A running relay server before deploying gateways. This can be either a managed relay (like Infisical's US/EU relays) or your own self-deployed relay server (see [Relay Deployment Guide](/documentation/platform/gateways/relay-deployment)) -## Deploying Relays +## Gateway Deployment Methods -Choose the relay deployment type that best fits your needs: - -- **Instance Relays** - Use Infisical's managed infrastructure (Infisical Cloud) or shared relays set up by your instance administrator (self-hosted). Best for getting started quickly with minimal operational overhead. - -- **Organization Relays** - Deploy and manage your own relay servers. Choose this for lower latency, custom network policies, compliance requirements, or when you need full control over the relay infrastructure. - - - Most users should start with **Instance Relays** for simplicity. Consider - Organization Relays only if you have specific latency, compliance, or control - requirements. - - - - - **Infisical Cloud:** - - Pre-configured and ready to use - - No setup required, managed by Infisical - - **Self-hosted:** - - Instance relays require **two-step configuration** with matching secrets: - - **Step 1: Instance Admin Configuration** - The Infisical instance administrator must first set the relay auth secret in the instance environment: - - ```bash - # In the Infisical instance environment variables - RELAY_AUTH_SECRET= - ``` - - **Step 2: Relay Deployment** - Deploy the relay using the **same secret value**: - - ```bash - # Set the matching secret for relay deployment - export INFISICAL_RELAY_AUTH_SECRET= - - # Start the instance relay - infisical relay start --type=instance --host= --name= - ``` - - - The `RELAY_AUTH_SECRET` (instance environment) and - `INFISICAL_RELAY_AUTH_SECRET` (relay environment) **must match exactly** for - authentication to work. - - - - - - Deploy your own relay server for full control. Organization relays support all authentication methods: - - ```bash - # Token auth - infisical relay start --type=org --host= --name= --token= - - # Universal auth - infisical relay start --type=org --host= --name= --auth-method=universal-auth --client-id= --client-secret= - - # Other auth methods (kubernetes, aws-iam, gcp-id-token, azure, etc.) - infisical relay start --type=org --host= --name= --auth-method= --machine-identity-id= - ``` - - - - -### Relay Systemd Service (Linux) - -For production deployments, install as a systemd service: - -```bash -# Organization relay -sudo infisical relay systemd install --token= --name= --host= --type=org - -# Instance relay -sudo infisical relay systemd install --type=instance --name= --host= --relay-auth-secret= - -# Start the service -sudo systemctl start infisical-relay - -# Uninstall -sudo infisical relay systemd uninstall -``` - -**Required Network Configuration:** - -- **Inbound SSH** on port 2222 from gateways -- **Inbound TCP with TLS** on port 8443 from Infisical platform -- **Outbound HTTPS** to Infisical API endpoints on port 443 - -## Deploying Gateways - -### Linux Server Deployment +### Linux Server Deployment (Production) For production deployments on Linux servers, install the Gateway as a systemd service: **Gateway v2:** The `infisical gateway systemd install` command deploys the new Gateway v2 component. -If you are migrating from Gateway v1 (legacy `infisical gateway install` command), this is not in-place. Gateway v2 provisions new gateway instances with new gateway IDs. Update any resources that reference a gateway ID (for example: dynamic secret configs, app connections, or other gateway-bound resources) to use the new Gateway v2 gateway ID. +If you are migrating from Gateway v1 (legacy `infisical gateway install` command), this will create a completely new gateway rather than upgrading your existing one. Gateway v2 provisions new gateway instances with new gateway IDs. You'll need to update any resources that reference the old gateway ID (for example: dynamic secret configs, app connections, or other gateway-bound resources) to use the new Gateway v2 gateway ID. @@ -135,7 +42,7 @@ This will install and start the Gateway as a secure systemd service that: privileges. -### Kubernetes Cluster Deployment +### Kubernetes Cluster Deployment (Production) For production deployments on Kubernetes clusters, install the Gateway using the Infisical Helm chart: @@ -168,7 +75,7 @@ helm install infisical-gateway infisical-helm-charts/infisical-gateway **Version mapping:** Helm chart versions `>= 1.0.0` contain the new Gateway v2 component. Helm chart versions `<= 0.0.5` contain the legacy Gateway v1 component. -If you are moving from Gateway v1 (chart `<= 0.0.5`) to Gateway v2 (chart `>= 1.0.0`), this is not in-place. Gateway v2 provisions new gateway instances with new gateway IDs. Update any resources that reference a gateway ID (for example: dynamic secret configs, app connections, or other gateway-bound resources) to use the new Gateway v2 gateway ID. +If you are moving from Gateway v1 (chart `<= 0.0.5`) to Gateway v2 (chart `>= 1.0.0`), this will create a completely new gateway rather than upgrading your existing one. Gateway v2 provisions new gateway instances with new gateway IDs. You'll need to update any resources that reference the old gateway ID (for example: dynamic secret configs, app connections, or other gateway-bound resources) to use the new Gateway v2 gateway ID. @@ -185,7 +92,7 @@ export INFISICAL_TOKEN= infisical gateway start --relay= --name= ``` -### Authentication Methods +## Authentication Methods The gateway supports multiple authentication methods. Choose the one that best fits your environment: @@ -266,7 +173,7 @@ The gateway supports multiple authentication methods. Choose the one that best f -### Environment Variables +## Environment Variables In addition to authentication, you must set these required variables: @@ -277,6 +184,72 @@ Optional variables: - `INFISICAL_API_URL` - The Infisical API URL (defaults to `https://app.infisical.com`) +## Network Configuration + +### Gateway Network Requirements + +The gateway uses SSH reverse tunnels to establish secure connections with end-to-end encryption: + +1. **Gateway** connects outbound to **Relay Servers** using SSH over TCP +2. **Infisical platform** establishes mTLS connections with gateways via the relay servers for application 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 + +### Outbound Connections (Required) + +The gateway requires the following outbound connectivity: + +| Protocol | Destination | Ports | Purpose | +| -------- | ------------------------------------ | ----- | ------------------------------------------ | +| TCP | Relay Servers | 2222 | SSH reverse tunnel establishment | +| TCP | app.infisical.com / eu.infisical.com | 443 | API communication and certificate requests | + +### Relay Server Connectivity + +Your gateway needs to connect to a relay server on port 2222. The specific relay server depends on your setup: + +**Managed Relays (Infisical Cloud):** + +- Use Infisical's pre-configured relay servers in US/EU regions +- Static IP addresses available for firewall whitelisting +- Allow outbound TCP connections to the relay server IP on port 2222 + +**Self-Deployed or Instance Relays:** + +- Connect to your own relay server or relay servers deployed by your instance administrator +- Allow outbound TCP connections to your relay server IP/hostname on port 2222 +- Example: If your relay is at `203.0.113.100`, allow TCP to `203.0.113.100:2222` +- For instance relays, contact your admin for the specific relay server addresses + +## Firewall Configuration + +### Gateway Firewall Rules + +Since gateways only make outbound connections, you only need simple outbound rules: + +1. **Allow outbound TCP** to relay servers (IP addresses or hostnames) on port 2222 +2. **Allow outbound HTTPS** to Infisical API endpoints on port 443 +3. **No inbound rules required** - all connections are outbound only + +### Common Network Scenarios + +#### Corporate Firewalls + +For corporate environments with strict egress filtering: + +1. **Allow outbound TCP** to relay servers (IP addresses or hostnames) 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 + +#### Cloud Environments (AWS/GCP/Azure) + +Configure security groups to allow: + +- **Outbound TCP** to relay servers (IP addresses or hostnames) 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 + ## Verification After deployment, verify your gateway is working: @@ -294,20 +267,12 @@ After deployment, verify your gateway is working: - **Rotate credentials** - Set up regular credential rotation - **Monitor authentication** - Watch for unusual authentication activity -### Relay Security - -- **Secure secret management** - For instance relays, ensure `RELAY_AUTH_SECRET` and `INFISICAL_RELAY_AUTH_SECRET` are stored securely -- **Network isolation** - Use security groups and network ACLs to restrict relay access -- **Regular updates** - Keep relay servers updated and patched -- **Monitor traffic** - Watch for unusual connection patterns or traffic volume - ### Performance & Reliability - **Deploy close to resources** - Place gateways as close as possible to your private resources -- **Deploy relays strategically** - For organization relays, deploy close to gateways to minimize latency -- **Use multiple instances** - Deploy multiple gateways and relays for redundancy -- **Monitor resource usage** - Track CPU, memory, and network usage for both gateways and relays -- **Health monitoring** - Set up monitoring for both gateway and relay connection status +- **Use multiple instances** - Deploy multiple gateways for redundancy +- **Monitor resource usage** - Track CPU, memory, and network usage for gateways +- **Health monitoring** - Set up monitoring for gateway connection status - **Automatic restart** - Use systemd or Kubernetes to automatically restart failed services ## Troubleshooting @@ -332,18 +297,6 @@ After deployment, verify your gateway is working: - Check token expiration and renewal - Ensure authentication method is properly configured -**Relay not accessible from gateways:** - -- Check firewall rules allow inbound SSH on port 2222 -- Verify public IP is correctly configured -- Test connectivity: `telnet 2222` - -**Platform cannot connect to relay:** - -- Check firewall rules allow inbound TCP with TLS on port 8443 -- Verify SSL certificate is properly configured -- Test connectivity: `openssl s_client -connect :8443` - ### Logs Check gateway logs for detailed error information: @@ -361,15 +314,58 @@ kubectl logs deployment/infisical-gateway ### Network Testing -Test relay connectivity: +Test relay connectivity from gateway: ```bash -# Test SSH port from gateway +# Test SSH port to relay nc -zv 2222 -# Test TCP with TLS port from platform -openssl s_client -connect :8443 - # Test outbound API access curl -I https://app.infisical.com ``` + +## Frequently Asked Questions + + +The gateway is designed to handle network interruptions gracefully: + +- **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 +- **Graceful degradation**: The gateway logs connection issues and continues attempting to restore connectivity + +No manual intervention is typically required during network interruptions. + + + + +No inbound ports need to be opened for gateways. The gateway only makes outbound connections: + +- **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 + +This design maintains security by avoiding the need for inbound firewall rules that could expose your network to external threats. + + + + +If your firewall has strict outbound restrictions: + +1. **Work with your network team** to allow outbound TCP connections on port 2222 to relay servers (IP addresses or hostnames) +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 + + + + +The gateway connects to **one relay server**: + +- **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 + + diff --git a/docs/documentation/platform/gateways/networking.mdx b/docs/documentation/platform/gateways/networking.mdx deleted file mode 100644 index 5d6e235a7..000000000 --- a/docs/documentation/platform/gateways/networking.mdx +++ /dev/null @@ -1,310 +0,0 @@ ---- -title: "Networking Requirements" -description: "Network configuration and firewall requirements for Infisical Gateways and Relays" ---- - -This page outlines the required ports, protocols, and firewall configurations needed for optimal gateway and relay usage. - -## Network Architecture - -The gateway system uses SSH reverse tunnels to establish secure connections with end-to-end encryption: - -1. **Gateway** connects outbound to **Relay Servers** using SSH over TCP -2. **Infisical platform** establishes mTLS connections with gateways for application 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 - -## Gateway Network Requirements - -### Outbound Connections (Required) - -The gateway requires the following outbound connectivity: - -| Protocol | Destination | Ports | Purpose | -| -------- | ------------------------------------ | ----- | ------------------------------------------ | -| TCP | Relay Servers | 2222 | SSH reverse tunnel establishment | -| TCP | app.infisical.com / eu.infisical.com | 443 | API communication and certificate requests | - -### Relay Server Connectivity - -**For Instance Relays (Infisical Cloud):** Your firewall must allow outbound connectivity to Infisical-managed relay servers. - -**For Organization Relays:** Your firewall must allow outbound connectivity to your own relay server IP addresses or hostnames. - -**For Self-hosted Instance Relays:** Your firewall must allow outbound connectivity to relay servers configured by your instance administrator. - - - - 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 relay server IP on port 2222. - - - You control the relay server IP addresses or hostnames when deploying your - own organization relays. **Firewall requirements:** Allow outbound TCP - connections to your relay server IP or hostname on port 2222. For example, - if your relay is at `203.0.113.100` or `relay.example.com`, allow TCP to - `203.0.113.100:2222` or `relay.example.com:2222`. - - - Contact your instance administrator for the relay server IP addresses or - hostnames configured for your deployment. **Firewall requirements:** Allow - outbound TCP connections to instance relay servers on port 2222. - - - -## Relay Server Network Requirements - -### Inbound Connections (Required) - -The relay server must accept the following inbound connections: - -| Protocol | Source | Port | Purpose | -| -------- | ------------------ | ---- | -------------------------------- | -| TCP | Gateways | 2222 | SSH reverse tunnel establishment | -| TCP | Infisical Platform | 8443 | Platform-to-relay communication | - -### Outbound Connections (Required) - -The relay server requires outbound connectivity to: - -| Protocol | Destination | Port | Purpose | -| -------- | ------------------------------------ | ---- | ------------------------------------------ | -| TCP | app.infisical.com / eu.infisical.com | 443 | API communication and certificate requests | - -## Firewall Configuration - -### Gateway Firewall Rules - -Since gateways only make outbound connections, you only need simple outbound rules: - -1. **Allow outbound TCP** to relay servers (IP addresses or hostnames) on port 2222 -2. **Allow outbound HTTPS** to Infisical API endpoints on port 443 -3. **No inbound rules required** - all connections are outbound only - -### Relay Firewall Rules - -Configure your firewall to allow: - -1. **SSH on port 2222** - For gateway connections - - ```bash - # Example iptables rule - iptables -A INPUT -p tcp --dport 2222 -j ACCEPT - ``` - -2. **TCP with TLS on port 8443** - For platform connections - - ```bash - # Example iptables rule - iptables -A INPUT -p tcp --dport 8443 -j ACCEPT - ``` - -3. **HTTPS to Infisical API** - For certificate requests and API communication - ```bash - # Example iptables rule - iptables -A OUTPUT -p tcp --dport 443 -d app.infisical.com -j ACCEPT - ``` - -## Cloud Provider Configuration - -### AWS EC2 - -Configure security groups: - -```json -{ - "SecurityGroupRules": [ - { - "IpProtocol": "tcp", - "FromPort": 2222, - "ToPort": 2222, - "CidrIpv4": "0.0.0.0/0", - "Description": "SSH for gateway connections" - }, - { - "IpProtocol": "tcp", - "FromPort": 8443, - "ToPort": 8443, - "CidrIpv4": "0.0.0.0/0", - "Description": "TCP with TLS for platform connections" - } - ] -} -``` - -### Google Cloud Platform - -Configure firewall rules: - -```bash -# Allow SSH from gateways -gcloud compute firewall-rules create allow-gateway-ssh \ - --allow tcp:2222 \ - --source-ranges 0.0.0.0/0 \ - --description "Allow SSH from gateways" - -# Allow TCP with TLS from platform -gcloud compute firewall-rules create allow-platform-tls \ - --allow tcp:8443 \ - --source-ranges 0.0.0.0/0 \ - --description "Allow TCP with TLS from platform" -``` - -### Azure - -Configure Network Security Groups: - -```json -{ - "securityRules": [ - { - "name": "AllowGatewaySSH", - "properties": { - "protocol": "Tcp", - "sourcePortRange": "*", - "destinationPortRange": "2222", - "sourceAddressPrefix": "*", - "destinationAddressPrefix": "*", - "access": "Allow", - "priority": 100, - "direction": "Inbound" - } - }, - { - "name": "AllowPlatformTLS", - "properties": { - "protocol": "Tcp", - "sourcePortRange": "*", - "destinationPortRange": "8443", - "sourceAddressPrefix": "*", - "destinationAddressPrefix": "*", - "access": "Allow", - "priority": 110, - "direction": "Inbound" - } - } - ] -} -``` - -## Protocol Details - -### SSH over TCP - -The gateway uses SSH reverse tunnels for primary communication: - -- **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 - -### TCP Connection Handling - -SSH connections over TCP are stateful and handled seamlessly by all modern firewalls: - -- **Established connections** are automatically tracked -- **Return traffic** is allowed for established outbound connections -- **No special configuration** needed for connection tracking -- **Standard SSH protocol** that enterprise firewalls handle well - -## Common Network Scenarios - -### Corporate Firewalls - -For corporate environments with strict egress filtering: - -1. **Allow outbound TCP** to relay servers (IP addresses or hostnames) 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 - -### Cloud Environments (AWS/GCP/Azure) - -Configure security groups to allow: - -- **Outbound TCP** to relay servers (IP addresses or hostnames) 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 - -## Performance Considerations - -### Network Optimization - -- **Deploy close to gateways** - Reduce latency by placing relay servers geographically close to your gateways -- **Use high-bandwidth connections** - Ensure adequate bandwidth for encrypted traffic -- **Monitor network performance** - Track latency and throughput metrics -- **Consider multiple relays** - Deploy multiple relay servers for redundancy and load distribution - -## Frequently Asked Questions - - -The gateway is designed to handle network interruptions gracefully: - -- **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 -- **Graceful degradation**: The gateway logs connection issues and continues attempting to restore connectivity - -No manual intervention is typically required during network interruptions. - - - - -SSH over TCP provides several advantages for enterprise gateway communication: - -- **Firewall-friendly**: TCP is stateful and handled seamlessly by all enterprise firewalls -- **Standard protocol**: SSH is a well-established protocol that network teams are familiar with -- **Certificate-based security**: Uses SSH certificates for strong authentication without shared secrets -- **Automatic tunneling**: SSH reverse tunnels handle all the complexity of secure communication -- **Enterprise compatibility**: Works reliably across all enterprise network configurations - -TCP's reliability and firewall compatibility make it ideal for enterprise environments where network policies are strictly managed. - - - - -No inbound ports need to be opened for gateways. The gateway only makes outbound connections: - -- **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 - -This design maintains security by avoiding the need for inbound firewall rules that could expose your network to external threats. - - - - -If your firewall has strict outbound restrictions: - -1. **Work with your network team** to allow outbound TCP connections on port 2222 to relay servers (IP addresses or hostnames) -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 - - - - -The gateway connects to **one relay server**: - -- **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 - - - - -No, relay servers cannot decrypt any traffic passing through them due to end-to-end encryption: - -- **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 -- **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 relay infrastructure is designed as a secure routing mechanism where only the client and gateway can decrypt the actual application traffic. - - diff --git a/docs/documentation/platform/gateways/overview.mdx b/docs/documentation/platform/gateways/overview.mdx index 84ca46d5f..266f2ad16 100644 --- a/docs/documentation/platform/gateways/overview.mdx +++ b/docs/documentation/platform/gateways/overview.mdx @@ -50,78 +50,49 @@ The Gateway system uses SSH reverse tunnels for secure, firewall-friendly connec - **Certificate-based authentication** provides enhanced security - **Automatic reconnection** if connections are lost -## Relay Types +## Understanding Relay Types -### Instance Relays (Shared Infrastructure) +Relays are the routing infrastructure that enables secure communication between Infisical and your gateways. There are two main approaches to relay deployment: -**Infisical Cloud:** +**Managed Relays** - Use Infisical's hosted relay infrastructure in US/EU regions for quick setup with minimal operational overhead. -- Pre-configured and ready to use -- No setup required -- Shared across all organizations -- Managed by Infisical +**Self-Deployed Relays** - Deploy your own relay servers for regional proximity, enhanced control, and custom network policies. -**Self-hosted:** +### Managed Relays (Recommended for Most Users) -- Set up by instance administrators -- Shared across all organizations on the instance -- Uses `INFISICAL_RELAY_AUTH_SECRET` for authentication +Managed relays are pre-configured relay servers hosted by Infisical that can serve multiple organizations with minimal operational overhead. -### Organization Relays (Customer-Deployed) +**Infisical Cloud (US/EU Regions):** -**Benefits:** +- Pre-configured relays in US and EU regions +- No setup or maintenance required +- Shared across all Infisical Cloud organizations +- Managed and monitored by Infisical +- Best for getting started quickly -- Full control over infrastructure -- Lower latency (deploy closer to resources) -- Enhanced security and compliance -- Custom network policies +**Self-Hosted Instance Relays:** -**Authentication:** +- Instance administrators can deploy shared relays for their entire instance +- All organizations on the instance can use these relays +- Reduces operational burden for individual Organizations +- Ideal for self-hosted instances wanting shared relay infrastructure +### Self-Deployed Relays (Organization-Specific) + +Organizations can deploy and manage their own dedicated relay servers for regional proximity, network control, compliance requirements, or enhanced security. + +**Key Benefits:** + +- Deploy in any region or cloud provider for lower latency +- Custom network configurations and security policies +- Dedicated resources not shared with other organizations +- Full control over relay infrastructure - Uses standard Infisical authentication methods -- Organization-specific credentials -- Full control over access and permissions - -## When to Use Each - -**Use Instance Relays when:** - -- You want minimal operational overhead -- You don't need custom network policies -- You're okay with shared infrastructure -- You want to get started quickly - -**Use Organization Relays when:** - -- You need lower latency -- You have security or compliance requirements -- You need custom network policies -- You want full control over infrastructure - -## Common Use Cases - -- **Database credential rotation** - Automatically rotate database passwords -- **Dynamic secret generation** - Generate temporary credentials for services -- **Private API access** - Connect to internal APIs and services -- **Compliance requirements** - Meet data sovereignty and air-gapped environment needs - -## Quick Start - -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. **Relay Server**: Before deploying gateways, you need a running relay server -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 relay server, allowing secure access to your private resources. ## Next Steps Ready to get started? Follow these guides: -1. **[Deployment Guide](/documentation/platform/gateways/deployment)** - Complete deployment instructions -2. **[Networking Requirements](/documentation/platform/gateways/networking)** - Network configuration and firewall setup +1. **[Gateway Deployment](/documentation/platform/gateways/gateway-deployment)** - Complete gateway deployment and network configuration +2. **[Relay Deployment](/documentation/platform/gateways/relay-deployment)** - Complete relay deployment and network configuration 3. **[Security Architecture](/documentation/platform/gateways/security)** - Security model and best practices diff --git a/docs/documentation/platform/gateways/relay-deployment.mdx b/docs/documentation/platform/gateways/relay-deployment.mdx new file mode 100644 index 000000000..c90576d46 --- /dev/null +++ b/docs/documentation/platform/gateways/relay-deployment.mdx @@ -0,0 +1,424 @@ +--- +title: "Relay Deployment" +description: "Complete guide to deploying Infisical Relay Servers including network configuration and firewall requirements" +--- + +This guide covers everything you need to deploy and configure Infisical Relay Servers, including prerequisites, step-by-step deployment instructions, network configuration, and troubleshooting. + +## Prerequisites + +Before deploying relays, ensure you have: + +1. **Server Infrastructure** - A server or cloud instance to host the relay +2. **Network Connectivity** - Ability to accept inbound connections on ports 2222 and 8443, plus outbound HTTPS access to Infisical API +3. **Machine Identity** - Only required for organization relays; configured with appropriate permissions to create and manage relays + + + **Instance relays** don't require machine identities - they use a shared + secret configured by the instance administrator. + + +## Understanding Relay Types + +Relays are the routing infrastructure that enables secure communication between Infisical and your gateways. There are two main approaches to relay deployment: + +**Managed Relays** - Use Infisical's hosted relay infrastructure in US/EU regions for quick setup with minimal operational overhead. + +**Self-Deployed Relays** - Deploy your own relay servers for regional proximity, enhanced control, and custom network policies. + +### Managed Relays (Recommended for Most Users) + +Managed relays are pre-configured relay servers hosted by Infisical that can serve multiple organizations with minimal operational overhead. + +**Infisical Cloud (US/EU Regions):** + +- Pre-configured relays in US and EU regions +- No setup or maintenance required +- Shared across all Infisical Cloud organizations +- Managed and monitored by Infisical +- Best for getting started quickly + +**Self-Hosted Instance Relays:** + +- Instance administrators can deploy shared relays for their entire instance +- All organizations on the instance can use these relays +- Reduces operational burden for individual Organizations +- Ideal for self-hosted instances wanting shared relay infrastructure + +### Self-Deployed Relays (Organization-Specific) + +Organizations can deploy and manage their own dedicated relay servers for regional proximity, network control, compliance requirements, or enhanced security. + +**Key Benefits:** + +- Deploy in any region or cloud provider for lower latency +- Custom network configurations and security policies +- Dedicated resources not shared with other organizations +- Full control over relay infrastructure +- Uses standard Infisical authentication methods + +## Relay Deployment Methods + +If you've decided to deploy your own relay servers, choose the deployment type that best fits your needs: + +- **Instance Relays** - Deploy shared relays for your entire self-hosted Infisical instance. All organizations on the instance can use these relays without deploying their own. + +- **Organization Relays** - Deploy and manage your own dedicated relay servers. Choose this for lower latency, custom network policies, compliance requirements, or when you need full control over the relay infrastructure. + + + **Note:** If you're using Infisical Cloud, you likely don't need to deploy + relays at all - you can use the managed US/EU relays. This guide is for users + who need to deploy their own relay infrastructure. + + + + + Instance relays require **two-step configuration** with matching secrets: + + **Step 1: Instance Admin Configuration** + + The Infisical instance administrator must first set the relay auth secret in the instance environment: + + ```bash + # In the Infisical instance environment variables + RELAY_AUTH_SECRET= + ``` + + **Step 2: Relay Deployment** + + Deploy the relay using the **same secret value**: + + ```bash + # Set the matching secret for relay deployment + export INFISICAL_RELAY_AUTH_SECRET= + + # Start the instance relay + infisical relay start --type=instance --host= --name= + ``` + + **Install as daemon (Linux only):** + + ```bash + # Instance relay + sudo infisical relay systemd install --type=instance --name= --host= --relay-auth-secret= + + # Start the service + sudo systemctl start infisical-relay + + # Uninstall + sudo infisical relay systemd uninstall + ``` + + + The `RELAY_AUTH_SECRET` (instance environment) and + `INFISICAL_RELAY_AUTH_SECRET` (relay environment) **must match exactly** for + authentication to work. + + + + + + Deploy your own relay server for full control. Organization relays support all authentication methods: + + ```bash + # Token auth + infisical relay start --type=org --host= --name= --token= + + # Universal auth + infisical relay start --type=org --host= --name= --auth-method=universal-auth --client-id= --client-secret= + + # Other auth methods (kubernetes, aws-iam, gcp-id-token, azure, etc.) + infisical relay start --type=org --host= --name= --auth-method= --machine-identity-id= + ``` + + **Install as daemon (Linux only):** + + ```bash + # Organization relay + sudo infisical relay systemd install --token= --name= --host= --type=org + + # Start the service + sudo systemctl start infisical-relay + + # Uninstall + sudo infisical relay systemd uninstall + ``` + + + + +## Network Configuration + +### Relay Server Network Requirements + +The relay server must accept inbound connections and make outbound connections to function properly: + +#### Inbound Connections (Required) + +The relay server must accept the following inbound connections: + +| Protocol | Source | Port | Purpose | +| -------- | ------------------ | ---- | -------------------------------- | +| TCP | Gateways | 2222 | SSH reverse tunnel establishment | +| TCP | Infisical Platform | 8443 | Platform-to-relay communication | + +#### Outbound Connections (Required) + +The relay server requires outbound connectivity to: + +| Protocol | Destination | Port | Purpose | +| -------- | ------------------------------------ | ---- | ------------------------------------------ | +| TCP | app.infisical.com / eu.infisical.com | 443 | API communication and certificate requests | + +## Firewall Configuration + +### Relay Firewall Rules + +Configure your firewall to allow: + +1. **SSH on port 2222** - For gateway connections + + ```bash + # Example iptables rule + iptables -A INPUT -p tcp --dport 2222 -j ACCEPT + ``` + +2. **TCP with TLS on port 8443** - For platform connections + + ```bash + # Example iptables rule + iptables -A INPUT -p tcp --dport 8443 -j ACCEPT + ``` + +3. **HTTPS to Infisical API** - For certificate requests and API communication + ```bash + # Example iptables rule + iptables -A OUTPUT -p tcp --dport 443 -d app.infisical.com -j ACCEPT + ``` + +## Cloud Provider Configuration + +### AWS EC2 + +Configure security groups: + +```json +{ + "SecurityGroupRules": [ + { + "IpProtocol": "tcp", + "FromPort": 2222, + "ToPort": 2222, + "CidrIpv4": "0.0.0.0/0", + "Description": "SSH for gateway connections" + }, + { + "IpProtocol": "tcp", + "FromPort": 8443, + "ToPort": 8443, + "CidrIpv4": "0.0.0.0/0", + "Description": "TCP with TLS for platform connections" + } + ] +} +``` + +### Google Cloud Platform + +Configure firewall rules: + +```bash +# Allow SSH from gateways +gcloud compute firewall-rules create allow-gateway-ssh \ + --allow tcp:2222 \ + --source-ranges 0.0.0.0/0 \ + --description "Allow SSH from gateways" + +# Allow TCP with TLS from platform +gcloud compute firewall-rules create allow-platform-tls \ + --allow tcp:8443 \ + --source-ranges 0.0.0.0/0 \ + --description "Allow TCP with TLS from platform" +``` + +### Azure + +Configure Network Security Groups: + +```json +{ + "securityRules": [ + { + "name": "AllowGatewaySSH", + "properties": { + "protocol": "Tcp", + "sourcePortRange": "*", + "destinationPortRange": "2222", + "sourceAddressPrefix": "*", + "destinationAddressPrefix": "*", + "access": "Allow", + "priority": 100, + "direction": "Inbound" + } + }, + { + "name": "AllowPlatformTLS", + "properties": { + "protocol": "Tcp", + "sourcePortRange": "*", + "destinationPortRange": "8443", + "sourceAddressPrefix": "*", + "destinationAddressPrefix": "*", + "access": "Allow", + "priority": 110, + "direction": "Inbound" + } + } + ] +} +``` + +## Protocol Details + +### SSH over TCP + +The gateway uses SSH reverse tunnels for primary communication: + +- **Port 2222**: SSH connection from gateways to relay servers +- **Built-in features**: Automatic reconnection, certificate-based authentication, encrypted tunneling +- **Encryption**: SSH with certificate-based authentication and key exchange + +### TCP Connection Handling + +SSH connections over TCP are stateful and handled seamlessly by all modern firewalls: + +- **Established connections** are automatically tracked +- **Return traffic** is allowed for established outbound connections +- **No special configuration** needed for connection tracking +- **Standard SSH protocol** that enterprise firewalls handle well + +## Performance Considerations + +### Network Optimization + +- **Deploy close to gateways** - Reduce latency by placing relay servers geographically close to your gateways +- **Use high-bandwidth connections** - Ensure adequate bandwidth for encrypted traffic +- **Monitor network performance** - Track latency and throughput metrics +- **Consider multiple relays** - Deploy multiple relay servers for redundancy and load distribution + +## Best Practices + +### Relay Security + +- **Secure secret management** - For instance relays, ensure `RELAY_AUTH_SECRET` and `INFISICAL_RELAY_AUTH_SECRET` are stored securely +- **Network isolation** - Use security groups and network ACLs to restrict relay access +- **Regular updates** - Keep relay servers updated and patched +- **Monitor traffic** - Watch for unusual connection patterns or traffic volume + +### Performance & Reliability + +- **Deploy relays strategically** - Deploy close to gateways to minimize latency +- **Use multiple instances** - Deploy multiple relay servers for redundancy +- **Monitor resource usage** - Track CPU, memory, and network usage for relays +- **Health monitoring** - Set up monitoring for relay connection status +- **Automatic restart** - Use systemd to automatically restart failed services + +## Troubleshooting + +### Common Issues + +**Relay not accessible from gateways:** + +- Check firewall rules allow inbound SSH on port 2222 +- Verify public IP is correctly configured +- Test connectivity: `telnet 2222` + +**Platform cannot connect to relay:** + +- Check firewall rules allow inbound TCP with TLS on port 8443 +- Verify SSL certificate is properly configured +- Test connectivity: `openssl s_client -connect :8443` + +**Authentication failures:** + +- For instance relays: Verify `RELAY_AUTH_SECRET` matches `INFISICAL_RELAY_AUTH_SECRET` +- For organization relays: Check machine identity credentials and permissions +- Ensure authentication method is properly configured + +### Logs + +Check relay logs for detailed error information: + +```bash +# systemd service +sudo journalctl -u infisical-relay -f + +# Local installation +# Logs appear in the terminal where you started the relay +``` + +### Network Testing + +Test relay connectivity: + +```bash +# Test SSH port from gateway +nc -zv 2222 + +# Test TCP with TLS port from platform +openssl s_client -connect :8443 + +# Test outbound API access +curl -I https://app.infisical.com +``` + +## Frequently Asked Questions + + +No, relay servers cannot decrypt any traffic passing through them due to end-to-end encryption: + +- **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 +- **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 relay infrastructure is designed as a secure routing mechanism where only the client and gateway can decrypt the actual application traffic. + + + + +Choose based on your specific requirements: + +**Use Instance Relays when:** + +- Getting started quickly is a priority +- You want minimal operational overhead +- Shared infrastructure is acceptable +- You don't have specific latency requirements + +**Use Organization Relays when:** + +- You need dedicated relay resources +- Lower latency is critical (deploy closer to gateways) +- You have compliance requirements for data routing +- You want full control over relay infrastructure +- You need custom network policies + +Most users should start with Instance Relays and migrate to Organization Relays only if they have specific requirements that aren't met by the managed infrastructure. + + + + +Relay server outages affect gateway connectivity: + +- **Gateway reconnection**: Gateways will automatically attempt to reconnect when the relay comes back online +- **Service interruption**: While the relay is down, the Infisical platform cannot reach gateways through that relay +- **Multiple relays**: Deploy multiple relay servers for redundancy and high availability +- **Monitoring**: Set up monitoring to detect relay outages quickly +- **Automatic restart**: Use systemd or container orchestration to automatically restart failed relay services + +For production environments, consider deploying multiple relay servers to avoid single points of failure. + +