From cd0d9d03485cdca219dc8bcbf8c193055b0a3906 Mon Sep 17 00:00:00 2001 From: Euan Kemp Date: Wed, 18 Sep 2024 05:14:10 +0000 Subject: [PATCH] WIP: Add private endpoint docs These are currently sparse. They also can't be merged until `--url` actually works with `.private`, since that's what we want to document, but it's currently got a service-side bug. This is WIP for those reasons. --- .../actions/forward-internal.mdx | 10 ++++++ docs/http/traffic-policy/actions/index.mdx | 1 + docs/network-edge/private-endpoints.mdx | 27 ++++++++++++++++ .../actions/forward-internal/behavior.mdx | 9 ++++++ .../actions/forward-internal/config.mdx | 27 ++++++++++++++++ .../examples/1-basic-example.mdx | 32 +++++++++++++++++++ .../forward-internal/examples/index.mdx | 5 +++ .../actions/forward-internal/index.mdx | 4 +++ 8 files changed, 115 insertions(+) create mode 100644 docs/http/traffic-policy/actions/forward-internal.mdx create mode 100644 docs/network-edge/private-endpoints.mdx create mode 100644 traffic-policy/actions/forward-internal/behavior.mdx create mode 100644 traffic-policy/actions/forward-internal/config.mdx create mode 100644 traffic-policy/actions/forward-internal/examples/1-basic-example.mdx create mode 100644 traffic-policy/actions/forward-internal/examples/index.mdx create mode 100644 traffic-policy/actions/forward-internal/index.mdx diff --git a/docs/http/traffic-policy/actions/forward-internal.mdx b/docs/http/traffic-policy/actions/forward-internal.mdx new file mode 100644 index 000000000..76b7852e1 --- /dev/null +++ b/docs/http/traffic-policy/actions/forward-internal.mdx @@ -0,0 +1,10 @@ +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"; +# Forward Internal + + + + + diff --git a/docs/http/traffic-policy/actions/index.mdx b/docs/http/traffic-policy/actions/index.mdx index 03254e7c7..806a1bb78 100644 --- a/docs/http/traffic-policy/actions/index.mdx +++ b/docs/http/traffic-policy/actions/index.mdx @@ -22,3 +22,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 private endpoint on your account. | Inbound | diff --git a/docs/network-edge/private-endpoints.mdx b/docs/network-edge/private-endpoints.mdx new file mode 100644 index 000000000..6d9b23160 --- /dev/null +++ b/docs/network-edge/private-endpoints.mdx @@ -0,0 +1,27 @@ +# Private Endpoints + +::::note +Private Endpoints are currently a beta feature, and only enabled for a limited +number of accounts. Please contact support if you are interested in using this feature. +:::: + +## Introduction + +In addition to [public endpoints][Public Endpoints], ngrok also supports creating Private Endpoints which are specific to your account. + +All private endpoints end in `.private`, and are specific to one ngrok account. + +Private endpoints cannot be accessed directly, but rather can only be accessed using the [forward-internal][forward-internal] policy action. + +### Creating a Private Endpoint + +A private endpoint may be created by specifying a binding of `private` for your endpoint. Specifically, when using the agent, a `private` endpoint may be created like so: + +```bash +ngrok http --binding private --url "some.name.private" 8080 +``` + +A private endpoint may listen on any port (such as `--url "some.name.private:1234"`) and any protocol scheme (such as `ngrok tcp` and `ngrok tls`). + +[Public Endpoints]: /network-edge/domains-and-tcp-addresses/ +[forward-internal]: /http/traffic-policy/actions/forward-internal/ diff --git a/traffic-policy/actions/forward-internal/behavior.mdx b/traffic-policy/actions/forward-internal/behavior.mdx new file mode 100644 index 000000000..96e203846 --- /dev/null +++ b/traffic-policy/actions/forward-internal/behavior.mdx @@ -0,0 +1,9 @@ +## Behavior + +This action forwards a request to a private endpoint. + +### Valid forward targets + +A request may only be forwarded to a private 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 Private Endpoint). diff --git a/traffic-policy/actions/forward-internal/config.mdx b/traffic-policy/actions/forward-internal/config.mdx new file mode 100644 index 000000000..e19975306 --- /dev/null +++ b/traffic-policy/actions/forward-internal/config.mdx @@ -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 | +| ---------- | -------------------- | -------------------------------------------------------------------------------------------------------------------------- | +| `binding` | `string` | The string `private`. | +| `url` | `string` | **Required.** The endpoint to forward to, such as `http://my-private-endpoint.private:1234` | +| `on_error` | 'halt' \| 'continue' | Whether a forward error is terminal (halts the action), or whether the policy continues to process later actions on error. | + +### Supported Directions + +- `inbound` + +### Supported Schemes + +- `https` +- `http` +- `tcp` +- `tls` diff --git a/traffic-policy/actions/forward-internal/examples/1-basic-example.mdx b/traffic-policy/actions/forward-internal/examples/1-basic-example.mdx new file mode 100644 index 000000000..b71478649 --- /dev/null +++ b/traffic-policy/actions/forward-internal/examples/1-basic-example.mdx @@ -0,0 +1,32 @@ +import ConfigExample from "/src/components/ConfigExample.tsx"; + +### Rewrite using Paths + +The following [Traffic Policy](/docs/http/traffic-policy/) +configuration demonstrates how to use the `forward-internal` action to forward to a Private Endpoint. + +#### Example Traffic Policy Document + + + +This configuration will forward requests to an agent started with `ngrok http --url "http://my-endpoint.private" 80` diff --git a/traffic-policy/actions/forward-internal/examples/index.mdx b/traffic-policy/actions/forward-internal/examples/index.mdx new file mode 100644 index 000000000..1a4591026 --- /dev/null +++ b/traffic-policy/actions/forward-internal/examples/index.mdx @@ -0,0 +1,5 @@ +import BasicExample from "./1-basic-example.mdx"; + +## Examples + + diff --git a/traffic-policy/actions/forward-internal/index.mdx b/traffic-policy/actions/forward-internal/index.mdx new file mode 100644 index 000000000..a0a5dc883 --- /dev/null +++ b/traffic-policy/actions/forward-internal/index.mdx @@ -0,0 +1,4 @@ +## Overview + +The **Forward Internal** Traffic Policy action enables you to forward requests +from an Endpoint to a Private Endpoint.