--- title: Mixer Configuration Schema overview: Generated documentation for Mixer's Configuration Schema order: 40 layout: docs type: markdown --- ## Package istio.mixer.v1.config ### Index * [Adapter](#istio.mixer.v1.config.Adapter) (message) * [Aspect](#istio.mixer.v1.config.Aspect) (message) * [AspectRule](#istio.mixer.v1.config.AspectRule) (message) * [AttributeManifest](#istio.mixer.v1.config.AttributeManifest) (message) * [DnsName](#istio.mixer.v1.config.DnsName) (message) * [EmailAddress](#istio.mixer.v1.config.EmailAddress) (message) * [GlobalConfig](#istio.mixer.v1.config.GlobalConfig) (message) * [IpAddress](#istio.mixer.v1.config.IpAddress) (message) * [ServiceConfig](#istio.mixer.v1.config.ServiceConfig) (message) * [Uri](#istio.mixer.v1.config.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](#istio.mixer.v1.config.descriptor.AttributeDescriptor) (message) * [LogEntryDescriptor](#istio.mixer.v1.config.descriptor.LogEntryDescriptor) (message) * [LogEntryDescriptor.PayloadFormat](#istio.mixer.v1.config.descriptor.LogEntryDescriptor.PayloadFormat) (enum) * [MetricDescriptor](#istio.mixer.v1.config.descriptor.MetricDescriptor) (message) * [MetricDescriptor.BucketsDefinition](#istio.mixer.v1.config.descriptor.MetricDescriptor.BucketsDefinition) (message) * [MetricDescriptor.BucketsDefinition.Explicit](#istio.mixer.v1.config.descriptor.MetricDescriptor.BucketsDefinition.Explicit) (message) * [MetricDescriptor.BucketsDefinition.Exponential](#istio.mixer.v1.config.descriptor.MetricDescriptor.BucketsDefinition.Exponential) (message) * [MetricDescriptor.BucketsDefinition.Linear](#istio.mixer.v1.config.descriptor.MetricDescriptor.BucketsDefinition.Linear) (message) * [MetricDescriptor.MetricKind](#istio.mixer.v1.config.descriptor.MetricDescriptor.MetricKind) (enum) * [MonitoredResourceDescriptor](#istio.mixer.v1.config.descriptor.MonitoredResourceDescriptor) (message) * [PrincipalDescriptor](#istio.mixer.v1.config.descriptor.PrincipalDescriptor) (message) * [QuotaDescriptor](#istio.mixer.v1.config.descriptor.QuotaDescriptor) (message) * [ValueType](#istio.mixer.v1.config.descriptor.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.