first commit

modules/01-networking/cloudflared-tunnel/README.md

@@ -0,0 +1,123 @@
+# Cloudflare Tunnel Module
+
+This module creates and manages Cloudflare Tunnels using OpenTofu, automating the entire setup process including:
+
+1. Creating the Cloudflare tunnel
+2. Configuring tunnel routing rules
+3. Setting up DNS records
+4. Deploying the cloudflared tunnel container
+
+## Features
+
+- **Automated Tunnel Management**: Creates and configures Cloudflare tunnels via the API
+- **Multiple Service Support**: Route multiple applications through a single tunnel
+- **DNS Management**: Automatically creates DNS records for your applications
+- **Docker Integration**: Deploys the cloudflared container with proper configuration
+- **Secret Management**: Auto-generates tunnel secrets if not provided
+
+## Prerequisites
+
+Before using this module, you need:
+
+1. A Cloudflare account
+2. API token with the following permissions:
+   - Account.Cloudflare Tunnel:Edit
+   - Zone.DNS:Edit
+   - Zone.Zone:Read
+3. Your Cloudflare account ID and zone ID
+
+## Usage
+
+```hcl
+module "homelab_tunnel" {
+  source = "./modules/01-networking/cloudflared-tunnel"
+  
+  cloudflare_account_id = var.cloudflare_account_id
+  cloudflare_zone_id    = var.cloudflare_zone_id
+  
+  tunnel_name    = "homelab-tunnel"
+  container_name = "cloudflared-homelab"
+  
+  ingress_rules = [
+    {
+      hostname = "budget.example.com"
+      service  = "http://actualbudget:5006"
+    },
+    {
+      hostname = "dashboard.example.com"
+      service  = "http://homepage:3000"
+    }
+  ]
+}
+```
+
+## Connecting with the Cloudflare Globals Module
+
+For cleaner code organization, use the globals module:
+
+```hcl
+module "cloudflare_globals" {
+  source = "./modules/00-globals/cloudflare"
+  
+  cloudflare_api_token = var.cloudflare_api_token
+  cloudflare_account_id = var.cloudflare_account_id
+  cloudflare_zone_id = var.cloudflare_zone_id
+  domain = "example.com"
+}
+
+module "homelab_tunnel" {
+  source = "./modules/01-networking/cloudflared-tunnel"
+  
+  cloudflare_account_id = module.cloudflare_globals.cloudflare_account_id
+  cloudflare_zone_id    = module.cloudflare_globals.cloudflare_zone_id
+  
+  tunnel_name = "homelab-tunnel"
+  
+  ingress_rules = [
+    {
+      hostname = "budget.${module.cloudflare_globals.domain}"
+      service  = "http://actualbudget:5006"
+    }
+  ]
+}
+```
+
+## Variables
+
+| Name | Description | Type | Default |
+|------|-------------|------|---------|
+| `cloudflare_account_id` | Cloudflare account ID | string | (required) |
+| `cloudflare_zone_id` | Cloudflare zone ID for your domain | string | (required) |
+| `container_name` | Name of the Cloudflare tunnel container | string | "" (defaults to "cloudflared-{tunnel_name}") |
+| `image_tag` | Docker image tag for cloudflared | string | "latest" |
+| `tunnel_name` | Name of the tunnel | string | (required) |
+| `tunnel_secret` | Secret for the tunnel | string | "" (auto-generated if empty) |
+| `ingress_rules` | List of ingress rules | list(object) | (required) |
+| `monitoring` | Enable monitoring via Watchtower | bool | true |
+
+### Ingress Rules Object Structure
+
+```hcl
+ingress_rules = [
+  {
+    hostname = "app.example.com"         # FQDN for the service
+    service = "http://container:port"    # Internal service URL
+    path = "/api/*"                      # Optional path pattern
+    create_dns_record = true             # Whether to create DNS record (default: true)
+  }
+]
+```
+
+## Outputs
+
+| Name | Description |
+|------|-------------|
+| `tunnel_id` | ID of the created tunnel |
+| `tunnel_name` | Name of the tunnel |
+| `tunnel_token` | Token for the tunnel (sensitive) |
+| `cname_target` | CNAME target for the tunnel |
+| `dns_records` | Map of created DNS records |
+| `container_name` | Name of the cloudflared container |
+| `container_id` | ID of the cloudflared container |
+| `image_id` | ID of the cloudflared image |
+| `ip_address` | IP address of the cloudflared container |

modules/01-networking/cloudflared-tunnel/main.tf

