Skip to content

Commit

Permalink
update cloud endpoint routing guide
Browse files Browse the repository at this point in the history
  • Loading branch information
@kaganjd
kaganjd committed Jan 8, 2025
1 parent e34a36b commit 98545b2
Show file tree
Hide file tree
Showing 2 changed files with 23 additions and 129 deletions.
146 changes: 23 additions & 123 deletions docs/guides/other-guides/forwarding-and-load-balancing-with-cloud-endpoints.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -18,13 +18,7 @@ import Tabs from "@theme/Tabs";

<!-- Guide -->

:::warning

Cloud endpoints are currently in private beta. The functionality listed below is not yet publicly available.

:::

This guide provides an example of using an ngrok Cloud Endpoint to route traffic between multiple internal endpoints.
This guide provides an example of using an ngrok Cloud Endpoint to route traffic to an internal endpoint.

## Core Concepts

Expand All @@ -34,99 +28,19 @@ This guide provides an example of using an ngrok Cloud Endpoint to route traffic

## Prerequisites

To follow this guide, you will need a local computer with `ngrok` installed. [You can download ngrok here.](https://download.ngrok.com).

If you are going to be following along using the **ngrok CLI**, you will need:

- An [ngrok API key](https://dashboard.ngrok.com/api) configured on your [ngrok agent](/docs/agent/#api-keys).

If you are going to be following along using **CURL**, you will need:

- An [ngrok API key](https://dashboard.ngrok.com/api) as an environment variable named `NGROK_API_KEY`.

## **Step 1** — Create an Internal Endpoint

Let's start by creating a internal endpoint, initiated from the agent.
The endpoints will be in HTTP for this guide, but you can also use TCP or TLS.

```bash
ngrok http 80 \
--url https://your-domain-name.internal
```

After running the above command, you should see an internal endpoint with an "online" status for your domain. This endpoint will route traffic to the app running at your local port 80.
You can set up any HTTP server to run on this port locally, and it the endpoint will internally route traffic to that server.

## **Step 2** - Create a Domain

Next, let's create the domain that the cloud endpoint will reside on.
For the purpose of this guide, we will create a ngrok HTTP domain.

<Tabs groupId="guide">
<TabItem value="cli" label="ngrok CLI" default>

```bash
ngrok api reserved-domains create \
--domain ${NGROK_SUBDOMAIN}.ngrok.app
```

- Replace or set `${NGROK_SUBDOMAIN}` as the subdomain you'd like to use for this guide.

After running, you should see the following:

```json
200 OK
{
"id":"rd_2MT5Bqt0UzU0mFQ0zr8m1UQWCfm",
...
}
```
To follow this guide, you will need a computer with `ngrok` installed. [You can download ngrok here.](https://download.ngrok.com).

</TabItem>
<TabItem value="curl" label="CURL">
## **Step 1** — Reserve a domain

```bash
curl \
-X POST https://api.ngrok.com/reserved_domains \
-H "Authorization: Bearer ${NGROK_API_KEY}" \
-H "Content-Type: application/json" \
-H "Ngrok-Version: 2" \
-d @- <<BODY
{
"domain":"${NGROK_SUBDOMAIN}.ngrok.app",
}
BODY
```
Visit https://dashboard.ngrok.com/domains and reserve a domain. This will be how your end users access your endpoint in the browser.

- Replace `NGROK_API_KEY` with your ngrok API key.
- Replace NGROK_SUBDOMAIN with the subdomain you'd like to use for this guide.
## **Step 2** — Create a public cloud endpoint

Running this command should give you the following output:

```json
200 OK
{
"id":"rd_2MT5Bqt0UzU0mFQ0zr8m1UQWCfm",
...
}
```
Once you've reserved a domain, visit https://dashboard.ngrok.com/endpoints to create a public endpoint linked to that domain

</TabItem>
<TabItem value="dash" label="ngrok Dashboard">
You can reserve a subdomain via [ngrok dashboard](https://dashboard.ngrok.com/domains/new).
After successfully reserving a domain, you should see it listed in the domains table.
</TabItem>
</Tabs>
## **Step 3** — Create a Traffic Policy for your cloud endpoint

When you have completed this step, you can move on to the next step.

## **Step 3** — Create a Traffic Policy for your Cloud Endpoint

Unlike agent endpoints in which traffic policies are optional,
cloud endpoints require a traffic policy so they know how to
handle incoming traffic. This guide will showcase one of the simplest
and most common use cases: forwarding traffic to other endpoints
(the internal endpoint we created in Step 1) via the forward action.
Cloud endpoints require a traffic policy so they know how to handle incoming traffic. This guide will showcase one of the simplest and most common use cases: forwarding traffic to a private endpoint via the `forward-internal` action.

<ConfigExample
snippetText={null}
Expand All @@ -138,8 +52,7 @@ and most common use cases: forwarding traffic to other endpoints
{
type: "forward-internal",
config: {
url: "https://your-domain-name.internal",
binding: "internal",
url: "https://the-internal-endpoint.internal",
},
},
],
Expand All @@ -148,46 +61,33 @@ and most common use cases: forwarding traffic to other endpoints
}}
/>

## **Step 4** — Create a ngrok Cloud Endpoint
## **Step 4** — Start an agent session

Now we can create a ngrok Cloud Endpoint that points to our
newly created internal endpoint. Cloud Endpoints can be created
via the API or ngrok dashboard.
At this point, you have a public endpoint with a domain and a traffic policy routing to the URL we defined in our traffic policy above, `https://the-internal-endpoint.internal`. But that URL doesn't exist on the public internet; we need to start an agent session so that requests to our public endpoint will be routed to our internal endpoint, served by the ngrok agent. So, locally, start an agent session with:

<Tabs groupId="guide">
<TabItem value="api" label="API" default>
We use the URL from Step 2 as the `url` value in the traffic policy, and the traffic policy from Step 3 as the `traffic-policy` value.
The binding is set to public so anyone can access our cloud endpoint.
`ngrok http 80 --url=https://the-internal-endpoint.internal`

```bash
ngrok api endpoints create \
--api-key YOUR_NGROK_API_KEY \
--bindings public \
--description "sample description" \
--metadata sample-metadata \
--url https://${NGROK_SUBDOMAIN}.ngrok.app
--traffic-policy '{"on_http_request":[{"actions":[{"type":"forward-internal","config":{"url":"https://clep.internal","binding":"internal"}}]}]}'
```
Make sure you have some sample application running on port 80.

- Replace NGROK_SUBDOMAIN with the value used in step 2.
## **Step 5** — See your endpoint in action

</TabItem>
<TabItem value="dash" label="ngrok Dashboard">
Coming soon!
</TabItem>
</Tabs>
Visit the public endpoint you created in Step 1 and see that you're routed to whatever application your ngrok agent is serving.

## **Step 5** — Load Balancing with Endpoint Pools

:::warning

Endpoint pools are currently in private beta. The functionality described below is not yet publicly available.

:::

Load balancing is simple with ngrok Endpoint Pools. Simply start another agent with the same internal endpoint URL,
and the traffic will be automatically load balanced between the two agents in the pool!

```bash
ngrok http 80 \
--url https://your-domain-name.internal
ngrok http 80 --url=https://the-internal-endpoint.internal
```

## Conclusion

And we're done! You've successfully created a cloud endpoint that can be accessed from the URL you reserved: `${NGROK_SUBDOMAIN}.ngrok.app`
The cloud endpoint will refer to its traffic policy and forward traffic to our internal endpoint. The internal endpoint finally exposes the local port on which it was created on in Step 1.
And you're done! You've successfully created a cloud endpoint that can be accessed from the URL you reserved. The cloud endpoint will refer to its traffic policy and forward traffic to our internal endpoint. The internal endpoint finally exposes the local port on which it was created on in Step 1.
6 changes: 0 additions & 6 deletions ...-guides/path-based-routing-and-policy-decentralization-with-cloud-endpoints.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -18,12 +18,6 @@ import Tabs from "@theme/Tabs";

<!-- Guide -->

:::warning

Cloud endpoints are currently in private beta. The functionality listed below is not yet publicly available.

:::

This guide provides an example on how to forward traffic to internal endpoints based on path using ngrok Cloud Endpoints. The cloud endpoint will have a traffic policy to route traffic to one of two internal endpoints depending on the path, but each internal endpoint will also have its own traffic policy to indepedently handle incoming traffic.

## Core Concepts
Expand Down

0 comments on commit 98545b2

Please sign in to comment.