istio
/
istio.io
mirror of https://github.com/istio/istio.io.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Merge branch 'master' of https://github.com/istio/istio.github.io

This commit is contained in:
Shriram Rajagopalan 2017-04-19 18:49:42 -04:00
parent 2ac27ed953 95cde568ba
commit a06f6a1581
2 changed files with 33 additions and 115 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

23
docs/concepts/mixer-config.md
View File

@ -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

125
docs/concepts/mixer.md
View File

@ -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