Skip to content

InternalvsExternalcloudflared.md

Jump to bottom
Chris edited this page Apr 22, 2025 · 4 revisions

Internal vs External cloudflared Mode

DockFlare can operate in two distinct modes regarding the cloudflared agent (the software that establishes the connection to Cloudflare's edge):

1. Internal Mode (Default)

  • How it works: DockFlare takes full responsibility for the cloudflared agent lifecycle.
    • It creates a Cloudflare Tunnel resource using the TUNNEL_NAME you provide.
    • It retrieves the tunnel's unique credentials (Tunnel Token).
    • It deploys and manages a dedicated cloudflared Docker container (named cloudflared-agent-<your-tunnel-name>). This container uses the retrieved token to connect to Cloudflare.
    • DockFlare ensures this agent container is running and restarts it if necessary.
    • DockFlare configures ingress rules directly on the tunnel it manages.
  • Configuration:
    • USE_EXTERNAL_CLOUDFLARED=false (or omitted, as this is the default).
    • TUNNEL_NAME environment variable is required.
  • Pros:
    • Simplest setup: DockFlare handles everything tunnel-related.
    • Self-contained: No need to manage a separate cloudflared instance.
  • Cons:
    • Creates a dedicated tunnel just for DockFlare's managed services. May not be ideal if you already have existing tunnels you want to reuse.

2. External Mode

  • How it works: You manage the cloudflared agent yourself, and DockFlare only handles the configuration within that existing tunnel.
    • You must have an existing Cloudflare Tunnel created (either manually via the dashboard or using cloudflared commands).
    • You must run the cloudflared agent yourself (as a service, another Docker container, etc.) and ensure it's connected to Cloudflare using your tunnel's credentials.
    • DockFlare connects to the Cloudflare API and modifies the configuration (ingress rules) and associated DNS records for the existing tunnel you specify.
    • DockFlare does not create a tunnel or run the cloudflared agent container itself.
  • Configuration:
    • USE_EXTERNAL_CLOUDFLARED=true environment variable is required.
    • EXTERNAL_TUNNEL_ID environment variable is required. You need to provide the UUID of your existing tunnel. See Finding Your Tunnel ID.
    • TUNNEL_NAME environment variable is ignored.
  • Pros:
    • Allows integration with existing cloudflared setups.
    • Enables sharing a single tunnel across multiple applications or controllers.
    • Gives you more control over the cloudflared agent's deployment and configuration.
  • Cons:
    • Requires more setup: You are responsible for creating the tunnel and running the agent correctly.
    • Requires finding and providing the EXTERNAL_TUNNEL_ID.

Choosing the Right Mode

  • Use Internal Mode if:
    • You are new to Cloudflare Tunnels and want the easiest setup.
    • You want DockFlare to manage the entire tunnel lifecycle for the services it exposes.
  • Use External Mode if:
    • You already have a cloudflared tunnel running for other purposes and want DockFlare to add rules to it.
    • You prefer to manage the cloudflared agent deployment separately.
    • You need fine-grained control over the cloudflared agent's parameters.

See also:

Clone this wiki locally