Policy and Telemetry Rules

Action

Action describes which Handler to invoke and what data to pass to it for processing.

The following example instructs Mixer to invoke ‘prometheus-handler’ handler and pass it the object constructed using the instance ‘RequestCountByService’

  handler: prometheus-handler
  instances:
  - RequestCountByService

Field	Type	Description
`handler`	`string`	Required. Fully qualified name of the handler to invoke. Must match the `name` of a Handler.
`instances`	`string[]`	Required. Each value must match the fully qualified name of the Instances. Referenced instances are evaluated by resolving the attributes/literals for all the fields. The constructed objects are then passed to the `handler` referenced within this action.

AttributeManifest

AttributeManifest describes a set of Attributes produced by some component of an Istio deployment.

Field Type Description

Field	Type	Description
`revision`	`string`	Optional. The revision of this document. Assigned by server.
`name`	`string`	Required. Name of the component producing these attributes. This can be the proxy (with the canonical name “istio-proxy”) or the name of an `attributes` kind adapter in Mixer.
`attributes`	`map<string,AttributeManifest.AttributeInfo>`	The set of attributes this Istio component will be responsible for producing at runtime. We map from attribute name to the attribute’s specification. The name of an attribute, which is how attributes are referred to in aspect configuration, must conform to: `Name = IDENT { SEPARATOR IDENT };` Where `IDENT` must match the regular expression `a-z+` and `SEPARATOR` must match the regular expression `[\.-]`. Attribute names must be unique within a single Istio deployment. The set of canonical attributes are described at https://istio.io/docs/reference/attribute-vocabulary.html. Attributes not in that list should be named with a component-specific suffix such as request.count-my.component

revision

string

Optional. The revision of this document. Assigned by server.

name

string

Required. Name of the component producing these attributes. This can be the proxy (with the canonical name “istio-proxy”) or the name of an attributes kind adapter in Mixer.

attributes

map<string,AttributeManifest.AttributeInfo>

The set of attributes this Istio component will be responsible for producing at runtime. We map from attribute name to the attribute’s specification. The name of an attribute, which is how attributes are referred to in aspect configuration, must conform to:

Name = IDENT { SEPARATOR IDENT };

Where IDENT must match the regular expression *a-z*+ and SEPARATOR must match the regular expression [\.-].

Attribute names must be unique within a single Istio deployment. The set of canonical attributes are described at https://istio.io/docs/reference/attribute-vocabulary.html. Attributes not in that list should be named with a component-specific suffix such as request.count-my.component

AttributeManifest.AttributeInfo

AttributeInfo describes the schema of an Istio Attribute.

Istio Attributes

Istio uses attributes to describe runtime activities of Istio services. An Istio attribute carries a specific piece of information about an activity, such as the error code of an API request, the latency of an API request, or the original IP address of a TCP connection. The attributes are often generated and consumed by different services. For example, a frontend service can generate an authenticated user attribute and pass it to a backend service for access control purpose.

To simplify the system and improve developer experience, Istio uses shared attribute definitions across all components. For example, the same authenticated user attribute will be used for logging, monitoring, analytics, billing, access control, auditing. Many Istio components provide their functionality by collecting, generating, and operating on attributes. For example, the proxy collects the error code attribute, and the logging stores it into a log.

Design

Each Istio attribute must conform to an AttributeInfo in an AttributeManifest in the current Istio deployment at runtime. An AttributeInfo is used to define an attribute’s metadata: the type of its value and a detailed description that explains the semantics of the attribute type. Each attribute’s name is globally unique; in other words an attribute name can only appear once across all manifests.

The runtime presentation of an attribute is intentionally left out of this specification, because passing attribute using JSON, XML, or Protocol Buffers does not change the semantics of the attribute. Different implementations can choose different representations based on their needs.

HTTP Mapping

Because many systems already have REST APIs, it makes sense to define a standard HTTP mapping for Istio attributes that are compatible with typical REST APIs. The design is to map one attribute to one HTTP header, the attribute name and value becomes the HTTP header name and value. The actual encoding scheme will be decided later.

