misc: addressed comments

2026-09-22 13:39:35 +00:00 · 2025-09-11 00:45:27 +08:00
parent 1dcdb90c62
commit 71ff01daf2
9 changed files with 105 additions and 38 deletions
--- a/docs/cli/commands/gateway.mdx
+++ b/docs/cli/commands/gateway.mdx
@@ -22,6 +22,13 @@ The Infisical gateway provides secure access to private resources using modern T

 The gateway system uses SSH reverse tunnels over TCP, eliminating firewall complexity and providing excellent performance for enterprise environments.

+<Warning>
+**Deprecation and Migration Notice:** The legacy `infisical gateway` command (v1) will be removed in a future release. Please migrate to `infisical gateway start` (Gateway v2).
+
+If you are moving from Gateway v1 to Gateway v2, this is NOT a drop-in switch. Gateway v2 creates new gateway instances with new gateway IDs. You must update any existing resources that reference gateway IDs (for example: dynamic secret configs, app connections, or other gateway-bound resources) to point to the new Gateway v2 gateway ID. Until you update those references, traffic will continue to target the old v1 gateway.
+
+</Warning>
+
 ## Subcommands & flags

 <Accordion title="infisical gateway start" defaultOpen="true">
@@ -361,6 +368,9 @@ sudo systemctl disable infisical-gateway  # Disable auto-start on boot
  **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.
+
+**Migration required:** If you are currently using Gateway v1 (via `infisical gateway`), moving to Gateway v2 is not in-place. Gateway v2 provisions new gateway instances with new gateway IDs. Update any resources that reference a gateway ID (for example: dynamic secret configs, app connections, or other gateway-bound resources) to use the new Gateway v2 gateway ID. Until you update those references, traffic will continue to target the old v1 gateway.
+
  </Warning>

 Run the legacy Infisical gateway in the foreground. The gateway will connect to the relay service and maintain a persistent connection.
@@ -585,6 +595,9 @@ The Infisical CLI supports multiple authentication methods. Below are the availa
  **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.
+
+**Migration required:** If you previously installed Gateway v1 via `infisical gateway install`, moving to Gateway v2 is not in-place. Gateway v2 provisions new gateway instances with new gateway IDs. Update any resources that reference a gateway ID (for example: dynamic secret configs, app connections, or other gateway-bound resources) to use the new Gateway v2 gateway ID. Until you update those references, traffic will continue to target the old v1 gateway.
+
  </Warning>

 Install and enable the legacy gateway as a systemd service. This command must be run with sudo on Linux.
--- a/docs/cli/commands/relay.mdx
+++ b/docs/cli/commands/relay.mdx
@@ -1,6 +1,6 @@
 ---
 title: "infisical relay"
-description: "Relay-related commands for Infisical including proxy components"
+description: "Relay-related commands for Infisical"
 ---

 <Tabs>
@@ -33,7 +33,7 @@ infisical relay start --type=<type> --host=<host> --name=<name> --auth-method=<a
  <Accordion title="--type">
    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.
+    - **`instance`**: Shared relay server that can be used by all organizations on your Infisical instance. Set up by the instance administrator. Uses `INFISICAL_RELAY_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
@@ -41,7 +41,7 @@ infisical relay start --type=<type> --host=<host> --name=<name> --auth-method=<a
    infisical relay start --type=org --host=192.168.1.100 --name=my-org-relay

    # Instance relay (configured by instance admin)
-    INFISICAL_PROXY_AUTH_SECRET=<secret> infisical relay start --type=instance --host=10.0.1.50 --name=shared-relay
+    INFISICAL_RELAY_AUTH_SECRET=<secret> infisical relay start --type=instance --host=10.0.1.50 --name=shared-relay
    ```

  </Accordion>
@@ -75,14 +75,14 @@ infisical relay start --type=<type> --host=<host> --name=<name> --auth-method=<a
 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.
+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_RELAY_AUTH_SECRET` environment variable.

 ```bash
 # Organization relay with Universal Auth (customer-deployed)
 infisical relay start --type=org --host=192.168.1.100 --name=my-org-relay --auth-method=universal-auth --client-id=<client-id> --client-secret=<client-secret>

 # Instance relay (configured by instance admin)
