This guide provides an example on how to forward traffic to internal endpoints based on path using ngrok Cloud Endpoints. The cloud endpoint will have a traffic policy to route traffic to one of two internal endpoints depending on the path, but each internal endpoint will also have its own traffic policy to independently handle incoming traffic.

​
Core Concepts

  • Cloud endpoints are centrally managed endpoints in the cloud that can be used to route traffic to agent endpoints.
  • Internal endpoints are endpoints that are not publicly accessible and are only reachable from within your network by cloud endpoints via the forward action.
  • Path-Based Routing involves directing incoming traffic to different destinations based on the path component of a URL

​
Prerequisites

To follow this guide, you will need a local computer with ngrok installed by following our installation guides. If you are going to be following along using ngrok CLI, you will need: If you are going to be following along using CURL, you will need:
  • An ngrok API key as an environment variable named NGROK_API_KEY.

​
Step 1 — Create an Internal Endpoint for the Homepage

Let’s start by creating a internal endpoint for the homepage endpoint, which will handle all non-API traffic. 
ngrok http 80 \
    --url https://homepage.internal
After running, you should see the endpoint with an “online” status at your domain. It will route traffic to the app running at your local port 80, which you can setup to have any HTTP server running.

​
Step 2 - Create an Internal Endpoint for the API

Next, let’s create the another internal endpoint, this one for all traffic to the /api/ path. We will use a traffic policy to simulate accessing an API endpoint. 
on_http_request:
  -     expressions:
      - !(hasReqHeader('Api-Key'))
    actions:
      -         type: deny
        config:
          status_code: 404
  -     actions:
      -         type: custom-response
        config:
          status_code: 200
          body: <html><body><h1>Hello world</h1><p>The quick brown fox jumps over the lazy dog.</p></body></html>
          headers:
            content-type: text/html
The above traffic policy will deny all requests that do not have an API-Key header, and return a 200 status code with a custom response for all other requests. Save the traffic policy as a file locally in your directory. Now, let’s create an internal endpoint based on this traffic policy. 
ngrok http 3001 \
    --url https://api.internal \
    --traffic-policy-file {PATH_TO_TRAFFIC_POLICY}
After running, you should see the endpoint with an “online” status for your endpoint.

​
Step 3 - Create a Domain for the Cloud Endpoint

Next, let’s create the domain or TCP address that the cloud endpoint will reside on. For the purpose of this guide, we will create an ngrok HTTP domain. 
ngrok api reserved-domains create \
    --url ${NGROK_SUBDOMAIN}.ngrok.app
  • Replace NGROK_SUBDOMAIN with the subdomain you’d like to use for this guide.
After running, you should see the following:
skip-validation
200 OK
{
   "id":"rd_2MT5Bqt0UzU0mFQ0zr8m1UQWCfm",
   ...
}
When you have completed this step, you can move on to the next step.

​
Step 4 — Create a Traffic Policy for your Cloud Endpoint

Now, we’ll continue and create a traffic policy for the cloud endpoint. All incoming traffic will be preprocessed by this traffic policy, before being forwarded to the internal endpoints which may or may not have their own independent traffic policies. This separation allows for granularity and full control over how traffic is handled. 
on_http_request:
  -     expressions:
      - req.url.path.startsWith('/api/')
    actions:
      -         type: forward-internal
        config:
          url: https://api.internal
          binding: internal
  -     actions:
      -         type: forward-internal
        config:
          url: https://homepage.internal
          binding: internal
Our traffic policy simply forwards traffic to one of our two internal endpoints based on the path. More complex traffic handling can be created at your discretion.

​
Step 5 — Create an ngrok Cloud Endpoint

Now we can create an ngrok Cloud Endpoint that points to our newly created internal endpoint. Cloud Endpoints can be created via the API or ngrok dashboard.
We use the URL from Step 2 as the url value in the traffic policy, and the traffic policy from Step 3 as the traffic-policy value. The binding is set to public so anyone can access our cloud endpoint.Due to the shell’s difficulty in parsing a more complex string that includes both ' and ", we will use Postman to send a POST request to the ngrok API instead of using the ngrok api command.
  1. Open Postman and create a POST request to https://api.ngrok.com/endpoints.
  2. In the Authorization tab, select “API Key”.
    • Set Key as Authorization
    • Set Value as Bearer NGROK_API_KEY
    • Set Add to as Header
  3. In the Headers tab, add a new header:
    • Create a header with the key Content-Type and value application/json
    • Create a header with the key Ngrok-Version and value 2
  4. In the Body tab, create a raw JSON:
{
	"bindings": ["public"],
	"description": "sample cloud endpoint",
	"metadata": "{\"environment\": \"prod\"}",
	"type": "cloud",
	"traffic_policy": "{\"on_http_request\": [{\"expressions\": [\"req.url.path.startsWith('/api/')\"],\"actions\": [{\"type\": \"forward-internal\",\"config\": {\"url\": \"https://api.internal\",\"binding\": \"internal\"}}]},{\"actions\": [{\"type\": \"forward-internal\",\"config\": {\"url\": \"https://homepage.internal\",\"binding\": \"internal\"}}]}]}",
	"url": "https://{NGROK_SUBDOMAIN}.ngrok.app"
}
  • Replace YOUR_NGROK_API_KEY with your ngrok API key.
  • Replace NGROK_SUBDOMAIN with the value used in Step 3.
For more details on using the API to create a cloud endpoint, see the API documentation for endpoints.

​
Conclusion

You’ve successfully created a cloud endpoint that can be accessed from the URL you reserved: ${NGROK_SUBDOMAIN}.ngrok.app On most paths, the cloud endpoint will refer to its traffic policy and forward traffic to our homepage internal endpoint, which exposes the app running on local port 80. For /api/ paths, the cloud endpoint will forward traffic to our API internal endpoint. It requires an Api-Key header to access, and denies for all other requests. You won’t be able to access the API normally from the browser, but you can use CURL or Postman to test it. 
curl --header "Api-Key: AnythingHere" https://${NGROK_SUBDOMAIN}.ngrok.app/api/