Traffic Policy
Overview
This module allows you to assign a policy to your endpoints containing a series of inbound and outbound rules that can be used to influence and control traffic to and from your upstream service.
Policy rules are composed of expressions that filter the traffic on which they are applicable and actions that should take effect.
Example Usage
- Agent CLI
- Agent Config
- SSH
- Go
- Javascript
- Python
- Rust
- Kubernetes Controller
ngrok http 80 --policy-file /path/to/policy.yml
inbound:
- name: FooBarParamNotFound
expressions:
- "'bar' in getQueryParam('foo')"
actions:
- type: "custom-response"
config:
status_code: 404
content: not found
headers:
content-type: text/plain
- name: "BazCookieForLargeRequests"
expressions:
- "!hasReqCookie('baz')"
- "req.content_length > 5000"
actions:
- type: deny
outbound:
- name: "LogUnsuccessfulRequests"
expressions:
- "res.status_code < 200 && res.status_code >= 300"
actions:
- type: log
config:
metadata:
hostport: example.com:443
success: false
tunnels:
example:
proto: http
addr: 80
policy:
inbound:
- name: FooBarParamNotFound
expressions:
- "'bar' in getQueryParam('foo')"
actions:
- type: "custom-response"
config:
status_code: 404
content: not found
headers:
content-type: text/plain
- name: "BazCookieForLargeRequests"
expressions:
- "!hasReqCookie('baz')"
- "req.content_length > 5000"
actions:
- type: deny
outbound:
- name: "LogUnsuccessfulRequests"
expressions:
- "res.status_code < 200 && res.status_code >= 300"
actions:
- type: log
config:
metadata:
hostport: example.com:443
success: false
Traffic Policy is not configurable via SSH
import (
"context"
"net"
"golang.ngrok.com/ngrok"
"golang.ngrok.com/ngrok/config"
"golang.ngrok.com/ngrok/policy"
)
func ngrokListener(ctx context.Context) (net.Listener, error) {
return ngrok.Listen(ctx,
config.HTTPEndpoint(
config.WithPolicy(
policy.Policy{
Inbound: []policy.Rule{
{
Name: "FooBarParamNotFound",
Expressions: []string{"'bar' in getQueryParam('foo')"},
Actions: []policy.Action{
{
Type: "custom-response",
Config: map[string]any{
"status_code": 400,
"content": "not found",
"headers": {
"content-type": "text/plain"
}
},
},
},
},
{
Name: "BazCookieForLargeRequests",
Expressions: []string{
"!hasReqCookie('baz')",
"req.content_length > 5000",
},
Actions: []policy.Action{
{
Type: "deny",
},
},
},
},
Outbound: []policy.Rule{
{
Name: "LogUnsuccessfulRequests",
Expressions: []string{"res.status_code < 200 && res.status_code >= 300"},
Actions: []policy.Action{
{
Type: "log",
Config: map[string]any{
"metadata": map[string]any{
"hostport": "example.com:443",
"success": false,
},
},
},
},
},
},
},
),
),
ngrok.WithAuthtokenFromEnv(),
)
}
Go Package Docs:
const ngrok = require("@ngrok/ngrok");
const fs = require("fs");
(async function () {
const listener = await ngrok.forward({
addr: 8080,
authtoken_from_env: true,
policy: fs.readFileSync("/path/to/policy.json", "utf8"),
});
console.log(`Ingress established at: ${listener.url()}`);
})();
{
"inbound":
[
{
"name": "FooBarParamNotFound",
"expressions": ["'bar' in getQueryParam('foo')"],
"actions":
[
{
"type": "custom-response",
"config":
{
"status_code": 404,
"content": "not found",
"headers": { "content-type": "text/plain" },
},
},
],
},
{
"name": "BazCookieForLargeRequests",
"expressions": ["!hasReqCookie('baz')", "req.content_length > 5000"],
"actions": [{ "type": "deny" }],
},
],
"outbound":
[
{
"name": "LogUnsuccessfulRequests",
"expressions": ["res.status_code < 200 && res.status_code >= 300"],
"actions":
[
{
"type": "log",
"config":
{
"metadata":
{ "hostport": "example.com:443", "success": false },
},
},
],
},
],
}
Javascript SDK Docs:
with open('/path/to/policy.json') as f:
policy = json.load(f)
listener = await session.http_endpoint().policy(policy).listen()
{
"inbound":
[
{
"name": "FooBarParamNotFound",
"expressions": ["'bar' in getQueryParam('foo')"],
"actions":
[
{
"type": "custom-response",
"config":
{
"status_code": 404,
"content": "not found",
"headers": { "content-type": "text/plain" },
},
},
],
},
{
"name": "BazCookieForLargeRequests",
"expressions": ["!hasReqCookie('baz')", "req.content_length > 5000"],
"actions": [{ "type": "deny" }],
},
],
"outbound":
[
{
"name": "LogUnsuccessfulRequests",
"expressions": ["res.status_code < 200 && res.status_code >= 300"],
"actions":
[
{
"type": "log",
"config":
{
"metadata":
{ "hostport": "example.com:443", "success": false },
},
},
],
},
],
}
Python SDK Docs:
Traffic Policy is coming soon via rust-sdk
---
kind: NgrokModuleSet
apiVersion: ingress.k8s.ngrok.com/v1alpha1
metadata:
name: policy-module
modules:
policy:
inbound:
- name: FooBarParamNotFound
expressions:
- "'bar' in getQueryParam('foo')"
actions:
- type: "custom-response"
config:
status_code: 404
content: not found
headers:
content-type: text/plain
- name: BazCookieForLargeRequests
expressions:
- "!hasReqCookie('baz')"
- "req.content_length > 5000"
actions:
- type: "deny"
outbound:
- name: LogUnsuccessfulRequests
expressions:
- "res.status_code != 200 && res.status_code != 204"
actions:
- type: "log"
config:
metadata:
hostport: example.com:443
success: false
---
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: example-ingress
annotations:
k8s.ngrok.com/modules: policy-module
spec:
ingressClassName: ngrok
rules:
- host: your-domain.ngrok.app
http:
paths:
- path: /
pathType: Prefix
backend:
service:
name: example-service
port:
number: 80
Behavior
Policy rules are evaluated sequentially in the order they are configured with inbound rules taking effect before the upstream server is reached and outbound rules taking effect after the upstream server responds. Whether or not the configured actions are performed is determined at runtime by the expressions.
Expression Evaluation
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 policy rule, its actions will always take effect.
See expressions for variable and macro definitions.
Action Execution
If a 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 policy, the actions will execute sequentially.
See actions for all available actions.
Reference
Configuration
Parameter | Description |
---|---|
inbound | A list of policy rules that will be applied to inbound traffic in the order specified. |
outbound | A list of policy rules that will be applied to outbound traffic in the order specified. |
name | Policy rules can optionally be given a name for convenience. |
expressions | A list of CEL expressions that filter which traffic a policy rule will apply to. |
actions | A list of actions that will execute sequentially if the associated policy rule's expressions all match on the traffic. |
type | The type of action. |
config | The configuration details of how an action should execute. Each action has its own configuration structure. |
Edges
Traffic Policy is an HTTPS Edge module which can be applied to Routes.
The Traffic Policy module can be configured via the ngrok dashboard or API.