AttributeGen Config

3 minute read

AttributeGen plugin uses builtin attributes as inputs and produces new attributes that can be used by downstream plugins.

The following is an example of a configuration that produces one attribute named istio_operationId using request.url_path and request.method.

{
  "attributes": [
    {
      "output_attribute": "istio_operationId",
      "match": [
        {
          "value": "ListBooks",
          "condition": "request.url_path == '/books' && request.method ==
          'GET'"
        },
        {
          "value": "GetBook",
          "condition":
          "request.url_path.matches('^/shelves/[[:alnum:]]*/books/[[:alnum:]]*$')
          && request.method == 'GET'"
        },
        {
          "value": "CreateBook",
          "condition": "request.url_path == '/books/' && request.method ==
          'POST'"
        }
      ]
    }
  ]
}

If the Stats plugin runs after AttributeGen, it can use istio_operationId to populate a dimension on a metric.

The following is an example of response codes being mapped into a smaller number of response classes as the istio_responseClass attribute. For example, all response codes in 200s are mapped to 2xx.

{
  "attributes": [
    {
      "output_attribute": "istio_responseClass",
      "match": [
        {
          "value": "2xx",
          "condition": "response.code >= 200 && response.code <= 299"
        },
        {
          "value": "3xx",
          "condition": "response.code >= 300 && response.code <= 399"
        },
        {
          "value": "404",
          "condition": "response.code == 404"
        },
        {
          "value": "429",
          "condition": "response.code == 429"
        },
        {
          "value": "503",
          "condition": "response.code == 503"
        },
        {
          "value": "5xx",
          "condition": "response.code >= 500 && response.code <= 599"
        },
        {
          "value": "4xx",
          "condition": "response.code >= 400 && response.code <= 499"
        }
      ]
    }
  ]
}

If multiple AttributeGen configurations produce the same attribute, the result of the last configuration will be visible to downstream filters.

PluginConfig

Top level configuration to generate new attributes based on attributes of the proxied traffic.

Field	Type	Description	Required
`debug`	`bool`	The following settings should be rarely used. Enable debug for this filter.	No
`attributes`	`AttributeGeneration[]`	Multiple independent attribute generation configurations.	No

AttributeGeneration

AttributeGeneration define generation of one attribute.

Field Type Description Required

Field	Type	Description	Required
`output_attribute`	`string`	The name of the attribute that is populated on a successful match. An attribute name SHOULD NOT contain a `.`. You may use underscores for namespacing instead. Example: `istio_operationId` `istio_` attribute namespace is reserved by Istio. AttributeGeneration may fail to evaluate when an attribute is not available. For example, `response.code` may not be available when a request ends abruptly. When attribute generation fails, it will not populate the attribute. If the generated attribute is used by an authz plugin, it should account for the possibility that the attribute may be missing. Use `has(attribute_name)` function to check for presence of an attribute before using its value, and provide appropriate defaults. For example the following is a safe use of `response.code` `has(response.code)?response.code:200`	No
`match`	`Match[]`	Matches are evaluated in order until the first successful match. The value specified by the successful match is assgined to the output_attribute.	No

output_attribute

string

The name of the attribute that is populated on a successful match. An attribute name SHOULD NOT contain a .. You may use underscores for namespacing instead.

Example: istio_operationId

istio_ attribute namespace is reserved by Istio.

AttributeGeneration may fail to evaluate when an attribute is not available. For example, response.code may not be available when a request ends abruptly. When attribute generation fails, it will not populate the attribute.

If the generated attribute is used by an authz plugin, it should account for the possibility that the attribute may be missing. Use has(attribute_name) function to check for presence of an attribute before using its value, and provide appropriate defaults. For example the following is a safe use of response.code

has(response.code)?response.code:200

match

Match[]

Matches are evaluated in order until the first successful match. The value specified by the successful match is assgined to the output_attribute.

Match

If the condition evaluates to true then the Match returns the specified value.

Field Type Description Required

Field	Type	Description	Required
`condition`	`string`	The condition is a CEL expression that may use builtin attributes. Example: `{ "value": "GetBook", "condition": "request.url_path.matches('^/shelves/[[:alnum:]]/books/[[:alnum:]]$') && request.method == 'GET'" },` Note: CEL uses re2 regex library. Use anchors `{^, $}` to ensure that the regex evaluates efficiently. Note: `request.url_path` is normalized and stripped of query params. a Read only operation on books `{ "value": "ReadOnlyBooks", "condition": "request.url_path.startsWith('/books/') && in(request.method, ['GET', 'HEAD'])"}` An empty condition evaluates to `true` and should be used to provide a default value.	No
`value`	`string`	If condition evaluates to true, return the `value`.	No

condition

string

The condition is a CEL expression that may use builtin attributes.

Example:

   {
     "value": "GetBook",
     "condition":
     "request.url_path.matches('^/shelves/[[:alnum:]]*/books/[[:alnum:]]*$')
     && request.method == 'GET'"
   },

Note: CEL uses re2 regex library. Use anchors {^, $} to ensure that the regex evaluates efficiently.

Note: request.url_path is normalized and stripped of query params.

a Read only operation on books

{ "value": "ReadOnlyBooks",
  "condition": "request.url_path.startsWith('/books/') &&
  in(request.method, ['GET', 'HEAD'])"}

An empty condition evaluates to true and should be used to provide a default value.

value

string

If condition evaluates to true, return the value.