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

misc: doc updates

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

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

@@ -3,43 +3,367 @@ title: "infisical gateway"
description: "Run the Infisical gateway or manage its systemd service" description: "Run the Infisical gateway or manage its systemd service"
--- ---
<Warning>
**New Gateway Architecture Available**
A completely redesigned gateway system is now available under the `infisical network` command with a fundamentally different architecture:
- **TCP-based SSH tunnels** instead of UDP/TURN protocol
- **Eliminates firewall complexity** - no UDP configuration needed
- **Enhanced security** with certificate-based authentication
- **Flexible deployment options** - instance-wide or organization-specific proxies
**Learn more:** See [`infisical network`](/cli/commands/network) for the new gateway architecture.
**Migration:** The current `infisical gateway` command will continue to work but **will be deprecated in a future release**. Migration to `infisical network gateway` requires **complete reconfiguration** - you cannot simply switch commands as this is an entirely different gateway infrastructure. We strongly recommend planning migration to `infisical network gateway` for all deployments.
</Warning>
<Tabs> <Tabs>
<Tab title="Run gateway"> <Tab title="Start gateway">
```bash ```bash
infisical gateway --token=<token> infisical gateway start --name=<name> --relay=<relay-name> --auth-method=<auth-method>
``` ```
</Tab> </Tab>
<Tab title="Install service"> <Tab title="Install gateway service">
```bash ```bash
sudo infisical gateway install --token=<token> --domain=<domain> sudo infisical gateway systemd install --token=<token> --domain=<domain> --name=<name> --relay=<relay-name>
``` ```
</Tab> </Tab>
</Tabs> </Tabs>
## Description ## Description
Run the Infisical gateway in the foreground or manage its systemd service installation. The gateway allows secure communication between your self-hosted Infisical instance and client applications. The Infisical gateway provides secure access to private resources using modern TCP-based SSH tunnel architecture with enhanced security and flexible deployment options.
The gateway system uses SSH reverse tunnels over TCP, eliminating firewall complexity and providing excellent performance for enterprise environments.
## Subcommands & flags ## Subcommands & flags
<Accordion title="infisical gateway" defaultOpen="true"> <Accordion title="infisical gateway start" defaultOpen="true">
Run the Infisical gateway in the foreground. The gateway will connect to the relay service and maintain a persistent connection. Run the Infisical gateway component within your VPC. The gateway establishes an SSH reverse tunnel to the specified relay server and provides secure access to private resources.
```bash
infisical gateway start --relay=<relay-name> --name=<name> --auth-method=<auth-method>
```
The gateway component:
- Establishes outbound SSH reverse tunnels to relay servers (no inbound firewall rules needed)
- Authenticates using SSH certificates issued by Infisical
- Automatically reconnects if the connection is lost
- Provides access to private resources within your network
### Authentication
The Infisical CLI supports multiple authentication methods. Below are the available authentication methods, with their respective flags.
<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="Flags">
<Expandable title="properties">
<ParamField query="client-id" type="string" required>
Your machine identity client ID.
</ParamField>
<ParamField query="client-secret" type="string" required>
Your machine identity client secret.
</ParamField>
<ParamField query="auth-method" type="string" required>
The authentication method to use. Must be `universal-auth` when using Universal Auth.
</ParamField>
</Expandable>
</ParamField>
```bash
infisical gateway start --auth-method=universal-auth --client-id=<client-id> --client-secret=<client-secret> --relay=<relay-name> --name=<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="Flags">
<Expandable title="properties">
<ParamField query="machine-identity-id" type="string" required>
Your machine identity ID.
</ParamField>
<ParamField query="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="auth-method" type="string" required>
The authentication method to use. Must be `kubernetes` when using Native Kubernetes.
</ParamField>
</Expandable>
</ParamField>
```bash
infisical gateway start --auth-method=kubernetes --machine-identity-id=<machine-identity-id> --relay=<relay-name> --name=<name>
```
</Accordion>
<Accordion title="Native Azure">
The Native Azure method is used to authenticate with Infisical when running in an Azure environment.
<ParamField query="Flags">
<Expandable title="properties">
<ParamField query="machine-identity-id" type="string" required>
Your machine identity ID.
</ParamField>
<ParamField query="auth-method" type="string" required>
The authentication method to use. Must be `azure` when using Native Azure.
</ParamField>
</Expandable>
</ParamField>
```bash
infisical gateway start --auth-method=azure --machine-identity-id=<machine-identity-id> --relay=<relay-name> --name=<name>
```
</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="Flags">
<Expandable title="properties">
<ParamField query="machine-identity-id" type="string" required>
Your machine identity ID.
</ParamField>
<ParamField query="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
infisical gateway start --auth-method=gcp-id-token --machine-identity-id=<machine-identity-id> --relay=<relay-name> --name=<name>
```
</Accordion>
<Accordion title="GCP IAM">
The GCP IAM method is used to authenticate with Infisical with a GCP service account key.
<ParamField query="Flags">
<Expandable title="properties">
<ParamField query="machine-identity-id" type="string" required>
Your machine identity ID.
</ParamField>
<ParamField query="service-account-key-file-path" type="string" required>
Path to your GCP service account key file _(Must be in JSON format!)_
</ParamField>
<ParamField query="auth-method" type="string" required>
The authentication method to use. Must be `gcp-iam` when using GCP IAM.
</ParamField>
</Expandable>
</ParamField>
```bash
infisical gateway start --auth-method=gcp-iam --machine-identity-id=<machine-identity-id> --service-account-key-file-path=<service-account-key-file-path> --relay=<relay-name> --name=<name>
```
</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="Flags">
<Expandable title="properties">
<ParamField query="machine-identity-id" type="string" required>
Your machine identity ID.
</ParamField>
<ParamField query="auth-method" type="string" required>
The authentication method to use. Must be `aws-iam` when using Native AWS IAM.
</ParamField>
</Expandable>
</ParamField>
```bash
infisical gateway start --auth-method=aws-iam --machine-identity-id=<machine-identity-id> --relay=<relay-name> --name=<name>
```
</Accordion>
<Accordion title="OIDC Auth">
The OIDC Auth method is used to authenticate with Infisical via identity tokens with OIDC.
<ParamField query="Flags">
<Expandable title="properties">
<ParamField query="machine-identity-id" type="string" required>
Your machine identity ID.
</ParamField>
<ParamField query="jwt" type="string" required>
The OIDC JWT from the identity provider.
</ParamField>
<ParamField query="auth-method" type="string" required>
The authentication method to use. Must be `oidc-auth` when using OIDC Auth.
</ParamField>
</Expandable>
</ParamField>
```bash
infisical gateway start --auth-method=oidc-auth --machine-identity-id=<machine-identity-id> --jwt=<oidc-jwt> --relay=<relay-name> --name=<name>
```
</Accordion>
<Accordion title="JWT Auth">
The JWT Auth method is used to authenticate with Infisical via a JWT token.
<ParamField query="Flags">
<Expandable title="properties">
<ParamField query="jwt" type="string" required>
The JWT token to use for authentication.
</ParamField>
<ParamField query="machine-identity-id" type="string" required>
Your machine identity ID.
</ParamField>
<ParamField query="auth-method" type="string" required>
The authentication method to use. Must be `jwt-auth` when using JWT Auth.
</ParamField>
</Expandable>
</ParamField>
```bash
infisical gateway start --auth-method=jwt-auth --jwt=<jwt> --machine-identity-id=<machine-identity-id> --relay=<relay-name> --name=<name>
```
</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="Flags">
<Expandable title="properties">
<ParamField query="token" type="string" required>
The machine identity access token to use for authentication.
</ParamField>
</Expandable>
</ParamField>
```bash
infisical gateway start --token=<token> --relay=<relay-name> --name=<name>
```
</Accordion>
</AccordionGroup>
### Other Flags
<Accordion title="--relay">
The name of the relay that this gateway should connect to. The relay must be running and registered before starting the gateway.
```bash
# Example
infisical gateway start --relay=my-relay --name=my-gateway --token=<token>
```
**Note:** If using organization relays or self-hosted instance relays, you must first start a relay server using `infisical relay start` before connecting gateways to it. For Infisical Cloud users using instance relays, the relay infrastructure is already running and managed by Infisical.
</Accordion>
<Accordion title="--name">
The name of the gateway instance.
```bash
# Example
infisical gateway start --name=my-gateway --relay=my-relay --token=<token>
```
</Accordion>
<Accordion title="--domain">
Domain of your self-hosted Infisical instance.
```bash
# Example
infisical gateway start --domain=https://app.your-domain.com --relay=<relay-name> --name=<name>
```
</Accordion>
</Accordion>
<Accordion title="infisical gateway systemd install">
Install and enable the gateway as a systemd service. This command must be run with sudo on Linux.
```bash
sudo infisical gateway systemd install --token=<token> --domain=<domain> --name=<name> --relay=<relay-name>
```
### Requirements
- Must be run on Linux
- Must be run with root/sudo privileges
- Requires systemd
### Flags
<Accordion title="--token">
The machine identity access token to authenticate with Infisical.
```bash
# Example
sudo infisical gateway systemd install --token=<token> --name=<name> --relay=<relay-name>
```
You may also expose the token to the CLI by setting the environment variable `INFISICAL_TOKEN` before executing the install command.
</Accordion>
<Accordion title="--domain">
Domain of your self-hosted Infisical instance.
```bash
# Example
sudo infisical gateway systemd install --domain=https://app.your-domain.com --name=<name> --relay=<relay-name>
```
</Accordion>
<Accordion title="--name">
The name of the gateway instance.
```bash
# Example
sudo infisical gateway systemd install --name=my-gateway --token=<token> --relay=<relay-name>
```
</Accordion>
<Accordion title="--relay">
The name of the relay that this gateway should connect to.
```bash
# Example
sudo infisical gateway systemd install --relay=my-relay --token=<token> --name=<name>
```
</Accordion>
### Service Details
The systemd service is installed with secure defaults:
- Service file: `/etc/systemd/system/infisical-gateway.service`
- Config file: `/etc/infisical/gateway.conf`
- Runs with restricted privileges:
- InaccessibleDirectories=/home
- PrivateTmp=yes
- Resource limits configured for stability
- Automatically restarts on failure
- Enabled to start on boot
- Maintains persistent SSH reverse tunnel connections to the specified relay
- Handles certificate rotation and connection recovery automatically
After installation, manage the service with standard systemd commands:
```bash
sudo systemctl start infisical-gateway # Start the service
sudo systemctl stop infisical-gateway # Stop the service
sudo systemctl status infisical-gateway # Check service status
sudo systemctl disable infisical-gateway # Disable auto-start on boot
```
</Accordion>
## Legacy Gateway Commands (Deprecated)
<Accordion title="infisical gateway (deprecated)">
<Warning>
**This command is deprecated and will be removed in a future release.**
Please migrate to `infisical gateway start` for the new TCP-based SSH tunnel architecture.
</Warning>
Run the legacy Infisical gateway in the foreground. The gateway will connect to the relay service and maintain a persistent connection.
```bash ```bash
infisical gateway --domain=<domain> --auth-method=<auth-method> infisical gateway --domain=<domain> --auth-method=<auth-method>
@@ -256,8 +580,14 @@ The Infisical CLI supports multiple authentication methods. Below are the availa
</Accordion> </Accordion>
</Accordion> </Accordion>
<Accordion title="infisical gateway install"> <Accordion title="infisical gateway install (deprecated)">
Install and enable the gateway as a systemd service. This command must be run with sudo on Linux. <Warning>
**This command is deprecated and will be removed in a future release.**
Please migrate to `infisical gateway systemd install` for the new TCP-based SSH tunnel architecture with enhanced security and better performance.
</Warning>
Install and enable the legacy gateway as a systemd service. This command must be run with sudo on Linux.
```bash ```bash
sudo infisical gateway install --token=<token> --domain=<domain> sudo infisical gateway install --token=<token> --domain=<domain>

