Path-Based Routing and Policy Decentralization with Cloud Endpoints

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

Core concepts

Cloud Endpoints are centrally managed endpoints in the cloud that you can use to route traffic to Agent Endpoints.
Internal endpoints are endpoints that aren’t 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 need a local computer with ngrok installed by following the installation guides. If you’re following along using the ngrok CLI, you need:

An ngrok API key configured on your ngrok agent.

If you’re following along using CURL, you need:

An ngrok API key as an environment variable named NGROK_API_KEY.

Create an internal endpoint for the homepage

Start by creating an internal endpoint for the homepage endpoint, which handles 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 routes traffic to the app running at your local port 80, which you can set up to have any HTTP server running.

Create an internal endpoint for the API

Next, create another internal endpoint, this one for all traffic to the /api/ path.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

{
  "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 denies all requests that don’t have an API-Key header, and returns a 200 status code with a custom response for all other requests.Save the Traffic Policy as a file locally in your directory. Now, 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.

Create a domain for the Cloud Endpoint

Next, create the domain or TCP address that the Cloud Endpoint resides on. For the purpose of this guide, create an ngrok HTTP domain.

ngrok CLI
CURL
ngrok dashboard

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",
   ...
}

curl \
    -X POST https://api.ngrok.com/reserved_domains \
    -H "Authorization: Bearer ${NGROK_API_KEY}" \
    -H "Content-Type: application/json" \
    -H "Ngrok-Version: 2" \
    -d @- <<BODY
    {
        "name":"${NGROK_SUBDOMAIN}.ngrok.app",
    }
BODY

Replace NGROK_API_KEY with your ngrok API key.
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.

Create a Traffic Policy for your Cloud Endpoint

Now, create a Traffic Policy for the Cloud Endpoint. This Traffic Policy preprocesses all incoming traffic before ngrok forwards it to the internal endpoints, which may or may not have their own independent Traffic Policies. This separation gives you granularity and full control over how ngrok handles traffic.

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

{
  "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"
          }
        }
      ]
    }
  ]
}

The Traffic Policy simply forwards traffic to one of the two internal endpoints based on the path. You can create more complex traffic handling at your discretion.

Create an ngrok Cloud Endpoint

Now create an ngrok Cloud Endpoint that points to the newly created internal endpoint. You can create Cloud Endpoints via the API or the ngrok dashboard.

API
ngrok dashboard

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. This request sets the binding to public so anyone can access the Cloud Endpoint.Due to the shell’s difficulty in parsing a more complex string that includes both ' and ", this example uses Postman to send a POST request to the ngrok API instead of using the ngrok api command.

Open Postman and create a POST request to https://api.ngrok.com/endpoints.
In the Authorization tab, select API Key.
- Set Key as Authorization
- Set Value as Bearer NGROK_API_KEY
- Set Add to as Header
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
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 you can access from the URL you reserved: ${NGROK_SUBDOMAIN}.ngrok.app On most paths, the Cloud Endpoint refers to its Traffic Policy and forwards traffic to the homepage internal endpoint, which exposes the app running on local port 80. For /api/ paths, the Cloud Endpoint forwards traffic to the API internal endpoint. It requires an Api-Key header to access, and denies 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/

Getting Started

Use Cases

Examples

Connectivity

Traffic Policy

Observability

Network

Resources

Identity & Access

Path-Based Routing and Policy Decentralization with Cloud Endpoints

Core concepts

Prerequisites

Create an internal endpoint for the homepage

Create an internal endpoint for the API

Create a domain for the Cloud Endpoint

Create a Traffic Policy for your Cloud Endpoint

Create an ngrok Cloud Endpoint

Conclusion

​Core concepts

​Prerequisites

Create an internal endpoint for the homepage

Create an internal endpoint for the API

Create a domain for the Cloud Endpoint

Create a Traffic Policy for your Cloud Endpoint

Create an ngrok Cloud Endpoint

​Conclusion

Core concepts

Prerequisites

Conclusion