Turn Mixer into a proper name...

Author: Martin Taillefer

docs/concepts/attributes.md

@@ -27,7 +27,7 @@ original IP address of a TCP connection. Here are a few examples of attributes:
 
 A given Istio deployment has a fixed vocabulary of attributes that it understands. The specific vocabulary is
 determined by the set of attribute producers being used in the deployment. The primary attribute producer in Istio
-is the proxy, although specialized mixer adapters and services can also introduce attributes.
+is Envoy, although specialized Mixer adapters and services can also introduce attributes.
 
 The common baseline set of attributes available in most Istio deployments is defined
 [here]({{site.baseurl}}/docs/reference/attribute-vocabulary.html). 

docs/concepts/mixer-config.md

@@ -22,13 +22,13 @@ affair potentially involving dozens of microservices, with a swarm of Istio prox
 support them. In large deployments, many different operators, each with different scope and areas of responsibility,
 may be involved in managing the overall deployment.
 
-The mixer's configuration model makes it possible to exploit all of the mixer's capabilities and flexibility, while
+Mixer's configuration model makes it possible to exploit all of its capabilities and flexibility, while
 remaining relatively simple to use. The model's scoping features enable large
 support organizations to collectively manage complex deployments with ease. Some of the model's key
 features include:
 
 - **Designed for Operators**. Service operators control all operational and policy
-aspects of a mixer deployment by manipulating configuration records.
+aspects of a Mixer deployment by manipulating configuration records.
 
 - **Scoped**. Configuration is described hierarchically, enabling both coarse global control as well
 as fine-grained local control.
@@ -45,14 +45,14 @@ can be added to Istio and be fully manipulated using the same general mechanisms
 
 ## Concepts
 
