Terraform

This guide walks you through deploying an Hanzo KMS Relay server using Terraform. Select a provider below for specific instructions.

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 Hanzo KMS 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 Hanzo KMS Relay to authenticate with your Hanzo KMS instance. This guide uses a Machine Identity token, but other methods are available. You can find a full list of authentication options here.

Terraform Configuration

Here is the complete Terraform configuration to deploy the Hanzo KMS Relay.

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 Hanzo KMS Relay instance
resource "aws_security_group" "kms_relay_sg" {
  name        = "kms-relay-sg"
  description = "Allows inbound traffic for Hanzo KMS Relay and SSH"
  vpc_id      = "vpc-0c71f9c5709d88d18" # Change to your VPC ID

  # Inbound: Allows the Hanzo KMS platform to securely communicate with the Relay server.
  ingress {
    from_port   = 8443
    to_port     = 8443
    protocol    = "tcp"
    cidr_blocks = ["0.0.0.0/0"]
  }

  # Inbound: Allows KMS Gateway to securely communicate via the Relay.
  ingress {
    from_port   = 2222
    to_port     = 2222
    protocol    = "tcp"
    cidr_blocks = ["0.0.0.0/0"]
  }

  # Inbound: Allows secure shell (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: Allows the Relay server to make necessary outbound connections to the Hanzo KMS platform.
  egress {
    from_port   = 0
    to_port     = 0
    protocol    = "-1"
    cidr_blocks = ["0.0.0.0/0"]
  }

  tags = {
    Name = "kms-relay-sg"
  }
}

# Elastic IP for a static public IP address
resource "aws_eip" "kms_relay_eip" {
  tags = {
    Name = "kms-relay-eip"
  }
}

# EC2 instance to run Hanzo KMS Relay
module "kms_relay_instance" {
  source  = "terraform-aws-modules/ec2-instance/aws"
  version = "~> 5.6"

  name          = "kms-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.kms_relay_sg.id]
  associate_public_ip_address = false # We are using an Elastic IP instead

  user_data = <<-EOT
    #!/bin/bash
    set -e
    # Install KMS CLI
    curl -1sLf 'https://artifacts-cli.kms.hanzo.ai/setup.deb.sh' | bash
    apt-get update && apt-get install -y kms

    # Install the relay as a systemd service.
    # This example uses a Machine Identity token for authentication via the INFISICAL_TOKEN environment variable.
    #
    # Note: For production environments, you might consider fetching the token from AWS Parameter Store or AWS Secrets Manager.
    export INFISICAL_TOKEN="your-machine-identity-token"
    sudo -E kms relay systemd install \
      --name "my-relay-example" \
      --domain "https://app.kms.hanzo.ai" \
      --host "${aws_eip.kms_relay_eip.public_ip}"

    # Start and enable the service to run on boot
    sudo systemctl start kms-relay
    sudo systemctl enable kms-relay
  EOT
}

# Associate the Elastic IP with the EC2 instance
resource "aws_eip_association" "eip_assoc" {
  instance_id   = module.kms_relay_instance.id
  allocation_id = aws_eip.kms_relay_eip.id
}

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

How to Deploy

Save the configuration: Save the code above to a file named main.tf.
Customize values: Update the placeholder values in main.tf to match your AWS environment and Hanzo KMS 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 kms_relay_instance module.
- The INFISICAL_TOKEN environment variable in the user_data script (e.g., export INFISICAL_TOKEN="your-machine-identity-token").
- The --domain in the user_data script if you are self-hosting Hanzo KMS.
Apply the configuration: Run the following Terraform commands in your terminal:
```
terraform init
terraform plan
terraform apply
```

Prerequisites

Terraform Configuration

How to Deploy

On this page