mirror of https://github.com/istio/istio.io.git
Work on Mixer docs.
This commit is contained in:
Martin Taillefer
parent
cb151d0713
commit
95cde568ba
|
|
@ -18,7 +18,7 @@ This page describes the Istio mixer's configuration model.
|
|||
## Background
|
||||
|
||||
Istio is a sophisticated system with hundreds of independent features. An Istio deployment can be a sprawling
|
||||
affair potentially involving dozens of microservices, with a swarm of Istio proxy and mixer instances to
|
||||
affair potentially involving dozens of microservices, with a swarm of Envoy proxies and Mixer instances to
|
||||
support them. In large deployments, many different operators, each with different scope and areas of responsibility,
|
||||
may be involved in managing the overall deployment.
|
||||
|
||||
|
|
@ -312,21 +312,34 @@ metrics:
|
|||
source: STRING
|
||||
target: STRING
|
||||
service: STRING
|
||||
method: STRING
|
||||
response_code: INT64
|
||||
```
|
||||
|
||||
The above is declaring that the system can produce metrics called `request_count`.
|
||||
Such metrics will hold 64-bit integer values and be managed as absolute counters. Each
|
||||
metric reported will have five labels, two specifying the source and
|
||||
target names, one being the service name, one being the name of an API method and
|
||||
the other being the response code for the request. Given this descriptor, Mixer
|
||||
metric reported will have four labels, two specifying the source and
|
||||
target names, one being the service name, the other being the response code for the request.
|
||||
Given this descriptor, Mixer
|
||||
can ensure that generated metrics are always properly formed, can arrange for efficient
|
||||
storage for these metrics, and can ensure backend systems are ready to accept
|
||||
these metrics. The `display_name` and `description` fields are optional and
|
||||
are communicated to backend systems which can use the text to enhance their
|
||||
metric visualization interfaces.
|
||||
|
||||
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 metric descriptor 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 [here](./mixer.md#scripting)
|
||||
|
||||
The different descriptor types are detailed in *TBD*
|
||||
|
||||
### Scopes
|
||||
|
|
|
|||
|
|
@ -7,7 +7,7 @@ layout: docs
|
|||
type: markdown
|
||||
---
|
||||
{% capture overview %}
|
||||
The page explains Istio's Mixer's role and general architecture.
|
||||
The page explains Mixer's role and general architecture.
|
||||
{% endcapture %}
|
||||
|
||||
{% capture body %}
|
||||
|
|
@ -21,7 +21,8 @@ to Mixer, which proceeds to repackage and redirect the data towards configured b
|
|||
Services within the Istio mesh can also directly integrate with Mixer. For example, services may wish to provide rich telemetry
|
||||
for particular operations beyond what Envoy automatically collects. Or services may use Mixer for resource-oriented quota
|
||||
management. Services that leverage 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)
|
||||
easing the process of hosting the code in different environments (different clouds and on-prem). (Please note that
|
||||
as of the Alpha release of Istio, only Envoy can calls Mixer directly.)
|
||||
|
||||
<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>
|
||||
|
|
@ -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.
|
||||
|
||||
<img style="width:65%;display:block;margin:auto;" src="./mixer/adapters.svg" alt="Mixer and its adapters." />
|
||||
|
||||
## 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
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue