Rules

Describes the rules used to configure Mixer’s policy and telemetry features.

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 objectconstructed using the instance ‘RequestCountByService’.

  1. handler: prometheus-handler
  2. instances:
  3. - RequestCountByService
FieldTypeDescriptionRequired
handlerstringFully qualified name of the handler to invoke.Must match the name of a Handler.Yes
instancesstring[]Each value must match the fully qualified name of theInstances.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.Yes
namestringA handle to refer to the results of the action.No

AttributeManifest

AttributeManifest describes a set of Attributes produced by some componentof an Istio deployment.

FieldTypeDescriptionRequired
revisionstringThe revision of this document. Assigned by server.No
namestringName of the component producing these attributes. This can bethe proxy (with the canonical name istio-proxy) or the name of anattributes kind adapter in Mixer.Yes
attributesmap<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:
  1. Name = IDENT { SEPARATOR IDENT };
Where IDENT must match the regular expression a-z+ and SEPARATOR mustmatch the regular expression [.-].Attribute names must be unique within a single Istio deployment. The set of canonicalattributes are described at here.Attributes not in that list should be named with a component-specific suffix such asrequest.count-my.component.
No

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 theoriginal IP address of a TCP connection. The attributes are often generatedand consumed by different services. For example, a frontend service cangenerate an authenticated user attribute and pass it to a backend service foraccess control purpose.

To simplify the system and improve developer experience, Istio usesshared attribute definitions across all components. For example, the sameauthenticated user attribute will be used for logging, monitoring, analytics,billing, access control, auditing. Many Istio components provide theirfunctionality by collecting, generating, and operating on attributes.For example, the proxy collects the error code attribute, and the loggingstores it into a log.

Design

Each Istio attribute must conform to an AttributeInfo in anAttributeManifest in the current Istio deployment at runtime. AnAttributeInfo is used to define an attribute’smetadata: the type of its value and a detailed description that explainsthe 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 thisspecification, because passing attribute using JSON, XML, or Protocol Buffersdoes not change the semantics of the attribute. Different implementationscan choose different representations based on their needs.

HTTP Mapping

Because many systems already have REST APIs, it makes sense to define astandard HTTP mapping for Istio attributes that are compatible with typicalREST APIs. The design is to map one attribute to one HTTP header, theattribute name and value becomes the HTTP header name and value. The actualencoding scheme will be decided later.

FieldTypeDescriptionRequired
descriptionstringA human-readable description of the attribute’s purpose.No
valueTypeValueTypeThe type of data carried by this attribute.Yes

Authentication

Authentication allows the operator to specify the authentication ofconnections to out-of-process infrastructure backend.

FieldTypeDescriptionRequired
tlsTls (oneof)Originate a TLS connection to the adapter and present an auth tokenin each call for client authentication.Yes
mutualMutual (oneof)Secure connections to the adapter using mutual TLS by presentingclient certificates for authentication.Yes

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.

FieldTypeDescriptionRequired
addressstringThe address of the backend.No
timeoutDurationTimeout for remote calls to the backend.No
authenticationAuthenticationAuth config for the connection to the backend. If omitted, plain text willbe used.No

DNSName

An instance field of type DNSName denotes that the expression for the field must evaluate toValueType.DNS_NAME

Objects of type DNSName are also passed to the adapters during request-time for the instance fields oftype DNSName

FieldTypeDescriptionRequired
valuestringDNSName encoded as string.No

DirectHttpResponse

Direct HTTP response for a client-facing error message which can be attachedto an RPC error.

FieldTypeDescriptionRequired
codeHttpStatusCodeHTTP status code. If not set, RPC error code is used.No
bodystringHTTP response body.No
headersmap<string, string>HTTP response headers.No

Duration

An instance field of type Duration denotes that the expression for the field must evaluate toValueType.DURATION

Objects of type Duration are also passed to the adapters during request-time for the instance fields oftype Duration

