transformation.proto

Package: envoy.api.v2.filter.http

Types:

Source File: github.com/solo-io/gloo/projects/gloo/api/external/envoy/extensions/transformation/transformation.proto

FilterTransformations

"transformations": []envoy.api.v2.filter.http.TransformationRule
"stage": int
"logRequestResponseInfo": bool

Field Type Description
transformations []envoy.api.v2.filter.http.TransformationRule Specifies transformations based on the route matches. The first matched transformation will be applied. If there are overlapped match conditions, please put the most specific match first.
stage int Only RouteTransformations.RouteTransformation with matching stage will be used with this filter.
logRequestResponseInfo bool Logs request/response sensitive information By default, this is false so no request or response sensitive information is logged. If set to true, the filter will log the request/response body and headers before and after any transformation is applied.

TransformationRule

"match": .solo.io.envoy.config.route.v3.RouteMatch
"routeTransformations": .envoy.api.v2.filter.http.TransformationRule.Transformations

Field Type Description
match .solo.io.envoy.config.route.v3.RouteMatch The route matching parameter. Only when the match is satisfied, the “requires” field will apply. For example: following match will match all requests. .. code-block:: yaml match: prefix: /.
routeTransformations .envoy.api.v2.filter.http.TransformationRule.Transformations transformation to perform.

Transformations

"requestTransformation": .envoy.api.v2.filter.http.Transformation
"clearRouteCache": bool
"responseTransformation": .envoy.api.v2.filter.http.Transformation
"onStreamCompletionTransformation": .envoy.api.v2.filter.http.Transformation

Field Type Description
requestTransformation .envoy.api.v2.filter.http.Transformation Apply a transformation to requests.
clearRouteCache bool Clear the route cache if the request transformation was applied.
responseTransformation .envoy.api.v2.filter.http.Transformation Apply a transformation to responses.
onStreamCompletionTransformation .envoy.api.v2.filter.http.Transformation Apply a transformation in the onStreamComplete callback (for modifying headers and dynamic metadata for access logs).

RouteTransformations

"requestTransformation": .envoy.api.v2.filter.http.Transformation
"responseTransformation": .envoy.api.v2.filter.http.Transformation
"clearRouteCache": bool
"transformations": []envoy.api.v2.filter.http.RouteTransformations.RouteTransformation

Field Type Description
requestTransformation .envoy.api.v2.filter.http.Transformation deprecated. Use transformations[].request_match.request_transformation instead.
responseTransformation .envoy.api.v2.filter.http.Transformation deprecated. Use transformations[].request_match.response_transformation instead.
clearRouteCache bool deprecated. Use transformations[].request_match.clear_route_cache instead.
transformations []envoy.api.v2.filter.http.RouteTransformations.RouteTransformation

RouteTransformation

"stage": int
"requestMatch": .envoy.api.v2.filter.http.RouteTransformations.RouteTransformation.RequestMatch
"responseMatch": .envoy.api.v2.filter.http.RouteTransformations.RouteTransformation.ResponseMatch

Field Type Description
stage int Stage number. This transformation will only be processed by filters with the same stage number.
requestMatch .envoy.api.v2.filter.http.RouteTransformations.RouteTransformation.RequestMatch Only one of requestMatch or responseMatch can be set.
responseMatch .envoy.api.v2.filter.http.RouteTransformations.RouteTransformation.ResponseMatch Only one of responseMatch or requestMatch can be set.

RequestMatch

"match": .solo.io.envoy.config.route.v3.RouteMatch
"requestTransformation": .envoy.api.v2.filter.http.Transformation
"responseTransformation": .envoy.api.v2.filter.http.Transformation
"clearRouteCache": bool

Field Type Description
match .solo.io.envoy.config.route.v3.RouteMatch if no match is specified, will match all.
requestTransformation .envoy.api.v2.filter.http.Transformation transformation to perform.
responseTransformation .envoy.api.v2.filter.http.Transformation
clearRouteCache bool clear the route cache if the request transformation was applied.

ResponseMatch

"match": .envoy.api.v2.filter.http.ResponseMatcher
"responseTransformation": .envoy.api.v2.filter.http.Transformation

Field Type Description
match .envoy.api.v2.filter.http.ResponseMatcher
responseTransformation .envoy.api.v2.filter.http.Transformation transformation to perform.

