Cloudflare Tunnel is available in two deployment modes: "Legacy" Tunnel and "Named" Tunnel. Named Tunnel ↗ mode improves maintainability and stability by distinguishing between routing and configuration.
Unlike Legacy mode, Named Tunnels give users the ability to manage routing in the Cloudflare dashboard and to run cloudflared once for multiple services ↗.
If you are using Legacy Tunnel today you can migrate to Named Tunnel deployment in less than 10 minutes.
This tutorial covers how to:
Time to complete:
10 minutes
See additional documentation for working with Kubernetes.
This tutorial starts by documenting the steps to create a Legacy Tunnel with Cloudflare Load Balancer so that those can be compared to the migration steps. If you would prefer to start the migration now, skip to Create a Named Tunnel.
In both modes, the first step is to create a load balancer and endpoint pool.
Go to Traffic > Load Balancing.
Select Create Load Balancer.
On the Hostname page:
Next, create an endpoint pool for the load balancer. A pool is a group of endpoints or origins, whether Cloudflare Tunnel connections or traditional IP addresses, used by the load balancer.
In Legacy mode, adding a new instance of cloudflared into a Load Balancer pool must be done from the command line tool itself. The cloudflared agent will start and create 4 separate connections, enrolling each of these into a load balancer pool.
cloudflared tunnel --hostname app.widgetcorp.tech --url http://localhost:8000 --lb-pool lisbon-data-center
For this example, the load balancer app.widgetcorp.tech would have a pool lisbon-data-center with endpoints similar to the following:
| Endpoint Name | Endpoint Address | Weight |
|---|---|---|
0-51cc...d004 | tunnel:snf...aad | 1 |
1-51cc...d004 | tunnel:10x...x1b | 1 |
2-51cc...d004 | tunnel:yeq...y15 | 1 |
3-51cc...d004 | tunnel:vn6...7p6 | 1 |
However, the Legacy Tunnel mode has some downsides, including:
cloudflared restarts, it will attempt to register these connections as new connections which can lead to service disruption.The Named Tunnel, documented below, model provides easier management and greater stability.
To migrate to the Named Tunnel model, first download and authenticate cloudflared. Install the agent within your environment in a location that can reach the service you plan to connect to Cloudflare.
To begin, create a Named Tunnel with the following command.
cloudflared tunnel create lisbon-appThis command will create a Tunnel object in your Cloudflare account that is represented by this instance of cloudflared. You can point DNS records or LB records to this connection when you run the Tunnel.
Next, configure your Tunnel. The example below consists of a web service that is available at port 8000. The ingress rule will send traffic that cloudflared receives for the specified hostname to that port. You can also connect multiple services with a single instance of cloudflared.
In the configuration file, you must specify the location of the credentials file generated previously when you created the Tunnel.
Save the configuration file.
You can now run the Tunnel. Running the Tunnel will connect cloudflared to Cloudflare's edge in a connection only available to your account. You can use the Tunnel ID value to treat that connection like the IP address of an endpoint or origin, without the risk of someone reaching it directly and bypassing Cloudflare.
Run the following command, replacing lisbon-app with the name of your Tunnel.
cloudflared tunnel run lisbon-appYou can now begin migrating your Load Balancer deployment to use the new Named Tunnel. Create a new pool in the load balancer. Add a new endpoint to the list.
In the Endpoint Address field, input the ID of the tunnel followed by cfargotunnel.com.
In this example, the endpoint address value would be 6b9b8f72-b655-46fb-b008-a45366e26b48.cfargotunnel.com.
| Endpoint Name | Endpoint Address | Weight |
|---|---|---|
lisbon-data-center-one | 6b9b8f72-b655-46fb-b008-a45366e26b48.cfargotunnel.com | 1 |
Wait 1 minute while the new origin is recognized as healthy by Cloudflare Load Balancer. Once healthy, you can begin to disable the Legacy Argo Tunnel endpoints from the legacy Load Balancer pool.