Templating language

Learn how to define powerful staged transformations with the advanced templating engine.

Solo Enterprise for kgateway transformation templates are powered by v3.4 of the Inja template engine, which is inspired by the popular Jinja templating language in Python. The template lets you transform headers and body information of a request or response based on the header and body properties themselves.

The following YAML file shows the structure of the transformation template and all the attributes that you can configure. To learn more about each attribute, see Template attributes.

          transformation:
            template:
              advancedTemplate:
              bodyTransformation:                
              dynamicMetadataValues:
              escapeCharacters:
              extractors:
              headers: 
              headersToAppend: 
              headersToRemove:
              ignoreErrorOnParse:
              parseBodyBehavior:
              spanTransformer:

When writing your templates, you can take advantage of all the core Inja features, such as loops, conditional logic, and functions. In addition, Solo Enterprise for kgateway comes with custom Inja functions that you can use to transform request and response metadata more easily.

Custom Inja functions

When specifying your transformation template, you can leverage custom Solo Enterprise for kgateway functions that can help to extract and transform headers and bodies more easily. These functions are available in the headers, headersToAppend, bodyTransformation, and dynamicMetadataValues attributes of your transformation template.

Other common functions

You might use default Inja functions, such as if else or if exists. For an example, see the Change response status guide in simple transformations.

dynamic_metadata examples

The dynamic_metadata function reads values from Envoy dynamic metadata that other filters or earlier transformation stages have set.

Default namespace: Read a value that was set by dynamicMetadataValues in an earlier transformation stage. Because no namespace is specified, the default io.solo.transformation namespace is used.

{{ dynamic_metadata("my_key") }}

External auth claims: Read claims that were set by an external auth filter (such as dynamicMetadataFromClaims in an AuthConfig). Use the envoy.filters.http.ext_authz namespace and colon-separated keys to access nested values.

{{ dynamic_metadata("config_0:sub", "envoy.filters.http.ext_authz") }}

JWT authentication claims: Read claims from the JWT authentication filter.

{{ dynamic_metadata("provider:email", "envoy.filters.http.jwt_authn") }}

Template attributes

Learn more about the template attributes that you can use to transform headers and bodies of requests and responses.

advancedTemplate

This attribute determines which notation Solo Enterprise for kgateway uses when accessing elements in JSON structures. If set to true, Solo Enterprise for kgateway expects JSON pointer notation (time/start) instead of dot notation (time.start). The default value is false.

transformation:
  template:
    advancedTemplates: false

bodyTransformation

Apply transformation templates to request or response bodies. The bodyTransformation attribute allows you to specify the structure of the body that you want to return. For example, you can replace values in the body, extract values from headers and add them to the body, or return a static body.

transformation:
  template:  
    bodyTransformation: 
      type: Body
      body: 'This is my static body'

transformation:
  template:  
    bodyTransformation: 
      type: Body
      body: 'This is the value of the POD_NAME environment variable: {{env("POD_NAME")}}'

{
  "slideshow": {
    "editor": "Yours Truly",
    "date": "date of publication",
    "slides": [
      {
        "title": "Wake up to WonderWidgets!",
        "type": "all"
      },
      {
        "items": [
          "Why <em>WonderWidgets</em> are great",
          "Who <em>buys</em> WonderWidgets"
        ],
        "title": "Overview",
        "type": "all"
      }
    ],
    "title": "Sample Slide Show"
  }
}

transformation: 
  template:
    bodyTransformation: 
      type: Body
      body: '{"author": "{{ slideshow.author }}", "title": "{{ slideshow.title }}", "slides": "{{ slideshow.slides }}}'

