From feabdbf55925cc725482197c0a6660e7f424cc4a Mon Sep 17 00:00:00 2001 From: x032205 Date: Wed, 5 Nov 2025 15:49:55 -0500 Subject: [PATCH] docs: make --relay flag optional --- docs/cli/commands/gateway.mdx | 66 ++++++++++++------- .../platform/gateways/gateway-deployment.mdx | 17 +++-- 2 files changed, 57 insertions(+), 26 deletions(-) diff --git a/docs/cli/commands/gateway.mdx b/docs/cli/commands/gateway.mdx index 59202e46e..d7e9bb768 100644 --- a/docs/cli/commands/gateway.mdx +++ b/docs/cli/commands/gateway.mdx @@ -6,12 +6,12 @@ description: "Run the Infisical gateway or manage its systemd service" ```bash - infisical gateway start --name= --relay= --auth-method= + infisical gateway start --name= --auth-method= ``` ```bash - sudo infisical gateway systemd install --token= --domain= --name= --relay= + sudo infisical gateway systemd install --token= --domain= --name= ``` @@ -33,22 +33,27 @@ If you are moving from Gateway v1 to Gateway v2, this is NOT a drop-in switch. G - Run the Infisical gateway component within your the network where your target resources are located. The gateway establishes an SSH reverse tunnel to the specified relay server and provides secure access to private resources within your network. + Run the Infisical gateway component within your the network where your target resources are located. The gateway establishes an SSH reverse tunnel to a relay server and provides secure access to private resources within your network. ```bash -infisical gateway start --relay= --name= --auth-method= +infisical gateway start --name= --auth-method= ``` + + By default, the gateway automatically connects to the relay with the lowest latency. To target a specific relay, use the `--relay=` flag. + + Once started, the gateway component will: -- Establish outbound SSH reverse tunnels to relay servers (no inbound firewall rules needed) +- Automatically connect to a healthy relay with the lowest latency (unless the `--relay` flag is specified) +- Establish outbound SSH reverse tunnel to relay server (no inbound firewall rules needed) - Authenticate using SSH certificates issued by Infisical - Automatically reconnect if the connection is lost - Provide access to private resources within your network ### Authentication -The Relay supports multiple authentication methods. Below are the available authentication methods, with their respective flags. +The gateway supports multiple authentication methods. Below are the available authentication methods, with their respective flags. @@ -69,7 +74,7 @@ The Relay supports multiple authentication methods. Below are the available auth ```bash - infisical gateway start --auth-method=universal-auth --client-id= --client-secret= --relay= --name= + infisical gateway start --auth-method=universal-auth --client-id= --client-secret= --name= ``` @@ -93,7 +98,7 @@ The Relay supports multiple authentication methods. Below are the available auth ```bash - infisical gateway start --auth-method=kubernetes --machine-identity-id= --relay= --name= + infisical gateway start --auth-method=kubernetes --machine-identity-id= --name= ``` @@ -114,7 +119,7 @@ The Relay supports multiple authentication methods. Below are the available auth ```bash - infisical gateway start --auth-method=azure --machine-identity-id= --relay= --name= + infisical gateway start --auth-method=azure --machine-identity-id= --name= ``` @@ -135,7 +140,7 @@ The Relay supports multiple authentication methods. Below are the available auth ```bash - infisical gateway start --auth-method=gcp-id-token --machine-identity-id= --relay= --name= + infisical gateway start --auth-method=gcp-id-token --machine-identity-id= --name= ``` @@ -157,7 +162,7 @@ The Relay supports multiple authentication methods. Below are the available auth ```bash - infisical gateway start --auth-method=gcp-iam --machine-identity-id= --service-account-key-file-path= --relay= --name= + infisical gateway start --auth-method=gcp-iam --machine-identity-id= --service-account-key-file-path= --name= ``` @@ -176,7 +181,7 @@ The Relay supports multiple authentication methods. Below are the available auth ```bash - infisical gateway start --auth-method=aws-iam --machine-identity-id= --relay= --name= + infisical gateway start --auth-method=aws-iam --machine-identity-id= --name= ``` @@ -198,7 +203,7 @@ The Relay supports multiple authentication methods. Below are the available auth ```bash - infisical gateway start --auth-method=oidc-auth --machine-identity-id= --jwt= --relay= --name= + infisical gateway start --auth-method=oidc-auth --machine-identity-id= --jwt= --name= ``` @@ -222,7 +227,7 @@ The Relay supports multiple authentication methods. Below are the available auth ```bash - infisical gateway start --auth-method=jwt-auth --jwt= --machine-identity-id= --relay= --name= + infisical gateway start --auth-method=jwt-auth --jwt= --machine-identity-id= --name= ``` @@ -238,7 +243,7 @@ The Relay supports multiple authentication methods. Below are the available auth ```bash - infisical gateway start --token= --relay= --name= + infisical gateway start --token= --name= ``` @@ -250,6 +255,8 @@ The Relay supports multiple authentication methods. Below are the available auth The name of the relay that this gateway should connect to. The relay must be running and registered before starting the gateway. + If this flag is omitted, the gateway will automatically connect to a healthy relay with the lowest latency. + ```bash # Example infisical gateway start --relay=my-relay --name=my-gateway --token= @@ -264,7 +271,7 @@ The Relay supports multiple authentication methods. Below are the available auth ```bash # Example - infisical gateway start --name=my-gateway --relay=my-relay --token= + infisical gateway start --name=my-gateway --token= ``` @@ -274,7 +281,7 @@ The Relay supports multiple authentication methods. Below are the available auth ```bash # Example - infisical gateway start --domain=https://app.your-domain.com --relay= --name= + infisical gateway start --domain=https://app.your-domain.com --name= ``` @@ -285,7 +292,7 @@ The Relay supports multiple authentication methods. Below are the available auth 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= +sudo infisical gateway systemd install --token= --domain= --name= ``` ### Requirements @@ -302,7 +309,7 @@ sudo infisical gateway systemd install --token= --domain= --name= ```bash # Example - sudo infisical gateway systemd install --token= --name= --relay= + sudo infisical gateway systemd install --token= --name= ``` You may also expose the token to the CLI by setting the environment variable `INFISICAL_TOKEN` before executing the install command. @@ -314,7 +321,7 @@ sudo infisical gateway systemd install --token= --domain= --name= ```bash # Example - sudo infisical gateway systemd install --domain=https://app.your-domain.com --name= --relay= + sudo infisical gateway systemd install --domain=https://app.your-domain.com --name= ``` @@ -324,19 +331,23 @@ sudo infisical gateway systemd install --token= --domain= --name= ```bash # Example - sudo infisical gateway systemd install --name=my-gateway --token= --relay= + sudo infisical gateway systemd install --name=my-gateway --token= ``` - The name of the relay that this gateway should connect to. + The name of the relay that this gateway should connect to. The relay must be running and registered before starting the gateway. + + If this flag is omitted, the gateway will automatically connect to a healthy relay with the lowest latency. ```bash # Example sudo infisical gateway systemd install --relay=my-relay --token= --name= ``` + **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. + @@ -671,3 +682,14 @@ sudo systemctl disable infisical-gateway # Disable auto-start on boot + +## Frequently Asked Questions + + + + If the `--relay` flag is omitted, the gateway automatically selects the optimal relay. It first checks for healthy organization relays and connects to the one with the lowest latency. If no organization relays are available, it then performs the same latency-based selection among the available platform relays. + + + No. The first time the gateway starts, it selects the optimal relay (based on latency) and caches that selection. On subsequent restarts, it will prioritize connecting to the cached relay. If it's unable to connect, it will then re-evaluate and connect to the next most optimal relay available. + + diff --git a/docs/documentation/platform/gateways/gateway-deployment.mdx b/docs/documentation/platform/gateways/gateway-deployment.mdx index 9a5b7d816..5c25914c0 100644 --- a/docs/documentation/platform/gateways/gateway-deployment.mdx +++ b/docs/documentation/platform/gateways/gateway-deployment.mdx @@ -122,11 +122,13 @@ To successfully deploy an Infisical Gateway for use, follow these steps in order For production deployments on Linux servers, install the Gateway as a systemd service so that it runs securely in the background and automatically restarts on failure or system reboot: ```bash - sudo infisical gateway systemd install --token --domain --name --relay + sudo infisical gateway systemd install --token --domain --name sudo systemctl start infisical-gateway ``` - + + By default, the gateway connects to the most optimal relay. Use the `--relay` flag to manually specify a different relay server. + The systemd install command requires a Linux operating system with root/sudo @@ -153,10 +155,13 @@ To successfully deploy an Infisical Gateway for use, follow these steps in order --from-literal=INFISICAL_AUTH_METHOD=universal-auth \ --from-literal=INFISICAL_UNIVERSAL_AUTH_CLIENT_ID= \ --from-literal=INFISICAL_UNIVERSAL_AUTH_CLIENT_SECRET= \ - --from-literal=INFISICAL_RELAY_NAME= \ --from-literal=INFISICAL_GATEWAY_NAME= ``` + + By default, the gateway connects to the most optimal relay. Use the `--from-literal=INFISICAL_RELAY_NAME=` flag to manually specify a different relay server. + + #### Install the Gateway ```bash @@ -168,8 +173,12 @@ To successfully deploy an Infisical Gateway for use, follow these steps in order For development or testing environments: ```bash - infisical gateway start --token --relay= --name= + infisical gateway start --token --name= ``` + + + By default, the gateway connects to the most optimal relay. Use the `--relay` flag to manually specify a different relay server. +