From 4732a7b8fbab42c17822c29bbfa089664f51d7f5 Mon Sep 17 00:00:00 2001 From: Euan Kemp Date: Wed, 18 Sep 2024 05:14:10 +0000 Subject: [PATCH] Add more internal endpoint docs This updates the forward-internal docs and adds more information on Internal Endpoints. --- docs/http/traffic-policy/actions/index.mdx | 1 + sidebars.js | 1 + .../actions/forward-internal/behavior.mdx | 12 +++++++++++- traffic-policy/actions/forward-internal/config.mdx | 14 +++++++------- .../{basic-example.mdx => 1-basic-example.mdx} | 0 .../actions/forward-internal/examples/index.mdx | 2 +- 6 files changed, 21 insertions(+), 9 deletions(-) rename traffic-policy/actions/forward-internal/examples/{basic-example.mdx => 1-basic-example.mdx} (100%) diff --git a/docs/http/traffic-policy/actions/index.mdx b/docs/http/traffic-policy/actions/index.mdx index 7c575c5f4..240464514 100644 --- a/docs/http/traffic-policy/actions/index.mdx +++ b/docs/http/traffic-policy/actions/index.mdx @@ -23,3 +23,4 @@ Traffic Policy actions enable you to modify the behavior of traffic flowing thro | [remove-headers](remove-headers) | Remove headers from incoming requests or outgoing responses. | Inbound, Outbound | | [restrict-ips](restrict-ips) | Allow or deny traffic based on source IP. | Inbound | | [url-rewrite](url-rewrite) | Rewrite request URLs transparently using regular expressions. | Inbound | +| [forward-internal](forward-internal) | Forward the request to a internal endpoint on your account. | Inbound | diff --git a/sidebars.js b/sidebars.js index 0d335f05f..330aa9533 100644 --- a/sidebars.js +++ b/sidebars.js @@ -233,6 +233,7 @@ const sidebars = { items: [ "network-edge/index", "network-edge/domains-and-tcp-addresses", + "network-edge/internal-endpoints", "network-edge/edges", "network-edge/gslb", "network-edge/tls-certificates", diff --git a/traffic-policy/actions/forward-internal/behavior.mdx b/traffic-policy/actions/forward-internal/behavior.mdx index 0a1b3fc21..5281ab59b 100644 --- a/traffic-policy/actions/forward-internal/behavior.mdx +++ b/traffic-policy/actions/forward-internal/behavior.mdx @@ -1,6 +1,8 @@ ## 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 internal endpoint). You also may not forward traffic to a second internal endpoint or back to the original endpoint in a loop. +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. @@ -21,3 +23,11 @@ The action will also set the `X-Forwarded-For`, `X-Forwarded-Host`, and `X-Forwa 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. diff --git a/traffic-policy/actions/forward-internal/config.mdx b/traffic-policy/actions/forward-internal/config.mdx index 872981afe..3ea625051 100644 --- a/traffic-policy/actions/forward-internal/config.mdx +++ b/traffic-policy/actions/forward-internal/config.mdx @@ -9,11 +9,11 @@ reference for this action. ### Configuration Fields -| Parameter | Type | Description | -| ---------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------ | -| `url` | `string` | **Required.** URL of the Endpoint to forward traffic to. | -| `binding` | `string` | Binding of the Endpoint (only `internal` 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`. | +| Parameter | Type | Description | +| ---------- | -------------------- | -------------------------------------------------------------------------------------------------------------------------- | +| `binding` | `string` | Binding of the Endpoint (only `internal` is currently supported). | +| `url` | `string` | **Required.** The endpoint to forward to, such as `http://my-internal-endpoint.internal:1234` | +| `on_error` | 'halt' \| 'continue' | 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 @@ -21,7 +21,7 @@ reference for this action. ### Supported Schemes -- `https` - `http` -- `tls` +- `https` - `tcp` +- `tls` diff --git a/traffic-policy/actions/forward-internal/examples/basic-example.mdx b/traffic-policy/actions/forward-internal/examples/1-basic-example.mdx similarity index 100% rename from traffic-policy/actions/forward-internal/examples/basic-example.mdx rename to traffic-policy/actions/forward-internal/examples/1-basic-example.mdx diff --git a/traffic-policy/actions/forward-internal/examples/index.mdx b/traffic-policy/actions/forward-internal/examples/index.mdx index 79709200f..1a4591026 100644 --- a/traffic-policy/actions/forward-internal/examples/index.mdx +++ b/traffic-policy/actions/forward-internal/examples/index.mdx @@ -1,4 +1,4 @@ -import BasicExample from "./basic-example.mdx"; +import BasicExample from "./1-basic-example.mdx"; ## Examples