diff --git a/docs/cli/commands/gateway.mdx b/docs/cli/commands/gateway.mdx index 0168c7a425..1d66281b8a 100644 --- a/docs/cli/commands/gateway.mdx +++ b/docs/cli/commands/gateway.mdx @@ -3,43 +3,367 @@ title: "infisical gateway" description: "Run the Infisical gateway or manage its systemd service" --- - -**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. - - - - + ```bash - infisical gateway --token= + infisical gateway start --name= --relay= --auth-method= ``` - + ```bash - sudo infisical gateway install --token= --domain= + sudo infisical gateway systemd install --token= --domain= --name= --relay= ``` ## 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 - - 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= --name= --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. + + + + 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. + + + + + Your machine identity client ID. + + + Your machine identity client secret. + + + The authentication method to use. Must be `universal-auth` when using Universal Auth. + + + + + ```bash + infisical gateway start --auth-method=universal-auth --client-id= --client-secret= --relay= --name= + ``` + + + + 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. + + + + + Your machine identity ID. + + + Path to the Kubernetes service account token to use. Default: `/var/run/secrets/kubernetes.io/serviceaccount/token`. + + + The authentication method to use. Must be `kubernetes` when using Native Kubernetes. + + + + + + + ```bash + infisical gateway start --auth-method=kubernetes --machine-identity-id= --relay= --name= + ``` + + + + The Native Azure method is used to authenticate with Infisical when running in an Azure environment. + + + + + Your machine identity ID. + + + The authentication method to use. Must be `azure` when using Native Azure. + + + + + + + ```bash + infisical gateway start --auth-method=azure --machine-identity-id= --relay= --name= + ``` + + + + The Native GCP ID Token method is used to authenticate with Infisical when running in a GCP environment. + + + + + Your machine identity ID. + + + The authentication method to use. Must be `gcp-id-token` when using Native GCP ID Token. + + + + + + + ```bash + infisical gateway start --auth-method=gcp-id-token --machine-identity-id= --relay= --name= + ``` + + + + The GCP IAM method is used to authenticate with Infisical with a GCP service account key. + + + + + Your machine identity ID. + + + Path to your GCP service account key file _(Must be in JSON format!)_ + + + The authentication method to use. Must be `gcp-iam` when using GCP IAM. + + + + + ```bash + infisical gateway start --auth-method=gcp-iam --machine-identity-id= --service-account-key-file-path= --relay= --name= + ``` + + + + 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. + + + + + Your machine identity ID. + + + The authentication method to use. Must be `aws-iam` when using Native AWS IAM. + + + + + ```bash + infisical gateway start --auth-method=aws-iam --machine-identity-id= --relay= --name= + ``` + + + + The OIDC Auth method is used to authenticate with Infisical via identity tokens with OIDC. + + + + + Your machine identity ID. + + + The OIDC JWT from the identity provider. + + + The authentication method to use. Must be `oidc-auth` when using OIDC Auth. + + + + + ```bash + infisical gateway start --auth-method=oidc-auth --machine-identity-id= --jwt= --relay= --name= + ``` + + + + + The JWT Auth method is used to authenticate with Infisical via a JWT token. + + + + + The JWT token to use for authentication. + + + Your machine identity ID. + + + The authentication method to use. Must be `jwt-auth` when using JWT Auth. + + + + + + ```bash + infisical gateway start --auth-method=jwt-auth --jwt= --machine-identity-id= --relay= --name= + ``` + + + + You can use the `INFISICAL_TOKEN` environment variable to authenticate with Infisical with a raw machine identity access token. + + + + + The machine identity access token to use for authentication. + + + + + ```bash + infisical gateway start --token= --relay= --name= + ``` + + + + +### Other Flags + + + 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= + ``` + + **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. + + + + + The name of the gateway instance. + + ```bash + # Example + infisical gateway start --name=my-gateway --relay=my-relay --token= + ``` + + + + + Domain of your self-hosted Infisical instance. + + ```bash + # Example + infisical gateway start --domain=https://app.your-domain.com --relay= --name= + ``` + + + + + + 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= --domain= --name= --relay= +``` + +### Requirements + +- Must be run on Linux +- Must be run with root/sudo privileges +- Requires systemd + +### Flags + + + The machine identity access token to authenticate with Infisical. + + ```bash + # Example + sudo infisical gateway systemd install --token= --name= --relay= + ``` + + You may also expose the token to the CLI by setting the environment variable `INFISICAL_TOKEN` before executing the install command. + + + + + Domain of your self-hosted Infisical instance. + + ```bash + # Example + sudo infisical gateway systemd install --domain=https://app.your-domain.com --name= --relay= + ``` + + + + + The name of the gateway instance. + + ```bash + # Example + sudo infisical gateway systemd install --name=my-gateway --token= --relay= + ``` + + + + + The name of the relay that this gateway should connect to. + + ```bash + # Example + sudo infisical gateway systemd install --relay=my-relay --token= --name= + ``` + + + +### 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 +``` + + + +## Legacy Gateway Commands (Deprecated) + + + + **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. + + +Run the legacy Infisical gateway in the foreground. The gateway will connect to the relay service and maintain a persistent connection. ```bash infisical gateway --domain= --auth-method= @@ -256,8 +580,14 @@ The Infisical CLI supports multiple authentication methods. Below are the availa - - Install and enable the gateway as a systemd service. This command must be run with sudo on Linux. + + + **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. + + +Install and enable the legacy gateway as a systemd service. This command must be run with sudo on Linux. ```bash sudo infisical gateway install --token= --domain= diff --git a/docs/cli/commands/network.mdx b/docs/cli/commands/network.mdx deleted file mode 100644 index 0ed19a2245..0000000000 --- a/docs/cli/commands/network.mdx +++ /dev/null @@ -1,441 +0,0 @@ ---- -title: "infisical network" -description: "Network-related commands for Infisical including gateway and proxy components" ---- - - - - ```bash - infisical network gateway --token= - ``` - - - ```bash - sudo infisical network gateway install --token= --domain= --name= --proxy-name= - ``` - - - -## 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 - - - 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= --name= --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. - - - - 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. - - - - - Your machine identity client ID. - - - Your machine identity client secret. - - - The authentication method to use. Must be `universal-auth` when using Universal Auth. - - - - - ```bash - infisical network gateway --auth-method=universal-auth --client-id= --client-secret= --proxy-name= --name= - ``` - - - - 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. - - - - - Your machine identity ID. - - - Path to the Kubernetes service account token to use. Default: `/var/run/secrets/kubernetes.io/serviceaccount/token`. - - - The authentication method to use. Must be `kubernetes` when using Native Kubernetes. - - - - - - - ```bash - infisical network gateway --auth-method=kubernetes --machine-identity-id= --proxy-name= --name= - ``` - - - - The Native Azure method is used to authenticate with Infisical when running in an Azure environment. - - - - - Your machine identity ID. - - - The authentication method to use. Must be `azure` when using Native Azure. - - - - - - - ```bash - infisical network gateway --auth-method=azure --machine-identity-id= --proxy-name= --name= - ``` - - - - The Native GCP ID Token method is used to authenticate with Infisical when running in a GCP environment. - - - - - Your machine identity ID. - - - The authentication method to use. Must be `gcp-id-token` when using Native GCP ID Token. - - - - - - - ```bash - infisical network gateway --auth-method=gcp-id-token --machine-identity-id= --proxy-name= --name= - ``` - - - - The GCP IAM method is used to authenticate with Infisical with a GCP service account key. - - - - - Your machine identity ID. - - - Path to your GCP service account key file _(Must be in JSON format!)_ - - - The authentication method to use. Must be `gcp-iam` when using GCP IAM. - - - - - ```bash - infisical network gateway --auth-method=gcp-iam --machine-identity-id= --service-account-key-file-path= --proxy-name= --name= - ``` - - - - 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. - - - - - Your machine identity ID. - - - The authentication method to use. Must be `aws-iam` when using Native AWS IAM. - - - - - ```bash - infisical network gateway --auth-method=aws-iam --machine-identity-id= --proxy-name= --name= - ``` - - - - The OIDC Auth method is used to authenticate with Infisical via identity tokens with OIDC. - - - - - Your machine identity ID. - - - The OIDC JWT from the identity provider. - - - The authentication method to use. Must be `oidc-auth` when using OIDC Auth. - - - - - ```bash - infisical network gateway --auth-method=oidc-auth --machine-identity-id= --jwt= --proxy-name= --name= - ``` - - - - - The JWT Auth method is used to authenticate with Infisical via a JWT token. - - - - - The JWT token to use for authentication. - - - Your machine identity ID. - - - The authentication method to use. Must be `jwt-auth` when using JWT Auth. - - - - - - ```bash - infisical network gateway --auth-method=jwt-auth --jwt= --machine-identity-id= --proxy-name= --name= - ``` - - - - You can use the `INFISICAL_TOKEN` environment variable to authenticate with Infisical with a raw machine identity access token. - - - - - The machine identity access token to use for authentication. - - - - - ```bash - infisical network gateway --token= --proxy-name= --name= - ``` - - - - -### Other Flags - - - 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= - ``` - - **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. - - - - - The name of the gateway instance. - - ```bash - # Example - infisical network gateway --name=my-gateway --proxy-name=my-proxy --token= - ``` - - - - - Domain of your self-hosted Infisical instance. - - ```bash - # Example - infisical network gateway --domain=https://app.your-domain.com --proxy-name= --name= - ``` - - - - - - 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= --domain= --name= --proxy-name= -``` - -### Requirements - -- Must be run on Linux -- Must be run with root/sudo privileges -- Requires systemd - -### Flags - - - The machine identity access token to authenticate with Infisical. - - ```bash - # Example - sudo infisical network gateway install --token= --name= --proxy-name= - ``` - - You may also expose the token to the CLI by setting the environment variable `INFISICAL_TOKEN` before executing the install command. - - - - - Domain of your self-hosted Infisical instance. - - ```bash - # Example - sudo infisical network gateway install --domain=https://app.your-domain.com --name= --proxy-name= - ``` - - - - - The name of the gateway instance. - - ```bash - # Example - sudo infisical network gateway install --name=my-gateway --token= --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= --name= - ``` - - - -### 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 -``` - - - - - Run the Infisical proxy component. The proxy handles network traffic routing and can operate in different modes. - -```bash -infisical network proxy --type= --ip= --name= --auth-method= -``` - -### Flags - - - 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= infisical network proxy --type=instance --ip=10.0.1.50 --name=shared-proxy - ``` - - - - - 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 - ``` - - - - - The name of the proxy. - - ```bash - # Example - infisical network proxy --name=my-proxy --type=org --ip=192.168.1.100 - ``` - - - -### 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-secret= - -# Instance proxy (configured by instance admin) -INFISICAL_PROXY_AUTH_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 - - diff --git a/docs/cli/commands/relay.mdx b/docs/cli/commands/relay.mdx new file mode 100644 index 0000000000..f7843709ce --- /dev/null +++ b/docs/cli/commands/relay.mdx @@ -0,0 +1,303 @@ +--- +title: "infisical relay" +description: "Relay-related commands for Infisical including proxy components" +--- + + + + ```bash + infisical relay start --type= --ip= --name= --auth-method= + ``` + + + +## 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 + + + Run the Infisical relay component. The relay handles network traffic routing and can operate in different modes. + +```bash +infisical relay start --type= --ip= --name= --auth-method= +``` + +### Flags + + + 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= infisical relay start --type=instance --ip=10.0.1.50 --name=shared-relay + ``` + + + + + 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 + ``` + + + + + The name of the relay. + + ```bash + # Example + infisical relay start --name=my-relay --type=org --ip=192.168.1.100 + ``` + + + +### 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-secret= + +# Instance relay (configured by instance admin) +INFISICAL_PROXY_AUTH_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. + + + + 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. + + + + + Your machine identity client ID. + + + Your machine identity client secret. + + + The authentication method to use. Must be `universal-auth` when using Universal Auth. + + + + + ```bash + infisical relay start --auth-method=universal-auth --client-id= --client-secret= --type=org --ip= --name= + ``` + + + + 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. + + + + + Your machine identity ID. + + + Path to the Kubernetes service account token to use. Default: `/var/run/secrets/kubernetes.io/serviceaccount/token`. + + + The authentication method to use. Must be `kubernetes` when using Native Kubernetes. + + + + + + + ```bash + infisical relay start --auth-method=kubernetes --machine-identity-id= --type=org --ip= --name= + ``` + + + + The Native Azure method is used to authenticate with Infisical when running in an Azure environment. + + + + + Your machine identity ID. + + + The authentication method to use. Must be `azure` when using Native Azure. + + + + + + + ```bash + infisical relay start --auth-method=azure --machine-identity-id= --type=org --ip= --name= + ``` + + + + The Native GCP ID Token method is used to authenticate with Infisical when running in a GCP environment. + + + + + Your machine identity ID. + + + The authentication method to use. Must be `gcp-id-token` when using Native GCP ID Token. + + + + + + + ```bash + infisical relay start --auth-method=gcp-id-token --machine-identity-id= --type=org --ip= --name= + ``` + + + + The GCP IAM method is used to authenticate with Infisical with a GCP service account key. + + + + + Your machine identity ID. + + + Path to your GCP service account key file _(Must be in JSON format!)_ + + + The authentication method to use. Must be `gcp-iam` when using GCP IAM. + + + + + ```bash + infisical relay start --auth-method=gcp-iam --machine-identity-id= --service-account-key-file-path= --type=org --ip= --name= + ``` + + + + 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. + + + + + Your machine identity ID. + + + The authentication method to use. Must be `aws-iam` when using Native AWS IAM. + + + + + ```bash + infisical relay start --auth-method=aws-iam --machine-identity-id= --type=org --ip= --name= + ``` + + + + The OIDC Auth method is used to authenticate with Infisical via identity tokens with OIDC. + + + + + Your machine identity ID. + + + The OIDC JWT from the identity provider. + + + The authentication method to use. Must be `oidc-auth` when using OIDC Auth. + + + + + ```bash + infisical relay start --auth-method=oidc-auth --machine-identity-id= --jwt= --type=org --ip= --name= + ``` + + + + + The JWT Auth method is used to authenticate with Infisical via a JWT token. + + + + + The JWT token to use for authentication. + + + Your machine identity ID. + + + The authentication method to use. Must be `jwt-auth` when using JWT Auth. + + + + + + ```bash + infisical relay start --auth-method=jwt-auth --jwt= --machine-identity-id= --type=org --ip= --name= + ``` + + + + You can use the `INFISICAL_TOKEN` environment variable to authenticate with Infisical with a raw machine identity access token. + + + + + The machine identity access token to use for authentication. + + + + + ```bash + infisical relay start --token= --type=org --ip= --name= + ``` + + + + +### 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 + + diff --git a/docs/docs.json b/docs/docs.json index 6a82526af6..285e11a608 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -774,11 +774,11 @@ "cli/commands/dynamic-secrets", "cli/commands/ssh", "cli/commands/gateway", + "cli/commands/relay", "cli/commands/bootstrap", "cli/commands/export", "cli/commands/token", "cli/commands/service-token", - "cli/commands/network", "cli/commands/vault", "cli/commands/user", "cli/commands/reset", diff --git a/docs/documentation/platform/gateways/networking.mdx b/docs/documentation/platform/gateways/networking.mdx index c7ab95fd9a..ca99a4e926 100644 --- a/docs/documentation/platform/gateways/networking.mdx +++ b/docs/documentation/platform/gateways/networking.mdx @@ -3,17 +3,17 @@ title: "Networking" 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. ## Network Architecture 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 -3. **Proxy 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 +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 @@ -23,34 +23,34 @@ The gateway requires the following outbound connectivity: | 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 | -### 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. - - Infisical provides multiple managed proxy servers with static IP addresses. - You can whitelist these IPs ahead of time based on which proxy server you + + Infisical provides multiple managed relay servers with static IP addresses. + You can whitelist these IPs ahead of time based on which relay server you choose to connect to. **Firewall requirements:** Allow outbound TCP - connections to the desired proxy server IP on port 2222. + connections to the desired relay server IP on port 2222. - - You control the proxy server IP addresses when deploying your own - organization proxies. **Firewall requirements:** Allow outbound TCP - connections to your proxy server IP on port 2222. For example, if your proxy + + You control the relay server IP addresses when deploying your own + organization relays. **Firewall requirements:** Allow outbound TCP + 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`. - - 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 - TCP connections to instance proxy servers on port 2222. + TCP connections to instance relay servers on port 2222. @@ -60,7 +60,7 @@ The gateway requires the following outbound connectivity: 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 - **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: -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 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: -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 3. **No inbound rules required** - all connections are outbound only 4. **Standard TCP rules** - simple and straightforward configuration @@ -100,7 +100,7 @@ For corporate environments with strict egress filtering: 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 - **No inbound rules required** - SSH reverse tunnels are outbound only @@ -109,7 +109,7 @@ Configure security groups to allow: 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 - **Persistent SSH tunnels**: SSH connections are automatically re-established when connectivity is restored - **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 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 - **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 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 3. **Consider network policy exceptions** for the gateway host if needed 4. **Monitor firewall logs** to identify which specific rules are blocking traffic - -The gateway connects to **one proxy server**: + +The gateway connects to **one relay server**: -- **Single SSH connection**: Each gateway establishes one SSH reverse tunnel to its assigned proxy server -- **Named proxy assignment**: Gateways connect to the specific proxy server specified by `--proxy-name` -- **Automatic reconnection**: If the proxy connection is lost, the gateway automatically reconnects to the same proxy +- **Single SSH connection**: Each gateway establishes one SSH reverse tunnel to its assigned relay server +- **Named relay assignment**: Gateways connect to the specific relay server specified by `--relay` +- **Automatic reconnection**: If the relay connection is lost, the gateway automatically reconnects to the same relay - **Certificate-based authentication**: Each connection uses SSH certificates issued by Infisical for secure authentication - -No, 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 -- **SSH tunnel encryption**: The mTLS-encrypted traffic is then transmitted through SSH reverse tunnels to proxy servers +- **Client-to-Gateway mTLS (via TLS-pinned tunnel)**: Clients connect via a proxy that establishes a TLS-pinned tunnel to the gateway; mTLS between the client and gateway is negotiated inside this tunnel, encrypting all application traffic +- **SSH tunnel encryption**: The mTLS-encrypted traffic is then transmitted through SSH reverse tunnels to relay servers - **Double encryption**: Traffic is encrypted twice - once by client mTLS and again by SSH tunnels -- **Proxy acts as a relay**: The proxy 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 +- **Relay only routes traffic**: The relay server only routes the doubly-encrypted traffic without access to either encryption layer +- **No data storage**: Relay servers do not store any traffic or sensitive information - **Certificate isolation**: Each connection uses unique certificates, ensuring complete tenant isolation -The 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. diff --git a/docs/documentation/platform/gateways/overview.mdx b/docs/documentation/platform/gateways/overview.mdx index 58701c41b2..35274fd8f2 100644 --- a/docs/documentation/platform/gateways/overview.mdx +++ b/docs/documentation/platform/gateways/overview.mdx @@ -11,7 +11,7 @@ The Infisical Gateway provides secure access to private resources within your ne **Architecture Components:** - **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. @@ -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: -1. **Gateway Registration**: The gateway establishes an outbound SSH reverse tunnel to a proxy 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 +1. **Gateway Registration**: The gateway establishes an outbound SSH reverse tunnel to a relay server using SSH certificates issued by Infisical +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 **Key Benefits:** @@ -39,18 +39,18 @@ The Gateway system uses SSH reverse tunnels for secure, firewall-friendly connec ## 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. For detailed installation instructions, refer to the Infisical [CLI Installation instructions](/cli/overview). **Prerequisites:** -1. **Proxy Server**: Before deploying gateways, you need a running proxy server: - - **Infisical Cloud**: Instance proxies are already available - no setup needed - - **Self-hosted**: Instance admin must set up shared instance proxies, or organizations can deploy their own +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 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 @@ -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 have two options for proxy infrastructure: + + You have two options for relay infrastructure: - - **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 - # Instance admin sets up shared proxy (one-time setup) - export INFISICAL_PROXY_AUTH_SECRET= - infisical network proxy --type=instance --ip= --name= + # Instance admin sets up shared relay (one-time setup) + export INFISICAL_RELAY_AUTH_SECRET= + infisical relay start --type=instance --ip= --name= ``` - - **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 - # Deploy organization-specific proxy - infisical network proxy --type=org --ip= --name= --auth-method=universal-auth --client-id= --client-secret= + # Deploy organization-specific relay + infisical relay start --type=org --ip= --name= --auth-method=universal-auth --client-id= --client-secret= ``` **When to choose this:** @@ -103,7 +103,7 @@ Once authenticated, the Gateway establishes an SSH reverse tunnel to the specifi For production deployments on Linux, install the Gateway as a systemd service: ```bash - sudo infisical network gateway install --token --domain --name --proxy-name + sudo infisical gateway systemd install --token --domain --name --relay sudo systemctl start infisical-gateway ``` 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_UNIVERSAL_AUTH_CLIENT_ID= \ --from-literal=INFISICAL_UNIVERSAL_AUTH_CLIENT_SECRET= \ - --from-literal=INFISICAL_PROXY_NAME= \ + --from-literal=INFISICAL_RELAY_NAME= \ --from-literal=INFISICAL_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: - - The name of the proxy server that this gateway should connect to. + + The name of the relay server that this gateway should connect to. 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_UNIVERSAL_AUTH_CLIENT_ID= \ --from-literal=INFISICAL_UNIVERSAL_AUTH_CLIENT_SECRET= \ - --from-literal=INFISICAL_PROXY_NAME= \ + --from-literal=INFISICAL_RELAY_NAME= \ --from-literal=INFISICAL_GATEWAY_NAME= ``` @@ -388,8 +388,8 @@ Once authenticated, the Gateway establishes an SSH reverse tunnel to the specifi INF Starting gateway INF Starting gateway certificate renewal goroutine INF Successfully registered gateway and received certificates - INF Connecting to proxy server infisical-start on 152.42.218.156:2222... - INF Proxy connection established for gateway + INF Connecting to relay server infisical-start on 152.42.218.156:2222... + INF Relay connection established for gateway ``` @@ -397,29 +397,29 @@ Once authenticated, the Gateway establishes an SSH reverse tunnel to the specifi 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 network gateway --token $(infisical login --method=universal-auth --client-id=<> --client-secret=<> --plain) --proxy-name= --name= + infisical gateway start --token $(infisical login --method=universal-auth --client-id=<> --client-secret=<> --plain) --relay= --name= ``` Alternatively, if you already have the token, use it directly with the `--token` flag: ```bash - infisical network gateway --token --proxy-name= --name= + infisical gateway start --token --relay= --name= ``` Or set it as an environment variable: ```bash export INFISICAL_TOKEN= - infisical network gateway --proxy-name= --name= + infisical gateway start --relay= --name= ``` - 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). **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 proxy server (outbound connection only) - - Replace `` with the name of your proxy server and `` with a unique name for this gateway + - The gateway must be able to reach the relay server (outbound connection only) + - Replace `` with the name of your relay server and `` with a unique name for this gateway diff --git a/docs/images/platform/gateways/gateway-highlevel-diagram.png b/docs/images/platform/gateways/gateway-highlevel-diagram.png index 0555cfadd4..5f942bcf0c 100644 Binary files a/docs/images/platform/gateways/gateway-highlevel-diagram.png and b/docs/images/platform/gateways/gateway-highlevel-diagram.png differ diff --git a/helm-charts/infisical-gateway/templates/deployment.yaml b/helm-charts/infisical-gateway/templates/deployment.yaml index f55684f3ba..d31a9c9e94 100644 --- a/helm-charts/infisical-gateway/templates/deployment.yaml +++ b/helm-charts/infisical-gateway/templates/deployment.yaml @@ -38,8 +38,8 @@ spec: image: "infisical/cli:{{ .Values.image.tag | default .Chart.AppVersion }}" imagePullPolicy: {{ .Values.image.pullPolicy }} args: - - network - gateway + - start envFrom: - secretRef: name: {{ .Values.secret.name }}