About staged transformations

While simple transformations let you apply simple header and body transformations on a route, you can only define one transformation at a time. The transformation filter is added as a regular transformation and applied after external authentication.

With staged transformations, you can apply multiple transformations to a route and configure when to run a request or response transformation in the Envoy filter chain. Supported stages are early, regular, and postRouting.

  • Early transformations are applied after fault injection, but before CORS, external authentication, rate limiting, and other filters.
  • Regular transformations on the other hand are applied after external authentication and other filters.
  • Post-routing transformations are applied during the router filter chain. Note that the clearRouteCache setting does not work in this stage as the routing decision is already made.

The following diagram illustrates where early, regular, and post-routing transformations are placed in the Envoy filter chain.

Configuration format

Staged transformations are configured in a GlooTrafficPolicy. Unlike simple transformations, you cannot configure these types of transformations in a kgateway TrafficPolicy.

The following GlooTrafficPolicy shows the structure for how to configure staged transformations. Note that the early, regular, and postRouting transformations have the same structure.

  apiVersion: gloo.solo.io/v1alpha1
kind: GlooTrafficPolicy
metadata:
  name: transformation
  namespace: httpbin
spec:
  glooTransformation:
    stages:
      early: 
        requests:
        - clearRouteCache: bool
          matcher: 
          transformation:
            headerBody:
            template:
              advancedTemplate:
              bodyTransformation:                
              dynamicMetadataValues:
              escapeCharacters:
              extractors:
              headers: 
              headersToAppend: 
              headersToRemove:
              ignoreErrorOnParse:
              parseBodyBehavior:
              spanTransformer:
        responses: 
        - transformation:
            template:
            headerBody: 
          responseCodeDetails:
          matchers: 
      regular:
        requests:
        responses: 
      escapeCharacters:
      logRequestResponseInfo:
      postRouting:

early, regular, and postRouting

Define the stage at which you want to apply the transformation. For more information, see About staged transformations.

requests and responses

The requests and responses attributes configure request and response transformations respectively.

matchers

You can define complex matching conditions to configure when to apply a transformation on a request or response.

If you have multiple transformations that each define a specific matcher, only the first transformation that matches the request is applied. For responses, transformations are applied only if no transformation in requests matched a request.

transformation

The transformation attribute defines how to transform a matching request or response.

  • headerBody: This type of transformation returns all the headers in a JSON body. The JSON body has two attributes: headers, containing the headers, and body, containing the original body. If addRequestMetadata is set to true, queryString, queryStringParameters, multiValueQueryStringParameters, httpMethod, path, and multiValueHeaders also added to the body.
  • template: A transformation template allows you to define flexible and powerful transformation rules, including what information you want to extract from a header, query parameter, or body; how you want to transform this information; and where you want to add this information in your request or response. Similar to simple transformations, you can leverage the Gloo Gateway Inja template engine to define your transformation rules. For more information, see Templating language.

clearRoutingCache

Use this setting to clear the route cache after the request transformation was applied so that the gateway proxy must redo the routing decision. This setting is useful if you have transformations that modify headers and therefore must be routed to a different endpoint. By default, the routing cache is not automatically cleared.

Note that the clearRoutingCache setting is not supported in post-routing transformations as the routing decision is already made.

escapeCharacters

If set to true, Inja preserves escaped characters in strings. Note that this setting enables character escaping for all staged transformations. However, you can overwrite this setting with the escapeCharacters setting in a transformation template. For more information, see Templating language.

logRequestResponseInfo

Log request or response body and header information before and after all the transformations are applied. Note that this setting enables logging for all staged transformations.