Traffic Policy Engine now supports dynamic configuration with CEL Interpolation

July 23, 2024
|
3
min read
Nijiko Yonskai

Welcome to the second installment of our series on ngrok’s Traffic Policy Module. In this blog post, we’ll delve into CEL Interpolation and CEL functions. CEL Interpolation is a powerful capability you can use to dynamically add details about the connection, request, or response through CEL variables and expressions. This gives you more flexibility and enhances your traffic policy, enabling a more dynamic and adaptable configuration.

Let’s dig in, and learn what CEL Interpolation is and how you can leverage it to enrich rules in your Traffic Policy documents.

What is CEL Interpolation?

CEL Interpolation allows you to create dynamic Traffic Policy configurations by embedding variables and expressions in your actions using the ${CEL} format. These expressions are evaluated at runtime, enabling you to customize responses or perform specific actions based on request data.

Example: Using CEL Interpolation with Custom Response Action

on_http_request:
  - expressions:
      - "!('authorization' in req.headers)"
    actions:
      - type: "custom-response"
        config:
          status_code: 401
          content: "Unauthorized access from ${req.user_agent}"

In the example above, the endpoint will return a custom response with a 401 status code if the authorization header is missing. The placeholder ${req.user_agent} will be interpolated and dynamically replaced with the value of the User-Agent request header.

Just as a note, CEL Interpolation is supported only in specific policy action configuration fields. Please refer to the documentation for each action to verify whether CEL Interpolation is available in that context.

Using functions in CEL Interpolation

In addition to Traffic Policy variables, CEL Interpolation allows the use of functions like split and join, as it treats everything inside curly brackets as CEL expressions. These functions make it easier to dynamically manipulate and format data, enhancing the flexibility of your Traffic Policy action configurations.

Example: Using CEL Interpolation with the List join Function

Traffic Policy Configuration

on_http_request:
  - expressions:
      - "req.method == 'GET'"
    actions:
      - type: "add-headers"
        config:
          headers:
            x-custom-header: "${['value1', req.headers['header1'].join(','), req.headers['header2'].join(',')].join(',')}"

Example Response

$ curl -i https://example.ngrok.app \
	-H "header1: hello" \
	-H "header2: world"
HTTP/2 200 OK
content-type: text/html
X-custom-header: value1,hello,world

In this example, when the HTTP request method is GET, a custom header x-custom-header is added to the request by concatenating value1 with the comma-separated values of header1 and header2. The join function is used to combine these lists into a single comma-separated string for the header value.

Start using CEL Interpolation to manage traffic to your apps and APIs, sign up for a free ngrok account today!

Learn more about ngrok and our traffic policy engine

Configure policies for your API gateway using CEL. Check out these resources:

Have questions or want to request a new feature? We’d love to hear from you, hit us up at support@ngrok.com.

Share this post
Nijiko Yonskai
Niji is a Principal Product Manager who helps shape ngrok user experience. Previously product at Kong and Postman.
Traffic Policy
Features
Production