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     = []
+}
+

modules/01-networking/docker-network/README.md

@@ -0,0 +1,47 @@
+# Docker Network Module
+
+This module creates a Docker network that allows containers to communicate with each other using container names as hostnames.
+
+## Purpose
+
+The module is designed to create a consistent Docker network for all homelab services, enabling direct container-to-container communication using container names instead of IP addresses.
+
+## Usage
+
+```hcl
+module "homelab_network" {
+  source = "../modules/01-networking/docker-network"
+  
+  network_name = "homelab-network"
+  driver       = "bridge"
+  
+  # Optional: Configure specific subnet (uncomment if needed)
+  # subnet       = "172.20.0.0/16"
+  # gateway      = "172.20.0.1"
+}
+```
+
+## Input Variables
+
+| Name | Description | Type | Default | Required |
+|------|-------------|------|---------|----------|
+| `network_name` | Name of the Docker network | `string` | N/A | Yes |
+| `driver` | Network driver to use | `string` | `"bridge"` | No |
+| `internal` | Restrict external access if true | `bool` | `false` | No |
+| `attachable` | Enable manual container attachment | `bool` | `true` | No |
+| `ipam_driver` | IP address management driver | `string` | `"default"` | No |
+| `subnet` | Subnet in CIDR format | `string` | `""` | No |
+| `gateway` | Gateway IP for the subnet | `string` | `""` | No |
+| `ip_range` | Range for container IP allocation | `string` | `""` | No |
+| `aux_address` | Auxiliary addresses for driver | `map(string)` | `{}` | No |
+| `labels` | Docker labels to add to the network | `map(string)` | `{}` | No |
+| `options` | Driver-specific options | `map(string)` | `{}` | No |
+
+## Outputs
+
+| Name | Description |
+|------|-------------|
+| `network_id` | The ID of the created Docker network |
+| `network_name` | The name of the Docker network |
+| `network_driver` | The driver of the Docker network |
+| `ipam_config` | The IPAM configuration of the network |

modules/01-networking/docker-network/main.tf

@@ -0,0 +1,31 @@
+// Docker Network Module
+// This module creates a Docker network for container communication
+
+terraform {
+  required_providers {
+    docker = {
+      source  = "kreuzwerker/docker"
+      version = "~> 3.6.0"
+    }
+  }
+}
+
+resource "docker_network" "this" {
+  name            = var.name
+  driver          = var.driver
+  internal        = var.internal
+  attachable      = var.attachable
+  ipam_driver     = var.ipam_driver
+  
+  dynamic "ipam_config" {
+    for_each = var.subnet != "" ? [1] : []
+    content {
+      subnet        = var.subnet
+      gateway       = var.gateway
+      ip_range      = var.ip_range
+      aux_address   = var.aux_address
+    }
+  }
+  
+  options         = var.options
+}

modules/01-networking/docker-network/outputs.tf

@@ -0,0 +1,21 @@
+// Outputs for Docker Network module
+
+output "network_id" {
+  description = "The ID of the Docker network"
+  value       = docker_network.this.id
+}
+
+output "name" {
+  description = "The name of the Docker network"
+  value       = docker_network.this.name
+}
+
+output "network_driver" {
+  description = "The driver of the Docker network"
+  value       = docker_network.this.driver
+}
+
+output "ipam_config" {
+  description = "The IPAM configuration of the Docker network"
+  value       = docker_network.this.ipam_config
+}

modules/01-networking/docker-network/variables.tf

@@ -0,0 +1,64 @@
+variable "name" {
+  description = "Name of the Docker network"
+  type        = string
+}
+
+variable "driver" {
+  description = "Name of the network driver to use"
+  type        = string
+  default     = "bridge"
+}
+
+variable "internal" {
+  description = "Restrict external access to the network if true"
+  type        = bool
+  default     = false
+}
+
+variable "attachable" {
+  description = "Enable manual container attachment if true"
+  type        = bool
+  default     = true
+}
+
+variable "ipam_driver" {
+  description = "Driver used for IP address management"
+  type        = string
+  default     = "default"
+}
+
+variable "subnet" {
+  description = "Subnet in CIDR format that represents a network segment"
+  type        = string
+  default     = ""
+}
+
+variable "gateway" {
+  description = "IPv4 or IPv6 gateway for the subnet"
+  type        = string
+  default     = ""
+}
+
+variable "ip_range" {
+  description = "Range of IPs from which to allocate container IPs"
+  type        = string
+  default     = ""
+}
+
+variable "aux_address" {
+  description = "Auxiliary IPv4 or IPv6 addresses used by the driver"
+  type        = map(string)
+  default     = {}
+}
+
+variable "labels" {
+  description = "Labels to add to the network"
+  type        = map(string)
+  default     = {}
+}
+
+variable "options" {
+  description = "Network driver specific options"
+  type        = map(string)
+  default     = {}
+}