From 8c5fdb055d44f001ec96311722d5c5f17c21ae27 Mon Sep 17 00:00:00 2001 From: Zack Butcher Date: Fri, 22 Sep 2017 16:00:11 -0700 Subject: [PATCH] First pass generating docs from istio/api and istio/mixer (#500) * First pass generating docs from istio/api and istio/mixer. Put them in a staging area so we can migrate into their final location incrementally. * regenerate everything, add in egress --- _docs/reference/new/adapters/denier.md | 34 + _docs/reference/new/adapters/index.md | 12 + _docs/reference/new/adapters/kubernetes.md | 168 +++ _docs/reference/new/adapters/list.md | 103 ++ _docs/reference/new/adapters/memquota.md | 107 ++ _docs/reference/new/adapters/prometheus.md | 263 ++++ _docs/reference/new/adapters/stackdriver.md | 437 ++++++ _docs/reference/new/adapters/statsd.md | 123 ++ _docs/reference/new/adapters/stdio.md | 104 ++ _docs/reference/new/adapters/svcctrl.md | 33 + _docs/reference/new/destination-policies.md | 1173 ++++++++++++++++ _docs/reference/new/egress-rules.md | 969 +++++++++++++ _docs/reference/new/fault-injection.md | 144 ++ _docs/reference/new/manager-config.md | 250 ++++ _docs/reference/new/mixer-config.md | 1240 +++++++++++++++++ _docs/reference/new/mixer-service.md | 566 ++++++++ _docs/reference/new/routing-rules.md | 689 +++++++++ _docs/reference/new/templates/checknothing.md | 24 + _docs/reference/new/templates/index.md | 12 + _docs/reference/new/templates/listentry.md | 35 + _docs/reference/new/templates/logentry.md | 142 ++ _docs/reference/new/templates/metric.md | 136 ++ _docs/reference/new/templates/quota.md | 117 ++ .../reference/new/templates/reportnothing.md | 24 + 24 files changed, 6905 insertions(+) create mode 100644 _docs/reference/new/adapters/denier.md create mode 100644 _docs/reference/new/adapters/index.md create mode 100644 _docs/reference/new/adapters/kubernetes.md create mode 100644 _docs/reference/new/adapters/list.md create mode 100644 _docs/reference/new/adapters/memquota.md create mode 100644 _docs/reference/new/adapters/prometheus.md create mode 100644 _docs/reference/new/adapters/stackdriver.md create mode 100644 _docs/reference/new/adapters/statsd.md create mode 100644 _docs/reference/new/adapters/stdio.md create mode 100644 _docs/reference/new/adapters/svcctrl.md create mode 100644 _docs/reference/new/destination-policies.md create mode 100644 _docs/reference/new/egress-rules.md create mode 100644 _docs/reference/new/fault-injection.md create mode 100644 _docs/reference/new/manager-config.md create mode 100644 _docs/reference/new/mixer-config.md create mode 100644 _docs/reference/new/mixer-service.md create mode 100644 _docs/reference/new/routing-rules.md create mode 100644 _docs/reference/new/templates/checknothing.md create mode 100644 _docs/reference/new/templates/index.md create mode 100644 _docs/reference/new/templates/listentry.md create mode 100644 _docs/reference/new/templates/logentry.md create mode 100644 _docs/reference/new/templates/metric.md create mode 100644 _docs/reference/new/templates/quota.md create mode 100644 _docs/reference/new/templates/reportnothing.md diff --git a/_docs/reference/new/adapters/denier.md b/_docs/reference/new/adapters/denier.md new file mode 100644 index 0000000000..644dc451c8 --- /dev/null +++ b/_docs/reference/new/adapters/denier.md @@ -0,0 +1,34 @@ +--- +title: denier Config +overview: Generated documentation for Mixer's denier Adapter Configuration Schema + +order: 0 + +layout: docs +type: markdown +--- + + + +### Index + +* [Params](#adapter.denier.config.Params) +(message) + + +### Params + + + + + + + + + + + + + +
FieldTypeDescription
statusStatusThe error to return when denying a request.
+ diff --git a/_docs/reference/new/adapters/index.md b/_docs/reference/new/adapters/index.md new file mode 100644 index 0000000000..55730b8503 --- /dev/null +++ b/_docs/reference/new/adapters/index.md @@ -0,0 +1,12 @@ +--- +title: Mixer Adapters +overview: Generated documentation for Mixer's adapters. + +order: 2000 + +layout: docs +type: markdown +--- + +{% include section-index.html %} + diff --git a/_docs/reference/new/adapters/kubernetes.md b/_docs/reference/new/adapters/kubernetes.md new file mode 100644 index 0000000000..8224f0251c --- /dev/null +++ b/_docs/reference/new/adapters/kubernetes.md @@ -0,0 +1,168 @@ +--- +title: kubernetes Config +overview: Generated documentation for Mixer's kubernetes Adapter Configuration Schema + +order: 10 + +layout: docs +type: markdown +--- + + + +### Index + +* [Params](#adapter.kubernetes.config.Params) +(message) + + +### 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, +destination, 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). + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FieldTypeDescription
kubeconfigPathstring

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.

NOTE: The kubernetes adapter will use the value of the env var KUBECONFIG in the case where it is set (overriding any value configured through this proto).

Default: "" (unset)

cacheRefreshDurationDuration

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.

Default: 5 minutes

sourceUidInputNamestring

Configures how the UID for the source pod for traffic is identified in the input map.

Default: sourceUID

destinationUidInputNamestring

Configures how the UID for the destination pod for traffic is identified in the input map.

Default: destinationUID

originUidInputNamestring

Configures how the UID for the origin pod for traffic is identified in the input map.

Default: originUID

sourceIpInputNamestring

Configures how the IP for the source pod for traffic is identified in the input map.

Default: sourceIP

destinationIpInputNamestring

Configures how the IP for the destination pod for traffic is identified in the input map.

Default: destinationIP

originIpInputNamestring

Configures how the IP for the origin pod for traffic is identified in the input map.

Default: originIP

clusterDomainNamestring

Configures the cluster domain name to use for service name normalization.

Default: svc.cluster.local

podLabelForServicestring

In order to extract the service associated with a source, destination, or origin, this adapter relies on pod labels. In particular, it looks for the value of a specific label, as specified by this parameter.

Default: app

podLabelForIstioComponentServicestring

In order to extract the service associated with a source, destination, or origin, this adapter relies on pod labels. In particular, it looks for the value of a specific label for istio component services, as specified by this parameter.

Default: istio

sourcePrefixstring

The prefix used for source pod output value names.

Default: source

destinationPrefixstring

The prefix used for destination pod output value names.

Default: destination

originPrefixstring

The prefix used for origin pod output value names.

Default: origin

labelsValueNamestring

The value name for the pod labels output value.

Default: Labels

podNameValueNamestring

The value name for the pod name output value.

Default: PodName

podIpValueNamestring

The value name for the pod ip address output value.

Default: PodIP

hostIpValueNamestring

The value name for the pod host ip address output value.

Default: HostIP

namespaceValueNamestring

The value name for the pod namespace output value.

Default: Namespace

serviceAccountValueNamestring

The value name for the pod service account name output value.

Default: ServiceAccountName

serviceValueNamestring

The value name for the service output value.

Default: Service

diff --git a/_docs/reference/new/adapters/list.md b/_docs/reference/new/adapters/list.md new file mode 100644 index 0000000000..f20962d633 --- /dev/null +++ b/_docs/reference/new/adapters/list.md @@ -0,0 +1,103 @@ +--- +title: list Config +overview: Generated documentation for Mixer's list Adapter Configuration Schema + +order: 20 + +layout: docs +type: markdown +--- + + + +### Index + +* [Params](#adapter.list.config.Params) +(message) +* [Params.ListEntryType](#adapter.list.config.Params.ListEntryType) +(enum) + + +### Params + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FieldTypeDescription
providerUrlstringWhere to find the list to check against. This may be ommited for a completely local list.
refreshIntervalDurationDetermines how often the provider is polled for an updated list
ttlDurationIndicates how long to keep a list before discarding it. Typically, the TTL value should be set to noticeably longer (> 2x) than the refresh interval to ensure continued operation in the face of transient server outages.
cachingIntervalDurationIndicates the amount of time a caller of this adapter can cache an answer before it should ask the adapter again.
cachingUseCountint32Indicates the number of times a caller of this adapter can use a cached answer before it should ask the adapter again.
overrides[]repeated stringList entries that are consulted first, before the list from the server
entryTypeListEntryTypeDetermines the kind of list entry and overrides.
blacklistboolWhether the list operates as a blacklist or a whitelist.
+ + +### ListEntryType + + + + + + + + + + + + + + + + + + + + + + +
ValueDescription
STRINGSList entries are treated as plain strings.
CASEINSENSITIVESTRINGSList entries are treated as case-insensitive strings.
IPADDRESSESList entries are treated as IP addresses and ranges.
diff --git a/_docs/reference/new/adapters/memquota.md b/_docs/reference/new/adapters/memquota.md new file mode 100644 index 0000000000..a5b442f857 --- /dev/null +++ b/_docs/reference/new/adapters/memquota.md @@ -0,0 +1,107 @@ +--- +title: memquota Config +overview: Generated documentation for Mixer's memquota Adapter Configuration Schema + +order: 30 + +layout: docs +type: markdown +--- + + + +### Index + +* [Params](#adapter.memquota.config.Params) +(message) +* [Params.Override](#adapter.memquota.config.Params.Override) +(message) +* [Params.Quota](#adapter.memquota.config.Params.Quota) +(message) + + +### Params + + + + + + + + + + + + + + + + + + + +
FieldTypeDescription
quotas[]repeated QuotaThe set of known quotas.
minDeduplicationDurationDurationMinimum number of seconds that deduplication is possible for a given operation.
+ + +### Override + + + + + + + + + + + + + + + + + + + + + + + + + +
FieldTypeDescription
dimensionsrepeated map<string, string>The specific dimensions for which this override applies. String representation of instance dimensions is used to check against configured dimensions.
maxAmountint64The upper limit for this quota.
validDurationDurationThe amount of time allocated quota remains valid before it is automatically released. This is only meaningful for rate limit quotas, otherwise the value must be zero.
+ + +### Quota + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FieldTypeDescription
namestringThe name of the quota
maxAmountint64The upper limit for this quota.
validDurationDurationThe amount of time allocated quota remains valid before it is automatically released. This is only meaningful for rate limit quotas, otherwise the value must be zero.
overrides[]repeated OverrideOverrides associated with this quota. The first matching override is applied.
diff --git a/_docs/reference/new/adapters/prometheus.md b/_docs/reference/new/adapters/prometheus.md new file mode 100644 index 0000000000..48a27f242c --- /dev/null +++ b/_docs/reference/new/adapters/prometheus.md @@ -0,0 +1,263 @@ +--- +title: prometheus Config +overview: Generated documentation for Mixer's prometheus Adapter Configuration Schema + +order: 40 + +layout: docs +type: markdown +--- + + + +### Index + +* [Params](#adapter.prometheus.config.Params) +(message) +* [Params.MetricInfo](#adapter.prometheus.config.Params.MetricInfo) +(message) +* [Params.MetricInfo.BucketsDefinition](#adapter.prometheus.config.Params.MetricInfo.BucketsDefinition) +(message) +* [Params.MetricInfo.BucketsDefinition.Explicit](#adapter.prometheus.config.Params.MetricInfo.BucketsDefinition.Explicit) +(message) +* [Params.MetricInfo.BucketsDefinition.Exponential](#adapter.prometheus.config.Params.MetricInfo.BucketsDefinition.Exponential) +(message) +* [Params.MetricInfo.BucketsDefinition.Linear](#adapter.prometheus.config.Params.MetricInfo.BucketsDefinition.Linear) +(message) +* [Params.MetricInfo.Kind](#adapter.prometheus.config.Params.MetricInfo.Kind) +(enum) + + +### Params + + + + + + + + + + + + + +
FieldTypeDescription
metrics[]repeated MetricInfoThe set of metrics to represent in Prometheus. If a metric is defined in Istio but doesn't have a corresponding shape here, it will not be populated at runtime.
+ + +### MetricInfo +Describes how a metric should be represented in Prometheus. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FieldTypeDescription
namestringRecommended. The name is used to register the prometheus metric. It must be unique across all prometheus metrics as prometheus does not allow duplicate names. If name is not specified a sanitized version of instanceName is used.
instanceNamestringRequired. The name is the fully qualified name of the Istio metric instance that this MetricInfo processes.
descriptionstringOptional. A human readable description of this metric.
kindKind
bucketsBucketsDefinitionFor metrics with a metric kind of DISTRIBUTION, this provides a mechanism for configuring the buckets that will be used to store the aggregated values. This field must be provided for metrics declared to be of type DISTRIBUTION. This field will be ignored for non-distribution metric kinds.
labelNames[]repeated stringThe names of labels to use: these need to match the dimensions of the Istio metric.
+ + +### BucketsDefinition +Describes buckets for DISTRIBUTION kind metrics. + + + + + + + + + + + + + + + + + + + + + + + + + +
FieldTypeDescription
linearBucketsLinear (oneof )The linear buckets.
exponentialBucketsExponential (oneof )The exponential buckets.
explicitBucketsExplicit (oneof )The explicit buckets.
+ + +### Explicit +Specifies a set of buckets with arbitrary widths. + +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]` + +The `bounds` field must contain at least one element. If `bounds` has +only one element, then there are no finite buckets, and that single +element is the common boundary of the overflow and underflow buckets. + + + + + + + + + + + + + +
FieldTypeDescription
bounds[]repeated doubleThe values must be monotonically increasing.
+ + +### Exponential +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 `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 * (growthFactor ^ i)` +* Lower bound (1 <= i < N): `scale * (growthFactor ^ (i - 1))` + + + + + + + + + + + + + + + + + + + + + + + + + +
FieldTypeDescription
numFiniteBucketsint32Must be greater than 0.
growthFactordoubleMust be greater than 1.
scaledoubleMust be greater than 0.
+ + +### Linear +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 `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))` + + + + + + + + + + + + + + + + + + + + + + + + + +
FieldTypeDescription
numFiniteBucketsint32Must be greater than 0.
widthdoubleMust be greater than 0.
offsetdoubleLower bound of the first bucket.
+ + +### Kind +Describes what kind of metric this is. + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ValueDescription
UNSPECIFIED
GAUGE
COUNTER
DISTRIBUTION
diff --git a/_docs/reference/new/adapters/stackdriver.md b/_docs/reference/new/adapters/stackdriver.md new file mode 100644 index 0000000000..c177f0345d --- /dev/null +++ b/_docs/reference/new/adapters/stackdriver.md @@ -0,0 +1,437 @@ +--- +title: stackdriver Config +overview: Generated documentation for Mixer's stackdriver Adapter Configuration Schema + +order: 50 + +layout: docs +type: markdown +--- + + + +### Index + +* [Params](#adapter.stackdriver.config.Params) +(message) +* [Params.LogInfo](#adapter.stackdriver.config.Params.LogInfo) +(message) +* [Params.LogInfo.HttpRequestMapping](#adapter.stackdriver.config.Params.LogInfo.HttpRequestMapping) +(message) +* [Params.MetricInfo](#adapter.stackdriver.config.Params.MetricInfo) +(message) +* [Params.MetricInfo.BucketsDefinition](#adapter.stackdriver.config.Params.MetricInfo.BucketsDefinition) +(message) +* [Params.MetricInfo.BucketsDefinition.Explicit](#adapter.stackdriver.config.Params.MetricInfo.BucketsDefinition.Explicit) +(message) +* [Params.MetricInfo.BucketsDefinition.Exponential](#adapter.stackdriver.config.Params.MetricInfo.BucketsDefinition.Exponential) +(message) +* [Params.MetricInfo.BucketsDefinition.Linear](#adapter.stackdriver.config.Params.MetricInfo.BucketsDefinition.Linear) +(message) + + +### Params + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FieldTypeDescription
endpointstringEndpoint URL to send stackdriver data - leave empty to use the StackDriver SDK's default value (monitoring.googleapis.com).
projectIdstringGCP Project to attach metrics to.
pushIntervalDurationThis adapter batches the data it sends to Stackdriver; we will push to stackdriver every pushInterval. If no value is provided we default to once per minute.
metricInforepeated map<string, MetricInfo>A map of Istio metric name to Stackdriver metric info.
logInforepeated map<string, LogInfo>A map of Istio LogEntry name to Stackdriver log info.
appCredentialsbool (oneof )

Use Google's Application Default Credentials to authorize calls made by the StackDriver SDK.

See Google's documentation.

apiKeystring (oneof )The API Key to be used for auth.
serviceAccountPathstring (oneof )The path to a Google service account credential file, relative to the Mixer. E.g. /etc/opt/mixer/gcp-serviceaccount-creds.json or ./testdata/my-test-account-creds.json.
+ + +### LogInfo +Describes how to represent an Istio Log in Stackdriver. + + + + + + + + + + + + + + + + + + + + + + + + + +
FieldTypeDescription
labelNames[]repeated stringThe logging template provides a set of variables; these list the subset of variables that should be used to form Stackdriver labels for the log entry.
payloadTemplatestringA golang text/template template that will be executed to construct the payload for this log entry. It will be given the full set of variables for the log to use to construct its result.
httpMappingHttpRequestMappingIf an HttpRequestMapping is provided, a HttpRequest object will be filled out for this log entry using the variables named in the mapping to populate the fields of the request struct from the instance's variables.
+ + +### HttpRequestMapping +Maps from template variable names to the various fields of Stackdriver's HTTP request struct. +See https://godoc.org/cloud.google.com/go/logging#HTTPRequest + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FieldTypeDescription
statusstringtemplate variable name to map into HTTPRequest.Status
requestSizestringtemplate variable name to map into HTTPRequest.RequestSize
responseSizestringtemplate variable name to map into HTTPRequest.ResponseSize
latencystringtemplate variable name to map into HTTPRequest.Latency
localIpstringtemplate variable name to map into HTTPRequest.LocalIP
remoteIpstringtemplate variable name to map into HTTPRequest.RemoteIP
+ + +### MetricInfo +Describes how to represent an Istio metric in Stackdriver. +See https://github.com/googleapis/googleapis/blob/master/google/api/metric.proto + + + + + + + + + + + + + + + + + + + + + + + + + +
FieldTypeDescription
kindMetricKind
valueValueType
bucketsBucketsDefinitionFor metrics with a metric value of DISTRIBUTION, this provides a mechanism for configuring the buckets that will be used to store the aggregated values. This field must be provided for metrics declared to be of type DISTRIBUTION. This field will be ignored for non-distribution metric kinds.
+ + +### BucketsDefinition +Describes buckets for DISTRIBUTION valued metrics. + + + + + + + + + + + + + + + + + + + + + + + + + +
FieldTypeDescription
linearBucketsLinear (oneof )The linear buckets.
exponentialBucketsExponential (oneof )The exponential buckets.
explicitBucketsExplicit (oneof )The explicit buckets.
+ + +### Explicit +Specifies a set of buckets with arbitrary widths. + +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]` + +The `bounds` field must contain at least one element. If `bounds` has +only one element, then there are no finite buckets, and that single +element is the common boundary of the overflow and underflow buckets. + + + + + + + + + + + + + +
FieldTypeDescription
bounds[]repeated doubleThe values must be monotonically increasing.
+ + +### Exponential +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 `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 * (growthFactor ^ i)` +* Lower bound (1 <= i < N): `scale * (growthFactor ^ (i - 1))` + + + + + + + + + + + + + + + + + + + + + + + + + +
FieldTypeDescription
numFiniteBucketsint32Must be greater than 0.
growthFactordoubleMust be greater than 1.
scaledoubleMust be greater than 0.
+ + +### Linear +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 `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))` + + + + + + + + + + + + + + + + + + + + + + + + + +
FieldTypeDescription
numFiniteBucketsint32Must be greater than 0.
widthdoubleMust be greater than 0.
offsetdoubleLower bound of the first bucket.
+ + +## Package google.api + + +### Index + +* [MetricDescriptor](#google.api.MetricDescriptor) +(message) +* [MetricDescriptor.MetricKind](#google.api.MetricDescriptor.MetricKind) +(enum) +* [MetricDescriptor.ValueType](#google.api.MetricDescriptor.ValueType) +(enum) + + +### MetricDescriptor +Defines a metric type and its schema. Once a metric descriptor is created, +deleting or altering it stops data collection and makes the metric type's +existing data unusable. + +NOTE: _No fields in this message type.__ + + +### MetricKind +The kind of measurement. It describes how the data is reported. + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ValueDescription
METRICKINDUNSPECIFIEDDo not use this default value.
GAUGEAn instantaneous measurement of a value.
DELTAThe change in a value during a time interval.
CUMULATIVEA value accumulated over a time interval. Cumulative measurements in a time series should have the same start time and increasing end times, until an event resets the cumulative value to zero and sets a new start time for the following points.
+ + +### ValueType +The value type of a metric. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ValueDescription
VALUETYPEUNSPECIFIEDDo not use this default value.
BOOLThe value is a boolean. This value type can be used only if the metric kind is GAUGE.
INT64The value is a signed 64-bit integer.
DOUBLEThe value is a double precision floating point number.
STRINGThe value is a text string. This value type can be used only if the metric kind is GAUGE.
DISTRIBUTIONThe value is a Distribution.
MONEYThe value is money.
diff --git a/_docs/reference/new/adapters/statsd.md b/_docs/reference/new/adapters/statsd.md new file mode 100644 index 0000000000..b9e5d32dfc --- /dev/null +++ b/_docs/reference/new/adapters/statsd.md @@ -0,0 +1,123 @@ +--- +title: statsd Config +overview: Generated documentation for Mixer's statsd Adapter Configuration Schema + +order: 60 + +layout: docs +type: markdown +--- + + + +### Index + +* [Params](#adapter.statsd.config.Params) +(message) +* [Params.MetricInfo](#adapter.statsd.config.Params.MetricInfo) +(message) +* [Params.MetricInfo.Type](#adapter.statsd.config.Params.MetricInfo.Type) +(enum) + + +### Params + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FieldTypeDescription
addressstringAddress of the statsd server, e.g. localhost:8125
prefixstringMetric prefix, do not specify for no prefix
flushDurationDurationFlushDuration controls the maximum amount of time between sending metrics to the statsd collection server. Metrics are reported when either flushBytes is full or flushDuration time has elapsed since the last report.
flushBytesint32Maximum 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.
samplingRatefloatChance that any particular metric is sampled when incremented; can take the range [0, 1], defaults to 1 if unspecified.
metricsrepeated map<string, MetricInfo>Map of metric name -> info. If a metric's name is not in the map then the metric will not be exported to statsd.
+ + +### MetricInfo +Describes how to represent this metric in statsd + + + + + + + + + + + + + + + + + + + +
FieldTypeDescription
typeType
nameTemplatestring

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 actionName-responseCode. The template strings must conform to go's text/template syntax. For the example of actionName-responseCode, we use the template: \{\{.apiMethod\}\}-\{\{.responseCode\}\}

If nameTemplate is the empty string the Istio metric name will be used for statsd metric's name.

+ + +### Type +The type of metric. + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ValueDescription
UNKNOWN
COUNTER
GAUGE
DISTRIBUTION
diff --git a/_docs/reference/new/adapters/stdio.md b/_docs/reference/new/adapters/stdio.md new file mode 100644 index 0000000000..be09a7acab --- /dev/null +++ b/_docs/reference/new/adapters/stdio.md @@ -0,0 +1,104 @@ +--- +title: stdio Config +overview: Generated documentation for Mixer's stdio Adapter Configuration Schema + +order: 70 + +layout: docs +type: markdown +--- + + + +### Index + +* [Params](#adapter.stdio.config.Params) +(message) +* [Params.Level](#adapter.stdio.config.Params.Level) +(enum) +* [Params.Stream](#adapter.stdio.config.Params.Stream) +(enum) + + +### Params + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FieldTypeDescription
logStreamStreamSelects which standard stream to write to for log entries. STDERR is the default Stream.
severityLevelsrepeated map<string, Level>Maps from severity strings as specified in LogEntry instances to the set of levels supported by this adapter.
metricLevelLevelThe level to assign to metrics being output.
outputAsJsonboolWhether to output a console-friendly or json-friendly format
+ + +### Level +Importance level for individual items output by this adapter. + + + + + + + + + + + + + + + + + + + + + + +
ValueDescription
INFO
WARNING
ERROR
+ + +### Stream +Stream is used to select between different log output sinks. + + + + + + + + + + + + + + + + + +
ValueDescription
STDOUT
STDERR
diff --git a/_docs/reference/new/adapters/svcctrl.md b/_docs/reference/new/adapters/svcctrl.md new file mode 100644 index 0000000000..5059413761 --- /dev/null +++ b/_docs/reference/new/adapters/svcctrl.md @@ -0,0 +1,33 @@ +--- +title: svcctrl Config +overview: Generated documentation for Mixer's svcctrl Adapter Configuration Schema + +order: 80 + +layout: docs +type: markdown +--- + + + +### Index + +* [Params](#adapter.svcctrl.config.Params) +(message) + + +### Params + + + + + + + + + + + + + +
FieldTypeDescription
serviceNamestringFully qualified GCP service name.
diff --git a/_docs/reference/new/destination-policies.md b/_docs/reference/new/destination-policies.md new file mode 100644 index 0000000000..abf938c312 --- /dev/null +++ b/_docs/reference/new/destination-policies.md @@ -0,0 +1,1173 @@ +--- +title: Destination Policies +overview: Generated documentation for Istio's Configuration Schemas + +order: 1000 + +layout: docs +type: markdown +--- + + + +### Index + +* [CircuitBreaker](#istio.proxy.v1.config.CircuitBreaker) +(message) +* [CircuitBreaker.SimpleCircuitBreakerPolicy](#istio.proxy.v1.config.CircuitBreaker.SimpleCircuitBreakerPolicy) +(message) +* [DestinationPolicy](#istio.proxy.v1.config.DestinationPolicy) +(message) +* [DestinationWeight](#istio.proxy.v1.config.DestinationWeight) +(message) +* [HTTPFaultInjection](#istio.proxy.v1.config.HTTPFaultInjection) +(message) +* [HTTPFaultInjection.Abort](#istio.proxy.v1.config.HTTPFaultInjection.Abort) +(message) +* [HTTPFaultInjection.Delay](#istio.proxy.v1.config.HTTPFaultInjection.Delay) +(message) +* [HTTPRedirect](#istio.proxy.v1.config.HTTPRedirect) +(message) +* [HTTPRetry](#istio.proxy.v1.config.HTTPRetry) +(message) +* [HTTPRetry.SimpleRetryPolicy](#istio.proxy.v1.config.HTTPRetry.SimpleRetryPolicy) +(message) +* [HTTPRewrite](#istio.proxy.v1.config.HTTPRewrite) +(message) +* [HTTPTimeout](#istio.proxy.v1.config.HTTPTimeout) +(message) +* [HTTPTimeout.SimpleTimeoutPolicy](#istio.proxy.v1.config.HTTPTimeout.SimpleTimeoutPolicy) +(message) +* [IstioService](#istio.proxy.v1.config.IstioService) +(message) +* [L4FaultInjection](#istio.proxy.v1.config.L4FaultInjection) +(message) +* [L4FaultInjection.Terminate](#istio.proxy.v1.config.L4FaultInjection.Terminate) +(message) +* [L4FaultInjection.Throttle](#istio.proxy.v1.config.L4FaultInjection.Throttle) +(message) +* [L4MatchAttributes](#istio.proxy.v1.config.L4MatchAttributes) +(message) +* [LoadBalancing](#istio.proxy.v1.config.LoadBalancing) +(message) +* [LoadBalancing.SimpleLBPolicy](#istio.proxy.v1.config.LoadBalancing.SimpleLBPolicy) +(enum) +* [MatchCondition](#istio.proxy.v1.config.MatchCondition) +(message) +* [MatchRequest](#istio.proxy.v1.config.MatchRequest) +(message) +* [RouteRule](#istio.proxy.v1.config.RouteRule) +(message) +* [StringMatch](#istio.proxy.v1.config.StringMatch) +(message) + + +### CircuitBreaker +Circuit breaker configuration for Envoy. The circuit breaker +implementation is fine-grained in that it tracks the success/failure +rates of individual hosts in the load balancing pool. Hosts that +continually return errors for API calls are ejected from the pool for a +pre-defined period of time. +See Envoy's +[circuit breaker](https://envoyproxy.github.io/envoy/intro/archOverview/circuitBreaking.html) +and [outlier detection](https://envoyproxy.github.io/envoy/intro/archOverview/outlier.html) +for more details. + + + + + + + + + + + + + +
FieldTypeDescription
simpleCbSimpleCircuitBreakerPolicy
+ + +### SimpleCircuitBreakerPolicy +A simple circuit breaker can be set based on a number of criteria such as +connection and request limits. For example, the following destination +policy sets a limit of 100 connections to "reviews" service version +"v1" backends. + + + metadata: + name: reviews-cb-policy + namespace: default + spec: + destination: + name: reviews + labels: + version: v1 + circuitBreaker: + simpleCb: + maxConnections: 100 + + +The following destination policy sets a limit of 100 connections and +1000 concurrent requests, with no more than 10 req/connection to +"reviews" service version "v1" backends. In addition, it configures +hosts to be scanned every 5 mins, such that any host that fails 7 +consecutive times with 5XX error code will be ejected for 15 minutes. + + + metadata: + name: reviews-cb-policy + namespace: default + spec: + destination: + name: reviews + labels: + version: v1 + circuitBreaker: + simpleCb: + maxConnections: 100 + httpMaxRequests: 1000 + httpMaxRequestsPerConnection: 10 + httpConsecutiveErrors: 7 + sleepWindow: 15m + httpDetectionInterval: 5m + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FieldTypeDescription
maxConnectionsint32Maximum number of connections to a backend.
httpMaxPendingRequestsint32Maximum number of pending requests to a backend. Default 1024
httpMaxRequestsint32Maximum number of requests to a backend. Default 1024
sleepWindowDurationMinimum time the circuit will be closed. format: 1h/1m/1s/1ms. MUST BE >=1ms. Default is 30s.
httpConsecutiveErrorsint32Number of 5XX errors before circuit is opened. Defaults to 5.
httpDetectionIntervalDurationTime interval between ejection sweep analysis. format: 1h/1m/1s/1ms. MUST BE >=1ms. Default is 10s.
httpMaxRequestsPerConnectionint32Maximum number of requests per connection to a backend. Setting this parameter to 1 disables keep alive.
httpMaxEjectionPercentint32Maximum % of hosts in the load balancing pool for the destination service that can be ejected by the circuit breaker. Defaults to 10%.
+ + +### DestinationPolicy +DestinationPolicy defines client/caller-side policies that determine how +to handle traffic bound to a particular destination service. The policy +specifies configuration for load balancing and circuit breakers. For +example, a simple load balancing policy for the ratings service would +look as follows: + + + metadata: + name: ratings-lb-policy + namespace: default # optional (default is "default") + spec: + destination: + name: ratings + loadBalancing: + name: ROUNDROBIN + + +The FQDN of the destination service is composed from the destination name and meta namespace fields, along with +a platform-specific domain suffix +(e.g. on Kubernetes, "reviews" + "default" + "svc.cluster.local" -> "reviews.default.svc.cluster.local"). + +A destination policy can be restricted to a particular version of a +service or applied to all versions. It can also be restricted to calls from +a particular source. For example, the following load balancing policy +applies to version v1 of the ratings service running in the prod +environment but only when called from version v2 of the reviews service: + + + metadata: + name: ratings-lb-policy + namespace: default + spec: + source: + name: reviews + labels: + version: v2 + destination: + name: ratings + labels: + env: prod + version: v1 + loadBalancing: + name: ROUNDROBIN + + +*Note:* Destination policies will be applied only if the corresponding +tagged instances are explicity routed to. In other words, for every +destination policy defined, at least one route rule must refer to the +service version indicated in the destination policy. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FieldTypeDescription
destinationIstioServiceOptional: Destination uniquely identifies the destination service associated with this policy.
sourceIstioServiceOptional: Source uniquely identifies the source service associated with this policy.
loadBalancingLoadBalancingLoad balancing policy.
circuitBreakerCircuitBreakerCircuit breaker policy.
customAny
+ + +### DestinationWeight +Each routing rule is associated with one or more service versions (see +glossary in beginning of document). Weights associated with the version +determine the proportion of traffic it receives. For example, the +following rule will route 25% of traffic for the "reviews" service to +instances with the "v2" tag and the remaining traffic (i.e., 75%) to +"v1". + + + metadata: + name: my-rule + namespace: default + spec: + destination: + name: reviews + route: + - labels: + version: v2 + weight: 25 + - labels: + version: v1 + weight: 75 + + + + + + + + + + + + + + + + + + + + + + + + + +
FieldTypeDescription
destinationIstioServiceOptional destination uniquely identifies the destination service. If not specified, the value is inherited from the parent route rule.
labelsrepeated map<string, string>Service version identifier for the destination service.
weightint32REQUIRED. The proportion of traffic to be forwarded to the service version. (0-100). Sum of weights across destinations SHOULD BE == 100. If there is only destination in a rule, the weight value is assumed to be 100.
+ + +### HTTPFaultInjection +HTTPFaultInjection can be used to specify one or more faults to inject +while forwarding http requests to the destination specified in the route +rule. Fault specification is part of a route rule. Faults include +aborting the Http request from downstream service, and/or delaying +proxying of requests. A fault rule MUST HAVE delay or abort or both. + +*Note:* Delay and abort faults are independent of one another, even if +both are specified simultaneously. + + + + + + + + + + + + + + + + + + + +
FieldTypeDescription
delayDelayDelay requests before forwarding, emulating various failures such as network issues, overloaded upstream service, etc.
abortAbortAbort Http request attempts and return error codes back to downstream service, giving the impression that the upstream service is faulty.
+ + +### Abort +Abort specification is used to prematurely abort a request with a +pre-specified error code. The following example will return an HTTP +400 error code for 10% of the requests to the "ratings" service "v1". + + + metadata: + name: my-rule + spec: + destination: + name: reviews + route: + - labels: + version: v1 + httpFault: + abort: + percent: 10 + httpStatus: 400 + + +The HttpStatus_ field is used to indicate the HTTP status code to +return to the caller. The optional Percent_ field, a value between 0 +and 100, is used to only abort a certain percentage of requests. If +not specified, all requests are aborted. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FieldTypeDescription
percentfloatpercentage of requests to be aborted with the error code provided (0-100).
overrideHeaderNamestring
grpcStatusstring (oneof )
http2Errorstring (oneof )
httpStatusint32 (oneof )REQUIRED. HTTP status code to use to abort the Http request.
+ + +### Delay +Delay specification is used to inject latency into the request +forwarding path. The following example will introduce a 5 second delay +in 10% of the requests to the "v1" version of the "reviews" +service. + + + metadata: + name: my-rule + spec: + destination: + name: reviews + route: + - labels: + version: v1 + httpFault: + delay: + percent: 10 + fixedDelay: 5s + + +The FixedDelay_ field is used to indicate the amount of delay in +seconds. An optional Percent_ field, a value between 0 and 100, can +be used to only delay a certain percentage of requests. If left +unspecified, all request will be delayed. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FieldTypeDescription
percentfloatpercentage of requests on which the delay will be injected (0-100)
overrideHeaderNamestring
fixedDelayDuration (oneof )REQUIRED. Add a fixed delay before forwarding the request. Format: 1h/1m/1s/1ms. MUST be >=1ms.
exponentialDelayDuration (oneof )
+ + +### HTTPRedirect +HTTPRedirect can be used to send a 302 redirect response to the caller, +where the Authority/Host and the URI in the response can be swapped with +the specified values. For example, the following route rule redirects +requests for /v1/getProductRatings API on the ratings service to +/v1/bookRatings provided by the bookratings service. + + + metadata: + name: my-rule + namespace: default + spec: + destination: + name: ratings + match: + request: + headers: + uri: /v1/getProductRatings + redirect: + uri: /v1/bookRatings + authority: bookratings.default.svc.cluster.local + + + + + + + + + + + + + + + + + + + +
FieldTypeDescription
uristringOn a redirect, overwrite the Path portion of the URL with this value. Note that the entire path will be replaced, irrespective of the request URI being matched as an exact path or prefix.
authoritystringOn a redirect, overwrite the Authority/Host portion of the URL with this value
+ + +### HTTPRetry +Describes the retry policy to use when a HTTP request fails. For +example, the following rule sets the maximum number of retries to 3 when +calling ratings:v1 service, with a 2s timeout per retry attempt. + + + metadata: + name: my-rule + namespace: default + spec: + destination: + name: ratings + route: + - labels: + version: v1 + httpReqRetries: + simpleRetry: + attempts: 3 + perTryTimeout: 2s + + + + + + + + + + + + + + + + + + + +
FieldTypeDescription
simpleRetrySimpleRetryPolicy (oneof )
customAny (oneof )
+ + +### SimpleRetryPolicy + + + + + + + + + + + + + + + + + + + + + + + + + +
FieldTypeDescription
attemptsint32REQUIRED. Number of retries for a given request. The interval between retries will be determined automatically (25ms+). Actual number of retries attempted depends on the httpReqTimeout.
perTryTimeoutDurationTimeout per retry attempt for a given request. format: 1h/1m/1s/1ms. MUST BE >=1ms.
overrideHeaderNamestring
+ + +### HTTPRewrite +HTTPRewrite can be used to rewrite specific parts of a HTTP request +before forwarding the request to the destination. Rewrite primitive can +be used only with the DestinationWeights. The following example +demonstrates how to rewrite the URL prefix for api call (/ratings) to +ratings service before making the actual API call. + + + metadata: + name: my-rule + namespace: default + spec: + destination: + name: ratings + match: + request: + headers: + uri: + prefix: /ratings + rewrite: + uri: /v1/bookRatings + route: + - labels: + version: v1 + + + + + + + + + + + + + + + + + + + +
FieldTypeDescription
uristringrewrite the Path (or the prefix) portion of the URI with this value. If the original URI was matched based on prefix, the value provided in this field will replace the corresponding matched prefix.
authoritystringrewrite the Authority/Host header with this value.
+ + +### HTTPTimeout +Describes HTTP request timeout. For example, the following rule sets a +10 second timeout for calls to the ratings:v1 service + + + metadata: + name: my-rule + namespace: default + spec: + destination: + name: ratings + route: + - labels: + version: v1 + httpReqTimeout: + simpleTimeout: + timeout: 10s + + + + + + + + + + + + + + + + + + + +
FieldTypeDescription
simpleTimeoutSimpleTimeoutPolicy (oneof )
customAny (oneof )
+ + +### SimpleTimeoutPolicy + + + + + + + + + + + + + + + + + + + +
FieldTypeDescription
timeoutDurationREQUIRED. Timeout for a HTTP request. Includes retries as well. Default 15s. format: 1h/1m/1s/1ms. MUST BE >=1ms. It is possible to control timeout per request by supplying the timeout value via x-envoy-upstream-rq-timeout-ms HTTP header.
overrideHeaderNamestring
+ + +### IstioService +IstioService identifies a service and optionally service version. +The FQDN of the service is composed from the name, namespace, and implementation-specific domain suffix +(e.g. on Kubernetes, "reviews" + "default" + "svc.cluster.local" -> "reviews.default.svc.cluster.local"). + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FieldTypeDescription
namestringThe short name of the service such as "foo".
namespacestringOptional namespace of the service. Defaults to value of metadata namespace field.
domainstringDomain suffix used to construct the service FQDN in implementations that support such specification.
servicestringThe service FQDN.
labelsrepeated map<string, string>

Optional one or more labels that uniquely identify the service version.

Note: When used for a RouteRule destination, labels MUST be empty.

+ + +### L4FaultInjection + + + + + + + + + + + + + + + + + + + +
FieldTypeDescription
throttleThrottleUnlike Http services, we have very little context for raw Tcp|Udp connections. We could throttle bandwidth of the connections (slow down the connection) and/or abruptly reset (terminate) the Tcp connection after it has been established. We first throttle (if set) and then terminate the connection.
terminateTerminate
+ + +### Terminate +Abruptly reset (terminate) the Tcp connection after it has been +established, emulating remote server crash or link failure. + + + + + + + + + + + + + + + + + + + +
FieldTypeDescription
percentfloatpercentage of established Tcp connections to be terminated/reset
terminateAfterPeriodDuration
+ + +### Throttle +Bandwidth throttling for Tcp and Udp connections + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FieldTypeDescription
percentfloatpercentage of connections to throttle.
downstreamLimitBpsint64bandwidth limit in "bits" per second between downstream and Envoy
upstreamLimitBpsint64bandwidth limits in "bits" per second between Envoy and upstream
throttleForPeriodDurationStop throttling after the given duration. If not set, the connection will be throttled for its lifetime.
throttleAfterPeriodDuration (oneof )Wait a while after the connection is established, before starting bandwidth throttling. This would allow us to inject fault after the application protocol (e.g., MySQL) has had time to establish sessions/whatever handshake necessary.
throttleAfterBytesdouble (oneof )Alternatively, we could wait for a certain number of bytes to be transferred to upstream before throttling the bandwidth.
+ + +### L4MatchAttributes + + + + + + + + + + + + + + + + + + + +
FieldTypeDescription
sourceSubnet[]repeated stringIPv4 or IPv6 ip address with optional subnet. E.g., a.b.c.d/xx form or just a.b.c.d
destinationSubnet[]repeated stringIPv4 or IPv6 ip address of destination with optional subnet. E.g., a.b.c.d/xx form or just a.b.c.d. This is only valid when the destination service has several IPs and the application explicitly specifies a particular IP.
+ + +### LoadBalancing +Load balancing policy to use when forwarding traffic. These policies +directly correlate to [load balancer +types](https://envoyproxy.github.io/envoy/intro/archOverview/loadBalancing.html) +supported by Envoy. Example, + + + metadata: + name: reviews-lb-policy + namespace: default + spec: + destination: + name: reviews + loadBalancing: + name: RANDOM + + + + + + + + + + + + + +
FieldTypeDescription
nameSimpleLBPolicyLoad balancing policy name (as defined in SimpleLBPolicy below)
+ + +### SimpleLBPolicy +Load balancing algorithms supported by Envoy proxy. + + + + + + + + + + + + + + + + + + + + + + +
ValueDescription
ROUNDROBINSimple round robin policy.
LEASTCONNThe least request load balancer uses an O(1) algorithm which selects two random healthy hosts and picks the host which has fewer active requests.
RANDOMThe random load balancer selects a random healthy host. The random load balancer generally performs better than round robin if no health checking policy is configured.
+ + +### MatchCondition +Match condition specifies a set of criterion to be met in order for the +route rule to be applied to the connection or HTTP request. The +condition provides distinct set of conditions for each protocol with the +intention that conditions apply only to the service ports that match the +protocol. For example, the following route rule restricts the rule to +match only requests originating from "reviews:v2", accessing ratings +service where the URL path starts with /ratings/v2/ and the request +contains a "cookie" with value "user=jason", + + + metadata: + name: my-rule + namespace: default + spec: + destination: + name: ratings + match: + source: + name: reviews + labels: + version: v2 + request: + headers: + cookie: + regex: "^(.*?;)?(user=jason)(;.*)?" + uri: + prefix: "/ratings/v2/" + + +MatchCondition CANNOT be empty. At least one source or +request header must be specified. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FieldTypeDescription
sourceIstioServiceIdentifies the service initiating a connection or a request.
tcpL4MatchAttributes
udpL4MatchAttributes
requestMatchRequestAttributes of an HTTP request to match.
+ + +### MatchRequest +MatchRequest specifies the attributes of an HTTP request to be used for matching a request. + + + + + + + + + + + + + +
FieldTypeDescription
headersrepeated map<string, StringMatch>

Set of HTTP match conditions based on HTTP/1.1, HTTP/2, GRPC request metadata, such as uri, scheme, authority. The header keys must be lowercase and use hyphen as the separator, e.g. x-request-id.

Header values are case-sensitive and formatted as follows:

exact: "value" or just "value" for exact string match

prefix: "value" for prefix-based match

regex: "value" for ECMAscript style regex-based match

Note 1: The keys uri, scheme, method, and authority correspond to URI, protocol scheme (e.g., HTTP, HTTPS), HTTP method (e.g., GET, POST), and the HTTP Host header respectively.

Note 2: uri can be used to perform URL matches. For all HTTP headers including uri, exact, prefix and ECMA style regular expression matches are supported.

+ + +### RouteRule + + +#### Glossary & concepts +*Service* is a unit of an application with a unique name that other services +use to refer to the functionality being called. Service instances are +pods/VMs/containers that implement the service. + +*Service versions* - In a continuous deployment scenario, for a given service, +there can be multiple sets of instances running potentially different +variants of the application binary. These variants are not necessarily +different API versions. They could be iterative changes to the same service, +deployed in different environments (prod, staging, dev, etc.). Common +scenarios where this occurs include A/B testing, canary rollouts, etc. The +choice of a particular version can be decided based on various criterion +(headers, url, etc.) and/or by weights assigned to each version. Each +service has a default version consisting of all its instances. + +*Source* - downstream client (browser or another service) calling the +Envoy proxy/sidecar (typically to reach another service). + +*Destination* - The remote upstream service to which the Envoy proxy/sidecar is +talking to, on behalf of the source service. There can be one or more +service versions for a given service (see the discussion on versions above). +Envoy would choose the version based on various routing rules. + +*Access model* - Applications address only the destination service +without knowledge of individual service versions. The actual choice of +the version is determined by Envoy, enabling the application code to +decouple itself from the evolution of dependent services. + + + +Route rule provides a custom routing policy based on the source and +destination service versions and connection/request metadata. The rule +must provide a set of conditions for each protocol (TCP, UDP, HTTP) that +the destination service exposes on its ports. + +The rule applies only to the ports on the destination service for which +it provides protocol-specific match condition, e.g. if the rule does not +specify TCP condition, the rule does not apply to TCP traffic towards +the destination service. + +For example, a simple rule to send 100% of incoming traffic for a +"reviews" service to version "v1" can be specified as follows: + + + metadata: + name: my-rule + namespace: default # optional (default is "default") + spec: + destination: + name: reviews + namespace: my-namespace # optional (default is metadata namespace field) + route: + - labels: + version: v1 + weight: 100 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FieldTypeDescription
destinationIstioService

REQUIRED: Destination uniquely identifies the destination associated with this routing rule. This field is applicable for hostname-based resolution for HTTP traffic as well as IP-based resolution for TCP/UDP traffic.

Note: The route rule destination specification represents all version of the service and therefore the IstioService's labels field MUST be empty.

precedenceint32RECOMMENDED. Precedence is used to disambiguate the order of application of rules for the same destination service. A higher number takes priority. If not specified, the value is assumed to be 0. The order of application for rules with the same precedence is unspecified.
matchMatchConditionMatch condtions to be satisfied for the route rule to be activated. If match is omitted, the route rule applies only to HTTP traffic.
route[]repeated DestinationWeightREQUIRED (route|redirect). A routing rule can either redirect traffic or forward traffic. The forwarding target can be one of several versions of a service (see glossary in beginning of document). Weights associated with the service version determine the proportion of traffic it receives.
redirectHTTPRedirectREQUIRED (route|redirect). A routing rule can either redirect traffic or forward traffic. The redirect primitive can be used to send a HTTP 302 redirect to a different URI or Authority.
rewriteHTTPRewriteRewrite HTTP URIs and Authority headers. Rewrite cannot be used with Redirect primitive. Rewrite will be performed before forwarding.
websocketUpgradeboolIndicates that a HTTP/1.1 client connection to this particular route should be allowed (and expected) to upgrade to a WebSocket connection. The default is false. Envoy expects the first request to this route to contain the WebSocket upgrade headers. Otherwise, the request will be rejected.
httpReqTimeoutHTTPTimeoutTimeout policy for HTTP requests.
httpReqRetriesHTTPRetryRetry policy for HTTP requests.
httpFaultHTTPFaultInjectionFault injection policy to apply on HTTP traffic
l4FaultL4FaultInjection
+ + +### StringMatch +Describes how to match a given string in HTTP headers. Match is case-sensitive. + + + + + + + + + + + + + + + + + + + + + + + + + +
FieldTypeDescription
exactstring (oneof )exact string match
prefixstring (oneof )prefix-based match
regexstring (oneof )ECMAscript style regex-based match
diff --git a/_docs/reference/new/egress-rules.md b/_docs/reference/new/egress-rules.md new file mode 100644 index 0000000000..dd51ca9a49 --- /dev/null +++ b/_docs/reference/new/egress-rules.md @@ -0,0 +1,969 @@ +--- +title: Egress Rules +overview: Generated documentation for Istio's Configuration Schemas + +order: 1010 + +layout: docs +type: markdown +--- + + + +### Index + +* [DestinationWeight](#istio.proxy.v1.config.DestinationWeight) +(message) +* [EgressRule](#istio.proxy.v1.config.EgressRule) +(message) +* [EgressRule.Port](#istio.proxy.v1.config.EgressRule.Port) +(message) +* [HTTPFaultInjection](#istio.proxy.v1.config.HTTPFaultInjection) +(message) +* [HTTPFaultInjection.Abort](#istio.proxy.v1.config.HTTPFaultInjection.Abort) +(message) +* [HTTPFaultInjection.Delay](#istio.proxy.v1.config.HTTPFaultInjection.Delay) +(message) +* [HTTPRedirect](#istio.proxy.v1.config.HTTPRedirect) +(message) +* [HTTPRetry](#istio.proxy.v1.config.HTTPRetry) +(message) +* [HTTPRetry.SimpleRetryPolicy](#istio.proxy.v1.config.HTTPRetry.SimpleRetryPolicy) +(message) +* [HTTPRewrite](#istio.proxy.v1.config.HTTPRewrite) +(message) +* [HTTPTimeout](#istio.proxy.v1.config.HTTPTimeout) +(message) +* [HTTPTimeout.SimpleTimeoutPolicy](#istio.proxy.v1.config.HTTPTimeout.SimpleTimeoutPolicy) +(message) +* [IstioService](#istio.proxy.v1.config.IstioService) +(message) +* [L4FaultInjection](#istio.proxy.v1.config.L4FaultInjection) +(message) +* [L4FaultInjection.Terminate](#istio.proxy.v1.config.L4FaultInjection.Terminate) +(message) +* [L4FaultInjection.Throttle](#istio.proxy.v1.config.L4FaultInjection.Throttle) +(message) +* [L4MatchAttributes](#istio.proxy.v1.config.L4MatchAttributes) +(message) +* [MatchCondition](#istio.proxy.v1.config.MatchCondition) +(message) +* [MatchRequest](#istio.proxy.v1.config.MatchRequest) +(message) +* [RouteRule](#istio.proxy.v1.config.RouteRule) +(message) +* [StringMatch](#istio.proxy.v1.config.StringMatch) +(message) + + +### DestinationWeight +Each routing rule is associated with one or more service versions (see +glossary in beginning of document). Weights associated with the version +determine the proportion of traffic it receives. For example, the +following rule will route 25% of traffic for the "reviews" service to +instances with the "v2" tag and the remaining traffic (i.e., 75%) to +"v1". + + + metadata: + name: my-rule + namespace: default + spec: + destination: + name: reviews + route: + - labels: + version: v2 + weight: 25 + - labels: + version: v1 + weight: 75 + + + + + + + + + + + + + + + + + + + + + + + + + +
FieldTypeDescription
destinationIstioServiceOptional destination uniquely identifies the destination service. If not specified, the value is inherited from the parent route rule.
labelsrepeated map<string, string>Service version identifier for the destination service.
weightint32REQUIRED. The proportion of traffic to be forwarded to the service version. (0-100). Sum of weights across destinations SHOULD BE == 100. If there is only destination in a rule, the weight value is assumed to be 100.
+ + +### EgressRule +Egress rules describe the properties of a service outside Istio. When transparent proxying +is used, egress rules signify a white listed set of domains that microserves in the mesh +are allowed to access. A subset of routing rules and all destination policies can be applied +on the service targeted by an egress rule. The destination of an egress rule is allowed to +contain wildcards (e.g., *.foo.com). Currently, only HTTP-based services can be expressed +through the egress rule. If TLS origination from the sidecar is desired, the protocol +associated with the service port must be marked as HTTPS, and the service is expected to +be accessed over HTTP (e.g., http://gmail.com:443). The sidecar will automatically upgrade +the connection to TLS when initiating a connection with the external service. + +For example, the following egress rule describes the set of services hosted under the *.foo.com domain + + + kind: EgressRule + metadata: + name: foo-egress-rule + spec: + destination: + service: *.foo.com + ports: + - port: 80 + protocol: http + - port: 443 + protocol: https + + + + + + + + + + + + + + + + + + + + + + + + + +
FieldTypeDescription
destinationIstioServiceREQUIRED: Hostname or a wildcard domain name associated with the external service. ONLY the "service" field of destination will be taken into consideration. Name, namespace, domain and labels are ignored. Routing rules and destination policies that refer to these external services must have identical specification for the destination as the corresponding egress rule. Wildcard domain specifications must conform to format allowed by Envoy's Virtual Host specification, such as “*.foo.com” or “*-bar.foo.com”. The character '*' in a domain specification indicates a non-empty string. Hence, a wildcard domain of form “*-bar.foo.com” will match “baz-bar.foo.com” but not “-bar.foo.com”.
ports[]repeated PortREQUIRED: list of ports on which the external service is available.
useEgressProxybool

Forward all the external traffic through a dedicated egress proxy. It is used in some scenarios where there is a requirement that all the external traffic goes through special dedicated nodes/pods. These dedicated egress nodes could then be more closely monitored for security vulnerabilities.

The default is false, i.e. the sidecar forwards external traffic directly to the external service.

+ + +### Port +Port describes the properties of a specific TCP port of an external service. + + + + + + + + + + + + + + + + + + + +
FieldTypeDescription
portint32A valid non-negative integer port number.
protocolstringThe protocol to communicate with the external services. MUST BE one of HTTP|HTTPS|GRPC|HTTP2.
+ + +### HTTPFaultInjection +HTTPFaultInjection can be used to specify one or more faults to inject +while forwarding http requests to the destination specified in the route +rule. Fault specification is part of a route rule. Faults include +aborting the Http request from downstream service, and/or delaying +proxying of requests. A fault rule MUST HAVE delay or abort or both. + +*Note:* Delay and abort faults are independent of one another, even if +both are specified simultaneously. + + + + + + + + + + + + + + + + + + + +
FieldTypeDescription
delayDelayDelay requests before forwarding, emulating various failures such as network issues, overloaded upstream service, etc.
abortAbortAbort Http request attempts and return error codes back to downstream service, giving the impression that the upstream service is faulty.
+ + +### Abort +Abort specification is used to prematurely abort a request with a +pre-specified error code. The following example will return an HTTP +400 error code for 10% of the requests to the "ratings" service "v1". + + + metadata: + name: my-rule + spec: + destination: + name: reviews + route: + - labels: + version: v1 + httpFault: + abort: + percent: 10 + httpStatus: 400 + + +The HttpStatus_ field is used to indicate the HTTP status code to +return to the caller. The optional Percent_ field, a value between 0 +and 100, is used to only abort a certain percentage of requests. If +not specified, all requests are aborted. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FieldTypeDescription
percentfloatpercentage of requests to be aborted with the error code provided (0-100).
overrideHeaderNamestring
grpcStatusstring (oneof )
http2Errorstring (oneof )
httpStatusint32 (oneof )REQUIRED. HTTP status code to use to abort the Http request.
+ + +### Delay +Delay specification is used to inject latency into the request +forwarding path. The following example will introduce a 5 second delay +in 10% of the requests to the "v1" version of the "reviews" +service. + + + metadata: + name: my-rule + spec: + destination: + name: reviews + route: + - labels: + version: v1 + httpFault: + delay: + percent: 10 + fixedDelay: 5s + + +The FixedDelay_ field is used to indicate the amount of delay in +seconds. An optional Percent_ field, a value between 0 and 100, can +be used to only delay a certain percentage of requests. If left +unspecified, all request will be delayed. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FieldTypeDescription
percentfloatpercentage of requests on which the delay will be injected (0-100)
overrideHeaderNamestring
fixedDelayDuration (oneof )REQUIRED. Add a fixed delay before forwarding the request. Format: 1h/1m/1s/1ms. MUST be >=1ms.
exponentialDelayDuration (oneof )
+ + +### HTTPRedirect +HTTPRedirect can be used to send a 302 redirect response to the caller, +where the Authority/Host and the URI in the response can be swapped with +the specified values. For example, the following route rule redirects +requests for /v1/getProductRatings API on the ratings service to +/v1/bookRatings provided by the bookratings service. + + + metadata: + name: my-rule + namespace: default + spec: + destination: + name: ratings + match: + request: + headers: + uri: /v1/getProductRatings + redirect: + uri: /v1/bookRatings + authority: bookratings.default.svc.cluster.local + + + + + + + + + + + + + + + + + + + +
FieldTypeDescription
uristringOn a redirect, overwrite the Path portion of the URL with this value. Note that the entire path will be replaced, irrespective of the request URI being matched as an exact path or prefix.
authoritystringOn a redirect, overwrite the Authority/Host portion of the URL with this value
+ + +### HTTPRetry +Describes the retry policy to use when a HTTP request fails. For +example, the following rule sets the maximum number of retries to 3 when +calling ratings:v1 service, with a 2s timeout per retry attempt. + + + metadata: + name: my-rule + namespace: default + spec: + destination: + name: ratings + route: + - labels: + version: v1 + httpReqRetries: + simpleRetry: + attempts: 3 + perTryTimeout: 2s + + + + + + + + + + + + + + + + + + + +
FieldTypeDescription
simpleRetrySimpleRetryPolicy (oneof )
customAny (oneof )
+ + +### SimpleRetryPolicy + + + + + + + + + + + + + + + + + + + + + + + + + +
FieldTypeDescription
attemptsint32REQUIRED. Number of retries for a given request. The interval between retries will be determined automatically (25ms+). Actual number of retries attempted depends on the httpReqTimeout.
perTryTimeoutDurationTimeout per retry attempt for a given request. format: 1h/1m/1s/1ms. MUST BE >=1ms.
overrideHeaderNamestring
+ + +### HTTPRewrite +HTTPRewrite can be used to rewrite specific parts of a HTTP request +before forwarding the request to the destination. Rewrite primitive can +be used only with the DestinationWeights. The following example +demonstrates how to rewrite the URL prefix for api call (/ratings) to +ratings service before making the actual API call. + + + metadata: + name: my-rule + namespace: default + spec: + destination: + name: ratings + match: + request: + headers: + uri: + prefix: /ratings + rewrite: + uri: /v1/bookRatings + route: + - labels: + version: v1 + + + + + + + + + + + + + + + + + + + +
FieldTypeDescription
uristringrewrite the Path (or the prefix) portion of the URI with this value. If the original URI was matched based on prefix, the value provided in this field will replace the corresponding matched prefix.
authoritystringrewrite the Authority/Host header with this value.
+ + +### HTTPTimeout +Describes HTTP request timeout. For example, the following rule sets a +10 second timeout for calls to the ratings:v1 service + + + metadata: + name: my-rule + namespace: default + spec: + destination: + name: ratings + route: + - labels: + version: v1 + httpReqTimeout: + simpleTimeout: + timeout: 10s + + + + + + + + + + + + + + + + + + + +
FieldTypeDescription
simpleTimeoutSimpleTimeoutPolicy (oneof )
customAny (oneof )
+ + +### SimpleTimeoutPolicy + + + + + + + + + + + + + + + + + + + +
FieldTypeDescription
timeoutDurationREQUIRED. Timeout for a HTTP request. Includes retries as well. Default 15s. format: 1h/1m/1s/1ms. MUST BE >=1ms. It is possible to control timeout per request by supplying the timeout value via x-envoy-upstream-rq-timeout-ms HTTP header.
overrideHeaderNamestring
+ + +### IstioService +IstioService identifies a service and optionally service version. +The FQDN of the service is composed from the name, namespace, and implementation-specific domain suffix +(e.g. on Kubernetes, "reviews" + "default" + "svc.cluster.local" -> "reviews.default.svc.cluster.local"). + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FieldTypeDescription
namestringThe short name of the service such as "foo".
namespacestringOptional namespace of the service. Defaults to value of metadata namespace field.
domainstringDomain suffix used to construct the service FQDN in implementations that support such specification.
servicestringThe service FQDN.
labelsrepeated map<string, string>

Optional one or more labels that uniquely identify the service version.

Note: When used for a RouteRule destination, labels MUST be empty.

+ + +### L4FaultInjection + + + + + + + + + + + + + + + + + + + +
FieldTypeDescription
throttleThrottleUnlike Http services, we have very little context for raw Tcp|Udp connections. We could throttle bandwidth of the connections (slow down the connection) and/or abruptly reset (terminate) the Tcp connection after it has been established. We first throttle (if set) and then terminate the connection.
terminateTerminate
+ + +### Terminate +Abruptly reset (terminate) the Tcp connection after it has been +established, emulating remote server crash or link failure. + + + + + + + + + + + + + + + + + + + +
FieldTypeDescription
percentfloatpercentage of established Tcp connections to be terminated/reset
terminateAfterPeriodDuration
+ + +### Throttle +Bandwidth throttling for Tcp and Udp connections + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FieldTypeDescription
percentfloatpercentage of connections to throttle.
downstreamLimitBpsint64bandwidth limit in "bits" per second between downstream and Envoy
upstreamLimitBpsint64bandwidth limits in "bits" per second between Envoy and upstream
throttleForPeriodDurationStop throttling after the given duration. If not set, the connection will be throttled for its lifetime.
throttleAfterPeriodDuration (oneof )Wait a while after the connection is established, before starting bandwidth throttling. This would allow us to inject fault after the application protocol (e.g., MySQL) has had time to establish sessions/whatever handshake necessary.
throttleAfterBytesdouble (oneof )Alternatively, we could wait for a certain number of bytes to be transferred to upstream before throttling the bandwidth.
+ + +### L4MatchAttributes + + + + + + + + + + + + + + + + + + + +
FieldTypeDescription
sourceSubnet[]repeated stringIPv4 or IPv6 ip address with optional subnet. E.g., a.b.c.d/xx form or just a.b.c.d
destinationSubnet[]repeated stringIPv4 or IPv6 ip address of destination with optional subnet. E.g., a.b.c.d/xx form or just a.b.c.d. This is only valid when the destination service has several IPs and the application explicitly specifies a particular IP.
+ + +### MatchCondition +Match condition specifies a set of criterion to be met in order for the +route rule to be applied to the connection or HTTP request. The +condition provides distinct set of conditions for each protocol with the +intention that conditions apply only to the service ports that match the +protocol. For example, the following route rule restricts the rule to +match only requests originating from "reviews:v2", accessing ratings +service where the URL path starts with /ratings/v2/ and the request +contains a "cookie" with value "user=jason", + + + metadata: + name: my-rule + namespace: default + spec: + destination: + name: ratings + match: + source: + name: reviews + labels: + version: v2 + request: + headers: + cookie: + regex: "^(.*?;)?(user=jason)(;.*)?" + uri: + prefix: "/ratings/v2/" + + +MatchCondition CANNOT be empty. At least one source or +request header must be specified. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FieldTypeDescription
sourceIstioServiceIdentifies the service initiating a connection or a request.
tcpL4MatchAttributes
udpL4MatchAttributes
requestMatchRequestAttributes of an HTTP request to match.
+ + +### MatchRequest +MatchRequest specifies the attributes of an HTTP request to be used for matching a request. + + + + + + + + + + + + + +
FieldTypeDescription
headersrepeated map<string, StringMatch>

Set of HTTP match conditions based on HTTP/1.1, HTTP/2, GRPC request metadata, such as uri, scheme, authority. The header keys must be lowercase and use hyphen as the separator, e.g. x-request-id.

Header values are case-sensitive and formatted as follows:

exact: "value" or just "value" for exact string match

prefix: "value" for prefix-based match

regex: "value" for ECMAscript style regex-based match

Note 1: The keys uri, scheme, method, and authority correspond to URI, protocol scheme (e.g., HTTP, HTTPS), HTTP method (e.g., GET, POST), and the HTTP Host header respectively.

Note 2: uri can be used to perform URL matches. For all HTTP headers including uri, exact, prefix and ECMA style regular expression matches are supported.

+ + +### RouteRule + + +#### Glossary & concepts +*Service* is a unit of an application with a unique name that other services +use to refer to the functionality being called. Service instances are +pods/VMs/containers that implement the service. + +*Service versions* - In a continuous deployment scenario, for a given service, +there can be multiple sets of instances running potentially different +variants of the application binary. These variants are not necessarily +different API versions. They could be iterative changes to the same service, +deployed in different environments (prod, staging, dev, etc.). Common +scenarios where this occurs include A/B testing, canary rollouts, etc. The +choice of a particular version can be decided based on various criterion +(headers, url, etc.) and/or by weights assigned to each version. Each +service has a default version consisting of all its instances. + +*Source* - downstream client (browser or another service) calling the +Envoy proxy/sidecar (typically to reach another service). + +*Destination* - The remote upstream service to which the Envoy proxy/sidecar is +talking to, on behalf of the source service. There can be one or more +service versions for a given service (see the discussion on versions above). +Envoy would choose the version based on various routing rules. + +*Access model* - Applications address only the destination service +without knowledge of individual service versions. The actual choice of +the version is determined by Envoy, enabling the application code to +decouple itself from the evolution of dependent services. + + + +Route rule provides a custom routing policy based on the source and +destination service versions and connection/request metadata. The rule +must provide a set of conditions for each protocol (TCP, UDP, HTTP) that +the destination service exposes on its ports. + +The rule applies only to the ports on the destination service for which +it provides protocol-specific match condition, e.g. if the rule does not +specify TCP condition, the rule does not apply to TCP traffic towards +the destination service. + +For example, a simple rule to send 100% of incoming traffic for a +"reviews" service to version "v1" can be specified as follows: + + + metadata: + name: my-rule + namespace: default # optional (default is "default") + spec: + destination: + name: reviews + namespace: my-namespace # optional (default is metadata namespace field) + route: + - labels: + version: v1 + weight: 100 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FieldTypeDescription
destinationIstioService

REQUIRED: Destination uniquely identifies the destination associated with this routing rule. This field is applicable for hostname-based resolution for HTTP traffic as well as IP-based resolution for TCP/UDP traffic.

Note: The route rule destination specification represents all version of the service and therefore the IstioService's labels field MUST be empty.

precedenceint32RECOMMENDED. Precedence is used to disambiguate the order of application of rules for the same destination service. A higher number takes priority. If not specified, the value is assumed to be 0. The order of application for rules with the same precedence is unspecified.
matchMatchConditionMatch condtions to be satisfied for the route rule to be activated. If match is omitted, the route rule applies only to HTTP traffic.
route[]repeated DestinationWeightREQUIRED (route|redirect). A routing rule can either redirect traffic or forward traffic. The forwarding target can be one of several versions of a service (see glossary in beginning of document). Weights associated with the service version determine the proportion of traffic it receives.
redirectHTTPRedirectREQUIRED (route|redirect). A routing rule can either redirect traffic or forward traffic. The redirect primitive can be used to send a HTTP 302 redirect to a different URI or Authority.
rewriteHTTPRewriteRewrite HTTP URIs and Authority headers. Rewrite cannot be used with Redirect primitive. Rewrite will be performed before forwarding.
websocketUpgradeboolIndicates that a HTTP/1.1 client connection to this particular route should be allowed (and expected) to upgrade to a WebSocket connection. The default is false. Envoy expects the first request to this route to contain the WebSocket upgrade headers. Otherwise, the request will be rejected.
httpReqTimeoutHTTPTimeoutTimeout policy for HTTP requests.
httpReqRetriesHTTPRetryRetry policy for HTTP requests.
httpFaultHTTPFaultInjectionFault injection policy to apply on HTTP traffic
l4FaultL4FaultInjection
+ + +### StringMatch +Describes how to match a given string in HTTP headers. Match is case-sensitive. + + + + + + + + + + + + + + + + + + + + + + + + + +
FieldTypeDescription
exactstring (oneof )exact string match
prefixstring (oneof )prefix-based match
regexstring (oneof )ECMAscript style regex-based match
diff --git a/_docs/reference/new/fault-injection.md b/_docs/reference/new/fault-injection.md new file mode 100644 index 0000000000..895bf2feb3 --- /dev/null +++ b/_docs/reference/new/fault-injection.md @@ -0,0 +1,144 @@ +--- +title: Fault Injection +overview: Generated documentation for Istio's Configuration Schemas + +order: 1020 + +layout: docs +type: markdown +--- + + + +### Index + +* [HTTPFaultInjection](#istio.proxy.v1.config.HTTPFaultInjection) +(message) +* [HTTPFaultInjection.Abort](#istio.proxy.v1.config.HTTPFaultInjection.Abort) +(message) +* [HTTPFaultInjection.Delay](#istio.proxy.v1.config.HTTPFaultInjection.Delay) +(message) + + +### HTTPFaultInjection +HTTPFaultInjection can be used to specify one or more faults to inject +while forwarding http requests to the destination specified in the route +rule. Fault specification is part of a route rule. Faults include +aborting the Http request from downstream service, and/or delaying +proxying of requests. A fault rule MUST HAVE delay or abort or both. + +*Note:* Delay and abort faults are independent of one another, even if +both are specified simultaneously. + + + + + + + + + + + + + + + + + + + +
FieldTypeDescription
delayDelayDelay requests before forwarding, emulating various failures such as network issues, overloaded upstream service, etc.
abortAbortAbort Http request attempts and return error codes back to downstream service, giving the impression that the upstream service is faulty.
+ + +### Abort +Abort specification is used to prematurely abort a request with a +pre-specified error code. The following example will return an HTTP +400 error code for 10% of the requests to the "ratings" service "v1". + + + metadata: + name: my-rule + spec: + destination: + name: reviews + route: + - labels: + version: v1 + httpFault: + abort: + percent: 10 + httpStatus: 400 + + +The HttpStatus_ field is used to indicate the HTTP status code to +return to the caller. The optional Percent_ field, a value between 0 +and 100, is used to only abort a certain percentage of requests. If +not specified, all requests are aborted. + + + + + + + + + + + + + + + + + + + +
FieldTypeDescription
percentfloatpercentage of requests to be aborted with the error code provided (0-100).
httpStatusint32REQUIRED. HTTP status code to use to abort the Http request.
+ + +### Delay +Delay specification is used to inject latency into the request +forwarding path. The following example will introduce a 5 second delay +in 10% of the requests to the "v1" version of the "reviews" +service. + + + metadata: + name: my-rule + spec: + destination: + name: reviews + route: + - labels: + version: v1 + httpFault: + delay: + percent: 10 + fixedDelay: 5s + + +The FixedDelay_ field is used to indicate the amount of delay in +seconds. An optional Percent_ field, a value between 0 and 100, can +be used to only delay a certain percentage of requests. If left +unspecified, all request will be delayed. + + + + + + + + + + + + + + + + + + + +
FieldTypeDescription
percentfloatpercentage of requests on which the delay will be injected (0-100)
fixedDelayDurationREQUIRED. Add a fixed delay before forwarding the request. Format: 1h/1m/1s/1ms. MUST be >=1ms.
diff --git a/_docs/reference/new/manager-config.md b/_docs/reference/new/manager-config.md new file mode 100644 index 0000000000..72098b40ee --- /dev/null +++ b/_docs/reference/new/manager-config.md @@ -0,0 +1,250 @@ +--- +title: Manager +overview: Generated documentation for Istio's Configuration Schemas + +order: 1030 + +layout: docs +type: markdown +--- + + + +### Index + +* [MeshConfig](#istio.proxy.v1.config.MeshConfig) +(message) +* [MeshConfig.AuthPolicy](#istio.proxy.v1.config.MeshConfig.AuthPolicy) +(enum) +* [MeshConfig.IngressControllerMode](#istio.proxy.v1.config.MeshConfig.IngressControllerMode) +(enum) +* [ProxyConfig](#istio.proxy.v1.config.ProxyConfig) +(message) + + +### MeshConfig +MeshConfig defines mesh-wide variables shared by all Envoy instances in the +Istio service mesh. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FieldTypeDescription
egressProxyAddressstringAddress of the egress Envoy service (e.g. istio-egress:80).
mixerAddressstringAddress of the mixer service (e.g. istio-mixer:9090). Empty value disables Mixer checks and telemetry.
disablePolicyChecksboolDisable policy checks by the mixer service. Metrics will still be reported to the mixer for HTTP requests and TCP connections. Default is false, i.e. mixer policy check is enabled by default.
proxyListenPortint32Port on which Envoy should listen for incoming connections from other services.
proxyHttpPortint32Port on which Envoy should listen for HTTP PROXY requests if set.
connectTimeoutDurationConnection timeout used by Envoy. (MUST BE >=1ms)
ingressClassstringClass of ingress resources to be processed by Istio ingress controller. This corresponds to the value of "kubernetes.io/ingress.class" annotation.
ingressServicestringName of the kubernetes service used for the istio ingress controller.
ingressControllerModeIngressControllerModeDefines whether to use Istio ingress controller for annotated or all ingress resources.
authPolicyAuthPolicyAuthentication policy defines the global switch to control authentication for Envoy-to-Envoy communication.
rdsRefreshDelayDurationPolling interval for RDS (MUST BE >=1ms)
enableTracingboolFlag to control generation of trace spans and request IDs. Requires a trace span collector defined in the proxy configuration.
accessLogFilestringFile address for the proxy access log (e.g. /dev/stdout). Empty value disables access logging.
defaultConfigProxyConfigDefault proxy config used by the proxy injection mechanism operating in the mesh (e.g. Kubernetes admission controller) In case of Kubernetes, the proxy config is applied once during the injection process, and remain constant for the duration of the pod. The rest of the mesh config can be changed at runtime and config gets distributed dynamically.
+ + +### AuthPolicy + + + + + + + + + + + + + + + + + +
ValueDescription
NONEDo not encrypt Envoy to Envoy traffic.
MUTUALTLSEnvoy to Envoy traffic is wrapped into mutual TLS connections.
+ + +### IngressControllerMode + + + + + + + + + + + + + + + + + + + + + + +
ValueDescription
OFFDisables Istio ingress controller.
DEFAULTIstio ingress controller will act on ingress resources that do not contain any annotation or whose annotations match the value specified in the ingressClass parameter described earlier. Use this mode if Istio ingress controller will be the default ingress controller for the entire kubernetes cluster.
STRICTIstio ingress controller will only act on ingress resources whose annotations match the value specified in the ingressClass parameter described earlier. Use this mode if Istio ingress controller will be a secondary ingress controller (e.g., in addition to a cloud-provided ingress controller).
+ + +### ProxyConfig +ProxyConfig defines variables for individual Envoy instances. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FieldTypeDescription
configPathstringPath to the generated configuration file directory. Proxy agent generates the actual configuration and stores it in this directory.
binaryPathstringPath to the proxy binary
serviceClusterstring

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

Since Istio does not assign a local service/service version to each Envoy instance, the name is same for all of them. However, the source/caller's identity (e.g., IP address) is encoded in the --service-node flag when launching Envoy. When the RDS service receives API calls from Envoy, it uses the value of the service-node flag to compute routes that are relative to the service instances located at that IP address.

drainDurationDurationThe time in seconds that Envoy will drain connections during a hot restart. MUST be >=1s (e.g., 1s/1m/1h)
parentShutdownDurationDurationThe time in seconds that Envoy will wait before shutting down the parent process during a hot restart. MUST be >=1s (e.g., 1s/1m/1h). MUST BE greater than drainDuration parameter.
discoveryAddressstringAddress of the discovery service exposing xDS (e.g. istio-pilot:8080).
discoveryRefreshDelayDurationPolling interval for service discovery (used by EDS, CDS, LDS, but not RDS). (MUST BE >=1ms)
zipkinAddressstringAddress of the Zipkin service (e.g. zipkin:9411).
connectTimeoutDurationConnection timeout used by Envoy for supporting services. (MUST BE >=1ms)
statsdUdpAddressstringIP Address and Port of a statsd UDP listener (e.g. 10.75.241.127:9125).
proxyAdminPortint32Port on which Envoy should listen for administrative commands.
availabilityZonestringThe availability zone where this Envoy instance is running. When running Envoy as a sidecar in Kubernetes, this flag must be one of the availability zones assigned to a node using failure-domain.beta.kubernetes.io/zone annotation.
diff --git a/_docs/reference/new/mixer-config.md b/_docs/reference/new/mixer-config.md new file mode 100644 index 0000000000..671f05e80d --- /dev/null +++ b/_docs/reference/new/mixer-config.md @@ -0,0 +1,1240 @@ +--- +title: Mixer +overview: Generated documentation for Mixer's Configuration Schema + +order: 1130 + +layout: docs +type: markdown +--- + + + +### Index + +* [Action](#istio.mixer.v1.config.Action) +(message) +* [Adapter](#istio.mixer.v1.config.Adapter) +(message) +* [Aspect](#istio.mixer.v1.config.Aspect) +(message) +* [AspectRule](#istio.mixer.v1.config.AspectRule) +(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) +(deprecated) +* [Handler](#istio.mixer.v1.config.Handler) +(message) +* [Instance](#istio.mixer.v1.config.Instance) +(message) +* [IpAddress](#istio.mixer.v1.config.IpAddress) +(message) +* [Rule](#istio.mixer.v1.config.Rule) +(message) +* [ServiceConfig](#istio.mixer.v1.config.ServiceConfig) +(message) +(deprecated) +* [Uri](#istio.mixer.v1.config.Uri) +(message) + + +### Action +Action describes which [Handler](#istio.mixer.v1.config.Handler) to invoke and what data to pass to it for processing. + +The following example instructs Mixer to invoke 'prometheus-handler' handler and pass it the object +constructed using the instance 'RequestCountByService' + + +```yaml + handler: prometheus-handler + instances: + - RequestCountByService +``` + + + + + + + + + + + + + + + + + + + +
FieldTypeDescription
handlerstringRequired. Fully qualified name of the handler to invoke. Must match the name of a Handler.
instances[]repeated stringRequired. Each value must match the fully qualified name of the Instances. Referenced instances are evaluated by resolving the attributes/literals for all the fields. The constructed objects are then passed to the handler referenced within this action.
+ + +### Adapter +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: +``` + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FieldTypeDescription
namestringRequired. must be unique per kind. Used by Aspect 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 kind is used to execute the intention described by the AspectRules.
kindstringRequired. The aspect this implementation with these params will implement; a single adapter implementation may implement many aspects, but an Adapter entry is required per kind.
implstringRequired. The name of a specific adapter implementation. An adapter's implementation name is typically a constant in its code.
paramsStructOptional. depends on adapter implementation. Struct representation of a proto defined by the implementation; this varies depending on impl.
+ + +### Aspect +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 following example instructs Mixer to populate a metric named "responseTime" +that was declared to have three labels: srcConsumerId, dstResponseStatusCode, +and dstServiceName. For each label and the metric's `value` we provide +an expression over Istio's attributes. Mixer evaluates these expressions for +each request. + + +```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 + dstResponseStatusCode: response.code + dstServiceName: destination.service +``` + + + + + + + + + + + + + + + + + + + + + + + + + +
FieldTypeDescription
kindstringRequired. The kind of aspect this intent is targeting.
adapterstringOptional. The name of the adapter this Aspect targets. If no name is provided, Mixer will use the adapter of the target kind named "default".
paramsStructRequired. Struct representation of a proto defined by each aspect kind.
+ + +### AspectRule +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. + + + + + + + + + + + + + + + + + + + + + + + + + +
FieldTypeDescription
selectorstring

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.

A few example selectors:

+
    +
  • an empty selector evaluates to true
    • +
  • true, a boolean literal; a rule with this selector will always be executed
    • +
  • destination.service == ratings* selects any request targeting a service whose name starts with "ratings"
    • +
  • attr1 == "20" && attr2 == "30" logical AND, OR, and NOT are also available
    • +
aspects[]repeated AspectThe aspects that apply when selector evaluates to true.
rules[]repeated AspectRuleNested aspect rules; their selectors are evaluated if this selector predicate evaluates to true.
+ + +### AttributeManifest +AttributeManifest describes a set of Attributes produced by some component +of an Istio deployment. + + + + + + + + + + + + + + + + + + + + + + + + + +
FieldTypeDescription
revisionstringOptional. The revision of this document. Assigned by server.
namestringRequired. Name of the component producing these attributes. This can be the proxy (with the canonical name "istio-proxy") or the name of an attributes kind adapter in Mixer.
attributesrepeated map<string, AttributeInfo>

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:

+
Name = IDENT { SEPARATOR IDENT };
+

Where IDENT must match the regular expression [a-z][a-z0-9]+ and SEPARATOR must match the regular expression [\.-].

Attribute names must be unique within a single Istio deployment. The set of canonical attributes are described at https://istio.io/docs/reference/attribute-vocabulary.html. Attributes not in that list should be named with a component-specific suffix such as request.count-my.component

+ + +### AttributeInfo +AttributeInfo describes the schema of an Istio `Attribute`. + + + + +#### 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. + + + + +#### 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. + + + + +#### 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. + + + + + + + + + + + + + + + + + + + +
FieldTypeDescription
descriptionstringOptional. A human-readable description of the attribute's purpose.
valueTypeValueTypeRequired. The type of data carried by this attribute.
+ + +### DnsName +DnsName holds a valid domain name. + + + + + + + + + + + + + +
FieldTypeDescription
valuestring
+ + +### EmailAddress +EmailAddress holds a properly formatted email address. + + + + + + + + + + + + + +
FieldTypeDescription
valuestring
+ + +### GlobalConfig + +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. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FieldTypeDescription
revisionstringOptional.
adapters[]repeated Adapter
manifests[]repeated AttributeManifest
logs[]repeated LogEntryDescriptor
metrics[]repeated MetricDescriptor
monitoredResources[]repeated MonitoredResourceDescriptor
principals[]repeated PrincipalDescriptor
quotas[]repeated QuotaDescriptor
handlers[]repeated HandlerUnder development, DO NOT USE Optional. List of handlers that can be referenced from actions
+ + +### Handler +Handler allows the operator to configure a specific adapter implementation. +Each adapter implementation defines its own `params` proto. + +In the following example we define a `metrics` handler using the Mixer's prepackaged +prometheus adapter. This handler doesn't require any parameters. + + +```yaml +name: prometheus-handler +adapter: prometheus +params: +``` + + + + + + + + + + + + + + + + + + + + + + + + + +
FieldTypeDescription
namestringRequired. Must be unique in the entire mixer configuration. Used by Actions to refer to this handler.
adapterstringRequired. The name of a specific adapter implementation. An adapter's implementation name is typically a constant in its code.
paramsStructOptional. Depends on adapter implementation. Struct representation of a proto defined by the adapter implementation; this varies depending on the value of field adapter.
+ + +### Instance +A Instance tells Mixer how to create instances for particular template. + +Instance is defined by the operator. Instance is defined relative to a known +template. Their purpose is to tell Mixer how to use attributes or literals to produce +instances of the specified template at runtime. + +The following example instructs Mixer to construct an instance associated with template +'istio.mixer.adapter.metric.Metric'. It provides a mapping from the template's fields to expressions. +Instances produced with this instance can be referenced by [Actions](#istio.mixer.v1.config.Action) using name +'RequestCountByService'. + + +```yaml +- name: RequestCountByService + template: istio.mixer.adapter.metric.Metric + params: + value: 1 + dimensions: + source: source.service + destinationIp: destination.ip +``` + + + + + + + + + + + + + + + + + + + + + + + + + +
FieldTypeDescription
namestring

Required. The name of this instance

Must be unique amongst other Instances in scope. Used by Action to refer to an instance produced by this instance.

templatestringRequired. The name of the template this instance creates instances for. The value must match the name of the available template in scope.
paramsStructRequired. Depends on referenced template. Struct representation of a proto defined by the template; this varies depending on the value of field template.
+ + +### IpAddress +IpAddress holds an IPv4 or IPv6 address. + + + + + + + + + + + + + +
FieldTypeDescription
valuebytes
+ + +### Rule +A Rule is a selector and a set of intentions to be executed when the +selector is `true` + +The following example instructs Mixer to invoke 'prometheus-handler' handler for all services and pass it the +instance constructed using the 'RequestCountByService' instance. + + +```yaml +- match: destination.service == "*" + actions: + - handler: prometheus-handler + instances: + - RequestCountByService +``` + + + + + + + + + + + + + + + + + + + +
FieldTypeDescription
matchstring

Required. Match is an attribute based predicate. When Mixer receives a request it evaluates the match expression and executes all the associated actions if the match evaluates to true.

A few example match:

+
    +
  • an empty match evaluates to true
    • +
  • true, a boolean literal; a rule with this match will always be executed
    • +
  • destination.service == ratings* selects any request targeting a service whose name starts with "ratings"
    • +
  • attr1 == "20" && attr2 == "30" logical AND, OR, and NOT are also available
    • +
actions[]repeated ActionOptional. The actions that will be executed when match evaluates to true.
+ + +### ServiceConfig + +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: + + +```yaml +subject: "namespace:ns1" +revision: "1011" +rules: +- selector: destination.service == "*" + aspects: + - kind: metrics + params: + metrics: # defines metric collection across the board. + - descriptorName: responseTimeByStatusCode + value: response.time + labels: + statusCode: response.code + +actionRules: +- selector: destination.service == "*" + actions: + - handler: prometheus-handler + instances: + - RequestCountByService + +handlers: +- name: prometheus-handler + adapter: prometheus + params: + +instances: +- name: RequestCountByService + template: istio.mixer.adapter.metric.Metric + params: + value: 1 + dimensions: + source: source.service + destinationIp: destination.ip +``` + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FieldTypeDescription
subjectstringOptional. Subject is unique for a config type. 2 config with the same subject will overwrite each other
revisionstringOptional. revision of this config. This is assigned by the server
rules[]
(deprecated)		repeated AspectRuleThis item is deprecated!
instances[]repeated InstanceUnder development, DO NOT USE Optional. List of instances that can be referenced from actions
actionRules[]repeated RuleUnder development, DO NOT USE Optional. List of actions that apply for this service
+ + +### Uri +Uri represents a properly formed URI. + + + + + + + + + + + + + +
FieldTypeDescription
valuestring
+ + +## Package istio.mixer.v1.config.descriptor + + +### Index + +* [LogEntryDescriptor](#istio.mixer.v1.config.descriptor.LogEntryDescriptor) +(message) +* [LogEntryDescriptor.PayloadFormat](#istio.mixer.v1.config.descriptor.LogEntryDescriptor.PayloadFormat) +(enum) +* [MetricDescriptor](#istio.mixer.v1.config.descriptor.MetricDescriptor) +(message) +* [MetricDescriptor.BucketsDefinition](#istio.mixer.v1.config.descriptor.MetricDescriptor.BucketsDefinition) +(message) +* [MetricDescriptor.BucketsDefinition.Explicit](#istio.mixer.v1.config.descriptor.MetricDescriptor.BucketsDefinition.Explicit) +(message) +* [MetricDescriptor.BucketsDefinition.Exponential](#istio.mixer.v1.config.descriptor.MetricDescriptor.BucketsDefinition.Exponential) +(message) +* [MetricDescriptor.BucketsDefinition.Linear](#istio.mixer.v1.config.descriptor.MetricDescriptor.BucketsDefinition.Linear) +(message) +* [MetricDescriptor.MetricKind](#istio.mixer.v1.config.descriptor.MetricDescriptor.MetricKind) +(enum) +* [MonitoredResourceDescriptor](#istio.mixer.v1.config.descriptor.MonitoredResourceDescriptor) +(message) +* [PrincipalDescriptor](#istio.mixer.v1.config.descriptor.PrincipalDescriptor) +(message) +* [QuotaDescriptor](#istio.mixer.v1.config.descriptor.QuotaDescriptor) +(message) +* [ValueType](#istio.mixer.v1.config.descriptor.ValueType) +(enum) + + +### LogEntryDescriptor +Defines the format of a single log entry. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FieldTypeDescription
namestringRequired. The name of this descriptor.
displayNamestringOptional. A concise name for the log entry type, which can be displayed in user interfaces. Use sentence case without an ending period, for example "access log".
descriptionstringOptional. A description of the log entry type, which can be used in documentation.
payloadFormatPayloadFormatRequired. Format of the value of the payload attribute.
logTemplatestring

Required. The template that will be populated with labels at runtime to generate a log message; the labels describe the parameters for this template.

The template strings must conform to go's text/template syntax.

labelsrepeated map<string, ValueType>Labels describe the parameters of this log's template string. The log definition allows the user to map attribute expressions to actual values for these labels at run time; the result of the evaluation must be of the type described by the kind for each label.
+ + +### PayloadFormat +PayloadFormat details the currently supported logging payload formats. +TEXT is the default payload format. + + + + + + + + + + + + + + + + + + + + + + +
ValueDescription
PAYLOADFORMATUNSPECIFIEDInvalid, default value.
TEXTIndicates a payload format of raw text.
JSONIndicates that the payload is a serialized JSON object.
+ + +### 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. + +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: + + +```yaml +metrics: + name: "responseCount" + kind: COUNTER + value: INT64 + labels: + apiMethod: STRING + responseCode: 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 +metric: + descriptor: "responseCount" # 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 +``` + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FieldTypeDescription
namestringRequired. The name of this descriptor. This is used to refer to this descriptor in other contexts.
displayNamestringOptional. A concise name for the metric, which can be displayed in user interfaces. Use sentence case without an ending period, for example "Request count".
descriptionstringOptional. A description of the metric, which should be used as the documentation for the metric.
kindMetricKindRequired. Whether the metric records instantaneous values, changes to a value, etc.
valueValueTypeRequired. The type of data this metric records.
labelsrepeated map<string, ValueType>Labels that dimension the data recorded by this metric. The metric definition allows the user to map attribute expressions to actual values for these labels at run time; the result of the evaluation must be of the type described by the kind for each label.
bucketsBucketsDefinitionFor metrics with a metric kind of DISTRIBUTION, this provides a mechanism for configuring the buckets that will be used to store the aggregated values. This field must be provided for metrics declared to be of type DISTRIBUTION. This field will be ignored for non-distribution metric kinds.
+ + +### BucketsDefinition + + + + + + + + + + + + + + + + + + + + + + + + + +
FieldTypeDescription
linearBucketsLinear (oneof )The linear buckets.
exponentialBucketsExponential (oneof )The exponential buckets.
explicitBucketsExplicit (oneof )The explicit buckets.
+ + +### Explicit +Specifies a set of buckets with arbitrary widths. + +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]` + +The `bounds` field must contain at least one element. If `bounds` has +only one element, then there are no finite buckets, and that single +element is the common boundary of the overflow and underflow buckets. + + + + + + + + + + + + + +
FieldTypeDescription
bounds[]repeated doubleThe values must be monotonically increasing.
+ + +### Exponential +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 `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 * (growthFactor ^ i)` +* Lower bound (1 <= i < N): `scale * (growthFactor ^ (i - 1))` + + + + + + + + + + + + + + + + + + + + + + + + + +
FieldTypeDescription
numFiniteBucketsint32Must be greater than 0.
growthFactordoubleMust be greater than 1.
scaledoubleMust be greater than 0.
+ + +### Linear +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 `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))` + + + + + + + + + + + + + + + + + + + + + + + + + +
FieldTypeDescription
numFiniteBucketsint32Must be greater than 0.
widthdoubleMust be greater than 0.
offsetdoubleLower bound of the first bucket.
+ + +### MetricKind +The kind of measurement. It describes how the data is recorded. + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ValueDescription
METRICKINDUNSPECIFIEDDo not use this default value.
GAUGEAn instantaneous measurement of a value. For example, the number of VMs.
COUNTERA count of occurrences over an interval, always a positive integer. For example, the number of API requests.
DISTRIBUTION

Summary statistics for a population of values. At the moment, only histograms representing the distribution of those values across a set of buckets are supported (configured via the buckets field).

Values for DISTRIBUTIONs will be reported in singular form. It will be up to the mixer adapters and backend systems to transform single reported values into the distribution form as needed (and as supported).

+ + +### MonitoredResourceDescriptor +An object that describes the schema of a `MonitoredResource`. A +`MonitoredResource` is used to define a type of resources for +monitoring purpose. For example, the monitored resource "VM" refers +to virtual machines, which requires 3 attributes "owner", "zone", +"name" to uniquely identify a specific instance. When reporting +a metric against a monitored resource, the metric attributes will +be used to associate the right value with the right instance, +such as memory usage of a VM. + + + + + + + + + + + + + + + + + + + + + + + + + +
FieldTypeDescription
namestringRequired. The name of this descriptor.
descriptionstringOptional. A detailed description of the monitored resource descriptor that might be used in documentation.
labelsrepeated map<string, ValueType>Labels represent the dimensions that uniquely identify this monitored resource. At runtime expressions will be evaluated to provide values for each label. Label names are mapped to expressions as part of aspect configuration.
+ + +### PrincipalDescriptor +Defines a a security principal. + +A principal is described by a set of attributes. + + + + + + + + + + + + + + + + + + + +
FieldTypeDescription
namestringRequired. The name of this descriptor.
labelsrepeated map<string, ValueType>Labels represent the dimensions that uniquely identify this security principal. At runtime expressions will be evaluated to provide values for each label. Label names are mapped to expressions as part of aspect configuration.
+ + +### QuotaDescriptor +Configuration state for a particular quota. + +Quotas are similar to metrics, except that they are mutated through method +calls and there are limits on the allowed values. +The descriptor below lets you define a quota and indicate the maximum +amount values of this quota are allowed to hold. + +A given quota is described by a set of attributes. These attributes represent +the different dimensions to associate with the quota. A given quota holds a +unique value for potentially any combination of these attributes. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FieldTypeDescription
namestringRequired. The name of this descriptor.
displayNamestringOptional. A concise name for the quota which can be displayed in user interfaces.
descriptionstringOptional. A description of the quota which can be used in documentation.
labelsrepeated map<string, ValueType>The set of labels that are necessary to describe a specific value cell for a quota of this type.
rateLimitboolIndicates whether the quota represents a rate limit or represents a resource quota.
+ + +### 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. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ValueDescription
VALUETYPEUNSPECIFIEDInvalid, default value.
STRINGAn undiscriminated variable-length string.
INT64An undiscriminated 64-bit signed integer.
DOUBLEAn undiscriminated 64-bit floating-point value.
BOOLAn undiscriminated boolean value.
TIMESTAMPA point in time.
IPADDRESSAn IP address.
EMAILADDRESSAn email address.
URIA URI.
DNSNAMEA DNS name.
DURATIONA span between two points in time.
STRINGMAPA map string -> string, typically used by headers.
diff --git a/_docs/reference/new/mixer-service.md b/_docs/reference/new/mixer-service.md new file mode 100644 index 0000000000..4f59f7a754 --- /dev/null +++ b/_docs/reference/new/mixer-service.md @@ -0,0 +1,566 @@ +--- +title: Mixer Service +overview: Generated documentation for Mixer's API Surface + +order: 1140 + +layout: docs +type: markdown +--- + + + +### Index + +* [Status](/docs/reference/api/status.html) +(message) + + +### 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 + + + + +#### 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. + + + + +#### 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. + + + + +#### 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. + + + + + + + + + + + + + + + + + + + + + + + + + +
FieldTypeDescription
codeint32The status code, which should be an enum value of google.rpc.Code.
messagestringA developer-facing error message, which should be in English. Any user-facing error message should be localized and sent in the google.rpc.Status.details field, or localized by the client.
details[]repeated AnyA list of messages that carry the error details. There is a common set of message types for APIs to use.
+ + +## Package istio.mixer.v1 + + +### Index +* [Mixer](#istio.mixer.v1.Mixer) (interface) +* [Attributes](#istio.mixer.v1.Attributes) +(message) +* [CheckRequest](#istio.mixer.v1.CheckRequest) +(message) +* [CheckRequest.QuotaParams](#istio.mixer.v1.CheckRequest.QuotaParams) +(message) +* [CheckResponse](#istio.mixer.v1.CheckResponse) +(message) +* [CheckResponse.PreconditionResult](#istio.mixer.v1.CheckResponse.PreconditionResult) +(message) +* [CheckResponse.QuotaResult](#istio.mixer.v1.CheckResponse.QuotaResult) +(message) +* [ReferencedAttributes](#istio.mixer.v1.ReferencedAttributes) +(message) +* [ReferencedAttributes.AttributeMatch](#istio.mixer.v1.ReferencedAttributes.AttributeMatch) +(message) +* [ReferencedAttributes.Condition](#istio.mixer.v1.ReferencedAttributes.Condition) +(enum) +* [ReportRequest](#istio.mixer.v1.ReportRequest) +(message) +* [ReportResponse](#istio.mixer.v1.ReportResponse) +(message) +* [StringMap](#istio.mixer.v1.StringMap) +(message) + + +### Mixer +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. + +- *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. + +- *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. + + +#### Check + + rpc Check([CheckRequest](#istio.mixer.v1.CheckRequest)) returns ([CheckResponse](#istio.mixer.v1.CheckResponse)) + +Checks preconditions and allocate quota before performing an operation. +The preconditions enforced depend on the set of supplied attributes and +the active configuration. + + +#### Report + + rpc Report([ReportRequest](#istio.mixer.v1.ReportRequest)) returns ([ReportResponse](#istio.mixer.v1.ReportResponse)) + +Reports telemetry, such as logs and metrics. +The reported information depends on the set of supplied attributes and the +active configuration. + + +### Attributes +Attributes represents a set of typed name/value pairs. Many of Mixer's +API either consume and/or return attributes. + +Istio uses attributes to control the runtime behavior of services running in the service mesh. +Attributes are named and typed pieces of metadata describing ingress and egress traffic and the +environment this traffic occurs in. An Istio attribute carries a specific piece +of information such as the error code of an API request, the latency of an API request, or the +original IP address of a TCP connection. For example: + + +``` +request.path: xyz/abc +request.size: 234 +request.time: 12:34:56.789 04/17/2017 +source.ip: 192.168.0.1 +target.service: example +``` + + +A given Istio deployment has a fixed vocabulary of attributes that it understands. +The specific vocabulary is determined by the set of attribute producers being used +in the deployment. The primary attribute producer in Istio is Envoy, although +specialized Mixer adapters and services can also generate attributes. + +The common baseline set of attributes available in most Istio deployments is defined +[here](https://istio.io/docs/reference/config/mixer/attribute-vocabulary.html). + +Attributes are strongly typed. The supported attribute types are defined by +[ValueType](https://github.com/istio/api/blob/master/mixer/v1/config/descriptor/valueType.proto). +Each type of value is encoded into one of the so-called transport types present +in this message. + +Within this message, strings are referenced using integer indices into +one of two string dictionaries. Positive integers index into the global +deployment-wide dictionary, whereas negative integers index into the message-level +dictionary instead. The message-level dictionary is carried by the +`words` field of this message, the deployment-wide dictionary is determined via +configuration. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FieldTypeDescription
words[]repeated stringThe message-level dictionary.
stringsrepeated map<sint32, sint32>Attribute payload. All sint32 values represent indices into one of the word dictionaries. Positive values are indices into the global deployment-wide dictionary, negative values are indices into the message-level dictionary.
int64srepeated map<sint32, int64>
doublesrepeated map<sint32, double>
boolsrepeated map<sint32, bool>
timestampsrepeated map<sint32, Timestamp>
durationsrepeated map<sint32, Duration>
bytesrepeated map<sint32, bytes>
stringMapsrepeated map<sint32, StringMap>
+ + +### CheckRequest +Used to get a thumbs-up/thumbs-down before performing an action. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FieldTypeDescription
attributesAttributes

The attributes to use for this request.

Mixer's configuration determines how these attributes are used to establish the result returned in the response.

globalWordCountuint32The number of words in the global dictionary, used with to populate the attributes. This value is used as a quick way to determine whether the client is using a dictionary that the server understands.
deduplicationIdstringUsed for deduplicating Check 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 call.
quotasrepeated map<string, QuotaParams>The individual quotas to allocate
+ + +### QuotaParams +parameters for a quota allocation + + + + + + + + + + + + + + + + + + + +
FieldTypeDescription
amountint64Amount of quota to allocate
bestEffortboolWhen true, supports returning less quota than what was requested.
+ + +### CheckResponse + + + + + + + + + + + + + + + + + + + +
FieldTypeDescription
preconditionPreconditionResultThe precondition check results.
quotasrepeated map<string, QuotaResult>The resulting quota, one entry per requested quota.
+ + +### PreconditionResult + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FieldTypeDescription
statusStatusA status code of OK indicates all preconditions were satisfied. Any other code indicates not all preconditions were satisfied and details describe why.
validDurationDurationThe amount of time for which this result can be considered valid.
validUseCountint32The number of uses for which this result can be considered valid.
attributesAttributes

The attributes returned by Mixer.

The exact set of attributes returned is determined by the set of adapters Mixer is configured with. These attributes are used to ferry new attributes that Mixer derived based on the input set of attributes and its configuration.

referencedAttributesReferencedAttributesThe total set of attributes that were used in producing the result along with matching conditions.
+ + +### QuotaResult + + + + + + + + + + + + + + + + + + + + + + + + + +
FieldTypeDescription
validDurationDurationThe amount of time for which this result can be considered valid.
grantedAmountint64The amount of granted quota. When QuotaParams.bestEffort is true, this will be >= 0. If QuotaParams.bestEffort is false, this will be either 0 or >= QuotaParams.amount.
referencedAttributesReferencedAttributesThe total set of attributes that were used in producing the result along with matching conditions.
+ + +### ReferencedAttributes +Describes the attributes that were used to determine the response. +This can be used to construct a response cache. + + + + + + + + + + + + + + + + + + + +
FieldTypeDescription
words[]repeated stringThe message-level dictionary. Refer to Attributes for information on using dictionaries.
attributeMatches[]repeated AttributeMatchDescribes a set of attributes.
+ + +### AttributeMatch + + + + + + + + + + + + + + + + + + + + + + + + + +
FieldTypeDescription
namesint32The name of the attribute. This is a dictionary index encoded in a manner identical to all strings in the Attributes message.
conditionConditionThe kind of match against the attribute value.
regexstringThe matching regex in the case of condition = REGEX
+ + +### Condition +How an attribute's value was matched + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ValueDescription
CONDITIONUNSPECIFIEDshould not occur
ABSENCEmatch when attribute doesn't exist
EXACTmatch when attribute value is an exact byte-for-byte match
REGEXmatch when attribute value matches the included regex
+ + +### ReportRequest +Used to report telemetry after performing one or more actions. + + + + + + + + + + + + + + + + + + + + + + + + + +
FieldTypeDescription
attributes[]repeated Attributes

The attributes to use for this request.

Each Attributes element represents the state of a single action. Multiple actions can be provided in a single message in order to improve communication efficiency. The client can accumulate a set of actions and send them all in one single message.

Although each Attributes message is semantically treated as an independent stand-alone entity unrelated to the other attributes within the message, this message format leverages delta-encoding between attribute messages in order to substantially reduce the request size and improve end-to-end efficiency. Each individual set of attributes is used to modify the previous set. This eliminates the need to redundantly send the same attributes multiple times over within a single request.

If a client is not sophisticated and doesn't want to use delta-encoding, a degenerate case is to include all attributes in every individual message.

defaultWords[]repeated string

The default message-level dictionary for all the attributes. Individual attribute messages can have their own dictionaries, but if they don't then this set of words, if it is provided, is used instead.

This makes it possible to share the same dictionary for all attributes in this request, which can substantially reduce the overall request size.

globalWordCountuint32The number of words in the global dictionary. To detect global dictionary out of sync between client and server.
+ + +### ReportResponse + +NOTE: _No fields in this message type.__ + + +### StringMap +A map of string to string. The keys and values in this map are dictionary +indices (see the [Attributes](#istio.mixer.v1.Attributes) message for an explanation) + + + + + + + + + + + + + +
FieldTypeDescription
entriesrepeated map<sint32, sint32>
diff --git a/_docs/reference/new/routing-rules.md b/_docs/reference/new/routing-rules.md new file mode 100644 index 0000000000..af6308144a --- /dev/null +++ b/_docs/reference/new/routing-rules.md @@ -0,0 +1,689 @@ +--- +title: Routing Rules +overview: Generated documentation for Istio's Configuration Schemas + +order: 1210 + +layout: docs +type: markdown +--- + + + +### Index + +* [DestinationWeight](#istio.proxy.v1.config.DestinationWeight) +(message) +* [HTTPFaultInjection](#istio.proxy.v1.config.HTTPFaultInjection) +(message) +* [HTTPFaultInjection.Abort](#istio.proxy.v1.config.HTTPFaultInjection.Abort) +(message) +* [HTTPFaultInjection.Delay](#istio.proxy.v1.config.HTTPFaultInjection.Delay) +(message) +* [HTTPRedirect](#istio.proxy.v1.config.HTTPRedirect) +(message) +* [HTTPRetry](#istio.proxy.v1.config.HTTPRetry) +(message) +* [HTTPRetry.SimpleRetryPolicy](#istio.proxy.v1.config.HTTPRetry.SimpleRetryPolicy) +(message) +* [HTTPRewrite](#istio.proxy.v1.config.HTTPRewrite) +(message) +* [HTTPTimeout](#istio.proxy.v1.config.HTTPTimeout) +(message) +* [HTTPTimeout.SimpleTimeoutPolicy](#istio.proxy.v1.config.HTTPTimeout.SimpleTimeoutPolicy) +(message) +* [IstioService](#istio.proxy.v1.config.IstioService) +(message) +* [MatchCondition](#istio.proxy.v1.config.MatchCondition) +(message) +* [MatchRequest](#istio.proxy.v1.config.MatchRequest) +(message) +* [RouteRule](#istio.proxy.v1.config.RouteRule) +(message) +* [StringMatch](#istio.proxy.v1.config.StringMatch) +(message) + + +### DestinationWeight +Each routing rule is associated with one or more service versions (see +glossary in beginning of document). Weights associated with the version +determine the proportion of traffic it receives. For example, the +following rule will route 25% of traffic for the "reviews" service to +instances with the "v2" tag and the remaining traffic (i.e., 75%) to +"v1". + + + metadata: + name: my-rule + namespace: default + spec: + destination: + name: reviews + route: + - labels: + version: v2 + weight: 25 + - labels: + version: v1 + weight: 75 + + + + + + + + + + + + + + + + + + + + + + + + + +
FieldTypeDescription
destinationIstioServiceOptional destination uniquely identifies the destination service. If not specified, the value is inherited from the parent route rule.
labelsrepeated map<string, string>Service version identifier for the destination service.
weightint32REQUIRED. The proportion of traffic to be forwarded to the service version. (0-100). Sum of weights across destinations SHOULD BE == 100. If there is only destination in a rule, the weight value is assumed to be 100.
+ + +### HTTPFaultInjection +HTTPFaultInjection can be used to specify one or more faults to inject +while forwarding http requests to the destination specified in the route +rule. Fault specification is part of a route rule. Faults include +aborting the Http request from downstream service, and/or delaying +proxying of requests. A fault rule MUST HAVE delay or abort or both. + +*Note:* Delay and abort faults are independent of one another, even if +both are specified simultaneously. + + + + + + + + + + + + + + + + + + + +
FieldTypeDescription
delayDelayDelay requests before forwarding, emulating various failures such as network issues, overloaded upstream service, etc.
abortAbortAbort Http request attempts and return error codes back to downstream service, giving the impression that the upstream service is faulty.
+ + +### Abort +Abort specification is used to prematurely abort a request with a +pre-specified error code. The following example will return an HTTP +400 error code for 10% of the requests to the "ratings" service "v1". + + + metadata: + name: my-rule + spec: + destination: + name: reviews + route: + - labels: + version: v1 + httpFault: + abort: + percent: 10 + httpStatus: 400 + + +The HttpStatus_ field is used to indicate the HTTP status code to +return to the caller. The optional Percent_ field, a value between 0 +and 100, is used to only abort a certain percentage of requests. If +not specified, all requests are aborted. + + + + + + + + + + + + + + + + + + + +
FieldTypeDescription
percentfloatpercentage of requests to be aborted with the error code provided (0-100).
httpStatusint32REQUIRED. HTTP status code to use to abort the Http request.
+ + +### Delay +Delay specification is used to inject latency into the request +forwarding path. The following example will introduce a 5 second delay +in 10% of the requests to the "v1" version of the "reviews" +service. + + + metadata: + name: my-rule + spec: + destination: + name: reviews + route: + - labels: + version: v1 + httpFault: + delay: + percent: 10 + fixedDelay: 5s + + +The FixedDelay_ field is used to indicate the amount of delay in +seconds. An optional Percent_ field, a value between 0 and 100, can +be used to only delay a certain percentage of requests. If left +unspecified, all request will be delayed. + + + + + + + + + + + + + + + + + + + +
FieldTypeDescription
percentfloatpercentage of requests on which the delay will be injected (0-100)
fixedDelayDurationREQUIRED. Add a fixed delay before forwarding the request. Format: 1h/1m/1s/1ms. MUST be >=1ms.
+ + +### HTTPRedirect +HTTPRedirect can be used to send a 302 redirect response to the caller, +where the Authority/Host and the URI in the response can be swapped with +the specified values. For example, the following route rule redirects +requests for /v1/getProductRatings API on the ratings service to +/v1/bookRatings provided by the bookratings service. + + + metadata: + name: my-rule + namespace: default + spec: + destination: + name: ratings + match: + request: + headers: + uri: /v1/getProductRatings + redirect: + uri: /v1/bookRatings + authority: bookratings.default.svc.cluster.local + + + + + + + + + + + + + + + + + + + +
FieldTypeDescription
uristringOn a redirect, overwrite the Path portion of the URL with this value. Note that the entire path will be replaced, irrespective of the request URI being matched as an exact path or prefix.
authoritystringOn a redirect, overwrite the Authority/Host portion of the URL with this value
+ + +### HTTPRetry +Describes the retry policy to use when a HTTP request fails. For +example, the following rule sets the maximum number of retries to 3 when +calling ratings:v1 service, with a 2s timeout per retry attempt. + + + metadata: + name: my-rule + namespace: default + spec: + destination: + name: ratings + route: + - labels: + version: v1 + httpReqRetries: + simpleRetry: + attempts: 3 + perTryTimeout: 2s + + + + + + + + + + + + + +
FieldTypeDescription
simpleRetrySimpleRetryPolicy
+ + +### SimpleRetryPolicy + + + + + + + + + + + + + + + + + + + +
FieldTypeDescription
attemptsint32REQUIRED. Number of retries for a given request. The interval between retries will be determined automatically (25ms+). Actual number of retries attempted depends on the httpReqTimeout.
perTryTimeoutDurationTimeout per retry attempt for a given request. format: 1h/1m/1s/1ms. MUST BE >=1ms.
+ + +### HTTPRewrite +HTTPRewrite can be used to rewrite specific parts of a HTTP request +before forwarding the request to the destination. Rewrite primitive can +be used only with the DestinationWeights. The following example +demonstrates how to rewrite the URL prefix for api call (/ratings) to +ratings service before making the actual API call. + + + metadata: + name: my-rule + namespace: default + spec: + destination: + name: ratings + match: + request: + headers: + uri: + prefix: /ratings + rewrite: + uri: /v1/bookRatings + route: + - labels: + version: v1 + + + + + + + + + + + + + + + + + + + +
FieldTypeDescription
uristringrewrite the Path (or the prefix) portion of the URI with this value. If the original URI was matched based on prefix, the value provided in this field will replace the corresponding matched prefix.
authoritystringrewrite the Authority/Host header with this value.
+ + +### HTTPTimeout +Describes HTTP request timeout. For example, the following rule sets a +10 second timeout for calls to the ratings:v1 service + + + metadata: + name: my-rule + namespace: default + spec: + destination: + name: ratings + route: + - labels: + version: v1 + httpReqTimeout: + simpleTimeout: + timeout: 10s + + + + + + + + + + + + + +
FieldTypeDescription
simpleTimeoutSimpleTimeoutPolicy
+ + +### SimpleTimeoutPolicy + + + + + + + + + + + + + +
FieldTypeDescription
timeoutDurationREQUIRED. Timeout for a HTTP request. Includes retries as well. Default 15s. format: 1h/1m/1s/1ms. MUST BE >=1ms. It is possible to control timeout per request by supplying the timeout value via x-envoy-upstream-rq-timeout-ms HTTP header.
+ + +### IstioService +IstioService identifies a service and optionally service version. +The FQDN of the service is composed from the name, namespace, and implementation-specific domain suffix +(e.g. on Kubernetes, "reviews" + "default" + "svc.cluster.local" -> "reviews.default.svc.cluster.local"). + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FieldTypeDescription
namestringThe short name of the service such as "foo".
namespacestringOptional namespace of the service. Defaults to value of metadata namespace field.
domainstringDomain suffix used to construct the service FQDN in implementations that support such specification.
servicestringThe service FQDN.
labelsrepeated map<string, string>

Optional one or more labels that uniquely identify the service version.

Note: When used for a RouteRule destination, labels MUST be empty.

+ + +### MatchCondition +Match condition specifies a set of criterion to be met in order for the +route rule to be applied to the connection or HTTP request. The +condition provides distinct set of conditions for each protocol with the +intention that conditions apply only to the service ports that match the +protocol. For example, the following route rule restricts the rule to +match only requests originating from "reviews:v2", accessing ratings +service where the URL path starts with /ratings/v2/ and the request +contains a "cookie" with value "user=jason", + + + metadata: + name: my-rule + namespace: default + spec: + destination: + name: ratings + match: + source: + name: reviews + labels: + version: v2 + request: + headers: + cookie: + regex: "^(.*?;)?(user=jason)(;.*)?" + uri: + prefix: "/ratings/v2/" + + +MatchCondition CANNOT be empty. At least one source or +request header must be specified. + + + + + + + + + + + + + + + + + + + +
FieldTypeDescription
sourceIstioServiceIdentifies the service initiating a connection or a request.
requestMatchRequestAttributes of an HTTP request to match.
+ + +### MatchRequest +MatchRequest specifies the attributes of an HTTP request to be used for matching a request. + + + + + + + + + + + + + +
FieldTypeDescription
headersrepeated map<string, StringMatch>

Set of HTTP match conditions based on HTTP/1.1, HTTP/2, GRPC request metadata, such as uri, scheme, authority. The header keys must be lowercase and use hyphen as the separator, e.g. x-request-id.

Header values are case-sensitive and formatted as follows:

exact: "value" or just "value" for exact string match

prefix: "value" for prefix-based match

regex: "value" for ECMAscript style regex-based match

Note 1: The keys uri, scheme, method, and authority correspond to URI, protocol scheme (e.g., HTTP, HTTPS), HTTP method (e.g., GET, POST), and the HTTP Host header respectively.

Note 2: uri can be used to perform URL matches. For all HTTP headers including uri, exact, prefix and ECMA style regular expression matches are supported.

+ + +### RouteRule + + +#### Glossary & concepts +*Service* is a unit of an application with a unique name that other services +use to refer to the functionality being called. Service instances are +pods/VMs/containers that implement the service. + +*Service versions* - In a continuous deployment scenario, for a given service, +there can be multiple sets of instances running potentially different +variants of the application binary. These variants are not necessarily +different API versions. They could be iterative changes to the same service, +deployed in different environments (prod, staging, dev, etc.). Common +scenarios where this occurs include A/B testing, canary rollouts, etc. The +choice of a particular version can be decided based on various criterion +(headers, url, etc.) and/or by weights assigned to each version. Each +service has a default version consisting of all its instances. + +*Source* - downstream client (browser or another service) calling the +Envoy proxy/sidecar (typically to reach another service). + +*Destination* - The remote upstream service to which the Envoy proxy/sidecar is +talking to, on behalf of the source service. There can be one or more +service versions for a given service (see the discussion on versions above). +Envoy would choose the version based on various routing rules. + +*Access model* - Applications address only the destination service +without knowledge of individual service versions. The actual choice of +the version is determined by Envoy, enabling the application code to +decouple itself from the evolution of dependent services. + + + +Route rule provides a custom routing policy based on the source and +destination service versions and connection/request metadata. The rule +must provide a set of conditions for each protocol (TCP, UDP, HTTP) that +the destination service exposes on its ports. + +The rule applies only to the ports on the destination service for which +it provides protocol-specific match condition, e.g. if the rule does not +specify TCP condition, the rule does not apply to TCP traffic towards +the destination service. + +For example, a simple rule to send 100% of incoming traffic for a +"reviews" service to version "v1" can be specified as follows: + + + metadata: + name: my-rule + namespace: default # optional (default is "default") + spec: + destination: + name: reviews + namespace: my-namespace # optional (default is metadata namespace field) + route: + - labels: + version: v1 + weight: 100 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FieldTypeDescription
destinationIstioService

REQUIRED: Destination uniquely identifies the destination associated with this routing rule. This field is applicable for hostname-based resolution for HTTP traffic as well as IP-based resolution for TCP/UDP traffic.

Note: The route rule destination specification represents all version of the service and therefore the IstioService's labels field MUST be empty.

precedenceint32RECOMMENDED. Precedence is used to disambiguate the order of application of rules for the same destination service. A higher number takes priority. If not specified, the value is assumed to be 0. The order of application for rules with the same precedence is unspecified.
matchMatchConditionMatch condtions to be satisfied for the route rule to be activated. If match is omitted, the route rule applies only to HTTP traffic.
route[]repeated DestinationWeightREQUIRED (route|redirect). A routing rule can either redirect traffic or forward traffic. The forwarding target can be one of several versions of a service (see glossary in beginning of document). Weights associated with the service version determine the proportion of traffic it receives.
redirectHTTPRedirectREQUIRED (route|redirect). A routing rule can either redirect traffic or forward traffic. The redirect primitive can be used to send a HTTP 302 redirect to a different URI or Authority.
rewriteHTTPRewriteRewrite HTTP URIs and Authority headers. Rewrite cannot be used with Redirect primitive. Rewrite will be performed before forwarding.
websocketUpgradeboolIndicates that a HTTP/1.1 client connection to this particular route should be allowed (and expected) to upgrade to a WebSocket connection. The default is false. Envoy expects the first request to this route to contain the WebSocket upgrade headers. Otherwise, the request will be rejected.
httpReqTimeoutHTTPTimeoutTimeout policy for HTTP requests.
httpReqRetriesHTTPRetryRetry policy for HTTP requests.
httpFaultHTTPFaultInjectionFault injection policy to apply on HTTP traffic
+ + +### StringMatch +Describes how to match a given string in HTTP headers. Match is case-sensitive. + + + + + + + + + + + + + + + + + + + + + + + + + +
FieldTypeDescription
exactstring (oneof )exact string match
prefixstring (oneof )prefix-based match
regexstring (oneof )ECMAscript style regex-based match
diff --git a/_docs/reference/new/templates/checknothing.md b/_docs/reference/new/templates/checknothing.md new file mode 100644 index 0000000000..cb8aec5e4c --- /dev/null +++ b/_docs/reference/new/templates/checknothing.md @@ -0,0 +1,24 @@ +--- +title: checknothing Config +overview: Generated documentation for Mixer's Template Configuration Schema + +order: 1150 + +layout: docs +type: markdown +--- + + + +### Index + +* [Template](#checknothing.Template) +(message) + + +### Template +CheckNothing represents an empty block of data that is used for Check-capable +adapters which don't require any parameters. This is primarily intended for testing +scenarios. + +NOTE: _No fields in this message type.__ diff --git a/_docs/reference/new/templates/index.md b/_docs/reference/new/templates/index.md new file mode 100644 index 0000000000..898527333f --- /dev/null +++ b/_docs/reference/new/templates/index.md @@ -0,0 +1,12 @@ +--- +title: Mixer Templates +overview: Generated documentation for Mixer's Templates. + +order: 2000 + +layout: docs +type: markdown +--- + +{% include section-index.html %} + diff --git a/_docs/reference/new/templates/listentry.md b/_docs/reference/new/templates/listentry.md new file mode 100644 index 0000000000..c57b97b522 --- /dev/null +++ b/_docs/reference/new/templates/listentry.md @@ -0,0 +1,35 @@ +--- +title: listentry Config +overview: Generated documentation for Mixer's Template Configuration Schema + +order: 1160 + +layout: docs +type: markdown +--- + + + +### Index + +* [Template](#listentry.Template) +(message) + + +### Template +ListEntry is used to verify the presence/absence of a string +within a list. + + + + + + + + + + + + + +
FieldTypeDescription
valuestringSpecifies the entry to verify in the list.
diff --git a/_docs/reference/new/templates/logentry.md b/_docs/reference/new/templates/logentry.md new file mode 100644 index 0000000000..8894fcf3ff --- /dev/null +++ b/_docs/reference/new/templates/logentry.md @@ -0,0 +1,142 @@ +--- +title: logentry Config +overview: Generated documentation for Mixer's Template Configuration Schema + +order: 1170 + +layout: docs +type: markdown +--- + + + +### Index + +* [ValueType](#istio.mixer.v1.config.descriptor.ValueType) +(enum) + + +### 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. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ValueDescription
VALUETYPEUNSPECIFIEDInvalid, default value.
STRINGAn undiscriminated variable-length string.
INT64An undiscriminated 64-bit signed integer.
DOUBLEAn undiscriminated 64-bit floating-point value.
BOOLAn undiscriminated boolean value.
TIMESTAMPA point in time.
IPADDRESSAn IP address.
EMAILADDRESSAn email address.
URIA URI.
DNSNAMEA DNS name.
DURATIONA span between two points in time.
STRINGMAPA map string -> string, typically used by headers.
+ + +## Package logentry + + +### Index + +* [Template](#logentry.Template) +(message) + + +### Template +LogEntry represents an individual entry within a log. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FieldTypeDescription
variablesrepeated map<string, ValueType>Variables that are delivered for each log entry.
timestampTimestampTimestamp is the time value for the log entry
severitystringSeverity indicates the importance of the log entry.
monitoredResourceTypestringOptional. An expression to compute the type of the monitored resource this log entry is being recorded on. If the logging backend supports monitored resources, these fields are used to populate that resource. Otherwise these fields will be ignored by the adapter.
monitoredResourceDimensionsrepeated map<string, ValueType>Optional. A set of expressions that will form the dimensions of the monitored resource this log entry is being recorded on. If the logging backend supports monitored resources, these fields are used to populate that resource. Otherwise these fields will be ignored by the adapter.
diff --git a/_docs/reference/new/templates/metric.md b/_docs/reference/new/templates/metric.md new file mode 100644 index 0000000000..02ff31525c --- /dev/null +++ b/_docs/reference/new/templates/metric.md @@ -0,0 +1,136 @@ +--- +title: metric Config +overview: Generated documentation for Mixer's Template Configuration Schema + +order: 1180 + +layout: docs +type: markdown +--- + + + +### Index + +* [ValueType](#istio.mixer.v1.config.descriptor.ValueType) +(enum) + + +### 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. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ValueDescription
VALUETYPEUNSPECIFIEDInvalid, default value.
STRINGAn undiscriminated variable-length string.
INT64An undiscriminated 64-bit signed integer.
DOUBLEAn undiscriminated 64-bit floating-point value.
BOOLAn undiscriminated boolean value.
TIMESTAMPA point in time.
IPADDRESSAn IP address.
EMAILADDRESSAn email address.
URIA URI.
DNSNAMEA DNS name.
DURATIONA span between two points in time.
STRINGMAPA map string -> string, typically used by headers.
+ + +## Package metric + + +### Index + +* [Template](#metric.Template) +(message) + + +### Template +Metric represents a single piece of data to report. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FieldTypeDescription
valueValueTypeThe value being reported.
dimensionsrepeated map<string, ValueType>The unique identity of the particular metric to report.
monitoredResourceTypestringOptional. An expression to compute the type of the monitored resource this metric is being reported on. If the metric backend supports monitored resources, these fields are used to populate that resource. Otherwise these fields will be ignored by the adapter.
monitoredResourceDimensionsrepeated map<string, ValueType>Optional. A set of expressions that will form the dimensions of the monitored resource this metric is being reported on. If the metric backend supports monitored resources, these fields are used to populate that resource. Otherwise these fields will be ignored by the adapter.
diff --git a/_docs/reference/new/templates/quota.md b/_docs/reference/new/templates/quota.md new file mode 100644 index 0000000000..a6c7731a1a --- /dev/null +++ b/_docs/reference/new/templates/quota.md @@ -0,0 +1,117 @@ +--- +title: quota Config +overview: Generated documentation for Mixer's Template Configuration Schema + +order: 1190 + +layout: docs +type: markdown +--- + + + +### Index + +* [ValueType](#istio.mixer.v1.config.descriptor.ValueType) +(enum) + + +### 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. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ValueDescription
VALUETYPEUNSPECIFIEDInvalid, default value.
STRINGAn undiscriminated variable-length string.
INT64An undiscriminated 64-bit signed integer.
DOUBLEAn undiscriminated 64-bit floating-point value.
BOOLAn undiscriminated boolean value.
TIMESTAMPA point in time.
IPADDRESSAn IP address.
EMAILADDRESSAn email address.
URIA URI.
DNSNAMEA DNS name.
DURATIONA span between two points in time.
STRINGMAPA map string -> string, typically used by headers.
+ + +## Package quota + + +### Index + +* [Template](#quota.Template) +(message) + + +### Template + + + + + + + + + + + + + +
FieldTypeDescription
dimensionsrepeated map<string, ValueType>The unique identity of the particular quota to manipulate.
diff --git a/_docs/reference/new/templates/reportnothing.md b/_docs/reference/new/templates/reportnothing.md new file mode 100644 index 0000000000..09a7c01440 --- /dev/null +++ b/_docs/reference/new/templates/reportnothing.md @@ -0,0 +1,24 @@ +--- +title: reportnothing Config +overview: Generated documentation for Mixer's Template Configuration Schema + +order: 1200 + +layout: docs +type: markdown +--- + + + +### Index + +* [Template](#reportnothing.Template) +(message) + + +### Template +ReportNothing represents an empty block of data that is used for Report-capable +adapters which don't require any parameters. This is primarily intended for testing +scenarios. + +NOTE: _No fields in this message type.__