infisical/docs/documentation/platform/gateways/deployment.mdx

---
title: "Deployment Guide"
description: "Complete guide to deploying Infisical Gateways and Relays"
---

This guide covers everything you need to deploy and configure both Infisical Gateways and Relay Servers, including prerequisites, step-by-step instructions, and troubleshooting.

## Prerequisites

Before deploying gateways or relays, ensure you have:

1. **Machine Identity** - Configured with appropriate permissions to create and manage gateways
2. **Network Access** - Proper connectivity between components
3. **Relay Server** - A running relay server before deploying gateways

## Deploying Relays

Choose the relay deployment type that best fits your needs:

- **Instance Relays** - Use Infisical's managed infrastructure (Infisical Cloud) or shared relays set up by your instance administrator (self-hosted). Best for getting started quickly with minimal operational overhead.

- **Organization Relays** - Deploy and manage your own relay servers. Choose this for lower latency, custom network policies, compliance requirements, or when you need full control over the relay infrastructure.

<Info>
  Most users should start with **Instance Relays** for simplicity. Consider
  Organization Relays only if you have specific latency, compliance, or control
  requirements.
</Info>

<AccordionGroup>
  <Accordion title="Instance Relays">
    **Infisical Cloud:**
    - Pre-configured and ready to use
    - No setup required, managed by Infisical

    **Self-hosted:**

    Instance relays require **two-step configuration** with matching secrets:

    **Step 1: Instance Admin Configuration**
    The Infisical instance administrator must first set the relay auth secret in the instance environment:

    ```bash
    # In the Infisical instance environment variables
    RELAY_AUTH_SECRET=<shared-secret-value>
    ```

    **Step 2: Relay Deployment**
    Deploy the relay using the **same secret value**:

    ```bash
    # Set the matching secret for relay deployment
    export INFISICAL_RELAY_AUTH_SECRET=<shared-secret-value>

    # Start the instance relay
    infisical relay start --type=instance --host=<public-ip> --name=<relay-name>
    ```

    <Warning>
      The `RELAY_AUTH_SECRET` (instance environment) and
      `INFISICAL_RELAY_AUTH_SECRET` (relay environment) **must match exactly** for
      authentication to work.
    </Warning>

  </Accordion>

  <Accordion title="Organization Relays (Customer-Deployed)">
    Deploy your own relay server for full control. Organization relays support all authentication methods:

    ```bash
    # Token auth
    infisical relay start --type=org --host=<public-ip> --name=<relay-name> --token=<token>

    # Universal auth
    infisical relay start --type=org --host=<public-ip> --name=<relay-name> --auth-method=universal-auth --client-id=<id> --client-secret=<secret>

    # Other auth methods (kubernetes, aws-iam, gcp-id-token, azure, etc.)
    infisical relay start --type=org --host=<public-ip> --name=<relay-name> --auth-method=<method> --machine-identity-id=<id>
    ```

  </Accordion>
</AccordionGroup>

### Relay Systemd Service (Linux)

For production deployments, install as a systemd service:

```bash
# Organization relay
sudo infisical relay systemd install --token=<token> --name=<name> --host=<host> --type=org

# Instance relay
sudo infisical relay systemd install --type=instance --name=<name> --host=<host> --relay-auth-secret=<secret>

# Start the service
sudo systemctl start infisical-relay

# Uninstall
sudo infisical relay systemd uninstall
```

**Required Network Configuration:**

- **Inbound SSH** on port 2222 from gateways
- **Inbound TCP with TLS** on port 8443 from Infisical platform
- **Outbound HTTPS** to Infisical API endpoints on port 443

## Deploying Gateways

### Linux Server Deployment

For production deployments on Linux servers, 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
```

This will install and start the Gateway as a secure systemd service that:

- Runs with restricted privileges
- Automatically restarts on failure
- Starts on system boot
- Manages token and domain configuration securely in `/etc/infisical/gateway.conf`

<Warning>
  The systemd install command requires a Linux operating system with root/sudo
  privileges.
</Warning>

### Kubernetes Cluster Deployment

For production deployments on Kubernetes clusters, install the Gateway using the Infisical Helm chart:

#### Install the latest Helm Chart repository

```bash
helm repo add infisical-helm-charts 'https://dl.cloudsmith.io/public/infisical/helm-charts/helm/charts/'
helm repo update
```

#### Create a Kubernetes Secret

The gateway supports all identity authentication methods through environment variables:

```bash
kubectl create secret generic infisical-gateway-environment \
  --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>
```

#### Install the Gateway

```bash
helm install infisical-gateway infisical-helm-charts/infisical-gateway
```

<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>

### Development & Testing

For development or testing environments:

```bash
# Direct execution with token
infisical gateway start --token <token> --relay=<relay-name> --name=<gateway-name>

