istio.io/_docs/reference/api/mixer-config.md

title	overview	order	layout	type
Mixer - Configuration Schema	Generated documentation for Mixer's configuration schema	40	docs	markdown

Package istio.mixer.v1.config

Index

• Adapter (message)
• Aspect (message)
• AspectRule (message)
• AttributeManifest (message)
• DnsName (message)
• EmailAddress (message)
• GlobalConfig (message)
• IpAddress (message)
• ServiceConfig (message)
• Uri (message)

Adapter

Adapter config defines specifics of adapter implementations We define an adapter that provides "metrics" aspect kind: istio/metrics name: metrics-statsd impl: “istio.io/adapters/statsd” params: Host: statd.svc.cluster Port: 8125

Field	Type	Description
name	string	statsd-slow
kind	string	metrics
impl	string	istio.statsd
params	Struct	Struct representation of a proto defined by the implementation based on impl {}

Aspect

Aspect is intent based. It specifies the intent "kind" following example specifies that the user would like to collect response_time with 3 labels (src_consumer_id, target_response_status_code, target_service_name)

The Input section tells if target_service_name is not available it can be computed using the given expression

 kind: istio/metrics
 params:
   metrics:
   - name: response_time     # What to call this metric outbound.
     value: metric_response_time  # from wellknown vocabulary
     metric_kind: DELTA
     labels:
     - key: src_consumer_id
     - key: target_response_status_code
     - key: target_service_name

Field	Type	Description
kind	string
adapter	string	optional, allows specifying an adapter
params	Struct	Struct representation of a proto defined by the aspect

AspectRule

AspectRules are intent based

Field	Type	Description
selector	string	selector is an attributes based predicate. attr1 == "20" && attr2 == "30"
aspects[]	repeated Aspect	The following aspects apply when the selector predicate evaluates to True
rules[]	repeated AspectRule	Nested aspect Rule is evaluated if selector predicate evaluates to True

AttributeManifest

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

Field	Type	Description
revision	string
name	string	Name of the component producing these attributes. This can be the proxy (with the canonical name "istio-proxy") or the name of an attribute producing adapter in the mixer itself.
attributes[]	repeated AttributeDescriptor	The set of attributes this Istio component will be responsible for producing at runtime.

DnsName

DnsName holds a valid domain name.

Field	Type	Description
value	string

EmailAddress

EmailAddress holds a properly formatted email address.

Field	Type	Description
value	string

GlobalConfig

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

Field	Type	Description
revision	string
adapters[]	repeated Adapter
manifests[]	repeated AttributeManifest
logs[]	repeated LogEntryDescriptor
metrics[]	repeated MetricDescriptor
monitored_resources[]	repeated MonitoredResourceDescriptor
principals[]	repeated PrincipalDescriptor
quotas[]	repeated QuotaDescriptor

IpAddress

IpAddress holds an IPv4 or IPv6 address.

Field	Type	Description
value	bytes

ServiceConfig

Configures a set of services following example configures metrics collection and ratelimit for all services

service config

subject: "namespace:ns1" revision: "1011" rules:

• selector: target_name == "*" aspects:
• kind: metrics params: metrics: # defines metric collection across the board.
  • name: response_time_by_status_code value: metric.response_time # certain attributes are metrics metric_kind: DELTA labels:
    • key: response.status_code
• kind: ratelimiter params: limits: # imposes 2 limits, 100/s per source and destination
  • limit: "100/s" labels:
    • key: src.service_id
    • key: target.service_id
  • limit: "1000/s" # every destination service gets 1000/s labels:
    • key: target.service_id

Field	Type	Description
subject	string	subject is unique for a config type 2 config with the same subject will overwrite each other
revision	string	revision of this config. This is assigned by the server
rules[]	repeated AspectRule

Uri

Uri represents a properly formed URI.

Field	Type	Description
value	string

Package istio.mixer.v1.config.descriptor

Index

• AttributeDescriptor (message)
• LogEntryDescriptor (message)
• LogEntryDescriptor.PayloadFormat (enum)
• MetricDescriptor (message)
• MetricDescriptor.BucketsDefinition (message)
• MetricDescriptor.BucketsDefinition.Explicit (message)
• MetricDescriptor.BucketsDefinition.Exponential (message)
• MetricDescriptor.BucketsDefinition.Linear (message)
• MetricDescriptor.MetricKind (enum)
• MonitoredResourceDescriptor (message)
• PrincipalDescriptor (message)
• QuotaDescriptor (message)
• ValueType (enum)

AttributeDescriptor

An AttributeDescriptor describes the schema of an Istio attribute type.

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, 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 Istio attribute type. The AttributeDescriptor is used to define attribute types. Each type has a globally unique type name, the type of the value, and a detailed description that explains the semantics of the attribute type.

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
name	string	The name of this descriptor, referenced from individual attribute instances and other descriptors. The format of this name is: Name = IDENT { "." IDENT } ; Where IDENT must match the regular expression a-z+. Attribute descriptor names must be unique within a single Istio deployment. There is a well- known set of attributes which have succinct names. Attributes not on this list should be named with a component-specific suffix such as request.count-my.component
description	string	An optional human-readable description of the attribute's purpose.
value_type	ValueType	The type of data carried by attributes

