Rules
Describes the rules used to configure Mixer’s policy and telemetry features.
Value
An instance field of type Value denotes that the expression for the field is of dynamic type and can evaluate to any
ValueType enum values. For example, when
authoring an instance configuration for a template that has a field data
of type istio.policy.v1beta1.Value
,
both of the following expressions are valid data: source.ip | ip("0.0.0.0")
, data: request.id | ""
;
the resulting type is either ValueType.IP_ADDRESS or ValueType.STRING for the two cases respectively.
Objects of type Value are also passed to the adapters during request-time. There is a 1:1 mapping between
oneof fields in Value
and enum values inside ValueType
. Depending on the expression’s evaluated ValueType
,
the equivalent oneof field in Value
is populated by Mixer and passed to the adapters.
IPAddress
An instance field of type IPAddress denotes that the expression for the field must evaluate to ValueType.IP_ADDRESS
Objects of type IPAddress are also passed to the adapters during request-time for the instance fields of type IPAddress
Duration
An instance field of type Duration denotes that the expression for the field must evaluate to ValueType.DURATION
Objects of type Duration are also passed to the adapters during request-time for the instance fields of type Duration
TimeStamp
An instance field of type TimeStamp denotes that the expression for the field must evaluate to ValueType.TIMESTAMP
Objects of type TimeStamp are also passed to the adapters during request-time for the instance fields of type TimeStamp
DNSName
An instance field of type DNSName denotes that the expression for the field must evaluate to ValueType.DNS_NAME
Objects of type DNSName are also passed to the adapters during request-time for the instance fields of type DNSName
StringMap
An instance field of type StringMap denotes that the expression for the field must evaluate to ValueType.STRING_MAP
Objects of type StringMap are also passed to the adapters during request-time for the instance fields of type StringMap
EmailAddress
DO NOT USE !! Under Development An instance field of type EmailAddress denotes that the expression for the field must evaluate to ValueType.EMAIL_ADDRESS
Objects of type EmailAddress are also passed to the adapters during request-time for the instance fields of type EmailAddress
Uri
DO NOT USE !! Under Development An instance field of type Uri denotes that the expression for the field must evaluate to ValueType.URI
Objects of type Uri are also passed to the adapters during request-time for the instance fields of type Uri
DirectHttpResponse
Direct HTTP response for a client-facing error message which can be attached to an RPC error.
AttributeManifest
AttributeManifest describes a set of Attributes produced by some component of an Istio deployment.
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.
- match: match(destination.service.host, "*")
actions:
- handler: prometheus-handler
instances:
- RequestCountByService
Action
Action describes which 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’.
handler: prometheus-handler
instances:
- RequestCountByService
Instance
An 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 using name ‘RequestCountByService’
- name: RequestCountByService
template: istio.mixer.adapter.metric.Metric
params:
value: 1
dimensions:
source: source.name
destination_ip: destination.ip
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 for the prometheus
adapter.
The example is in the form of a Kubernetes resource:
* The metadata.name
is the name of the handler
* The kind
refers to the adapter name
* The spec
block represents adapter-specific configuration as well as the connection information
### Sample-1: No connection specified (for compiled in adapters)
### Note: if connection information is not specified, the adapter configuration is directly inside
### `spec` block. This is going to be DEPRECATED in favor of Sample-2
apiVersion: "config.istio.io/v1alpha2"
kind: handler
metadata:
name: requestcount
namespace: istio-system
spec:
compiledAdapter: prometheus
params:
metrics:
- name: request_count
instance_name: requestcount.metric.istio-system
kind: COUNTER
label_names:
- source_service
- source_version
- destination_service
- destination_version
---
### Sample-2: With connection information (for out-of-process adapters)
### Note: Unlike sample-1, the adapter configuration is parallel to `connection` and is nested inside `param` block.
apiVersion: "config.istio.io/v1alpha2"
kind: handler
metadata:
name: requestcount
namespace: istio-system
spec:
compiledAdapter: prometheus
params:
param:
metrics:
- name: request_count
instance_name: requestcount.metric.istio-system
kind: COUNTER
label_names:
- source_service
- source_version
- destination_service
- destination_version
connection:
address: localhost:8090
---
Connection
Connection allows the operator to specify the endpoint for out-of-process infrastructure backend. Connection is part of the handler custom resource and is specified alongside adapter specific configuration.
Authentication
Authentication allows the operator to specify the authentication of connections to out-of-process infrastructure backend.
Tls
Tls let operator specify client authentication setting when TLS is used for connection to the backend.
OAuth
OAuth let operator specify config to fetch access token via oauth when using TLS for connection to the backend.
Mutual
Mutual let operator specify TLS configuration for Mixer as client if mutual TLS is used to secure connection to adapter backend.
AttributeManifest.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.
Rule.HeaderOperationTemplate
A template for an HTTP header manipulation. Values in the template are expressions
that may reference action outputs by name. For example, if an action x
produces an output
with a field f
, then the header value expressions may use attribute x.output.f
to reference
the field value:
request_header_operations:
- name: x-istio-header
values:
- x.output.f
If the header value expression evaluates to an empty string, and the operation is to either replace or append a header, then the operation is not applied. This permits conditional behavior on behalf of the adapter to optionally modify the headers.
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.
Name | Description |
---|---|
VALUE_TYPE_UNSPECIFIED | Invalid, default value. |
STRING | An undiscriminated variable-length string. |
INT64 | An undiscriminated 64-bit signed integer. |
DOUBLE | An undiscriminated 64-bit floating-point value. |
BOOL | An undiscriminated boolean value. |
TIMESTAMP | A point in time. |
IP_ADDRESS | An IP address. |
EMAIL_ADDRESS | An email address. |
URI | A URI. |
DNS_NAME | A DNS name. |
DURATION | A span between two points in time. |
STRING_MAP | A map string -> string, typically used by headers. |
HttpStatusCode
HTTP response codes. For more details: http://www.iana.org/assignments/http-status-codes/http-status-codes.xhtml
Name | Description |
---|---|
Empty | Empty - This code not part of the HTTP status code specification, but it is needed for proto
|
Continue | |
OK | |
Created | |
Accepted | |
NonAuthoritativeInformation | |
NoContent | |
ResetContent | |
PartialContent | |
MultiStatus | |
AlreadyReported | |
IMUsed | |
MultipleChoices | |
MovedPermanently | |
Found | |
SeeOther | |
NotModified | |
UseProxy | |
TemporaryRedirect | |
PermanentRedirect | |
BadRequest | |
Unauthorized | |
PaymentRequired | |
Forbidden | |
NotFound | |
MethodNotAllowed | |
NotAcceptable | |
ProxyAuthenticationRequired | |
RequestTimeout | |
Conflict | |
Gone | |
LengthRequired | |
PreconditionFailed | |
PayloadTooLarge | |
URITooLong | |
UnsupportedMediaType | |
RangeNotSatisfiable | |
ExpectationFailed | |
MisdirectedRequest | |
UnprocessableEntity | |
Locked | |
FailedDependency | |
UpgradeRequired | |
PreconditionRequired | |
TooManyRequests | |
RequestHeaderFieldsTooLarge | |
InternalServerError | |
NotImplemented | |
BadGateway | |
ServiceUnavailable | |
GatewayTimeout | |
HTTPVersionNotSupported | |
VariantAlsoNegotiates | |
InsufficientStorage | |
LoopDetected | |
NotExtended | |
NetworkAuthenticationRequired |
Rule.HeaderOperationTemplate.Operation
Header operation type.
Name | Description |
---|---|
REPLACE | Replace a header by name. |
REMOVE | Remove a header by name. Values are ignored. |
APPEND | Append values to the existing header values. |
FractionalPercent.DenominatorType
Fraction percentages support several fixed denominator values.
Name | Description |
---|---|
HUNDRED | 100. Example: 1⁄100 = 1%. |
TEN_THOUSAND | 10,000. Example: 1⁄10000 = 0.01%. |
Tls.AuthHeader
AuthHeader specifies how to pass access token with authorization header.
Name | Description |
---|---|
PLAIN | Access token is passed in authorization header as what it is (authorization: some-token). |
BEARER | Access token is passed to adapter as bearer token (i.e. authorization: bearer some-token). |