Mixer

Adapter

Adapter allows the operator to configure a specific adapter implementation. Each adapter implementation defines its own params proto. Note that unlike Aspect, the type of params varies with impl and not with kind.

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

kind: metrics
name: prometheus-adapter
impl: prometheus
params:

Aspect

Aspect describes how an adapter is intended to operate in the context of the rule it’s embedded in. The value for params depends on the kind of this aspect: each kind of aspect defines its own params proto.

The following example instructs Mixer to populate a metric named “responseTime” that was declared to have three labels: srcConsumerId, targetResponseStatusCode, and targetServiceName. For each label and the metric’s value we provide an expression over Istio’s attributes. Mixer evaluates these expressions for each request.

kind: metrics
params:
  metrics:
  - descriptorName: responseTime # tie this metric to a descriptor of the same name
    value: response.time  # from the set of canonical attributes
    labels:
      srcConsumerId: source.user | source.uid
      targetResponseStatusCode: response.code
      targetServiceName: target.service

AspectRule

An AspectRule is a selector and a set of intentions to be executed when the selector is true. The selectors of the this rule’s child AspectRules are only evaluated if this rule’s selector is true.

AttributeManifest

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

Name = IDENT { SEPARATOR IDENT };

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.

DnsName

DnsName holds a valid domain name.

EmailAddress

EmailAddress holds a properly formatted email address.

GlobalConfig

WARNING: GlobalConfig is deprecated, see the Config API’s swagger spec.

GlobalConfig defines configuration elements that are available for the rest of the config. It is used to configure adapters and make them available in AspectRules.

IpAddress

IpAddress holds an IPv4 or IPv6 address.

ServiceConfig

WARNING: ServiceConfig is deprecated, see the Config API’s swagger spec.

Configures a set of services.

The following example configures a metric that will be recorded for all services:

subject: "namespace:ns1"
revision: "1011"
rules:
- selector: target.service == "*"
  aspects:
  - kind: metrics
    params:
      metrics: # defines metric collection across the board.
      - descriptorName: responseTimeByStatusCode
        value: response.time
        labels:
          statusCode: response.code

Uri

Uri represents a properly formed URI.

Package istio.mixer.v1.config.descriptor

LogEntryDescriptor

Defines the format of a single log entry.

PayloadFormat

PayloadFormat details the currently supported logging payload formats. TEXT is the default payload format.

MetricDescriptor

Defines a metric type and its schema.

A metric is dimensioned by a set of labels whose values are derived at runtime from attributes. A given metric holds a unique value for potentially any combination of these dimensions.

The following is an example descriptor for a metric capturing the number of RPCs served, dimensioned by the method being called and response code returned by the server:

metrics:
  name: "responseCode"
  kind: COUNTER
  value: INT64
  labels:
    apiMethod: STRING
    responseCode: INT64

To actually report metrics at run time a mapping from attributes to a metric’s labels must be provided. This is provided in the aspect config; using our above descriptor we might describe the metric as:

metric:
  descriptor: "responseCode" # must match metricDescriptor.name
  value: request.count # expression syntax for the attribute named "request.count"
  labels:
    # either the attribute named 'api.method' or the literal string 'unknown'; must eval to a string
    apiMethod: api.method | "unknown"
    # either the attribute named 'response.code' or the literal int64 500; must eval to an int64
    responseCode: response.code | 500

BucketsDefinition

Explicit

Specifies a set of buckets with arbitrary widths.

There are size(bounds) + 1 (= N) buckets. Bucket i has the following boundaries:

• Upper bound (0 <= i < N-1): bounds[i]
• Lower bound (1 <= i < N): bounds[i - 1]

The bounds field must contain at least one element. If bounds has only one element, then there are no finite buckets, and that single element is the common boundary of the overflow and underflow buckets.

Exponential

Specifies an exponential sequence of buckets that have a width that is proportional to the value of the lower bound. Each bucket represents a constant relative uncertainty on a specific value in the bucket.

There are numFiniteBuckets + 2 (= N) buckets. The two additional buckets are the underflow and overflow buckets.

Bucket i has the following boundaries:

• Upper bound (0 <= i < N-1): scale * (growthFactor ^ i)
• Lower bound (1 <= i < N): scale * (growthFactor ^ (i - 1))

Linear

Specifies a linear sequence of buckets that all have the same width (except overflow and underflow). Each bucket represents a constant absolute uncertainty on the specific value in the bucket.

There are numFiniteBuckets + 2 (= N) buckets. The two additional buckets are the underflow and overflow buckets.

Bucket i has the following boundaries:

• Upper bound (0 <= i < N-1): offset + (width * i)
• Lower bound (1 <= i < N): offset + (width * (i - 1))

MetricKind

The kind of measurement. It describes how the data is recorded.

MonitoredResourceDescriptor

An object that describes the schema of a MonitoredResource. A MonitoredResource is used to define a type of resources for monitoring purpose. For example, the monitored resource “VM” refers to virtual machines, which requires 3 attributes “owner”, “zone”, “name” to uniquely identify a specific instance. When reporting a metric against a monitored resource, the metric attributes will be used to associate the right value with the right instance, such as memory usage of a VM.

PrincipalDescriptor

Defines a a security principal.

A principal is described by a set of attributes.

QuotaDescriptor

Configuration state for a particular quota.

Quotas are similar to metrics, except that they are mutated through method calls and there are limits on the allowed values. The descriptor below lets you define a quota and indicate the maximum amount values of this quota are allowed to hold.

A given quota is described by a set of attributes. These attributes represent the different dimensions to associate with the quota. A given quota holds a unique value for potentially any combination of these attributes.

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.