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

doc: cli docs for gateway v2

Browse Source
This commit is contained in:
Sheen Capadngan
2025-09-04 01:09:48 +08:00
parent d994cb0bf8
commit 0a9f51f62f
3 changed files with 525 additions and 40 deletions
Download Patch File Download Diff File Expand all files Collapse all files

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

@@ -3,6 +3,22 @@ title: "infisical gateway"
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>
<Tab title="Run gateway">
```bash
@@ -25,13 +41,13 @@ Run the Infisical gateway in the foreground or manage its systemd service instal
<Accordion title="infisical gateway" defaultOpen="true">
Run the Infisical gateway in the foreground. The gateway will connect to the relay service and maintain a persistent connection.
```bash
infisical gateway --domain=<domain> --auth-method=<auth-method>
```
```bash
infisical gateway --domain=<domain> --auth-method=<auth-method>
```
### Authentication
### Authentication
The Infisical CLI supports multiple authentication methods. Below are the available authentication methods, with their respective flags.
The Infisical CLI supports multiple authentication methods. Below are the available authentication methods, with their respective flags.
<AccordionGroup>
<Accordion title="Universal Auth">
@@ -121,7 +137,6 @@ Run the Infisical gateway in the foreground or manage its systemd service instal
infisical gateway --auth-method=gcp-id-token --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.
@@ -163,7 +178,6 @@ Run the Infisical gateway in the foreground or manage its systemd service instal
infisical gateway --auth-method=aws-iam --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.
@@ -185,6 +199,7 @@ Run the Infisical gateway in the foreground or manage its systemd service instal
```bash
infisical gateway --auth-method=oidc-auth --machine-identity-id=<machine-identity-id> --jwt=<oidc-jwt>
```
</Accordion>
<Accordion title="JWT Auth">
@@ -208,6 +223,7 @@ Run the Infisical gateway in the foreground or manage its systemd service instal
```bash
infisical gateway --auth-method=jwt-auth --jwt=<jwt> --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.
@@ -227,7 +243,7 @@ Run the Infisical gateway in the foreground or manage its systemd service instal
</Accordion>
</AccordionGroup>
### Other Flags
### Other Flags
<Accordion title="--domain">
Domain of your self-hosted Infisical instance.
@@ -236,22 +252,24 @@ Run the Infisical gateway in the foreground or manage its systemd service instal
# Example
infisical gateway --domain=https://app.your-domain.com
```
</Accordion>
</Accordion>
<Accordion title="infisical gateway install">
Install and enable the gateway as a systemd service. This command must be run with sudo on Linux.
```bash
sudo infisical gateway install --token=<token> --domain=<domain>
```
```bash
sudo infisical gateway install --token=<token> --domain=<domain>
```
### Requirements
- Must be run on Linux
- Must be run with root/sudo privileges
- Requires systemd
### Requirements
### Flags
- 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.
@@ -262,6 +280,7 @@ Run the Infisical gateway in the foreground or manage its systemd service instal
```
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">
@@ -271,24 +290,29 @@ Run the Infisical gateway in the foreground or manage its systemd service instal
# Example
sudo infisical gateway install --domain=https://app.your-domain.com
```
</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
### 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
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
```
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>

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

@@ -0,0 +1,441 @@
---
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 through a three-tier proxy system:
- **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>