LogEntryDescriptor

Defines the format of a single log entry.

Field	Type	Description
name	string	The name of this descriptor.
display_name	string	An optional concise name for the log entry type, which can be displayed in user interfaces. Use sentence case without an ending period, for example "Request count".
description	string	An optional description of the log entry type, which can be used in documentation.
payload_format	PayloadFormat	Format of the value of the payload attribute.
log_template	string	The template that will be populated with labels at runtime to generate a log message; the labels describe the parameters for this template. The template strings must conform to go's text/template syntax.
labels	repeated map<string, ValueType>	Labels describe the parameters of this log's template string. The log definition allows the user to map attribute expressions to actual values for these labels at run time; the result of the evaluation must be of the type described by the kind for each label.

PayloadFormat

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

Value	Description
PAYLOAD_FORMAT_UNSPECIFIED	Invalid, default value.
TEXT	Indicates a payload format of raw text.
JSON	Indicates that the payload is a serialized JSON object.

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:

metric_descriptor: name: "response_code" kind: COUNTER value: I64 labels: name: api_method value_type: STRING labels: name: response_code value_type: 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: "response_code" # must match metric_descriptor.name value: $requestCount # Istio expression syntax for the attribute named "request_count" labels: # either the attribute named 'apiMethod' or the literal string 'unknown'; must eval to a string api_method: $apiMethod | "unknown" # either the attribute named 'responseCode' or the literal int64 500; must eval to an int64 response_code: $responseCode | 500

Field	Type	Description
name	string	The name of this descriptor. This is used to refer to this descriptor in other contexts.
display_name	string	An optional concise name for the metric, which can be displayed in user interfaces. Use sentence case without an ending period, for example "Request count".
description	string	An optional description of the metric, which should be used as the documentation for the metric.
kind	MetricKind	Whether the metric records instantaneous values, changes to a value, etc.
value	ValueType	The type of data this metric records.
labels	repeated map<string, ValueType>	Labels that dimension the data recorded by this metric. The metric definition allows the user to map attribute expressions to actual values for these labels at run time; the result of the evaluation must be of the type described by the kind for each label.
buckets	BucketsDefinition	For metrics with a metric kind of DISTRIBUTION, this provides a mechanism for configuring the buckets that will be used to store the aggregated values. This field must be provided for metrics declared to be of type DISTRIBUTION. This field will be ignored for non-distribution metric kinds.

BucketsDefinition

Field	Type	Description
linear_buckets	Linear (oneof )	The linear buckets.
exponential_buckets	Exponential (oneof )	The exponential buckets.
explicit_buckets	Explicit (oneof )	The explicit buckets.

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.

Field	Type	Description
bounds[]	repeated double	The values must be monotonically increasing.

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 num_finite_buckets + 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 * (growth_factor ^ i). Lower bound (1 <= i < N): scale * (growth_factor ^ (i - 1)).

Field	Type	Description
num_finite_buckets	int32	Must be greater than 0.
growth_factor	double	Must be greater than 1.
scale	double	Must be greater than 0.

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 num_finite_buckets + 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)).

Field	Type	Description
num_finite_buckets	int32	Must be greater than 0.
width	double	Must be greater than 0.
offset	double	Lower bound of the first bucket.

MetricKind

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

Value	Description
METRIC_KIND_UNSPECIFIED	Do not use this default value.
GAUGE	An instantaneous measurement of a value. For example, the number of VMs.
COUNTER	A count of occurrences over an interval, always a positive integer. For example, the number of API requests.
DISTRIBUTION	Summary statistics for a population of values. At the moment, only histograms representing the distribution of those values across a set of buckets are supported (configured via the buckets field). Values for DISTRIBUTIONs will be reported in singular form. It will be up to the mixer adapters and backend systems to transform single reported values into the distribution form as needed (and as supported).

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.

Field	Type	Description
name	string	The name of this descriptor
description	string	An optional detailed description of the monitored resource descriptor that might be used in documentation.
labels	repeated map<string, ValueType>	Labels represent the dimensions that uniquely identify this monitored resource. At runtime expressions will be evaluated to provide values for each label. Label names are mapped to expressions as part of aspect configuration.

PrincipalDescriptor

Defines a a security principal.

A principal is described by a set of attributes.

Field	Type	Description
name	string	The name of this descriptor.
labels	repeated map<string, ValueType>	Labels represent the dimensions that uniquely identify this security principal. At runtime expressions will be evaluated to provide values for each label. Label names are mapped to expressions as part of aspect configuration.

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.

Field	Type	Description
name	string	The name of this descriptor.
display_name	string	An optional concise name for the quota which can be displayed in user interfaces.
description	string	An optional description of the quota which can be used in documentation.
labels	repeated map<string, ValueType>	The set of labels that are necessary to describe a specific value cell for a quota of this type.
rate_limit	bool	Indicates whether the quota represents a rate limit or represents a resource quota.

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.

Value	Description
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.