441
docs/cli/commands/network.mdx
View File

@@ -1,441 +0,0 @@
---
title: "infisical network"
description: "Network-related commands for Infisical including gateway and proxy components"
---
<Tabs>
<Tab title="Run gateway">
```bash
infisical network gateway --token=<token>
```
</Tab>
<Tab title="Install service">
```bash
sudo infisical network gateway install --token=<token> --domain=<domain> --name=<name> --proxy-name=<proxy-name>
```
</Tab>
</Tabs>
## Description
Network-related commands for Infisical that provide secure access to private resources:
- **Gateway**: Lightweight agent deployed within your VPCs to provide access to private resources
- **Proxy**: Identity-aware relay infrastructure that routes encrypted traffic (can be instance-wide or organization-specific)
The gateway system uses SSH reverse tunnels over TCP, eliminating firewall complexity and providing excellent performance for enterprise environments.
## Subcommands & flags
<Accordion title="infisical network gateway" defaultOpen="true">
Run the Infisical gateway component within your VPC. The gateway establishes an SSH reverse tunnel to the specified proxy server and provides secure access to private resources.
```bash
infisical network gateway --proxy-name=<proxy-name> --name=<name> --auth-method=<auth-method>
```
The gateway component:
- Establishes outbound SSH reverse tunnels to proxy servers (no inbound firewall rules needed)
- Authenticates using SSH certificates issued by Infisical
- Automatically reconnects if the connection is lost
- Provides access to private resources within your network
### Authentication
The Infisical CLI supports multiple authentication methods. Below are the available authentication methods, with their respective flags.
<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="Flags">
<Expandable title="properties">
<ParamField query="client-id" type="string" required>
Your machine identity client ID.
</ParamField>
<ParamField query="client-secret" type="string" required>
Your machine identity client secret.
</ParamField>
<ParamField query="auth-method" type="string" required>
The authentication method to use. Must be `universal-auth` when using Universal Auth.
</ParamField>
</Expandable>
</ParamField>
```bash
infisical network gateway --auth-method=universal-auth --client-id=<client-id> --client-secret=<client-secret> --proxy-name=<proxy-name> --name=<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="Flags">
<Expandable title="properties">
<ParamField query="machine-identity-id" type="string" required>
Your machine identity ID.
</ParamField>
<ParamField query="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="auth-method" type="string" required>
The authentication method to use. Must be `kubernetes` when using Native Kubernetes.
</ParamField>
</Expandable>
</ParamField>
```bash
infisical network gateway --auth-method=kubernetes --machine-identity-id=<machine-identity-id> --proxy-name=<proxy-name> --name=<name>
```
</Accordion>
<Accordion title="Native Azure">
The Native Azure method is used to authenticate with Infisical when running in an Azure environment.
<ParamField query="Flags">
<Expandable title="properties">
<ParamField query="machine-identity-id" type="string" required>
Your machine identity ID.
</ParamField>
<ParamField query="auth-method" type="string" required>
The authentication method to use. Must be `azure` when using Native Azure.
</ParamField>
</Expandable>
</ParamField>
```bash
infisical network gateway --auth-method=azure --machine-identity-id=<machine-identity-id> --proxy-name=<proxy-name> --name=<name>
```
</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="Flags">
<Expandable title="properties">
<ParamField query="machine-identity-id" type="string" required>
Your machine identity ID.
</ParamField>
<ParamField query="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
infisical network gateway --auth-method=gcp-id-token --machine-identity-id=<machine-identity-id> --proxy-name=<proxy-name> --name=<name>
```
</Accordion>
<Accordion title="GCP IAM">
The GCP IAM method is used to authenticate with Infisical with a GCP service account key.
<ParamField query="Flags">
<Expandable title="properties">
<ParamField query="machine-identity-id" type="string" required>
Your machine identity ID.
</ParamField>
<ParamField query="service-account-key-file-path" type="string" required>
Path to your GCP service account key file _(Must be in JSON format!)_
</ParamField>
<ParamField query="auth-method" type="string" required>
The authentication method to use. Must be `gcp-iam` when using GCP IAM.
</ParamField>
</Expandable>
</ParamField>
```bash
infisical network gateway --auth-method=gcp-iam --machine-identity-id=<machine-identity-id> --service-account-key-file-path=<service-account-key-file-path> --proxy-name=<proxy-name> --name=<name>
```
</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="Flags">
<Expandable title="properties">
<ParamField query="machine-identity-id" type="string" required>
Your machine identity ID.
</ParamField>
<ParamField query="auth-method" type="string" required>
The authentication method to use. Must be `aws-iam` when using Native AWS IAM.
</ParamField>
</Expandable>
</ParamField>
```bash
infisical network gateway --auth-method=aws-iam --machine-identity-id=<machine-identity-id> --proxy-name=<proxy-name> --name=<name>
```
</Accordion>
<Accordion title="OIDC Auth">
The OIDC Auth method is used to authenticate with Infisical via identity tokens with OIDC.
<ParamField query="Flags">
<Expandable title="properties">
<ParamField query="machine-identity-id" type="string" required>
Your machine identity ID.
</ParamField>
<ParamField query="jwt" type="string" required>
The OIDC JWT from the identity provider.
</ParamField>
<ParamField query="auth-method" type="string" required>
The authentication method to use. Must be `oidc-auth` when using OIDC Auth.
</ParamField>
</Expandable>
</ParamField>
```bash
infisical network gateway --auth-method=oidc-auth --machine-identity-id=<machine-identity-id> --jwt=<oidc-jwt> --proxy-name=<proxy-name> --name=<name>
```
</Accordion>
<Accordion title="JWT Auth">
The JWT Auth method is used to authenticate with Infisical via a JWT token.
<ParamField query="Flags">
<Expandable title="properties">
<ParamField query="jwt" type="string" required>
The JWT token to use for authentication.
</ParamField>
<ParamField query="machine-identity-id" type="string" required>
Your machine identity ID.
</ParamField>
<ParamField query="auth-method" type="string" required>
The authentication method to use. Must be `jwt-auth` when using JWT Auth.
</ParamField>
</Expandable>
</ParamField>
```bash
infisical network gateway --auth-method=jwt-auth --jwt=<jwt> --machine-identity-id=<machine-identity-id> --proxy-name=<proxy-name> --name=<name>
```
</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="Flags">
<Expandable title="properties">
<ParamField query="token" type="string" required>
The machine identity access token to use for authentication.
</ParamField>
</Expandable>
</ParamField>
```bash
infisical network gateway --token=<token> --proxy-name=<proxy-name> --name=<name>
```
</Accordion>
</AccordionGroup>
### Other Flags
<Accordion title="--proxy-name">
The name of the proxy that this gateway should connect to. The proxy must be running and registered before starting the gateway.
```bash
# Example
infisical network gateway --proxy-name=my-proxy --name=my-gateway --token=<token>
```
**Note:** If using organization proxies or self-hosted instance proxies, you must first start a proxy server using `infisical network proxy` before connecting gateways to it. For Infisical Cloud users using instance proxies, the proxy infrastructure is already running and managed by Infisical.
</Accordion>
<Accordion title="--name">
The name of the gateway instance.
```bash
# Example
infisical network gateway --name=my-gateway --proxy-name=my-proxy --token=<token>
```
</Accordion>
<Accordion title="--domain">
Domain of your self-hosted Infisical instance.
```bash
# Example
infisical network gateway --domain=https://app.your-domain.com --proxy-name=<proxy-name> --name=<name>
```
</Accordion>
</Accordion>
<Accordion title="infisical network gateway install">
Install and enable the gateway as a systemd service. This command must be run with sudo on Linux.
```bash
sudo infisical network gateway install --token=<token> --domain=<domain> --name=<name> --proxy-name=<proxy-name>
```
### Requirements
- Must be run on Linux
- Must be run with root/sudo privileges
- Requires systemd
### Flags
<Accordion title="--token">
The machine identity access token to authenticate with Infisical.
```bash
# Example
sudo infisical network gateway install --token=<token> --name=<name> --proxy-name=<proxy-name>
```
You may also expose the token to the CLI by setting the environment variable `INFISICAL_TOKEN` before executing the install command.
</Accordion>
<Accordion title="--domain">
Domain of your self-hosted Infisical instance.
```bash
# Example
sudo infisical network gateway install --domain=https://app.your-domain.com --name=<name> --proxy-name=<proxy-name>
```
</Accordion>
<Accordion title="--name">
The name of the gateway instance.
```bash
# Example
sudo infisical network gateway install --name=my-gateway --token=<token> --proxy-name=<proxy-name>
```
</Accordion>
<Accordion title="--proxy-name">
The name of the proxy that this gateway should connect to.
```bash
# Example
sudo infisical network gateway install --proxy-name=my-proxy --token=<token> --name=<name>
```
</Accordion>
### Service Details
The systemd service is installed with secure defaults:
- Service file: `/etc/systemd/system/infisical-gateway.service`
- Config file: `/etc/infisical/gateway.conf`
- Runs with restricted privileges:
- InaccessibleDirectories=/home
- PrivateTmp=yes
- Resource limits configured for stability
- Automatically restarts on failure
- Enabled to start on boot
- Maintains persistent SSH reverse tunnel connections to the specified proxy
- Handles certificate rotation and connection recovery automatically
After installation, manage the service with standard systemd commands:
```bash
sudo systemctl start infisical-gateway # Start the service
sudo systemctl stop infisical-gateway # Stop the service
sudo systemctl status infisical-gateway # Check service status
sudo systemctl disable infisical-gateway # Disable auto-start on boot
```
</Accordion>
<Accordion title="infisical network proxy">
Run the Infisical proxy component. The proxy handles network traffic routing and can operate in different modes.
```bash
infisical network proxy --type=<type> --ip=<ip> --name=<name> --auth-method=<auth-method>
```
### Flags
<Accordion title="--type">
The type of proxy to run. Must be either 'instance' or 'org'.
- **`instance`**: Shared proxy server that can be used by all organizations on your Infisical instance. Set up by the instance administrator. Uses `INFISICAL_PROXY_AUTH_SECRET` environment variable for authentication, which must be configured by the instance admin.
- **`org`**: Dedicated proxy server that individual organizations deploy and manage in their own infrastructure. Provides enhanced security, custom geographic placement, and compliance benefits. Uses standard Infisical authentication methods.
```bash
# Organization proxy (customer-deployed)
infisical network proxy --type=org --ip=192.168.1.100 --name=my-org-proxy
# Instance proxy (configured by instance admin)
INFISICAL_PROXY_AUTH_SECRET=<secret> infisical network proxy --type=instance --ip=10.0.1.50 --name=shared-proxy
```
</Accordion>
<Accordion title="--ip">
The public IP address of the instance where the proxy is deployed. This must be a static public IP that gateways can reach.
```bash
# Example
infisical network proxy --ip=203.0.113.100 --type=org --name=my-proxy
```
</Accordion>
<Accordion title="--name">
The name of the proxy.
```bash
# Example
infisical network proxy --name=my-proxy --type=org --ip=192.168.1.100
```
</Accordion>
### Authentication
**Organization Proxies (`--type=org`):**
Deploy your own proxy server in your infrastructure for enhanced security and reduced latency. Supports all standard Infisical authentication methods documented above in the gateway section.
**Instance Proxies (`--type=instance`):**
Shared proxy servers that serve all organizations on your Infisical instance. For Infisical Cloud, these are already running and ready to use. For self-hosted deployments, they're set up by the instance administrator. Authentication is handled via the `INFISICAL_PROXY_AUTH_SECRET` environment variable.
```bash
# Organization proxy with Universal Auth (customer-deployed)
infisical network proxy --type=org --ip=192.168.1.100 --name=my-org-proxy --auth-method=universal-auth --client-id=<client-id> --client-secret=<client-secret>
# Instance proxy (configured by instance admin)
INFISICAL_PROXY_AUTH_SECRET=<secret> infisical network proxy --type=instance --ip=10.0.1.50 --name=shared-proxy
```
### Deployment Considerations
**When to use Instance Proxies (`--type=instance`):**
- You want to get started quickly without setting up your own proxy infrastructure
- You're using Infisical Cloud and want to leverage the existing proxy infrastructure
- You're on a self-hosted instance where the admin has already set up shared proxies
- You don't need custom geographic placement of proxy servers
- You don't have specific compliance requirements that require dedicated infrastructure
- You want to minimize operational overhead by using shared infrastructure
**When to use Organization Proxies (`--type=org`):**
- You need lower latency by deploying proxy servers closer to your resources
- You have security requirements that mandate running infrastructure in your own environment
- You have compliance requirements such as data sovereignty or air-gapped environments
- You need custom network policies or specific networking configurations
- You have high-scale performance requirements that shared infrastructure can't meet
- You want full control over your proxy infrastructure and its configuration
</Accordion>

