awatertrevi/infisical
1
0
Fork 0
mirror of https://github.com/awatertrevi/infisical.git synced 2026-09-22 13:39:35 +00:00
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #4818 from Infisical/PLATFRM-4

Browse Source 
make --relay flag optional & add sudo to gateway start examples
This commit is contained in:
Andre
2025-11-10 14:16:01 -05:00
committed by GitHub
parent cc23f4c54c 2f9007d36f
commit 821ab27273
4 changed files with 77 additions and 35 deletions
Download Patch File Download Diff File Expand all files Collapse all files

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

@@ -6,12 +6,12 @@ description: "Run the Infisical gateway or manage its systemd service"
<Tabs>
<Tab title="Start gateway">
```bash
infisical gateway start --name=<name> --relay=<relay-name> --auth-method=<auth-method>
sudo infisical gateway start --name=<name> --auth-method=<auth-method>
```
</Tab>
<Tab title="Start gateway as background daemon (Linux only)">
```bash
sudo infisical gateway systemd install --token=<token> --domain=<domain> --name=<name> --relay=<relay-name>
sudo infisical gateway systemd install --token=<token> --domain=<domain> --name=<name>
```
</Tab>
</Tabs>
@@ -33,22 +33,27 @@ If you are moving from Gateway v1 to Gateway v2, this is NOT a drop-in switch. G
<AccordionGroup>
<Accordion title="infisical gateway start" defaultOpen="true">
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=<relay-name> --name=<name> --auth-method=<auth-method>
sudo infisical gateway start --name=<name> --auth-method=<auth-method>
```
<Info>
By default, the gateway automatically connects to the relay with the lowest latency. To target a specific relay, use the `--relay=<relay-name>` flag.
</Info>
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.
<AccordionGroup>
<Accordion title="Universal Auth">
@@ -69,7 +74,7 @@ The Relay supports multiple authentication methods. Below are the available auth
</ParamField>
```bash
infisical gateway start --auth-method=universal-auth --client-id=<client-id> --client-secret=<client-secret> --relay=<relay-name> --name=<name>
sudo infisical gateway start --auth-method=universal-auth --client-id=<client-id> --client-secret=<client-secret> --name=<name>
```
</Accordion>
@@ -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=<machine-identity-id> --relay=<relay-name> --name=<name>
sudo infisical gateway start --auth-method=kubernetes --machine-identity-id=<machine-identity-id> --name=<name>
```
</Accordion>
@@ -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=<machine-identity-id> --relay=<relay-name> --name=<name>
sudo infisical gateway start --auth-method=azure --machine-identity-id=<machine-identity-id> --name=<name>
```
</Accordion>
@@ -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=<machine-identity-id> --relay=<relay-name> --name=<name>
sudo infisical gateway start --auth-method=gcp-id-token --machine-identity-id=<machine-identity-id> --name=<name>
```
</Accordion>
@@ -157,7 +162,7 @@ The Relay supports multiple authentication methods. Below are the available auth
</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>
sudo infisical gateway start --auth-method=gcp-iam --machine-identity-id=<machine-identity-id> --service-account-key-file-path=<service-account-key-file-path> --name=<name>
```
</Accordion>
@@ -176,7 +181,7 @@ The Relay supports multiple authentication methods. Below are the available auth
</ParamField>
```bash
infisical gateway start --auth-method=aws-iam --machine-identity-id=<machine-identity-id> --relay=<relay-name> --name=<name>
sudo infisical gateway start --auth-method=aws-iam --machine-identity-id=<machine-identity-id> --name=<name>
```
</Accordion>
@@ -198,7 +203,7 @@ The Relay supports multiple authentication methods. Below are the available auth
</ParamField>
```bash
infisical gateway start --auth-method=oidc-auth --machine-identity-id=<machine-identity-id> --jwt=<oidc-jwt> --relay=<relay-name> --name=<name>
sudo infisical gateway start --auth-method=oidc-auth --machine-identity-id=<machine-identity-id> --jwt=<oidc-jwt> --name=<name>
```
</Accordion>
@@ -222,7 +227,7 @@ The Relay supports multiple authentication methods. Below are the available auth
```bash
infisical gateway start --auth-method=jwt-auth --jwt=<jwt> --machine-identity-id=<machine-identity-id> --relay=<relay-name> --name=<name>
sudo infisical gateway start --auth-method=jwt-auth --jwt=<jwt> --machine-identity-id=<machine-identity-id> --name=<name>
```
</Accordion>
@@ -238,7 +243,7 @@ The Relay supports multiple authentication methods. Below are the available auth
</ParamField>
```bash
infisical gateway start --token=<token> --relay=<relay-name> --name=<name>
sudo infisical gateway start --token=<token> --name=<name>
```
</Accordion>
@@ -250,12 +255,14 @@ The Relay supports multiple authentication methods. Below are the available auth
<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.
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=<token>
sudo 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.
**Note:** For Infisical Cloud users using instance relays, the relay infrastructure is already running and managed by Infisical. If using organization relays or self-hosted instance relays, you must first start a relay server. For more information on deploying relays, refer to the [Relay Deployment Guide](/documentation/platform/gateways/relay-deployment).
</Accordion>
@@ -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=<token>
sudo infisical gateway start --name=my-gateway --token=<token>
```
</Accordion>
@@ -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=<relay-name> --name=<name>
sudo infisical gateway start --domain=https://app.your-domain.com --name=<name>
```
</Accordion>
@@ -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=<token> --domain=<domain> --name=<name> --relay=<relay-name>
sudo infisical gateway systemd install --token=<token> --domain=<domain> --name=<name>
```
### Requirements
@@ -302,7 +309,7 @@ sudo infisical gateway systemd install --token=<token> --domain=<domain> --name=
```bash
# Example
sudo infisical gateway systemd install --token=<token> --name=<name> --relay=<relay-name>
sudo infisical gateway systemd install --token=<token> --name=<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=<token> --domain=<domain> --name=
```bash
# Example
sudo infisical gateway systemd install --domain=https://app.your-domain.com --name=<name> --relay=<relay-name>
sudo infisical gateway systemd install --domain=https://app.your-domain.com --name=<name>
```
</Accordion>
@@ -324,19 +331,23 @@ sudo infisical gateway systemd install --token=<token> --domain=<domain> --name=
```bash
# Example
sudo infisical gateway systemd install --name=my-gateway --token=<token> --relay=<relay-name>
sudo infisical gateway systemd install --name=my-gateway --token=<token>
```
</Accordion>
<Accordion title="--relay">
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=<token> --name=<name>
```
**Note:** For Infisical Cloud users using instance relays, the relay infrastructure is already running and managed by Infisical. If using organization relays or self-hosted instance relays, you must first start a relay server. For more information on deploying relays, refer to the [Relay Deployment Guide](/documentation/platform/gateways/relay-deployment).
</Accordion>
</AccordionGroup>
@@ -671,3 +682,14 @@ sudo systemctl disable infisical-gateway # Disable auto-start on boot
</Accordion>
</AccordionGroup>
## Frequently Asked Questions
<AccordionGroup>
<Accordion title="How are relays auto-selected?">
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 managed relays.
</Accordion>
<Accordion title="When restarting the gateway without a relay flag, does it select a new relay every time?">
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.
</Accordion>
</AccordionGroup>

