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 objectconstructed using the instance ‘RequestCountByService’.

  handler: prometheus-handler
  instances:
  - RequestCountByService

AttributeManifest

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

Name = IDENT { SEPARATOR IDENT };

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 theoriginal IP address of a TCP connection. The attributes are often generatedand consumed by different services. For example, a frontend service cangenerate an authenticated user attribute and pass it to a backend service foraccess control purpose.

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

Design

Each Istio attribute must conform to an AttributeInfo in anAttributeManifest in the current Istio deployment at runtime. AnAttributeInfo is used to define an attribute’smetadata: the type of its value and a detailed description that explainsthe 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 thisspecification, because passing attribute using JSON, XML, or Protocol Buffersdoes not change the semantics of the attribute. Different implementationscan choose different representations based on their needs.

HTTP Mapping

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

Authentication

Authentication allows the operator to specify the authentication ofconnections to out-of-process infrastructure backend.

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.

DNSName

An instance field of type DNSName denotes that the expression for the field must evaluate toValueType.DNS_NAME

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

DirectHttpResponse

Direct HTTP response for a client-facing error message which can be attachedto an RPC error.

Duration

An instance field of type Duration denotes that the expression for the field must evaluate toValueType.DURATION

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

EmailAddress

DO NOT USE !! Under DevelopmentAn instance field of type EmailAddress denotes that the expression for the field must evaluate toValueType.EMAIL_ADDRESS

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

FractionalPercent.DenominatorType

Fraction percentages support several fixed denominator values.

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: handler
metadata:
  name: requestcount
  namespace: istio-system
spec:
  compiledAdapter: prometheus
  params:
    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: handler
metadata:
  name: requestcount
  namespace: istio-system
spec:
  compiledAdapter: prometheus
  params:
    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
---

HttpStatusCode

HTTP response codes.For more details: http://www.iana.org/assignments/http-status-codes/http-status-codes.xhtml

IPAddress

An instance field of type IPAddress denotes that the expression for the field must evaluate toValueType.IP_ADDRESS

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

Instance

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

Instance is defined by the operator. Instance is defined relative to a knowntemplate. Their purpose is to tell Mixer how to use attributes or literals to produceinstances 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.name
      destination_ip: destination.ip

params:  # Pass the required attribute data to the adapter  source_uid: source.uid | ""attribute_bindings:  # Fill the new attributes from the adapter produced output  source.namespace: output.source_namespace

Mutual

Mutual let operator specify TLS configuration for Mixer as client if mutual TLS is used tosecure connection to adapter backend.

OAuth

OAuth let operator specify config to fetch access token via oauth when usingTLS for connection to the backend.

Rule

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

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

- match: match(destination.service.host, "*")
  actions:
  - handler: prometheus-handler
    instances:
    - RequestCountByService

Rule.HeaderOperationTemplate

A template for an HTTP header manipulation. Values in the template are expressionsthat may reference action outputs by name. For example, if an action x produces an outputwith a field f, then the header value expressions may use attribute x.output.f to referencethe field value:

request_header_operations:
- name: x-istio-header
  values:
  - x.output.f

If the header value expression evaluates to an empty string, and the operation is to either replaceor append a header, then the operation is not applied. This permits conditional behavior on behalf of theadapter to optionally modify the headers.

Rule.HeaderOperationTemplate.Operation

Header operation type.

StringMap

An instance field of type StringMap denotes that the expression for the field must evaluate toValueType.STRING_MAP

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

TimeStamp

An instance field of type TimeStamp denotes that the expression for the field must evaluate toValueType.TIMESTAMP

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

Tls

Tls let operator specify client authentication setting when TLS is used forconnection to the backend.

Tls.AuthHeader

AuthHeader specifies how to pass access token with authorization header.

Uri

DO NOT USE !! Under DevelopmentAn instance field of type Uri denotes that the expression for the field must evaluate toValueType.URI

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

Value

An instance field of type Value denotes that the expression for the field is of dynamic type and can evaluate to anyValueType enum values. For example, whenauthoring 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 betweenoneof 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.

ValueType

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