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

Update mixer proto generated docs (#129) 

* Re-regenerate the protos

* Update the metric desc by hand for the pending fix to code snippets in its comments

* Add a file for the status proto's docs, refer to it everywhere and remove the embedded status docs generated everywhere they're used.

* remove mixer services's embedded status proto by hand
This commit is contained in:
Zack 2017-05-08 18:04:53 -07:00 committed by GitHub
parent 69526d7990
commit 34b88ab280
21 changed files with 1467 additions and 423 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

34
_docs/reference/api/mixer/adapters/denyChecker.md Normal file
View File

@ -0,0 +1,34 @@
---
title: denyChecker Config
overview: Generated documentation for Mixer's denyChecker Adapter Configuration Schema
order: 0
layout: docs
type: markdown
---
<a name="rpcAdapter.denyChecker.configIndex"></a>
### Index
* [Params](#adapter.denyChecker.config.Params)
(message)
<a name="adapter.denyChecker.config.Params"></a>
### Params
<table>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
<a name="adapter.denyChecker.config.Params.error"></a>
<tr>
<td><code>error</code></td>
<td><a href="/docs/reference/api/status.html">Status</a></td>
<td>The error to return when denying a request.</td>
</tr>
</table>

33
_docs/reference/api/mixer/adapters/genericListChecker.md Normal file
View File

@ -0,0 +1,33 @@
---
title: genericListChecker Config
overview: Generated documentation for Mixer's genericListChecker Adapter Configuration Schema
order: 10
layout: docs
type: markdown
---
<a name="rpcAdapter.genericListChecker.configIndex"></a>
### Index
* [Params](#adapter.genericListChecker.config.Params)
(message)
<a name="adapter.genericListChecker.config.Params"></a>
### Params
<table>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
<a name="adapter.genericListChecker.config.Params.listEntries"></a>
<tr>
<td><code>listEntries[]</code></td>
<td>repeated string</td>
<td>The set of entries in the list to check against</td>
</tr>
</table>

12
_docs/reference/api/mixer/adapters/index.md Normal file
View File

@ -0,0 +1,12 @@
---
title: Mixer Adapters
overview: Generated documentation for Mixer's adapters.
order: 2000
layout: docs
type: markdown
---
{% include section-index.html %}

45
_docs/reference/api/mixer/adapters/ipListChecker.md Normal file
View File

@ -0,0 +1,45 @@
---
title: ipListChecker Config
overview: Generated documentation for Mixer's ipListChecker Adapter Configuration Schema
order: 20
layout: docs
type: markdown
---
<a name="rpcAdapter.ipListChecker.configIndex"></a>
### Index
* [Params](#adapter.ipListChecker.config.Params)
(message)
<a name="adapter.ipListChecker.config.Params"></a>
### Params
<table>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
<a name="adapter.ipListChecker.config.Params.providerUrl"></a>
<tr>
<td><code>providerUrl</code></td>
<td>string</td>
<td>Where to find the list to check against</td>
</tr>
<a name="adapter.ipListChecker.config.Params.refreshInterval"></a>
<tr>
<td><code>refreshInterval</code></td>
<td><a href="https://developers.google.com/protocol-buffers/docs/reference/google.protobuf#duration">Duration</a></td>
<td>Determines how often the provider is polled for an updated list</td>
</tr>
<a name="adapter.ipListChecker.config.Params.ttl"></a>
<tr>
<td><code>ttl</code></td>
<td><a href="https://developers.google.com/protocol-buffers/docs/reference/google.protobuf#duration">Duration</a></td>
<td>Indicates how long to keep a list before discarding it. Typically, the TTL value should be set to noticeably longer (&gt; 2x) than the refresh interval to ensure continued operation in the face of transient server outages.</td>
</tr>
</table>

151
_docs/reference/api/mixer/adapters/kubernetes.md Normal file
View File

@ -0,0 +1,151 @@
---
title: kubernetes Config
overview: Generated documentation for Mixer's kubernetes Adapter Configuration Schema
order: 30
layout: docs
type: markdown
---
<a name="rpcAdapter.kubernetes.configIndex"></a>
### Index
* [Params](#adapter.kubernetes.config.Params)
(message)
<a name="adapter.kubernetes.config.Params"></a>
### Params
Configuration parameters for the kubernetes adapter. These params
control the manner in which the kubernetes adapter discovers and
generates values related to pod information.
The adapter works by looking up pod information by UIDs (of the
form: "kubernetes://pod.namespace"). It expects that the UIDs will be
supplied in an input map for three distinct traffic classes (source,
target, and origin).
For all valid UIDs supplied, this adapter generates a map of output
values containing information about the related pods. The generated map
is keyed by value names generated by concatenating a pod identifier
prefix with a value name. For example, for the pod corresponding to a
sourceUID and the output value of pod ip, this adapter will output a map
that includes a key of "sourcePodIP" (assuming parameter defaults).
next field id: 19
<table>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
<a name="adapter.kubernetes.config.Params.kubeconfigPath"></a>
<tr>
<td><code>kubeconfigPath</code></td>
<td>string</td>
<td><p>File path to discover kubeconfig. For in-cluster configuration, this should be left unset. For local configuration, this should be set to the path of a kubeconfig file that can be used to reach a kubernetes API server.</p><p>Default: "" (unset)</p></td>
</tr>
<a name="adapter.kubernetes.config.Params.cacheRefreshDuration"></a>
<tr>
<td><code>cacheRefreshDuration</code></td>
<td><a href="https://developers.google.com/protocol-buffers/docs/reference/google.protobuf#duration">Duration</a></td>
<td><p>Controls the resync period of the kubernetes cluster info cache. The cache will watch for events and every so often completely resync. This controls how frequently the complete resync occurs.</p><p>Default: 5 minutes</p></td>
</tr>
<a name="adapter.kubernetes.config.Params.sourceUidInputName"></a>
<tr>
<td><code>sourceUidInputName</code></td>
<td>string</td>
<td><p>Configures how the UID for the source pod for traffic is identified in the input map.</p><p>Default: sourceUID</p></td>
</tr>
<a name="adapter.kubernetes.config.Params.targetUidInputName"></a>
<tr>
<td><code>targetUidInputName</code></td>
<td>string</td>
<td><p>Configures how the UID for the target pod for traffic is identified in the input map.</p><p>Default: targetUID</p></td>
</tr>
<a name="adapter.kubernetes.config.Params.originUidInputName"></a>
<tr>
<td><code>originUidInputName</code></td>
<td>string</td>
<td><p>Configures how the UID for the origin pod for traffic is identified in the input map.</p><p>Default: originUID</p></td>
</tr>
<a name="adapter.kubernetes.config.Params.targetServiceInputName"></a>
<tr>
<td><code>targetServiceInputName</code></td>
<td>string</td>
<td><p>Configures how the identifier for the target service is populated in the input map (if at all). When supplied, this value will be used (after successful normalization) in place of the value derived from the pod cache for the target pod in the generated map of output values.</p><p>Default: targetService</p></td>
</tr>
<a name="adapter.kubernetes.config.Params.clusterDomainName"></a>
<tr>
<td><code>clusterDomainName</code></td>
<td>string</td>
<td><p>Configures the cluster domain name to use for service name normalization.</p><p>Default: svc.cluster.local</p></td>
</tr>
<a name="adapter.kubernetes.config.Params.podLabelForService"></a>
<tr>
<td><code>podLabelForService</code></td>
<td>string</td>
<td><p>In order to extract the service associated with a source, target, or origin, this adapter relies on pod labels. In particular, it looks for the value of a specific label, as specified by this parameter.</p><p>Default: app</p></td>
</tr>
<a name="adapter.kubernetes.config.Params.sourcePrefix"></a>
<tr>
<td><code>sourcePrefix</code></td>
<td>string</td>
<td><p>The prefix used for source pod output value names.</p><p>Default: source</p></td>
</tr>
<a name="adapter.kubernetes.config.Params.targetPrefix"></a>
<tr>
<td><code>targetPrefix</code></td>
<td>string</td>
<td><p>The prefix used for target pod output value names.</p><p>Default: target</p></td>
</tr>
<a name="adapter.kubernetes.config.Params.originPrefix"></a>
<tr>
<td><code>originPrefix</code></td>
<td>string</td>
<td><p>The prefix used for origin pod output value names.</p><p>Default: origin</p></td>
</tr>
<a name="adapter.kubernetes.config.Params.labelsValueName"></a>
<tr>
<td><code>labelsValueName</code></td>
<td>string</td>
<td><p>The value name for the pod labels output value.</p><p>Default: Labels</p></td>
</tr>
<a name="adapter.kubernetes.config.Params.podNameValueName"></a>
<tr>
<td><code>podNameValueName</code></td>
<td>string</td>
<td><p>The value name for the pod name output value.</p><p>Default: PodName</p></td>
</tr>
<a name="adapter.kubernetes.config.Params.podIpValueName"></a>
<tr>
<td><code>podIpValueName</code></td>
<td>string</td>
<td><p>The value name for the pod ip address output value.</p><p>Default: PodIP</p></td>
</tr>
<a name="adapter.kubernetes.config.Params.hostIpValueName"></a>
<tr>
<td><code>hostIpValueName</code></td>
<td>string</td>
<td><p>The value name for the pod host ip address output value.</p><p>Default: HostIP</p></td>
</tr>
<a name="adapter.kubernetes.config.Params.namespaceValueName"></a>
<tr>
<td><code>namespaceValueName</code></td>
<td>string</td>
<td><p>The value name for the pod namespace output value.</p><p>Default: Namespace</p></td>
</tr>
<a name="adapter.kubernetes.config.Params.serviceAccountValueName"></a>
<tr>
<td><code>serviceAccountValueName</code></td>
<td>string</td>
<td><p>The value name for the pod service account name output value.</p><p>Default: ServiceAccountName</p></td>
</tr>
<a name="adapter.kubernetes.config.Params.serviceValueName"></a>
<tr>
<td><code>serviceValueName</code></td>
<td>string</td>
<td><p>The value name for the service output value.</p><p>Default: Service</p></td>
</tr>
</table>

33
_docs/reference/api/mixer/adapters/memQuota.md Normal file
View File

@ -0,0 +1,33 @@
---
title: memQuota Config
overview: Generated documentation for Mixer's memQuota Adapter Configuration Schema
order: 40
layout: docs
type: markdown
---
<a name="rpcAdapter.memQuota.configIndex"></a>
### Index
* [Params](#adapter.memQuota.config.Params)
(message)
<a name="adapter.memQuota.config.Params"></a>
### Params
<table>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
<a name="adapter.memQuota.config.Params.minDeduplicationDuration"></a>
<tr>
<td><code>minDeduplicationDuration</code></td>
<td><a href="https://developers.google.com/protocol-buffers/docs/reference/google.protobuf#duration">Duration</a></td>
<td>Minimum number of seconds that deduplication is possible for a given operation.</td>
</tr>
</table>

21
_docs/reference/api/mixer/adapters/prometheus.md Normal file
View File

@ -0,0 +1,21 @@
---
title: prometheus Config
overview: Generated documentation for Mixer's prometheus Adapter Configuration Schema
order: 50
layout: docs
type: markdown
---
<a name="rpcAdapter.prometheus.configIndex"></a>
### Index
* [Params](#adapter.prometheus.config.Params)
(message)
<a name="adapter.prometheus.config.Params"></a>
### Params
NOTE: _No fields in this message type.__

57
_docs/reference/api/mixer/adapters/redisquota.md Normal file
View File

@ -0,0 +1,57 @@
---
title: redisquota Config
overview: Generated documentation for Mixer's redisquota Adapter Configuration Schema
order: 60
layout: docs
type: markdown
---
<a name="rpcAdapter.redisquota.configIndex"></a>
### Index
* [Params](#adapter.redisquota.config.Params)
(message)
<a name="adapter.redisquota.config.Params"></a>
### Params
<table>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
<a name="adapter.redisquota.config.Params.minDeduplicationDuration"></a>
<tr>
<td><code>minDeduplicationDuration</code></td>
<td><a href="https://developers.google.com/protocol-buffers/docs/reference/google.protobuf#duration">Duration</a></td>
<td>Minimum number of seconds that deduplication is possible for a given operation.</td>
</tr>
<a name="adapter.redisquota.config.Params.redisServerUrl"></a>
<tr>
<td><code>redisServerUrl</code></td>
<td>string</td>
<td>Redis network address</td>
</tr>
<a name="adapter.redisquota.config.Params.socketType"></a>
<tr>
<td><code>socketType</code></td>
<td>string</td>
<td>Network for communicating with redis, i.e., "tcp"</td>
</tr>
<a name="adapter.redisquota.config.Params.connectionPoolSize"></a>
<tr>
<td><code>connectionPoolSize</code></td>
<td>int64</td>
<td>Maximum number of idle connections to redis</td>
</tr>
<a name="adapter.redisquota.config.Params.rateLimitAlgorithm"></a>
<tr>
<td><code>rateLimitAlgorithm</code></td>
<td>string</td>
<td>Algorithm for rate-limiting: either fixed-window or rolling-window. The fixed-window approach can allow 2x peak specified rate, whereas the rolling-window doesn't. The rolling-window algorithm's additional precision comes at the cost of increased redis resource usage.</td>
</tr>
</table>

63
_docs/reference/api/mixer/adapters/statsd.md Normal file
View File

@ -0,0 +1,63 @@
---
title: statsd Config
overview: Generated documentation for Mixer's statsd Adapter Configuration Schema
order: 70
layout: docs
type: markdown
---
<a name="rpcAdapter.statsd.configIndex"></a>
### Index
* [Params](#adapter.statsd.config.Params)
(message)
<a name="adapter.statsd.config.Params"></a>
### Params
<table>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
<a name="adapter.statsd.config.Params.address"></a>
<tr>
<td><code>address</code></td>
<td>string</td>
<td>Address of the statsd server, e.g. localhost:8125</td>
</tr>
<a name="adapter.statsd.config.Params.prefix"></a>
<tr>
<td><code>prefix</code></td>
<td>string</td>
<td>Metric prefix, do not specify for no prefix</td>
</tr>
<a name="adapter.statsd.config.Params.flushDuration"></a>
<tr>
<td><code>flushDuration</code></td>
<td><a href="https://developers.google.com/protocol-buffers/docs/reference/google.protobuf#duration">Duration</a></td>
<td>Flush Interval controls the maximum amount of time between sending metrics to the statsd collection server. Metrics are reported when either flushBytes is full or flushInterval time has elapsed since the last report.</td>
</tr>
<a name="adapter.statsd.config.Params.flushBytes"></a>
<tr>
<td><code>flushBytes</code></td>
<td>int32</td>
<td>Maximum UDP packet size to send; if not specified defaults to 512 bytes. If the statsd server is running on the same (private) network 1432 bytes is recommended for better performance.</td>
</tr>
<a name="adapter.statsd.config.Params.samplingRate"></a>
<tr>
<td><code>samplingRate</code></td>
<td>float</td>
<td>Chance that any particular metric is sampled when incremented; can take the range [0, 1], defaults to 1 if unspecified.</td>
</tr>
<a name="adapter.statsd.config.Params.metricNameTemplateStrings"></a>
<tr>
<td><code>metricNameTemplateStrings</code></td>
<td>repeated map&lt;string, string&gt;</td>
<td><p>Map of metric name -&gt; template string; the template will be filled with values from the metric's labels and the resulting string will be used as the statsd metric name. This allows easier creation of statsd metrics like <code>actionName-responseCode</code>. The template strings must conform to go's text/template syntax. For the example of <code>actionName-responseCode</code>, we use the template: <code>\{\{.apiMethod\}\}-\{\{.responseCode\}\}</code></p><p>If a metric's name is not in the map then the exported statsd metric name will be exactly the metric's name.</p></td>
</tr>
</table>

57
_docs/reference/api/mixer/adapters/stdioLogger.md Normal file
View File

@ -0,0 +1,57 @@
---
title: stdioLogger Config
overview: Generated documentation for Mixer's stdioLogger Adapter Configuration Schema
order: 80
layout: docs
type: markdown
---
<a name="rpcAdapter.stdioLogger.configIndex"></a>
### Index
* [Params](#adapter.stdioLogger.config.Params)
(message)
* [Params.Stream](#adapter.stdioLogger.config.Params.Stream)
(enum)
<a name="adapter.stdioLogger.config.Params"></a>
### Params
<table>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
<a name="adapter.stdioLogger.config.Params.logStream"></a>
<tr>
<td><code>logStream</code></td>
<td><a href="#adapter.stdioLogger.config.Params.Stream">Stream</a></td>
<td>Selects which standard stream to write to for log entries. STDERR is the default Stream.</td>
</tr>
</table>
<a name="adapter.stdioLogger.config.Params.Stream"></a>
### Stream
Stream is used to select between different logs output sinks.
<table>
<tr>
<th>Value</th>
<th>Description</th>
</tr>
<a name="adapter.stdioLogger.config.Params.Stream.STDERR"></a>
<tr>
<td>STDERR</td>
<td>STDERR refers to os.Stderr.</td>
</tr>
<a name="adapter.stdioLogger.config.Params.Stream.STDOUT"></a>
<tr>
<td>STDOUT</td>
<td>STDOUT refers to os.Stdout.</td>
</tr>
</table>

95
_docs/reference/api/mixer/aspects/accessLogs.md Normal file
View File

@ -0,0 +1,95 @@
---
title: accessLogs Config
overview: Generated documentation for Mixer's Aspect Configuration Schema
order: 1120
layout: docs
type: markdown
---
<a name="rpcAspect.configIndex"></a>
### Index
* [AccessLogsParams](#aspect.config.AccessLogsParams)
(message)
* [AccessLogsParams.AccessLog](#aspect.config.AccessLogsParams.AccessLog)
(message)
<a name="aspect.config.AccessLogsParams"></a>
### AccessLogsParams
Example usage:
kind: access-logs
params:
logName: "accessLog"
log:
logFormat: COMMON
templateExpressions:
originIp: origin.ip
sourceUser: origin.user
timestamp: request.time
method: request.method | ""
url: request.path
protocol: request.scheme
responseCode: response.code
responseSize: response.size
labels:
originIp: origin.ip
sourceUser: origin.user
timestamp: request.time
method: request.method | ""
url: request.path
protocol: request.scheme
responseCode: response.code
responseSize: response.size
<table>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
<a name="aspect.config.AccessLogsParams.logName"></a>
<tr>
<td><code>logName</code></td>
<td>string</td>
<td>Identifies a collection of related log entries.</td>
</tr>
<a name="aspect.config.AccessLogsParams.log"></a>
<tr>
<td><code>log</code></td>
<td><a href="#aspect.config.AccessLogsParams.AccessLog">AccessLog</a></td>
<td>The log that will be constructed and handed to the aspect at runtime.</td>
</tr>
</table>
<a name="aspect.config.AccessLogsParams.AccessLog"></a>
### AccessLog
Describes how attributes must be evaluated to produce values for a log message.
<table>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
<a name="aspect.config.AccessLogsParams.AccessLog.descriptorName"></a>
<tr>
<td><code>descriptorName</code></td>
<td>string</td>
<td>Only used if logFormat is CUSTOM. Links this AccessLog to a LogEntryDescriptor that describes the log's template.</td>
</tr>
<a name="aspect.config.AccessLogsParams.AccessLog.templateExpressions"></a>
<tr>
<td><code>templateExpressions</code></td>
<td>repeated map&lt;string, string&gt;</td>
<td>Map of template variable name to expression for the descriptor's logTemplate. At run time each expression will be evaluated, and together they will provide values for the log's template string. Labels and template expressions do not mix: if the result of some expression is needed for both constructing the payload and for dimensioning the log entry, it must be included both in these expressions and in the <code>labels</code> expressions.</td>
</tr>
<a name="aspect.config.AccessLogsParams.AccessLog.labels"></a>
<tr>
<td><code>labels</code></td>
<td>repeated map&lt;string, string&gt;</td>
<td>Map of LogEntryDescriptor label name to attribute expression. At run time each expression will be evaluated to determine the value that will be used to fill in the log template. The result of evaluating the expression must match the ValueType of the label in the LogEntryDescriptor.</td>
</tr>
</table>

89
_docs/reference/api/mixer/aspects/applicationLogs.md Normal file
View File

@ -0,0 +1,89 @@
---
title: applicationLogs Config
overview: Generated documentation for Mixer's Aspect Configuration Schema
order: 1130
layout: docs
type: markdown
---
<a name="rpcAspect.configIndex"></a>
### Index
* [ApplicationLogsParams](#aspect.config.ApplicationLogsParams)
(message)
* [ApplicationLogsParams.ApplicationLog](#aspect.config.ApplicationLogsParams.ApplicationLog)
(message)
<a name="aspect.config.ApplicationLogsParams"></a>
### ApplicationLogsParams
Configures an individual application-logs aspect.
<table>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
<a name="aspect.config.ApplicationLogsParams.logName"></a>
<tr>
<td><code>logName</code></td>
<td>string</td>
<td>Identifies a collection of related log entries.</td>
</tr>
<a name="aspect.config.ApplicationLogsParams.logs"></a>
<tr>
<td><code>logs[]</code></td>
<td>repeated <a href="#aspect.config.ApplicationLogsParams.ApplicationLog">ApplicationLog</a></td>
<td></td>
</tr>
</table>
<a name="aspect.config.ApplicationLogsParams.ApplicationLog"></a>
### ApplicationLog
<table>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
<a name="aspect.config.ApplicationLogsParams.ApplicationLog.descriptorName"></a>
<tr>
<td><code>descriptorName</code></td>
<td>string</td>
<td>Must match the name of some LogEntryDescriptor.</td>
</tr>
<a name="aspect.config.ApplicationLogsParams.ApplicationLog.severity"></a>
<tr>
<td><code>severity</code></td>
<td>string</td>
<td>The expression to evaluate to determine this log's severity at runtime.</td>
</tr>
<a name="aspect.config.ApplicationLogsParams.ApplicationLog.timestamp"></a>
<tr>
<td><code>timestamp</code></td>
<td>string</td>
<td>The expression to evaluate to determine this log's timestamp.</td>
</tr>
<a name="aspect.config.ApplicationLogsParams.ApplicationLog.timeFormat"></a>
<tr>
<td><code>timeFormat</code></td>
<td>string</td>
<td>The golang time layout format string used to print the timestamp</td>
</tr>
<a name="aspect.config.ApplicationLogsParams.ApplicationLog.templateExpressions"></a>
<tr>
<td><code>templateExpressions</code></td>
<td>repeated map&lt;string, string&gt;</td>
<td>Map of template variable name to expression for the descriptor's logTemplate. At run time each expression will be evaluated, and together they will provide values for the log's template string. Labels and template expressions do not mix: if the result of some expression is needed for both constructing the payload and for dimensioning the log entry, it must be included both in these expressions and in the <code>labels</code> expressions.</td>
</tr>
<a name="aspect.config.ApplicationLogsParams.ApplicationLog.labels"></a>
<tr>
<td><code>labels</code></td>
<td>repeated map&lt;string, string&gt;</td>
<td>Map of LogEntryDescriptor label name to attribute expression. At run time each expression will be evaluated to determine the value that will be used to fill in the log template. The result of evaluating the expression must match the ValueType of the label in the LogEntryDescriptor.</td>
</tr>
</table>

71
_docs/reference/api/mixer/aspects/attrgen.md Normal file
View File

@ -0,0 +1,71 @@
---
title: attrgen Config
overview: Generated documentation for Mixer's Aspect Configuration Schema
order: 1140
layout: docs
type: markdown
---
<a name="rpcAspect.configIndex"></a>
### Index
* [AttributesGeneratorParams](#aspect.config.AttributesGeneratorParams)
(message)
<a name="aspect.config.AttributesGeneratorParams"></a>
### AttributesGeneratorParams
Configures an AttributesGenerator aspect.
The following config specifies two adapters (mixerInfo and k8sPodInfo)
that will be used to generate attributes for use within in Mixer:
aspects:
- kind: attributes
adapter: mixerInfo
params:
attributeBindings:
mixerVersion: version
mixerBuildId: buildID
mixerBuildStatus: buildStatus
- kind: attributes
adapter: k8sPodInfo
params:
inputExpressions:
srcIP: source.ip | "unknown"
tgtIP: target.ip | "unknown"
attributeBindings:
sourceName: srcName
targetName: tgtName
The mixerInfo adapter takes no input arguments and produces three output
values (version, buildID, and buildStatus). Those three output values are
mapped into three attributes (mixerVersion, mixerBuildId, and
mixerBuildStatus) via the attributeBindings.
Similarly, the k8sPodInfo adapter takes two inputs (srcIp and tgtIp). Their
values are generated from the expressions that reference mixer attributes.
The adapter produces two outputs (srcName and tgtName) that are mapped into
mixer attributes (sourceName and targetName) by the attributeBindings.
<table>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
<a name="aspect.config.AttributesGeneratorParams.inputExpressions"></a>
<tr>
<td><code>inputExpressions</code></td>
<td>repeated map&lt;string, string&gt;</td>
<td>Map of input params name to attribute expressions. At runtime, each expression will be evaluated to determine the input value provided to the aspect.</td>
</tr>
<a name="aspect.config.AttributesGeneratorParams.attributeBindings"></a>
<tr>
<td><code>attributeBindings</code></td>
<td>repeated map&lt;string, string&gt;</td>
<td>Map of attribute descriptor names to the names of values produced by an adapter. This map will be used to translate from adapter outputs into mixer attributes.</td>
</tr>
</table>

22
_docs/reference/api/mixer/aspects/denials.md Normal file
View File

@ -0,0 +1,22 @@
---
title: denials Config
overview: Generated documentation for Mixer's Aspect Configuration Schema
order: 1150
layout: docs
type: markdown
---
<a name="rpcAspect.configIndex"></a>
### Index
* [DenialsParams](#aspect.config.DenialsParams)
(message)
<a name="aspect.config.DenialsParams"></a>
### DenialsParams
Configures a denials aspect.
NOTE: _No fields in this message type.__

12
_docs/reference/api/mixer/aspects/index.md Normal file
View File

@ -0,0 +1,12 @@
---
title: Mixer Aspects
overview: Generated documentation for Mixer's aspects.
order: 2000
layout: docs
type: markdown
---
{% include section-index.html %}

46
_docs/reference/api/mixer/aspects/lists.md Normal file
View File

@ -0,0 +1,46 @@
---
title: lists Config
overview: Generated documentation for Mixer's Aspect Configuration Schema
order: 1160
layout: docs
type: markdown
---
<a name="rpcAspect.configIndex"></a>
### Index
* [ListsParams](#aspect.config.ListsParams)
(message)
<a name="aspect.config.ListsParams"></a>
### ListsParams
Configures a lists aspect.
Example:
kind: lists
params:
blacklist: true
checkExpression: source.ip
<table>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
<a name="aspect.config.ListsParams.blacklist"></a>
<tr>
<td><code>blacklist</code></td>
<td>bool</td>
<td>blacklist determines if this behaves like a blacklist default is whitelist</td>
</tr>
<a name="aspect.config.ListsParams.checkExpression"></a>
<tr>
<td><code>checkExpression</code></td>
<td>string</td>
<td>checkExpression is the expression evaluated at runtime to derive the value that is checked against the list</td>
</tr>
</table>

94
_docs/reference/api/mixer/aspects/metrics.md Normal file
View File

@ -0,0 +1,94 @@
---
title: metrics Config
overview: Generated documentation for Mixer's Aspect Configuration Schema
order: 1170
layout: docs
type: markdown
---
<a name="rpcAspect.configIndex"></a>
### Index
* [MetricsParams](#aspect.config.MetricsParams)
(message)
* [MetricsParams.Metric](#aspect.config.MetricsParams.Metric)
(message)
<a name="aspect.config.MetricsParams"></a>
### MetricsParams
Configures a metric aspect.
<table>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
<a name="aspect.config.MetricsParams.metrics"></a>
<tr>
<td><code>metrics[]</code></td>
<td>repeated <a href="#aspect.config.MetricsParams.Metric">Metric</a></td>
<td>The set of metrics that will be populated and handed to aspects at run time.</td>
</tr>
</table>
<a name="aspect.config.MetricsParams.Metric"></a>
### Metric
Describes how attributes must be evaluated to produce values for the named metric. Suppose the following
MetricDescriptor exists in the global configuration:
```yaml
metricDescriptor:
name: "responseCode"
kind: COUNTER
value: I64
labels:
name: apiMethod
valueType: STRING
labels:
name: responseCode
valueType: I64
```
To actually report metrics at run time a mapping from attributes to a metric's labels must be provided in
the form of a metric:
```yaml
metric:
descriptorName: "responseCode" # must match metricDescriptor.name
value: $requestCount # Istio expression syntax for the attribute named "requestCount"
labels:
# either the attribute named 'apiMethod' or the literal string 'unknown'; must eval to a string
apiMethod: $apiMethod | "unknown"
# either the attribute named 'responseCode' or the literal int64 500; must eval to an int64
responseCode: $responseCode | 500
```
<table>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
<a name="aspect.config.MetricsParams.Metric.descriptorName"></a>
<tr>
<td><code>descriptorName</code></td>
<td>string</td>
<td>Must match the name of some metricDescriptor in the global config.</td>
</tr>
<a name="aspect.config.MetricsParams.Metric.value"></a>
<tr>
<td><code>value</code></td>
<td>string</td>
<td>Attribute expression to evaluate to determine the value for this metric; the result of the evaluation must match the value ValueType of the metricDescriptor.</td>
</tr>
<a name="aspect.config.MetricsParams.Metric.labels"></a>
<tr>
<td><code>labels</code></td>
<td>repeated map&lt;string, string&gt;</td>
<td>Map of metricDescriptor label name to attribute expression. At run time each expression will be evaluated to determine the value provided to the aspect. The result of evaluating the expression must match the ValueType of the label in the metricDescriptor.</td>
</tr>
</table>

71
_docs/reference/api/mixer/aspects/quotas.md Normal file
View File

@ -0,0 +1,71 @@
---
title: quotas Config
overview: Generated documentation for Mixer's Aspect Configuration Schema
order: 1180
layout: docs
type: markdown
---
<a name="rpcAspect.configIndex"></a>
### Index
* [QuotasParams](#aspect.config.QuotasParams)
(message)
* [QuotasParams.Quota](#aspect.config.QuotasParams.Quota)
(message)
<a name="aspect.config.QuotasParams"></a>
### QuotasParams
Configures a quotas aspect.
<table>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
<a name="aspect.config.QuotasParams.quotas"></a>
<tr>
<td><code>quotas[]</code></td>
<td>repeated <a href="#aspect.config.QuotasParams.Quota">Quota</a></td>
<td>The set of quotas that will be populated and handed to aspects at run time.</td>
</tr>
</table>
<a name="aspect.config.QuotasParams.Quota"></a>
### Quota
<table>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
<a name="aspect.config.QuotasParams.Quota.descriptorName"></a>
<tr>
<td><code>descriptorName</code></td>
<td>string</td>
<td>Must match the name of some quotaDescriptor in the global config.</td>
</tr>
<a name="aspect.config.QuotasParams.Quota.labels"></a>
<tr>
<td><code>labels</code></td>
<td>repeated map&lt;string, string&gt;</td>
<td>Map of quotaDescriptor label name to attribute expression. At run time each expression will be evaluated to determine the value provided to the aspect. The result of evaluating the expression must match the ValueType of the label in the quotaDescriptor.</td>
</tr>
<a name="aspect.config.QuotasParams.Quota.maxAmount"></a>
<tr>
<td><code>maxAmount</code></td>
<td>int64</td>
<td>The upper limit for this quota.</td>
</tr>
<a name="aspect.config.QuotasParams.Quota.expiration"></a>
<tr>
<td><code>expiration</code></td>
<td><a href="https://developers.google.com/protocol-buffers/docs/reference/google.protobuf#duration">Duration</a></td>
<td>The amount of time allocated quota remains valid before it is automatically released. This is only meaningful for quotas annotated as rate limits, otherwise the value must be zero.</td>
</tr>
</table>

518
_docs/reference/api/mixer/mixer-config.md
View File

@ -1,17 +1,15 @@
---
title: Configuration Schema
overview: Generated documentation for Mixer's configuration schema
title: Mixer
overview: Generated documentation for Mixer's Configuration Schema
order: 40
order: 1190
layout: docs
type: markdown
---
<a name="rpc_istio.mixer.v1_config"></a>
## Package istio.mixer.v1.config
<a name="rpc_istio.mixer.v1_config_index"></a>
<a name="rpcIstio.mixer.v1.configIndex"></a>
### Index
* [Adapter](#istio.mixer.v1.config.Adapter)
@ -22,29 +20,40 @@ type: markdown
(message)
* [AttributeManifest](#istio.mixer.v1.config.AttributeManifest)
(message)
* [AttributeManifest.AttributeInfo](#istio.mixer.v1.config.AttributeManifest.AttributeInfo)
(message)
* [DnsName](#istio.mixer.v1.config.DnsName)
(message)
* [EmailAddress](#istio.mixer.v1.config.EmailAddress)
(message)
* [GlobalConfig](#istio.mixer.v1.config.GlobalConfig)
(message)
<b>(deprecated)</b>
* [IpAddress](#istio.mixer.v1.config.IpAddress)
(message)
* [ServiceConfig](#istio.mixer.v1.config.ServiceConfig)
(message)
<b>(deprecated)</b>
* [Uri](#istio.mixer.v1.config.Uri)
(message)
<a name="istio.mixer.v1.config.Adapter"></a>
### Adapter
Adapter config defines specifics of adapter implementations
We define an adapter that provides "metrics" aspect
kind: istio/metrics
name: metrics-statsd
impl: “istio.io/adapters/statsd”
Adapter allows the operator to configure a specific adapter implementation.
Each adapter implementation defines its own `params` proto. Note that unlike
[Aspect](#istio.mixer.v1.config.Aspect), the type of `params` varies with `impl`
and not with `kind`.
In the following example we define a `metrics` adapter using the Mixer's prepackaged
prometheus adapter. This adapter doesn't require any parameters.
```yaml
kind: metrics
name: prometheus-adapter
impl: prometheus
params:
Host: statd.svc.cluster
Port: 8125
```
<table>
<tr>
@ -56,49 +65,52 @@ params:
<tr>
<td><code>name</code></td>
<td>string</td>
<td>statsd-slow</td>
<td>Required, must be unique per <code>kind</code>. Used by <a href="#istio.mixer.v1.config.Aspect">Aspect</a> to refer to this adapter. The name "default" is special: when an Aspect does not specify a name, the Adapter named "default" of the same <code>kind</code> is used to execute the intention described by the <a href="#istio.mixer.v1.config.AspectRule">AspectRule</a>s.</td>
</tr>
<a name="istio.mixer.v1.config.Adapter.kind"></a>
<tr>
<td><code>kind</code></td>
<td>string</td>
<td>metrics</td>
<td>Required. The aspect this implementation with these params will implement; a single adapter implementation may implement many aspects, but an <code>Adapter</code> entry is required per kind.</td>
</tr>
<a name="istio.mixer.v1.config.Adapter.impl"></a>
<tr>
<td><code>impl</code></td>
<td>string</td>
<td>istio.statsd</td>
<td>Required. The name of a specific adapter implementation. An adapter's implementation name is typically a constant in its code.</td>
</tr>
<a name="istio.mixer.v1.config.Adapter.params"></a>
<tr>
<td><code>params</code></td>
<td><a href="https://developers.google.com/protocol-buffers/docs/reference/google.protobuf#struct">Struct</a></td>
<td>Struct representation of a proto defined by the implementation based on impl {}</td>
<td>Optional, depends on adapter implementation. Struct representation of a proto defined by the implementation; this varies depending on <code>impl</code>.</td>
</tr>
</table>
<a name="istio.mixer.v1.config.Aspect"></a>
### Aspect
Aspect is intent based. It specifies the intent "kind"
following example specifies that the user would like to collect
response_time with 3 labels (src_consumer_id, target_response_status_code,
target_service_name)
Aspect describes how an adapter is intended to operate in the context of the
rule it's embedded in. The value for `params` depends on the `kind` of this
aspect: each kind of aspect defines its own `params` proto.
The Input section tells if target_service_name is not available it can be
computed using the given expression
The following example instructs Mixer to populate a metric named "responseTime"
that was declared to have three labels: srcConsumerId, targetResponseStatusCode,
and targetServiceName. For each label and the metric's `value` we provide
an expression over Istio's attributes. Mixer evaluates these expressions for
each request.
kind: istio/metrics
params:
metrics:
- name: response_time # What to call this metric outbound.
value: metric_response_time # from wellknown vocabulary
metric_kind: DELTA
labels:
- key: src_consumer_id
- key: target_response_status_code
- key: target_service_name
```yaml
kind: metrics
params:
metrics:
- descriptorName: responseTime # tie this metric to a descriptor of the same name
value: response.time # from the set of canonical attributes
labels:
srcConsumerId: source.user | source.uid
targetResponseStatusCode: response.code
targetServiceName: target.service
```
<table>
<tr>
@ -110,25 +122,27 @@ computed using the given expression
<tr>
<td><code>kind</code></td>
<td>string</td>
<td></td>
<td>Required. The kind of aspect this intent is targeting.</td>
</tr>
<a name="istio.mixer.v1.config.Aspect.adapter"></a>
<tr>
<td><code>adapter</code></td>
<td>string</td>
<td>optional, allows specifying an adapter</td>
<td>Optional. The name of the adapter this Aspect targets. If no name is provided, Mixer will use the adapter of the target kind named "default".</td>
</tr>
<a name="istio.mixer.v1.config.Aspect.params"></a>
<tr>
<td><code>params</code></td>
<td><a href="https://developers.google.com/protocol-buffers/docs/reference/google.protobuf#struct">Struct</a></td>
<td>Struct representation of a proto defined by the aspect</td>
<td>Required. Struct representation of a proto defined by each aspect kind.</td>
</tr>
</table>
<a name="istio.mixer.v1.config.AspectRule"></a>
### AspectRule
AspectRules are intent based
An AspectRule is a selector and a set of intentions to be executed when the
selector is `true`. The selectors of the this rule's child AspectRules are only
evaluated if this rule's selector is true.
<table>
<tr>
@ -140,25 +154,32 @@ AspectRules are intent based
<tr>
<td><code>selector</code></td>
<td>string</td>
<td>selector is an attributes based predicate. attr1 == "20" &amp;&amp; attr2 == "30"</td>
<td><p>Required. Selector is an attribute based predicate. When Mixer receives a request it evaluates all selectors in scope and executes the rules for all selectors that evaluated to true.</p><p>A few example selectors:</p>
<ul>
<li>an empty selector evaluates to <code>true</code></li>
<li><code>true</code>, a boolean literal; a rule with this selector will always be executed</li>
<li><code>target.service == ratings*</code> selects any request targeting a service whose name starts with "ratings"</li>
<li><code>attr1 == &quot;20&quot; &amp;&amp; attr2 == &quot;30&quot;</code> logical AND, OR, and NOT are also available</li>
</ul></td>
</tr>
<a name="istio.mixer.v1.config.AspectRule.aspects"></a>
<tr>
<td><code>aspects[]</code></td>
<td>repeated <a href="#istio.mixer.v1.config.Aspect">Aspect</a></td>
<td>The following aspects apply when the selector predicate evaluates to True</td>
<td>The aspects that apply when selector evaluates to <code>true</code>.</td>
</tr>
<a name="istio.mixer.v1.config.AspectRule.rules"></a>
<tr>
<td><code>rules[]</code></td>
<td>repeated <a href="#istio.mixer.v1.config.AspectRule">AspectRule</a></td>
<td>Nested aspect Rule is evaluated if selector predicate evaluates to True</td>
<td>Nested aspect rules; their selectors are evaluated if this selector predicate evaluates to <code>true</code>.</td>
</tr>
</table>
<a name="istio.mixer.v1.config.AttributeManifest"></a>
### AttributeManifest
AttributeManifest describes a set of Attributes produced by some component of an Istio deployment.
AttributeManifest describes a set of Attributes produced by some component
of an Istio deployment.
<table>
<tr>
@ -170,19 +191,91 @@ AttributeManifest describes a set of Attributes produced by some component of an
<tr>
<td><code>revision</code></td>
<td>string</td>
<td></td>
<td>Optional. The revision of this document. Assigned by server.</td>
</tr>
<a name="istio.mixer.v1.config.AttributeManifest.name"></a>
<tr>
<td><code>name</code></td>
<td>string</td>
<td>Name of the component producing these attributes. This can be the proxy (with the canonical name "istio-proxy") or the name of an attribute producing adapter in the mixer itself.</td>
<td>Required. Name of the component producing these attributes. This can be the proxy (with the canonical name "istio-proxy") or the name of an <code>attributes</code> kind adapter in Mixer.</td>
</tr>
<a name="istio.mixer.v1.config.AttributeManifest.attributes"></a>
<tr>
<td><code>attributes[]</code></td>
<td>repeated <a href="#istio.mixer.v1.config.descriptor.AttributeDescriptor">AttributeDescriptor</a></td>
<td>The set of attributes this Istio component will be responsible for producing at runtime.</td>
<td><code>attributes</code></td>
<td>repeated map&lt;string, <a href="#istio.mixer.v1.config.AttributeManifest.AttributeInfo">AttributeInfo</a>&gt;</td>
<td><p>The set of attributes this Istio component will be responsible for producing at runtime. We map from attribute name to the attribute's specification. The name of an attribute, which is how attributes are referred to in aspect configuration, must conform to:</p>
<pre><code>Name = IDENT { SEPARATOR IDENT };
</code></pre><p>Where <code>IDENT</code> must match the regular expression <code>a-z+</code> and <code>SEPARATOR</code> must match the regular expression <code>[\.-]</code>.</p><p>Attribute names must be unique within a single Istio deployment. The set of canonical attributes are described at <a href="https://istio.io/docs/reference/attribute-vocabulary.html">https://istio.io/docs/reference/attribute-vocabulary.html</a>. Attributes not in that list should be named with a component-specific suffix such as request.count-my.component</p></td>
</tr>
</table>
<a name="istio.mixer.v1.config.AttributeManifest.AttributeInfo"></a>
### AttributeInfo
AttributeInfo describes the schema of an Istio `Attribute`.
<a name="rpcIstio.mixer.v1.configIstio.mixer.v1.config.AttributeManifest.AttributeInfoDescriptionSubsectionSubsection"></a>
#### Istio Attributes
Istio uses `attributes` to describe runtime activities of Istio services.
An Istio attribute carries a specific piece of information about an activity,
such as the error code of an API request, the latency of an API request, or the
original IP address of a TCP connection. The attributes are often generated
and consumed by different services. For example, a frontend service can
generate an authenticated user attribute and pass it to a backend service for
access control purpose.
To simplify the system and improve developer experience, Istio uses
shared attribute definitions across all components. For example, the same
authenticated user attribute will be used for logging, monitoring, analytics,
billing, access control, auditing. Many Istio components provide their
functionality by collecting, generating, and operating on attributes.
For example, the proxy collects the error code attribute, and the logging
stores it into a log.
<a name="rpcIstio.mixer.v1.configIstio.mixer.v1.config.AttributeManifest.AttributeInfoDescriptionSubsectionSubsection_1"></a>
#### Design
Each Istio attribute must conform to an `AttributeInfo` in an
`AttributeManifest` in the current Istio deployment at runtime. An
`AttributeInfo` is used to define an attribute's
metadata: the type of its value and a detailed description that explains
the semantics of the attribute type. Each attribute's name is globally unique;
in other words an attribute name can only appear once across all manifests.
The runtime presentation of an attribute is intentionally left out of this
specification, because passing attribute using JSON, XML, or Protocol Buffers
does not change the semantics of the attribute. Different implementations
can choose different representations based on their needs.
<a name="rpcIstio.mixer.v1.configIstio.mixer.v1.config.AttributeManifest.AttributeInfoDescriptionSubsectionSubsection_2"></a>
#### HTTP Mapping
Because many systems already have REST APIs, it makes sense to define a
standard HTTP mapping for Istio attributes that are compatible with typical
REST APIs. The design is to map one attribute to one HTTP header, the
attribute name and value becomes the HTTP header name and value. The actual
encoding scheme will be decided later.
<table>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
<a name="istio.mixer.v1.config.AttributeManifest.AttributeInfo.description"></a>
<tr>
<td><code>description</code></td>
<td>string</td>
<td>Optional. A human-readable description of the attribute's purpose.</td>
</tr>
<a name="istio.mixer.v1.config.AttributeManifest.AttributeInfo.valueType"></a>
<tr>
<td><code>valueType</code></td>
<td><a href="#istio.mixer.v1.config.descriptor.ValueType">ValueType</a></td>
<td>Required. The type of data carried by this attribute.</td>
</tr>
</table>
@ -224,9 +317,13 @@ EmailAddress holds a properly formatted email address.
<a name="istio.mixer.v1.config.GlobalConfig"></a>
### GlobalConfig
GlobalConfig defines configuration elements that are available
for the rest of the config
It is used to configure adapters and make them available in AspectRules
WARNING: GlobalConfig is deprecated, see the Config API's
swagger spec.
GlobalConfig defines configuration elements that are available for the rest
of the config. It is used to configure adapters and make them available in
AspectRules.
<table>
<tr>
@ -238,7 +335,7 @@ It is used to configure adapters and make them available in AspectRules
<tr>
<td><code>revision</code></td>
<td>string</td>
<td></td>
<td>Optional.</td>
</tr>
<a name="istio.mixer.v1.config.GlobalConfig.adapters"></a>
<tr>
@ -264,9 +361,9 @@ It is used to configure adapters and make them available in AspectRules
<td>repeated <a href="#istio.mixer.v1.config.descriptor.MetricDescriptor">MetricDescriptor</a></td>
<td></td>
</tr>
<a name="istio.mixer.v1.config.GlobalConfig.monitored_resources"></a>
<a name="istio.mixer.v1.config.GlobalConfig.monitoredResources"></a>
<tr>
<td><code>monitored_resources[]</code></td>
<td><code>monitoredResources[]</code></td>
<td>repeated <a href="#istio.mixer.v1.config.descriptor.MonitoredResourceDescriptor">MonitoredResourceDescriptor</a></td>
<td></td>
</tr>
@ -304,36 +401,29 @@ IpAddress holds an IPv4 or IPv6 address.
<a name="istio.mixer.v1.config.ServiceConfig"></a>
### ServiceConfig
Configures a set of services
following example configures metrics collection and ratelimit for
all services
WARNING: ServiceConfig is deprecated, see the Config API's
swagger spec.
Configures a set of services.
The following example configures a metric that will be recorded for all services:
<a name="rpc_istio.mixer.v1_config_istio.mixer.v1.config.ServiceConfig_description_subsection"></a>
#### service config
```yaml
subject: "namespace:ns1"
revision: "1011"
rules:
- selector: target_name == "*"
aspects:
- kind: metrics
params:
metrics: # defines metric collection across the board.
- name: response_time_by_status_code
value: metric.response_time # certain attributes are metrics
metric_kind: DELTA
labels:
- key: response.status_code
- kind: ratelimiter
params:
limits: # imposes 2 limits, 100/s per source and destination
- limit: "100/s"
labels:
- key: src.service_id
- key: target.service_id
- limit: "1000/s" # every destination service gets 1000/s
labels:
- key: target.service_id
- selector: target.service == "*"
aspects:
- kind: metrics
params:
metrics: # defines metric collection across the board.
- descriptorName: responseTimeByStatusCode
value: response.time
labels:
statusCode: response.code
```
<table>
<tr>
@ -345,13 +435,13 @@ rules:
<tr>
<td><code>subject</code></td>
<td>string</td>
<td>subject is unique for a config type 2 config with the same subject will overwrite each other</td>
<td>Optional. Subject is unique for a config type. 2 config with the same subject will overwrite each other</td>
</tr>
<a name="istio.mixer.v1.config.ServiceConfig.revision"></a>
<tr>
<td><code>revision</code></td>
<td>string</td>
<td>revision of this config. This is assigned by the server</td>
<td>Optional. revision of this config. This is assigned by the server</td>
</tr>
<a name="istio.mixer.v1.config.ServiceConfig.rules"></a>
<tr>
@ -379,14 +469,12 @@ Uri represents a properly formed URI.
</tr>
</table>
<a name="rpc_istio.mixer.v1_config_descriptor"></a>
<a name="rpcIstio.mixer.v1.configDescriptor"></a>
## Package istio.mixer.v1.config.descriptor
<a name="rpc_istio.mixer.v1_config_descriptor_index"></a>
<a name="rpcIstio.mixer.v1.configDescriptorIndex"></a>
### Index
* [AttributeDescriptor](#istio.mixer.v1.config.descriptor.AttributeDescriptor)
(message)
* [LogEntryDescriptor](#istio.mixer.v1.config.descriptor.LogEntryDescriptor)
(message)
* [LogEntryDescriptor.PayloadFormat](#istio.mixer.v1.config.descriptor.LogEntryDescriptor.PayloadFormat)
@ -412,82 +500,6 @@ Uri represents a properly formed URI.
* [ValueType](#istio.mixer.v1.config.descriptor.ValueType)
(enum)
<a name="istio.mixer.v1.config.descriptor.AttributeDescriptor"></a>
### AttributeDescriptor
An `AttributeDescriptor` describes the schema of an Istio attribute type.
<a name="rpc_istio.mixer.v1_config_descriptor_istio.mixer.v1.config.descriptor.AttributeDescriptor_description_subsection_subsection"></a>
#### Istio Attributes
Istio uses `attributes` to describe runtime activities of Istio services.
An Istio attribute carries a specific piece of information about an activity,
such as the error code of an API request, the latency of an API request, the
original IP address of a TCP connection. The attributes are often generated
and consumed by different services. For example, a frontend service can
generate an authenticated user attribute and pass it to a backend service for
access control purpose.
To simplify the system and improve developer experience, Istio uses
shared attribute definitions across all components. For example, the same
authenticated user attribute will be used for logging, monitoring, analytics,
billing, access control, auditing. Many Istio components provide their
functionality by collecting, generating, and operating on attributes.
For example, the proxy collects the error code attribute, and the logging
stores it into a log.
<a name="rpc_istio.mixer.v1_config_descriptor_istio.mixer.v1.config.descriptor.AttributeDescriptor_description_subsection_subsection_1"></a>
#### Design
Each Istio attribute must conform to an Istio attribute type. The
`AttributeDescriptor` is used to define attribute types. Each type has a
globally unique type name, the type of the value, and a detailed description
that explains the semantics of the attribute type.
The runtime presentation of an attribute is intentionally left out of this
specification, because passing attribute using JSON, XML, or Protocol Buffers
does not change the semantics of the attribute. Different implementations
can choose different representations based on their needs.
<a name="rpc_istio.mixer.v1_config_descriptor_istio.mixer.v1.config.descriptor.AttributeDescriptor_description_subsection_subsection_2"></a>
#### HTTP Mapping
Because many systems already have REST APIs, it makes sense to define a
standard HTTP mapping for Istio attributes that are compatible with typical
REST APIs. The design is to map one attribute to one HTTP header, the
attribute name and value becomes the HTTP header name and value. The actual
encoding scheme will be decided later.
<table>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
<a name="istio.mixer.v1.config.descriptor.AttributeDescriptor.name"></a>
<tr>
<td><code>name</code></td>
<td>string</td>
<td><p>The name of this descriptor, referenced from individual attribute instances and other descriptors.</p><p>The format of this name is:</p>
<pre><code>Name = IDENT { &quot;.&quot; IDENT } ;
</code></pre><p>Where <code>IDENT</code> must match the regular expression <code>a-z+</code>.</p><p>Attribute descriptor names must be unique within a single Istio deployment. There is a well- known set of attributes which have succinct names. Attributes not on this list should be named with a component-specific suffix such as request.count-my.component</p></td>
</tr>
<a name="istio.mixer.v1.config.descriptor.AttributeDescriptor.description"></a>
<tr>
<td><code>description</code></td>
<td>string</td>
<td>An optional human-readable description of the attribute's purpose.</td>
</tr>
<a name="istio.mixer.v1.config.descriptor.AttributeDescriptor.value_type"></a>
<tr>
<td><code>value_type</code></td>
<td><a href="#istio.mixer.v1.config.descriptor.ValueType">ValueType</a></td>
<td>The type of data carried by attributes</td>
</tr>
</table>
<a name="istio.mixer.v1.config.descriptor.LogEntryDescriptor"></a>
### LogEntryDescriptor
Defines the format of a single log entry.
@ -502,31 +514,31 @@ Defines the format of a single log entry.
<tr>
<td><code>name</code></td>
<td>string</td>
<td>The name of this descriptor.</td>
<td>Required. The name of this descriptor.</td>
</tr>
<a name="istio.mixer.v1.config.descriptor.LogEntryDescriptor.display_name"></a>
<a name="istio.mixer.v1.config.descriptor.LogEntryDescriptor.displayName"></a>
<tr>
<td><code>display_name</code></td>
<td><code>displayName</code></td>
<td>string</td>
<td>An optional concise name for the log entry type, which can be displayed in user interfaces. Use sentence case without an ending period, for example "Request count".</td>
<td>Optional. A concise name for the log entry type, which can be displayed in user interfaces. Use sentence case without an ending period, for example "Request count".</td>
</tr>
<a name="istio.mixer.v1.config.descriptor.LogEntryDescriptor.description"></a>
<tr>
<td><code>description</code></td>
<td>string</td>
<td>An optional description of the log entry type, which can be used in documentation.</td>
<td>Optional. A description of the log entry type, which can be used in documentation.</td>
</tr>
<a name="istio.mixer.v1.config.descriptor.LogEntryDescriptor.payload_format"></a>
<a name="istio.mixer.v1.config.descriptor.LogEntryDescriptor.payloadFormat"></a>
<tr>
<td><code>payload_format</code></td>
<td><code>payloadFormat</code></td>
<td><a href="#istio.mixer.v1.config.descriptor.LogEntryDescriptor.PayloadFormat">PayloadFormat</a></td>
<td>Format of the value of the payload attribute.</td>
<td>Required. Format of the value of the payload attribute.</td>
</tr>
<a name="istio.mixer.v1.config.descriptor.LogEntryDescriptor.log_template"></a>
<a name="istio.mixer.v1.config.descriptor.LogEntryDescriptor.logTemplate"></a>
<tr>
<td><code>log_template</code></td>
<td><code>logTemplate</code></td>
<td>string</td>
<td><p>The template that will be populated with labels at runtime to generate a log message; the labels describe the parameters for this template.</p><p>The template strings must conform to go's text/template syntax.</p></td>
<td><p>Required. The template that will be populated with labels at runtime to generate a log message; the labels describe the parameters for this template.</p><p>The template strings must conform to go's text/template syntax.</p></td>
</tr>
<a name="istio.mixer.v1.config.descriptor.LogEntryDescriptor.labels"></a>
<tr>
@ -547,9 +559,9 @@ TEXT is the default payload format.
<th>Value</th>
<th>Description</th>
</tr>
<a name="istio.mixer.v1.config.descriptor.LogEntryDescriptor.PayloadFormat.PAYLOAD_FORMAT_UNSPECIFIED"></a>
<a name="istio.mixer.v1.config.descriptor.LogEntryDescriptor.PayloadFormat.PAYLOADFORMATUNSPECIFIED"></a>
<tr>
<td>PAYLOAD_FORMAT_UNSPECIFIED</td>
<td>PAYLOADFORMATUNSPECIFIED</td>
<td>Invalid, default value.</td>
</tr>
<a name="istio.mixer.v1.config.descriptor.LogEntryDescriptor.PayloadFormat.TEXT"></a>
@ -568,34 +580,41 @@ TEXT is the default payload format.
### MetricDescriptor
Defines a metric type and its schema.
A metric is dimensioned by a set of labels whose values are derived at runtime from attributes.
A given metric holds a unique value for potentially any combination of these dimensions.
A metric is dimensioned by a set of labels whose values are derived at runtime
from attributes. A given metric holds a unique value for potentially any
combination of these dimensions.
The following is an example descriptor for a metric capturing the number of RPCs served, dimensioned
by the method being called and response code returned by the server:
The following is an example descriptor for a metric capturing the number of
RPCs served, dimensioned by the method being called and response code returned
by the server:
metric_descriptor:
name: "response_code"
kind: COUNTER
value: I64
labels:
name: api_method
value_type: STRING
labels:
name: response_code
value_type: INT64
To actually report metrics at run time a mapping from attributes to a metric's labels must be provided.
This is provided in the aspect config; using our above descriptor we might describe the metric as:
```yaml
metrics:
name: "responseCode"
kind: COUNTER
value: INT64
labels:
apiMethod: STRING
responseCode: INT64
```
metric:
descriptor: "response_code" # must match metric_descriptor.name
value: $requestCount # Istio expression syntax for the attribute named "request_count"
labels:
# either the attribute named 'apiMethod' or the literal string 'unknown'; must eval to a string
api_method: $apiMethod | "unknown"
# either the attribute named 'responseCode' or the literal int64 500; must eval to an int64
response_code: $responseCode | 500
To actually report metrics at run time a mapping from attributes to a metric's
labels must be provided. This is provided in the aspect config; using our above
descriptor we might describe the metric as:
```yaml
metric:
descriptor: "responseCode" # must match metricDescriptor.name
value: request.count # expression syntax for the attribute named "request.count"
labels:
# either the attribute named 'api.method' or the literal string 'unknown'; must eval to a string
apiMethod: api.method | "unknown"
# either the attribute named 'response.code' or the literal int64 500; must eval to an int64
responseCode: response.code | 500
```
<table>
<tr>
@ -607,31 +626,31 @@ This is provided in the aspect config; using our above descriptor we might descr
<tr>
<td><code>name</code></td>
<td>string</td>
<td>The name of this descriptor. This is used to refer to this descriptor in other contexts.</td>
<td>Required. The name of this descriptor. This is used to refer to this descriptor in other contexts.</td>
</tr>
<a name="istio.mixer.v1.config.descriptor.MetricDescriptor.display_name"></a>
<a name="istio.mixer.v1.config.descriptor.MetricDescriptor.displayName"></a>
<tr>
<td><code>display_name</code></td>
<td><code>displayName</code></td>
<td>string</td>
<td>An optional concise name for the metric, which can be displayed in user interfaces. Use sentence case without an ending period, for example "Request count".</td>
<td>Optional. A concise name for the metric, which can be displayed in user interfaces. Use sentence case without an ending period, for example "Request count".</td>
</tr>
<a name="istio.mixer.v1.config.descriptor.MetricDescriptor.description"></a>
<tr>
<td><code>description</code></td>
<td>string</td>
<td>An optional description of the metric, which should be used as the documentation for the metric.</td>
<td>Optional. A description of the metric, which should be used as the documentation for the metric.</td>
</tr>
<a name="istio.mixer.v1.config.descriptor.MetricDescriptor.kind"></a>
<tr>
<td><code>kind</code></td>
<td><a href="#istio.mixer.v1.config.descriptor.MetricDescriptor.MetricKind">MetricKind</a></td>
<td>Whether the metric records instantaneous values, changes to a value, etc.</td>
<td>Required. Whether the metric records instantaneous values, changes to a value, etc.</td>
</tr>
<a name="istio.mixer.v1.config.descriptor.MetricDescriptor.value"></a>
<tr>
<td><code>value</code></td>
<td><a href="#istio.mixer.v1.config.descriptor.ValueType">ValueType</a></td>
<td>The type of data this metric records.</td>
<td>Required. The type of data this metric records.</td>
</tr>
<a name="istio.mixer.v1.config.descriptor.MetricDescriptor.labels"></a>
<tr>
@ -656,21 +675,21 @@ This is provided in the aspect config; using our above descriptor we might descr
<th>Type</th>
<th>Description</th>
</tr>
<a name="istio.mixer.v1.config.descriptor.MetricDescriptor.BucketsDefinition.linear_buckets"></a>
<a name="istio.mixer.v1.config.descriptor.MetricDescriptor.BucketsDefinition.linearBuckets"></a>
<tr>
<td><code>linear_buckets</code></td>
<td><code>linearBuckets</code></td>
<td><a href="#istio.mixer.v1.config.descriptor.MetricDescriptor.BucketsDefinition.Linear">Linear</a> (oneof )</td>
<td>The linear buckets.</td>
</tr>
<a name="istio.mixer.v1.config.descriptor.MetricDescriptor.BucketsDefinition.exponential_buckets"></a>
<a name="istio.mixer.v1.config.descriptor.MetricDescriptor.BucketsDefinition.exponentialBuckets"></a>
<tr>
<td><code>exponential_buckets</code></td>
<td><code>exponentialBuckets</code></td>
<td><a href="#istio.mixer.v1.config.descriptor.MetricDescriptor.BucketsDefinition.Exponential">Exponential</a> (oneof )</td>
<td>The exponential buckets.</td>
</tr>
<a name="istio.mixer.v1.config.descriptor.MetricDescriptor.BucketsDefinition.explicit_buckets"></a>
<a name="istio.mixer.v1.config.descriptor.MetricDescriptor.BucketsDefinition.explicitBuckets"></a>
<tr>
<td><code>explicit_buckets</code></td>
<td><code>explicitBuckets</code></td>
<td><a href="#istio.mixer.v1.config.descriptor.MetricDescriptor.BucketsDefinition.Explicit">Explicit</a> (oneof )</td>
<td>The explicit buckets.</td>
</tr>
@ -680,11 +699,11 @@ This is provided in the aspect config; using our above descriptor we might descr
### Explicit
Specifies a set of buckets with arbitrary widths.
There are `size(bounds) + 1` (= N) buckets. Bucket `i` has the following
There are `size(bounds) + 1` (= `N`) buckets. Bucket `i` has the following
boundaries:
Upper bound (0 <= i < N-1): bounds[i]
Lower bound (1 <= i < N); bounds[i - 1]
* Upper bound (`0 <= i < N-1`): `bounds[i]`
* Lower bound (`1 <= i < N`): `bounds[i - 1]`
The `bounds` field must contain at least one element. If `bounds` has
only one element, then there are no finite buckets, and that single
@ -710,13 +729,13 @@ Specifies an exponential sequence of buckets that have a width that is
proportional to the value of the lower bound. Each bucket represents a
constant relative uncertainty on a specific value in the bucket.
There are `num_finite_buckets + 2` (= N) buckets. The two additional
There are `numFiniteBuckets + 2` (= `N`) buckets. The two additional
buckets are the underflow and overflow buckets.
Bucket `i` has the following boundaries:
Upper bound (0 <= i < N-1): scale * (growth_factor ^ i).
Lower bound (1 <= i < N): scale * (growth_factor ^ (i - 1)).
* Upper bound (0 <= i < N-1): `scale * (growthFactor ^ i)`
* Lower bound (1 <= i < N): `scale * (growthFactor ^ (i - 1))`
<table>
<tr>
@ -724,15 +743,15 @@ Bucket `i` has the following boundaries:
<th>Type</th>
<th>Description</th>
</tr>
<a name="istio.mixer.v1.config.descriptor.MetricDescriptor.BucketsDefinition.Exponential.num_finite_buckets"></a>
<a name="istio.mixer.v1.config.descriptor.MetricDescriptor.BucketsDefinition.Exponential.numFiniteBuckets"></a>
<tr>
<td><code>num_finite_buckets</code></td>
<td><code>numFiniteBuckets</code></td>
<td>int32</td>
<td>Must be greater than 0.</td>
</tr>
<a name="istio.mixer.v1.config.descriptor.MetricDescriptor.BucketsDefinition.Exponential.growth_factor"></a>
<a name="istio.mixer.v1.config.descriptor.MetricDescriptor.BucketsDefinition.Exponential.growthFactor"></a>
<tr>
<td><code>growth_factor</code></td>
<td><code>growthFactor</code></td>
<td>double</td>
<td>Must be greater than 1.</td>
</tr>
@ -750,13 +769,13 @@ Specifies a linear sequence of buckets that all have the same width
(except overflow and underflow). Each bucket represents a constant
absolute uncertainty on the specific value in the bucket.
There are `num_finite_buckets + 2` (= N) buckets. The two additional
There are `numFiniteBuckets + 2` (= `N`) buckets. The two additional
buckets are the underflow and overflow buckets.
Bucket `i` has the following boundaries:
Upper bound (0 <= i < N-1): offset + (width * i).
Lower bound (1 <= i < N): offset + (width * (i - 1)).
* Upper bound (`0 <= i < N-1`): `offset + (width * i)`
* Lower bound (`1 <= i < N`): `offset + (width * (i - 1))`
<table>
<tr>
@ -764,9 +783,9 @@ Bucket `i` has the following boundaries:
<th>Type</th>
<th>Description</th>
</tr>
<a name="istio.mixer.v1.config.descriptor.MetricDescriptor.BucketsDefinition.Linear.num_finite_buckets"></a>
<a name="istio.mixer.v1.config.descriptor.MetricDescriptor.BucketsDefinition.Linear.numFiniteBuckets"></a>
<tr>
<td><code>num_finite_buckets</code></td>
<td><code>numFiniteBuckets</code></td>
<td>int32</td>
<td>Must be greater than 0.</td>
</tr>
@ -794,9 +813,9 @@ The kind of measurement. It describes how the data is recorded.
<th>Value</th>
<th>Description</th>
</tr>
<a name="istio.mixer.v1.config.descriptor.MetricDescriptor.MetricKind.METRIC_KIND_UNSPECIFIED"></a>
<a name="istio.mixer.v1.config.descriptor.MetricDescriptor.MetricKind.METRICKINDUNSPECIFIED"></a>
<tr>
<td>METRIC_KIND_UNSPECIFIED</td>
<td>METRICKINDUNSPECIFIED</td>
<td>Do not use this default value.</td>
</tr>
<a name="istio.mixer.v1.config.descriptor.MetricDescriptor.MetricKind.GAUGE"></a>
@ -837,13 +856,13 @@ such as memory usage of a VM.
<tr>
<td><code>name</code></td>
<td>string</td>
<td>The name of this descriptor</td>
<td>Required. The name of this descriptor.</td>
</tr>
<a name="istio.mixer.v1.config.descriptor.MonitoredResourceDescriptor.description"></a>
<tr>
<td><code>description</code></td>
<td>string</td>
<td>An optional detailed description of the monitored resource descriptor that might be used in documentation.</td>
<td>Optional. A detailed description of the monitored resource descriptor that might be used in documentation.</td>
</tr>
<a name="istio.mixer.v1.config.descriptor.MonitoredResourceDescriptor.labels"></a>
<tr>
@ -869,7 +888,7 @@ A principal is described by a set of attributes.
<tr>
<td><code>name</code></td>
<td>string</td>
<td>The name of this descriptor.</td>
<td>Required. The name of this descriptor.</td>
</tr>
<a name="istio.mixer.v1.config.descriptor.PrincipalDescriptor.labels"></a>
<tr>
@ -902,19 +921,19 @@ unique value for potentially any combination of these attributes.
<tr>
<td><code>name</code></td>
<td>string</td>
<td>The name of this descriptor.</td>
<td>Required. The name of this descriptor.</td>
</tr>
<a name="istio.mixer.v1.config.descriptor.QuotaDescriptor.display_name"></a>
<a name="istio.mixer.v1.config.descriptor.QuotaDescriptor.displayName"></a>
<tr>
<td><code>display_name</code></td>
<td><code>displayName</code></td>
<td>string</td>
<td>An optional concise name for the quota which can be displayed in user interfaces.</td>
<td>Optional. A concise name for the quota which can be displayed in user interfaces.</td>
</tr>
<a name="istio.mixer.v1.config.descriptor.QuotaDescriptor.description"></a>
<tr>
<td><code>description</code></td>
<td>string</td>
<td>An optional description of the quota which can be used in documentation.</td>
<td>Optional. A description of the quota which can be used in documentation.</td>
</tr>
<a name="istio.mixer.v1.config.descriptor.QuotaDescriptor.labels"></a>
<tr>
@ -922,9 +941,9 @@ unique value for potentially any combination of these attributes.
<td>repeated map&lt;string, <a href="#istio.mixer.v1.config.descriptor.ValueType">ValueType</a>&gt;</td>
<td>The set of labels that are necessary to describe a specific value cell for a quota of this type.</td>
</tr>
<a name="istio.mixer.v1.config.descriptor.QuotaDescriptor.rate_limit"></a>
<a name="istio.mixer.v1.config.descriptor.QuotaDescriptor.rateLimit"></a>
<tr>
<td><code>rate_limit</code></td>
<td><code>rateLimit</code></td>
<td>bool</td>
<td>Indicates whether the quota represents a rate limit or represents a resource quota.</td>
</tr>
@ -932,9 +951,10 @@ unique value for potentially any combination of these attributes.
<a name="istio.mixer.v1.config.descriptor.ValueType"></a>
### ValueType
ValueType describes the types that values in the Istio system can take. These are used to describe the type of
Attributes at run time, describe the type of the result of evaluating an expression, and to describe the runtime
type of fields of other descriptors.
ValueType describes the types that values in the Istio system can take. These
are used to describe the type of Attributes at run time, describe the type of
the result of evaluating an expression, and to describe the runtime type of
fields of other descriptors.
<table>
@ -942,9 +962,9 @@ type of fields of other descriptors.
<th>Value</th>
<th>Description</th>
</tr>
<a name="istio.mixer.v1.config.descriptor.ValueType.VALUE_TYPE_UNSPECIFIED"></a>
<a name="istio.mixer.v1.config.descriptor.ValueType.VALUETYPEUNSPECIFIED"></a>
<tr>
<td>VALUE_TYPE_UNSPECIFIED</td>
<td>VALUETYPEUNSPECIFIED</td>
<td>Invalid, default value.</td>
</tr>
<a name="istio.mixer.v1.config.descriptor.ValueType.STRING"></a>
@ -972,14 +992,14 @@ type of fields of other descriptors.
<td>TIMESTAMP</td>
<td>A point in time.</td>
</tr>
<a name="istio.mixer.v1.config.descriptor.ValueType.IP_ADDRESS"></a>
<a name="istio.mixer.v1.config.descriptor.ValueType.IPADDRESS"></a>
<tr>
<td>IP_ADDRESS</td>
<td>IPADDRESS</td>
<td>An IP address.</td>
</tr>
<a name="istio.mixer.v1.config.descriptor.ValueType.EMAIL_ADDRESS"></a>
<a name="istio.mixer.v1.config.descriptor.ValueType.EMAILADDRESS"></a>
<tr>
<td>EMAIL_ADDRESS</td>
<td>EMAILADDRESS</td>
<td>An email address.</td>
</tr>
<a name="istio.mixer.v1.config.descriptor.ValueType.URI"></a>
@ -987,9 +1007,9 @@ type of fields of other descriptors.
<td>URI</td>
<td>A URI.</td>
</tr>
<a name="istio.mixer.v1.config.descriptor.ValueType.DNS_NAME"></a>
<a name="istio.mixer.v1.config.descriptor.ValueType.DNSNAME"></a>
<tr>
<td>DNS_NAME</td>
<td>DNSNAME</td>
<td>A DNS name.</td>
</tr>
<a name="istio.mixer.v1.config.descriptor.ValueType.DURATION"></a>
@ -997,9 +1017,9 @@ type of fields of other descriptors.
<td>DURATION</td>
<td>A span between two points in time.</td>
</tr>
<a name="istio.mixer.v1.config.descriptor.ValueType.STRING_MAP"></a>
<a name="istio.mixer.v1.config.descriptor.ValueType.STRINGMAP"></a>
<tr>
<td>STRING_MAP</td>
<td>STRINGMAP</td>
<td>A map string -&gt; string, typically used by headers.</td>
</tr>
</table>

264
_docs/reference/api/mixer/mixer-service.md
View File

@ -1,16 +1,14 @@
---
title: API
overview: Generated documentation for Mixer's API that is used by Envoy.
title: Mixer Service
overview: Generated documentation for Mixer's API Surface
order: 20
order: 1200
layout: docs
type: markdown
---
<a name="rpc_istio.mixer.v1"></a>
## Package istio.mixer.v1
<a name="rpc_istio.mixer.v1_index"></a>
<a name="rpcIstio.mixer.v1Index"></a>
### Index
* [Mixer](#istio.mixer.v1.Mixer) (interface)
* [Attributes](#istio.mixer.v1.Attributes)
@ -32,32 +30,46 @@ type: markdown
<a name="istio.mixer.v1.Mixer"></a>
### Mixer
The Mixer API
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 report 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. Rate limits are examples of quotas.
<a name="istio.mixer.v1.Mixer.Check"></a>
#### Check
<pre>
rpc Check(<a href="#istio.mixer.v1.CheckRequest">CheckRequest</a>) returns (<a href="#istio.mixer.v1.CheckResponse">CheckResponse</a>)
</pre>
<code>
rpc Check([CheckRequest](#istio.mixer.v1.CheckRequest)) returns ([CheckResponse](#istio.mixer.v1.CheckResponse))
</code>
Checks preconditions before performing an operation.
The preconditions enforced depend on the set of supplied attributes
and the active configuration.
The preconditions enforced depend on the set of supplied attributes and
the active configuration.
<a name="istio.mixer.v1.Mixer.Quota"></a>
#### Quota
<pre>
rpc Quota(<a href="#istio.mixer.v1.QuotaRequest">QuotaRequest</a>) returns (<a href="#istio.mixer.v1.QuotaResponse">QuotaResponse</a>)
</pre>
<code>
rpc Quota([QuotaRequest](#istio.mixer.v1.QuotaRequest)) returns ([QuotaResponse](#istio.mixer.v1.QuotaResponse))
</code>
Quota allocates and releases quota.
<a name="istio.mixer.v1.Mixer.Report"></a>
#### Report
<pre>
rpc Report(<a href="#istio.mixer.v1.ReportRequest">ReportRequest</a>) returns (<a href="#istio.mixer.v1.ReportResponse">ReportResponse</a>)
</pre>
<code>
rpc Report([ReportRequest](#istio.mixer.v1.ReportRequest)) returns ([ReportResponse](#istio.mixer.v1.ReportResponse))
</code>
Reports telemetry, such as logs and metrics.
The reported information depends on the set of supplied attributes
and the active configuration.
The reported information depends on the set of supplied attributes and the
active configuration.
<a name="istio.mixer.v1.Attributes"></a>
### Attributes
@ -81,7 +93,7 @@ The processing order for this state in the mixer is:
new context is automatically created and initialized to the empty state. When a gRPC
stream is first created, there are no attribute contexts for the stream.
* If reset_context is true, then the attribute context is reset to the
* If resetContext is true, then the attribute context is reset to the
empty state.
* All attributes to deleted are removed from the attribute context.
@ -100,81 +112,81 @@ The processing order for this state in the mixer is:
<td>repeated map&lt;int32, string&gt;</td>
<td><p>A dictionary that provides a mapping of shorthand index values to attribute names.</p><p>This is intended to leverage the stateful gRPC stream from the proxy to the mixer. This dictionary is sent over only when a stream to the mixer is first established and when the proxy's configuration changes and different attributes may be produced.</p><p>Once a dictionary has been sent over, it stays in effect until a new dictionary is sent to replace it. The first request sent on a stream must include a dictionary, otherwise the mixer can't process any attribute updates.</p><p>Dictionaries are independent of the attribute context and are thus global to each gRPC stream.</p></td>
</tr>
<a name="istio.mixer.v1.Attributes.attribute_context"></a>
<a name="istio.mixer.v1.Attributes.attributeContext"></a>
<tr>
<td><code>attribute_context</code></td>
<td><code>attributeContext</code></td>
<td>int32</td>
<td><p>The attribute context against which to operate.</p><p>The mixer keeps different contexts live for any proxy gRPC stream. This allows the proxy to maintain multiple concurrent 'bags of attributes' within the mixer.</p><p>If the proxy doesn't want to leverage multiple contexts, it just passes 0 here for every request.</p><p>The proxy is configured to use a maximum number of attribute contexts in order to prevent an explosion of contexts in the mixer's memory space.</p></td>
</tr>
<a name="istio.mixer.v1.Attributes.reset_context"></a>
<a name="istio.mixer.v1.Attributes.resetContext"></a>
<tr>
<td><code>reset_context</code></td>
<td><code>resetContext</code></td>
<td>bool</td>
<td><p>When true, resets the current attribute context to the empty state before applying any incoming attributes.</p><p>Resetting contexts is useful to constrain the amount of resources used by the mixer. The proxy needs to intelligently manage a pool of contexts. It may be useful to reset a context when certain big events happen, such as when an HTTP2 connection into the proxy terminates.</p></td>
</tr>
<a name="istio.mixer.v1.Attributes.string_attributes"></a>
<a name="istio.mixer.v1.Attributes.stringAttributes"></a>
<tr>
<td><code>string_attributes</code></td>
<td><code>stringAttributes</code></td>
<td>repeated map&lt;int32, string&gt;</td>
<td>Attributes being updated within the specified attribute context. These maps add and/or overwrite the context's current set of attributes.</td>
</tr>
<a name="istio.mixer.v1.Attributes.int64_attributes"></a>
<a name="istio.mixer.v1.Attributes.int64Attributes"></a>
<tr>
<td><code>int64_attributes</code></td>
<td><code>int64Attributes</code></td>
<td>repeated map&lt;int32, int64&gt;</td>
<td></td>
</tr>
<a name="istio.mixer.v1.Attributes.double_attributes"></a>
<a name="istio.mixer.v1.Attributes.doubleAttributes"></a>
<tr>
<td><code>double_attributes</code></td>
<td><code>doubleAttributes</code></td>
<td>repeated map&lt;int32, double&gt;</td>
<td></td>
</tr>
<a name="istio.mixer.v1.Attributes.bool_attributes"></a>
<a name="istio.mixer.v1.Attributes.boolAttributes"></a>
<tr>
<td><code>bool_attributes</code></td>
<td><code>boolAttributes</code></td>
<td>repeated map&lt;int32, bool&gt;</td>
<td></td>
</tr>
<a name="istio.mixer.v1.Attributes.timestamp_attributes"></a>
<a name="istio.mixer.v1.Attributes.timestampAttributes"></a>
<tr>
<td><code>timestamp_attributes</code></td>
<td><code>timestampAttributes</code></td>
<td>repeated map&lt;int32, <a href="https://developers.google.com/protocol-buffers/docs/reference/google.protobuf#timestamp">Timestamp</a>&gt;</td>
<td></td>
</tr>
<a name="istio.mixer.v1.Attributes.duration_attributes"></a>
<a name="istio.mixer.v1.Attributes.durationAttributes"></a>
<tr>
<td><code>duration_attributes</code></td>
<td><code>durationAttributes</code></td>
<td>repeated map&lt;int32, <a href="https://developers.google.com/protocol-buffers/docs/reference/google.protobuf#duration">Duration</a>&gt;</td>
<td></td>
</tr>
<a name="istio.mixer.v1.Attributes.bytes_attributes"></a>
<a name="istio.mixer.v1.Attributes.bytesAttributes"></a>
<tr>
<td><code>bytes_attributes</code></td>
<td><code>bytesAttributes</code></td>
<td>repeated map&lt;int32, bytes&gt;</td>
<td></td>
</tr>
<a name="istio.mixer.v1.Attributes.stringMap_attributes"></a>
<a name="istio.mixer.v1.Attributes.stringMapAttributes"></a>
<tr>
<td><code>stringMap_attributes</code></td>
<td><code>stringMapAttributes</code></td>
<td>repeated map&lt;int32, <a href="#istio.mixer.v1.StringMap">StringMap</a>&gt;</td>
<td></td>
</tr>
<a name="istio.mixer.v1.Attributes.deleted_attributes"></a>
<a name="istio.mixer.v1.Attributes.deletedAttributes"></a>
<tr>
<td><code>deleted_attributes[]</code></td>
<td><code>deletedAttributes[]</code></td>
<td>repeated int32</td>
<td>Attributes that should be removed from the specified attribute context. Deleting attributes which aren't currently in the attribute context is not considered an error.</td>
</tr>
<a name="istio.mixer.v1.Attributes.timestamp_attributes_HACK"></a>
<a name="istio.mixer.v1.Attributes.timestampAttributesHACK"></a>
<tr>
<td><code>timestamp_attributes_HACK</code></td>
<td><code>timestampAttributesHACK</code></td>
<td>repeated map&lt;int32, <a href="https://developers.google.com/protocol-buffers/docs/reference/google.protobuf#timestamp">Timestamp</a>&gt;</td>
<td></td>
</tr>
<a name="istio.mixer.v1.Attributes.duration_attributes_HACK"></a>
<a name="istio.mixer.v1.Attributes.durationAttributesHACK"></a>
<tr>
<td><code>duration_attributes_HACK</code></td>
<td><code>durationAttributesHACK</code></td>
<td>repeated map&lt;int32, <a href="https://developers.google.com/protocol-buffers/docs/reference/google.protobuf#duration">Duration</a>&gt;</td>
<td></td>
</tr>
@ -190,15 +202,15 @@ Used to verify preconditions before performing an action.
<th>Type</th>
<th>Description</th>
</tr>
<a name="istio.mixer.v1.CheckRequest.request_index"></a>
<a name="istio.mixer.v1.CheckRequest.requestIndex"></a>
<tr>
<td><code>request_index</code></td>
<td><code>requestIndex</code></td>
<td>int64</td>
<td>Index within the stream for this request, used to match to responses</td>
</tr>
<a name="istio.mixer.v1.CheckRequest.attribute_update"></a>
<a name="istio.mixer.v1.CheckRequest.attributeUpdate"></a>
<tr>
<td><code>attribute_update</code></td>
<td><code>attributeUpdate</code></td>
<td><a href="#istio.mixer.v1.Attributes">Attributes</a></td>
<td>The attributes to use for this request</td>
</tr>
@ -213,22 +225,22 @@ Used to verify preconditions before performing an action.
<th>Type</th>
<th>Description</th>
</tr>
<a name="istio.mixer.v1.CheckResponse.request_index"></a>
<a name="istio.mixer.v1.CheckResponse.requestIndex"></a>
<tr>
<td><code>request_index</code></td>
<td><code>requestIndex</code></td>
<td>int64</td>
<td>Index of the request this response is associated with</td>
</tr>
<a name="istio.mixer.v1.CheckResponse.attribute_update"></a>
<a name="istio.mixer.v1.CheckResponse.attributeUpdate"></a>
<tr>
<td><code>attribute_update</code></td>
<td><code>attributeUpdate</code></td>
<td><a href="#istio.mixer.v1.Attributes">Attributes</a></td>
<td>The attributes to use for this response</td>
</tr>
<a name="istio.mixer.v1.CheckResponse.result"></a>
<tr>
<td><code>result</code></td>
<td><a href="#google.rpc.Status">Status</a></td>
<td><a href="/docs/reference/api/status.html">Status</a></td>
<td>Indicates whether or not the preconditions succeeded</td>
</tr>
<a name="istio.mixer.v1.CheckResponse.expiration"></a>
@ -248,21 +260,21 @@ Used to verify preconditions before performing an action.
<th>Type</th>
<th>Description</th>
</tr>
<a name="istio.mixer.v1.QuotaRequest.request_index"></a>
<a name="istio.mixer.v1.QuotaRequest.requestIndex"></a>
<tr>
<td><code>request_index</code></td>
<td><code>requestIndex</code></td>
<td>int64</td>
<td>Index within the stream for this request, used to match to responses</td>
</tr>
<a name="istio.mixer.v1.QuotaRequest.attribute_update"></a>
<a name="istio.mixer.v1.QuotaRequest.attributeUpdate"></a>
<tr>
<td><code>attribute_update</code></td>
<td><code>attributeUpdate</code></td>
<td><a href="#istio.mixer.v1.Attributes">Attributes</a></td>
<td>The attributes to use for this request</td>
</tr>
<a name="istio.mixer.v1.QuotaRequest.deduplication_id"></a>
<a name="istio.mixer.v1.QuotaRequest.deduplicationId"></a>
<tr>
<td><code>deduplication_id</code></td>
<td><code>deduplicationId</code></td>
<td>string</td>
<td>Used for deduplicating quota allocation/free calls in the case of failed RPCs and retries. This should be a UUID per call, where the same UUID is used for retries of the same quota allocation call.</td>
</tr>
@ -278,9 +290,9 @@ Used to verify preconditions before performing an action.
<td>int64</td>
<td>The amount of quota to allocate.</td>
</tr>
<a name="istio.mixer.v1.QuotaRequest.best_effort"></a>
<a name="istio.mixer.v1.QuotaRequest.bestEffort"></a>
<tr>
<td><code>best_effort</code></td>
<td><code>bestEffort</code></td>
<td>bool</td>
<td>If true, allows a response to return less quota than requested. When false, the exact requested amount is returned or 0 if not enough quota was available.</td>
</tr>
@ -295,22 +307,22 @@ Used to verify preconditions before performing an action.
<th>Type</th>
<th>Description</th>
</tr>
<a name="istio.mixer.v1.QuotaResponse.request_index"></a>
<a name="istio.mixer.v1.QuotaResponse.requestIndex"></a>
<tr>
<td><code>request_index</code></td>
<td><code>requestIndex</code></td>
<td>int64</td>
<td>Index of the request this response is associated with.</td>
</tr>
<a name="istio.mixer.v1.QuotaResponse.attribute_update"></a>
<a name="istio.mixer.v1.QuotaResponse.attributeUpdate"></a>
<tr>
<td><code>attribute_update</code></td>
<td><code>attributeUpdate</code></td>
<td><a href="#istio.mixer.v1.Attributes">Attributes</a></td>
<td>The attributes to use for this response</td>
</tr>
<a name="istio.mixer.v1.QuotaResponse.result"></a>
<tr>
<td><code>result</code></td>
<td><a href="#google.rpc.Status">Status</a></td>
<td><a href="/docs/reference/api/status.html">Status</a></td>
<td>Indicates whether the quota request was successfully processed.</td>
</tr>
<a name="istio.mixer.v1.QuotaResponse.expiration"></a>
@ -337,15 +349,15 @@ Used to report telemetry after performing an action.
<th>Type</th>
<th>Description</th>
</tr>
<a name="istio.mixer.v1.ReportRequest.request_index"></a>
<a name="istio.mixer.v1.ReportRequest.requestIndex"></a>
<tr>
<td><code>request_index</code></td>
<td><code>requestIndex</code></td>
<td>int64</td>
<td>Index within the stream for this request, used to match to responses</td>
</tr>
<a name="istio.mixer.v1.ReportRequest.attribute_update"></a>
<a name="istio.mixer.v1.ReportRequest.attributeUpdate"></a>
<tr>
<td><code>attribute_update</code></td>
<td><code>attributeUpdate</code></td>
<td><a href="#istio.mixer.v1.Attributes">Attributes</a></td>
<td>The attributes to use for this request</td>
</tr>
@ -360,22 +372,22 @@ Used to report telemetry after performing an action.
<th>Type</th>
<th>Description</th>
</tr>
<a name="istio.mixer.v1.ReportResponse.request_index"></a>
<a name="istio.mixer.v1.ReportResponse.requestIndex"></a>
<tr>
<td><code>request_index</code></td>
<td><code>requestIndex</code></td>
<td>int64</td>
<td>Index of the request this response is associated with</td>
</tr>
<a name="istio.mixer.v1.ReportResponse.attribute_update"></a>
<a name="istio.mixer.v1.ReportResponse.attributeUpdate"></a>
<tr>
<td><code>attribute_update</code></td>
<td><code>attributeUpdate</code></td>
<td><a href="#istio.mixer.v1.Attributes">Attributes</a></td>
<td>The attributes to use for this response</td>
</tr>
<a name="istio.mixer.v1.ReportResponse.result"></a>
<tr>
<td><code>result</code></td>
<td><a href="#google.rpc.Status">Status</a></td>
<td><a href="/docs/reference/api/status.html">Status</a></td>
<td>Indicates whether the report was processed or not</td>
</tr>
</table>
@ -398,99 +410,3 @@ dictionary.
<td></td>
</tr>
</table>
<a name="rpc_google.rpc"></a>
## Package google.rpc
<a name="rpc_google.rpc_index"></a>
### Index
* [Status](#google.rpc.Status)
(message)
<a name="google.rpc.Status"></a>
### Status
The `Status` type defines a logical error model that is suitable for different
programming environments, including REST APIs and RPC APIs. It is used by
[gRPC](https://github.com/grpc). The error model is designed to be:
- Simple to use and understand for most users
- Flexible enough to meet unexpected needs
<a name="rpc_google.rpc_google.rpc.Status_description_subsection"></a>
#### Overview
The `Status` message contains three pieces of data: error code, error message,
and error details. The error code should be an enum value of
[google.rpc.Code](#google.rpc.Code), but it may accept additional error codes if needed. The
error message should be a developer-facing English message that helps
developers *understand* and *resolve* the error. If a localized user-facing
error message is needed, put the localized message in the error details or
localize it in the client. The optional error details may contain arbitrary
information about the error. There is a predefined set of error detail types
in the package `google.rpc` which can be used for common error conditions.
<a name="rpc_google.rpc_google.rpc.Status_description_subsection_1"></a>
#### Language mapping
The `Status` message is the logical representation of the error model, but it
is not necessarily the actual wire format. When the `Status` message is
exposed in different client libraries and different wire protocols, it can be
mapped differently. For example, it will likely be mapped to some exceptions
in Java, but more likely mapped to some error codes in C.
<a name="rpc_google.rpc_google.rpc.Status_description_subsection_2"></a>
#### Other uses
The error model and the `Status` message can be used in a variety of
environments, either with or without APIs, to provide a
consistent developer experience across different environments.
Example uses of this error model include:
- Partial errors. If a service needs to return partial errors to the client,
it may embed the `Status` in the normal response to indicate the partial
errors.
- Workflow errors. A typical workflow has multiple steps. Each step may
have a `Status` message for error reporting purpose.
- Batch operations. If a client uses batch request and batch response, the
`Status` message should be used directly inside batch response, one for
each error sub-response.
- Asynchronous operations. If an API call embeds asynchronous operation
results in its response, the status of those operations should be
represented directly using the `Status` message.
- Logging. If some API errors are stored in logs, the message `Status` could
be used directly after any stripping needed for security/privacy reasons.
<table>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
<a name="google.rpc.Status.code"></a>
<tr>
<td><code>code</code></td>
<td>int32</td>
<td>The status code, which should be an enum value of <a href="#google.rpc.Code">google.rpc.Code</a>.</td>
</tr>
<a name="google.rpc.Status.message"></a>
<tr>
<td><code>message</code></td>
<td>string</td>
<td>A developer-facing error message, which should be in English. Any user-facing error message should be localized and sent in the <a href="#google.rpc.Status.details">google.rpc.Status.details</a> field, or localized by the client.</td>
</tr>
<a name="google.rpc.Status.details"></a>
<tr>
<td><code>details[]</code></td>
<td>repeated <a href="https://developers.google.com/protocol-buffers/docs/reference/google.protobuf#any">Any</a></td>
<td>A list of messages that carry the error details. There will be a common set of message types for APIs to use.</td>
</tr>
</table>

102
_docs/reference/api/status.md Normal file
View File

@ -0,0 +1,102 @@
---
title: Status RPC
overview: Generated documentation for Google's rpc.Status proto
order: 40
layout: docs
type: markdown
---
<a name="rpcGoogle.rpcIndex"></a>
### Index
* [Status](#google.rpc.Status)
(message)
<a name="google.rpc.Status"></a>
### Status
The `Status` type defines a logical error model that is suitable for different
programming environments, including REST APIs and RPC APIs. It is used by
[gRPC](https://github.com/grpc). The error model is designed to be:
- Simple to use and understand for most users
- Flexible enough to meet unexpected needs
<a name="rpcGoogle.rpcGoogle.rpc.StatusDescriptionSubsection"></a>
#### Overview
The `Status` message contains three pieces of data: error code, error message,
and error details. The error code should be an enum value of
[google.rpc.Code](#google.rpc.Code), but it may accept additional error codes if needed. The
error message should be a developer-facing English message that helps
developers *understand* and *resolve* the error. If a localized user-facing
error message is needed, put the localized message in the error details or
localize it in the client. The optional error details may contain arbitrary
information about the error. There is a predefined set of error detail types
in the package `google.rpc` that can be used for common error conditions.
<a name="rpcGoogle.rpcGoogle.rpc.StatusDescriptionSubsection_1"></a>
#### Language mapping
The `Status` message is the logical representation of the error model, but it
is not necessarily the actual wire format. When the `Status` message is
exposed in different client libraries and different wire protocols, it can be
mapped differently. For example, it will likely be mapped to some exceptions
in Java, but more likely mapped to some error codes in C.
<a name="rpcGoogle.rpcGoogle.rpc.StatusDescriptionSubsection_2"></a>
#### Other uses
The error model and the `Status` message can be used in a variety of
environments, either with or without APIs, to provide a
consistent developer experience across different environments.
Example uses of this error model include:
- Partial errors. If a service needs to return partial errors to the client,
it may embed the `Status` in the normal response to indicate the partial
errors.
- Workflow errors. A typical workflow has multiple steps. Each step may
have a `Status` message for error reporting.
- Batch operations. If a client uses batch request and batch response, the
`Status` message should be used directly inside batch response, one for
each error sub-response.
- Asynchronous operations. If an API call embeds asynchronous operation
results in its response, the status of those operations should be
represented directly using the `Status` message.
- Logging. If some API errors are stored in logs, the message `Status` could
be used directly after any stripping needed for security/privacy reasons.
<table>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
<a name="google.rpc.Status.code"></a>
<tr>
<td><code>code</code></td>
<td>int32</td>
<td>The status code, which should be an enum value of <a href="#google.rpc.Code">google.rpc.Code</a>.</td>
</tr>
<a name="google.rpc.Status.message"></a>
<tr>
<td><code>message</code></td>
<td>string</td>
<td>A developer-facing error message, which should be in English. Any user-facing error message should be localized and sent in the <a href="#google.rpc.Status.details">google.rpc.Status.details</a> field, or localized by the client.</td>
</tr>
<a name="google.rpc.Status.details"></a>
<tr>
<td><code>details[]</code></td>
<td>repeated <a href="https://developers.google.com/protocol-buffers/docs/reference/google.protobuf#any">Any</a></td>
<td>A list of messages that carry the error details. There will be a common set of message types for APIs to use.</td>
</tr>
</table>