FieldTypeDescriptionRequired
valueDurationDuration encoded as google.protobuf.Duration.No

EmailAddress

DO NOT USE !! Under DevelopmentAn instance field of type EmailAddress denotes that the expression for the field must evaluate toValueType.EMAIL_ADDRESS

Objects of type EmailAddress are also passed to the adapters during request-time for the instance fields oftype EmailAddress

FieldTypeDescriptionRequired
valuestringEmailAddress encoded as string.No

FractionalPercent.DenominatorType

Fraction percentages support several fixed denominator values.

NameDescription
HUNDRED100.Example: 1100 = 1%.
TEN_THOUSAND10,000.Example: 110000 = 0.01%.

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

  1. ### Sample-1: No connection specified (for compiled in adapters)
  2. ### Note: if connection information is not specified, the adapter configuration is directly inside
  3. ### `spec` block. This is going to be DEPRECATED in favor of Sample-2
  4. apiVersion: "config.istio.io/v1alpha2"
  5. kind: handler
  6. metadata:
  7. name: requestcount
  8. namespace: istio-system
  9. spec:
  10. compiledAdapter: prometheus
  11. params:
  12. metrics:
  13. - name: request_count
  14. instance_name: requestcount.metric.istio-system
  15. kind: COUNTER
  16. label_names:
  17. - source_service
  18. - source_version
  19. - destination_service
  20. - destination_version
  21. ---
  22. ### Sample-2: With connection information (for out-of-process adapters)
  23. ### Note: Unlike sample-1, the adapter configuration is parallel to `connection` and is nested inside `param` block.
  24. apiVersion: "config.istio.io/v1alpha2"
  25. kind: handler
  26. metadata:
  27. name: requestcount
  28. namespace: istio-system
  29. spec:
  30. compiledAdapter: prometheus
  31. params:
  32. param:
  33. metrics:
  34. - name: request_count
  35. instance_name: requestcount.metric.istio-system
  36. kind: COUNTER
  37. label_names:
  38. - source_service
  39. - source_version
  40. - destination_service
  41. - destination_version
  42. connection:
  43. address: localhost:8090
  44. ---
FieldTypeDescriptionRequired
namestringMust be unique in the entire Mixer configuration. Used by Actionsto refer to this handler.Yes
compiledAdapterstringThe name of the compiled in adapter this handler instantiates. For referencing non compiled-inadapters, use the adapter field instead.The value must match the name of the available adapter Mixer is built with. An adapter’s name is typically aconstant in its code.Yes
adapterstringThe name of a specific adapter implementation. For referencing compiled-inadapters, use the compiled_adapter field instead.An adapter’s implementation name is typically a constant in its code.No
paramsStructDepends on adapter implementation. Struct representation of aproto defined by the adapter implementation; this varies depending on the value of field adapter.No
connectionConnectionInformation on how to connect to the out-of-process adapter.This is used if the adapter is not compiled into Mixer binary and is running as a separate process.No

HttpStatusCode

HTTP response codes.For more details: http://www.iana.org/assignments/http-status-codes/http-status-codes.xhtml

NameDescription
EmptyEmpty - This code not part of the HTTP status code specification, but it is needed for protoenum type.
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

IPAddress

An instance field of type IPAddress denotes that the expression for the field must evaluate toValueType.IP_ADDRESS

Objects of type IPAddress are also passed to the adapters during request-time for the instance fields oftype IPAddress

FieldTypeDescriptionRequired
valuebytesIPAddress encoded as bytes.No

Instance

An Instance tells Mixer how to create instances for particular template.

Instance is defined by the operator. Instance is defined relative to a knowntemplate. Their purpose is to tell Mixer how to use attributes or literals to produceinstances 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’

  1. - name: RequestCountByService
  2. template: istio.mixer.adapter.metric.Metric
  3. params:
  4. value: 1
  5. dimensions:
  6. source: source.name
  7. destination_ip: destination.ip
