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

revamp gateway docs

Browse Source
This commit is contained in:
Maidul Islam
2025-09-18 13:25:00 -04:00
parent 7aaafb19e9
commit d3d3fbe5c5
1 changed files with 216 additions and 322 deletions
Download Patch File Download Diff File Expand all files Collapse all files

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

@@ -3,328 +3,253 @@ 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 Infisical Gateways, including prerequisites, step-by-step deployment instructions, network configuration, and troubleshooting.
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.
## Prerequisites
## Deployment Steps
Before deploying gateways, ensure you have:
To successfully deploy an Infisical Gateway for use, follow these steps in order.
1. **Machine Identity** - Configured with appropriate permissions to create and manage 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))
<Steps>
<Step title="Provision a Machine Identity">
Create a machine identity with the correct permissions to create and manage gateways. This identity is used by the gateway to authenticate with Infisical and should be provisioned in advance.
The gateway supports several [machine identity auth methods](/documentation/platform/identities/machine-identities), as listed below. Choose the one that best fits your environment and set the corresponding environment variables when deploying the gateway.
## Gateway Deployment Methods
<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>`
- `INFISICAL_JWT=<jwt>`
</Accordion>
</AccordionGroup>
</Step>
<Step title="Set Up a Relay Server">
Ensure a relay server is running and accessible before you deploy any gateways. You can use either:
- A managed relay provided by Infisical (such as the US/EU relays). If you are on a dedicated Infisical managed instance, a relay will be provisioned for you to use.
- Your own self-hosted relay server. For setup instructions, see the <a href="/documentation/platform/gateways/relay-deployment">Relay Deployment Guide</a>.
</Step>
<Step title="Install the Infisical CLI">
Make sure the Infisical CLI is installed on the machine or environment where you plan to deploy the gateway. The CLI is required for gateway installation and management.
### Linux Server Deployment (Production)
See the [CLI Installation Guide](/cli/overview) for instructions.
</Step>
<Step title="Configure Network & Firewall">
Ensure your network and firewall settings allow the gateway to connect to all required services. All connections are outbound only; no inbound ports need to be opened.
For production deployments on Linux servers, install the Gateway as a systemd service:
| Protocol | Destination | Port | Purpose |
| -------- | ------------------------------------ | ---- | ------------------------------------------ |
| TCP | Relay Server IP/Hostname | 2222 | SSH reverse tunnel establishment |
| TCP | Infisical instance host (US/EU, other) | 443 | API communication and certificate requests |
<Warning>
**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 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.
</Warning>
```bash
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:
- Runs with restricted privileges
- Automatically restarts on failure
- Starts on system boot
- Manages token and domain configuration securely in `/etc/infisical/gateway.conf`
<Warning>
The systemd install command requires a Linux operating system with root/sudo
privileges.
</Warning>
### Kubernetes Cluster Deployment (Production)
For production deployments on Kubernetes clusters, install the Gateway using the Infisical Helm chart:
#### Install the latest Helm Chart repository
```bash
helm repo add infisical-helm-charts 'https://dl.cloudsmith.io/public/infisical/helm-charts/helm/charts/'
helm repo update
```
#### Create a Kubernetes Secret
The gateway supports all identity authentication methods through environment variables:
```bash
kubectl create secret generic infisical-gateway-environment \
--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_RELAY_NAME=<relay-name> \
--from-literal=INFISICAL_GATEWAY_NAME=<gateway-name>
```
#### Install the Gateway
```bash
helm install infisical-gateway infisical-helm-charts/infisical-gateway
```
<Warning>
**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 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.
</Warning>
### Development & Testing
For development or testing environments:
```bash
# Direct execution with token
infisical gateway start --token <token> --relay=<relay-name> --name=<gateway-name>
# Using environment variable
export INFISICAL_TOKEN=<token>
infisical gateway start --relay=<relay-name> --name=<gateway-name>
```
## Authentication Methods
The gateway supports multiple authentication methods. Choose the one that best fits your environment:
<AccordionGroup>
<Accordion title="Universal Auth">
Simple and secure authentication using client ID and client secret.
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.
**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>`
- `INFISICAL_JWT=<jwt>`
</Accordion>
</AccordionGroup>
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">
The Infisical CLI is used to install and start the gateway in your chosen environment. The CLI provides commands for both production and development scenarios, and supports a variety of options/flags to configure your deployment.
## Environment Variables
To view all available flags and equivalent environment variables for gateway deployment, see the [Gateway CLI Command Reference](/cli/commands/gateway).
<Tabs>
<Tab title="Linux Server (Production)">
For production deployments on Linux servers, install the Gateway as a systemd service so that it runs securely in the background and automatically restarts on failure or system reboot:
```bash
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
```
In addition to authentication, you must set these required variables:
- `INFISICAL_RELAY_NAME` - The name of the relay server to connect to
- `INFISICAL_GATEWAY_NAME` - A unique name for this gateway instance
Optional variables:
<Warning>
The systemd install command requires a Linux operating system with root/sudo
privileges.
</Warning>
</Tab>
- `INFISICAL_API_URL` - The Infisical API URL (defaults to `https://app.infisical.com`)
<Tab title="Kubernetes (Production)">
For production deployments on Kubernetes clusters, install the Gateway using the Infisical Helm chart:
## Network Configuration
#### Install the latest Helm Chart repository
### Gateway Network Requirements
```bash
helm repo add infisical-helm-charts 'https://dl.cloudsmith.io/public/infisical/helm-charts/helm/charts/'
helm repo update
```
The gateway uses SSH reverse tunnels to establish secure connections with end-to-end encryption:
#### Create a Kubernetes Secret
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
The gateway supports all identity authentication methods through environment variables:
### Outbound Connections (Required)
```bash
kubectl create secret generic infisical-gateway-environment \
--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_RELAY_NAME=<relay-name> \
--from-literal=INFISICAL_GATEWAY_NAME=<gateway-name>
```
The gateway requires the following outbound connectivity:
#### Install the Gateway
| 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 |
```bash
helm install infisical-gateway infisical-helm-charts/infisical-gateway
```
</Tab>
### Relay Server Connectivity
<Tab title="Development & Testing">
For development or testing environments:
Your gateway needs to connect to a relay server on port 2222. The specific relay server depends on your setup:
```bash
infisical gateway start --token <token> --relay=<relay-name> --name=<gateway-name>
```
</Tab>
</Tabs>
</Step>
**Managed Relays (Infisical Cloud):**
<Step title="Verify Your Gateway Deployment">
After deployment, verify your gateway is working:
- 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
1. **Check logs** for "Gateway started successfully" message indicating the gateway is running and connected to the relay
**Self-Deployed or Instance Relays:**
2. **Verify registration** in the Infisical by visiting the Gateways section of your organization. The new gateway should appear with a recent heartbeat timestamp.
- 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
3. **Test connectivity** by creating a resource in Infisical that uses the gateway to access a private service. Verify the resource can successfully connect through the gateway.
</Step>
</Steps>
## 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:
1. **Check logs** for "Gateway started successfully" message
2. **Verify registration** in the Infisical dashboard under Organization Access Control > Gateways
3. **Test connectivity** by creating a dynamic secret or app connection
## Best Practices
### Gateway Security
- **One identity per gateway** - Create a unique machine identity for each gateway
- **Minimal permissions** - Assign only the permissions each gateway actually needs
- **Rotate credentials** - Set up regular credential rotation
- **Monitor authentication** - Watch for unusual authentication activity
### Performance & Reliability
- **Deploy close to resources** - Place gateways as close as possible to your private resources
- **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
### Common Issues
**Gateway fails to start:**
- Verify machine identity has correct permissions
- Check network connectivity to relay server
- Ensure all required environment variables are set
**Cannot connect to relay:**
- Verify relay server is running and accessible
- Check firewall rules allow outbound connections on port 2222
- Confirm relay name matches exactly
**Authentication failures:**
- Verify machine identity credentials are correct
- Check token expiration and renewal
- Ensure authentication method is properly configured
### Logs
Check gateway logs for detailed error information:
```bash
# systemd service
sudo journalctl -u infisical-gateway -f
# Kubernetes
kubectl logs deployment/infisical-gateway
# Local installation
# Logs appear in the terminal where you started the gateway
```
### Network Testing
Test relay connectivity from gateway:
```bash
# Test SSH port to relay
nc -zv <relay-ip> 2222
# Test outbound API access
curl -I https://app.infisical.com
```
## Frequently Asked Questions
<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:
- **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.
</Accordion>
<Accordion title="How do I test network connectivity from the gateway?">
Test relay connectivity and outbound API access from the gateway:
1. Test SSH port to relay:
```bash
nc -zv <relay-ip> 2222
```
2. Test outbound API access (replace with your Infisical domain if different):
```bash
curl -I https://app.infisical.com
```
</Accordion>
<Accordion title="How do I troubleshoot relay connectivity issues?">
If the gateway cannot connect to the relay:
1. Verify the relay server is running and accessible
2. Check firewall rules allow outbound connections on port 2222
3. Confirm the relay name matches exactly
4. Test SSH port to relay:
```bash
nc -zv <relay-ip> 2222
```
</Accordion>
<Accordion title="How do I troubleshoot authentication failures?">
If you encounter authentication failures:
1. Verify machine identity credentials are correct
2. Check token expiration and renewal
3. Ensure authentication method is properly configured
</Accordion>
<Accordion title="Where can I find gateway logs?">
Check gateway logs for detailed error information:
- **systemd service:**
```bash
sudo journalctl -u infisical-gateway -f
```
- **Kubernetes:**
```bash
kubectl logs deployment/infisical-gateway
```
- **Local installation:** Logs appear in the terminal where you started the gateway
</Accordion>
<Accordion title="Where is the gateway configuration file stored?">
For systemd-based installations, the gateway's configuration file is stored at `/etc/infisical/gateway.conf`. You may reference or inspect this file for troubleshooting advanced configuration issues.
</Accordion>
<Accordion title="What happens if there is a network interruption?">
The gateway is designed to handle network interruptions gracefully:
@@ -338,34 +263,3 @@ The gateway is designed to handle network interruptions gracefully:
No manual intervention is typically required during network interruptions.
</Accordion>
<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:
- **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.
</Accordion>
<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 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
</Accordion>
<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 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>