@@ -0,0 +1,95 @@
+// Cloudflare Tunnel module
+// This module creates a Cloudflare tunnel and deploys a cloudflared container
+
+terraform {
+  required_providers {
+    cloudflare = {
+      source  = "cloudflare/cloudflare"
+      version = "~> 4.0"
+    }
+    random = {
+      source  = "hashicorp/random"
+      version = "~> 3.5.1"
+    }
+  }
+}
+
+// Generate a random secret for the tunnel if none provided
+resource "random_id" "tunnel_secret" {
+  count       = var.tunnel_secret == "" ? 1 : 0
+  byte_length = 35
+}
+
+// Create the Cloudflare Tunnel
+resource "cloudflare_zero_trust_tunnel_cloudflared" "this" {
+  account_id = var.cloudflare_account_id
+  name       = var.tunnel_name
+  secret     = var.tunnel_secret != "" ? var.tunnel_secret : random_id.tunnel_secret[0].b64_std
+}
+
+locals {  
+  all_ingress_rules = [for rule in var.ingress_rules : rule if rule != null]
+}
+
+// Configure tunnel routing
+resource "cloudflare_zero_trust_tunnel_cloudflared_config" "this" {
+  account_id = var.cloudflare_account_id
+  tunnel_id  = cloudflare_zero_trust_tunnel_cloudflared.this.id
+  
+  config {
+    // Add all service ingress rules
+    dynamic "ingress_rule" {
+      for_each = local.all_ingress_rules
+      content {
+        hostname = ingress_rule.value.hostname
+        service  = ingress_rule.value.service
+      }
+    }
+    
+    // Default catch-all rule (required)
+    ingress_rule {
+      service = "http_status:404"
+    }
+  }
+}
+
+// Create DNS record for each service
+resource "cloudflare_record" "service" {
+  for_each = { for rule in var.ingress_rules : rule.hostname => rule }
+  
+  zone_id = var.cloudflare_zone_id
+  name    = split(".", each.value.hostname)[0] // Extract subdomain
+  content = "${cloudflare_zero_trust_tunnel_cloudflared.this.id}.cfargotunnel.com"
+  type    = "CNAME"
+  proxied = true
+}
+
+// Set up the Docker container
+locals {
+  container_name = var.container_name != "" ? var.container_name : "cloudflared-${var.tunnel_name}"
+  image_tag      = var.image_tag != "" ? var.image_tag : "latest"
+}
+
+module "cloudflared" {
+  source = "../../10-services-generic/docker-service"
+
+  container_name = var.container_name
+  image          = "cloudflare/cloudflared"
+  tag            = local.image_tag
+  
+  // Environment variables with tunnel token
+  env_vars      = {
+    TUNNEL_TOKEN = cloudflare_zero_trust_tunnel_cloudflared.this.tunnel_token
+  }
+  
+  // Command to run tunnel
+  command       = ["tunnel", "--no-autoupdate", "run"]
+  
+  // Restart policy
+  restart_policy = "unless-stopped"
+  
+  // Enable monitoring for the container via Watchtower if specified
+  monitoring    = var.monitoring
+
+  networks      = var.networks
+}

modules/01-networking/cloudflared-tunnel/outputs.tf

@@ -0,0 +1,47 @@
+// Outputs for the Cloudflare tunnel module
+
+output "tunnel_id" {
+  description = "ID of the created Cloudflare tunnel"
+  value       = cloudflare_zero_trust_tunnel_cloudflared.this.id
+}
+
+output "tunnel_name" {
+  description = "Name of the Cloudflare tunnel"
+  value       = cloudflare_zero_trust_tunnel_cloudflared.this.name
+}
+
+output "tunnel_token" {
+  description = "Token for the Cloudflare tunnel"
+  value       = cloudflare_zero_trust_tunnel_cloudflared.this.tunnel_token
+  sensitive   = true
+}
+
+output "cname_target" {
+  description = "CNAME target for the tunnel"
+  value       = "${cloudflare_zero_trust_tunnel_cloudflared.this.id}.cfargotunnel.com"
+}
+
+output "dns_records" {
+  description = "Map of created DNS records"
+  value       = { for k, v in cloudflare_record.service : k => v.hostname }
+}
+
+output "container_name" {
+  description = "The name of the Cloudflared tunnel container"
+  value       = module.cloudflared.container_name
+}
+
+output "container_id" {
+  description = "The ID of the Cloudflared tunnel container"
+  value       = module.cloudflared.container_id
+}
+
+output "image_id" {
+  description = "The ID of the Cloudflared image"
+  value       = module.cloudflared.image_id
+}
+
+output "ip_address" {
+  description = "The IP address of the Cloudflared container"
+  value       = module.cloudflared.ip_address
+}

modules/01-networking/cloudflared-tunnel/variables.tf

@@ -0,0 +1,57 @@
+// Variables for the Cloudflare tunnel module
+
+variable "cloudflare_account_id" {
+  description = "Cloudflare account ID"
+  type        = string
+}
+
+variable "cloudflare_zone_id" {
+  description = "Cloudflare zone ID for your domain"
+  type        = string
+}
+
+variable "container_name" {
+  description = "Name of the Cloudflare tunnel container"
+  type        = string
+  default     = ""
+}
+
+variable "image_tag" {
+  description = "Docker image tag for cloudflare/cloudflared"
+  type        = string
+  default     = "latest"
+}
+
+variable "tunnel_name" {
+  description = "Name of the Cloudflare tunnel"
+  type        = string
+}
+
+variable "tunnel_secret" {
+  description = "Secret for the Cloudflare tunnel (will be auto-generated if empty)"
+  type        = string
+  sensitive   = true
+  default     = ""
+}
+
+variable "ingress_rules" {
+  description = "List of ingress rules for services to be exposed through the tunnel"
+  type = list(object({
+    hostname = string
+    service  = string
+  }))
+  default = []
+}
+
+variable "monitoring" {
+  description = "Enable monitoring via Watchtower"
+  type        = bool
+  default     = true
+}
+
+variable "networks" {
+  description = "List of networks to connect the container to"
+  type        = list(string)
+  default     = []
+}
+