ExternalcloudflaredMode.md

External cloudflared Mode

Caution

FOR ADVANCED USERS ONLY

This mode is powerful but requires a solid understanding of Docker networking and existing Cloudflare Tunnel configurations. Misconfiguration can easily lead to services being unreachable. The default Internal Mode is recommended for most users.

DockFlare can integrate with an existing, independently managed cloudflared agent instead of managing its own. This is known as "External Mode."

Use Cases

• You already have a cloudflared service running (e.g., as a systemd service or a separate Docker container).
• You want multiple applications or controllers (including DockFlare) to add ingress rules to the same Cloudflare Tunnel.
• You require specific cloudflared command-line arguments not exposed by DockFlare's internal management.

How it Works

In External Mode, the responsibilities are divided:

• You are responsible for:

  • Creating a Cloudflare Tunnel resource on the dashboard.
  • Running the cloudflared agent process and ensuring it remains connected to Cloudflare.
  • Crucially, ensuring network connectivity between your cloudflared agent and the services DockFlare will point to it. If your services are Docker containers, your external agent must be on a shared Docker network with them to resolve their container names.

• DockFlare is responsible for:

  • Monitoring Docker container labels.
  • Creating and deleting CNAME DNS records that point to your external tunnel.
  • Updating the ingress rules within your existing tunnel's configuration via the Cloudflare API.
  • Creating and managing Cloudflare Access Applications for those rules.

DockFlare DOES NOT start, stop, or manage the cloudflared agent process itself. It only manages the DNS and Tunnel Configuration on Cloudflare's side.

Configuration

To enable External Mode, set the following environment variables:

1. USE_EXTERNAL_CLOUDFLARED=true: This flag activates the mode.
2. EXTERNAL_TUNNEL_ID: The unique ID (UUID) of your existing Cloudflare Tunnel.

Example .env snippet:

# Enable External Mode
USE_EXTERNAL_CLOUDFLARED=true

# Provide the ID of your existing tunnel
EXTERNAL_TUNNEL_ID=6ff42ae2-765d-4adf-befc-ca51f8e4e688 # <-- Replace with your actual Tunnel ID

# TUNNEL_NAME is IGNORED in this mode

# You still need your Cloudflare credentials!
CF_API_TOKEN=your_cloudflare_api_token_here
CF_ACCOUNT_ID=your_cloudflare_account_id_here
CF_ZONE_ID=your_cloudflare_zone_id_here

Finding Your Tunnel ID

If you don't know the ID of your existing tunnel:

1. Log in to the Cloudflare Zero Trust Dashboard.
2. Navigate to Access -> Tunnels.
3. Find your desired tunnel in the list and click on its name.
4. The Tunnel ID (a UUID) is displayed on the tunnel's overview page.

Important Considerations

• Network, Network, Network! The most common failure point in this mode is networking. Your external cloudflared agent must be able to resolve and reach the service addresses you define in DockFlare's labels (e.g., http://my-app:80).
• API Permissions: The Cloudflare API Token used by DockFlare still needs Account:Cloudflare Tunnel:Edit and Zone:DNS:Edit permissions to modify the external tunnel's configuration and manage DNS.
• Authoritative Management: DockFlare assumes it has authoritative control over the ingress rules and associated DNS records for the hostnames it manages. It may remove rules or DNS records from the tunnel that it doesn't recognize from its own state. Do not have other systems managing ingress rules for the same hostnames on the same tunnel.

Checklist Before Using External Mode

You should be able to answer "Yes" to all these questions before proceeding:

1. Do I have a cloudflared agent already running and connected to my tunnel, completely separate from DockFlare?
2. Does my cloudflared agent have network access to the Docker services I want to expose?
3. Am I comfortable troubleshooting Docker networking issues independently?
4. Do I understand that DockFlare will be modifying the DNS and Ingress Rules of my existing tunnel?