Traffic Policy Engine - What are CEL variables?

We introduced Traffic Policy Module to simplify configuration across all ngrok platforms, whether it’s the cloud, API, SDKs, or Kubernetes. We will be writing a series of blog posts that dive deep into this module to showcase its powerful capabilities.

We will start with Common Expression Language (CEL) variables. A quick recap on CEL: CEL is a simple yet powerful language for evaluating expressions. It's designed for safety, performance, and ease of integration, making it ideal for policy evaluation, rule enforcement, and data transformation without requiring complex coding.

We have dedicated significant effort to ensuring consistency in variable names across the board. This ensures that regardless of where you use variables in the Traffic Policy Engine, the names remain uniform and intuitive. Understanding and effectively using CEL variables can significantly enhance your ability to create dynamic and powerful traffic filtering rules. In this post, we'll explore what CEL variables are, how they work, and provide practical examples to help you leverage them effectively in your Traffic Policy documents.

What are CEL variables?

CEL variables contain information extracted from the incoming connection, both requests and responses that can be used within Traffic Policy expressions. CEL variables provide information about the connection, identity, request, and response such as headers, method, URL and more. They enable you to create Traffic Policy rules that adapt to varying conditions, making your Traffic Policy documents more flexible and responsive.

Here are some key HTTP request variables you can use for requests:

• req.content_encoding: The encoding set in the Content-Encoding header for this request as a list.
• req.content_length: The content length of the body in bytes.
• req.content_type: The media type set in the Content-Type header for this request.
• req.headers: The request headers parsed as a map of lower-case names to values.
• req.method: The request method.
• req.url: The normalized full URL for this request.
• req.user_agent: The user-agent header value for this request.

For a complete list of available HTTP variables, click here.

How do I use CEL variables to filter traffic?

Here is an example of how you can use CEL variables to filter traffic using expressions:

1inbound:
2  - expressions:
3      - "req.method == 'POST' && req.content_type == 'application/json'"
4    actions:
5      - type: "log"
6        config:
7          metadata:
8	          message: "Received JSON POST request"

In this example, req.method and req.content_type are CEL variables that are dynamically looked up and evaluated for each incoming request. This means that the log action will trigger only if the request is a POST method with a JSON content type.

Learn more about ngrok and Traffic Policy

CEL variables add a layer of flexibility and control to your Traffic Policy documents. They allow you to leverage information from requests and shape traffic for various scenarios with appropriate responses. This enhances the flexibility of your Traffic Policy documents, making them more efficient and effective.

Start using these variables to manage traffic to your apps and APIs. You can reach us at support@ngrok.com. Or sign up for an account and get started today. Or, learn more about ngrok and traffic policy via these resources:

• Introducing ngrok's Traffic Policy module
• API Gateway Gallery: Drop in policy action templates
• Transform connectivity with ngrok

‍