A project that uses Terraform to provision and manage Cloudflare Tunnels through Infrastructure as Code.

TerraCFTunnel allows you to provision Cloudflare Tunnels using Terraform and automatically deploy them as Docker containers. This approach provides:

• 🏗️ Infrastructure as Code: Use Terraform to declare and manage your Cloudflare Tunnel configurations
• 🔄 Reproducibility: Easily recreate your tunnels with consistent configuration
• 🐳 Docker Integration: Run your tunnels in Docker containers for better isolation and management

• 🐳 Docker
• 🏗️ Terraform (>= 0.14.0)
• ☁️ Cloudflare account with access to create tunnels
• 🔑 Cloudflare API token with the required permissions

To use this project, you need to create a Cloudflare API token with the following permissions:

1. Go to the Cloudflare dashboard and navigate to "My Profile" → "API Tokens"
2. Click "Create Token" → "Custom Permissions"
3. Add the following permissions:
   • Account → Cloudflare Tunnel: Edit
   • Account → Access: Apps and Policies: Edit (Required for Zero Trust UI)
   • Zone → DNS: Edit

⚠️ Without these permissions, the Terraform provider won't be able to create and manage tunnels properly.

This project is designed to be easily forked and used for your own purposes! Just follow these steps:

1. Fork this repository on GitHub by clicking the "Fork" button at the top right of the repository page
2. Clone your forked repository to your local machine:

   git clone https://github.com/YOUR_USERNAME/TerraCFTunnel.git
   cd TerraCFTunnel
   

3. Update the services.auto.tfvars file with your own configuration values (see below)
4. Use the Makefile commands to deploy your own tunnels

This template is production-ready and can be used "as-is" by simply configuring your own variables.

1. Clone this repository:

   git clone https://github.com/bariiss/TerraCFTunnel.git
   cd TerraCFTunnel
   

2. Configure your Terraform variables by editing the services.auto.tfvars file:

   # Example services.auto.tfvars
   tunnel_name = "your-tunnel-name"
   account_id = "your-cloudflare-account-id"
   api_token = "your-cloudflare-api-token"
   
   services = {
     service1 = { 
       hostname = "service1.yourdomain.com",
       target = "http://localhost:8080",
       zone_id = "your-cloudflare-zone-id"
     }
     # Add more services as needed
   }
   

   You must update:

   • tunnel_name: A name for your Cloudflare tunnel
   • account_id: Your Cloudflare account ID (found in the Cloudflare dashboard URL)
   • api_token: Your Cloudflare API token with proper permissions
   • services: The services you want to expose through the tunnel
     • Each service needs a hostname (DNS record), target (local service address), and zone_id (Cloudflare zone ID for the domain)

3. Use the provided Makefile commands to manage your infrastructure

This project includes a Makefile to simplify common operations:

make init       - Initialize Terraform
make plan       - Plan Terraform changes
make apply      - Apply Terraform changes
make destroy    - Destroy Terraform resources (with confirmation)
make docker-run - Run the Cloudflare tunnel in Docker
make apply-run  - Apply Terraform changes and start the Cloudflare tunnel

To provision infrastructure and start a tunnel:

make apply-run

This will:

1. Initialize Terraform
2. Apply the Terraform configuration
3. Retrieve the Cloudflare tunnel command from Terraform outputs
4. Start a Docker container running the Cloudflare tunnel

To destroy the infrastructure:

make destroy

This will:

1. Prompt for confirmation
2. Remove the running Docker container
3. Wait for resources to clean up (60 seconds)
4. Destroy the Terraform-managed resources

This project includes GitHub Actions workflows to automate Terraform operations:

The project includes a GitHub Actions workflow for applying Terraform changes automatically:

# .github/workflows/terraform-apply.yml
name: Terraform Apply

on:
  push:
    branches:
      - main

jobs:
  apply:
    runs-on: ubuntu-latest
    if: contains(github.event.head_commit.message, '#APPLY')

To trigger this workflow:

1. Commit your changes with a message containing #APPLY
2. Push to the main branch
3. The workflow will automatically initialize Terraform and apply changes

There's also a workflow for destroying the infrastructure:

# .github/workflows/terraform-destroy.yml
name: Terraform Destroy

on:
  push:
    branches:
      - main

jobs:
  destroy:
    runs-on: ubuntu-latest
    if: contains(github.event.head_commit.message, '#DESTROY')

To trigger infrastructure destruction:

1. Commit any change with a message containing #DESTROY
2. Push to the main branch
3. The workflow will automatically initialize Terraform and destroy all resources

⚠️ Note: Be cautious when using the destroy workflow as it will remove all resources without confirmation.

The project uses:

• 🏗️ Terraform: To provision and manage Cloudflare tunnel resources
• 🐳 Docker: To run the Cloudflare tunnel client (cloudflared) in a container
• 📋 Makefile: To simplify and standardize operations

The Terraform configuration outputs the necessary cloudflared command that's automatically used when starting the Docker container.

If the tunnel doesn't start correctly:

1. Check the Docker container logs: docker logs cf-tunnel
2. Verify your Terraform configuration and outputs
3. Ensure your Cloudflare credentials are properly configured

Contributions are welcome! Please feel free to submit a Pull Request. ✨