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, andfrankfurt). - Docker and Docker Compose installed on each VM.
- Hostnames should be unique, ideally using the location of the datacenter (for example,
jqinstalled on your local workstation.
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, Export a variable for your domain, which you use in the following API calls.
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.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 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, Export the If you open a tab and navigate to
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.on_error: continue falls through to the next action rather than returning an error to the client.Now create the Cloud Endpoint with the Traffic Policy.
jq handles escaping the YAML into a valid JSON string:id from the response for future use.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.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:Edit the Build and start the containerized API deployment, passing the hostname of the VM to the hostname of the Docker container:
- A straightforward Go-based API with a single endpoint at
/api, which returns a randomly generated UUID and the machine’shostname, which should reflect the regions of your VMs. - A
Dockerfilefor containerizing said Go-based API. - A
docker-compose.ymlfile for starting the API container and a containerized edition of the ngrok agent on the same network. - A
ngrok.ymlagent configuration file to connect the agent to your ngrok account and the internal endpoint for that VM.
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):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 To see the load balancing in action, try a batch of You’ll see each VM respond with similar frequency:Navigate to the Endpoints dashboard to confirm your tunnels are online.
<YOUR_NGROK_DOMAIN>/api to see which backend responds.curl requests.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 Then patch your Cloud Endpoint with the updated policy:When you request your API again, the response includes the
policy.yaml to add an on_http_response phase: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-varslist 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-varsaction.