--- WARNING: THIS IS AN AUTO-GENERATED FILE, DO NOT EDIT. PLEASE MODIFY THE ORIGINAL SOURCE IN THE 'https://github.com/istio/proxy' REPO source_repo: https://github.com/istio/proxy title: AttributeGen Config description: Configuration for Attribute Generation plugin. location: https://istio.io/docs/reference/config/proxy_extensions/attributegen.html layout: protoc-gen-docs generator: protoc-gen-docs schema: istio.attributegen weight: 20 number_of_entries: 3 ---

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 AttributeGene configurations produce the same attribute, the result of the last configuration will be visible to downstream filters.

AttributeGeneration

AttributeGeneration define generation of one attribute.

Field Type Description Required
outputAttribute 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

Match

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

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

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