{"author": "Yours Truly", "title": "Sample Slide Show", "slides": "[{"title":"Wake up to WonderWidgets!","type":"all"},{"items":["Why <em>WonderWidgets</em> are great","Who <em>buys</em> WonderWidgets"],"title":"Overview","type":"all"}]}% 

transformation: 
  template:
    extractors: 
      foo: 
        header: 'foo'
        # Use a nested capturing group to extract the foo query parameter
        regex: '.*'
    bodyTransformation: 
      type: MergeExtractorsToBody

{
  "Name": "Solo",
  "Favorites": {
    "Color": "Blue"
  }
}

{
  "Name": "Solo",
  "Favorites": {
    "Color": "Blue"
  },
  "foo": "foo-value-from-header"
}

transformation:
  template: 
    bodyTransformation: 
      type: Passthrough

dynamicMetadataValues

Use this attribute to define an Envoy Dynamic Metadata entry. This metadata can be used by other filters in the filter chain to implement custom behavior.

As an example, the following configuration creates a dynamic metadata entry in the com.example namespace with the key foo and the value of the foo header.

transformation:
  template: 
    dynamicMetadataValues: 
      - key: 'foo'
        value: '{{ header("foo") }}'
        metadataNamespace: "com.example"

Setting the metadataNamespace is optional. If not set, it defaults to the namespace of the Solo Enterprise for kgateway transformation filter name, such as io.solo.transformation.

A common use case for using this attribute is to include custom data in your access logs. For an example, see Enrich access logs.

escapeCharacters

Set to true to instruct Inja to preserve escaped characters in strings. This option is useful when using context from the request or response body to construct new JSON bodies.

transformation: 
  template:
    escapceCharacters: true

extractors

Use extractors to extract specific information from a header, query parameter, or the body that is sent in a request or response. You can later reference an extractor when injecting headers or transforming the request or response body.

Each extractor must use a regular expression (regex) to define which information you want to extract from the source. If the regex uses capturing groups, you can select the group match that you want to extract by using a subgroup attribute.

Extract values

Review the following examples to learn how to extract information from a header or body.

Use extractors

You can refer to extractors in the headers or bodyTransformation attributes to transform a header or body.

For example, to access the value of the foo extractor when transforming a header, use the following syntax:

extractors:
  foo:
    header: ':path'
    regex: '(.*foo=([^&]*).*)'
    subgroup: 2
header: 
  x-foo: "{{ foo }}"

Similarly, to refer to it when transforming the body, use the following syntax:

extractors:
  foo:
    header: ':path'
    regex: '(.*foo=([^&]*).*)'
    subgroup: 2
bodyTransformation: 
  type: Body
  body: 'This is the foo value: {{ foo }}'

To merge all extractors to an existing body, you can use the type: MergeExtractorsToBody setting. For more information, see bodyTransformation.

Extractor modes

Solo Enterprise for kgateway provides predefined extractor modes that you can use to transform the extracted information more easily.

  extractors:
     # The name of the extractor
    foo:
      # The extractor uses the :path pseudo header as the source, which contains the request/response path
      header: ':path'
      # Use a nested capturing group to extract the foo query parameter
      regex: '(.*foo=([^&]*).*)'
      # Select the second group match, which contains the value of the foo query parameter
      subgroup: 2
  header: 
    x-foo: "{{ foo }}"

extractors:
  # The name of the extractor
  BananaToOrange:
    # Capture the entire body and use that as the source for the transformation
    body: true
    # The extractor mode that replaces the first occurrence of the capturing group with 'replacement_text'
    mode: SingleReplace
    # Find 'banana' in the captured body
    regex: '.*(banana).*'
    # The regex capturing group that you want to replace with 'replacement_text'
    subgroup: 1
    # Replace the capturing group value with 'orange'.
    replacementText: 'orange'
bodyTransformation: 
  type: Body
  body: '{{ BananaToOrange }}'

extractors:
  # The name of the extractor
  FooToBar:
    # Capture the entire body and use that as the source for the transformation
    body: true
    # Find all instances of 'foo' in the source body
    regex: 'foo'
    # The extractor mode that replaces the all occurences of 'foo'
    mode: ReplaceAll
    # Replace all instances of 'foo' with 'bar'
    replacementText: 'bar'
bodyTransformation: 
  type: Body
  body: '{{ FooToBar }}'

headers

Apply transformation templates to request or response headers. The headers attribute allows you to specify the name of the resulting header key and applies a transformation template before determining the resulting header value. To transform the header value, you can leverage default and custom Inja functions, static values, or extractors.

transformation:
  template: 
    headers: 
      # The name of the resulting header and transformation template to apply. In this example,
      # you set the foo header to the value of 'static'. 
      foo: 'static'

transformation:
  template: 
    headers: 
      # The name of the resulting header and transformation template to apply. In this example, 
      # you retrieve the value of the 'bar' header and add that to the 'foo' header.
      foo: '{{ header("bar")}}'

{
  "Name": "Solo",
  "Favorites": {
    "Color": "Blue"
  }
}

transformation: 
  template:
    headers:
      color: '{{ Favorites.Color }}'

transformation:
  template:
    extractors:
      account_id:
        header: account
        regex: '(\w+)'
        subgroup: 1
    headers:
      x-account-solo: "{{ account_id }}-solo"

headersToAppend

Append values to existing headers. For example, to add multiple values to the same header, use the following transformation template:

transformation: 
  template:
    headersToAppend:
    - key: Set-Cookie
      value: 'customcookie2={{ request_header("Host") }}'
    - key: Set-Cookie
      value: 'customcookie3={{ request_header("Host") }}'

For an example, see Append headers.

headersToRemove

You can define the headers that you want to remove from a request or response. For example, to remove the User-Agent header, use the following transformation template:

transformation: 
  template:
    headersToRemove: ["User-Agent"]

ignoreErrorOnParse

Set this attribute to true if you want the Solo Enterprise for kgateway control plane to parse the body as a JSON, but to not return an error if the body is not formatted as valid JSON.

transformation: 
  template:
    ignoreErrorOnParse: true

parseBodyBehavior

Select how you want the Solo Enterprise for kgateway control plane to parse the request or response body.

• ParseAsJson: Instruct the control plane to parse the body as a JSON. Note that this is the default behavior in Solo Enterprise for kgateway. If parseBodyBehavior is not set, the body is automatically parsed as a JSON. If the control plane fails to parse the body as a JSON, a 400 Bad Request HTTP error is returned.

  
  transformation: 
    template:
      parseBodyBehavior: ParseAsJson

• DontParse: Buffer the body as plain text, but do not parse it. This is useful for bodies that are not formatted as a JSON. Note that some of the templating features are not available when treating the body as plain text. To skip buffering and parsing of the body completely, see the passthrough setting in bodyTransformation.

  
  transformation:
    template:
      parseBodyBehavior: DontParse