diff --git a/_docs/concepts/policy-and-control/attributes.md b/_docs/concepts/policy-and-control/attributes.md index 236cc62cca..4b83c94cc4 100644 --- a/_docs/concepts/policy-and-control/attributes.md +++ b/_docs/concepts/policy-and-control/attributes.md @@ -13,7 +13,7 @@ The page describes Istio attributes, what they are and how they are used. ## 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 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 @@ -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. 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 -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 [here]({{home}}/docs/reference/config/mixer/attribute-vocabulary.html). diff --git a/_docs/concepts/policy-and-control/mixer-aspect-config.md.old b/_docs/concepts/policy-and-control/mixer-aspect-config.md.old deleted file mode 100644 index c35d16a709..0000000000 --- a/_docs/concepts/policy-and-control/mixer-aspect-config.md.old +++ /dev/null @@ -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). diff --git a/_docs/concepts/policy-and-control/mixer-config.md b/_docs/concepts/policy-and-control/mixer-config.md index 88d6670995..d395925ca8 100644 --- a/_docs/concepts/policy-and-control/mixer-config.md +++ b/_docs/concepts/policy-and-control/mixer-config.md @@ -60,7 +60,7 @@ Configuration is based on *adapters* and *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 |----------------------------|----------- @@ -82,14 +82,14 @@ spec: - **kind** - A Mixer assigned unique "kind" for every adapter and template. - **name** - The configuration resource name. - **namespace** - The namespace in which the configuration resource is applicable. -- **spec** - The `kind` specific configuration. +- **spec** - The `kind`-specific configuration. ### Handlers [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). 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. 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. 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 -delivered to it by Mixer. +Spec typically includes connection information necessary to connect to an external system. It may also include configuration to process the request instance +delivered to the adapter by Mixer. 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. @@ -148,7 +148,7 @@ adapters and their specific configuration formats can be found [here]({{home}}/d ### Instances 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 // Metric represents a single piece of data to report. @@ -164,7 +164,7 @@ type MetricInstanceParam struct { 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 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 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. diff --git a/_docs/reference/config/service-mesh.md.old b/_docs/reference/config/service-mesh.md.old deleted file mode 100644 index 2c099b4e43..0000000000 --- a/_docs/reference/config/service-mesh.md.old +++ /dev/null @@ -1,166 +0,0 @@ ---- -title: Service Mesh -overview: Global configuration schema - -order: 30 -draft: true -layout: docs -type: markdown ---- - - - -### ProxyMeshConfig -ProxyMeshConfig defines variables shared by all Envoy instances in the -Istio service mesh. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldTypeDescription
egressProxyAddressstringAddress of the egress envoy service (e.g. istio-egress:80).
discoveryAddressstringAddress of the discovery service exposing SDS, CDS, RDS (e.g. istio-pilot:8080).
mixerAddressstringMixer's address (e.g. istio-mixer:9090).
zipkinAddressstringAddress of the Zipkin service (e.g. zipkin:9411).
proxyListenPortint32Port on which envoy should listen for incoming connections from other services.
proxyAdminPortint32Port on which envoy should listen for administrative commands.
drainDurationDurationThe time in seconds that Envoy will drain connections during a hot restart. MUST be >=1s (e.g., 1s/1m/1h)
parentShutdownDurationDurationThe time in seconds that Envoy will wait before shutting down the parent process during a hot restart. MUST be >=1s (e.g., 1s/1m/1h). MUST BE greater than drainDuration parameter.
istioServiceClusterstring

istioServiceCluster defines the name for the serviceCluster that is shared by all Envoy instances. This setting corresponds to --service-cluster flag in Envoy. In a typical Envoy deployment, the service-cluster flag is used to identify the caller, for source-based routing scenarios.

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 --service-node flag when launching Envoy. When the RDS service receives API calls from Envoy, it uses the value of the service-node flag to compute routes that are relative to the service instances located at that IP address.

discoveryRefreshDelayDurationPolling interval for service discovery. (MUST BE >=1ms)
connectTimeoutDurationConnection timeout used by Envoy. (MUST BE >=1ms)
ingressClassstringClass of ingress resources to be processed by Istio ingress controller. This corresponds to the value of "kubernetes.io/ingress.class" annotation.
ingressServicestringName of the Kubernetes service used for the istio ingress controller.
ingressControllerModeIngressControllerModeDefines whether to use Istio ingress controller for annotated or all ingress resources.
authPolicyAuthPolicyAuthentication policy defines the global switch to control authentication for Envoy-to-Envoy communication.
authCertsPathstringPath to the secrets used by the authentication policy.
- - -### AuthPolicy - - - - - - - - - - - - - - - - - -
ValueDescription
NONEDo not encrypt Envoy to Envoy traffic.
MUTUAL_TLSEnvoy to Envoy traffic is wrapped into mutual TLS connections.
- - -### IngressControllerMode - - - - - - - - - - - - - - - - - - - - - - -
ValueDescription
OFFDisables Istio ingress controller.
DEFAULTIstio 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.
STRICTIstio 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).