# Using environment variable
export INFISICAL_TOKEN=<token>
infisical gateway start --relay=<relay-name> --name=<gateway-name>
```

### Authentication Methods

The gateway supports multiple authentication methods. Choose the one that best fits your environment:

<AccordionGroup>
  <Accordion title="Universal Auth">
    Simple and secure authentication using client ID and client secret.
    
    **Environment Variables:**
    - `INFISICAL_AUTH_METHOD=universal-auth`
    - `INFISICAL_UNIVERSAL_AUTH_CLIENT_ID=<client-id>`
    - `INFISICAL_UNIVERSAL_AUTH_CLIENT_SECRET=<client-secret>`
  </Accordion>
  
  <Accordion title="Token Auth">
    Direct authentication using a machine identity access token.
    
    **Environment Variables:**
    - `INFISICAL_TOKEN=<token>`
  </Accordion>
  
  <Accordion title="Native Kubernetes">
    Authentication using Kubernetes service account tokens.
    
    **Environment Variables:**
    - `INFISICAL_AUTH_METHOD=kubernetes`
    - `INFISICAL_MACHINE_IDENTITY_ID=<machine-identity-id>`
  </Accordion>
  
  <Accordion title="Native AWS IAM">
    Authentication using AWS IAM roles.
    
    **Environment Variables:**
    - `INFISICAL_AUTH_METHOD=aws-iam`
    - `INFISICAL_MACHINE_IDENTITY_ID=<machine-identity-id>`
  </Accordion>
  
  <Accordion title="Native GCP ID Token">
    Authentication using GCP identity tokens.
    
    **Environment Variables:**
    - `INFISICAL_AUTH_METHOD=gcp-id-token`
    - `INFISICAL_MACHINE_IDENTITY_ID=<machine-identity-id>`
  </Accordion>
  
  <Accordion title="GCP IAM">
    Authentication using GCP service account keys.
    
    **Environment Variables:**
    - `INFISICAL_AUTH_METHOD=gcp-iam`
    - `INFISICAL_MACHINE_IDENTITY_ID=<machine-identity-id>`
    - `INFISICAL_GCP_SERVICE_ACCOUNT_KEY_FILE_PATH=<path-to-key-file>`
  </Accordion>
  
  <Accordion title="Native Azure">
    Authentication using Azure managed identity.
    
    **Environment Variables:**
    - `INFISICAL_AUTH_METHOD=azure`
    - `INFISICAL_MACHINE_IDENTITY_ID=<machine-identity-id>`
  </Accordion>
  
  <Accordion title="OIDC Auth">
    Authentication using OIDC identity tokens.
    
    **Environment Variables:**
    - `INFISICAL_AUTH_METHOD=oidc-auth`
    - `INFISICAL_MACHINE_IDENTITY_ID=<machine-identity-id>`
    - `INFISICAL_JWT=<oidc-jwt>`
  </Accordion>
  
  <Accordion title="JWT Auth">
    Authentication using JWT tokens.
    
    **Environment Variables:**
    - `INFISICAL_AUTH_METHOD=jwt-auth`
    - `INFISICAL_MACHINE_IDENTITY_ID=<machine-identity-id>`
    - `INFISICAL_JWT=<jwt>`
  </Accordion>
</AccordionGroup>

### Environment Variables

In addition to authentication, you must set these required variables:

- `INFISICAL_RELAY_NAME` - The name of the relay server to connect to
- `INFISICAL_GATEWAY_NAME` - A unique name for this gateway instance

Optional variables:

- `INFISICAL_API_URL` - The Infisical API URL (defaults to `https://app.infisical.com`)

## Verification

After deployment, verify your gateway is working:

1. **Check logs** for "Gateway started successfully" message
2. **Verify registration** in the Infisical dashboard under Organization Access Control > Gateways
3. **Test connectivity** by creating a dynamic secret or app connection

## Best Practices

### Gateway Security

- **One identity per gateway** - Create a unique machine identity for each gateway
- **Minimal permissions** - Assign only the permissions each gateway actually needs
- **Rotate credentials** - Set up regular credential rotation
- **Monitor authentication** - Watch for unusual authentication activity

### Relay Security

- **Secure secret management** - For instance relays, ensure `RELAY_AUTH_SECRET` and `INFISICAL_RELAY_AUTH_SECRET` are stored securely
- **Network isolation** - Use security groups and network ACLs to restrict relay access
- **Regular updates** - Keep relay servers updated and patched
- **Monitor traffic** - Watch for unusual connection patterns or traffic volume

### Performance & Reliability

- **Deploy close to resources** - Place gateways as close as possible to your private resources
- **Deploy relays strategically** - For organization relays, deploy close to gateways to minimize latency
- **Use multiple instances** - Deploy multiple gateways and relays for redundancy
- **Monitor resource usage** - Track CPU, memory, and network usage for both gateways and relays
- **Health monitoring** - Set up monitoring for both gateway and relay connection status
- **Automatic restart** - Use systemd or Kubernetes to automatically restart failed services

## Troubleshooting

### Common Issues

**Gateway fails to start:**

- Verify machine identity has correct permissions
- Check network connectivity to relay server
- Ensure all required environment variables are set

**Cannot connect to relay:**

- Verify relay server is running and accessible
- Check firewall rules allow outbound connections on port 2222
- Confirm relay name matches exactly

**Authentication failures:**

- Verify machine identity credentials are correct
- Check token expiration and renewal
- Ensure authentication method is properly configured

**Relay not accessible from gateways:**

- Check firewall rules allow inbound SSH on port 2222
- Verify public IP is correctly configured
- Test connectivity: `telnet <relay-ip> 2222`

**Platform cannot connect to relay:**

- Check firewall rules allow inbound TCP with TLS on port 8443
- Verify SSL certificate is properly configured
- Test connectivity: `openssl s_client -connect <relay-ip>:8443`

### Logs

Check gateway logs for detailed error information:

```bash
# systemd service
sudo journalctl -u infisical-gateway -f

# Kubernetes
kubectl logs deployment/infisical-gateway

# Local installation
# Logs appear in the terminal where you started the gateway
```

### Network Testing

Test relay connectivity:

```bash
# Test SSH port from gateway
nc -zv <relay-ip> 2222

# Test TCP with TLS port from platform
openssl s_client -connect <relay-ip>:8443

# Test outbound API access
curl -I https://app.infisical.com
```