Prerequisites
- An ngrok account with an ngrok API key.
- The ngrok API documentation.
- Tools like
curlor Postman (or ngrok’s own API libraries). - Understanding of your existing edge configurations.
- YAML formatting skills for creating Traffic Policies.
- A text editor to prepare YAML payloads.
What you’ll be migrating
Set up environment
Make sure you have:
- NGROK_API_TOKEN (your personal or organization token).
- API Base URL:
https://api.ngrok.com.
List your edges
Use the ngrok API to list all existing edges:If a response includes a non-empty Be sure to keep your API rate limits in mind.
Repeat this process for:
next_page_uri you’ll want to follow it until it is null:/edges/tls/edges/tcp
Determine the target URL
Each edge has one or more
hostports. Use those to define a Cloud Endpoint url:Note, you’ll have to create a Cloud Endpoint for each
hostport attached to an edge if you want multiple hostports to service the same traffic flow.Create a Traffic Policy
Each Cloud Endpoint will have a YAML Traffic Policy.Here is the base structure of a Traffic Policy:Use only the relevant phases for the edge type.
Migrate routes (HTTPS only)
HTTPS edges have routes, and each route needs to be converted to a CEL expression based on its
match_type for use on every rule that is defined.Here are some example CEL expressions for routes based on the match_type:Create these for later use in each
expressions: block in your policy rules.Convert modules to actions
Each module on the edge or its routes maps to one or more policy actions:
You’ll want to translate each Module configuration to Action Configuration:Add these actions under the correct phase (with matching route expressions when the endpoint is HTTP or HTTPS).
Convert backends
Your edge’s backend defines where traffic goes. These should be placed after all other actions you defined above. These should be added to the end of the phase.Here, Here, an Agent Endpoint has been started with the URL Additionally, you cannot use the Since the CEL environment doesn’t support reduce or fold, you’ll have to use an external script to determine the cumulative weights, chance, and lookups:
Tunnel group backends
If the edge uses atunnel_group backend (identified by labels):- Construct an internal domain for each label (for example,
service=app→service-app.internal) - Forward traffic to each internal domain using the
forward-internalaction and fall through with theforward-internalaction. - Run the agent or create a Cloud Endpoint with that internal domain to receive traffic.
forward-internal is defined to forward to https://service-app.internal and when an error occurs (like the endpoint being offline) fallback to some custom text (by leveraging on_error: continue and custom-response) describing how to get back online (this is optional).Running internal Agent Endpoint via the CLI:https://service-app.internal which points to a service running locally on the machine on port 80.TCP/TLS backends
These are generally Tunnel Groups and should follow the same rules as above. However, wanted to call out that you should use theon_tcp_connect phase here instead:custom-response action for an HTTP fallback.HTTP response backends
Usecustom-response to serve static content:Failover backends
- Loop through the list of failover backends
- For each backend type, applying the same rules in group in sequence but on each Tunnel Group, use
on_error: continueto fall-through to the next group, or HTTP Response backend.
Weighted backends → Not yet supported
These are not officially supported today in Traffic Policies.You can pseudo-replicate this functionality today using multiple internal endpoints and therand macro to randomly send traffic:✏️ 8. Create the Cloud Endpoint
Each edgehostport should become a separate Cloud Endpoint with its configuration represented as JSON, and the traffic_policy embedded as stringified YAML.
Endpoint configuration object
⚠️ Ensure all newlines (\n) and indentations are preserved when stringifying YAML into JSON. It’s best to use a library or third-party service to stringify your YAML into an object and then generate the resulting Cloud Endpoint JSON object.Submit to: