From 040fa8c3f96299ba6b910ac808a0a9fd295c0ab4 Mon Sep 17 00:00:00 2001 From: Maidul Islam Date: Fri, 19 Sep 2025 09:39:30 -0400 Subject: [PATCH] improve gaps in relay docs --- .../platform/gateways/gateway-deployment.mdx | 2 +- .../platform/gateways/relay-deployment.mdx | 138 +++++++++++++----- 2 files changed, 104 insertions(+), 36 deletions(-) diff --git a/docs/documentation/platform/gateways/gateway-deployment.mdx b/docs/documentation/platform/gateways/gateway-deployment.mdx index 0d44e214f..40b98965a 100644 --- a/docs/documentation/platform/gateways/gateway-deployment.mdx +++ b/docs/documentation/platform/gateways/gateway-deployment.mdx @@ -95,7 +95,7 @@ To successfully deploy an Infisical Gateway for use, follow these steps in order Ensure a relay server is running and accessible before you deploy any gateways. You have two options: - **Managed relay (Infisical Cloud, US/EU only):** Managed relays are only available for Infisical Cloud instances in the US and EU regions. If you are using Infisical Cloud in these regions, you can use the provided managed relay. - - **Self-hosted relay:** For all other cases, including all self-hosted, dedicated, or non-US/EU Infisical Cloud instances, you must deploy your own relay server. You can also choose to deploy your own relay server with Infisical Cloud if you require geographic proximity for lower latency or to reduce network congestion. For setup instructions, see the Relay Deployment Guide. + - **Self-hosted relay:** For all other cases, including all self-hosted and dedicated enterprise instances of Infisical, you must deploy your own relay server. You can also choose to deploy your own relay server when using Infisical Cloud if you require reduced geographic proximity to your target resources for lower latency or to reduce network congestion. For setup instructions, see the Relay Deployment Guide. Make sure the Infisical CLI is installed on the machine or environment where you plan to deploy the gateway. The CLI is required for gateway installation and management. diff --git a/docs/documentation/platform/gateways/relay-deployment.mdx b/docs/documentation/platform/gateways/relay-deployment.mdx index f256a197a..adf5fdb9d 100644 --- a/docs/documentation/platform/gateways/relay-deployment.mdx +++ b/docs/documentation/platform/gateways/relay-deployment.mdx @@ -14,8 +14,8 @@ Before diving in, it's important to determine whether you actually need to deplo Not all users need to deploy their own relay servers. Infisical provides managed relay infrastructure in US/EU regions for Infisical Cloud users, which requires no setup or maintenance. You only need to deploy a relay if you: - Are self-hosting Infisical -- Have a dedicated Infisical instance (managed by Infisical) -- Require dedicated relays for your organization (for compliance, custom network policies, or regional proximity) +- Have a dedicated enterprise instance of Infisical (managed by Infisical) +- Require closer geographic proximity to target resources than managed relays provide for lower latency and reduced network congestion when accessing resources through the relay - Need full control over relay infrastructure and traffic routing If you are using Infisical Cloud and do not have specific requirements, you can use the managed relays provided by Infisical and skip the rest of this guide. @@ -25,44 +25,107 @@ If you are using Infisical Cloud and do not have specific requirements, you can To successfully deploy an Infisical Relay for use, follow these steps in order. - - Before deploying your relay server, ensure you have: - - - A server with a static IP address or DNS - - Administrative access to configure firewall rules - - Access to create machine identities in your Infisical organization - - The Infisical CLI installed on your deployment environment - - - - Create a machine identity with the appropriate permissions for your relay: - - 1. **Create a machine identity** in your Infisical organization with permissions to create and manage relays. + Create a machine identity with the correct permissions to create and manage relays. This identity is used by the relay to authenticate with Infisical and should be provisioned in advance. + The relay supports several [machine identity auth methods](/documentation/platform/identities/machine-identities) for authentication, as listed below. Choose the one that best fits your environment and set the corresponding environment variables when deploying the relay. - 2. **Choose an authentication method** from the supported [machine identity auth methods](/documentation/platform/identities/machine-identities) - - 3. **Configure environment variables** corresponding to your chosen authentication method when deploying the relay The relay will use this machine identity to authenticate with Infisical and register itself within your organization. - + + + Simple and secure authentication using client ID and client secret. + + **Environment Variables:** + - `INFISICAL_AUTH_METHOD=universal-auth` + - `INFISICAL_UNIVERSAL_AUTH_CLIENT_ID=` + - `INFISICAL_UNIVERSAL_AUTH_CLIENT_SECRET=` + + + + Direct authentication using a machine identity access token. + + **Environment Variables:** + - `INFISICAL_TOKEN=` + + + + Authentication using Kubernetes service account tokens. + + **Environment Variables:** + - `INFISICAL_AUTH_METHOD=kubernetes` + - `INFISICAL_MACHINE_IDENTITY_ID=` + + + + Authentication using AWS IAM roles. + + **Environment Variables:** + - `INFISICAL_AUTH_METHOD=aws-iam` + - `INFISICAL_MACHINE_IDENTITY_ID=` + + + + Authentication using GCP identity tokens. + + **Environment Variables:** + - `INFISICAL_AUTH_METHOD=gcp-id-token` + - `INFISICAL_MACHINE_IDENTITY_ID=` + + + + Authentication using GCP service account keys. + + **Environment Variables:** + - `INFISICAL_AUTH_METHOD=gcp-iam` + - `INFISICAL_MACHINE_IDENTITY_ID=` + - `INFISICAL_GCP_SERVICE_ACCOUNT_KEY_FILE_PATH=` + + + + Authentication using Azure managed identity. + + **Environment Variables:** + - `INFISICAL_AUTH_METHOD=azure` + - `INFISICAL_MACHINE_IDENTITY_ID=` + + + + Authentication using OIDC identity tokens. + + **Environment Variables:** + - `INFISICAL_AUTH_METHOD=oidc-auth` + - `INFISICAL_MACHINE_IDENTITY_ID=` + - `INFISICAL_JWT=` + + + + Authentication using JWT tokens. + + **Environment Variables:** + - `INFISICAL_AUTH_METHOD=jwt-auth` + - `INFISICAL_MACHINE_IDENTITY_ID=` + - `INFISICAL_JWT=` + + - Make sure the Infisical CLI is installed on the server where you plan to deploy the relay. The CLI is required for relay installation and management. + Install the Infisical CLI on the server where you plan to deploy the relay. The CLI is required for relay installation and management. - See the [CLI Installation Guide](/cli/overview) for instructions. + See the [CLI Installation Guide](/cli/overview) for instructions. + + This server must have a static IP address or DNS name to be identifiable by the Infisical platform. Ensure your network and firewall settings allow the server to accept inbound connections and make outbound connections: - **Inbound Connections:** + **Inbound Connections Rules:** | Protocol | Source | Port | Purpose | | -------- | ------------------ | ---- | -------------------------------- | | TCP | Gateways | 2222 | SSH reverse tunnel establishment | | TCP | Infisical instance host (US/EU, other) | 8443 | Platform-to-relay communication | - **Outbound Connections:** + **Outbound Connections Rules:** | Protocol | Destination | Port | Purpose | | -------- | ------------------------------------ | ---- | ------------------------------------------ | | TCP | Infisical instance host (US/EU, other) | 443 | API communication and certificate requests | @@ -75,26 +138,32 @@ To successfully deploy an Infisical Relay for use, follow these steps in order. To view all available flags and equivalent environment variables for relay deployment, see the [Relay CLI Command Reference](/cli/commands/relay). - For production deployments on Linux servers, install the Relay as a systemd service. This installation method only supports [Token Auth](/documentation/platform/identities/token-auth). + For production deployments on Linux servers, install the Relay as a systemd service. This installation method only supports [Token Auth](/documentation/platform/identities/token-auth) at the moment. + + Once you have a [Token Auth](/documentation/platform/identities/token-auth) token, set the following environment variables for relay authentication: + + ```bash + export INFISICAL_TOKEN= + ``` + + + The systemd install command requires a Linux operating system with root/sudo privileges. + ```bash sudo infisical relay systemd install \ --token \ --name \ --domain \ - --host + --host # Start the relay service sudo systemctl start infisical-relay sudo systemctl enable infisical-relay ``` - - - The systemd install command requires a Linux operating system with root/sudo privileges. - - + For non-Linux systems or when you need more control over the relay process: ```bash @@ -106,6 +175,7 @@ To successfully deploy an Infisical Relay for use, follow these steps in order. ``` This method supports all [machine identity auth methods](/documentation/platform/identities/machine-identities) and runs in the foreground. Suitable for production use on non-Linux systems or development environments. + Set the appropriate environment variables for your chosen auth method as described in Step 1 before running the relay start command. @@ -134,7 +204,7 @@ Deploying your own relay provides several advantages: - **Lower latency**: Deploy closer to your gateways for optimal performance - **Compliance**: Meet specific data routing and compliance requirements - **Custom network policies**: Implement organization-specific network configurations -- **Geographic proximity**: Reduce network congestion and improve response times +- **Geographic proximity**: Reduce network congestion and improve response times to access resources - **High availability**: Deploy multiple relays for redundancy and load distribution Organization-deployed relays give you complete control over your secure communication infrastructure. @@ -152,22 +222,20 @@ For detailed troubleshooting: **Test network connectivity:** ```bash -# Test outbound API access from relay +# Test outbound API access from relay. Replace URL with your Infisical instance if self-hosted curl -I https://app.infisical.com # Test TCP with TLS port from platform openssl s_client -connect :8443 ``` - Relay server outages affect gateway connectivity: - **Gateway reconnection**: Gateways will automatically attempt to reconnect when the relay comes back online -- **Service interruption**: While the relay is down, the Infisical platform cannot reach gateways through that relay +- **Service interruption**: While the relay is down, the Infisical platform cannot reach gateways through that relay. As a result, any secrets or resources accessed via those gateways will be temporarily unavailable until connectivity is restored. - **Multiple relays**: Deploy multiple relay servers for redundancy and high availability -- **Monitoring**: Set up monitoring to detect relay outages quickly - **Automatic restart**: Use systemd or container orchestration to automatically restart failed relay services For production environments, consider deploying multiple relay servers to avoid single points of failure.