FieldTypeDescriptionRequired
namestringThe name of this instanceMust be unique amongst other Instances in scope. Used by Action to referto an instance produced by this instance.Yes
compiledTemplatestringThe name of the compiled in template this instance creates instances for. For referencing non compiled-intemplates, use the template field instead.The value must match the name of the available template Mixer is built with.Yes
templatestringThe name of the template this instance creates instances for. For referencing compiled-intemplates, use the compiled_template field instead.The value must match the name of the available template in scope.No
paramsStructDepends on referenced template. Struct representation of aproto defined by the template; this varies depending on the value of field template.Yes
attributeBindingsmap<string, string>Defines attribute bindings to map the output of attribute-producing adapters back intothe attribute space. The variable output refers to the output template instance producedby the adapter.The following example derives source.namespace from source.uid in the context of Kubernetes:
  1. params: # Pass the required attribute data to the adapter source_uid: source.uid | ""attribute_bindings: # Fill the new attributes from the adapter produced output source.namespace: output.source_namespace
No

Mutual

Mutual let operator specify TLS configuration for Mixer as client if mutual TLS is used tosecure connection to adapter backend.

FieldTypeDescriptionRequired
privateKeystringThe path to the file holding the private key for mutual TLS. If omitted, thedefault Mixer private key will be used.No
clientCertificatestringThe path to the file holding client certificate for mutual TLS. If omitted, thedefault Mixer certificates will be used.No
caCertificatesstringThe path to the file holding additional CA certificates that are needed toverify the presented adapter certificates. By default Mixer should alreadyinclude Istio CA certificates and system certificates in cert pool.No
serverNamestringUsed to configure mixer mutual TLS client to supply server name for SNI.It is not used to verify the hostname of the peer certificate, sinceIstio verifies whitelisted SAN fields in mutual TLS.No

OAuth

OAuth let operator specify config to fetch access token via oauth when usingTLS for connection to the backend.

FieldTypeDescriptionRequired
clientIdstringOAuth client id for mixer.Yes
clientSecretstringThe path to the file holding the client secret for oauth.Yes
tokenUrlstringThe Resource server’s token endpoint URL.Yes
scopesstring[]List of requested permissions.No
endpointParamsmap<string, string>Additional parameters for requests to the token endpoint.No

Rule

A Rule is a selector and a set of intentions to be executed when theselector is true

The following example instructs Mixer to invoke prometheus-handler handler for all services and pass it theinstance constructed using the ‘RequestCountByService’ instance.

  1. - match: match(destination.service.host, "*")
  2. actions:
  3. - handler: prometheus-handler
  4. instances:
  5. - RequestCountByService
FieldTypeDescriptionRequired
matchstringMatch is an attribute based predicate. When Mixer receives arequest it evaluates the match expression and executes all the associated actionsif 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- match(destination.service.host, "ratings.*") selects any request targeting a service whosename starts with “ratings”- attr1 == "20" && attr2 == "30" logical AND, OR, and NOT are also availableNo
actionsAction[]The actions that will be executed when match evaluates to true.No
requestHeaderOperationsHeaderOperationTemplate[]Templatized operations on the request headers using values produced by therule actions. Require the check action result to be OK.No
responseHeaderOperationsHeaderOperationTemplate[]Templatized operations on the response headers using values produced by therule actions. Require the check action result to be OK.No

Rule.HeaderOperationTemplate

A template for an HTTP header manipulation. Values in the template are expressionsthat may reference action outputs by name. For example, if an action x produces an outputwith a field f, then the header value expressions may use attribute x.output.f to referencethe field value:

  1. request_header_operations:
  2. - name: x-istio-header
  3. values:
  4. - x.output.f

If the header value expression evaluates to an empty string, and the operation is to either replaceor append a header, then the operation is not applied. This permits conditional behavior on behalf of theadapter to optionally modify the headers.

