mirror of https://github.com/istio/istio.io.git
208 lines
10 KiB
Markdown
208 lines
10 KiB
Markdown
---
|
||
title: Mixer
|
||
headline: Mixer
|
||
sidenav: doc-side-concepts-nav.html
|
||
bodyclass: docs
|
||
layout: docs
|
||
type: markdown
|
||
---
|
||
{% capture overview %}
|
||
The page explains the Istio mixer's role and general architecture.
|
||
{% endcapture %}
|
||
|
||
{% capture body %}
|
||
## Background
|
||
|
||
The mixer provides the control-plane abstractions necessary to support most real-world multi-tenant services,
|
||
such as precondition checks, telemetry reporting, and quota management. The proxy delegates precondition
|
||
checking (permissions, whitelist, etc) to the mixer and dispatches its telemetry data
|
||
to the mixer, which proceeds to repackage and redirect the data towards configured backends.
|
||
|
||
Services within the Istio mesh can also directly integrate with the mixer. For example, services may wish to provide rich telemetry
|
||
for particular operations beyond what the proxy automatically collects. Or services may use the mixer for resource-oriented quota
|
||
management. Services that leverage the mixer in this way are abstracted from environment-specific control plane details, greatly
|
||
easing the process of hosting the code in different environments (different clouds and on-prem)
|
||
|
||
<img style="display:block;width:60%;margin:auto;" src="./mixer/traffic.svg" alt="Flow of traffic." />
|
||
<p style="text-align:center;">Mixer Traffic Flow</p>
|
||
|
||
The mixer provides three core features:
|
||
|
||
- **Precondition Checking**. Enables callers to verify a number of preconditions before responding to an incoming request from a service consumer.
|
||
Preconditions can include whether the service consumer is properly authenticated, is on the service's whitelist, passes ACL checks, and more.
|
||
|
||
- **Telemetry Reporting**. Enables services to produce logging and monitoring. In the future, it will also enable tracing and billing
|
||
streams intended for both the service operator as well as for service consumers.
|
||
|
||
- **Quota Management**. Enables services to allocate and free quota on a number of dimensions, Quotas are used as a relatively simple resource management
|
||
tool to provide some fairness between service consumers when contending for limited resources.
|
||
|
||
These mechanisms are applied based on a set of [attributes]({{site.baseurl}}/docs/concepts/attributes.html) that are
|
||
materialized for every request into the mixer.
|
||
|
||
## Adapters
|
||
|
||
Adapters are binary-level plugins to the mixer which make it possible to customize the mixer’s behavior. Adapters allow the mixer to interface
|
||
to different backend systems that deliver core control-plane functionality, such as logging, monitoring, quotas, ACL checking, and more. Adapters
|
||
enable the mixer to expose a single consistent control API, independent of the backends in use. The exact set of adapters
|
||
used at runtime is determined through configuration.
|
||
|
||
<img style="width:65%;display:block;margin:auto;" src="./mixer/adapters.svg" alt="The mixer and its adapters." />
|
||
|
||
## Descriptors and policy objects
|
||
|
||
The mixer is essentially an attribute processing machine. It takes in a number of attributes from
|
||
its caller and produces as a result a set of calls into its adapters, which in turn trigger calls to
|
||
associated backend systems such as Prometheus or NewRelic. As the mixer calls its adapters, it provides them what are
|
||
called *policy objects* as input. These policy objects are the parameters telling the adapters what to do. For example, when
|
||
reporting metrics to an adapter, the mixer produces a policy object that holds the metric data.
|
||
|
||
Descriptors let you define the *shape* of the policy objects produced during the mixer's [attribute processing phase](#request-phases).
|
||
In other words, descriptors let you control the set and type of values carried by individual policy objects. Some facts:
|
||
|
||
- The mixer supports a variety of different descriptor kinds (`MetricDescriptor`, `LogEntryDescriptor`, `QuotaDescriptor`, etc)
|
||
|
||
- For each descriptor kind, you can declare any number of descriptors within a given deployment.
|
||
|
||
- While handling a request, the mixer's attribute processing phase can produce any number of policy objects for each of the
|
||
configured descriptors.
|
||
|
||
An example can help clarify the concepts. Let's consider the `MetricDescriptor` type which is defined as follows:
|
||
|
||
message MetricDescriptor {
|
||
string name = 1;
|
||
string display_name = 2;
|
||
string description = 3;
|
||
|
||
enum MetricKind {
|
||
METRIC_KIND_UNSPECIFIED = 0;
|
||
GAUGE = 1;
|
||
COUNTER = 2;
|
||
}
|
||
|
||
MetricKind kind = 4;
|
||
ValueType value = 5;
|
||
repeated LabelDescriptor labels = 6;
|
||
}
|
||
|
||
Within a deployment configuration, you can declare a metric descriptor using a snippet of YAML:
|
||
|
||
name: request_count
|
||
kind: COUNTER
|
||
value: INT64
|
||
description: request count by source, target, service, and code
|
||
labels:
|
||
- name: source
|
||
valueType: STRING
|
||
- name: target
|
||
valueType: STRING
|
||
- name: service
|
||
valueType: STRING
|
||
- name: method
|
||
valueType: STRING
|
||
- name: response_code
|
||
valueType: INT64
|
||
|
||
This is declaring a descriptor called `request_count`. Because of the kind and value fields, policy objects associated with this
|
||
descriptor represent 64-bit integer counters. Additionally, each associated policy object will be uniquely identified via the 5
|
||
listed labels. Producing a policy object for such a descriptor requires 6 pieces of information:
|
||
|
||
- a 64-bit integer metric value
|
||
- a source string
|
||
- a target string
|
||
- a service string
|
||
- a method string
|
||
- a 64-bit integer response code
|
||
|
||
Here is an example snippet of Istio configuration which produces a policy object for the above descriptor:
|
||
|
||
descriptor_name: request_count
|
||
value: "1"
|
||
labels:
|
||
source: source.name | "unknown"
|
||
target: target.name | "unknown"
|
||
service: api.name | "unknown"
|
||
method: api.method | "unknown"
|
||
response_code: response.code | 200
|
||
|
||
Many such policy objects are created as part of attribute processing and they ultimately serve as input to
|
||
adapters.
|
||
|
||
Explicitly defining descriptors and creating policy objects for them is akin to types and objects in a traditional
|
||
programming language. Doing so enables a few important scenarios:
|
||
|
||
- Having the set of descriptors explicitly defined enables Istio to program backend systems to accept traffic produced
|
||
by the mixer. For example, a `MetricDescriptor` provides all the information needed to program a backend system to accept metrics
|
||
that conform to the descriptor's shape (it's value type and its set of labels).
|
||
|
||
- It enables type checking of the deployment's configuration. Since attributes have strong types, and so do descriptors,
|
||
Istio can provide a number of strong correctness guarantees of the system's configuration. Basically, if a chunk of
|
||
configuration is accepted into the Istio system, it means the configuration passes a minimum correctness bar. Again, this
|
||
plays the same role as types in a programming language.
|
||
|
||
- It enables Istio to provide a strongly-typed scripting environment as discussed [below](#scripting)
|
||
|
||
## Configuration state
|
||
|
||
The mixer's core runtime methods (`Check`, `Report`, and `Quota`) all accept a set of attributes on input and
|
||
produce a set of attributes on output. The work that the individual methods perform is dictated by the set of input
|
||
attributes, as well as by the mixer's current configuration. To that end, the service operator is responsible
|
||
for:
|
||
|
||
- Configuring the set of *aspects* that the deployment uses. An aspect is essentially a chunk of configuration
|
||
state that configures an adapter (adapters being binary plugins as described [below](#adapters)).
|
||
|
||
- Establishing the types of policy objects that the mixer can manipulate. These
|
||
types are described in configuration through a set of *descriptors* (as described [above](#descriptors))
|
||
|
||
- Creating rules to map the attributes of every incoming request into a
|
||
specific set of aspects and policy objects.
|
||
|
||
The above configuration state is required to have mixer know what to do with incoming attributes
|
||
and dispatch to the appropriate backend systems.
|
||
|
||
Refer to *TBD* for detailed information on mixer's configuration format.
|
||
|
||
## Request phases
|
||
|
||
When a request comes in to the mixer, it goes through a number of distinct handling phases:
|
||
|
||
- **Supplementary Attribute Production**. The first thing that happens in the mixer is to run a globally configured
|
||
set of adapters that are responsible for introducing new attributes. These attributes are combined with the attributes
|
||
from the request to form the total set of attributes for the operation.
|
||
|
||
- **Resolution**. The second phase is to evaluate the set of attributes to determine the effective
|
||
configuration to apply for the request. See *TBD* for information on how resolution works. The effective
|
||
configuration determines the set of aspects and descriptors available to handle the request in the
|
||
subsequent phases.
|
||
|
||
- **Attribute Processing**. The third phase takes the set of incoming request attributes
|
||
and produces a set of policy objects. Attribute processing is initially
|
||
configured through a simple declarative form as described in *TBD*.
|
||
|
||
- **Adapter Dispatching**. The Resolution phase establishes the set of available aspects and the Attribute
|
||
Processing phase creates a set of policy objects. The Adapter Dispatching phase invokes the adapters
|
||
associated with each aspect and passes them policy objects.
|
||
|
||
<img style="display:block;width:40%;margin:auto;" src="./mixer/phases.svg" alt="Phases of mixer request processing" />
|
||
<p style="text-align:center;">Request Phases</p>
|
||
|
||
## Scripting
|
||
|
||
> This section is preliminary and subject to change. We're still experimenting with the concept of scripting in the mixer.
|
||
|
||
The mixer's attribute processing phase is implemented via a scripting language (exact language *TBD*).
|
||
The scripts are provided a set of attributes and are responsible for producing policy objects and dispatching
|
||
control to individual configured aspects.
|
||
|
||
For common uses, the operator authors policy objects production rules via a relatively simple declarative format
|
||
and expression syntax. The mixer ingests such rules and produces a script that performs the necessary runtime work
|
||
of accessing the request's incoming attributes and producing the requisite policy objects.
|
||
|
||
For advanced uses, the operator can bypass the declarative format and author directly in the scripting
|
||
language. This is more complex, but provides ultimate flexibility.
|
||
|
||
{% endcapture %}
|
||
|
||
{% include templates/concept.md %}
|