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

Author: Shriram Rajagopalan

docs/concepts/mixer-config.md

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

docs/concepts/mixer.md

@@ -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,15 +69,15 @@ 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.
 
 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