-The mixer is an attribute processing machine. Requests arrive at the mixer with a set of [*attributes*]({{site.baseurl}}/docs/attributes.html),
-and based on these attributes, the mixer generates calls to a variety of backend systems. The set of
-attributes determines which backend systems the mixer calls for a given request and what parameters
-they are given. In order to hide the details of individual backend systems, the mixer uses modules
+Mixer is an attribute processing machine. Requests arrive at Mixer with a set of [*attributes*]({{site.baseurl}}/docs/attributes.html),
+and based on these attributes, Mixer generates calls to a variety of backend systems. The set of
+attributes determines which backend systems Mixer calls for a given request and what parameters
+they are given. In order to hide the details of individual backend systems, Mixer uses modules
 known as [*adapters*]({{site.baseurl}}/docs/concepts/mixer.html#adapters) which you can think of as
 *device drivers* for backend systems.
 
-The mixer's configuration has two central responsibilities:
+Mixer's configuration has two central responsibilities:
 
 - Describe which adapters are being used and how they operate.
 - Describe how to map request attributes into adapter parameters.
@@ -73,11 +73,11 @@ The following sections explain these concepts in detail.
 ### Adapters
 
 [Adapters]({{site.baseurl}}/docs/concepts/mixer.html#adapters) are the foundational work horses that the Istio mixer is built around. Adapters
-encapsulate the logic necessary to interface the mixer with specific external backend systems such as Prometheus or NewRelic. Individual adapters
+encapsulate the logic necessary to interface Mixer with specific external backend systems such as Prometheus or NewRelic. Individual adapters
 generally need to be provided some basic operational parameters in order to do their work. For example, a logging adapter may need
 to know the IP address and port where it's log data should be pumped.
 
-The mixer can use a suite of adapters, and each requires separate configuration parameters.
+Mixer can use a suite of adapters, and each requires separate configuration parameters.
 Here's an example showing how to configure an adapter:
 
 ```yaml
@@ -210,7 +210,7 @@ aspect configuration formats can be found in *TBD*.
 
 #### Attribute Expressions
 
-The mixer features a number of independent [request processing phases]({{site.baseurl}}/docs/concepts/mixer#request-phases).
+Mixer features a number of independent [request processing phases]({{site.baseurl}}/docs/concepts/mixer#request-phases).
 The *Attribute Processing* phase is responsible for ingesting a set of attributes and producing the adapter parameters 
 necessary to invoke individual adapters. The phase operates by evaluating a series of *attribute expressions*.
 
@@ -285,8 +285,8 @@ was not defined.
 
 ### Descriptors
 
-Descriptors are used to prepare the mixer, its adapters, and its backend systems to receive
-particular types of data. For example, declaring a set of metric descriptors tells the mixer
+Descriptors are used to prepare Mixer, its adapters, and its backend systems to receive
+particular types of data. For example, declaring a set of metric descriptors tells Mixer
 the type of data different metrics will carry and the set of labels used to identity different
 instances of these metric.
 
@@ -320,7 +320,7 @@ 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, the mixer
+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 

docs/concepts/mixer.md

@@ -7,64 +7,69 @@ layout: docs
 type: markdown
 ---
 {% capture overview %}
-The page explains the Istio mixer's role and general architecture.
+The page explains Istio's 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.
+Mixer provides the control-plane abstractions necessary to support most real-world multi-tenant services,
+such as precondition checks, telemetry reporting, and quota management. Envoy delegates precondition
+checking (permissions, whitelist, etc) to Mixer and dispatches its telemetry data 
+to 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
+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)
 
 <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:
+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.
+- **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. Rate limits are
+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 the mixer.
+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.
 
 ## 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 
+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.
+
+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 the mixer to expose a single consistent control API, independent of the backends in use. The exact set of 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.
 
-<img style="width:65%;display:block;margin:auto;" src="./mixer/adapters.svg" alt="The mixer and its adapters." />
+<img style="width:65%;display:block;margin:auto;" src="./mixer/adapters.svg" alt="Mixer and its adapters." />
 
-## Descriptors and policy objects
+## Descriptors and Adapter Parameters
 
-The mixer is essentially an attribute processing machine. It takes in a number of attributes from
+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.
+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 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:
+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:
 
-- The mixer supports a variety of different descriptor kinds (`MetricDescriptor`, `LogEntryDescriptor`, `QuotaDescriptor`, etc)
+- 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, the mixer's attribute processing phase can produce any number of policy objects for each of the
+- 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:
@@ -118,7 +123,7 @@ listed labels. Producing a policy object for such a descriptor requires 6 pieces
 - 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:
+Here is an example snippet of Istio configuration which produces adapter parameters given the above descriptor:
 
 ```yaml
 descriptor_name: request_count
@@ -131,14 +136,14 @@ labels:
   response_code: response.code | 200
 ```
 
-Many such policy objects are created as part of attribute processing and they ultimately serve as input to
-adapters.
+Many such parameters are are typically created as part of attribute processing and they ultimately determine what
+adapters do.
 
-Explicitly defining descriptors and creating policy objects for them is akin to types and objects in a traditional
+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 the mixer. For example, a `MetricDescriptor` provides all the information needed to program a backend system to accept metrics
+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,
@@ -150,30 +155,30 @@ plays the same role as types in a programming language.
 
 ## Configuration state
 
-The mixer's core runtime methods (`Check`, `Report`, and `Quota`) all accept a set of attributes on input and
+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
+attributes, as well as by 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
+- 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))
 
 - Creating rules to map the attributes of every incoming request into a 
-specific set of aspects and policy objects.
+specific set of aspects and adapter parameters.
 
-The above configuration state is required to have mixer know what to do with incoming attributes
+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 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:
+When a request comes in to 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
+- **Supplementary Attribute Production**. The first thing that happens in 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.
 
@@ -195,14 +200,14 @@ associated with each aspect and passes them those parameters.
 
 ## Scripting
 
-> This section is preliminary and subject to change. We're still experimenting with the concept of scripting in the mixer.
+> This section is preliminary and subject to change. We're still experimenting with the concept of scripting in Mixer.
 
-The mixer's attribute processing phase is implemented via a scripting language (exact language *TBD*). 
+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 the adapter parameters and dispatching
 control to individual configured adapters.
 
 For common uses, the operator authors adapter parameter 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
+and expression syntax. 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 adapter parameters.
 
 For advanced uses, the operator can bypass the declarative format and author directly in the scripting

docs/concepts/mixer/traffic.svg

@@ -76,7 +76,7 @@ The actual choice of the service version is determined dynamically by the
 Istio Proxy based on the routing rules set forth by the operator. This
 model enables the application code to decouple itself from the
 evolution of its dependent services, while providing other benefits as well
-(see [mixer](mixer.md)). Routing rules allow the proxy to select a version based on
+(see [mixer](mixer.md)). Routing rules allow Envoy to select a version based on
 criterion such as (headers, url, etc.), tags associated with
 source/destination and/or by weights assigned to each version.
 

docs/concepts/service-model.md

@@ -12,12 +12,12 @@ and what they are used for [here]({{site.baseurl}}/docs/concepts/attributes.html
 
 A given Istio deployment has a fixed vocabulary of attributes that it understands. The specific vocabulary is
 determined by the set of attribute producers being used in the deployment. The primary attribute producer in Istio
-is the proxy, although the mixer and services can also introduce attributes.
+is Envoy, although Mixer and services can also introduce attributes.
 
 ## Standard Istio attribute vocabulary
 
 The table below shows the set of canonical attributes and their respective types. Most Istio
-deployments will have agents (proxy or mixer adapters) that produce these attributes.
+deployments will have agents (Envoy or Mixer adapters) that produce these attributes.
 
 | Name | Type | Description | Kubernetes Example |
 |------|------|-------------|--------------------|

docs/reference/attribute-vocabulary.md

@@ -23,7 +23,7 @@ is the best fit for your content:
   <tr>
     <td>Concept</td>
     <td>A concept page explains some significant aspect of Istio. For example, a concept page might describe the 
-    mixer's configuration model and explain some of its subtleties.
+    Mixer's configuration model and explain some of its subtleties.
     Typically, concept pages don't include sequences of steps, but instead provide links to
     tasks or tutorials that do.</td>
   </tr>