-INFISICAL_PROXY_AUTH_SECRET=<secret> infisical relay start --type=instance --host=10.0.1.50 --name=shared-relay
+INFISICAL_RELAY_AUTH_SECRET=<secret> infisical relay start --type=instance --host=10.0.1.50 --name=shared-relay
 ```

 ### Authentication Methods
--- a/docs/documentation/platform/gateways/gateway-security.mdx
+++ b/docs/documentation/platform/gateways/gateway-security.mdx
@@ -68,26 +68,35 @@ Gateway ↔ Relay Server communication uses SSH certificate authentication:
  - Gateway validates certificate against appropriate SSH Server CA
  - Ensures gateway connects to legitimate relay infrastructure

-### 3. Application Traffic Security
+### 3. Platform-to-Gateway Direct Connection

-End-to-end encryption for application data:
+The platform establishes secure direct connections with gateways through a **TLS-pinned tunnel** mechanism:

-1. **mTLS Layer**:
+1. **TLS-Pinned Tunnel Establishment**:

-   - Infisical platform establishes mTLS connections directly with gateways
-   - Uses Organization Gateway certificates for authentication
-   - Application traffic is encrypted end-to-end between platform and gateway
+   - Gateway initiates outbound connection to platform through SSH reverse tunnel
+   - Platform establishes direct mTLS connection with gateway using Organization Gateway certificates
+   - TLS certificate pinning ensures the connection is bound to the specific gateway identity
+   - No inbound connections required - all communication flows through the outbound tunnel

-2. **SSH Tunnel Layer**:
+2. **Connection Flow**:

-   - mTLS-encrypted application traffic travels through SSH reverse tunnels
-   - Creates double encryption: mTLS payload within SSH tunnel
-   - Relay servers cannot decrypt either encryption layer
+   ```
+   Platform ←→ [SSH Reverse Tunnel] ←→ Gateway
+   ```

-3. **Traffic Isolation**:
-   - Each gateway maintains separate SSH tunnels
-   - Organization's private keys never leave their environment
-   - Complete cryptographic isolation between organizations
+   - Gateway maintains persistent outbound SSH tunnel to relay server
+   - Platform connects directly to gateway through this tunnel
+   - TLS handshake occurs over the SSH tunnel, establishing mTLS connection
+   - Application traffic flows through the TLS-pinned tunnel
+
+3. **Security Benefits**:
+
+   - **No inbound connections**: Gateway never needs to accept incoming connections
+   - **Certificate-based authentication**: Uses Organization Gateway certificates for mutual TLS
+   - **Double encryption**: TLS traffic within SSH tunnel provides layered security
+   - **Relay server isolation**: Relay cannot decrypt either TLS or application data
+   - **Tenant isolation**: Each organization's traffic flows through separate authenticated channels

 ## Tenant Isolation

--- a/docs/documentation/platform/gateways/overview.mdx
+++ b/docs/documentation/platform/gateways/overview.mdx
@@ -102,6 +102,13 @@ Once authenticated, the Gateway establishes an SSH reverse tunnel to the specifi
    <Tabs>
      <Tab title="Production (systemd)">
        For production deployments on Linux, install the Gateway as a systemd service:
+
+        <Warning>
+          **Gateway v2:** The `infisical gateway systemd install` command deploys the new Gateway v2 component.
+
+          If you are migrating from Gateway v1 (legacy `infisical gateway install` command), this is not in-place. Gateway v2 provisions new gateway instances with new gateway IDs. Update any resources that reference a gateway ID (for example: dynamic secret configs, app connections, or other gateway-bound resources) to use the new Gateway v2 gateway ID.
+        </Warning>
+
        ```bash
        sudo infisical gateway systemd install --token <your-machine-identity-token> --domain <your-infisical-domain> --name <gateway-name> --relay <relay-name>
        sudo systemctl start infisical-gateway
@@ -369,8 +376,13 @@ Once authenticated, the Gateway establishes an SSH reverse tunnel to the specifi
          </Accordion>
        </AccordionGroup>

-
        ### Install the Infisical Gateway Helm Chart
+        <Warning>
+          **Version mapping:** Helm chart versions `>= 1.0.0` contain the new Gateway v2 component. Helm chart versions `<= 0.0.5` contain the legacy Gateway v1 component.
+
+          If you are moving from Gateway v1 (chart `<= 0.0.5`) to Gateway v2 (chart `>= 1.0.0`), this is not in-place. Gateway v2 provisions new gateway instances with new gateway IDs. Update any resources that reference a gateway ID (for example: dynamic secret configs, app connections, or other gateway-bound resources) to use the new Gateway v2 gateway ID.
+        </Warning>
+
        ```bash
        helm install infisical-gateway infisical-helm-charts/infisical-gateway
        ```
@@ -385,11 +397,17 @@ Once authenticated, the Gateway establishes an SSH reverse tunnel to the specifi
        You should see the following output which indicates the gateway is running as expected.
        ```bash
        $ kubectl logs deployment/infisical-gateway
-        INF Starting gateway
-        INF Starting gateway certificate renewal goroutine
-        INF Successfully registered gateway and received certificates
-        INF Connecting to relay server infisical-start on 152.42.218.156:2222...
-        INF Relay connection established for gateway
+        12:43AM INF Starting gateway
+        12:43AM INF Starting gateway certificate renewal goroutine
+        12:43AM INF Successfully registered gateway and received certificates
+        12:43AM INF Connecting to relay server infisical-start on 152.42.218.156:2222...
+        12:43AM INF Relay connection established for gateway
+        12:43AM INF Received incoming connection, starting TLS handshake
+        12:43AM INF TLS handshake completed successfully
+        12:43AM INF Negotiated ALPN protocol: infisical-ping
+        12:43AM INF Starting ping handler
+        12:43AM INF Ping handler completed
+        12:43AM INF Gateway is reachable by Infisical
        ```

      </Tab>