istio
/
istio.io
mirror of https://github.com/istio/istio.io.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity
istio.io/_docs/reference/api/mixer/mixer-config.md

36 KiB
Raw Blame History

title overview order layout type
Mixer Generated documentation for Mixer's Configuration Schema 1190 docs markdown

Index

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:
Field Type Description
name string Required, must be unique per kind. Used by Aspect to refer to this adapter. The name "default" is special: when an Aspect does not specify a name, the Adapter named "default" of the same kind is used to execute the intention described by the AspectRules.
kind string Required. The aspect this implementation with these params will implement; a single adapter implementation may implement many aspects, but an Adapter entry is required per kind.
impl string Required. The name of a specific adapter implementation. An adapter's implementation name is typically a constant in its code.
params Struct Optional, depends on adapter implementation. Struct representation of a proto defined by the implementation; this varies depending on impl.

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
Field Type Description
kind string Required. The kind of aspect this intent is targeting.
adapter string Optional. The name of the adapter this Aspect targets. If no name is provided, Mixer will use the adapter of the target kind named "default".
params Struct Required. Struct representation of a proto defined by each aspect kind.

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.

Field Type Description
selector string

Required. Selector is an attribute based predicate. When Mixer receives a request it evaluates all selectors in scope and executes the rules for all selectors that evaluated to true.

A few example selectors:

  • an empty selector evaluates to true
  • true, a boolean literal; a rule with this selector will always be executed
  • target.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
aspects[] repeated Aspect The aspects that apply when selector evaluates to true.
rules[] repeated AspectRule Nested aspect rules; their selectors are evaluated if this 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 Optional. The revision of this document. Assigned by server.
name string 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.
attributes repeated map<string, 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

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.

Field Type Description
description string Optional. A human-readable description of the attribute's purpose.
valueType ValueType Required. The type of data carried by this attribute.

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

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.

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

IpAddress

IpAddress holds an IPv4 or IPv6 address.

Field Type Description
value bytes

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
Field Type Description
subject string Optional. Subject is unique for a config type. 2 config with the same subject will overwrite each other
revision string Optional. 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

LogEntryDescriptor

Defines the format of a single log entry.

Field Type Description
name string Required. The name of this descriptor.
displayName string Optional. A 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 Optional. A description of the log entry type, which can be used in documentation.
payloadFormat PayloadFormat Required. Format of the value of the payload attribute.
logTemplate string

Required. 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
PAYLOADFORMATUNSPECIFIED 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:

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
Field Type Description
name string Required. The name of this descriptor. This is used to refer to this descriptor in other contexts.
displayName string Optional. A 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 Optional. A description of the metric, which should be used as the documentation for the metric.
kind MetricKind Required. Whether the metric records instantaneous values, changes to a value, etc.
value ValueType Required. 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
linearBuckets Linear (oneof ) The linear buckets.
exponentialBuckets Exponential (oneof ) The exponential buckets.
explicitBuckets 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 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))
Field Type Description
numFiniteBuckets int32 Must be greater than 0.
growthFactor 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 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))
Field Type Description
numFiniteBuckets 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
METRICKINDUNSPECIFIED 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 Required. The name of this descriptor.
description string Optional. A 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 Required. 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 Required. The name of this descriptor.
displayName string Optional. A concise name for the quota which can be displayed in user interfaces.
description string Optional. A 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.
rateLimit 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
VALUETYPEUNSPECIFIED 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.
IPADDRESS An IP address.
EMAILADDRESS An email address.
URI A URI.
DNSNAME A DNS name.
DURATION A span between two points in time.
STRINGMAP A map string -> string, typically used by headers.