mirror of
https://github.com/Infisical/infisical.git
synced 2026-01-09 15:38:03 -05:00
misc: revamped gateway v2 docs
This commit is contained in:
Sheen Capadngan
@@ -9,6 +9,15 @@ description: "Relay-related commands for Infisical"
|
||||
infisical relay start --type=<type> --host=<host> --name=<name> --auth-method=<auth-method>
|
||||
```
|
||||
</Tab>
|
||||
<Tab title="Systemd service">
|
||||
```bash
|
||||
# Install systemd service
|
||||
sudo infisical relay systemd install --type=<type> --host=<host> --name=<name> --token=<token>
|
||||
|
||||
# Uninstall systemd service
|
||||
sudo infisical relay systemd uninstall
|
||||
```
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
## Description
|
||||
@@ -304,3 +313,154 @@ The Infisical CLI supports multiple authentication methods for organization rela
|
||||
- You want full control over your relay infrastructure and its configuration
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="infisical relay systemd" defaultOpen="false">
|
||||
Manage systemd service for Infisical relay. This allows you to install and run the relay as a systemd service on Linux systems.
|
||||
### Requirements
|
||||
- **Operating System**: Linux only (systemd is not supported on other operating systems)
|
||||
- **Privileges**: Root/sudo privileges required for both install and uninstall operations
|
||||
- **Systemd**: The system must be running systemd as the init system
|
||||
|
||||
```bash
|
||||
infisical relay systemd <subcommand>
|
||||
```
|
||||
|
||||
### Subcommands
|
||||
|
||||
<Accordion title="install">
|
||||
Install and enable systemd service for the relay. Must be run with sudo on Linux systems.
|
||||
|
||||
```bash
|
||||
sudo infisical relay systemd install --type=<type> --host=<host> --name=<name> [flags]
|
||||
```
|
||||
|
||||
#### Flags
|
||||
|
||||
<Accordion title="--type">
|
||||
The type of relay to run. Must be either 'instance' or 'org'.
|
||||
|
||||
- **`instance`**: Shared relay server that can be used by all organizations on your Infisical instance. Requires `--relay-auth-secret` flag or `INFISICAL_RELAY_AUTH_SECRET` environment variable.
|
||||
- **`org`**: Dedicated relay server that individual organizations deploy and manage in their own infrastructure. Requires `--token` flag.
|
||||
|
||||
```bash
|
||||
# Organization relay
|
||||
sudo infisical relay systemd install --type=org --host=192.168.1.100 --name=my-org-relay --token=<token>
|
||||
|
||||
# Instance relay
|
||||
sudo infisical relay systemd install --type=instance --host=10.0.1.50 --name=shared-relay --relay-auth-secret=<secret>
|
||||
```
|
||||
|
||||
</Accordion>
|
||||
|
||||
<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.
|
||||
|
||||
```bash
|
||||
# Example with IP address
|
||||
sudo infisical relay systemd install --host=203.0.113.100 --type=org --name=my-relay --token=<token>
|
||||
|
||||
# Example with hostname
|
||||
sudo infisical relay systemd install --host=relay.example.com --type=org --name=my-relay --token=<token>
|
||||
```
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="--name">
|
||||
The name of the relay.
|
||||
|
||||
```bash
|
||||
# Example
|
||||
sudo infisical relay systemd install --name=my-relay --type=org --host=192.168.1.100 --token=<token>
|
||||
```
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="--token">
|
||||
Connect with Infisical using machine identity access token. Required for organization relays (`--type=org`).
|
||||
|
||||
```bash
|
||||
# Example
|
||||
sudo infisical relay systemd install --token=<machine-identity-token> --type=org --host=<host> --name=<name>
|
||||
```
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="--domain">
|
||||
Domain of your self-hosted Infisical instance. Optional flag for specifying a custom domain.
|
||||
|
||||
```bash
|
||||
# Example
|
||||
sudo infisical relay systemd install --domain=http://localhost:8080 --token=<token> --type=org --host=<host> --name=<name>
|
||||
```
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="--relay-auth-secret">
|
||||
Relay auth secret. Required for instance relays (`--type=instance`) if the `INFISICAL_RELAY_AUTH_SECRET` environment variable is not set.
|
||||
|
||||
```bash
|
||||
# Example
|
||||
sudo infisical relay systemd install --relay-auth-secret=<secret> --type=instance --host=<host> --name=<name>
|
||||
```
|
||||
|
||||
</Accordion>
|
||||
|
||||
#### Examples
|
||||
|
||||
```bash
|
||||
# Install organization relay with token authentication
|
||||
sudo infisical relay systemd install --type=org --host=192.168.1.100 --name=my-org-relay --token=<machine-identity-token>
|
||||
|
||||
# Install instance relay with auth secret
|
||||
sudo infisical relay systemd install --type=instance --host=10.0.1.50 --name=shared-relay --relay-auth-secret=<secret>
|
||||
|
||||
# Install with custom domain
|
||||
sudo infisical relay systemd install --domain=http://localhost:8080 --token=<token> --type=org --host=<host> --name=<name>
|
||||
```
|
||||
|
||||
#### Post-installation
|
||||
|
||||
After successful installation, the service will be enabled but not started. To start the service:
|
||||
|
||||
```bash
|
||||
sudo systemctl start infisical-relay
|
||||
```
|
||||
|
||||
To check the service status:
|
||||
|
||||
```bash
|
||||
sudo systemctl status infisical-relay
|
||||
```
|
||||
|
||||
To view service logs:
|
||||
|
||||
```bash
|
||||
sudo journalctl -u infisical-relay -f
|
||||
```
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="uninstall">
|
||||
Uninstall and remove systemd service for the relay. Must be run with sudo on Linux systems.
|
||||
|
||||
```bash
|
||||
sudo infisical relay systemd uninstall
|
||||
```
|
||||
|
||||
#### Examples
|
||||
|
||||
```bash
|
||||
# Uninstall the relay systemd service
|
||||
sudo infisical relay systemd uninstall
|
||||
```
|
||||
|
||||
#### What it does
|
||||
|
||||
- Stops the `infisical-relay` systemd service if it's running
|
||||
- Disables the service from starting on boot
|
||||
- Removes the systemd service file
|
||||
- Cleans up the service configuration
|
||||
|
||||
</Accordion>
|
||||
|
||||
</Accordion>
|
||||
|
||||
@@ -173,8 +173,9 @@
|
||||
"group": "Gateway",
|
||||
"pages": [
|
||||
"documentation/platform/gateways/overview",
|
||||
"documentation/platform/gateways/gateway-security",
|
||||
"documentation/platform/gateways/deployment",
|
||||
"documentation/platform/gateways/networking",
|
||||
"documentation/platform/gateways/security",
|
||||
{
|
||||
"group": "Gateway (Deprecated)",
|
||||
"pages": [
|
||||
|
||||
375
docs/documentation/platform/gateways/deployment.mdx
Normal file
375
docs/documentation/platform/gateways/deployment.mdx
Normal file
@@ -0,0 +1,375 @@
|
||||
---
|
||||
title: "Deployment Guide"
|
||||
description: "Complete guide to deploying Infisical Gateways and Relays"
|
||||
---
|
||||
|
||||
This guide covers everything you need to deploy and configure both Infisical Gateways and Relay Servers, including prerequisites, step-by-step instructions, and troubleshooting.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
Before deploying gateways or relays, 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
|
||||
|
||||
## Deploying Relays
|
||||
|
||||
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.
|
||||
|
||||
<Info>
|
||||
Most users should start with **Instance Relays** for simplicity. Consider
|
||||
Organization Relays only if you have specific latency, compliance, or control
|
||||
requirements.
|
||||
</Info>
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Instance Relays">
|
||||
**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=<shared-secret-value>
|
||||
```
|
||||
|
||||
**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=<shared-secret-value>
|
||||
|
||||
# Start the instance relay
|
||||
infisical relay start --type=instance --host=<public-ip> --name=<relay-name>
|
||||
```
|
||||
|
||||
<Warning>
|
||||
The `RELAY_AUTH_SECRET` (instance environment) and
|
||||
`INFISICAL_RELAY_AUTH_SECRET` (relay environment) **must match exactly** for
|
||||
authentication to work.
|
||||
</Warning>
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Organization Relays (Customer-Deployed)">
|
||||
Deploy your own relay server for full control. Organization relays support all authentication methods:
|
||||
|
||||
```bash
|
||||
# Token auth
|
||||
infisical relay start --type=org --host=<public-ip> --name=<relay-name> --token=<token>
|
||||
|
||||
# Universal auth
|
||||
infisical relay start --type=org --host=<public-ip> --name=<relay-name> --auth-method=universal-auth --client-id=<id> --client-secret=<secret>
|
||||
|
||||
# Other auth methods (kubernetes, aws-iam, gcp-id-token, azure, etc.)
|
||||
infisical relay start --type=org --host=<public-ip> --name=<relay-name> --auth-method=<method> --machine-identity-id=<id>
|
||||
```
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
### Relay Systemd Service (Linux)
|
||||
|
||||
For production deployments, install as a systemd service:
|
||||
|
||||
```bash
|
||||
# Organization relay
|
||||
sudo infisical relay systemd install --token=<token> --name=<name> --host=<host> --type=org
|
||||
|
||||
# Instance relay
|
||||
sudo infisical relay systemd install --type=instance --name=<name> --host=<host> --relay-auth-secret=<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
|
||||
|
||||
For production deployments on Linux servers, install the Gateway as a systemd service:
|
||||
|
||||
<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 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.
|
||||
|
||||
</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
|
||||
|
||||
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 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.
|
||||
|
||||
</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.
|
||||
|
||||
**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>
|
||||
|
||||
### Environment Variables
|
||||
|
||||
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:
|
||||
|
||||
- `INFISICAL_API_URL` - The Infisical API URL (defaults to `https://app.infisical.com`)
|
||||
|
||||
## 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
|
||||
|
||||
### 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
|
||||
- **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
|
||||
|
||||
**Relay not accessible from gateways:**
|
||||
|
||||
- Check firewall rules allow inbound SSH on port 2222
|
||||
- Verify public IP is correctly configured
|
||||
- Test connectivity: `telnet <relay-ip> 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 <relay-ip>:8443`
|
||||
|
||||
### 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:
|
||||
|
||||
```bash
|
||||
# Test SSH port from gateway
|
||||
nc -zv <relay-ip> 2222
|
||||
|
||||
# Test TCP with TLS port from platform
|
||||
openssl s_client -connect <relay-ip>:8443
|
||||
|
||||
# Test outbound API access
|
||||
curl -I https://app.infisical.com
|
||||
```
|
||||
@@ -1,21 +1,20 @@
|
||||
---
|
||||
title: "Networking"
|
||||
description: "Network configuration and firewall requirements for Infisical Gateway"
|
||||
title: "Networking Requirements"
|
||||
description: "Network configuration and firewall requirements for Infisical Gateways and Relays"
|
||||
---
|
||||
|
||||
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.
|
||||
This page outlines the required ports, protocols, and firewall configurations needed for optimal gateway and relay usage.
|
||||
|
||||
## Network Architecture
|
||||
|
||||
The gateway uses SSH reverse tunnels to establish secure connections with end-to-end encryption:
|
||||
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
|
||||
|
||||
## Required Network Connectivity
|
||||
## Gateway Network Requirements
|
||||
|
||||
### Outbound Connections (Required)
|
||||
|
||||
@@ -55,6 +54,141 @@ The gateway requires the following outbound connectivity:
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
## 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
|
||||
@@ -65,10 +199,6 @@ The gateway uses SSH reverse tunnels for primary communication:
|
||||
- **Built-in features**: Automatic reconnection, certificate-based authentication, encrypted tunneling
|
||||
- **Encryption**: SSH with certificate-based authentication and key exchange
|
||||
|
||||
## Firewall Configuration for SSH
|
||||
|
||||
The gateway uses standard SSH over TCP, making firewall configuration straightforward.
|
||||
|
||||
### TCP Connection Handling
|
||||
|
||||
SSH connections over TCP are stateful and handled seamlessly by all modern firewalls:
|
||||
@@ -78,14 +208,6 @@ SSH connections over TCP are stateful and handled seamlessly by all modern firew
|
||||
- **No special configuration** needed for connection tracking
|
||||
- **Standard SSH protocol** that enterprise firewalls handle well
|
||||
|
||||
### Simplified Firewall Rules
|
||||
|
||||
Since SSH uses TCP, 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
|
||||
@@ -105,6 +227,15 @@ Configure security groups to allow:
|
||||
- **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
|
||||
|
||||
<Accordion title="What happens if there is a network interruption?">
|
||||
@@ -134,7 +265,7 @@ TCP's reliability and firewall compatibility make it ideal for enterprise enviro
|
||||
</Accordion>
|
||||
|
||||
<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:
|
||||
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
|
||||
@@ -163,6 +294,7 @@ The gateway connects to **one relay server**:
|
||||
- **Certificate-based authentication**: Each connection uses SSH certificates issued by Infisical for secure authentication
|
||||
|
||||
</Accordion>
|
||||
|
||||
<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:
|
||||
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
---
|
||||
title: "Gateway"
|
||||
title: "Gateway Overview"
|
||||
sidebarTitle: "Overview"
|
||||
description: "How to access private network resources from Infisical"
|
||||
---
|
||||
@@ -8,13 +8,6 @@ description: "How to access private network resources from Infisical"
|
||||
|
||||
The Infisical Gateway provides secure access to private resources within your network without needing direct inbound connections to your environment. This method keeps your resources fully protected from external access while enabling Infisical to securely interact with resources like databases.
|
||||
|
||||
**Architecture Components:**
|
||||
|
||||
- **Gateway**: Lightweight agent deployed within your VPCs that provides access to private resources
|
||||
- **Relay**: Infrastructure that routes encrypted traffic (instance-wide or organization-specific)
|
||||
|
||||
Common use cases include generating dynamic credentials or rotating credentials for private databases.
|
||||
|
||||
<Info>
|
||||
Gateway is a paid feature available under the Enterprise Tier for Infisical
|
||||
Cloud users. Self-hosted Infisical users can contact
|
||||
@@ -22,6 +15,26 @@ Common use cases include generating dynamic credentials or rotating credentials
|
||||
license.
|
||||
</Info>
|
||||
|
||||
## What are Gateways and Relays?
|
||||
|
||||
### Gateway
|
||||
|
||||
A lightweight service deployed within your VPCs that provides secure access to private resources:
|
||||
|
||||
- **Runs inside your network** - Deployed within your VPCs, data centers, or on-premises infrastructure
|
||||
- **Makes outbound connections only** - No inbound firewall rules required
|
||||
- **Provides secure access** - Uses SSH reverse tunnels and certificate-based authentication
|
||||
- **Handles resource connections** - Connects to your private databases, APIs, and services
|
||||
|
||||
### Relay Server
|
||||
|
||||
Infrastructure that routes encrypted traffic between the Infisical platform and gateways:
|
||||
|
||||
- **Routes encrypted traffic** - Routes traffic between the platform and gateways
|
||||
- **Provides network isolation** - Enables communication without direct connections
|
||||
- **Handles authentication** - Manages SSH certificate validation and routing
|
||||
- **Ensures security** - Uses double encryption to protect data in transit
|
||||
|
||||
## How It Works
|
||||
|
||||
The Gateway system uses SSH reverse tunnels for secure, firewall-friendly connectivity:
|
||||
@@ -37,7 +50,62 @@ The Gateway system uses SSH reverse tunnels for secure, firewall-friendly connec
|
||||
- **Certificate-based authentication** provides enhanced security
|
||||
- **Automatic reconnection** if connections are lost
|
||||
|
||||
## Deployment
|
||||
## Relay Types
|
||||
|
||||
### Instance Relays (Shared Infrastructure)
|
||||
|
||||
**Infisical Cloud:**
|
||||
|
||||
- Pre-configured and ready to use
|
||||
- No setup required
|
||||
- Shared across all organizations
|
||||
- Managed by Infisical
|
||||
|
||||
**Self-hosted:**
|
||||
|
||||
- Set up by instance administrators
|
||||
- Shared across all organizations on the instance
|
||||
- Uses `INFISICAL_RELAY_AUTH_SECRET` for authentication
|
||||
|
||||
### Organization Relays (Customer-Deployed)
|
||||
|
||||
**Benefits:**
|
||||
|
||||
- Full control over infrastructure
|
||||
- Lower latency (deploy closer to resources)
|
||||
- Enhanced security and compliance
|
||||
- Custom network policies
|
||||
|
||||
**Authentication:**
|
||||
|
||||
- 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.
|
||||
@@ -45,405 +113,15 @@ For detailed installation instructions, refer to the Infisical [CLI Installation
|
||||
|
||||
**Prerequisites:**
|
||||
|
||||
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
|
||||
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.
|
||||
|
||||
### Get started
|
||||
## Next Steps
|
||||
|
||||
<Steps>
|
||||
<Step title="Create a Gateway Identity">
|
||||
1. Navigate to **Organization Access Control** in your Infisical dashboard.
|
||||
2. Create a dedicated machine identity for your Gateway.
|
||||
3. **Best Practice:** Assign a unique identity to each Gateway for better security and management.
|
||||
|
||||
</Step>
|
||||
|
||||
<Step title="Configure Authentication Method">
|
||||
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>
|
||||
Ready to get started? Follow these guides:
|
||||
|
||||
<Step title="Choose Your Relay Setup">
|
||||
You have two options for relay infrastructure:
|
||||
|
||||
<Tabs>
|
||||
<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 relays, you can use them directly. If not, the instance admin can set them up:
|
||||
```bash
|
||||
# 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 Relay">
|
||||
**Available for all users:** Deploy your own dedicated relay infrastructure for enhanced control:
|
||||
```bash
|
||||
# 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:**
|
||||
- You need lower latency (deploy closer to your resources)
|
||||
- Enhanced security requirements
|
||||
- Compliance needs (data sovereignty, air-gapped environments)
|
||||
- Custom network policies
|
||||
</Tab>
|
||||
</Tabs>
|
||||
</Step>
|
||||
|
||||
<Step title="Deploy the Gateway">
|
||||
Use the Infisical CLI to deploy the Gateway. You can run it directly or install it as a systemd service for production:
|
||||
|
||||
<Tabs>
|
||||
<Tab title="Production (systemd)">
|
||||
For production deployments on Linux, install the Gateway as a systemd service:
|
||||
|
||||
<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 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.
|
||||
</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:
|
||||
- Runs as root user (required for secure token management)
|
||||
- Restricted access to home directories
|
||||
- Private temporary directory
|
||||
- Automatically restarts on failure
|
||||
- Starts on system boot
|
||||
- Manages token and domain configuration securely in `/etc/infisical/gateway.conf`
|
||||
|
||||
<Warning>
|
||||
The install command requires:
|
||||
- Linux operating system
|
||||
- Root/sudo privileges
|
||||
- Systemd
|
||||
</Warning>
|
||||
</Tab>
|
||||
|
||||
<Tab title="Production (Helm)">
|
||||
|
||||
The Gateway can be installed via [Helm](https://helm.sh/). Helm is a package manager for Kubernetes that allows you to define, install, and upgrade Kubernetes applications.
|
||||
|
||||
For production deployments on Kubernetes, 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/'
|
||||
```
|
||||
|
||||
### Update the Helm Chart repository
|
||||
```bash
|
||||
helm repo update
|
||||
```
|
||||
|
||||
### Create a Kubernetes Secret containing gateway environment variables
|
||||
|
||||
The gateway supports all identity authentication methods through the use of environment variables.
|
||||
The environment variables must be set in the `infisical-gateway-environment` Kubernetes secret.
|
||||
|
||||
|
||||
#### Supported authentication methods
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Universal Auth">
|
||||
The Universal Auth method is a simple and secure way to authenticate with Infisical. It requires a client ID and a client secret to authenticate with Infisical.
|
||||
|
||||
<ParamField query="Environment Variables">
|
||||
<Expandable title="properties">
|
||||
<ParamField query="INFISICAL_UNIVERSAL_AUTH_CLIENT_ID" type="string" required>
|
||||
Your machine identity client ID.
|
||||
</ParamField>
|
||||
<ParamField query="INFISICAL_UNIVERSAL_AUTH_CLIENT_SECRET" type="string" required>
|
||||
Your machine identity client secret.
|
||||
</ParamField>
|
||||
<ParamField query="INFISICAL_AUTH_METHOD" type="string" required>
|
||||
The authentication method to use. Must be `universal-auth` when using Universal Auth.
|
||||
</ParamField>
|
||||
</Expandable>
|
||||
</ParamField>
|
||||
|
||||
```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>
|
||||
```
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Native Kubernetes">
|
||||
The Native Kubernetes method is used to authenticate with Infisical when running in a Kubernetes environment. It requires a service account token to authenticate with Infisical.
|
||||
|
||||
<ParamField query="Environment Variables">
|
||||
<Expandable title="properties">
|
||||
<ParamField query="INFISICAL_MACHINE_IDENTITY_ID" type="string" required>
|
||||
Your machine identity ID.
|
||||
</ParamField>
|
||||
<ParamField query="INFISICAL_KUBERNETES_SERVICE_ACCOUNT_TOKEN_PATH" type="string" optional>
|
||||
Path to the Kubernetes service account token to use. Default: `/var/run/secrets/kubernetes.io/serviceaccount/token`.
|
||||
</ParamField>
|
||||
<ParamField query="INFISICAL_AUTH_METHOD" type="string" required>
|
||||
The authentication method to use. Must be `kubernetes` when using Native Kubernetes.
|
||||
</ParamField>
|
||||
</Expandable>
|
||||
</ParamField>
|
||||
|
||||
|
||||
```bash
|
||||
kubectl create secret generic infisical-gateway-environment --from-literal=INFISICAL_AUTH_METHOD=kubernetes --from-literal=INFISICAL_MACHINE_IDENTITY_ID=<machine-identity-id>
|
||||
```
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Native Azure">
|
||||
The Native Azure method is used to authenticate with Infisical when running in an Azure environment.
|
||||
|
||||
<ParamField query="Environment Variables">
|
||||
<Expandable title="properties">
|
||||
<ParamField query="INFISICAL_MACHINE_IDENTITY_ID" type="string" required>
|
||||
Your machine identity ID.
|
||||
</ParamField>
|
||||
<ParamField query="INFISICAL_AUTH_METHOD" type="string" required>
|
||||
The authentication method to use. Must be `azure` when using Native Azure.
|
||||
</ParamField>
|
||||
</Expandable>
|
||||
</ParamField>
|
||||
|
||||
```bash
|
||||
kubectl create secret generic infisical-gateway-environment --from-literal=INFISICAL_AUTH_METHOD=azure --from-literal=INFISICAL_MACHINE_IDENTITY_ID=<machine-identity-id>
|
||||
```
|
||||
</Accordion>
|
||||
<Accordion title="Native GCP ID Token">
|
||||
The Native GCP ID Token method is used to authenticate with Infisical when running in a GCP environment.
|
||||
|
||||
<ParamField query="Environment Variables">
|
||||
<Expandable title="properties">
|
||||
<ParamField query="INFISICAL_MACHINE_IDENTITY_ID" type="string" required>
|
||||
Your machine identity ID.
|
||||
</ParamField>
|
||||
<ParamField query="INFISICAL_AUTH_METHOD" type="string" required>
|
||||
The authentication method to use. Must be `gcp-id-token` when using Native GCP ID Token.
|
||||
</ParamField>
|
||||
</Expandable>
|
||||
</ParamField>
|
||||
|
||||
```bash
|
||||
kubectl create secret generic infisical-gateway-environment --from-literal=INFISICAL_AUTH_METHOD=gcp-id-token --from-literal=INFISICAL_MACHINE_IDENTITY_ID=<machine-identity-id>
|
||||
```
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="GCP IAM">
|
||||
The GCP IAM method is used to authenticate with Infisical with a GCP service account key.
|
||||
|
||||
<ParamField query="Environment Variables">
|
||||
<Expandable title="properties">
|
||||
<ParamField query="INFISICAL_MACHINE_IDENTITY_ID" type="string" required>
|
||||
Your machine identity ID.
|
||||
</ParamField>
|
||||
<ParamField query="INFISICAL_GCP_SERVICE_ACCOUNT_KEY_FILE_PATH" type="string" required>
|
||||
Path to your GCP service account key file _(Must be in JSON format!)_
|
||||
</ParamField>
|
||||
<ParamField query="INFISICAL_AUTH_METHOD" type="string" required>
|
||||
The authentication method to use. Must be `gcp-iam` when using GCP IAM.
|
||||
</ParamField>
|
||||
</Expandable>
|
||||
</ParamField>
|
||||
|
||||
```bash
|
||||
kubectl create secret generic infisical-gateway-environment --from-literal=INFISICAL_AUTH_METHOD=gcp-iam --from-literal=INFISICAL_MACHINE_IDENTITY_ID=<machine-identity-id> --from-literal=INFISICAL_GCP_SERVICE_ACCOUNT_KEY_FILE_PATH=<service-account-key-file-path>
|
||||
```
|
||||
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Native AWS IAM">
|
||||
The AWS IAM method is used to authenticate with Infisical with an AWS IAM role while running in an AWS environment like EC2, Lambda, etc.
|
||||
|
||||
<ParamField query="Environment Variables">
|
||||
<Expandable title="properties">
|
||||
<ParamField query="INFISICAL_MACHINE_IDENTITY_ID" type="string" required>
|
||||
Your machine identity ID.
|
||||
</ParamField>
|
||||
<ParamField query="INFISICAL_AUTH_METHOD" type="string" required>
|
||||
The authentication method to use. Must be `aws-iam` when using Native AWS IAM.
|
||||
</ParamField>
|
||||
</Expandable>
|
||||
</ParamField>
|
||||
|
||||
```bash
|
||||
kubectl create secret generic infisical-gateway-environment --from-literal=INFISICAL_AUTH_METHOD=aws-iam --from-literal=INFISICAL_MACHINE_IDENTITY_ID=<machine-identity-id>
|
||||
```
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="OIDC Auth">
|
||||
The OIDC Auth method is used to authenticate with Infisical via identity tokens with OIDC.
|
||||
|
||||
<ParamField query="Environment Variables">
|
||||
<Expandable title="properties">
|
||||
<ParamField query="INFISICAL_MACHINE_IDENTITY_ID" type="string" required>
|
||||
Your machine identity ID.
|
||||
</ParamField>
|
||||
<ParamField query="INFISICAL_JWT" type="string" required>
|
||||
The OIDC JWT from the identity provider.
|
||||
</ParamField>
|
||||
<ParamField query="INFISICAL_AUTH_METHOD" type="string" required>
|
||||
The authentication method to use. Must be `oidc-auth` when using OIDC Auth.
|
||||
</ParamField>
|
||||
</Expandable>
|
||||
</ParamField>
|
||||
|
||||
```bash
|
||||
kubectl create secret generic infisical-gateway-environment --from-literal=INFISICAL_AUTH_METHOD=oidc-auth --from-literal=INFISICAL_MACHINE_IDENTITY_ID=<machine-identity-id> --from-literal=INFISICAL_JWT=<oidc-jwt>
|
||||
```
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="JWT Auth">
|
||||
The JWT Auth method is used to authenticate with Infisical via a JWT token.
|
||||
|
||||
<ParamField query="Environment Variables">
|
||||
<Expandable title="properties">
|
||||
<ParamField query="INFISICAL_JWT" type="string" required>
|
||||
The JWT token to use for authentication.
|
||||
</ParamField>
|
||||
<ParamField query="INFISICAL_MACHINE_IDENTITY_ID" type="string" required>
|
||||
Your machine identity ID.
|
||||
</ParamField>
|
||||
<ParamField query="INFISICAL_AUTH_METHOD" type="string" required>
|
||||
The authentication method to use. Must be `jwt-auth` when using JWT Auth.
|
||||
</ParamField>
|
||||
</Expandable>
|
||||
</ParamField>
|
||||
|
||||
```bash
|
||||
kubectl create secret generic infisical-gateway-environment --from-literal=INFISICAL_AUTH_METHOD=jwt-auth --from-literal=INFISICAL_JWT=<jwt> --from-literal=INFISICAL_MACHINE_IDENTITY_ID=<machine-identity-id>
|
||||
```
|
||||
</Accordion>
|
||||
<Accordion title="Token Auth">
|
||||
You can use the `INFISICAL_TOKEN` environment variable to authenticate with Infisical with a raw machine identity access token.
|
||||
|
||||
<ParamField query="Environment Variables">
|
||||
<Expandable title="properties">
|
||||
<ParamField query="INFISICAL_TOKEN" type="string" required>
|
||||
The machine identity access token to use for authentication.
|
||||
</ParamField>
|
||||
</Expandable>
|
||||
</ParamField>
|
||||
|
||||
```bash
|
||||
kubectl create secret generic infisical-gateway-environment --from-literal=INFISICAL_TOKEN=<token>
|
||||
```
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
|
||||
#### Required environment variables
|
||||
|
||||
In addition to the authentication method above, you **must** include these required variables:
|
||||
|
||||
<AccordionGroup>
|
||||
<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.
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
**Complete example with required 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>
|
||||
```
|
||||
|
||||
#### Other environment variables
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="INFISICAL_API_URL">
|
||||
The API URL to use for the gateway. By default, `INFISICAL_API_URL` is set to `https://app.infisical.com`.
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
### Install the Infisical Gateway Helm Chart
|
||||
<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 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.
|
||||
</Warning>
|
||||
|
||||
```bash
|
||||
helm install infisical-gateway infisical-helm-charts/infisical-gateway
|
||||
```
|
||||
|
||||
### Check the gateway logs
|
||||
After installing the gateway, you can check the logs to ensure it's running as expected.
|
||||
|
||||
```bash
|
||||
kubectl logs deployment/infisical-gateway
|
||||
```
|
||||
|
||||
You should see the following output which indicates the gateway is running as expected.
|
||||
```bash
|
||||
$ kubectl logs deployment/infisical-gateway
|
||||
12:43AM INF Starting gateway
|
||||
12:43AM INF Starting gateway certificate renewal goroutine
|
||||
12:43AM INF Successfully registered gateway and received certificates
|
||||
12:43AM INF Connecting to relay server infisical-start on 152.42.218.156:2222...
|
||||
12:43AM INF Relay connection established for gateway
|
||||
12:43AM INF Received incoming connection, starting TLS handshake
|
||||
12:43AM INF TLS handshake completed successfully
|
||||
12:43AM INF Negotiated ALPN protocol: infisical-ping
|
||||
12:43AM INF Starting ping handler
|
||||
12:43AM INF Ping handler completed
|
||||
12:43AM INF Gateway is reachable by Infisical
|
||||
```
|
||||
|
||||
</Tab>
|
||||
|
||||
<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 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 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 gateway start --relay=<relay-name> --name=<gateway-name>
|
||||
```
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
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 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>
|
||||
|
||||
<Step title="Verify Gateway Deployment">
|
||||
To confirm your Gateway is working, check the deployment status by looking for the message **"Gateway started successfully"** in the Gateway logs. This indicates the Gateway is running properly. Next, verify its registration by opening your Infisical dashboard, navigating to **Organization Access Control**, and selecting the **Gateways** tab. Your newly deployed Gateway should appear in the list.
|
||||
|
||||
</Step>
|
||||
</Steps>
|
||||
1. **[Deployment Guide](/documentation/platform/gateways/deployment)** - Complete deployment instructions
|
||||
2. **[Networking Requirements](/documentation/platform/gateways/networking)** - Network configuration and firewall setup
|
||||
3. **[Security Architecture](/documentation/platform/gateways/security)** - Security model and best practices
|
||||
|
||||
@@ -1,13 +1,9 @@
|
||||
---
|
||||
title: "Gateway Security Architecture"
|
||||
sidebarTitle: "Architecture"
|
||||
description: "Understand the security model and tenant isolation of Infisical's Gateway"
|
||||
title: "Security Architecture"
|
||||
description: "Security model, tenant isolation, and best practices for Infisical Gateways and Relays"
|
||||
---
|
||||
|
||||
# Gateway Security Architecture
|
||||
|
||||
The Infisical Gateway enables secure access to private resources using SSH reverse tunnels, certificate-based authentication, and a comprehensive PKI (Public Key Infrastructure) system. The architecture provides end-to-end encryption and complete tenant isolation through multiple certificate authorities.
|
||||
This document explains the internal security architecture and how tenant isolation is maintained.
|
||||
|
||||
## Security Model Overview
|
||||
|
||||
@@ -82,16 +78,16 @@ The platform establishes secure direct connections with gateways through a **TLS
|
||||
2. **Connection Flow**:
|
||||
|
||||
```
|
||||
Platform ←→ [SSH Reverse Tunnel] ←→ Gateway
|
||||
Platform ←→ [TCP with TLS] ←→ Relay ←→ [SSH Reverse Tunnel] ←→ Gateway
|
||||
```
|
||||
|
||||
- Gateway maintains persistent outbound SSH tunnel to relay server
|
||||
- Platform connects directly to gateway through this tunnel
|
||||
- TLS handshake occurs over the SSH tunnel, establishing mTLS connection
|
||||
- Application traffic flows through the TLS-pinned tunnel
|
||||
- Platform connects to relay server using TCP with TLS
|
||||
- Relay routes encrypted traffic between platform and gateway
|
||||
- TLS handshake occurs between platform and gateway through the relay
|
||||
- Application traffic flows through the TLS-pinned tunnel via relay routing
|
||||
|
||||
3. **Security Benefits**:
|
||||
|
||||
- **No inbound connections**: Gateway never needs to accept incoming connections
|
||||
- **Certificate-based authentication**: Uses Organization Gateway certificates for mutual TLS
|
||||
- **Double encryption**: TLS traffic within SSH tunnel provides layered security
|
||||
@@ -132,7 +128,77 @@ The architecture provides tenant isolation through multiple certificate authorit
|
||||
- Ephemeral certificate validation ensures time-bound access
|
||||
|
||||
2. **Network Isolation**:
|
||||
|
||||
- Each organization's traffic flows through isolated certificate-authenticated channels
|
||||
- Relay servers route traffic based on certificate validation without content access
|
||||
- Gateway validates all incoming connections against Organization Gateway Client CA
|
||||
|
||||
## Security 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 (quarterly recommended)
|
||||
- **Monitor authentication** - Watch for unusual authentication activity
|
||||
- **Deploy close to resources** - Place gateways as close as possible to your private resources
|
||||
- **Use multiple gateways** - Deploy multiple gateways for redundancy and load distribution
|
||||
|
||||
### Relay Security
|
||||
|
||||
- **Deploy close to gateways** - Minimize latency between gateways and relays
|
||||
- **Use multiple regions** - Deploy relays in multiple regions for redundancy
|
||||
- **Monitor performance** - Track connection counts and throughput
|
||||
- **Regular updates** - Keep relay servers updated and patched
|
||||
- **Network isolation** - Use security groups and network ACLs to restrict access
|
||||
- **Monitor network traffic** - Watch for unusual patterns
|
||||
|
||||
### Network Security
|
||||
|
||||
- **Gateway outbound only** - Gateways only need outbound connections (port 2222 to relays, port 443 to Infisical API)
|
||||
- **Relay inbound** - Relays need inbound SSH (2222) and TCP with TLS (8443)
|
||||
- **No inbound for gateways** - Never open inbound ports for gateways
|
||||
- **Use security groups** in cloud environments to restrict access
|
||||
- **Implement network ACLs** to limit traffic to specific IP ranges
|
||||
- **Monitor network traffic** for unusual patterns
|
||||
- **Regular security updates** for the relay server
|
||||
|
||||
## Compliance Considerations
|
||||
|
||||
### Data Sovereignty
|
||||
|
||||
- **Customer-deployed relays** - Deploy relays in your preferred geographic region
|
||||
- **Air-gapped environments** - Use self-hosted relays for completely isolated deployments
|
||||
- **Custom network policies** - Implement organization-specific security requirements
|
||||
|
||||
### Security Controls
|
||||
|
||||
- **Certificate-based authentication** - No shared secrets, uses SSH certificates
|
||||
- **End-to-end encryption** - All traffic is encrypted in transit
|
||||
- **Tenant isolation** - Each organization's traffic is completely isolated
|
||||
- **No data storage** - Relay servers only route traffic, never store data
|
||||
- **Automatic reconnection** - Handles network interruptions gracefully
|
||||
|
||||
## Troubleshooting Security Issues
|
||||
|
||||
### Common Security Issues
|
||||
|
||||
**Authentication failures:**
|
||||
|
||||
- Verify machine identity credentials are correct
|
||||
- Check token expiration and renewal
|
||||
- Ensure authentication method is properly configured
|
||||
|
||||
**Network security issues:**
|
||||
|
||||
- Verify firewall rules allow required connections
|
||||
- Check for network ACLs blocking traffic
|
||||
- Monitor for unusual network patterns
|
||||
|
||||
### Security Monitoring
|
||||
|
||||
**Key metrics to monitor:**
|
||||
|
||||
- Gateway connection status and health
|
||||
- Authentication success/failure rates
|
||||
- Network connectivity and latency
|
||||
- Unusual traffic patterns or access attempts
|
||||
Reference in New Issue
Block a user