Rules

Describes the rules used to configure Mixer’s policy and telemetry features.

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
FieldTypeDescription
handlerstring

Required. Fully qualified name of the handler to invoke. Must match the name of a Handler.

instancesstring[]

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.

FieldTypeDescription
revisionstring

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

namestring

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.

attributesmap<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.

FieldTypeDescription
descriptionstring

Optional. A human-readable description of the attribute’s purpose.

valueTypeValueType

Required. The type of data carried by this attribute.

Connection

Connection allows the operator to specify the endpoint for out-of-process infrastructure backend. Connection is part of the handler custom resource and is specified alongside adapter specific configuration.

FieldTypeDescription
addressstring

The address of the backend.

DNSName

An instance field of type DNSName denotes that the expression for the field must evalaute to ValueType.DNS_NAME

Objects of type DNSName are also passed to the adapters during request-time for the instance fields of type DNSName

FieldTypeDescription
valuestring

DNSName encoded as string.

Duration

An instance field of type Duration denotes that the expression for the field must evalaute to ValueType.DURATION

Objects of type Duration are also passed to the adapters during request-time for the instance fields of type Duration

FieldTypeDescription
valuegoogle.protobuf.Duration

Duration encoded as google.protobuf.Duration.

EmailAddress

DO NOT USE !! Under Development An instance field of type EmailAddress denotes that the expression for the field must evalaute to ValueType.EMAIL_ADDRESS

Objects of type EmailAddress are also passed to the adapters during request-time for the instance fields of type EmailAddress

FieldTypeDescription
valuestring

EmailAddress encoded as string.

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 for the prometheus adapter. The example is in the form of a kubernetes resource: * The metadata.name is the name of the handler * The kind refers to the adapter name * The spec block represents adapter-specific configuration as well as the connection information

### Sample-1: No connection specified (for compiled in adapters)
### Note: if connection information is not specified, the adapter configuration is directly inside
### `spec` block. This is going to be DEPRECATED in favor of Sample-2
apiVersion: "config.istio.io/v1alpha2"
kind: prometheus
metadata:
  name: handler
  namespace: istio-system
spec:
  metrics:
  - name: request_count
    instance_name: requestcount.metric.istio-system
    kind: COUNTER
    label_names:
    - source_service
    - source_version
    - destination_service
    - destination_version
---
### Sample-2: With connection information (for out-of-process adapters)
### Note: Unlike sample-1, the adapter configuration is parallel to `connection` and is nested inside `param` block.
apiVersion: "config.istio.io/v1alpha2"
kind: prometheus
metadata:
  name: handler
  namespace: istio-system
spec:
  param:
    metrics:
    - name: request_count
      instance_name: requestcount.metric.istio-system
      kind: COUNTER
      label_names:
      - source_service
      - source_version
      - destination_service
      - destination_version
  connection:
    address: localhost:8090
---
FieldTypeDescription
namestring

Required. Must be unique in the entire mixer configuration. Used by Actions to refer to this handler.

compiledAdapterstring

Required. The name of the compiled in adapter this handler instantiates. For referencing non compiled-in adapters, use the adapter field instead.

The value must match the name of the available adapter Mixer is built with. An adapter’s name is typically a constant in its code.

adapterstring

Required. The name of a specific adapter implementation. For referencing compiled-in adapters, use the compiled_adapter field instead.

An adapter’s implementation name is typically a constant in its code.

paramsgoogle.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.

connectionConnection

Optional. Information on how to connect to the out-of-process adapter. This is used if the adapter is not compiled into Mixer binary and is running as a separate process.

IPAddress

An instance field of type IPAddress denotes that the expression for the field must evalaute to ValueType.IP_ADDRESS

Objects of type IPAddress are also passed to the adapters during request-time for the instance fields of type IPAddress

FieldTypeDescription
valuebytes

IPAddress encoded as bytes.

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
FieldTypeDescription
namestring

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.

compiledTemplatestring

Required. The name of the compiled in template this instance creates instances for. For referencing non compiled-in templates, use the template field instead.

The value must match the name of the available template Mixer is built with.

templatestring

Required. The name of the template this instance creates instances for. For referencing compiled-in templates, use the compiled_template field instead.

The value must match the name of the available template in scope.

paramsgoogle.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
FieldTypeDescription
matchstring

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
actionsAction[]

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

TimeStamp

An instance field of type TimeStamp denotes that the expression for the field must evalaute to ValueType.TIMESTAMP

Objects of type TimeStamp are also passed to the adapters during request-time for the instance fields of type TimeStamp

FieldTypeDescription
valuegoogle.protobuf.Timestamp

TimeStamp encoded as google.protobuf.Timestamp.

Uri

DO NOT USE !! Under Development An instance field of type Uri denotes that the expression for the field must evalaute to ValueType.URI

Objects of type Uri are also passed to the adapters during request-time for the instance fields of type Uri

FieldTypeDescription
valuestring

Uri encoded as string.

Value

An instance field of type Value denotes that the expression for the field is of dynamic type and can evalaute to any ValueType enum values. For example, when authoring an instance configuration for a template that has a field data of type istio.policy.v1beta1.Value, both of the following expressions are valid data: source.ip | ip("0.0.0.0"), data: request.id | ""; the resulting type is either ValueType.IP_ADDRESS or ValueType.STRING for the two cases respectively.

Objects of type Value are also passed to the adapters during request-time. There is a 1:1 mapping between oneof fields in Value and enum values inside ValueType. Depending on the expression’s evaluated ValueType, the equivalent oneof field in Value is populated by Mixer and passed to the adapters.

FieldTypeDescription
stringValuestring (oneof)

Used for values of type STRING

int64Valueint64 (oneof)

Used for values of type INT64

doubleValuedouble (oneof)

Used for values of type DOUBLE

boolValuebool (oneof)

Used for values of type BOOL

ipAddressValueIPAddress (oneof)

Used for values of type IPAddress

timestampValueTimeStamp (oneof)

Used for values of type TIMESTAMP

durationValueDuration (oneof)

Used for values of type DURATION

emailAddressValueEmailAddress (oneof)

Used for values of type EmailAddress

dnsNameValueDNSName (oneof)

Used for values of type DNSName

uriValueUri (oneof)

Used for values of type Uri

ValueType

ValueType describes the types that values in the Istio system can take. These are used to describe the type of Attributes at run time, describe the type of the result of evaluating an expression, and to describe the runtime type of fields of other descriptors.

NameDescription
VALUE_TYPE_UNSPECIFIED

Invalid, default value.

STRING

An undiscriminated variable-length string.

INT64

An undiscriminated 64-bit signed integer.

DOUBLE

An undiscriminated 64-bit floating-point value.

BOOL

An undiscriminated boolean value.

TIMESTAMP

A point in time.

IP_ADDRESS

An IP address.

EMAIL_ADDRESS

An email address.

URI

A URI.

DNS_NAME

A DNS name.

DURATION

A span between two points in time.

STRING_MAP

A map string -> string, typically used by headers.