FieldTypeDescriptionRequired
namestringHeader name literal value.Yes
valuesstring[]Header value expressions.No
operationOperationHeader operation type. Default operation is to replace the value of the header by name.No

Rule.HeaderOperationTemplate.Operation

Header operation type.

NameDescription
REPLACEReplace a header by name.
REMOVERemove a header by name. Values are ignored.
APPENDAppend values to the existing header values.

StringMap

An instance field of type StringMap denotes that the expression for the field must evaluate toValueType.STRING_MAP

Objects of type StringMap are also passed to the adapters during request-time for the instance fields oftype StringMap

FieldTypeDescriptionRequired
valuemap<string, string>StringMap encoded as a map of stringsNo

TimeStamp

An instance field of type TimeStamp denotes that the expression for the field must evaluate toValueType.TIMESTAMP

Objects of type TimeStamp are also passed to the adapters during request-time for the instance fields oftype TimeStamp

FieldTypeDescriptionRequired
valueTimestampTimeStamp encoded as google.protobuf.Timestamp.No

Tls

Tls let operator specify client authentication setting when TLS is used forconnection to the backend.

FieldTypeDescriptionRequired
caCertificatesstringThe path to the file holding additional CA certificates to well knownpublic certs.No
tokenPathstring (oneof)The path to the file holding the auth token (password, jwt token, apikey, etc).Yes
oauthOAuth (oneof)Oauth config to fetch access token from auth provider.Yes
authHeaderAuthHeader (oneof)Access token is passed as authorization header.Yes
customHeaderstring (oneof)Customized header key to hold access token, e.g. x-api-key. Token will bepassed as what it is.Yes
serverNamestringUsed to configure mixer TLS client to verify the hostname on the returnedcertificates. It is also included in the client’s handshake to support SNI.No

Tls.AuthHeader

AuthHeader specifies how to pass access token with authorization header.

NameDescription
PLAINAccess token is passed in authorization header as what it is(authorization: some-token).
BEARERAccess token is passed to adapter as bearer token (i.e. authorization:bearer some-token).

Uri

DO NOT USE !! Under DevelopmentAn instance field of type Uri denotes that the expression for the field must evaluate toValueType.URI

Objects of type Uri are also passed to the adapters during request-time for the instance fields oftype Uri

FieldTypeDescriptionRequired
valuestringUri encoded as string.No

Value

An instance field of type Value denotes that the expression for the field is of dynamic type and can evaluate to anyValueType enum values. For example, whenauthoring 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 betweenoneof 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.

FieldTypeDescriptionRequired
stringValuestring (oneof)Used for values of type STRINGYes
int64Valueint64 (oneof)Used for values of type INT64Yes
doubleValuedouble (oneof)Used for values of type DOUBLEYes
boolValuebool (oneof)Used for values of type BOOLYes
ipAddressValueIPAddress (oneof)Used for values of type IPAddressYes
timestampValueTimeStamp (oneof)Used for values of type TIMESTAMPYes
durationValueDuration (oneof)Used for values of type DURATIONYes
emailAddressValueEmailAddress (oneof)Used for values of type EmailAddressYes
dnsNameValueDNSName (oneof)Used for values of type DNSNameYes
uriValueUri (oneof)Used for values of type UriYes
stringMapValueStringMap (oneof)Used for values of type STRING_MAPYes

ValueType

ValueType describes the types that values in the Istio system can take. Theseare used to describe the type of Attributes at run time, describe the type ofthe result of evaluating an expression, and to describe the runtime type offields of other descriptors.

NameDescription
VALUE_TYPE_UNSPECIFIEDInvalid, 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.
IP_ADDRESSAn IP address.
EMAIL_ADDRESSAn email address.
URIA URI.
DNS_NAMEA DNS name.
DURATIONA span between two points in time.
STRING_MAPA map string -> string, typically used by headers.