Skip to content

Commit

Permalink
WIP: Add private endpoint docs
Browse files Browse the repository at this point in the history
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.
  • Loading branch information
euank committed Sep 18, 2024
1 parent 4998067 commit 34a6552
Show file tree
Hide file tree
Showing 9 changed files with 117 additions and 0 deletions.
11 changes: 11 additions & 0 deletions docs/http/traffic-policy/actions/forward-internal.mdx
Original file line number Diff line number Diff line change
@@ -0,0 +1,11 @@
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

<ActionOverview />
<ActionConfig />
<ActionBehavior />
<ActionExamples />
1 change: 1 addition & 0 deletions docs/http/traffic-policy/actions/index.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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 |
27 changes: 27 additions & 0 deletions docs/network-edge/private-endpoints.mdx
Original file line number Diff line number Diff line change
@@ -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/
1 change: 1 addition & 0 deletions sidebars.js
Original file line number Diff line number Diff line change
Expand Up @@ -233,6 +233,7 @@ const sidebars = {
items: [
"network-edge/index",
"network-edge/domains-and-tcp-addresses",
"network-edge/private-endpoints",
"network-edge/edges",
"network-edge/gslb",
"network-edge/tls-certificates",
Expand Down
9 changes: 9 additions & 0 deletions traffic-policy/actions/forward-internal/behavior.mdx
Original file line number Diff line number Diff line change
@@ -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).
27 changes: 27 additions & 0 deletions traffic-policy/actions/forward-internal/config.mdx
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 |
| ---------- | -------------------- | -------------------------------------------------------------------------------------------------------------------------- |
| `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`
Original file line number Diff line number Diff line change
@@ -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

<ConfigExample
snippetText={null}
showLineNumbers={true}
jsonMetastring="{5,8-14}"
yamlMetastring="{4,6-13}"
config={{
inbound: [
{
actions: [
{
type: "forward-internal",
config: {
binding: "private",
url: "http://my-endpoint.private",
},
},
],
},
],
}}
/>

This configuration will forward requests to an agent started with `ngrok http --url "http://my-endpoint.private" 80`
5 changes: 5 additions & 0 deletions traffic-policy/actions/forward-internal/examples/index.mdx
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
import BasicExample from "./1-basic-example.mdx";

## Examples

<BasicExample />
4 changes: 4 additions & 0 deletions traffic-policy/actions/forward-internal/index.mdx
Original file line number Diff line number Diff line change
@@ -0,0 +1,4 @@
## Overview

The **Forward Internal** Traffic Policy action enables you to forward requests
from an Endpoint to a Private Endpoint.

0 comments on commit 34a6552

Please sign in to comment.