Migrate legacy tunnels to named tunnels
Originally, a Cloudflare Tunnel connection corresponded to a DNS record in your account. Requests to that hostname hit Cloudflare’s network first and our edge sends those requests over the tunnel to your origin. However, fitting an outbound-only connection into a reverse proxy creates some ergonomic and stability hurdles. The original Cloudflare Tunnel architecture attempted to both manage DNS records and create connections. When connections became disrupted, Tunnel would recreate the entire deployment. Additionally, Argo Tunnel connections could not be treated like regular origin servers in Cloudflare’s control plane and had to be managed directly from the server-side software.
Today, Cloudflare Tunnel’s architecture distinguishes between the persistent objects (DNS records,
cloudflared) and the ephemeral objects (the connections). To do that, it assigns permanent names and UUIDs to tunnels, which makes them more stable and easier to use. Since the name and UUID for a tunnel do not change, your DNS record never needs to be cleaned up or recreated when Cloudflare Tunnel restarts. In the event of a restart, the enrolled instance of
cloudflared connects back to that UUID address.
To migrate your legacy tunnels to the named tunnels architecture:
- $ cloudflared tunnel create <TUNNEL-NAME>
- $ cloudflared tunnel route dns <TUNNEL-NAME> tunnel.example.com
- $ cloudflared tunnel route lb <TUNNEL-NAME> <LOAD-BALANCER-NAME> <LOAD-BALANCER-POOL>
After configuring DNS/LB records for each zone you want to serve, follow the instructions to create a config file with ingress rules. The ingress rules describe how to dispatch requests to your origins based on hostname and path. For example, if you used to run:$ cloudflared tunnel --hostname tunnel.example.com --url https://localhost:3000
You can have an equivalent ingress rule:ingress:- hostname: tunnel.example.comservice: https://localhost:3000- service: http_status:404# Note that the last rule is the catch-all rule and is required.
Make sure everything works
Once your migration is done, validate your new named tunnel by:
- Making sure the resource behind the tunnel is accessible
cloudflared tunnel info <NAME-or-UUID>to confirm that the named tunnel exists