-
Notifications
You must be signed in to change notification settings - Fork 2k
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Initial docs for the Forward Internal action (#936)
Co-authored-by: Niji <[email protected]> Co-authored-by: ℕ <[email protected]>
- Loading branch information
1 parent
c590142
commit 09bc9fd
Showing
9 changed files
with
146 additions
and
1 deletion.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,18 @@ | ||
import ActionBehavior from "/traffic-policy/actions/forward-internal/behavior.mdx"; | ||
import ActionConfig from "/traffic-policy/actions/forward-internal/config.mdx"; | ||
import ActionExamples from "/traffic-policy/actions/forward-internal/examples/index.mdx"; | ||
import ActionOverview from "/traffic-policy/actions/forward-internal/index.mdx"; | ||
import ActionVariables from "/traffic-policy/actions/forward-internal/variables.mdx"; | ||
import ActionVariablesDescription from "/traffic-policy/common/action-variables-description.mdx"; | ||
|
||
# Forward Internal | ||
|
||
<ActionOverview /> | ||
<ActionConfig /> | ||
<ActionBehavior /> | ||
<ActionExamples /> | ||
|
||
## Action Result Variables | ||
|
||
<ActionVariablesDescription /> | ||
<ActionVariables /> |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,23 @@ | ||
## Behavior | ||
|
||
When the Forward Internal action executes, it will look up the specified endpoint and relay any incoming traffic. The endpoint being forwarded to will behave as if the traffic was sent directly to it and execute all of the actions in its associated Traffic Policy. The endpoint being forwarded to must exist in the same ngrok account and be the same protocol as the forwarding endpoint (e.g. an HTTP public endpoint can only forward to an HTTP private endpoint). You also may not forward traffic to a second private endpoint or back to the original endpoint in a loop. | ||
|
||
If the forwarding is successful, the response from the upstream for the private endpoint will be sent back to the client making the original request. No further actions in the `on_http_request` 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](#on-error)). | ||
|
||
:::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.private`, 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](/docs/http#upstream-headers) for more information. | ||
|
||
### Managing Fallback Behavior (`on_error`) {#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. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,27 @@ | ||
## Configuration Reference | ||
|
||
This is the [Traffic Policy](/docs/http/traffic-policy/) configuration | ||
reference for this action. | ||
|
||
### Action Type | ||
|
||
`forward-internal` | ||
|
||
### Configuration Fields | ||
|
||
| Parameter | Type | Description | | ||
| ---------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------ | | ||
| `url` | `string` | **Required.** URL of the Endpoint to forward traffic to. | | ||
| `binding` | `string` | Binding of the Endpoint (only `private` is currently supported). | | ||
| `on_error` | `string` | Whether or not further actions in the Traffic Policy should run if there is an error. Must be either `halt` (default) or `continue`. | | ||
|
||
### Supported Directions | ||
|
||
- `inbound` | ||
|
||
### Supported Schemes | ||
|
||
- `https` | ||
- `http` | ||
- `tls` | ||
- `tcp` |
65 changes: 65 additions & 0 deletions
65
traffic-policy/actions/forward-internal/examples/basic-example.mdx
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,65 @@ | ||
import ConfigExample from "/src/components/ConfigExample.tsx"; | ||
|
||
### Basic Example | ||
|
||
This example configuration will set up a public endpoint (`forward-internal-example.ngrok.io`) forwarding all traffic it receives to a private endpoint (`example.private`) that forwards the request to port `80` on your local machine. Since it is forwarding all traffic to the private endpoint, no traffic will be sent to `8080` which is the upstream port for the public endpoint. | ||
|
||
#### Example Traffic Policy Document | ||
|
||
<ConfigExample | ||
snippetText={null} | ||
showLineNumbers={true} | ||
jsonMetastring="{5-51}" | ||
yamlMetastring="{4-28}" | ||
config={{ | ||
inbound: [ | ||
{ | ||
actions: [ | ||
{ | ||
type: "forward-internal", | ||
config: { | ||
url: "https://example.private", | ||
}, | ||
}, | ||
], | ||
}, | ||
], | ||
}} | ||
/> | ||
|
||
#### Start Private Endpoint | ||
|
||
```shell | ||
ngrok http 80 --url example.private --binding private | ||
``` | ||
|
||
#### Start Public Endpoint with Traffic Policy | ||
|
||
```shell | ||
ngrok http 8080 --url forward-internal-example.ngrok.io --traffic-policy-file /path/to/policy.yml | ||
``` | ||
|
||
### Example Request | ||
|
||
```shell | ||
$ 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 private endpoint `https://example.private` 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 | ||
``` |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,5 @@ | ||
import BasicExample from "./basic-example.mdx"; | ||
|
||
## Examples | ||
|
||
<BasicExample /> |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,3 @@ | ||
## Overview | ||
|
||
The **Forward Internal** Traffic Policy action enables you to forward traffic from an endpoint to a private 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. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1 @@ | ||
This action does not set any variables after it has been executed. |