Field	Type	Description
`description`	`string`	Optional. A human-readable description of the attribute’s purpose.
`valueType`	`istio.mixer.v1.config.descriptor.ValueType`	Required. The type of data carried by this attribute.

Handler

Handler allows the operator to configure a specific adapter implementation. Each adapter implementation defines its own params proto.

In the following example we define a metrics handler using the Mixer’s prepackaged prometheus adapter. This handler doesn’t require any parameters.

name: prometheus-handler
adapter: prometheus
params:

Field	Type	Description
`name`	`string`	Required. Must be unique in the entire mixer configuration. Used by Actions to refer to this handler.
`adapter`	`string`	Required. The name of a specific adapter implementation. An adapter’s implementation name is typically a constant in its code.
`params`	`google.protobuf.Struct`	Optional. Depends on adapter implementation. Struct representation of a proto defined by the adapter implementation; this varies depending on the value of field `adapter`.

Instance

An Instance tells Mixer how to create instances for particular template.

Instance is defined by the operator. Instance is defined relative to a known template. Their purpose is to tell Mixer how to use attributes or literals to produce instances of the specified template at runtime.

The following example instructs Mixer to construct an instance associated with template ‘istio.mixer.adapter.metric.Metric’. It provides a mapping from the template’s fields to expressions. Instances produced with this instance can be referenced by Actions using name ‘RequestCountByService’.

- name: RequestCountByService
  template: istio.mixer.adapter.metric.Metric
  params:
    value: 1
    dimensions:
      source: source.service
      destination_ip: destination.ip

Field Type Description

Field	Type	Description
`name`	`string`	Required. The name of this instance Must be unique amongst other Instances in scope. Used by Action to refer to an instance produced by this instance.
`template`	`string`	Required. The name of the template this instance creates instances for. The value must match the name of the available template in scope.
`params`	`google.protobuf.Struct`	Required. Depends on referenced template. Struct representation of a proto defined by the template; this varies depending on the value of field `template`.

name

string

Required. The name of this instance

Must be unique amongst other Instances in scope. Used by Action to refer to an instance produced by this instance.

template

string

Required. The name of the template this instance creates instances for. The value must match the name of the available template in scope.

params

google.protobuf.Struct

Required. Depends on referenced template. Struct representation of a proto defined by the template; this varies depending on the value of field template.

Rule

A Rule is a selector and a set of intentions to be executed when the selector is true

The following example instructs Mixer to invoke ‘prometheus-handler’ handler for all services and pass it the instance constructed using the ‘RequestCountByService’ instance.

- match: destination.service == "*"
  actions:
  - handler: prometheus-handler
    instances:
    - RequestCountByService

Field Type Description

Field	Type	Description
`match`	`string`	Required. Match is an attribute based predicate. When Mixer receives a request it evaluates the match expression and executes all the associated `actions` if the match evaluates to true. A few example match: an empty match evaluates to `true` `true`, a boolean literal; a rule with this match will always be executed `destination.service == ratings*` selects any request targeting a service whose name starts with “ratings” `attr1 == "20" && attr2 == "30"` logical AND, OR, and NOT are also available
`actions`	`Action[]`	Optional. The actions that will be executed when match evaluates to `true`.

match

string

Required. Match is an attribute based predicate. When Mixer receives a request it evaluates the match expression and executes all the associated actions if the match evaluates to true.

A few example match:

an empty match evaluates to true
true, a boolean literal; a rule with this match will always be executed
destination.service == ratings* selects any request targeting a service whose name starts with “ratings”
attr1 == "20" && attr2 == "30" logical AND, OR, and NOT are also available

actions

Action[]

Optional. The actions that will be executed when match evaluates to true.

google.protobuf.Struct

Struct represents a structured data value, consisting of fields which map to dynamically typed values. In some languages, Struct might be supported by a native representation. For example, in scripting languages like JS a struct is represented as an object. The details of that representation are described together with the proto support for the language.

The JSON representation for Struct is JSON object.

Field	Type	Description
`fields`	`map<string,google.protobuf.Value>`	Unordered map of dynamically typed values.