122 lines
4.6 KiB
Markdown
122 lines
4.6 KiB
Markdown
# 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 = "dashboard.example.com"
|
|
service = "http://homepage:3000"
|
|
}
|
|
]
|
|
|
|
service_definitions = [
|
|
{
|
|
name = "homepage"
|
|
subdomains = ["dashboard"]
|
|
endpoint = "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"
|
|
}
|
|
|
|
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) | (optional) |
|
|
| `service_definitions` | List of service definitions. Tunnel will create DNS records for each service with a subdomain. | list(object) | (optional) |
|
|
| `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 |
|