ResponseMatcher

"headers": []solo.io.envoy.config.route.v3.HeaderMatcher
"responseCodeDetails": .solo.io.envoy.type.matcher.v3.StringMatcher

Field Type Description
headers []solo.io.envoy.config.route.v3.HeaderMatcher Specifies a set of headers that the route should match on. The router will check the response headers against all the specified headers in the route config. A match will happen if all the headers in the route are present in the request with the same values (or based on presence if the value field is not in the config).
responseCodeDetails .solo.io.envoy.type.matcher.v3.StringMatcher Only match responses with non empty response code details (this usually implies a local reply).

ResponseTransformationRule

"match": .envoy.api.v2.filter.http.ResponseMatcher
"responseTransformation": .envoy.api.v2.filter.http.Transformation

Field Type Description
match .envoy.api.v2.filter.http.ResponseMatcher
responseTransformation .envoy.api.v2.filter.http.Transformation transformation to perform.

Transformation

This message defines a transformation. This proto is for envoy filter config, not user-facing API.

"transformationTemplate": .envoy.api.v2.filter.http.TransformationTemplate
"headerBodyTransform": .envoy.api.v2.filter.http.HeaderBodyTransform
"transformerConfig": .solo.io.envoy.config.core.v3.TypedExtensionConfig
"logRequestResponseInfo": .google.protobuf.BoolValue

Field Type Description
transformationTemplate .envoy.api.v2.filter.http.TransformationTemplate Apply transformation templates. Only one of transformationTemplate, headerBodyTransform, or transformerConfig can be set.
headerBodyTransform .envoy.api.v2.filter.http.HeaderBodyTransform This type of transformation will make all the headers available in the response body. The resulting JSON body will consist of two attributes: ‘headers’, containing the headers, and ‘body’, containing the original body. Only one of headerBodyTransform, transformationTemplate, or transformerConfig can be set.
transformerConfig .solo.io.envoy.config.core.v3.TypedExtensionConfig Configuration for an externally implemented transformer, used by envoy transformation filter. Only one of transformerConfig, transformationTemplate, or headerBodyTransform can be set.
logRequestResponseInfo .google.protobuf.BoolValue Logs request/response sensitive information By default, this is false so no request or response sensitive information is logged. If set to true, the filter will log the request/response body and headers before and after this transformation is applied.

Extraction

Extractions can be used to extract information from the request/response. The extracted information can then be referenced in template fields.

"header": string
"body": .google.protobuf.Empty
"regex": string
"subgroup": int
"replacementText": .google.protobuf.StringValue
"mode": .envoy.api.v2.filter.http.Extraction.Mode

Field Type Description
header string Extract information from headers. Only one of header or body can be set.
body .google.protobuf.Empty Extract information from the request/response body. Only one of body or header can be set.
regex string The regex field specifies the regular expression used for matching against the source content. - In EXTRACT mode, the entire source must match the regex. subgroup selects the n-th capturing group, which determines the part of the match that you want to extract. If the regex does not match the source, the result of the extraction will be an empty value. - In SINGLE_REPLACE mode, the regex also needs to match the entire source. subgroup selects the n-th capturing group that is replaced with the content of replacement_text. If the regex does not match the source, the result of the replacement will be the source itself. - In REPLACE_ALL mode, the regex is applied repeatedly to find all occurrences within the source that match. Each matching occurrence is replaced with the value in replacement_text. In this mode, the configuration is rejected if subgroup is set. If the regex does not match the source, the result of the replacement will be the source itself.
subgroup int If your regex contains capturing groups, use this field to determine the group that you want to select. Defaults to 0. If set in EXTRACT and SINGLE_REPLACE modes, the subgroup represents the capturing group that you want to extract or replace in the source. The configuration is rejected if you set subgroup to a non-zero value when using thev REPLACE_ALL mode.
replacementText .google.protobuf.StringValue The value replacement_text is used to format the substitution for matched sequences in in an input string. This value is only legal in SINGLE_REPLACE and REPLACE_ALL modes. - In SINGLE_REPLACE mode, the subgroup selects the n-th capturing group, which represents the value that you want to replace with the string provided in replacement_text. - In REPLACE_ALL mode, each sequence that matches the specified regex in the input is replaced with the value inreplacement_text. The replacement_text can include special syntax, such as $1, $2, etc., to refer to capturing groups within the regular expression. The value that is specified in replacement_text is treated as a string, and is passed to std::regex_replace as the replacement string. For more informatino, see https://en.cppreference.com/w/cpp/regex/regex_replace.
mode .envoy.api.v2.filter.http.Extraction.Mode The mode of operation for the extraction. Defaults to EXTRACT.

