devops/quadlets/modules/rabbitmq/tenant/README.md

RabbitMQ Tenant Module

This module creates a RabbitMQ virtual host (vhost) and user (tenant) on a VPS-hosted RabbitMQ instance using SSH tunneling for secure access to the Management API.

Features

• Creates SSH tunnel to VPS-hosted RabbitMQ Management API
• Creates isolated virtual host and user for tenant
• Configures full permissions for user on their vhost
• Generates secure random password
• Outputs connection details for application use
• Supports explicit dependencies via wait_on

Requirements

• SSH access to VPS with key-based authentication
• RabbitMQ admin credentials
• RabbitMQ Management plugin enabled
• terraform-ssh-tunnel module (automatically downloaded)
• cyrilgdn/rabbitmq provider (automatically configured)

Usage

Basic Example

module "app_tenant" {
  source = "./quadlets/modules/rabbitmq/tenant"

  tenant_name     = "myapp"
  admin_username  = var.rabbitmq_admin_username
  admin_password  = var.rabbitmq_admin_password
  server_ip       = "203.0.113.10"
  ssh_user        = "fourlights"
  
  # Wait for RabbitMQ service to be ready
  wait_on = module.rabbitmq.installed
}

# Use the connection details
output "app_mq_connection" {
  value = {
    host     = module.app_tenant.host
    port     = module.app_tenant.port
    vhost    = module.app_tenant.vhost
    username = module.app_tenant.username
    password = module.app_tenant.password
  }
  sensitive = true
}

With Custom Management Port

module "custom_tenant" {
  source = "./quadlets/modules/rabbitmq/tenant"

  tenant_name     = "custom_app"
  admin_username  = var.rabbitmq_admin_username
  admin_password  = var.rabbitmq_admin_password
  server_ip       = "203.0.113.10"
  target_port     = 25672  # Custom Management API port
  
  wait_on = module.rabbitmq.installed
}

Multiple Tenants

module "tenant_1" {
  source = "./quadlets/modules/rabbitmq/tenant"

  tenant_name     = "app1"
  admin_username  = var.rabbitmq_admin_username
  admin_password  = var.rabbitmq_admin_password
  server_ip       = var.vps_ip
  
  wait_on = module.rabbitmq.installed
}

module "tenant_2" {
  source = "./quadlets/modules/rabbitmq/tenant"

  tenant_name     = "app2"
  admin_username  = var.rabbitmq_admin_username
  admin_password  = var.rabbitmq_admin_password
  server_ip       = var.vps_ip
  
  wait_on = module.rabbitmq.installed
}

Using Connection String

module "app_tenant" {
  source = "./quadlets/modules/rabbitmq/tenant"

  tenant_name     = "myapp"
  admin_username  = var.rabbitmq_admin_username
  admin_password  = var.rabbitmq_admin_password
  server_ip       = var.vps_ip
  
  wait_on = module.rabbitmq.installed
}

# Use in application configuration
resource "kubernetes_secret" "rabbitmq_credentials" {
  metadata {
    name = "rabbitmq-connection"
  }

  data = {
    connection_string = module.app_tenant.connection_string
  }
}

Inputs

Name	Description	Type	Default	Required
tenant_name	Name of the tenant (used for vhost name and username)	string	-	yes
admin_username	RabbitMQ admin username	string	-	yes
admin_password	RabbitMQ admin password	string	-	yes
server_ip	VPS server IP address	string	-	yes
ssh_user	SSH user for connecting to VPS	string	"fourlights"	no
ssh_private_key_path	Path to SSH private key	string	"~/.ssh/id_rsa"	no
target_port	RabbitMQ Management API port on VPS	number	15672	no
wait_on	Resources to wait on before creating tenant	any	null	no

Outputs

Name	Description	Sensitive
host	RabbitMQ connection host (VPS IP for AMQP)	no
port	RabbitMQ AMQP connection port (5672)	no
management_host	RabbitMQ Management API host (via SSH tunnel)	no
management_port	RabbitMQ Management API port (via SSH tunnel)	no
vhost	Virtual host name	no
username	RabbitMQ username	no
password	RabbitMQ password	yes
connection_string	Full AMQP connection string	yes
installed	Installation complete flag	no

How It Works

1. SSH Tunnel: The module uses terraform-ssh-tunnel to create a secure SSH tunnel from your local machine to the VPS RabbitMQ Management API (port 15672)
2. Provider Configuration: The RabbitMQ provider is configured to connect through the tunnel
3. Resource Creation: Creates a RabbitMQ virtual host, user, and permissions
4. Password Generation: Generates a cryptographically secure random password
5. Outputs: Provides connection details for your application to use

Connection Details

• Management API: Accessed via SSH tunnel (for Terraform operations)
• AMQP Protocol: Direct connection to VPS on port 5672 (for application connections)
• Virtual Host: Isolated messaging environment for the tenant
• Permissions: User has full configure, write, and read permissions on their vhost

Notes

• The SSH tunnel is only used for management operations (creating vhost/user/permissions)
• Applications connect directly to the VPS AMQP port (5672), not through the tunnel
• The virtual host and user will have the same name as tenant_name
• User is granted configure=".*", write=".*", read=".*" on their vhost
• Password is stored in Terraform state (sensitive)
• Ensure RabbitMQ Management plugin is enabled on the VPS instance

Permissions Explained

The tenant user receives the following permissions on their vhost:

• configure: Can declare exchanges, queues, and bindings
• write: Can publish messages
• read: Can consume messages

All permissions use the .* regex pattern, granting full access within the vhost.