Rules

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’.

AttributeManifest

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

Field Type Description Required

Field	Type	Description	Required
`revision`	`string`	The revision of this document. Assigned by server.	No
`name`	`string`	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.	Yes
`attributes`	`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: Where `IDENT` must match the regular expression `a-z+` 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 . Attributes not in that list should be named with a component-specific suffix such as `request.count-my.component`.	No

revision

string

The revision of this document. Assigned by server.

name

string

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.

Yes

attributes

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:

Where IDENT must match the regular expression a-z+ 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 . Attributes not in that list should be named with a component-specific suffix such as request.count-my.component.

AttributeManifest.AttributeInfo

AttributeInfo describes the schema of an Istio Attribute.

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.

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.

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.

Field	Type	Description	Required
`description`	`string`	A human-readable description of the attribute’s purpose.	No
`valueType`		The type of data carried by this attribute.	Yes

Authentication

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

Field	Type	Description	Required
`tls`		Originate a TLS connection to the adapter and present an auth token in each call for client authentication.	Yes
`mutual`	`Mutual (oneof)`	Secure connections to the adapter using mutual TLS by presenting client 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.

Field	Type	Description	Required
`address`	`string`	The address of the backend.	No
`timeout`	`Duration`	Timeout for remote calls to the backend.	No
`authentication`		Auth config for the connection to the backend. If omitted, plain text will be used.	No

DNSName

An instance field of type DNSName denotes that the expression for the field must evaluate to

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

Field	Type	Description	Required
`value`	`string`	DNSName encoded as string.	No

DirectHttpResponse

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

Field	Type	Description	Required
`code`		HTTP status code. If not set, RPC error code is used.	No
`body`	`string`	HTTP response body.	No
`headers`	`map<string, string>`	HTTP response headers.	No

Duration

An instance field of type Duration denotes that the expression for the field must evaluate to

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

Field	Type	Description	Required
`value`	`Duration`	Duration encoded as google.protobuf.Duration.	No

DO NOT USE !! Under Development An instance field of type EmailAddress denotes that the expression for the field must evaluate to

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

FractionalPercent.DenominatorType

Fraction percentages support several fixed denominator values.

Name Description

Name	Description
`HUNDRED`	100. Example: ¹⁄₁₀₀ = 1%.
`TEN_THOUSAND`	10,000. Example: ¹⁄₁₀₀₀₀ = 0.01%.

HUNDRED

100.

Example: ¹⁄₁₀₀ = 1%.

TEN_THOUSAND

10,000.

Example: ¹⁄₁₀₀₀₀ = 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

Field	Type	Description	Required
`name`	`string`		Yes
`compiledAdapter`	`string`	The name of the compiled in adapter this handler instantiates. For referencing non compiled-in adapters, 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 a constant in its code.	Yes
`adapter`	`string`	The name of a specific adapter implementation. For referencing compiled-in adapters, use the `compiled_adapter` field instead. An adapter’s implementation name is typically a constant in its code.	No
`params`	`Struct`	Depends on adapter implementation. Struct representation of a proto defined by the adapter implementation; this varies depending on the value of field `adapter`.	No
`connection`		Information 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:

Name	Description
`Empty`	Empty - This code not part of the HTTP status code specification, but it is needed for proto `enum` type.
`Continue`
`OK`
`Created`
`Accepted`
`NonAuthoritativeInformation`
`NoContent`
`ResetContent`
`PartialContent`
`MultiStatus`
`AlreadyReported`
`IMUsed`
`MultipleChoices`
`MovedPermanently`
`Found`

`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 to

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

Field	Type	Description	Required
`value`	`bytes`	IPAddress 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 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 using name ‘RequestCountByService’

- name: RequestCountByService
  template: istio.mixer.adapter.metric.Metric
  params:
    value: 1
    dimensions:
      source: source.name
      destination_ip: destination.ip

Field	Type	Description	Required
`name`	`string`	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.	Yes
`compiledTemplate`	`string`	The name of the compiled in template this instance creates instances for. For referencing non compiled-in templates, use the `template` field instead. The value must match the name of the available template Mixer is built with.	Yes
`template`	`string`	The name of the template this instance creates instances for. For referencing compiled-in templates, use the `compiled_template` field instead. The value must match the name of the available template in scope.	No
`params`		Depends on referenced template. Struct representation of a proto defined by the template; this varies depending on the value of field `template`.	Yes
`attributeBindings`	`map<string, string>`	Defines attribute bindings to map the output of attribute-producing adapters back into the attribute space. The variable `output` refers to the output template instance produced by the adapter. The following example derives `source.namespace` from `source.uid` in the context of Kubernetes:	No

Mutual

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

Field	Type	Description	Required
`privateKey`	`string`	The path to the file holding the private key for mutual TLS. If omitted, the default Mixer private key will be used.	No
`clientCertificate`	`string`	The path to the file holding client certificate for mutual TLS. If omitted, the default Mixer certificates will be used.	No
`caCertificates`	`string`	The path to the file holding additional CA certificates that are needed to verify the presented adapter certificates. By default Mixer should already include Istio CA certificates and system certificates in cert pool.	No
`serverName`	`string`	Used to configure mixer mutual TLS client to supply server name for SNI. It is not used to verify the hostname of the peer certificate, since Istio verifies whitelisted SAN fields in mutual TLS.	No

OAuth

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

Field	Type	Description	Required
`clientId`	`string`	OAuth client id for mixer.	Yes
`clientSecret`	`string`	The path to the file holding the client secret for oauth.	Yes
`tokenUrl`	`string`	The Resource server’s token endpoint URL.	Yes
`scopes`	`string[]`	List of requested permissions.	No
`endpointParams`	`map<string, string>`	Additional parameters for requests to the token endpoint.	No

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
    - RequestCountByService

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:

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.

Field	Type	Description	Required
`name`	`string`	Header name literal value.	Yes
`values`	`string[]`	Header value expressions.	No
`operation`		Header operation type. Default operation is to replace the value of the header by name.	No

Rule.HeaderOperationTemplate.Operation

Header operation type.

Name	Description
`REPLACE`
`REMOVE`	Remove a header by name. Values are ignored.
`APPEND`	Append values to the existing header values.

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

Field	Type	Description	Required
`value`	`map<string, string>`	StringMap encoded as a map of strings	No

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

Field	Type	Description	Required
`value`		TimeStamp encoded as google.protobuf.Timestamp.	No

Tls

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

Field	Type	Description	Required
`caCertificates`	`string`	The path to the file holding additional CA certificates to well known public certs.	No
`tokenPath`	`string (oneof)`	The path to the file holding the auth token (password, jwt token, api key, etc).	Yes
`oauth`		Oauth config to fetch access token from auth provider.	Yes
`authHeader`	`AuthHeader (oneof)`	Access token is passed as authorization header.	Yes
`customHeader`	`string (oneof)`	Customized header key to hold access token, e.g. x-api-key. Token will be passed as what it is.	Yes
`serverName`	`string`	Used to configure mixer TLS client to verify the hostname on the returned certificates. 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.

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).

Uri

DO NOT USE !! Under Development An instance field of type Uri denotes that the expression for the field must evaluate to

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

Field	Type	Description	Required
`value`	`string`	Uri encoded as string.	No

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.

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`