Mode

The mode of operation for the extraction.

Name Description
EXTRACT Default mode. Extract the content of a specified capturing group. In this mode, subgroup selects the n-th capturing group, which represents the value that you want to extract.
SINGLE_REPLACE Replace the content of a specified capturing group. In this mode, subgroup selects the n-th capturing group, which represents the value that you want to replace with the string provided in replacement_text. Note: replacement_text must be set for this mode.
REPLACE_ALL Replace all regex matches with the value provided in replacement_text. Note: replacement_text must be set for this mode. Note: The configuration fails if subgroup is set to a non-zero value. Note: restrictions on the regex are different for this mode. See the regex field for more details.

TransformationTemplate

Defines a transformation template.

"advancedTemplates": bool
"extractors": map<string, .envoy.api.v2.filter.http.Extraction>
"headers": map<string, .envoy.api.v2.filter.http.InjaTemplate>
"headersToAppend": []envoy.api.v2.filter.http.TransformationTemplate.HeaderToAppend
"headersToRemove": []string
"body": .envoy.api.v2.filter.http.InjaTemplate
"passthrough": .envoy.api.v2.filter.http.Passthrough
"mergeExtractorsToBody": .envoy.api.v2.filter.http.MergeExtractorsToBody
"mergeJsonKeys": .envoy.api.v2.filter.http.MergeJsonKeys
"parseBodyBehavior": .envoy.api.v2.filter.http.TransformationTemplate.RequestBodyParse
"ignoreErrorOnParse": bool
"dynamicMetadataValues": []envoy.api.v2.filter.http.TransformationTemplate.DynamicMetadataValue
"escapeCharacters": bool

Field Type Description
advancedTemplates bool If set to true, use JSON pointer notation (e.g. “time/start”) instead of dot notation (e.g. “time.start”) to access JSON elements. Defaults to false. Please note that, if set to ‘true’, you will need to use the extraction function to access extractors in the template (e.g. ‘{{ extraction(“my_extractor”) }}'); if the default value of ‘false’ is used, extractors will simply be available by their name (e.g. ‘{{ my_extractor }}').
extractors map<string, .envoy.api.v2.filter.http.Extraction> Use this attribute to extract information from the request. It consists of a map of strings to extractors. The extractor will defines which information will be extracted, while the string key will provide the extractor with a name. You can reference extractors by their name in templates, e.g. “{{ my-extractor }}” will render to the value of the “my-extractor” extractor.
headers map<string, .envoy.api.v2.filter.http.InjaTemplate> Use this attribute to transform request/response headers. It consists of a map of strings to templates. The string key determines the name of the resulting header, the rendered template will determine the value. Any existing headers with the same header name will be replaced by the transformed header. If a header name is included in headers and headers_to_append, it will first be replaced the template in headers, then additional header values will be appended by the templates defined in headers_to_append. For example, the following header transformation configuration: yaml headers: x-header-one: {"text": "first {{inja}} template"} x-header-one: {"text": "second {{inja}} template"} headersToAppend: - key: x-header-one value: {"text": "first appended {{inja}} template"} - key: x-header-one value: {"text": "second appended {{inja}} template"} will result in the following headers on the HTTP message: x-header-one: first inja template x-header-one: first appended inja template x-header-one: second appended inja template.
headersToAppend []envoy.api.v2.filter.http.TransformationTemplate.HeaderToAppend Use this attribute to transform request/response headers. It consists of an array of string/template objects. Use this attribute to define multiple templates for a single header. Header template(s) defined here will be appended to any existing headers with the same header name, not replace existing ones. See headers documentation to see an example of usage.
headersToRemove []string Attribute to remove headers from requests. If a header is present multiple times, all instances of the header will be removed.
body .envoy.api.v2.filter.http.InjaTemplate Apply a template to the body. Only one of body, passthrough, mergeExtractorsToBody, or mergeJsonKeys can be set.
passthrough .envoy.api.v2.filter.http.Passthrough This will cause the transformation filter not to buffer the body. Use this setting if the response body is large and you don’t need to transform nor extract information from it. Only one of passthrough, body, mergeExtractorsToBody, or mergeJsonKeys can be set.
mergeExtractorsToBody .envoy.api.v2.filter.http.MergeExtractorsToBody Merge all defined extractors to the request/response body. If you want to nest elements inside the body, use dot separator in the extractor name. Only one of mergeExtractorsToBody, body, passthrough, or mergeJsonKeys can be set.
mergeJsonKeys .envoy.api.v2.filter.http.MergeJsonKeys A set of key-value pairs to merge into the JSON body. Each value will be rendered separately, and then placed into the JSON body at the specified key. There are a number of important caveats to using this feature: * This can only be used when the body is parsed as JSON. * This option does NOT work with advanced templates currently. Only one of mergeJsonKeys, body, passthrough, or mergeExtractorsToBody can be set.
parseBodyBehavior .envoy.api.v2.filter.http.TransformationTemplate.RequestBodyParse Determines how the body will be parsed. Defaults to ParseAsJson.
ignoreErrorOnParse bool If set to true, Envoy will not throw an exception in case the body parsing fails.
dynamicMetadataValues []envoy.api.v2.filter.http.TransformationTemplate.DynamicMetadataValue Use this field to set Dynamic Metadata.
escapeCharacters bool Use this field to set Inja behavior when rendering strings which contain characters that would need to be escaped to be valid JSON. Note that this sets the behavior for the entire transformation. Use raw_strings function for fine-grained control within a template.

