Forward Internal

Overview

The Forward Internal Traffic Policy action enables you to forward traffic from an endpoint to a internal endpoint within the same ngrok account. This is useful for safely and securely routing traffic from your public endpoints to other services, giving you the ability to choose when and how your endpoints are made publicly available.

Configuration Reference

The Traffic Policy configuration reference for this action.

Supported Phases

on_tcp_connect, on_http_request

Type

forward-internal

Configuration Fields

• urlstringRequired

  The endpoint to forward to, such as http://my-internal-endpoint.internal:1234.

• bindingstring

  Binding of the Endpoint (only internal is currently supported).

• on_errorenum

  Whether or not further actions in the Traffic Policy should run if there is an error.

  • Possible enum values
  • halt (default)
  • continue

Behavior

This action forwards a request to an internal endpoint.

Any traffic policy associated with the internal endpoint will also be applied to the request when it's forwarded.

If the forwarding is successful, the response from the upstream for the internal endpoint will be sent back to the client making the original request. No further actions in the inbound phase will be executed and no traffic will be sent to the upstream for the public endpoint.

If the forwarding is unsuccessful because the specified endpoint doesn't exist, is offline, or encounters another error, the action will return an error and follow the behavior that is specified by on_error (see Managing Fallback Behavior).

note

Even if you do not plan to send traffic to a local service when creating a forwarding endpoint, you will still need to specify a local port. This port will receive traffic if an expression causes only a subset of traffic to be forwarded or if there is an error forwarding traffic and on_error is set to continue without a subsequent terminating action.

HTTP Headers

When forwarding HTTP requests to another endpoint, the Host header will be set to the hostname of the forwarding endpoint. For example, if example.ngrok.io is forwarding HTTP requests to example.internal, the Host header received by the upstream will be example.ngrok.io.

The action will also set the X-Forwarded-For, X-Forwarded-Host, and X-Forwarded-Proto headers when making the upstream request. See Upstream Headers for more information.

Managing Fallback Behavior (on_error)

If on_error is set to halt (default) and the action encounters an error when forwarding traffic, the Traffic Policy chain will halt and no further actions will be executed. For example, if you have a log action after the forward-internal action and the url specified isn't an online endpoint, the log action will not be run and the error will be returned.

However, if on_error is set to continue, actions that appear after the forward-internal action will still be executed even if the forward-internal action encounters an error. This can be used as a fallback to forward traffic to one of many endpoints depending which are online.

Valid forward targets

A request may only be forwarded to a internal endpoint on the same account as this endpoint.

The target must be of the same protocol (i.e. an HTTP Endpoint may only forward to an HTTP Internal Endpoint).

In addition, the target's traffic policy may only specify policy for the current protocol, for example if forward-internal is used in the on_http_request phase, the internal endpoint may only have on_http_request and on_http_response sections.

Examples

Basic Example

This example configuration will set up a public endpoint (forward-internal-example.ngrok.io) forwarding all traffic it receives to a internal endpoint (example.internal) that forwards the request to port 80 on your local machine. Since it is forwarding all traffic to the internal endpoint, no traffic will be sent to 8080 which is the upstream port for the public endpoint.

Example Traffic Policy Document

YAML

---
inbound:
  - actions:
      - type: "forward-internal"
        config:
          url: "https://example.internal"

JSON

{
  "inbound": [
    {
      "actions": [
        {
          "type": "forward-internal",
          "config": {
            "url": "https://example.internal"
          }
        }
      ]
    }
  ]
}

Start an Internal Endpoint

ngrok http 80 --url example.internal --binding internal

Start Public Endpoint with Traffic Policy

ngrok http 8080 --url forward-internal-example.ngrok.io --traffic-policy-file /path/to/policy.yml

Example Request

$ curl https://forward-internal-example.ngrok.io -v
 ...
> GET / HTTP/2
> Host: forward-internal-example.ngrok.io
> User-Agent: curl/[version]
> Accept: */*
...

This request will be forwarded to the internal endpoint https://example.internal which will then forward the request to port 80 on your local machine.

GET / HTTP/1.1
Host: forward-internal-example.ngrok.io
User-Agent: curl/[version]
Accept: */*
X-Forwarded-For: [ngrok IP]
X-Forwarded-Host: forward-internal-example.ngrok.io
X-Forwarded-Proto: https
Accept-Encoding: gzip

Action Result Variables

The following variables are made available for use in subsequent expressions and CEL interpolations after the action has run. Variable values will only apply to the last action execution, results are not concatenated.

This action does not set any variables after it has been executed.