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

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

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

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

```hcl
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.