Skip to main content

Traffic Policy

warning

Traffic Policy is currently in preview. Breaking changes may occur at any time with no notice, including changes to the structure of policy documents, the behaviors of policies, and the pricing of this feature.

Overview

This module enables you to assign a policy to your endpoints by defining a set of rules for the on_tcp_connect traffic management phase. These rules allow you to influence and control traffic to your upstream service.

Traffic Policy rules are composed of expressions that filter the traffic on which they are applicable and actions that should take effect.

Example Usage

ngrok tls 80 --traffic-policy-file /path/to/policy.yml
policy.yml
on_tcp_connect:
- name: "LimitToKnownIPs"
expressions:
- "conn.client_ip != '8.8.8.8'"
- "conn.client_ip != '9.9.9.9'"
actions:
- type: deny

Behavior

Traffic Policy rules are evaluated sequentially in the order they are configured with on_tcp_connect rules taking effect before the upstream server is reached. Whether or not the configured actions are performed is determined at runtime by the expressions.

Expression Evaluation

Traffic Policy expressions are written using the Common Expression Language (CEL). Policy expressions must evaluate to true in order for policy actions to take effect. There is no behavioral difference between adding multiple expressions to a single policy rule and having one single expression with multiple statements logically conjoined together (i.e. ["1 == 1 && 2 == 2"] is the same s ["1 == 1", "2 == 2"]).

If no expressions are specified on a traffic policy rule, its actions will always take effect.

Action Execution

If a traffic policy's expressions are evaluated as a match against a connection, the policy's actions will be executed. If multiple actions are defined on a traffic policy, the actions will execute sequentially.

See actions for all available actions.

Reference

Configuration

ParameterDescription
nameTraffic Policy rules can optionally be given a name for convenience.
expressionsA list of CEL expressions that filter which traffic a policy rule will apply to.
actionsA list of actions that will execute sequentially if the associated policy rule's expressions all match on the traffic.
typeThe type of action.
configThe configuration details of how an action should execute. Each action has its own configuration structure.

Edges

Traffic Policy is a TLS Edge module.

The Traffic Policy module can be configured vai the ngrok dashboard or API.