303
docs/cli/commands/relay.mdx Normal file
View File

@@ -0,0 +1,303 @@
---
title: "infisical relay"
description: "Relay-related commands for Infisical including proxy components"
---
<Tabs>
<Tab title="Start relay">
```bash
infisical relay start --type=<type> --ip=<ip> --name=<name> --auth-method=<auth-method>
```
</Tab>
</Tabs>
## Description
Relay-related commands for Infisical that provide identity-aware relay infrastructure for routing encrypted traffic:
- **Relay**: Identity-aware server that routes encrypted traffic (can be instance-wide or organization-specific)
The relay system uses SSH reverse tunnels over TCP, eliminating firewall complexity and providing excellent performance for enterprise environments.
## Subcommands & flags
<Accordion title="infisical relay start" defaultOpen="true">
Run the Infisical relay component. The relay handles network traffic routing and can operate in different modes.
```bash
infisical relay start --type=<type> --ip=<ip> --name=<name> --auth-method=<auth-method>
```
### 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. Set up by the instance administrator. Uses `INFISICAL_PROXY_AUTH_SECRET` environment variable for authentication, which must be configured by the instance admin.
- **`org`**: Dedicated relay server that individual organizations deploy and manage in their own infrastructure. Provides enhanced security, custom geographic placement, and compliance benefits. Uses standard Infisical authentication methods.
```bash
# Organization relay (customer-deployed)
infisical relay start --type=org --ip=192.168.1.100 --name=my-org-relay
# Instance relay (configured by instance admin)
INFISICAL_PROXY_AUTH_SECRET=<secret> infisical relay start --type=instance --ip=10.0.1.50 --name=shared-relay
```
</Accordion>
<Accordion title="--ip">
The public IP address of the instance where the relay is deployed. This must be a static public IP that gateways can reach.
```bash
# Example
infisical relay start --ip=203.0.113.100 --type=org --name=my-relay
```
</Accordion>
<Accordion title="--name">
The name of the relay.
```bash
# Example
infisical relay start --name=my-relay --type=org --ip=192.168.1.100
```
</Accordion>
### Authentication
**Organization Relays (`--type=org`):**
Deploy your own relay server in your infrastructure for enhanced security and reduced latency. Supports all standard Infisical authentication methods documented below.
**Instance Relays (`--type=instance`):**
Shared relay servers that serve all organizations on your Infisical instance. For Infisical Cloud, these are already running and ready to use. For self-hosted deployments, they're set up by the instance administrator. Authentication is handled via the `INFISICAL_PROXY_AUTH_SECRET` environment variable.
```bash
# Organization relay with Universal Auth (customer-deployed)
infisical relay start --type=org --ip=192.168.1.100 --name=my-org-relay --auth-method=universal-auth --client-id=<client-id> --client-secret=<client-secret>
# Instance relay (configured by instance admin)
INFISICAL_PROXY_AUTH_SECRET=<secret> infisical relay start --type=instance --ip=10.0.1.50 --name=shared-relay
```
### Authentication Methods
The Infisical CLI supports multiple authentication methods for organization relays. Below are the available authentication methods, with their respective flags.
<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="Flags">
<Expandable title="properties">
<ParamField query="client-id" type="string" required>
Your machine identity client ID.
</ParamField>
<ParamField query="client-secret" type="string" required>
Your machine identity client secret.
</ParamField>
<ParamField query="auth-method" type="string" required>
The authentication method to use. Must be `universal-auth` when using Universal Auth.
</ParamField>
</Expandable>
</ParamField>
```bash
infisical relay start --auth-method=universal-auth --client-id=<client-id> --client-secret=<client-secret> --type=org --ip=<ip> --name=<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="Flags">
<Expandable title="properties">
<ParamField query="machine-identity-id" type="string" required>
Your machine identity ID.
</ParamField>
<ParamField query="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="auth-method" type="string" required>
The authentication method to use. Must be `kubernetes` when using Native Kubernetes.
</ParamField>
</Expandable>
</ParamField>
```bash
infisical relay start --auth-method=kubernetes --machine-identity-id=<machine-identity-id> --type=org --ip=<ip> --name=<name>
```
</Accordion>
<Accordion title="Native Azure">
The Native Azure method is used to authenticate with Infisical when running in an Azure environment.
<ParamField query="Flags">
<Expandable title="properties">
<ParamField query="machine-identity-id" type="string" required>
Your machine identity ID.
</ParamField>
<ParamField query="auth-method" type="string" required>
The authentication method to use. Must be `azure` when using Native Azure.
</ParamField>
</Expandable>
</ParamField>
```bash
infisical relay start --auth-method=azure --machine-identity-id=<machine-identity-id> --type=org --ip=<ip> --name=<name>
```
</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="Flags">
<Expandable title="properties">
<ParamField query="machine-identity-id" type="string" required>
Your machine identity ID.
</ParamField>
<ParamField query="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
infisical relay start --auth-method=gcp-id-token --machine-identity-id=<machine-identity-id> --type=org --ip=<ip> --name=<name>
```
</Accordion>
<Accordion title="GCP IAM">
The GCP IAM method is used to authenticate with Infisical with a GCP service account key.
<ParamField query="Flags">
<Expandable title="properties">
<ParamField query="machine-identity-id" type="string" required>
Your machine identity ID.
</ParamField>
<ParamField query="service-account-key-file-path" type="string" required>
Path to your GCP service account key file _(Must be in JSON format!)_
</ParamField>
<ParamField query="auth-method" type="string" required>
The authentication method to use. Must be `gcp-iam` when using GCP IAM.
</ParamField>
</Expandable>
</ParamField>
```bash
infisical relay start --auth-method=gcp-iam --machine-identity-id=<machine-identity-id> --service-account-key-file-path=<service-account-key-file-path> --type=org --ip=<ip> --name=<name>
```
</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="Flags">
<Expandable title="properties">
<ParamField query="machine-identity-id" type="string" required>
Your machine identity ID.
</ParamField>
<ParamField query="auth-method" type="string" required>
The authentication method to use. Must be `aws-iam` when using Native AWS IAM.
</ParamField>
</Expandable>
</ParamField>
```bash
infisical relay start --auth-method=aws-iam --machine-identity-id=<machine-identity-id> --type=org --ip=<ip> --name=<name>
```
</Accordion>
<Accordion title="OIDC Auth">
The OIDC Auth method is used to authenticate with Infisical via identity tokens with OIDC.
<ParamField query="Flags">
<Expandable title="properties">
<ParamField query="machine-identity-id" type="string" required>
Your machine identity ID.
</ParamField>
<ParamField query="jwt" type="string" required>
The OIDC JWT from the identity provider.
</ParamField>
<ParamField query="auth-method" type="string" required>
The authentication method to use. Must be `oidc-auth` when using OIDC Auth.
</ParamField>
</Expandable>
</ParamField>
```bash
infisical relay start --auth-method=oidc-auth --machine-identity-id=<machine-identity-id> --jwt=<oidc-jwt> --type=org --ip=<ip> --name=<name>
```
</Accordion>
<Accordion title="JWT Auth">
The JWT Auth method is used to authenticate with Infisical via a JWT token.
<ParamField query="Flags">
<Expandable title="properties">
<ParamField query="jwt" type="string" required>
The JWT token to use for authentication.
</ParamField>
<ParamField query="machine-identity-id" type="string" required>
Your machine identity ID.
</ParamField>
<ParamField query="auth-method" type="string" required>
The authentication method to use. Must be `jwt-auth` when using JWT Auth.
</ParamField>
</Expandable>
</ParamField>
```bash
infisical relay start --auth-method=jwt-auth --jwt=<jwt> --machine-identity-id=<machine-identity-id> --type=org --ip=<ip> --name=<name>
```
</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="Flags">
<Expandable title="properties">
<ParamField query="token" type="string" required>
The machine identity access token to use for authentication.
</ParamField>
</Expandable>
</ParamField>
```bash
infisical relay start --token=<token> --type=org --ip=<ip> --name=<name>
```
</Accordion>
</AccordionGroup>
### Deployment Considerations
**When to use Instance Relays (`--type=instance`):**
- You want to get started quickly without setting up your own relay infrastructure
- You're using Infisical Cloud and want to leverage the existing relay infrastructure
- You're on a self-hosted instance where the admin has already set up shared relays
- You don't need custom geographic placement of relay servers
- You don't have specific compliance requirements that require dedicated infrastructure
- You want to minimize operational overhead by using shared infrastructure
**When to use Organization Relays (`--type=org`):**
- You need lower latency by deploying relay servers closer to your resources
- You have security requirements that mandate running infrastructure in your own environment
- You have compliance requirements such as data sovereignty or air-gapped environments
- You need custom network policies or specific networking configurations
- You have high-scale performance requirements that shared infrastructure can't meet
- You want full control over your relay infrastructure and its configuration
</Accordion>

2
docs/docs.json
View File

@@ -774,11 +774,11 @@
"cli/commands/dynamic-secrets", "cli/commands/dynamic-secrets",
"cli/commands/ssh", "cli/commands/ssh",
"cli/commands/gateway", "cli/commands/gateway",
"cli/commands/relay",
"cli/commands/bootstrap", "cli/commands/bootstrap",
"cli/commands/export", "cli/commands/export",
"cli/commands/token", "cli/commands/token",
"cli/commands/service-token", "cli/commands/service-token",
"cli/commands/network",
"cli/commands/vault", "cli/commands/vault",
"cli/commands/user", "cli/commands/user",
"cli/commands/reset", "cli/commands/reset",

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

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

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

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

BIN
docs/images/platform/gateways/gateway-highlevel-diagram.png
View File

Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 111 KiB

After

Width:  |  Height:  |  Size: 324 KiB

2
helm-charts/infisical-gateway/templates/deployment.yaml
View File

@@ -38,8 +38,8 @@ spec:
image: "infisical/cli:{{ .Values.image.tag | default .Chart.AppVersion }}" image: "infisical/cli:{{ .Values.image.tag | default .Chart.AppVersion }}"
imagePullPolicy: {{ .Values.image.pullPolicy }} imagePullPolicy: {{ .Values.image.pullPolicy }}
args: args:
- network
- gateway - gateway
- start
envFrom: envFrom:
- secretRef: - secretRef:
name: {{ .Values.secret.name }} name: {{ .Values.secret.name }}