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

Minor Mixer doc updates. (#603)

This commit is contained in:
Martin Taillefer 2017-10-04 13:51:45 -07:00 committed by GitHub
parent 2067b33be5
commit 62ea0b009d
4 changed files with 10 additions and 338 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
_docs/concepts/policy-and-control/attributes.md
View File

@ -13,7 +13,7 @@ The page describes Istio attributes, what they are and how they are used.
## Background ## Background
Istio uses *attributes* to control the runtime behavior of services running in the service mesh. Istio uses *attributes* to control the runtime behavior of services running in the mesh.
Attributes are named and typed pieces of metadata describing ingress and egress traffic and the Attributes are named and typed pieces of metadata describing ingress and egress traffic and the
environment this traffic occurs in. An Istio attribute carries a specific piece environment this traffic occurs in. An Istio attribute carries a specific piece
of information such as the error code of an API request, the latency of an API request, or the of information such as the error code of an API request, the latency of an API request, or the
@ -30,7 +30,7 @@ original IP address of a TCP connection. For example:
A given Istio deployment has a fixed vocabulary of attributes that it understands. 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 The specific vocabulary is determined by the set of attribute producers being used
in the deployment. The primary attribute producer in Istio is Envoy, although in the deployment. The primary attribute producer in Istio is Envoy, although
specialized Mixer adapters and services can also generate attributes. specialized Mixer adapters can also generate attributes.
The common baseline set of attributes available in most Istio deployments is defined The common baseline set of attributes available in most Istio deployments is defined
[here]({{home}}/docs/reference/config/mixer/attribute-vocabulary.html). [here]({{home}}/docs/reference/config/mixer/attribute-vocabulary.html).

162
_docs/concepts/policy-and-control/mixer-aspect-config.md.old
View File

@ -1,162 +0,0 @@
---
title: Mixer Aspect Configuration
overview: Explains how to configure a Mixer Aspect and its dependencies.
order: 38
draft: true
layout: docs
type: markdown
---
{% include home.html %}
{% capture aspectConfig %}{{home}}/docs/reference/config/mixer/aspects{% endcapture %}
{% capture adapterConfig %}{{home}}/docs/reference/config/mixer/adapters{% endcapture %}
{% capture mixerConfig %}{{home}}/docs/reference/config/mixer/mixer-config.html{% endcapture %}
{% capture tasks %}{{home}}/docs/tasks{% endcapture %}
Explains how to configure a Mixer _Aspect_ and its dependencies.
## Overview
Mixer configuration expresses system behavior by specifying three
key pieces of information: **what** action to take, **how** to take that action, and **when** to take that action.
* **What action to take:** [_Aspect_](./mixer-config.html#Aspects) configuration defines _what_ action to take. These actions include
logging, metrics collection, list checks, quota enforcement and others.
[_Descriptors_](./mixer-config.html#Descriptors) are named and re-usable parts of the aspect configuration.
For example the `metrics` aspect defines the [`MetricDescriptor`]({{mixerConfig}}#istio.mixer.v1.config.descriptor.MetricDescriptor) and refers to the MetricDescriptor instances by name.
* **How to take that action:** [_Adapter_](./mixer-config.html#Adapters) configuration defines _how_ to take an action.
The metrics adapter configuration includes details of the infrastructure backends.
* **When to take that action:** [_Selectors_](./mixer-config.html#Selectors) and `subjects` define _when_ to take an action.
Selectors are attribute-based expressions like `response.code == 200` and Subjects
are hierarchical resource names like `myservice.namespace.svc.cluster.local`.
## Configuration steps
Consider the following aspect configuration that [enables rate limits]({{tasks}}/rate-limiting.html).
```yaml
- aspects:
- kind: quotas
params:
quotas:
- descriptorName: RequestCount
maxAmount: 5
expiration: 1s
labels:
label1: destination.service
```
It _uses_ `RequestCount` to describe the quota.
The following is an example of the `RequestCount` descriptor.
```yaml
name: RequestCount
rate_limit: true
labels:
label1: 1 # STRING
```
In this example, `rate_limit` is `true`, hence the `aspect` must specify an `expiration`.
Similarly, the `aspect` must supply one label of type `string`.
Mixer delegates the work of applying rate limits to an `adapter` that implements the `quotas` kind.
[adapters.yml](https://github.com/istio/mixer/blob/master/testdata/configroot/scopes/global/adapters.yml) defines this configuration.
```yaml
- name: default
kind: quotas
impl: memQuota
params:
minDeduplicationDuration: 2s
```
The `memQuota` adapter in the above example takes one parameter. An operator may switch from
`memQuota` to `redisQuota` by specifying an alternate `quotas` adapter.
```yaml
- name: default
kind: quotas
impl: redisQuota
params:
redisServerUrl: redisHost:6379
minDeduplicationDuration: 2s
```
The following example shows how to use a [_selector_](./mixer-config.html#Selectors) to apply rate limits selectively.
```yaml
- selector: source.labels["app"]=="reviews" && source.labels["version"] == "v3"
aspects:
- kind: quotas
params:
quotas:
- descriptorName: RequestCount
maxAmount: 5
expiration: 1s
labels:
label1: destination.service
```
## Aspect associations
The steps outlined in the previous section apply to all of Mixer's aspects.
Each aspect requires specific `desciptors` and `adapters`.
The following table enumerates valid combinations of the `aspects`, the `descriptors` and the `adapters`.
|Aspect |Descriptors |Adapters
|-----------------------------------------------
|[Quota enforcement]({{aspectConfig}}/quotas.html ) | [QuotaDescriptor]({{mixerConfig}}#istio.mixer.v1.config.descriptor.QuotaDescriptor) | [memQuota]({{adapterConfig}}/memQuota.html), [redisQuota]({{adapterConfig}}/redisquota.html)
|[Metrics collection]({{aspectConfig}}/metrics.html)| [MetricDescriptor]({{mixerConfig}}#metricdescriptor) |[prometheus]({{adapterConfig}}/prometheus.html),[statsd]({{adapterConfig}}/statsd.html)
|[Whitelist/Blacklist]({{aspectConfig}}/lists.html)| None |[genericListChecker]({{adapterConfig}}/genericListChecker.html),[listchecker]({{adapterConfig}}/list.html)
|[Access logs]({{aspectConfig}}/accessLogs.html)|[LogEntryDescriptor]({{mixerConfig}}#logentrydescriptor) |[stdioLogger]({{adapterConfig}}/stdioLogger.html)
|[Application logs]({{aspectConfig}}/applicationLogs.html)|[LogEntryDescriptor]({{mixerConfig}}#logentrydescriptor) |[stdioLogger]({{adapterConfig}}/stdioLogger.html)
|[Deny Request]({{aspectConfig}}/denials.html)| None |[denyChecker]({{adapterConfig}}/denier.html)
Istio uses [`protobufs`](https://developers.google.com/protocol-buffers/) to define configuration schemas. The [Writing Configuration]({{home}}/docs/reference/writing-config.html) document explains how to express `proto` definitions as `yaml`.
## Organization of configuration
Aspect configuration applies to a `subject`. A `Subject` is a resource in a hierarchy.
Typically `subject` is the fully qualified name of a service, namespace or a cluster. An aspect configuration may apply
to the `subject` resource and its sub-resources.
## Pushing configuration
`istioctl` pushes configuration changes to the API server.
As of the alpha release, the API server supports pushing only aspect rules.
A temporary workaround allows you to push `adapters.yml` and `descriptors.yml` as follows.
1. Find the Mixer pod FIXME
```bash
kubectl get pods -l istio=mixer
```
The output is similar to this:
```
NAME READY STATUS RESTARTS AGE
istio-mixer-2657627433-3r0nn 1/1 Running 0 2d
```
2. Fetch adapters.yml from Mixer
``` bash
kubectl cp istio-mixer-2657627433-3r0nn:/etc/opt/mixer/configroot/scopes/global/adapters.yml adapters.yml
```
3. Edit the file and push it back.
```bash
kubectl cp adapters.yml istio-mixer-2657627433-3r0nn:/etc/opt/mixer/configroot/scopes/global/adapters.yml
```
4. `/etc/opt/mixer/configroot/scopes/global/descriptors.yml` is similarly updated.
5. View Mixer logs to see validation errors since the above operation bypasses the API server.
## Default configuration
Mixer provides default definitions for commonly used
[descriptors](https://github.com/istio/mixer/blob/master/testdata/configroot/scopes/global/descriptors.yml) and
[adapters](https://github.com/istio/mixer/blob/master/testdata/configroot/scopes/global/adapters.yml).
## What's next
* Learn more about [Mixer](./mixer.html) and [Mixer Config](./mixer-config.html).
* Discover the full [Attribute Vocabulary]({{home}}/docs/reference/config/mixer/attribute-vocabulary.html).

16
_docs/concepts/policy-and-control/mixer-config.md
View File

@ -60,7 +60,7 @@ Configuration is based on *adapters* and *templates*.
An adapter may support multiple templates. An adapter may support multiple templates.
Configuration is expressed using a YAML format built around the following abstractions. These abstractions are later explained in detail. Configuration is expressed using a YAML format built around the following abstractions:
|Concept |Description |Concept |Description
|----------------------------|----------- |----------------------------|-----------
@ -82,14 +82,14 @@ spec:
- **kind** - A Mixer assigned unique "kind" for every adapter and template. - **kind** - A Mixer assigned unique "kind" for every adapter and template.
- **name** - The configuration resource name. - **name** - The configuration resource name.
- **namespace** - The namespace in which the configuration resource is applicable. - **namespace** - The namespace in which the configuration resource is applicable.
- **spec** - The `kind` specific configuration. - **spec** - The `kind`-specific configuration.
### Handlers ### Handlers
[Adapters](./mixer.html#adapters) encapsulates the logic necessary to interface Mixer with specific external infrastructure [Adapters](./mixer.html#adapters) encapsulates the logic necessary to interface Mixer with specific external infrastructure
backends such as [Prometheus](https://prometheus.io), [New Relic](https://newrelic.com), or [Stackdriver](https://cloud.google.com/logging). backends such as [Prometheus](https://prometheus.io), [New Relic](https://newrelic.com), or [Stackdriver](https://cloud.google.com/logging).
Individual adapters generally need operational parameters in order to do their work. For example, a logging adapter may require Individual adapters generally need operational parameters in order to do their work. For example, a logging adapter may require
the IP address and port of the log sink. the IP address and port of the log sink.
Here is an example showing how to configure an adapter of kind = `listchecker`. The listchecker adapter checks the input value against a list. Here is an example showing how to configure an adapter of kind = `listchecker`. The listchecker adapter checks the input value against a list.
If the adapter is configured for a whitelist, it returns success if the input value is found in the list. If the adapter is configured for a whitelist, it returns success if the input value is found in the list.
@ -109,8 +109,8 @@ spec:
`staticversion.listchecker.istio-system` and it must be unique. `staticversion.listchecker.istio-system` and it must be unique.
An adapter defines the schema of the `spec` section as a proto message. An adapter defines the schema of the `spec` section as a proto message.
Spec typically includes connection information necessary to connect to an external systems. It may also include configuration to process the request instance Spec typically includes connection information necessary to connect to an external system. It may also include configuration to process the request instance
delivered to it by Mixer. delivered to the adapter by Mixer.
Some adapters implement functionality that goes beyond connecting Mixer to a backend. Some adapters implement functionality that goes beyond connecting Mixer to a backend.
For example, the `prometheus` adapter consumes metrics observations and aggregates them as distributions or counters in a configurable way. For example, the `prometheus` adapter consumes metrics observations and aggregates them as distributions or counters in a configurable way.
@ -148,7 +148,7 @@ adapters and their specific configuration formats can be found [here]({{home}}/d
### Instances ### Instances
Instance configuration specifies the request mapping from attributes to adapter inputs. An adapter consumes a set of instance types. Instance configuration specifies the request mapping from attributes to adapter inputs. An adapter consumes a set of instance types.
The prometheus adapter from the previous section consumes instances from the metrics template. The prometheus adapter from the previous section consumes instances produced from the `metric` template.
```go ```go
// Metric represents a single piece of data to report. // Metric represents a single piece of data to report.
@ -164,7 +164,7 @@ type MetricInstanceParam struct {
MonitoredResourceDimensions map[string]string MonitoredResourceDimensions map[string]string
} }
``` ```
The following is an example of a metrics instance configuration that produces the `requestduration` metric. The following is an example of a metric instance configuration that produces the `requestduration` metric.
```yaml ```yaml
apiVersion: config.istio.io/v1alpha2 apiVersion: config.istio.io/v1alpha2
@ -255,7 +255,7 @@ Resolution depends on a well-known attribute to guide its choice, called *identi
The default identity attribute is `destination.service`. The default identity attribute is `destination.service`.
The mesh-wide configuration is stored in the `configDefaultNamespace` whose default value is `istio-system`. The mesh-wide configuration is stored in the `configDefaultNamespace` whose default value is `istio-system`.
Mixer resolver goes through the following steps to arrive at the set of `actions`. Mixer goes through the following steps to arrive at the set of `actions`.
1. Extract the value of the identity attribute from the request. 1. Extract the value of the identity attribute from the request.

166
_docs/reference/config/service-mesh.md.old
View File

@ -1,166 +0,0 @@
---
title: Service Mesh
overview: Global configuration schema
order: 30
draft: true
layout: docs
type: markdown
---
<a name="istio.proxy.v1.config.ProxyMeshConfig"></a>
### ProxyMeshConfig
ProxyMeshConfig defines variables shared by all Envoy instances in the
Istio service mesh.
<table>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
<a name="istio.proxy.v1.config.ProxyMeshConfig.egressProxyAddress"></a>
<tr>
<td><code>egressProxyAddress</code></td>
<td>string</td>
<td>Address of the egress envoy service (e.g. <em>istio-egress:80</em>).</td>
</tr>
<a name="istio.proxy.v1.config.ProxyMeshConfig.discoveryAddress"></a>
<tr>
<td><code>discoveryAddress</code></td>
<td>string</td>
<td>Address of the discovery service exposing SDS, CDS, RDS (e.g. <em>istio-pilot:8080</em>).</td>
</tr>
<a name="istio.proxy.v1.config.ProxyMeshConfig.mixerAddress"></a>
<tr>
<td><code>mixerAddress</code></td>
<td>string</td>
<td>Mixer's address (e.g. <em>istio-mixer:9090</em>).</td>
</tr>
<a name="istio.proxy.v1.config.ProxyMeshConfig.zipkinAddress"></a>
<tr>
<td><code>zipkinAddress</code></td>
<td>string</td>
<td>Address of the Zipkin service (e.g. <em>zipkin:9411</em>).</td>
</tr>
<a name="istio.proxy.v1.config.ProxyMeshConfig.proxyListenPort"></a>
<tr>
<td><code>proxyListenPort</code></td>
<td>int32</td>
<td>Port on which envoy should listen for incoming connections from other services.</td>
</tr>
<a name="istio.proxy.v1.config.ProxyMeshConfig.proxyAdminPort"></a>
<tr>
<td><code>proxyAdminPort</code></td>
<td>int32</td>
<td>Port on which envoy should listen for administrative commands.</td>
</tr>
<a name="istio.proxy.v1.config.ProxyMeshConfig.drainDuration"></a>
<tr>
<td><code>drainDuration</code></td>
<td><a href="https://developers.google.com/protocol-buffers/docs/reference/google.protobuf#duration">Duration</a></td>
<td>The time in seconds that Envoy will drain connections during a hot restart. MUST be &gt;=1s (e.g., <em>1s/1m/1h</em>)</td>
</tr>
<a name="istio.proxy.v1.config.ProxyMeshConfig.parentShutdownDuration"></a>
<tr>
<td><code>parentShutdownDuration</code></td>
<td><a href="https://developers.google.com/protocol-buffers/docs/reference/google.protobuf#duration">Duration</a></td>
<td>The time in seconds that Envoy will wait before shutting down the parent process during a hot restart. MUST be &gt;=1s (e.g., <em>1s/1m/1h</em>). MUST BE greater than <em>drainDuration</em> parameter.</td>
</tr>
<a name="istio.proxy.v1.config.ProxyMeshConfig.istioServiceCluster"></a>
<tr>
<td><code>istioServiceCluster</code></td>
<td>string</td>
<td><p>istioServiceCluster defines the name for the serviceCluster that is shared by all Envoy instances. This setting corresponds to <em>--service-cluster</em> flag in Envoy. In a typical Envoy deployment, the <em>service-cluster</em> flag is used to identify the caller, for source-based routing scenarios.</p><p>Since Istio does not assign a local service/service version to each Envoy instance, the name is same for all of them. However, the source/caller's identity (e.g., IP address) is encoded in the <em>--service-node</em> flag when launching Envoy. When the RDS service receives API calls from Envoy, it uses the value of the <em>service-node</em> flag to compute routes that are relative to the service instances located at that IP address.</p></td>
</tr>
<a name="istio.proxy.v1.config.ProxyMeshConfig.discoveryRefreshDelay"></a>
<tr>
<td><code>discoveryRefreshDelay</code></td>
<td><a href="https://developers.google.com/protocol-buffers/docs/reference/google.protobuf#duration">Duration</a></td>
<td>Polling interval for service discovery. (MUST BE &gt;=1ms)</td>
</tr>
<a name="istio.proxy.v1.config.ProxyMeshConfig.connectTimeout"></a>
<tr>
<td><code>connectTimeout</code></td>
<td><a href="https://developers.google.com/protocol-buffers/docs/reference/google.protobuf#duration">Duration</a></td>
<td>Connection timeout used by Envoy. (MUST BE &gt;=1ms)</td>
</tr>
<a name="istio.proxy.v1.config.ProxyMeshConfig.ingressClass"></a>
<tr>
<td><code>ingressClass</code></td>
<td>string</td>
<td>Class of ingress resources to be processed by Istio ingress controller. This corresponds to the value of "kubernetes.io/ingress.class" annotation.</td>
</tr>
<a name="istio.proxy.v1.config.ProxyMeshConfig.ingressService"></a>
<tr>
<td><code>ingressService</code></td>
<td>string</td>
<td>Name of the Kubernetes service used for the istio ingress controller.</td>
</tr>
<a name="istio.proxy.v1.config.ProxyMeshConfig.ingressControllerMode"></a>
<tr>
<td><code>ingressControllerMode</code></td>
<td><a href="#istio.proxy.v1.config.ProxyMeshConfig.IngressControllerMode">IngressControllerMode</a></td>
<td>Defines whether to use Istio ingress controller for annotated or all ingress resources.</td>
</tr>
<a name="istio.proxy.v1.config.ProxyMeshConfig.authPolicy"></a>
<tr>
<td><code>authPolicy</code></td>
<td><a href="#istio.proxy.v1.config.ProxyMeshConfig.AuthPolicy">AuthPolicy</a></td>
<td>Authentication policy defines the global switch to control authentication for Envoy-to-Envoy communication.</td>
</tr>
<a name="istio.proxy.v1.config.ProxyMeshConfig.authCertsPath"></a>
<tr>
<td><code>authCertsPath</code></td>
<td>string</td>
<td>Path to the secrets used by the authentication policy.</td>
</tr>
</table>
<a name="istio.proxy.v1.config.ProxyMeshConfig.AuthPolicy"></a>
### AuthPolicy
<table>
<tr>
<th>Value</th>
<th>Description</th>
</tr>
<a name="istio.proxy.v1.config.ProxyMeshConfig.AuthPolicy.NONE"></a>
<tr>
<td>NONE</td>
<td>Do not encrypt Envoy to Envoy traffic.</td>
</tr>
<a name="istio.proxy.v1.config.ProxyMeshConfig.AuthPolicy.MUTUAL_TLS"></a>
<tr>
<td>MUTUAL_TLS</td>
<td>Envoy to Envoy traffic is wrapped into mutual TLS connections.</td>
</tr>
</table>
<a name="istio.proxy.v1.config.ProxyMeshConfig.IngressControllerMode"></a>
### IngressControllerMode
<table>
<tr>
<th>Value</th>
<th>Description</th>
</tr>
<a name="istio.proxy.v1.config.ProxyMeshConfig.IngressControllerMode.OFF"></a>
<tr>
<td>OFF</td>
<td>Disables Istio ingress controller.</td>
</tr>
<a name="istio.proxy.v1.config.ProxyMeshConfig.IngressControllerMode.DEFAULT"></a>
<tr>
<td>DEFAULT</td>
<td>Istio ingress controller will act on ingress resources that do not contain any annotation or whose annotations match the value specified in the ingressClass parameter described earlier. Use this mode if Istio ingress controller will be the default ingress controller for the entire kubernetes cluster.</td>
</tr>
<a name="istio.proxy.v1.config.ProxyMeshConfig.IngressControllerMode.STRICT"></a>
<tr>
<td>STRICT</td>
<td>Istio ingress controller will only act on ingress resources whose annotations match the value specified in the ingressClass parameter described earlier. Use this mode if Istio ingress controller will be a secondary ingress controller (e.g., in addition to a cloud-provided ingress controller).</td>
</tr>
</table>