package envoy.type.matcher.v3

Get desktop application:
View/edit binary Protocol Buffers messages

Match an IP against a repeated CIDR range. This matcher is intended to be used in other matchers, for example in the filter state matcher to match a filter state object as an IP.

Used in: FilterStateMatcher

• repeated xds.core.v3.CidrRange ranges = 1

Specifies the way to match a double value.

Used in: ValueMatcher

• oneof match_pattern

  • v3.DoubleRange range = 1

    If specified, the input double value must be in the range specified here. Note: The range is using half-open interval semantics [start, end).

  • double exact = 2

    If specified, the input double value must be equal to the value specified here.

FilterStateMatcher provides a general interface for matching the filter state objects.

Used in: config.rbac.v3.Principal, config.route.v3.RouteMatch

• string key = 1

  The filter state key to retrieve the object.

• oneof matcher

  • StringMatcher string_match = 2

    Matches the filter state object as a string value.

  • AddressMatcher address_match = 3

    Matches the filter state object as a ip Instance.

Match input indicates that matching should be done on a specific request header. The resulting input string will be all headers for the given key joined by a comma, e.g. if the request contains two 'foo' headers with value 'bar' and 'baz', the input string will be 'bar,baz'. [#comment:TODO(snowp): Link to unified matching docs.] [#extension: envoy.matching.inputs.request_headers]

• string header_name = 1

  The request header to match on.

Match input indicates that matching should be done on a specific query parameter. The resulting input string will be the first query parameter for the value 'query_param'. [#extension: envoy.matching.inputs.query_params]

• string query_param = 1

  The query parameter to match on.

Match input indicates that matching should be done on a specific request trailer. The resulting input string will be all headers for the given key joined by a comma, e.g. if the request contains two 'foo' headers with value 'bar' and 'baz', the input string will be 'bar,baz'. [#comment:TODO(snowp): Link to unified matching docs.] [#extension: envoy.matching.inputs.request_trailers]

• string header_name = 1

  The request trailer to match on.

Match input indicating that matching should be done on a specific response header. The resulting input string will be all headers for the given key joined by a comma, e.g. if the response contains two 'foo' headers with value 'bar' and 'baz', the input string will be 'bar,baz'. [#comment:TODO(snowp): Link to unified matching docs.] [#extension: envoy.matching.inputs.response_headers]

• string header_name = 1

  The response header to match on.

Match input indicates that the matching should be done on the class of the response status code. For eg: 1xx, 2xx, 3xx, 4xx or 5xx.

(message has no fields)

Match input indicates that matching should be done on the response status code.

(message has no fields)

Match input indicates that matching should be done on a specific response trailer. The resulting input string will be all headers for the given key joined by a comma, e.g. if the request contains two 'foo' headers with value 'bar' and 'baz', the input string will be 'bar,baz'. [#comment:TODO(snowp): Link to unified matching docs.] [#extension: envoy.matching.inputs.response_trailers]

• string header_name = 1

  The response trailer to match on.

Specifies the way to match a list value.

Used in: ValueMatcher

• oneof match_pattern

  • ValueMatcher one_of = 1

    If specified, at least one of the values in the list must match the value specified.

Specifies a list of ways to match a string.

Used in: config.metrics.v3.StatsMatcher, extensions.filters.http.ext_authz.v3.AuthorizationRequest, extensions.filters.http.ext_authz.v3.AuthorizationResponse, extensions.filters.http.ext_authz.v3.ExtAuthz, extensions.filters.http.ext_proc.v3.HeaderForwardingRules

• repeated StringMatcher patterns = 1

[#next-major-version: MetadataMatcher should use StructMatcher]

Used in: config.accesslog.v3.MetadataFilter, config.rbac.v3.Permission, config.rbac.v3.Principal, config.rbac.v3.SourcedMetadata, config.route.v3.RouteMatch, extensions.filters.http.ext_authz.v3.ExtAuthz, extensions.filters.network.ext_authz.v3.ExtAuthz

• string filter = 1

  The filter name to retrieve the Struct from the Metadata.

• repeated MetadataMatcher.PathSegment path = 2

  The path to retrieve the Value from the Struct.

• optional ValueMatcher value = 3

  The MetadataMatcher is matched if the value retrieved by path is matched to this value.

• bool invert = 4

  If true, the match result will be inverted.

Specifies the segment in a path to retrieve value from Metadata. Note: Currently it's not supported to retrieve a value from a list in Metadata. This means that if the segment key refers to a list, it has to be the last segment in a path.

Used in: MetadataMatcher

• oneof segment

  • string key = 1

    If specified, use the key to retrieve the value in a Struct.

Specifies the way to match a Node. The match follows AND semantics.

Used in: service.status.v3.ClientStatusRequest

• optional StringMatcher node_id = 1

  Specifies match criteria on the node id.

• repeated StructMatcher node_metadatas = 2

  Specifies match criteria on the node metadata.

Specifies a list of alternatives for the match.

Used in: ValueMatcher

• repeated ValueMatcher value_matchers = 1

Specifies the way to match a path on HTTP request.

Used in: config.rbac.v3.Permission, config.rbac.v3.Principal, extensions.filters.http.oauth2.v3.OAuth2Config

• oneof rule

  • StringMatcher path = 1

    The ``path`` must match the URL path portion of the :path header. The query and fragment string (if present) are removed in the URL path portion. For example, the path ``/data`` will match the ``:path`` header ``/data#fragment?param=value``.

Describes how to match a string and then produce a new string using a regular expression and a substitution string.

Used in: config.route.v3.RedirectAction, config.route.v3.RouteAction, config.route.v3.RouteAction.HashPolicy.Header, extensions.filters.http.header_to_metadata.v3.Config.KeyValuePair, extensions.filters.network.thrift_proxy.filters.header_to_metadata.v3.HeaderToMetadata.KeyValuePair, extensions.filters.network.thrift_proxy.filters.payload_to_metadata.v3.PayloadToMetadata.KeyValuePair

• optional RegexMatcher pattern = 1

  The regular expression used to find portions of a string (hereafter called the "subject string") that should be replaced. When a new string is produced during the substitution operation, the new string is initially the same as the subject string, but then all matches in the subject string are replaced by the substitution string. If replacing all matches isn't desired, regular expression anchors can be used to ensure a single match, so as to replace just one occurrence of a pattern. Capture groups can be used in the pattern to extract portions of the subject string, and then referenced in the substitution string.

• string substitution = 2

  The string that should be substituted into matching portions of the subject string during a substitution operation to produce a new string. Capture groups in the pattern can be referenced in the substitution string. Note, however, that the syntax for referring to capture groups is defined by the chosen regular expression engine. Google's `RE2 <https://github.com/google/re2>`_ regular expression engine uses a backslash followed by the capture group number to denote a numbered capture group. E.g., ``\1`` refers to capture group 1, and ``\2`` refers to capture group 2.

A regex matcher designed for safety when used with untrusted input.

Used in: config.common.mutation_rules.v3.HeaderMutationRules, config.route.v3.HeaderMatcher, config.route.v3.RouteMatch, extensions.filters.http.json_to_metadata.v3.JsonToMetadata.MatchRules, RegexMatchAndSubstitute, StringMatcher

• oneof engine_type

  • RegexMatcher.GoogleRE2 google_re2 = 1

    Google's RE2 regex engine.

• string regex = 2

  The regex match string. The string must be supported by the configured engine. The regex is matched against the full string, not as a partial match.

Google's `RE2 <https://github.com/google/re2>`_ regex engine. The regex string must adhere to the documented `syntax <https://github.com/google/re2/wiki/Syntax>`_. The engine is designed to complete execution in linear time as well as limit the amount of memory used. Envoy supports program size checking via runtime. The runtime keys ``re2.max_program_size.error_level`` and ``re2.max_program_size.warn_level`` can be set to integers as the maximum program size or complexity that a compiled regex can have before an exception is thrown or a warning is logged, respectively. ``re2.max_program_size.error_level`` defaults to 100, and ``re2.max_program_size.warn_level`` has no default if unset (will not check/log a warning). Envoy emits two stats for tracking the program size of regexes: the histogram ``re2.program_size``, which records the program size, and the counter ``re2.exceeded_warn_level``, which is incremented each time the program size exceeds the warn level threshold.

Used in: RegexMatcher

• optional google.protobuf.UInt32Value max_program_size = 1

  This field controls the RE2 "program size" which is a rough estimate of how complex a compiled regex is to evaluate. A regex that has a program size greater than the configured value will fail to compile. In this case, the configured max program size can be increased or the regex can be simplified. If not specified, the default is 100. This field is deprecated; regexp validation should be performed on the management server instead of being done by each individual client. .. note:: Although this field is deprecated, the program size will still be checked against the global ``re2.max_program_size.error_level`` runtime value.

Specifies the way to match a string. [#next-free-field: 9]

Used in: config.common.matcher.v3.Matcher.MatcherList.Predicate.SinglePredicate, config.core.v3.HealthCheck.HttpHealthCheck, config.core.v3.Http1ProtocolOptions, config.metrics.v3.HistogramBucketSettings, config.rbac.v3.Permission, config.rbac.v3.Principal.Authenticated, config.route.v3.CorsPolicy, config.route.v3.HeaderMatcher, config.route.v3.QueryParameterMatcher, data.dns.v3.DnsTable, extensions.filters.http.aws_request_signing.v3.AwsRequestSigning, extensions.filters.http.cache.v3.CacheConfig, extensions.filters.http.cors.v3.CorsPolicy, extensions.filters.http.csrf.v3.CsrfPolicy, extensions.filters.http.jwt_authn.v3.JwtProvider, extensions.filters.network.dubbo_proxy.v3.MethodMatch, extensions.filters.network.generic_proxy.matcher.v3.KeyValueMatchEntry, extensions.filters.network.generic_proxy.matcher.v3.RequestMatcher, extensions.transport_sockets.tls.v3.CertificateValidationContext, extensions.transport_sockets.tls.v3.SubjectAltNameMatcher, FilterStateMatcher, ListStringMatcher, NodeMatcher, PathMatcher, ValueMatcher

• oneof match_pattern

  • string exact = 1

    The input string must match exactly the string specified here. Examples: * ``abc`` only matches the value ``abc``.

  • string prefix = 2

    The input string must have the prefix specified here. Note: empty prefix is not allowed, please use regex instead. Examples: * ``abc`` matches the value ``abc.xyz``

  • string suffix = 3

    The input string must have the suffix specified here. Note: empty prefix is not allowed, please use regex instead. Examples: * ``abc`` matches the value ``xyz.abc``

  • RegexMatcher safe_regex = 5

    The input string must match the regular expression specified here.

  • string contains = 7

    The input string must have the substring specified here. Note: empty contains match is not allowed, please use regex instead. Examples: * ``abc`` matches the value ``xyz.abc.def``

  • xds.core.v3.TypedExtensionConfig custom = 8

    Use an extension as the matcher type. [#extension-category: envoy.string_matcher]

• bool ignore_case = 6

  If true, indicates the exact/prefix/suffix/contains matching should be case insensitive. This has no effect for the safe_regex match. For example, the matcher ``data`` will match both input string ``Data`` and ``data`` if set to true.

StructMatcher provides a general interface to check if a given value is matched in google.protobuf.Struct. It uses ``path`` to retrieve the value from the struct and then check if it's matched to the specified value. For example, for the following Struct: .. code-block:: yaml fields: a: struct_value: fields: b: struct_value: fields: c: string_value: pro t: list_value: values: - string_value: m - string_value: n The following MetadataMatcher is matched as the path [a, b, c] will retrieve a string value "pro" from the Metadata which is matched to the specified prefix match. .. code-block:: yaml path: - key: a - key: b - key: c value: string_match: prefix: pr The following StructMatcher is matched as the code will match one of the string values in the list at the path [a, t]. .. code-block:: yaml path: - key: a - key: t value: list_match: one_of: string_match: exact: m An example use of StructMatcher is to match metadata in envoy.v*.core.Node.

Used in: NodeMatcher

• repeated StructMatcher.PathSegment path = 2

  The path to retrieve the Value from the Struct.

• optional ValueMatcher value = 3

  The StructMatcher is matched if the value retrieved by path is matched to this value.

Specifies the segment in a path to retrieve value from Struct.

Used in: StructMatcher

• oneof segment

  • string key = 1

    If specified, use the key to retrieve the value in a Struct.

Specifies the way to match a ProtobufWkt::Value. Primitive values and ListValue are supported. StructValue is not supported and is always not matched. [#next-free-field: 8]

Used in: extensions.matching.input_matchers.metadata.v3.Metadata, ListMatcher, MetadataMatcher, OrMatcher, StructMatcher

• oneof match_pattern

  Specifies how to match a value.

  • ValueMatcher.NullMatch null_match = 1

    If specified, a match occurs if and only if the target value is a NullValue.

  • DoubleMatcher double_match = 2

    If specified, a match occurs if and only if the target value is a double value and is matched to this field.

  • StringMatcher string_match = 3

    If specified, a match occurs if and only if the target value is a string value and is matched to this field.

  • bool bool_match = 4

    If specified, a match occurs if and only if the target value is a bool value and is equal to this field.

  • bool present_match = 5

    If specified, value match will be performed based on whether the path is referring to a valid primitive value in the metadata. If the path is referring to a non-primitive value, the result is always not matched.

  • ListMatcher list_match = 6

    If specified, a match occurs if and only if the target value is a list value and is matched to this field.

  • OrMatcher or_match = 7

    If specified, a match occurs if and only if any of the alternatives in the match accept the value.

NullMatch is an empty message to specify a null value.

Used in: ValueMatcher

(message has no fields)