Overview

Do You Need to Deploy a Relay?

Feedback
Are self-hosting Hanzo KMS
Feedback
Have a dedicated enterprise instance of Hanzo KMS (managed by Hanzo KMS)
Feedback
Require closer geographic proximity to target resources than managed relays provide for lower latency and reduced network congestion when accessing resources through the relay
Feedback
Need full control over relay infrastructure and traffic routing

Deployment Steps

Create a machine identity with the correct permissions to create and manage relays. This identity is used by the relay to authenticate with Hanzo KMS and should be provisioned in advance. The relay supports several machine identity auth methods for authentication, as listed below. Choose the one that best fits your environment and set the corresponding environment variables when deploying the relay.

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>

Direct authentication using a machine identity access token.

Environment Variables:

• INFISICAL_TOKEN=<token>

Authentication using Kubernetes service account tokens.

Environment Variables:

• INFISICAL_AUTH_METHOD=kubernetes
• INFISICAL_MACHINE_IDENTITY_ID=<machine-identity-id>

Authentication using AWS IAM roles.

Environment Variables:

• INFISICAL_AUTH_METHOD=aws-iam
• INFISICAL_MACHINE_IDENTITY_ID=<machine-identity-id>

Authentication using GCP identity tokens.

Environment Variables:

• INFISICAL_AUTH_METHOD=gcp-id-token
• INFISICAL_MACHINE_IDENTITY_ID=<machine-identity-id>

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>

Authentication using Azure managed identity.

Environment Variables:

• INFISICAL_AUTH_METHOD=azure
• INFISICAL_MACHINE_IDENTITY_ID=<machine-identity-id>

Authentication using OIDC identity tokens.

Environment Variables:

• INFISICAL_AUTH_METHOD=oidc-auth
• INFISICAL_MACHINE_IDENTITY_ID=<machine-identity-id>
• INFISICAL_JWT=<oidc-jwt>

Authentication using JWT tokens.

Environment Variables:

• INFISICAL_AUTH_METHOD=jwt-auth
• INFISICAL_MACHINE_IDENTITY_ID=<machine-identity-id>
• INFISICAL_JWT=<jwt>

Provision a server or virtual machine where you plan to deploy the relay. This server must have a static IP address or DNS name to be identifiable by the Hanzo KMS platform.

Ensure your network and firewall settings allow the server to accept inbound connections and make outbound connections:

Inbound Connections Rules:

Outbound Connections Rules:

You can deploy the Hanzo KMS Relay in various ways. This guide provides a manual setup example using the KMS CLI. For an infrastructure-as-code approach, see our Terraform guide.

The KMS 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.

For production deployments on Linux servers, install the Relay as a systemd service. This installation method only supports Token Auth at the moment.

Once you have a Token Auth token, set the following environment variables for relay authentication:

export INFISICAL_TOKEN=<your-machine-identity-token>

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

sudo kms relay systemd install \
   --token <your-machine-identity-token> \
   --name <relay-name> \
   --domain <your-kms-domain> \
   --host <static-ip-or-dns-of-the-server>

# Start the relay service
sudo systemctl start kms-relay
sudo systemctl enable kms-relay

For non-Linux systems or when you need more control over the relay process:

kms relay start \
   --host=<host> \
   --name=<name> \
   --auth-method=<auth-method>

This method supports all machine identity auth methods 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.

Frequently Asked Questions

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.

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.

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:

# Test outbound API access from relay. Replace URL with your Hanzo KMS instance if self-hosted
curl -I https://app.kms.hanzo.ai

# Test TCP with TLS port from platform
openssl s_client -connect <relay-ip>: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 Hanzo KMS 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.