awatertrevi/infisical
1
0
Fork 0
mirror of https://github.com/awatertrevi/infisical.git synced 2026-09-22 13:39:35 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: add EC2 terraform deployment docs for relay

Browse Source
This commit is contained in:
x032205
2025-10-23 03:01:59 -04:00
parent 39cbdca9eb
commit edbfd74282
3 changed files with 159 additions and 3 deletions
Download Patch File Download Diff File Expand all files Collapse all files

244
docs/documentation/platform/gateways/relay-deployment/cli.mdx Normal file
View File

@@ -0,0 +1,244 @@
---
title: "CLI"
description: "How to deploy Infisical Relay Servers using the CLI"
---
Infisical Relay is a secure routing layer that allows Infisical to connect to your private network resources, such as databases or internal APIs, without exposing them to the public internet.
The relay acts as an intermediary, forwarding encrypted traffic between Infisical and your deployed gateways. This ensures that your sensitive data remains protected and never leaves your network unencrypted.
With this architecture, you can achieve secure, firewall-friendly access across network boundaries, making it possible for Infisical to interact with resources even in highly restricted environments.
Before diving in, it's important to determine whether you actually need to deploy your own relay server or if you can use Infisical's managed infrastructure.
## Do You Need to Deploy a Relay?
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 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.
## Deployment Steps
To successfully deploy an Infisical Relay for use, follow these steps in order.
<Steps>
<Step title="Provision a Machine Identity">
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.
<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>
</Step>
<Step title="Install the Infisical CLI">
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.
This server must have a static IP address or DNS name to be identifiable by the Infisical platform.
</Step>
<Step title="Configure Network & Firewall">
Ensure your network and firewall settings allow the server to accept inbound connections and make outbound 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 Rules:**
| Protocol | Destination | Port | Purpose |
| -------- | ------------------------------------ | ---- | ------------------------------------------ |
| TCP | Infisical instance host (US/EU, other) | 443 | API communication and certificate requests |
</Step>
<Step title="Select a Deployment Method">
The Infisical CLI is used to install and start the relay in your chosen environment. The CLI provides commands for both production and development scenarios, and supports a variety of options/flags to configure your deployment.
To view all available flags and equivalent environment variables for relay deployment, see the [Relay CLI Command Reference](/cli/commands/relay).
<Tabs>
<Tab title="Linux Server">
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=<your-machine-identity-token>
```
<Warning>
The systemd install command requires a Linux operating system with root/sudo privileges.
</Warning>
```bash
sudo infisical relay systemd install \
--token <your-machine-identity-token> \
--name <relay-name> \
--domain <your-infisical-domain> \
--host <static-ip-or-dns-of-the-server>
# Start the relay service
sudo systemctl start infisical-relay
sudo systemctl enable infisical-relay
```
</Tab>
<Tab title="Other Environments">
For non-Linux systems or when you need more control over the relay process:
```bash
infisical relay start \
--host=<host> \
--name=<name> \
--auth-method=<auth-method>
```
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.
</Tab>
</Tabs>
</Step>
</Steps>
## Frequently Asked Questions
<AccordionGroup>
<Accordion title="Can the relay servers decrypt traffic going through them?">
No, relay servers cannot decrypt any traffic passing through them due to end-to-end encryption:
- **Client-to-Gateway mTLS (via TLS-pinned tunnel)**: Clients connect via a proxy that establishes a TLS-pinned tunnel to the gateway; mTLS between the client and gateway is negotiated inside this tunnel, encrypting all application traffic
- **SSH tunnel encryption**: The mTLS-encrypted traffic is then transmitted through SSH reverse tunnels to relay servers
- **Double encryption**: Traffic is encrypted twice - once by client mTLS and again by SSH tunnels
- **Relay only routes traffic**: The relay server only routes the doubly-encrypted traffic without access to either encryption layer
The relay infrastructure is designed as a secure routing mechanism where only the client and gateway can decrypt the actual application traffic.
</Accordion>
<Accordion title="What are the benefits of deploying my own relay?">
Deploying your own relay provides several advantages:
- **Dedicated resources**: Full control over relay infrastructure and performance
- **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 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.
</Accordion>
<Accordion title="How do I troubleshoot connectivity issues?">
For detailed troubleshooting:
**Platform cannot connect to relay:**
- Check firewall rules allow inbound TCP with TLS on port 8443
- Test connectivity: `openssl s_client -connect <relay-ip>:8443`
**Test network connectivity:**
```bash
# 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 <relay-ip>:8443
```
</Accordion>
<Accordion title="What happens if my relay server goes down?">
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. 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
- **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.
</Accordion>
</AccordionGroup>

150
docs/documentation/platform/gateways/relay-deployment/terraform.mdx Normal file
View File

@@ -0,0 +1,150 @@
---
title: "Terraform"
description: "How to deploy Infisical Relay Servers using Terraform"
---
This guide walks you through deploying an Infisical Relay server using Terraform. Select a provider below for specific instructions.
<Tabs>
<Tab title="AWS EC2">
The provided configuration automates the creation of the EC2 instance, sets up the necessary security group rules, and uses a startup script to install and configure the Infisical Relay service.
### Prerequisites
Before you start, make sure you have the following:
- An AWS account with permissions to create EC2 instances, Security Groups, and Elastic IPs.
- An existing VPC and Subnet ID in your desired AWS region.
- The AMI ID for your chosen OS (this guide uses an Ubuntu 22.04 LTS AMI).
- Credentials for the Infisical Relay to authenticate with your Infisical instance. This guide uses a Machine Identity token, but other methods are available. You can find a full list of authentication options [here](/cli/commands/relay#available-authentication-methods).
### Terraform Configuration
Here is the complete Terraform configuration to deploy the Infisical Relay.
```terraform
terraform {
required_providers {
aws = {
source = "hashicorp/aws"
version = "~> 5.0"
}
}
}
provider "aws" {
region = "us-west-2" # Change to your desired AWS region
}
# Security Group for the Infisical Relay instance
resource "aws_security_group" "infisical_relay_sg" {
name = "infisical-relay-sg"
description = "Allows inbound traffic for Infisical Relay and SSH"
vpc_id = "vpc-0c71f9c5709d88d18" # Change to your VPC ID
# Inbound: Platform-to-relay communication (TLS)
ingress {
from_port = 8443
to_port = 8443
protocol = "tcp"
cidr_blocks = ["0.0.0.0/0"]
}
# Inbound: SSH reverse tunnel from gateways
ingress {
from_port = 2222
to_port = 2222
protocol = "tcp"
cidr_blocks = ["0.0.0.0/0"]
}
# Inbound: SSH access for administration
ingress {
from_port = 22
to_port = 22
protocol = "tcp"
cidr_blocks = ["0.0.0.0/0"] # Restrict this to your IP in production
}
# Outbound: All traffic
egress {
from_port = 0
to_port = 0
protocol = "-1"
cidr_blocks = ["0.0.0.0/0"]
}
tags = {
Name = "infisical-relay-sg"
}
}
# Elastic IP for a static public IP address
resource "aws_eip" "infisical_relay_eip" {
tags = {
Name = "infisical-relay-eip"
}
}
# EC2 instance to run Infisical Relay
module "infisical_relay_instance" {
source = "terraform-aws-modules/ec2-instance/aws"
version = "~> 5.6"
name = "infisical-relay-example"
ami = "ami-065778886ef8ec7c8" # Change to your desired AMI ID
instance_type = "t3.micro"
subnet_id = "subnet-0fd2337a1c604a494" # Change to your Subnet ID
vpc_security_group_ids = [aws_security_group.infisical_relay_sg.id]
associate_public_ip_address = false # We are using an Elastic IP instead
user_data = <<-EOT
#!/bin/bash
set -e
# Install Infisical CLI
curl -1sLf 'https://artifacts-cli.infisical.com/setup.deb.sh' | bash
apt-get update && apt-get install -y infisical
# Install the relay as a systemd service.
# This example uses a Machine Identity token for authentication (--token).
# For other authentication methods, see https://infisical.com/docs/cli/commands/relay#available-authentication-methods
sudo infisical relay systemd install \
--token "your-machine-identity-token" \
--name "my-relay-example" \
--domain "https://app.infisical.com" \ # If you are self-hosting Infisical, change this to your instance's domain
--host "${aws_eip.infisical_relay_eip.public_ip}"
# Start and enable the service to run on boot
sudo systemctl start infisical-relay
sudo systemctl enable infisical-relay
EOT
}
# Associate the Elastic IP with the EC2 instance
resource "aws_eip_association" "eip_assoc" {
instance_id = module.infisical_relay_instance.id
allocation_id = aws_eip.infisical_relay_eip.id
}
```
<Warning>
The provided security group rules are open to the internet (`0.0.0.0/0`) for simplicity. In a production environment, you should restrict the `cidr_blocks` to known IP addresses for enhanced security, especially for the SSH port (22).
</Warning>
### How to Deploy
1. **Save the configuration:** Save the code above to a file named `main.tf`.
2. **Customize values:** Update the placeholder values in `main.tf` to match your AWS environment and Infisical credentials. You'll need to replace:
- `region` in the `provider` block.
- `vpc_id` in the `aws_security_group` resource.
- `ami` and `subnet_id` in the `infisical_relay_instance` module.
- The authentication flag and value in the `user_data` script (e.g., `--token "your-machine-identity-token"`).
- The `--domain` in the `user_data` script if you are self-hosting Infisical.
3. **Apply the configuration:** Run the following Terraform commands in your terminal:
```bash
terraform init
terraform plan
terraform apply
```
</Tab>
</Tabs>