Skip to main content
In this guide, you’ll learn how to layer ngrok’s Global Load Balancer (GSLB) on top of a VM-based deployment on Linode. GSLB improves the performance and resiliency for your apps by distributing traffic to the nearest Point of Presence (PoP) and the upstream service. Unlike a traditional GSLB deployment, ngrok automatically routes traffic without requiring you to deploy infrastructure, provision IPs, or change DNS records. All you have to do is configure your ngrok agents for a simple path to high availability, horizontal scaling, A/B testing, and more. ngrok’s GSLB even works on top of Linode’s internal load balancing mechanism, NodeBalancer, for additional global resiliency and latency improvements.

What you’ll need

  • An ngrok account.
  • An account with Linode.
  • Three Ubuntu 24.04 virtual machines (VMs) in three globally distributed regions (for example, Atlanta, Osaka, and Frankfurt):
    • Hostnames should be unique, ideally using the location of the datacenter (for example, atlanta, osaka, and frankfurt).
    • Docker and Docker Compose installed on each VM.
  • jq installed on your local workstation.
1

Reserve your ngrok domain

First, generate an API key in the ngrok dashboard. Make sure you save the API key before you close the modal, because it won’t be displayed again.Export the API key on your local workstation.
Next, create a domain that is a subdomain of an ngrok-managed domain. For an example deployment like this, YOUR_COMPANY-linode-gslb.ngrok.app would work great.You can reserve your domain in one of two ways: with the ngrok API, or in the ngrok dashboard.With the ngrok API, reserve your domain on the /reserved_domains endpoint using the NGROK_API_KEY and NGROK_DOMAIN variables you exported.
Export a variable for your domain, which you use in the following API calls.
Using CNAMEs, ngrok can host an endpoint on your domain while also managing the complete TLS certificate lifecycle on your behalf. If you’d prefer to use a custom domain rather than an ngrok-managed one, follow the custom domains guide to set up your DNS and replace your custom domain in the export command above.
2

Create a Cloud Endpoint

With ngrok, you create a Cloud Endpoint to manage a persistent public endpoint in the cloud. A Cloud Endpoint’s Traffic Policy defines how ngrok handles requests—including routing, authentication, and load balancing across your upstream services.Save the following Traffic Policy to a file named policy.yaml on your local workstation. Replace dc-atlanta, dc-osaka, and dc-frankfurt with the location names you plan to use for your VMs—you’ll use these same names when configuring the ngrok agent on each VM in step 3.
This policy randomly picks one of three internal endpoints on each request, distributing load equally across your VMs. When a VM’s agent is offline, on_error: continue falls through to the next action rather than returning an error to the client.
To assign custom weights instead of equal distribution, see the weighted backend migration guide for a more advanced pattern using cumulative weights and the rand.int() macro.
Now create the Cloud Endpoint with the Traffic Policy. jq handles escaping the YAML into a valid JSON string:
Export the id from the response for future use.
If you open a tab and navigate to https://<YOUR_NGROK_DOMAIN> right now, you’ll see a 503 from ngrok. You’ve successfully created an endpoint, but don’t yet have any ngrok agents running to receive traffic.Navigate to the Endpoints dashboard to see your Cloud Endpoint configuration.
3

Install the ngrok agent and an example workload on each VM

To get some tunnels online and quickly see how ngrok’s GSLB works, use an example API deployment. This demo deployment has four parts:
  • A straightforward Go-based API with a single endpoint at /api, which returns a randomly generated UUID and the machine’s hostname, which should reflect the regions of your VMs.
  • A Dockerfile for containerizing said Go-based API.
  • A docker-compose.yml file for starting the API container and a containerized edition of the ngrok agent on the same network.
  • A ngrok.yml agent configuration file to connect the agent to your ngrok account and the internal endpoint for that VM.
Repeat the following steps on each VM:Clone the demo repository:
Edit the ngrok.yml ngrok agent configuration file with your <YOUR_NGROK_AUTHTOKEN>, which you can find in the ngrok dashboard. Note that it’s different from the API key you created in the first step. Set the url to the internal endpoint for that VM, matching the location names you used in the Traffic Policy in step 2 (for example, dc-atlanta, dc-osaka, and dc-frankfurt):
Build and start the containerized API deployment, passing the hostname of the VM to the hostname of the Docker container:
4

Test out ngrok's global server load balancing

ngrok is now load-balancing your single API endpoint across all three distributed VMs.Ping your demo API at <YOUR_NGROK_DOMAIN>/api to see which backend responds.
To see the load balancing in action, try a batch of curl requests.
You’ll see each VM respond with similar frequency:
Navigate to the Endpoints dashboard to confirm your tunnels are online.
5

Optional: Extend the Traffic Policy for API gateway features

Your demo API is already globally load-balanced, but if you want to extend your ngrok usage even further, you can update the Traffic Policy on your Cloud Endpoint with additional Traffic Policy actions.For example, to add response headers that include the request’s country code, update policy.yaml to add an on_http_response phase:
Then patch your Cloud Endpoint with the updated policy:
When you request your API again, the response includes the country header (with the appropriate code for where you’re generating the request) and the is-ngrok header.

What’s next?

You now have a globally load-balanced API deployment using three Linode VMs, three ngrok agents, three secure tunnels, one Cloud Endpoint, and a single convenient endpoint for your users. From here, you have many options for extending your use of ngrok’s GSLB:
  • Spread the load from user requests further by creating additional deployments in more regions, adding their internal endpoint URLs to the set-vars list in your Traffic Policy, and patching your Cloud Endpoint with the updated configuration.
  • Add more VMs to a region with existing deployments by starting additional agents pointing to the same internal endpoint URL. ngrok pools those connections and load-balances between them automatically. Alternatively, use NodeBalancers for additional load balancing within a region.
  • Provision a Kubernetes cluster with the same workload and the ngrok Kubernetes Operator to load-balance between VM- and Kubernetes-based deployments of the same API or application.
  • Use your Traffic Policy for A/B tests by adjusting the distribution logic in the set-vars action.
To learn more about ngrok’s GSLB, check out: