From 0a9f51f62fb9351b0a1c778277653a0431b0d7a9 Mon Sep 17 00:00:00 2001 From: Sheen Capadngan Date: Thu, 4 Sep 2025 01:09:48 +0800 Subject: [PATCH] doc: cli docs for gateway v2 --- docs/cli/commands/gateway.mdx | 90 ++++--- docs/cli/commands/network.mdx | 441 ++++++++++++++++++++++++++++++++++ docs/docs.json | 34 ++- 3 files changed, 525 insertions(+), 40 deletions(-) create mode 100644 docs/cli/commands/network.mdx diff --git a/docs/cli/commands/gateway.mdx b/docs/cli/commands/gateway.mdx index a12493c58..0168c7a42 100644 --- a/docs/cli/commands/gateway.mdx +++ b/docs/cli/commands/gateway.mdx @@ -3,6 +3,22 @@ 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 @@ -25,13 +41,13 @@ Run the Infisical gateway in the foreground or manage its systemd service instal Run the Infisical gateway in the foreground. The gateway will connect to the relay service and maintain a persistent connection. - ```bash - infisical gateway --domain= --auth-method= - ``` +```bash +infisical gateway --domain= --auth-method= +``` - ### Authentication +### Authentication - The Infisical CLI supports multiple authentication methods. Below are the available authentication methods, with their respective flags. +The Infisical CLI supports multiple authentication methods. Below are the available authentication methods, with their respective flags. @@ -121,7 +137,6 @@ Run the Infisical gateway in the foreground or manage its systemd service instal infisical gateway --auth-method=gcp-id-token --machine-identity-id= ``` - The GCP IAM method is used to authenticate with Infisical with a GCP service account key. @@ -163,7 +178,6 @@ Run the Infisical gateway in the foreground or manage its systemd service instal infisical gateway --auth-method=aws-iam --machine-identity-id= ``` - The OIDC Auth method is used to authenticate with Infisical via identity tokens with OIDC. @@ -185,6 +199,7 @@ Run the Infisical gateway in the foreground or manage its systemd service instal ```bash infisical gateway --auth-method=oidc-auth --machine-identity-id= --jwt= ``` + @@ -208,6 +223,7 @@ Run the Infisical gateway in the foreground or manage its systemd service instal ```bash infisical gateway --auth-method=jwt-auth --jwt= --machine-identity-id= ``` + You can use the `INFISICAL_TOKEN` environment variable to authenticate with Infisical with a raw machine identity access token. @@ -227,7 +243,7 @@ Run the Infisical gateway in the foreground or manage its systemd service instal - ### Other Flags +### Other Flags Domain of your self-hosted Infisical instance. @@ -236,22 +252,24 @@ Run the Infisical gateway in the foreground or manage its systemd service instal # Example infisical gateway --domain=https://app.your-domain.com ``` + Install and enable the gateway as a systemd service. This command must be run with sudo on Linux. - ```bash - sudo infisical gateway install --token= --domain= - ``` +```bash +sudo infisical gateway install --token= --domain= +``` - ### Requirements - - Must be run on Linux - - Must be run with root/sudo privileges - - Requires systemd +### Requirements - ### Flags +- Must be run on Linux +- Must be run with root/sudo privileges +- Requires systemd + +### Flags The machine identity access token to authenticate with Infisical. @@ -262,6 +280,7 @@ Run the Infisical gateway in the foreground or manage its systemd service instal ``` You may also expose the token to the CLI by setting the environment variable `INFISICAL_TOKEN` before executing the install command. + @@ -271,24 +290,29 @@ Run the Infisical gateway in the foreground or manage its systemd service instal # Example sudo infisical gateway install --domain=https://app.your-domain.com ``` + - ### 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 +### 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 + +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 +``` - 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 - ``` diff --git a/docs/cli/commands/network.mdx b/docs/cli/commands/network.mdx new file mode 100644 index 000000000..4e4cdbfe3 --- /dev/null +++ b/docs/cli/commands/network.mdx @@ -0,0 +1,441 @@ +--- +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 through a three-tier proxy system: + +- **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/docs.json b/docs/docs.json index 08121fa08..2f1bb225d 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -346,7 +346,10 @@ }, { "group": "Architecture", - "pages": ["internals/architecture/components", "internals/architecture/cloud"] + "pages": [ + "internals/architecture/components", + "internals/architecture/cloud" + ] }, "internals/security", "internals/service-tokens" @@ -564,7 +567,10 @@ "integrations/cloud/gcp-secret-manager", { "group": "Cloudflare", - "pages": ["integrations/cloud/cloudflare-pages", "integrations/cloud/cloudflare-workers"] + "pages": [ + "integrations/cloud/cloudflare-pages", + "integrations/cloud/cloudflare-workers" + ] }, "integrations/cloud/terraform-cloud", "integrations/cloud/databricks", @@ -659,7 +665,9 @@ "documentation/platform/secret-scanning/overview", { "group": "Concepts", - "pages": ["documentation/platform/secret-scanning/concepts/secret-scanning"] + "pages": [ + "documentation/platform/secret-scanning/concepts/secret-scanning" + ] } ] }, @@ -709,13 +717,18 @@ "documentation/platform/ssh/overview", { "group": "Concepts", - "pages": ["documentation/platform/ssh/concepts/ssh-certificates"] + "pages": [ + "documentation/platform/ssh/concepts/ssh-certificates" + ] } ] }, { "group": "Platform Reference", - "pages": ["documentation/platform/ssh/usage", "documentation/platform/ssh/host-groups"] + "pages": [ + "documentation/platform/ssh/usage", + "documentation/platform/ssh/host-groups" + ] } ] }, @@ -757,12 +770,17 @@ "cli/commands/export", "cli/commands/token", "cli/commands/service-token", + "cli/commands/network", "cli/commands/vault", "cli/commands/user", "cli/commands/reset", { "group": "infisical scan", - "pages": ["cli/commands/scan", "cli/commands/scan-git-changes", "cli/commands/scan-install"] + "pages": [ + "cli/commands/scan", + "cli/commands/scan-git-changes", + "cli/commands/scan-install" + ] } ] }, @@ -1096,7 +1114,9 @@ "pages": [ { "group": "Kubernetes", - "pages": ["api-reference/endpoints/dynamic-secrets/kubernetes/create-lease"] + "pages": [ + "api-reference/endpoints/dynamic-secrets/kubernetes/create-lease" + ] }, "api-reference/endpoints/dynamic-secrets/create", "api-reference/endpoints/dynamic-secrets/update",