HeaderToAppend

Defines a header-template pair to be used in headers_to_append

"key": string
"value": .envoy.api.v2.filter.http.InjaTemplate

Field Type Description
key string Header name.
value .envoy.api.v2.filter.http.InjaTemplate Apply a template to the header value.

DynamicMetadataValue

Defines an Envoy Dynamic Metadata entry.

"metadataNamespace": string
"key": string
"value": .envoy.api.v2.filter.http.InjaTemplate
"jsonToProto": bool

Field Type Description
metadataNamespace string The metadata namespace. Defaults to the filter namespace.
key string The metadata key.
value .envoy.api.v2.filter.http.InjaTemplate A template that determines the metadata value.
jsonToProto bool Instruct the filter to parse the rendered value as a proto Struct message before setting it as the metadata value.

RequestBodyParse

Determines how the body will be parsed.

Name Description
ParseAsJson Will attempt to parse the request/response body as JSON
DontParse The request/response body will be treated as plain text

InjaTemplate

Defines an Inja template that will be rendered by Gloo. In addition to the core template functions, the Gloo transformation filter defines the following custom functions:

"text": string

Field Type Description
text string

Passthrough


Field Type Description

MergeExtractorsToBody


Field Type Description

MergeJsonKeys

"jsonKeys": map<string, .envoy.api.v2.filter.http.MergeJsonKeys.OverridableTemplate>

Field Type Description
jsonKeys map<string, .envoy.api.v2.filter.http.MergeJsonKeys.OverridableTemplate> Map of key name -> template to render into the JSON body. Specified keys which don’t exist in the JSON body will be set, keys which do exist will be overriden. For example, given the following JSON body: { “key1”: “value1” } and the following MergeJsonKeys: { “key1”: “{{ header(“header1”) }}”, “key2”: “{{ header(“header2”) }}” } The resulting JSON body will be: { “key1”: “header1_value”, “key2”: “header2_value” }.

OverridableTemplate

"tmpl": .envoy.api.v2.filter.http.InjaTemplate
"overrideEmpty": bool

Field Type Description
tmpl .envoy.api.v2.filter.http.InjaTemplate Template to render.
overrideEmpty bool If set to true, the template will be set even if the rendered value is empty.

HeaderBodyTransform

"addRequestMetadata": bool

Field Type Description
addRequestMetadata bool When transforming a request, setting this to true will additionally add “queryString”, “queryStringParameters”, “multiValueQueryStringParameters”, “httpMethod”, “path”, and “multiValueHeaders” to the body.