Mixer Traffic Flow
@@ -40,119 +41,23 @@ examples of quotas. These mechanisms are applied based on a set of [attributes]({{site.baseurl}}/docs/concepts/attributes.html) that are materialized for every request into Mixer. Within Istio, Envoy depends heavily on Mixer. Services running within the mesh -can also use Mixer to report telemetry or manage quotas. +can also use Mixer to report telemetry or manage quotas. (Note: as of Istio Alpha, only Envoy can call Mixer.) ## Adapters -Mixer abstracts away the implementation details of individual policy and telemetry backend systems. This insulates -Envoy and services within the mesh from those details, keeping them portable. +Mixer is a highly modular and extensible component. One of it's key functions is to abstract +away the details of different policy and telemetry backend systems, allowing Envoy and Istio-based +services to be agnostic of those backends, which keeps them portable. -Adapters are binary-level plugins to Mixer which allow Mixer to interface -to different backend systems that deliver core control-plane functionality, such as logging, monitoring, quotas, ACL checking, and more. Adapters -enable 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. +Mixer's flexibility in dealing with different backend systems is achieved by having a general-purpose +plug-in model. Individual plug-ins are known as *adapters* and they allow +Mixer to interface to different backend systems that deliver core functionality, such as logging, monitoring, quotas, ACL +checking, and more. Adapters enable Mixer to expose a single consistent API, independent of the backends in use. +The exact set of adapters used at runtime is determined through configuration and can easily be extended +to target new or custom backend systems.
-## Descriptors and Adapter Parameters
-
-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 Mixer calls its adapters, it provides them
-*adapter parameters* as input. These tell the adapters what to do. For example, when
-reporting metrics to an adapter, Mixer produces parameters that hold the metric data.
-
-Descriptors let you define the *shape* of the parameters produced during Mixer's [attribute processing phase](#request-phases).
-In other words, descriptors let you control the set and type of values carried by these parameters. Some facts:
-
-- Mixer supports a variety of different descriptor kinds (Metric Descriptor, Log Entry Descriptor, Quota Descriptor, etc)
-
-- For each descriptor kind, you can declare any number of descriptors within a given deployment.
-
-- While handling a request, Mixer's attribute processing phase can produce any number of distinct adapter parameters for each of the
-configured descriptors.
-
-An example can help clarify the concepts. Let's consider the `MetricDescriptor` type which is defined as follows:
-
-```proto
- 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:
-
-```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 adapter parameters given the above descriptor:
-
-```yaml
-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 parameters are are typically created as part of attribute processing and they ultimately determine what
-adapters do.
-
-Explicitly defining descriptors and creating adapter parameters using 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 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
Mixer's core runtime methods (`Check`, `Report`, and `Quota`) all accept a set of attributes on input and
@@ -164,7 +69,7 @@ for:
state that configures an adapter (adapters being binary plugins as described [below](#adapters)).
- Establishing the types of adapter parameters that Mixer can manipulate. These
-types are described in configuration through a set of *descriptors* (as described [above](#descriptors))
+types are described in configuration through a set of *descriptors* (as described [here](./mixer-config/#descriptors))
- Creating rules to map the attributes of every incoming request into a
specific set of aspects and adapter parameters.
@@ -172,7 +77,7 @@ specific set of aspects and adapter parameters.
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.
+Refer [here](./mixer-config.md) for detailed information on Mixer's configuration model.
## Request phases