Skip to content

Infisical is the open-source platform for securing secrets, certificates, access, and AI Agents.

docs(gateways): fix errors found rereading the direct listen pages

bernie-g88388f1f57d4
diff --git a/docs/cli/commands/gateway.mdx b/docs/cli/commands/gateway.mdx
index 79a9361d2a..20aafe06d1 100644
--- a/docs/cli/commands/gateway.mdx
+++ b/docs/cli/commands/gateway.mdx
@@ -46,7 +46,6 @@ The gateway name is provided as a positional argument.
Once started, the gateway component will:
- Authenticate using certificates issued by Infisical
-- Provide access to private resources within your network
- Automatically renew its certificates
In relay mode it also:
@@ -149,7 +148,7 @@ In direct listen mode it also:
For Infisical Cloud users on instance relays, the relay infrastructure is already running and managed by Infisical. If using organization relays or self-hosted instance relays, start a relay server first. See the [Relay Deployment Guide](/documentation/platform/gateways/relay-deployment).
<Note>
- This flag was previously named `--target-relay-name`, which still works but is deprecated. An Infisical CLI older than the release that added `--relay` accepts only the old name, so a deploy command copied from a newer UI fails on it with an unknown flag error. Upgrade the CLI on the host.
+ This flag was previously named `--target-relay-name`, which still works but is deprecated.
</Note>
</Accordion>
@@ -181,7 +180,7 @@ In direct listen mode it also:
<Accordion title="--bind">
The local `host:port` the gateway binds for direct connections. Defaults to every interface on the port from `--listen-address`, so you only need this flag when the address Infisical dials differs from the socket the gateway should open.
- Reach for it to bind a single interface, or to listen on a different local port than the one advertised, such as behind a load balancer that terminates on 8443 and forwards to 9000.
+ Use it to bind a single interface, or to listen on a different local port than the one advertised, such as behind a load balancer that terminates on 8443 and forwards to 9000.
```bash
# Advertise 8443, listen locally on 9000
@@ -371,9 +370,9 @@ The gateway name is provided as a positional argument.
Relay mode, with a relay chosen automatically. Direct listen is opt-in: the gateway only listens for connections when you pass `--listen-address`.
</Accordion>
<Accordion title="Do PAM sessions work in direct listen mode?">
- Browser-based sessions work in either mode, because the platform brokers the connection.
+ Browser-based sessions work in either mode, because the platform brokers the connection. `infisical pam access` connects from your own machine instead, so it needs to reach the gateway's registered address.
- `infisical pam access` connects to the gateway from your own machine instead, so it needs to reach the gateway's registered address. From a laptop outside the gateway's network that means a VPN into the network, or a relay running on the gateway alongside direct listen.
+ See [Gateway deployment](/documentation/platform/gateways/gateway-deployment#frequently-asked-questions) for what to give users outside the network.
</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.
diff --git a/docs/documentation/platform/gateways/gateway-deployment.mdx b/docs/documentation/platform/gateways/gateway-deployment.mdx
index 212f48dca0..2e404f5fc7 100644
--- a/docs/documentation/platform/gateways/gateway-deployment.mdx
+++ b/docs/documentation/platform/gateways/gateway-deployment.mdx
@@ -3,7 +3,7 @@ title: "Gateway deployment"
description: "Complete guide to deploying Infisical Gateways including network configuration and firewall requirements"
---
-Infisical Gateways give the platform access to resources in your private network, such as databases and internal APIs, without handing out their credentials.
+Infisical Gateways run inside your network and let Infisical reach systems that aren't exposed to the internet, such as a database in a private subnet or an internal API.
This guide covers everything you need to deploy and configure Infisical Gateways.
<Tip>
@@ -53,7 +53,7 @@ For the ports, certificates, and traffic flow behind each mode, see [Network arc
- **Token** (default): a one-time enrollment token (1h expiry) bootstraps the gateway.
- **AWS**: the gateway authenticates by signing an `sts:GetCallerIdentity` request with whatever AWS credentials it can resolve on the host (instance role, env vars, shared profile). Configure the allowed principal ARNs and/or account IDs that match your hosts.
- **Kubernetes**: the gateway authenticates with the projected service account token of the pod it runs in, so no credential has to be distributed to the cluster. Configure the cluster's API server URL and the allowed namespaces and/or service account names.
- 5. Select **Show deploy command** in the **Deployment** card.
+ 5. In the **Deployment** card, select **Generate deploy command**. For the AWS and Kubernetes methods the command is shown without this step.
6. Under **Connection Mode**, select **Direct Listen** or **Relay**.
- For **Direct Listen**, enter the **Listen Address** that Infisical will dial, as `host:port`.
- For **Relay**, pick a relay, or leave **Auto Select Relay** so the gateway chooses the healthiest one.
@@ -122,7 +122,6 @@ For the ports, certificates, and traffic flow behind each mode, see [Network arc
helm install infisical-gateway infisical/infisical-gateway \
--set gateway.name=my-gateway \
--set gateway.listenAddress=infisical-gateway.default.svc.cluster.local:8443 \
- --set service.port=8443 \
--set gateway.enrollment.method=token \
--set gateway.enrollment.token.existingSecretRef=gateway-enrollment-token \
--set gateway.domain=<your-infisical-domain>
@@ -314,7 +313,7 @@ For the ports, certificates, and traffic flow behind each mode, see [Network arc
</Warning>
<Info>
- Token-method enrollment tokens are single-use and expire after 1 hour. If the token expires before deployment, select **Show deploy command** again on the detail page to generate a new one.
+ Token-method enrollment tokens are single-use and expire after 1 hour. If the token expires before deployment, select **Generate deploy command** again on the detail page to generate a new one.
</Info>
<Info>
@@ -333,12 +332,12 @@ For the ports, certificates, and traffic flow behind each mode, see [Network arc
From the gateway's detail page (select the gateway row in the list):
-- **Show deploy command**: Generates a fresh enrollment token (token method) or re-displays the start command for the AWS and Kubernetes methods. Selecting this on a token-method gateway doesn't disconnect the running gateway; the next login with the new token rotates credentials atomically.
+- **Generate deploy command**: Generates a fresh enrollment token (token method) or re-displays the start command for the AWS and Kubernetes methods. Selecting this on a token-method gateway doesn't disconnect the running gateway; the next login with the new token rotates credentials atomically.
- **Edit auth method**: Switch between Token, AWS, and Kubernetes, or update the allowlists of the current method. Existing gateways keep their JWT until they restart and re-authenticate.
- **Options → Revoke Access** — Disconnects the running gateway and invalidates outstanding enrollment tokens. The gateway must re-authenticate to reconnect. Gated by the dedicated `revoke-gateway-access` permission, separate from `edit-gateways`.
- **Options → Delete Gateway** — Permanently removes the gateway.
-To migrate a gateway to a different host with zero downtime: select **Show deploy command** to generate a fresh token, run it on the new host, and the new login will rotate credentials away from the old host.
+To migrate a gateway to a different host with zero downtime: select **Generate deploy command** to generate a fresh token, run it on the new host, and the new login will rotate credentials away from the old host.
## Frequently asked questions
@@ -357,7 +356,7 @@ In direct listen mode, one inbound port has to be open: the port in your listen
</Accordion>
<Accordion title="Can I switch a gateway between relay and direct listen?">
-Yes. Open the gateway's detail page, select **Show deploy command**, choose the mode you want, and re-run the generated command on the host. The gateway re-registers with the new mode and is issued the certificate it needs for it.
+Yes. Open the gateway's detail page, choose the mode you want under **Connection Mode**, and re-run the generated command on the host. The gateway re-registers with the new mode and is issued the certificate it needs for it.
Switching away from a mode drops it. To keep both, pass `--relay` and `--listen-address` together.
@@ -370,7 +369,7 @@ Direct listen is also unavailable on Infisical Cloud, which runs outside your ne
</Accordion>
-<Accordion title="Do PAM CLI sessions work with direct listen?">
+<Accordion title="Do PAM sessions work in direct listen mode?">
Only from a machine that can reach the gateway's registered address. The CLI connects to the gateway from the user's own machine rather than through Infisical, so a laptop outside the network can't reach a gateway listening on an internal address. Give those users a VPN into the network, or run a relay on the gateway alongside direct listen.
Browser-based PAM access works in either mode, because the platform brokers that connection.
@@ -419,7 +418,7 @@ If the gateway binds a different local port than the one you advertise, such as
</Accordion>
<Accordion title="How do I troubleshoot authentication failures?">
-For token method: ensure the enrollment token hasn't expired or already been used. Open the gateway's detail page and select **Show deploy command** to generate a fresh token.
+For token method: ensure the enrollment token hasn't expired or already been used. Open the gateway's detail page and select **Generate deploy command** to generate a fresh token.
For AWS method: ensure the host has AWS credentials available (instance role, env vars, or shared profile) and the resolved principal/account is in the allowlist on the gateway's detail page.
@@ -437,7 +436,7 @@ Check gateway logs for detailed error information:
</Accordion>
<Accordion title="What happens if my enrollment token expires?">
-Enrollment tokens expire after 1 hour. If the token expires before deployment, open the gateway's detail page and select **Show deploy command** to generate a new one.
+Enrollment tokens expire after 1 hour. If the token expires before deployment, open the gateway's detail page and select **Generate deploy command** to generate a new one.
</Accordion>
<Accordion title="Where are gateway credentials stored?">
diff --git a/docs/documentation/platform/gateways/network-architecture.mdx b/docs/documentation/platform/gateways/network-architecture.mdx
index e3a2b80efb..83986a00f8 100644
--- a/docs/documentation/platform/gateways/network-architecture.mdx
+++ b/docs/documentation/platform/gateways/network-architecture.mdx
@@ -4,7 +4,7 @@ sidebarTitle: "Network architecture"
description: "Ports, egress requirements, and the two ways the Gateway and Infisical connect"
---
-The Gateway is deployed inside your private network, alongside the resources it protects. Infisical never touches those resources directly. It sends every request through the Gateway, which forwards it to the database or internal API on the other side.
+The Gateway is deployed inside your private network, alongside the resources Infisical needs to reach. Infisical never touches those resources directly. It sends every request through the Gateway, which forwards it to the database or internal API on the other side.
There are two ways the Gateway and Infisical reach each other, and they differ in one thing: which side opens the connection.
@@ -66,7 +66,7 @@ flowchart LR
end
PLAT["Infisical Platform"]
GW -->|"TCP 443 · HTTPS"| PLAT
- PLAT -->|"TCP 8443 · mTLS"| GW
+ PLAT -->|"listen address · mTLS"| GW
```
| Connection | Source | Destination | Port | Protocol | Purpose |
@@ -123,10 +123,10 @@ If you run a self-hosted relay, that host needs:
Use relay mode when the Gateway sits behind NAT or a firewall you can't open, when you're on Infisical Cloud, or when PAM CLI users connect from outside the Gateway's network. See [Gateway deployment](/documentation/platform/gateways/gateway-deployment) for the full comparison.
</Accordion>
- <Accordion title="Do PAM CLI sessions work in direct listen mode?">
- Only from a machine that can reach the Gateway's registered address. The CLI opens its own connection to the Gateway rather than going through Infisical, so a user on a laptop outside the network can't reach a Gateway that only listens on an internal address. Those users need a VPN into the network, or a relay on the Gateway.
+ <Accordion title="Do PAM sessions work in direct listen mode?">
+ Browser-based access is unaffected, because the platform brokers that connection. `infisical pam access` opens its own connection to the Gateway, so it works only from a machine that can reach the registered address.
- Browser-based PAM access is unaffected, because the platform brokers that connection.
+ See [Gateway deployment](/documentation/platform/gateways/gateway-deployment#frequently-asked-questions) for what to give users outside the network.
</Accordion>
<Accordion title="Does the Gateway only proxy raw TCP?">
diff --git a/docs/documentation/platform/gateways/relay-deployment/overview.mdx b/docs/documentation/platform/gateways/relay-deployment/overview.mdx
index d4bf96ccfa..0b9e07a764 100644
--- a/docs/documentation/platform/gateways/relay-deployment/overview.mdx
+++ b/docs/documentation/platform/gateways/relay-deployment/overview.mdx
@@ -19,7 +19,7 @@ A relay is what you need when:
- You're on Infisical Cloud, which runs outside your network and has no route into it, so a gateway there can't be dialed and has to open the connection itself
- PAM CLI users connect from outside the gateway's network, since the CLI dials the gateway from their own machine
-A gateway can also run both, giving you direct connections for platform operations and a relay for CLI users outside the network.
+A gateway can also run both, which is mainly how you switch an existing gateway between modes without an outage. See [Running both modes](/documentation/platform/gateways/network-architecture#running-both-modes).
## Do you need to deploy your own relay?