17
docs/documentation/platform/gateways/gateway-deployment.mdx
View File

@@ -122,11 +122,13 @@ To successfully deploy an Infisical Gateway for use, follow these steps in order
<Tab title="Linux Server (Production)">
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 <your-machine-identity-token> --domain <your-infisical-domain> --name <gateway-name> --relay <relay-name>
sudo infisical gateway systemd install --token <your-machine-identity-token> --domain <your-infisical-domain> --name <gateway-name>
sudo systemctl start infisical-gateway
```
<Info>
By default, the gateway connects to the most optimal relay. Use the `--relay` flag to manually specify a different relay server.
</Info>
<Warning>
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=<client-id> \
--from-literal=INFISICAL_UNIVERSAL_AUTH_CLIENT_SECRET=<client-secret> \
--from-literal=INFISICAL_RELAY_NAME=<relay-name> \
--from-literal=INFISICAL_GATEWAY_NAME=<gateway-name>
```
<Info>
By default, the gateway connects to the most optimal relay. Use the `--from-literal=INFISICAL_RELAY_NAME=<relay-name>` flag to manually specify a different relay server.
</Info>
#### 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 <token> --relay=<relay-name> --name=<gateway-name>
sudo infisical gateway start --token <token> --name=<gateway-name>
```
<Info>
By default, the gateway connects to the most optimal relay. Use the `--relay` flag to manually specify a different relay server.
</Info>
</Tab>
</Tabs>
</Step>

11
frontend/src/pages/organization/NetworkingPage/components/GatewayTab/components/GatewayCliDeploymentMethod.tsx
View File

@@ -80,7 +80,7 @@ export const GatewayCliDeploymentMethod = () => {
const [relay, setRelay] = useState<null | {
id: string;
name: string;
}>(null);
}>({ id: "_auto", name: "Auto Select Relay" });
const [identity, setIdentity] = useState<null | {
id: string;
name: string;
@@ -183,9 +183,8 @@ export const GatewayCliDeploymentMethod = () => {
};
const command = useMemo(() => {
return `infisical gateway start --name=${name} --relay=${
relay?.name || ""
} --domain=${siteURL} --token=${identityToken}`;
const relayPart = relay?.id !== "_auto" ? ` --relay=${relay?.name || ""}` : "";
return `sudo infisical gateway start --name=${name}${relayPart} --domain=${siteURL} --token=${identityToken}`;
}, [name, relay, identityToken, siteURL]);
if (step === "command") {
@@ -256,6 +255,10 @@ export const GatewayCliDeploymentMethod = () => {
}}
isLoading={isRelaysLoading}
options={[
{
id: "_auto",
name: "Auto Select Relay"
},
{
id: "_create",
name: "Deploy New Relay"

14
frontend/src/pages/organization/NetworkingPage/components/GatewayTab/components/RelayOption.tsx
View File

@@ -1,6 +1,6 @@
import { components, OptionProps } from "react-select";
import { faCheckCircle } from "@fortawesome/free-regular-svg-icons";
import { faPlus } from "@fortawesome/free-solid-svg-icons";
import { faPlus, faWandMagicSparkles } from "@fortawesome/free-solid-svg-icons";
import { FontAwesomeIcon } from "@fortawesome/react-fontawesome";
export const RelayOption = ({
@@ -9,16 +9,24 @@ export const RelayOption = ({
...props
}: OptionProps<{ id: string; name: string }>) => {
const isCreateOption = props.data.id === "_create";
const isAutoOption = props.data.id === "_auto";
return (
<components.Option isSelected={isSelected} {...props}>
<div className="flex flex-row items-center justify-between">
{isCreateOption ? (
{isCreateOption && (
<div className="flex items-center gap-x-1 text-mineshaft-400">
<FontAwesomeIcon icon={faPlus} size="sm" />
<span className="mr-auto">Deploy New Relay</span>
</div>
) : (
)}
{isAutoOption && (
<div className="flex items-center gap-x-1 text-mineshaft-400">
<FontAwesomeIcon icon={faWandMagicSparkles} size="sm" />
<span className="mr-auto">Auto Select Relay</span>
</div>
)}
{!isCreateOption && !isAutoOption && (
<>
<p className="truncate">{children}</p>
{isSelected && (