---
title: Global Mesh Options
description: Configuration affecting the service mesh as a whole.
location: https://istio.io/docs/reference/config/istio.mesh.v1alpha1.html
layout: protoc-gen-docs
generator: protoc-gen-docs
weight: 20
number_of_entries: 81
---
Configuration affecting the service mesh as a whole.
MeshConfig
MeshConfig defines mesh-wide settings for the Istio service mesh.
Field |
Type |
Description |
Required |
proxyListenPort |
int32 |
Port on which Envoy should listen for all outbound traffic to other services.
Default port is 15001.
|
No
|
proxyInboundListenPort |
int32 |
Port on which Envoy should listen for all inbound traffic to the pod/vm will be captured to.
Default port is 15006.
|
No
|
proxyHttpPort |
int32 |
Port on which Envoy should listen for HTTP PROXY requests if set.
|
No
|
connectTimeout |
Duration |
Connection timeout used by Envoy. (MUST BE >=1ms)
Default timeout is 10s.
|
No
|
tcpKeepalive |
TcpKeepalive |
If set then set SO_KEEPALIVE on the socket to enable TCP Keepalives.
|
No
|
ingressClass |
string |
Class of ingress resources to be processed by Istio ingress
controller. This corresponds to the value of
kubernetes.io/ingress.class annotation.
|
No
|
ingressService |
string |
Name of the Kubernetes service used for the istio ingress controller.
If no ingress controller is specified, the default value istio-ingressgateway is used.
|
No
|
ingressControllerMode |
IngressControllerMode |
Defines whether to use Istio ingress controller for annotated or all ingress resources.
Default mode is STRICT .
|
No
|
ingressSelector |
string |
Defines which gateway deployment to use as the Ingress controller. This field corresponds to
the Gateway.selector field, and will be set as istio: INGRESS_SELECTOR .
By default, ingressgateway is used, which will select the default IngressGateway as it has the
istio: ingressgateway labels.
It is recommended that this is the same value as ingressService.
|
No
|
enableTracing |
bool |
Flag to control generation of trace spans and request IDs.
Requires a trace span collector defined in the proxy configuration.
|
No
|
accessLogFile |
string |
File address for the proxy access log (e.g. /dev/stdout).
Empty value disables access logging.
|
No
|
accessLogFormat |
string |
Format for the proxy access log
Empty value results in proxy’s default access log format
|
No
|
accessLogEncoding |
AccessLogEncoding |
Encoding for the proxy access log (TEXT or JSON ).
Default value is TEXT .
|
No
|
enableEnvoyAccessLogService |
bool |
This flag enables Envoy’s gRPC Access Log Service.
See Access Log Service
for details about Envoy’s gRPC Access Log Service API.
Default value is false .
|
No
|
disableEnvoyListenerLog |
bool |
This flag disables Envoy Listener logs.
See Listener Access Log
Istio Enables Envoy’s listener access logs on “NoRoute” response flag.
Default value is false .
|
No
|
defaultConfig |
ProxyConfig |
Default proxy config used by gateway and sidecars.
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.
On Kubernetes, this can be overridden on individual pods with the proxy.istio.io/config annotation.
|
No
|
outboundTrafficPolicy |
OutboundTrafficPolicy |
Set the default behavior of the sidecar for handling outbound
traffic from the application.
Can be overridden at a Sidecar level by setting the OutboundTrafficPolicy in the
Sidecar API.
Default mode is ALLOW_ANY , which means outbound traffic to unknown destinations will be allowed.
|
No
|
inboundTrafficPolicy |
InboundTrafficPolicy |
Set the default behavior of the sidecar for handling inbound
traffic to the application. If your application listens on
localhost, you will need to set this to LOCALHOST .
|
No
|
configSources |
ConfigSource[] |
ConfigSource describes a source of configuration data for networking
rules, and other Istio configuration artifacts. Multiple data sources
can be configured for a single control plane.
|
No
|
enableAutoMtls |
BoolValue |
This flag is used to enable mutual TLS automatically for service to service communication
within the mesh, default true.
If set to true, and a given service does not have a corresponding DestinationRule configured,
or its DestinationRule does not have ClientTLSSettings specified, Istio configures client side
TLS configuration appropriately. More specifically,
If the upstream authentication policy is in STRICT mode, use Istio provisioned certificate
for mutual TLS to connect to upstream.
If upstream service is in plain text mode, use plain text.
If the upstream authentication policy is in PERMISSIVE mode, Istio configures clients to use
mutual TLS when server sides are capable of accepting mutual TLS traffic.
If service DestinationRule exists and has ClientTLSSettings specified, that is always used instead.
|
No
|
trustDomain |
string |
The trust domain corresponds to the trust root of a system.
Refer to SPIFFE-ID
|
No
|
trustDomainAliases |
string[] |
The trust domain aliases represent the aliases of trustDomain .
For example, if we have
trustDomain: td1
trustDomainAliases: ["td2", "td3"]
Any service with the identity td1/ns/foo/sa/a-service-account , td2/ns/foo/sa/a-service-account ,
or td3/ns/foo/sa/a-service-account will be treated the same in the Istio mesh.
|
No
|
caCertificates |
CertificateData[] |
The extra root certificates for workload-to-workload communication.
The plugin certificates (the ‘cacerts’ secret) or self-signed certificates (the ‘istio-ca-secret’ secret)
are automatically added by Istiod.
The CA certificate that signs the workload certificates is automatically added by Istio Agent.
|
No
|
defaultServiceExportTo |
string[] |
The default value for the ServiceEntry.exportTo field and services
imported through container registry integrations, e.g. this applies to
Kubernetes Service resources. The value is a list of namespace names and
reserved namespace aliases. The allowed namespace aliases are:
* - All Namespaces
. - Current Namespace
~ - No Namespace
If not set the system will use “*” as the default value which implies that
services are exported to all namespaces.
All namespaces is a reasonable default for implementations that don’t
need to restrict access or visibility of services across namespace
boundaries. If that requirement is present it is generally good practice to
make the default Current namespace so that services are only visible
within their own namespaces by default. Operators can then expand the
visibility of services to other namespaces as needed. Use of No Namespace
is expected to be rare but can have utility for deployments where
dependency management needs to be precise even within the scope of a single
namespace.
For further discussion see the reference documentation for ServiceEntry ,
Sidecar , and Gateway .
|
No
|
defaultVirtualServiceExportTo |
string[] |
The default value for the VirtualService.exportTo field. Has the same
syntax as defaultServiceExportTo .
If not set the system will use “*” as the default value which implies that
virtual services are exported to all namespaces
|
No
|
defaultDestinationRuleExportTo |
string[] |
The default value for the DestinationRule.exportTo field. Has the same
syntax as defaultServiceExportTo .
If not set the system will use “*” as the default value which implies that
destination rules are exported to all namespaces
|
No
|
rootNamespace |
string |
The namespace to treat as the administrative root namespace for
Istio configuration. When processing a leaf namespace Istio will search for
declarations in that namespace first and if none are found it will
search in the root namespace. Any matching declaration found in the root
namespace is processed as if it were declared in the leaf namespace.
The precise semantics of this processing are documented on each resource
type.
|
No
|
localityLbSetting |
LocalityLoadBalancerSetting |
Locality based load balancing distribution or failover settings.
If unspecified, locality based load balancing will be enabled by default.
However, this requires outlierDetection to actually take effect for a particular
service, see https://istio.io/latest/docs/tasks/traffic-management/locality-load-balancing/failover/
|
No
|
dnsRefreshRate |
Duration |
Configures DNS refresh rate for Envoy clusters of type STRICT_DNS
Default refresh rate is 60s .
|
No
|
h2UpgradePolicy |
H2UpgradePolicy |
Specify if http1.1 connections should be upgraded to http2 by default.
if sidecar is installed on all pods in the mesh, then this should be set to UPGRADE .
If one or more services or namespaces do not have sidecar(s), then this should be set to DO_NOT_UPGRADE .
It can be enabled by destination using the destinationRule.trafficPolicy.connectionPool.http.h2UpgradePolicy override.
|
No
|
inboundClusterStatName |
string |
Name to be used while emitting statistics for inbound clusters. The same pattern is used while computing stat prefix for
network filters like TCP and Redis.
By default, Istio emits statistics with the pattern inbound|<port>|<port-name>|<service-FQDN> .
For example inbound|7443|grpc-reviews|reviews.prod.svc.cluster.local . This can be used to override that pattern.
A Pattern can be composed of various pre-defined variables. The following variables are supported.
%SERVICE% - Will be substituted with short hostname of the service.
%SERVICE_NAME% - Will be substituted with name of the service.
%SERVICE_FQDN% - Will be substituted with FQDN of the service.
%SERVICE_PORT% - Will be substituted with port of the service.
%TARGET_PORT% - Will be substituted with the target port of the service.
%SERVICE_PORT_NAME% - Will be substituted with port name of the service.
Following are some examples of supported patterns for reviews:
%SERVICE_FQDN%_%SERVICE_PORT% will use reviews.prod.svc.cluster.local_7443 as the stats name.
%SERVICE% will use reviews.prod as the stats name.
|
No
|
outboundClusterStatName |
string |
Name to be used while emitting statistics for outbound clusters. The same pattern is used while computing stat prefix for
network filters like TCP and Redis.
By default, Istio emits statistics with the pattern outbound|<port>|<subsetname>|<service-FQDN> .
For example outbound|8080|v2|reviews.prod.svc.cluster.local . This can be used to override that pattern.
A Pattern can be composed of various pre-defined variables. The following variables are supported.
%SERVICE% - Will be substituted with short hostname of the service.
%SERVICE_NAME% - Will be substituted with name of the service.
%SERVICE_FQDN% - Will be substituted with FQDN of the service.
%SERVICE_PORT% - Will be substituted with port of the service.
%SERVICE_PORT_NAME% - Will be substituted with port name of the service.
%SUBSET_NAME% - Will be substituted with subset.
Following are some examples of supported patterns for reviews:
%SERVICE_FQDN%_%SERVICE_PORT% will use reviews.prod.svc.cluster.local_7443 as the stats name.
%SERVICE% will use reviews.prod as the stats name.
|
No
|
enablePrometheusMerge |
BoolValue |
If enabled, Istio agent will merge metrics exposed by the application with metrics from Envoy
and Istio agent. The sidecar injection will replace prometheus.io annotations present on the pod
and redirect them towards Istio agent, which will then merge metrics of from the application with Istio metrics.
This relies on the annotations prometheus.io/scrape , prometheus.io/port , and
prometheus.io/path annotations.
If you are running a separately managed Envoy with an Istio sidecar, this may cause issues, as the metrics will collide.
In this case, it is recommended to disable aggregation on that deployment with the
prometheus.istio.io/merge-metrics: "false" annotation.
If not specified, this will be enabled by default.
|
No
|
extensionProviders |
ExtensionProvider[] |
Defines a list of extension providers that extend Istio’s functionality. For example, the AuthorizationPolicy
can be used with an extension provider to delegate the authorization decision to a custom authorization system.
|
No
|
defaultProviders |
DefaultProviders |
Specifies extension providers to use by default in Istio configuration resources.
|
No
|
discoverySelectors |
LabelSelector[] |
A list of Kubernetes selectors that specify the set of namespaces that Istio considers when
computing configuration updates for sidecars. This can be used to reduce Istio’s computational load
by limiting the number of entities (including services, pods, and endpoints) that are watched and processed.
If omitted, Istio will use the default behavior of processing all namespaces in the cluster.
Elements in the list are disjunctive (OR semantics), i.e. a namespace will be included if it matches any selector.
The following example selects any namespace that matches either below:
- The namespace has both of these labels:
env: prod and region: us-east1
- The namespace has label
app equal to cassandra or spark .
discoverySelectors:
- matchLabels:
env: prod
region: us-east1
- matchExpressions:
- key: app
operator: In
values:
- cassandra
- spark
Refer to the Kubernetes selector docs
for additional detail on selector semantics.
|
No
|
pathNormalization |
ProxyPathNormalization |
ProxyPathNormalization configures how URL paths in incoming and outgoing HTTP requests are
normalized by the sidecars and gateways.
The normalized paths will be used in all aspects through the requests’ lifetime on the
sidecars and gateways, which includes routing decisions in outbound direction (client proxy),
authorization policy match and enforcement in inbound direction (server proxy), and the URL
path proxied to the upstream service.
If not set, the NormalizationType.DEFAULT configuration will be used.
|
No
|
defaultHttpRetryPolicy |
HTTPRetry |
Configure the default HTTP retry policy.
The default number of retry attempts is set at 2 for these errors:
“connect-failure,refused-stream,unavailable,cancelled,retriable-status-codes”.
Setting the number of attempts to 0 disables retry policy globally.
This setting can be overridden on a per-host basis using the Virtual Service
API.
All settings in the retry policy except perTryTimeout can currently be
configured globally via this field.
|
No
|
meshMTLS |
TLSConfig |
The below configuration parameters can be used to specify TLSConfig for mesh traffic.
For example, a user could enable min TLS version for ISTIO_MUTUAL traffic and specify a curve for non ISTIO_MUTUAL traffic like below:
meshConfig:
meshMTLS:
minProtocolVersion: TLSV1_3
tlsDefaults:
Note: applicable only for non ISTIO_MUTUAL scenarios
ecdhCurves:
- P-256
- P-512
Configuration of mTLS for traffic between workloads with ISTIO_MUTUAL TLS traffic.
Note: Mesh mTLS does not respect ECDH curves.
|
No
|
tlsDefaults |
TLSConfig |
Configuration of TLS for all traffic except for ISTIO_MUTUAL mode.
Currently, this supports configuration of ecdhCurves and cipherSuites only.
For ISTIO_MUTUAL TLS settings, use meshMTLS configuration.
|
No
|
LabelSelector
A label selector requirement is a selector that contains values, a key, and an operator that
relates the key and values.
Copied from Kubernetes to avoid expensive dependency on Kubernetes libraries.
Field |
Type |
Description |
Required |
matchLabels |
map<string, string> |
matchLabels is a map of {key,value} pairs. A single {key,value} in the matchLabels
map is equivalent to an element of matchExpressions, whose key field is “key”, the
operator is “In”, and the values array contains only “value”. The requirements are ANDed.
|
No
|
matchExpressions |
LabelSelectorRequirement[] |
matchExpressions is a list of label selector requirements. The requirements are ANDed.
|
No
|
LabelSelectorRequirement
A label selector requirement is a selector that contains values, a key, and an operator that
relates the key and values.
Copied from Kubernetes to avoid expensive dependency on Kubernetes libraries.
Field |
Type |
Description |
Required |
key |
string |
key is the label key that the selector applies to.
|
No
|
operator |
string |
operator represents a key’s relationship to a set of values.
Valid operators are In, NotIn, Exists and DoesNotExist.
|
No
|
values |
string[] |
values is an array of string values. If the operator is In or NotIn,
the values array must be non-empty. If the operator is Exists or DoesNotExist,
the values array must be empty. This array is replaced during a strategic
merge patch.
|
No
|
ConfigSource
ConfigSource describes information about a configuration store inside a
mesh. A single control plane instance can interact with one or more data
sources.
Field |
Type |
Description |
Required |
address |
string |
Address of the server implementing the Istio Mesh Configuration
protocol (MCP). Can be IP address or a fully qualified DNS name.
Use xds:// to specify a grpc-based xds backend, k8s:// to specify a k8s controller or
fs:/// to specify a file-based backend with absolute path to the directory.
|
No
|
tlsSettings |
ClientTLSSettings |
Use the tlsSettings to specify the tls mode to use. If the MCP server
uses Istio mutual TLS and shares the root CA with Pilot, specify the TLS
mode as ISTIO_MUTUAL .
|
No
|
subscribedResources |
Resource[] |
Describes the source of configuration, if nothing is specified default is MCP
|
No
|
MeshConfig.OutboundTrafficPolicy
OutboundTrafficPolicy
sets the default behavior of the sidecar for
handling unknown outbound traffic from the application.
Field |
Type |
Description |
Required |
mode |
Mode |
|
No
|
MeshConfig.InboundTrafficPolicy
Field |
Type |
Description |
Required |
mode |
Mode |
|
No
|
MeshConfig.CertificateData
Field |
Type |
Description |
Required |
pem |
string (oneof) |
The PEM data of the certificate.
|
No
|
spiffeBundleUrl |
string (oneof) |
The SPIFFE bundle endpoint URL that complies to:
https://github.com/spiffe/spiffe/blob/master/standards/SPIFFE_Trust_Domain_and_Bundle.md#the-spiffe-trust-domain-and-bundle
The endpoint should support authentication based on Web PKI:
https://github.com/spiffe/spiffe/blob/master/standards/SPIFFE_Trust_Domain_and_Bundle.md#521-web-pki
The certificate is retrieved from the endpoint.
|
No
|
certSigners |
string[] |
Optional. Specify the kubernetes signers (External CA) that use this trustAnchor
when Istiod is acting as RA(registration authority)
If set, they are used for these signers. Otherwise, this trustAnchor is used for all signers.
|
No
|
trustDomains |
string[] |
Optional. Specify the list of trust domains to which this trustAnchor data belongs.
If set, they are used for these trust domains. Otherwise, this trustAnchor is used for default trust domain
and its aliases.
Note that we can have multiple trustAnchor data for a same trustDomain.
In that case, trustAnchors with a same trust domain will be merged and used together to verify peer certificates.
If neither certSigners nor trustDomains is set, this trustAnchor is used for all trust domains and all signers.
If only trustDomains is set, this trustAnchor is used for these trustDomains and all signers.
If only certSigners is set, this trustAnchor is used for these certSigners and all trust domains.
If both certSigners and trustDomains is set, this trustAnchor is only used for these signers and trust domains.
|
No
|
MeshConfig.CA
Field |
Type |
Description |
Required |
address |
string |
REQUIRED. Address of the CA server implementing the Istio CA gRPC API.
Can be IP address or a fully qualified DNS name with port
Eg: custom-ca.default.svc.cluster.local:8932, 192.168.23.2:9000
|
No
|
tlsSettings |
ClientTLSSettings |
Use the tlsSettings to specify the tls mode to use.
Regarding tlsSettings:
- DISABLE MODE is legitimate for the case Istiod is making the request via an Envoy sidecar.
DISABLE MODE can also be used for testing
- TLS MUTUAL MODE be on by default. If the CA certificates
(cert bundle to verify the CA server’s certificate) is omitted, Istiod will
use the system root certs to verify the CA server’s certificate.
|
No
|
requestTimeout |
Duration |
timeout for forward CSR requests from Istiod to External CA
Default: 10s
|
No
|
istiodSide |
bool |
Use istiodSide to specify CA Server integrate to Istiod side or Agent side
Default: true
|
No
|
MeshConfig.ExtensionProvider
MeshConfig.DefaultProviders
Holds the name references to the providers that will be used by default
in other Istio configuration resources if the provider is not specified.
These names must match a provider defined in extensionProviders
that is
one of the supported tracing providers.
Field |
Type |
Description |
Required |
tracing |
string[] |
Name of the default provider(s) for tracing.
|
No
|
metrics |
string[] |
Name of the default provider(s) for metrics.
|
No
|
accessLogging |
string[] |
Name of the default provider(s) for access logging.
|
No
|
MeshConfig.ProxyPathNormalization
MeshConfig.TLSConfig
Field |
Type |
Description |
Required |
minProtocolVersion |
TLSProtocol |
Optional: the minimum TLS protocol version. The default minimum
TLS version will be TLS 1.2. As servers may not be Envoy and be
set to TLS 1.2 (e.g., workloads using mTLS without sidecars), the
minimum TLS version for clients may also be TLS 1.2.
In the current Istio implementation, the maximum TLS protocol version
is TLS 1.3.
|
No
|
ecdhCurves |
string[] |
Optional: If specified, the TLS connection will only support the specified ECDH curves for the DH key exchange.
If not specified, the default curves enforced by Envoy will be used. For details about the default curves, refer to
Ecdh Curves.
|
No
|
cipherSuites |
string[] |
Optional: If specified, the TLS connection will only support the specified cipher list when negotiating TLS 1.0-1.2.
If not specified, the following cipher suites will be used:
ECDHE-ECDSA-AES256-GCM-SHA384
ECDHE-RSA-AES256-GCM-SHA384
ECDHE-ECDSA-AES128-GCM-SHA256
ECDHE-RSA-AES128-GCM-SHA256
AES256-GCM-SHA384
AES128-GCM-SHA256
|
No
|
MeshConfig.ServiceSettings.Settings
Settings for the selected services.
Field |
Type |
Description |
Required |
clusterLocal |
bool |
If true, specifies that the client and service endpoints must reside in the same cluster.
By default, in multi-cluster deployments, the Istio control plane assumes all service
endpoints to be reachable from any client in any of the clusters which are part of the
mesh. This configuration option limits the set of service endpoints visible to a client
to be cluster scoped.
There are some common scenarios when this can be useful:
- A service (or group of services) is inherently local to the cluster and has local storage
for that cluster. For example, the kube-system namespace (e.g. the Kube API Server).
- A mesh administrator wants to slowly migrate services to Istio. They might start by first
having services cluster-local and then slowly transition them to mesh-wide. They could do
this service-by-service (e.g. mysvc.myns.svc.cluster.local) or as a group
(e.g. *.myns.svc.cluster.local).
By default Istio will consider kubernetes.default.svc (i.e. the API Server) as well as all
services in the kube-system namespace to be cluster-local, unless explicitly overridden here.
|
No
|
MeshConfig.ExtensionProvider.EnvoyExternalAuthorizationRequestBody
Field |
Type |
Description |
Required |
maxRequestBytes |
uint32 |
Sets the maximum size of a message body that the ext-authz filter will hold in memory.
If maxRequestBytes is reached, and allowPartialMessage is false, Envoy will return a 413 (Payload Too Large).
Otherwise the request will be sent to the provider with a partial message.
Note that this setting will have precedence over the failOpen field, the 413 will be returned even when the
failOpen is set to true.
|
No
|
allowPartialMessage |
bool |
When this field is true, ext-authz filter will buffer the message until maxRequestBytes is reached.
The authorization request will be dispatched and no 413 HTTP error will be returned by the filter.
A “x-envoy-auth-partial-body: false|true” metadata header will be added to the authorization request message
indicating if the body data is partial.
|
No
|
packAsBytes |
bool |
If true, the body sent to the external authorization service in the gRPC authorization request is set with raw bytes
in the raw_body field.
Otherwise, it will be filled with UTF-8 string in the body field.
This field only works with the envoyExtAuthzGrpc provider and has no effect for the envoyExtAuthzHttp provider.
|
No
|
MeshConfig.ExtensionProvider.EnvoyExternalAuthorizationHttpProvider
Field |
Type |
Description |
Required |
service |
string |
REQUIRED. Specifies the service that implements the Envoy ext_authz HTTP authorization service.
The format is [<Namespace>/]<Hostname> . The specification of <Namespace> is required only when it is insufficient
to unambiguously resolve a service in the service registry. The <Hostname> is a fully qualified host name of a
service defined by the Kubernetes service or ServiceEntry.
Example: “my-ext-authz.foo.svc.cluster.local” or “bar/my-ext-authz.example.com”.
|
No
|
port |
uint32 |
REQUIRED. Specifies the port of the service.
|
No
|
timeout |
Duration |
The maximum duration that the proxy will wait for a response from the provider (default timeout: 600s).
When this timeout condition is met, the proxy marks the communication to the authorization service as failure.
In this situation, the response sent back to the client will depend on the configured failOpen field.
|
No
|
pathPrefix |
string |
Sets a prefix to the value of authorization request header Path.
For example, setting this to “/check” for an original user request at path “/admin” will cause the
authorization check request to be sent to the authorization service at the path “/check/admin” instead of “/admin”.
|
No
|
failOpen |
bool |
If true, the user request will be allowed even if the communication with the authorization service has failed,
or if the authorization service has returned a HTTP 5xx error.
Default is false and the request will be rejected with “Forbidden” response.
|
No
|
statusOnError |
string |
Sets the HTTP status that is returned to the client when there is a network error to the authorization service.
The default status is “403” (HTTP Forbidden).
|
No
|
includeRequestBodyInCheck |
EnvoyExternalAuthorizationRequestBody |
If set, the client request body will be included in the authorization request sent to the authorization service.
|
No
|
MeshConfig.ExtensionProvider.EnvoyExternalAuthorizationGrpcProvider
Field |
Type |
Description |
Required |
service |
string |
REQUIRED. Specifies the service that implements the Envoy ext_authz gRPC authorization service.
The format is [<Namespace>/]<Hostname> . The specification of <Namespace> is required only when it is insufficient
to unambiguously resolve a service in the service registry. The <Hostname> is a fully qualified host name of a
service defined by the Kubernetes service or ServiceEntry.
Example: “my-ext-authz.foo.svc.cluster.local” or “bar/my-ext-authz.example.com”.
|
No
|
port |
uint32 |
REQUIRED. Specifies the port of the service.
|
No
|
timeout |
Duration |
The maximum duration that the proxy will wait for a response from the provider, this is the timeout for a specific request (default timeout: 600s).
When this timeout condition is met, the proxy marks the communication to the authorization service as failure.
In this situation, the response sent back to the client will depend on the configured failOpen field.
|
No
|
failOpen |
bool |
If true, the HTTP request or TCP connection will be allowed even if the communication with the authorization service has failed,
or if the authorization service has returned a HTTP 5xx error.
Default is false. For HTTP request, it will be rejected with 403 (HTTP Forbidden). For TCP connection, it will be closed immediately.
|
No
|
statusOnError |
string |
Sets the HTTP status that is returned to the client when there is a network error to the authorization service.
The default status is “403” (HTTP Forbidden).
|
No
|
includeRequestBodyInCheck |
EnvoyExternalAuthorizationRequestBody |
If set, the client request body will be included in the authorization request sent to the authorization service.
|
No
|
MeshConfig.ExtensionProvider.ZipkinTracingProvider
Defines configuration for a Zipkin tracer.
Field |
Type |
Description |
Required |
service |
string |
REQUIRED. Specifies the service that the Zipkin API.
The format is [<Namespace>/]<Hostname> . The specification of <Namespace> is required only when it is insufficient
to unambiguously resolve a service in the service registry. The <Hostname> is a fully qualified host name of a
service defined by the Kubernetes service or ServiceEntry.
Example: “zipkin.default.svc.cluster.local” or “bar/zipkin.example.com”.
|
No
|
port |
uint32 |
REQUIRED. Specifies the port of the service.
|
No
|
maxTagLength |
uint32 |
Optional. Controls the overall path length allowed in a reported span.
NOTE: currently only controls max length of the path tag.
|
No
|
enable64bitTraceId |
bool |
Optional. A 128 bit trace id will be used in Istio.
If true, will result in a 64 bit trace id being used.
|
No
|
path |
string |
Optional. Specifies the endpoint of Zipkin API.
The default value is “/api/v2/spans”.
|
No
|
MeshConfig.ExtensionProvider.LightstepTracingProvider
Defines configuration for a Lightstep tracer.
Note: Lightstep has moved to OpenTelemetry-based integrations. Istio 1.15+
will generate OpenTelemetry-compatible configuration when using this option.
Field |
Type |
Description |
Required |
service |
string |
REQUIRED. Specifies the service for the Lightstep collector.
The format is [<Namespace>/]<Hostname> . The specification of <Namespace> is required only when it is insufficient
to unambiguously resolve a service in the service registry. The <Hostname> is a fully qualified host name of a
service defined by the Kubernetes service or ServiceEntry.
Example: “lightstep.default.svc.cluster.local” or “bar/lightstep.example.com”.
|
No
|
port |
uint32 |
REQUIRED. Specifies the port of the service.
|
No
|
accessToken |
string |
The Lightstep access token.
|
No
|
maxTagLength |
uint32 |
Optional. Controls the overall path length allowed in a reported span.
NOTE: currently only controls max length of the path tag.
|
No
|
MeshConfig.ExtensionProvider.DatadogTracingProvider
Defines configuration for a Datadog tracer.
Field |
Type |
Description |
Required |
service |
string |
REQUIRED. Specifies the service for the Datadog agent.
The format is [<Namespace>/]<Hostname> . The specification of <Namespace> is required only when it is insufficient
to unambiguously resolve a service in the service registry. The <Hostname> is a fully qualified host name of a
service defined by the Kubernetes service or ServiceEntry.
Example: “datadog.default.svc.cluster.local” or “bar/datadog.example.com”.
|
No
|
port |
uint32 |
REQUIRED. Specifies the port of the service.
|
No
|
maxTagLength |
uint32 |
Optional. Controls the overall path length allowed in a reported span.
NOTE: currently only controls max length of the path tag.
|
No
|
MeshConfig.ExtensionProvider.SkyWalkingTracingProvider
Defines configuration for a SkyWalking tracer.
Field |
Type |
Description |
Required |
service |
string |
REQUIRED. Specifies the service for the SkyWalking receiver.
The format is [<Namespace>/]<Hostname> . The specification of <Namespace> is required only when it is insufficient
to unambiguously resolve a service in the service registry. The <Hostname> is a fully qualified host name of a
service defined by the Kubernetes service or ServiceEntry.
Example: “skywalking.default.svc.cluster.local” or “bar/skywalking.example.com”.
|
No
|
port |
uint32 |
REQUIRED. Specifies the port of the service.
|
No
|
accessToken |
string |
Optional. The SkyWalking OAP access token.
|
No
|
MeshConfig.ExtensionProvider.StackdriverProvider
Defines configuration for Stackdriver.
WARNING: Stackdriver tracing uses OpenCensus configuration under the hood and, as a result, cannot be used
alongside any OpenCensus provider configuration. This is due to a limitation in the implementation of OpenCensus
driver in Envoy.
Field |
Type |
Description |
Required |
maxTagLength |
uint32 |
Optional. Controls the overall path length allowed in a reported span.
NOTE: currently only controls max length of the path tag.
|
No
|
logging |
Logging |
Optional. Controls Stackdriver logging behavior.
|
No
|
MeshConfig.ExtensionProvider.OpenCensusAgentTracingProvider
Defines configuration for an OpenCensus tracer writing to an OpenCensus backend.
WARNING: OpenCensusAgentTracingProviders should be used with extreme care. Configuration of
OpenCensus providers CANNOT be changed during the course of proxy’s lifetime due to a limitation
in the implementation of OpenCensus driver in Envoy. This means only a single provider configuration
may be used for OpenCensus at any given time for a proxy or group of proxies AND that any change to the provider
configuration MUST be accompanied by a restart of all proxies that will use that configuration.
NOTE: Stackdriver tracing uses OpenCensus configuration under the hood and, as a result, cannot be used
alongside OpenCensus provider configuration.
Field |
Type |
Description |
Required |
service |
string |
REQUIRED. Specifies the service for the OpenCensusAgent.
The format is [<Namespace>/]<Hostname> . The specification of <Namespace> is required only when it is insufficient
to unambiguously resolve a service in the service registry. The <Hostname> is a fully qualified host name of a
service defined by the Kubernetes service or ServiceEntry.
Example: “ocagent.default.svc.cluster.local” or “bar/ocagent.example.com”.
|
No
|
port |
uint32 |
REQUIRED. Specifies the port of the service.
|
No
|
context |
TraceContext[] |
Specifies the set of context propagation headers used for distributed
tracing. Default is ["W3C_TRACE_CONTEXT"] . If multiple values are specified,
the proxy will attempt to read each header for each request and will
write all headers.
|
No
|
maxTagLength |
uint32 |
Optional. Controls the overall path length allowed in a reported span.
NOTE: currently only controls max length of the path tag.
|
No
|
MeshConfig.ExtensionProvider.PrometheusMetricsProvider
MeshConfig.ExtensionProvider.EnvoyFileAccessLogProvider
Defines configuration for Envoy-based access logging that writes to
local files (and/or standard streams).
Field |
Type |
Description |
Required |
path |
string |
Path to a local file to write the access log entries.
This may be used to write to streams, via /dev/stderr and /dev/stdout
If unspecified, defaults to /dev/stdout .
|
No
|
logFormat |
LogFormat |
Optional. Allows overriding of the default access log format.
|
No
|
MeshConfig.ExtensionProvider.EnvoyHttpGrpcV3LogProvider
Defines configuration for an Envoy Access Logging Service
integration for HTTP traffic.
Field |
Type |
Description |
Required |
service |
string |
REQUIRED. Specifies the service that implements the Envoy ALS gRPC authorization service.
The format is [<Namespace>/]<Hostname> . The specification of <Namespace> is required only when it is insufficient
to unambiguously resolve a service in the service registry. The <Hostname> is a fully qualified host name of a
service defined by the Kubernetes service or ServiceEntry.
Example: “envoy-als.foo.svc.cluster.local” or “bar/envoy-als.example.com”.
|
No
|
port |
uint32 |
REQUIRED. Specifies the port of the service.
|
No
|
logName |
string |
Optional. The friendly name of the access log.
Defaults:
- “http_envoy_accesslog”
- “listener_envoy_accesslog”
|
No
|
filterStateObjectsToLog |
string[] |
Optional. Additional filter state objects to log.
|
No
|
additionalResponseTrailersToLog |
string[] |
Optional. Additional response trailers to log.
|
No
|
MeshConfig.ExtensionProvider.EnvoyTcpGrpcV3LogProvider
Defines configuration for an Envoy Access Logging Service
integration for TCP traffic.
Field |
Type |
Description |
Required |
service |
string |
REQUIRED. Specifies the service that implements the Envoy ALS gRPC authorization service.
The format is [<Namespace>/]<Hostname> . The specification of <Namespace> is required only when it is insufficient
to unambiguously resolve a service in the service registry. The <Hostname> is a fully qualified host name of a
service defined by the Kubernetes service or ServiceEntry.
Example: “envoy-als.foo.svc.cluster.local” or “bar/envoy-als.example.com”.
|
No
|
port |
uint32 |
REQUIRED. Specifies the port of the service.
|
No
|
logName |
string |
Optional. The friendly name of the access log.
Defaults:
- “tcp_envoy_accesslog”
- “listener_envoy_accesslog”
|
No
|
filterStateObjectsToLog |
string[] |
Optional. Additional filter state objects to log.
|
No
|
MeshConfig.ExtensionProvider.EnvoyOpenTelemetryLogProvider
Defines configuration for an Envoy OpenTelemetry (gRPC) Access Log
Field |
Type |
Description |
Required |
service |
string |
REQUIRED. Specifies the service that implements the Envoy ALS gRPC authorization service.
The format is [<Namespace>/]<Hostname> . The specification of <Namespace> is required only when it is insufficient
to unambiguously resolve a service in the service registry. The <Hostname> is a fully qualified host name of a
service defined by the Kubernetes service or ServiceEntry.
Example: “envoy-als.foo.svc.cluster.local” or “bar/envoy-als.example.com”.
|
No
|
port |
uint32 |
REQUIRED. Specifies the port of the service.
|
No
|
logName |
string |
Optional. The friendly name of the access log.
Defaults:
|
No
|
logFormat |
LogFormat |
Optional. Format for the proxy access log
Empty value results in proxy’s default access log format, following Envoy access logging formatting.
|
No
|
MeshConfig.ExtensionProvider.OpenTelemetryTracingProvider
Defines configuration for an OpenTelemetry tracing backend. Istio 1.16.1 or higher is needed.
Field |
Type |
Description |
Required |
service |
string |
REQUIRED. Specifies the OpenTelemetry endpoint that will receive OTLP traces.
The format is [<Namespace>/]<Hostname> . The specification of <Namespace> is required only when it is insufficient
to unambiguously resolve a service in the service registry. The <Hostname> is a fully qualified host name of a
service defined by the Kubernetes service or ServiceEntry.
Example: “otlp.default.svc.cluster.local” or “bar/otlp.example.com”.
|
No
|
port |
uint32 |
REQUIRED. Specifies the port of the service.
|
No
|
maxTagLength |
uint32 |
Optional. Controls the overall path length allowed in a reported span.
NOTE: currently only controls max length of the path tag.
|
No
|
http |
HttpService |
Optional. Specifies the configuration for exporting OTLP traces via HTTP.
When empty, traces will be exported via gRPC.
The following example shows how to configure the OpenTelemetry ExtensionProvider to export via HTTP:
- Add/change the OpenTelemetry extension provider in
MeshConfig
- name: otel-tracing
opentelemetry:
port: 443
service: my.olly-backend.com
http:
path: "/api/otlp/traces"
timeout: 10s
headers:
- name: "my-custom-header"
value: "some value"
- Deploy a
ServiceEntry for the observability back-end
apiVersion: networking.istio.io/v1alpha3
kind: ServiceEntry
metadata:
name: my-olly-backend
spec:
hosts:
- my.olly-backend.com
ports:
- number: 443
name: https-port
protocol: HTTPS
resolution: DNS
location: MESH_EXTERNAL
---
apiVersion: networking.istio.io/v1alpha3
kind: DestinationRule
metadata:
name: my-olly-backend
spec:
host: my.olly-backend.com
trafficPolicy:
portLevelSettings:
- port:
number: 443
tls:
mode: SIMPLE
|
No
|
grpc |
GrpcService |
Optional. Specifies the configuration for exporting OTLP traces via GRPC.
When empty, traces will check whether HTTP is set.
If not, traces will use default GRPC configurations.
The following example shows how to configure the OpenTelemetry ExtensionProvider to export via GRPC:
- Add/change the OpenTelemetry extension provider in
MeshConfig
- name: opentelemetry
opentelemetry:
port: 8090
service: tracing.example.com
grpc:
timeout: 10s
initialMetadata:
- name: "Authentication"
value: "token-xxxxx"
- Deploy a
ServiceEntry for the observability back-end
apiVersion: networking.istio.io/v1alpha3
kind: ServiceEntry
metadata:
name: tracing-grpc
spec:
hosts:
- tracing.example.com
ports:
- number: 8090
name: grpc-port
protocol: GRPC
resolution: DNS
location: MESH_EXTERNAL
|
No
|
resourceDetectors |
ResourceDetectors |
Optional. Specifies Resource Detectors
to be used by the OpenTelemetry Tracer. When multiple resources are provided, they are merged
according to the OpenTelemetry Resource specification.
The following example shows how to configure the Environment Resource Detector, that will
read the attributes from the environment variable OTEL_RESOURCE_ATTRIBUTES :
- name: otel-tracing
opentelemetry:
port: 443
service: my.olly-backend.com
resourceDetectors:
environment: {}
|
No
|
dynatraceSampler |
DynatraceSampler (oneof) |
The Dynatrace adaptive traffic management (ATM) sampler.
Example configuration:
- name: otel-tracing
opentelemetry:
port: 443
service: "{your-environment-id}.live.dynatrace.com"
http:
path: "/api/v2/otlp/v1/traces"
timeout: 10s
headers:
- name: "Authorization"
value: "Api-Token dt0c01."
resourceDetectors:
dynatrace: {}
dynatraceSampler:
tenant: "{your-environment-id}"
clusterId: 1234
|
No
|
MeshConfig.ExtensionProvider.HttpService
Defines configuration for an HTTP service that can be used by an Extension Provider.
that does communication via HTTP.
Field |
Type |
Description |
Required |
path |
string |
REQUIRED. Specifies the path on the service.
|
No
|
timeout |
Duration |
Optional. Specifies the timeout for the HTTP request.
If not specified, the default is 3s.
|
No
|
Field |
Type |
Description |
Required |
MeshConfig.ExtensionProvider.ResourceDetectors
MeshConfig.ExtensionProvider.GrpcService
Defines configuration for an GRPC service that can be used by an Extension Provider.
that does communication via GRPC.
Field |
Type |
Description |
Required |
timeout |
Duration |
Optional. Specifies the timeout for the GRPC request.
|
No
|
initialMetadata |
HttpHeader[] |
Optional. Additional metadata to include in streams initiated to the GrpcService. This can be used for
scenarios in which additional ad hoc authorization headers (e.g. “x-foo-bar: baz-key“) are to
be injected.
|
No
|
MeshConfig.ExtensionProvider.AggregateProvider
The following example configures zipkin-intranet provider for cluster-a, and cluster-c
opentelemetry provider for cluster-b, zipkin provider for the rest.
aggregate:
defaultProvider:
name: zipkin
uniqueProviders:
- provider:
name: zipkin-intranet
clusters:
- id: cluster-a
- id: cluster-c
- provider:
name: opentelemetry
clusters:
- id: cluster-b
- id: cluster-c
NOTE: If a cluster refered different providers, the first provider refered will be used.
MeshConfig.ExtensionProvider.StackdriverProvider.Logging
Field |
Type |
Description |
Required |
labels |
map<string, string> |
Collection of tag names and tag expressions to include in the log
entry. Conflicts are resolved by the tag name by overriding previously
supplied values.
Example:
labels:
path: request.url_path
foo: request.headers[‘x-foo’]
|
No
|
Field |
Type |
Description |
Required |
text |
string (oneof) |
Textual format for the envoy access logs. Envoy command operators may be
used in the format. The format string documentation
provides more information.
NOTE: Istio will insert a newline (’\n’) on all formats (if missing).
Example: text: "%LOCAL_REPLY_BODY%:%RESPONSE_CODE%:path=%REQ(:path)%"
|
No
|
labels |
Struct (oneof) |
JSON structured format for the envoy access logs. Envoy command operators
can be used as values for fields within the Struct. Values are rendered
as strings, numbers, or boolean values, as appropriate
(see: format dictionaries). Nested JSON is
supported for some command operators (e.g. FILTER_STATE or DYNAMIC_METADATA ).
Use labels: {} for default envoy JSON log format.
Example:
labels:
status: "%RESPONSE_CODE%"
message: "%LOCAL_REPLY_BODY%"
|
No
|
Field |
Type |
Description |
Required |
text |
string |
Textual format for the envoy access logs. Envoy command operators may be
used in the format. The format string documentation
provides more information.
Alias to body field in Open Telemetry
Example: text: "%LOCAL_REPLY_BODY%:%RESPONSE_CODE%:path=%REQ(:path)%"
|
No
|
labels |
Struct |
Optional. Additional attributes that describe the specific event occurrence.
Structured format for the envoy access logs. Envoy command operators
can be used as values for fields within the Struct. Values are rendered
as strings, numbers, or boolean values, as appropriate
(see: format dictionaries). Nested JSON is
supported for some command operators (e.g. FILTER_STATE or DYNAMIC_METADATA).
Alias to attributes field in Open Telemetry
Example:
labels:
status: "%RESPONSE_CODE%"
message: "%LOCAL_REPLY_BODY%"
|
No
|
MeshConfig.ExtensionProvider.OpenTelemetryTracingProvider.DynatraceSampler
Field |
Type |
Description |
Required |
tenant |
string |
REQUIRED. The Dynatrace customer’s tenant identifier.
The value can be obtained from the Istio deployment page in Dynatrace.
|
No
|
clusterId |
int32 |
REQUIRED. The identifier of the cluster in the Dynatrace platform.
The cluster here is Dynatrace-specific concept and not related to the cluster concept in Istio/Envoy.
The value can be obtained from the Istio deployment page in Dynatrace.
|
No
|
rootSpansPerMinute |
uint32 |
Optional. Number of sampled spans per minute to be used
when the adaptive value cannot be obtained from the Dynatrace API.
A default value of 1000 is used when:
rootSpansPerMinute is unset
rootSpansPerMinute is set to 0
|
No
|
httpService |
DynatraceApi |
Optional. Dynatrace HTTP API to obtain sampling configuration.
When not provided, the Dynatrace Sampler will re-use the configuration from the OpenTelemetryTracingProvider HTTP Exporter
(service , port and http ), including the access token.
|
No
|
MeshConfig.ExtensionProvider.OpenTelemetryTracingProvider.DynatraceSampler.DynatraceApi
Field |
Type |
Description |
Required |
service |
string |
REQUIRED. Specifies the Dynatrace environment to obtain the sampling configuration.
The format is <Hostname> , where <Hostname> is the fully qualified Dynatrace environment
host name defined in the ServiceEntry.
Example: “{your-environment-id}.live.dynatrace.com”.
|
No
|
port |
uint32 |
REQUIRED. Specifies the port of the service.
|
No
|
http |
HttpService |
REQUIRED. Specifies sampling configuration URI.
|
No
|
MeshConfig.ExtensionProvider.ResourceDetectors.EnvironmentResourceDetector
OpenTelemetry Environment Resource Detector.
The resource detector reads attributes from the environment variable OTEL_RESOURCE_ATTRIBUTES
and adds them to the OpenTelemetry resource.
See: Resource specification
MeshConfig.ExtensionProvider.ResourceDetectors.DynatraceResourceDetector
MeshConfig.ExtensionProvider.AggregateProvider.UniqueProviderRef
Field |
Type |
Description |
Required |
provider |
ProviderRef |
REQUIRED. The unique provider to use when a proxy is matched.
|
No
|
clusters |
ClusterRef[] |
Optional. List of clusters that will use the provider.
|
No
|
MeshConfig.ExtensionProvider.AggregateProvider.ClusterRef
Field |
Type |
Description |
Required |
id |
string |
REQUIRE. Id of the cluster, will be used as proxy selector.
|
No
|
name |
string |
Optional. Name of the cluster, won’t be used as selector currently, just for more readability.
|
No
|
region |
string |
Optional. Region of the cluster, won’t be used as selector currently, just for more readability.
|
No
|
Tracing
Tracing defines configuration for the tracing performed by Envoy instances.
Topology
Topology describes the configuration for relative location of a proxy with
respect to intermediate trusted proxies and the client. These settings
control how the client attributes are retrieved from the incoming traffic by
the gateway proxy and propagated to the upstream services in the cluster.
Field |
Type |
Description |
Required |
numTrustedProxies |
uint32 |
Number of trusted proxies deployed in front of the Istio gateway proxy.
When this option is set to value N greater than zero, the trusted client
address is assumed to be the Nth address from the right end of the
X-Forwarded-For (XFF) header from the incoming request. If the
X-Forwarded-For (XFF) header is missing or has fewer than N addresses, the
gateway proxy falls back to using the immediate downstream connection’s
source address as the trusted client address.
Note that the gateway proxy will append the downstream connection’s source
address to the X-Forwarded-For (XFF) address and set the
X-Envoy-External-Address header to the trusted client address before
forwarding it to the upstream services in the cluster.
The default value of numTrustedProxies is 0.
See Envoy XFF
header handling for more details.
|
No
|
forwardClientCertDetails |
ForwardClientCertDetails |
Configures how the gateway proxy handles x-forwarded-client-cert (XFCC)
header in the incoming request.
|
No
|
proxyProtocol |
ProxyProtocolConfiguration |
Enables PROXY protocol for
downstream connections on a gateway.
|
No
|
xffTrustedCidrs |
string[] |
|
No
|
skipXffAppend |
BoolValue |
|
No
|
PrivateKeyProvider
PrivateKeyProvider defines private key configuration for gateways and sidecars. This can be configured
mesh wide or individual per-workload basis.
ProxyConfig
ProxyConfig defines variables for individual Envoy instances. This can be configured on a per-workload basis
as well as by the mesh-wide defaults.
To set the mesh wide defaults, configure the defaultConfig
section of meshConfig
. For example:
meshConfig:
defaultConfig:
discoveryAddress: istiod:15012
This can also be configured on a per-workload basis by configuring the proxy.istio.io/config
annotation on the pod. For example:
annotations:
proxy.istio.io/config: |
discoveryAddress: istiod:15012
If both are configured, the two are merged with per field semantics; the field set in annotation will fully replace the field from mesh config defaults.
This is different than a deep merge provided by protobuf.
For example, "tracing": { "sampling": 5 }
would completely override a setting configuring a tracing provider
such as "tracing": { "zipkin": { "address": "..." } }
.
Note: fields in ProxyConfig are not dynamically configured; changes will require restart of workloads to take effect.
Field |
Type |
Description |
Required |
configPath |
string |
Path to the generated configuration file directory.
Proxy agent generates the actual configuration and stores it in this directory.
|
No
|
binaryPath |
string |
Path to the proxy binary
|
No
|
serviceCluster |
string (oneof) |
Service cluster defines the name for the service_cluster 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.
|
No
|
tracingServiceName |
TracingServiceName (oneof) |
Used by Envoy proxies to assign the values for the service names in trace
spans.
|
No
|
drainDuration |
Duration |
The time in seconds that Envoy will drain connections during a hot
restart. MUST be >=1s (e.g., 1s/1m/1h)
Default drain duration is 45s .
|
No
|
discoveryAddress |
string |
Address of the discovery service exposing xDS with mTLS connection.
The inject configuration may override this value.
|
No
|
statsdUdpAddress |
string |
IP Address and Port of a statsd UDP listener (e.g. 10.75.241.127:9125 ).
|
No
|
proxyAdminPort |
int32 |
Port on which Envoy should listen for administrative commands.
Default port is 15000 .
|
No
|
controlPlaneAuthPolicy |
AuthenticationPolicy |
AuthenticationPolicy defines how the proxy is authenticated when it connects to the control plane.
Default is set to MUTUAL_TLS .
|
No
|
customConfigFile |
string |
File path of custom proxy configuration, currently used by proxies
in front of Mixer and Pilot.
|
No
|
statNameLength |
int32 |
Maximum length of name field in Envoy’s metrics. The length of the name field
is determined by the length of a name field in a service and the set of labels that
comprise a particular version of the service. The default value is set to 189 characters.
Envoy’s internal metrics take up 67 characters, for a total of 256 character name per metric.
Increase the value of this field if you find that the metrics from Envoys are truncated.
|
No
|
concurrency |
Int32Value |
The number of worker threads to run.
If unset, which is recommended, this will be automatically determined based on CPU requests/limits.
If set to 0, all cores on the machine will be used, ignoring CPU requests or limits. This can lead to major performance
issues if CPU limits are also set.
|
No
|
proxyBootstrapTemplatePath |
string |
Path to the proxy bootstrap template file
|
No
|
interceptionMode |
InboundInterceptionMode |
The mode used to redirect inbound traffic to Envoy.
|
No
|
tracing |
Tracing |
Tracing configuration to be used by the proxy.
|
No
|
envoyAccessLogService |
RemoteService |
Address of the service to which access logs from Envoys should be
sent. (e.g. accesslog-service:15000 ). See Access Log
Service
for details about Envoy’s gRPC Access Log Service API.
|
No
|
envoyMetricsService |
RemoteService |
Address of the Envoy Metrics Service implementation (e.g. metrics-service:15000 ).
See Metric Service
for details about Envoy’s Metrics Service API.
|
No
|
proxyMetadata |
map<string, string> |
Additional environment variables for the proxy.
Names starting with ISTIO_META_ will be included in the generated bootstrap and sent to the XDS server.
|
No
|
runtimeValues |
map<string, string> |
Envoy runtime configuration to set during bootstrapping.
This enables setting experimental, unsafe, unsupported, and deprecated features that should be used with extreme caution.
|
No
|
statusPort |
int32 |
Port on which the agent should listen for administrative commands such as readiness probe.
Default is set to port 15020 .
|
No
|
gatewayTopology |
Topology |
Topology encapsulates the configuration which describes where the proxy is
located i.e. behind a (or N) trusted proxy (proxies) or directly exposed
to the internet. This configuration only effects gateways and is applied
to all the gateways in the cluster unless overridden via annotations of the
gateway workloads.
|
No
|
terminationDrainDuration |
Duration |
The amount of time allowed for connections to complete on proxy shutdown.
On receiving SIGTERM or SIGINT , istio-agent tells the active Envoy to start gracefully draining,
discouraging any new connections and allowing existing connections to complete. It then
sleeps for the terminationDrainDuration and then kills any remaining active Envoy processes.
If not set, a default of 5s will be applied.
|
No
|
meshId |
string |
The unique identifier for the service mesh
All control planes running in the same service mesh should specify the same mesh ID.
Mesh ID is used to label telemetry reports for cases where telemetry from multiple meshes is mixed together.
|
No
|
readinessProbe |
ReadinessProbe |
VM Health Checking readiness probe. This health check config exactly mirrors the
kubernetes readiness probe configuration both in schema and logic.
Only one health check method of 3 can be set at a time.
|
No
|
proxyStatsMatcher |
ProxyStatsMatcher |
Proxy stats matcher defines configuration for reporting custom Envoy stats.
To reduce memory and CPU overhead from Envoy stats system, Istio proxies by
default create and expose only a subset of Envoy stats. This option is to
control creation of additional Envoy stats with prefix, suffix, and regex
expressions match on the name of the stats. This replaces the stats
inclusion annotations
(sidecar.istio.io/statsInclusionPrefixes ,
sidecar.istio.io/statsInclusionRegexps , and
sidecar.istio.io/statsInclusionSuffixes ). For example, to enable stats
for circuit breakers, request retries, upstream connections, and request timeouts,
you can specify stats matcher as follows:
proxyStatsMatcher:
inclusionRegexps:
- .*outlier_detection.*
- .*upstream_rq_retry.*
- .*upstream_cx_.*
inclusionSuffixes:
- upstream_rq_timeout
Note including more Envoy stats might increase number of time series
collected by prometheus significantly. Care needs to be taken on Prometheus
resource provision and configuration to reduce cardinality.
|
No
|
holdApplicationUntilProxyStarts |
BoolValue |
Boolean flag for enabling/disabling the holdApplicationUntilProxyStarts behavior.
This feature adds hooks to delay application startup until the pod proxy
is ready to accept traffic, mitigating some startup race conditions.
Default value is ‘false’.
|
No
|
caCertificatesPem |
string[] |
The PEM data of the extra root certificates for workload-to-workload communication.
This includes the certificates defined in MeshConfig and any other certificates that Istiod uses as CA.
The plugin certificates (the ‘cacerts’ secret), self-signed certificates (the ‘istio-ca-secret’ secret)
are added automatically by Istiod.
|
No
|
image |
ProxyImage |
Specifies the details of the proxy image.
|
No
|
privateKeyProvider |
PrivateKeyProvider |
Specifies the details of the Private Key Provider configuration for gateway and sidecar proxies.
|
No
|
httpsHttp2Disabled |
bool |
Boolean flag for enabling/disabling the http2 protocol
|
No
|
zipkinAddress |
string |
Address of the Zipkin service (e.g. zipkin:9411).
DEPRECATED: Use tracing instead.
|
No
|
RemoteService
Field |
Type |
Description |
Required |
address |
string |
Address of a remove service used for various purposes (access log
receiver, metrics receiver, etc.). Can be IP address or a fully
qualified DNS name.
|
No
|
tlsSettings |
ClientTLSSettings |
Use the tlsSettings to specify the tls mode to use. If the remote service
uses Istio mutual TLS and shares the root CA with Pilot, specify the TLS
mode as ISTIO_MUTUAL .
|
No
|
tcpKeepalive |
TcpKeepalive |
If set then set SO_KEEPALIVE on the socket to enable TCP Keepalives.
|
No
|
Tracing.Zipkin
Zipkin defines configuration for a Zipkin tracer.
Field |
Type |
Description |
Required |
address |
string |
Address of the Zipkin service (e.g. zipkin:9411).
|
No
|
Tracing.Datadog
Datadog defines configuration for a Datadog tracer.
Field |
Type |
Description |
Required |
address |
string |
Address of the Datadog Agent.
|
No
|
Tracing.Stackdriver
Tracing.OpenCensusAgent
OpenCensusAgent defines configuration for an OpenCensus tracer writing to
an OpenCensus agent backend. See
Envoy’s OpenCensus trace configuration
and
OpenCensus trace config
for details.
Field |
Type |
Description |
Required |
address |
string |
gRPC address for the OpenCensus agent (e.g. dns://authority/host:port or
unix:path). See gRPC naming
docs for
details.
|
No
|
context |
TraceContext[] |
Specifies the set of context propagation headers used for distributed
tracing. Default is ["W3C_TRACE_CONTEXT"] . If multiple values are specified,
the proxy will attempt to read each header for each request and will
write all headers.
|
No
|
Topology.ProxyProtocolConfiguration
PROXY protocol configuration.
PrivateKeyProvider.CryptoMb
CryptoMb PrivateKeyProvider configuration
Field |
Type |
Description |
Required |
pollDelay |
Duration |
How long to wait until the per-thread processing queue should be processed. If the processing queue
gets full (eight sign or decrypt requests are received) it is processed immediately.
However, if the queue is not filled before the delay has expired, the requests already in the queue
are processed, even if the queue is not full.
In effect, this value controls the balance between latency and throughput.
The duration needs to be set to a value greater than or equal to 1 millisecond.
|
No
|
fallback |
BoolValue |
If the private key provider isn’t available (eg. the required hardware capability doesn’t existed)
Envoy will fallback to the BoringSSL default implementation when the fallback is true.
The default value is false.
|
No
|
PrivateKeyProvider.QAT
QAT (QuickAssist Technology) PrivateKeyProvider configuration
Field |
Type |
Description |
Required |
pollDelay |
Duration |
How long to wait before polling the hardware accelerator after a request has been submitted there.
Having a small value leads to quicker answers from the hardware but causes more polling loop spins,
leading to potentially larger CPU usage.
The duration needs to be set to a value greater than or equal to 1 millisecond.
|
No
|
fallback |
BoolValue |
If the private key provider isn’t available (eg. the required hardware capability doesn’t existed)
Envoy will fallback to the BoringSSL default implementation when the fallback is true.
The default value is false.
|
No
|
ProxyConfig.ProxyStatsMatcher
Proxy stats name matchers for stats creation. Note this is in addition to
the minimum Envoy stats that Istio generates by default.
Field |
Type |
Description |
Required |
inclusionPrefixes |
string[] |
Proxy stats name prefix matcher for inclusion.
|
No
|
inclusionSuffixes |
string[] |
Proxy stats name suffix matcher for inclusion.
|
No
|
inclusionRegexps |
string[] |
Proxy stats name regexps matcher for inclusion.
|
No
|
Field |
Type |
Description |
Required |
Field |
Type |
Description |
Required |
Field |
Type |
Description |
Required |
Field |
Type |
Description |
Required |
Field |
Type |
Description |
Required |
Field |
Type |
Description |
Required |
Field |
Type |
Description |
Required |
Network
Network provides information about the endpoints in a routable L3
network. A single routable L3 network can have one or more service
registries. Note that the network has no relation to the locality of the
endpoint. The endpoint locality will be obtained from the service
registry.
Field |
Type |
Description |
Required |
endpoints |
NetworkEndpoints[] |
The list of endpoints in the network (obtained through the
constituent service registries or from CIDR ranges). All endpoints in
the network are directly accessible to one another.
|
Yes
|
gateways |
IstioNetworkGateway[] |
Set of gateways associated with the network.
|
Yes
|
MeshNetworks
MeshNetworks (config map) provides information about the set of networks
inside a mesh and how to route to endpoints in each network. For example
MeshNetworks(file/config map):
networks:
network1:
endpoints:
- fromRegistry: registry1 #must match kubeconfig name in Kubernetes secret
- fromCidr: 192.168.100.0/22 #a VM network for example
gateways:
- registryServiceName: istio-ingressgateway.istio-system.svc.cluster.local
port: 15443
locality: us-east-1a
- address: 192.168.100.1
port: 15443
locality: us-east-1a
Field |
Type |
Description |
Required |
networks |
map<string, Network> |
The set of networks inside this mesh. Each network should
have a unique name and information about how to infer the endpoints in
the network as well as the gateways associated with the network.
|
Yes
|
Network.NetworkEndpoints
NetworkEndpoints describes how the network associated with an endpoint
should be inferred. An endpoint will be assigned to a network based on
the following rules:
-
Implicitly: If the registry explicitly provides information about
the network to which the endpoint belongs to. In some cases, its
possible to indicate the network associated with the endpoint by
adding the ISTIO_META_NETWORK
environment variable to the sidecar.
-
Explicitly:
a. By matching the registry name with one of the “fromRegistry”
in the mesh config. A “fromRegistry” can only be assigned to a
single network.
b. By matching the IP against one of the CIDR ranges in a mesh
config network. The CIDR ranges must not overlap and be assigned to
a single network.
(2) will override (1) if both are present.
Field |
Type |
Description |
Required |
fromCidr |
string (oneof) |
A CIDR range for the set of endpoints in this network. The CIDR
ranges for endpoints from different networks must not overlap.
|
No
|
fromRegistry |
string (oneof) |
Add all endpoints from the specified registry into this network.
The names of the registries should correspond to the kubeconfig file name
inside the secret that was used to configure the registry (Kubernetes
multicluster) or supplied by MCP server.
|
No
|
Network.IstioNetworkGateway
The gateway associated with this network. Traffic from remote networks
will arrive at the specified gateway:port. All incoming traffic must
use mTLS.
Field |
Type |
Description |
Required |
registryServiceName |
string (oneof) |
A fully qualified domain name of the gateway service. Pilot will
lookup the service from the service registries in the network and
obtain the endpoint IPs of the gateway from the service
registry. Note that while the service name is a fully qualified
domain name, it need not be resolvable outside the orchestration
platform for the registry. e.g., this could be
istio-ingressgateway.istio-system.svc.cluster.local.
|
No
|
address |
string (oneof) |
IP address or externally resolvable DNS address associated with the gateway.
|
No
|
port |
uint32 |
The port associated with the gateway.
|
Yes
|
locality |
string |
The locality associated with an explicitly specified gateway (i.e. ip)
|
No
|
MeshConfig.OutboundTrafficPolicy.Mode
Name |
Description |
REGISTRY_ONLY |
In REGISTRY_ONLY mode, unknown outbound traffic will be dropped.
Traffic destinations must be explicitly declared into the service registry through ServiceEntry configurations.
Note: Istio does not offer an outbound traffic security policy.
This option does not act as one, or as any form of an outbound firewall.
Instead, this option exists primarily to offer users a way to detect missing ServiceEntry configurations by explicitly failing.
|
ALLOW_ANY |
In ALLOW_ANY mode, any traffic to unknown destinations will be allowed.
Unknown destination traffic will have limited functionality, however, such as reduced observability.
This mode allows users that do not have all possible egress destinations registered through ServiceEntry configurations to still connect
to arbitrary destinations.
|
MeshConfig.InboundTrafficPolicy.Mode
Name |
Description |
PASSTHROUGH |
inbound traffic will be passed through to the destination listening
on Pod IP. This matches the behavior without Istio enabled at all
allowing proxy to be transparent.
|
LOCALHOST |
inbound traffic will be sent to the destinations listening on localhost.
|
MeshConfig.ExtensionProvider.OpenCensusAgentTracingProvider.TraceContext
TraceContext selects the context propagation headers used for
distributed tracing.
MeshConfig.ProxyPathNormalization.NormalizationType
Name |
Description |
DEFAULT |
Apply default normalizations. Currently, this is BASE.
|
NONE |
No normalization, paths are used as is.
|
BASE |
Normalize according to RFC 3986.
For Envoy proxies, this is the normalize_path option.
For example, /a/../b normalizes to /b .
|
MERGE_SLASHES |
In addition to the BASE normalization, consecutive slashes are also merged.
For example, /a//b normalizes to a/b .
|
DECODE_AND_MERGE_SLASHES |
In addition to normalization in MERGE_SLASHES , slash characters are UTF-8 decoded (case insensitive) prior to merging.
This means %2F , %2f , %5C , and %5c sequences in the request path will be rewritten to / or \ .
For example, /a%2f/b normalizes to a/b .
|
MeshConfig.TLSConfig.TLSProtocol
TLS protocol versions.
Name |
Description |
TLS_AUTO |
Automatically choose the optimal TLS version.
|
TLSV1_2 |
TLS version 1.2
|
TLSV1_3 |
TLS version 1.3
|
MeshConfig.IngressControllerMode
Name |
Description |
UNSPECIFIED |
Unspecified Istio ingress controller.
|
OFF |
Disables Istio ingress controller.
|
DEFAULT |
Istio 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.
|
STRICT |
Istio 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).
|
MeshConfig.AccessLogEncoding
Name |
Description |
TEXT |
text encoding for the proxy access log
|
JSON |
json encoding for the proxy access log
|
MeshConfig.H2UpgradePolicy
Default Policy for upgrading http1.1 connections to http2.
Name |
Description |
DO_NOT_UPGRADE |
Do not upgrade connections to http2.
|
UPGRADE |
Upgrade the connections to http2.
|
Resource
Resource describes the source of configuration
Name |
Description |
SERVICE_REGISTRY |
Set to only receive service entries that are generated by the platform.
These auto generated service entries are combination of services and endpoints
that are generated by a specific platform e.g. k8
|
Tracing.OpenCensusAgent.TraceContext
TraceContext selects the context propagation headers used for
distributed tracing.
ProxyConfig.TracingServiceName
Allows specification of various Istio-supported naming schemes for the
Envoy service_cluster
value. The service_cluster
value is primarily used
by Envoys to provide service names for tracing spans.
ProxyConfig.InboundInterceptionMode
The mode used to redirect inbound traffic to Envoy.
This setting has no effect on outbound traffic: iptables REDIRECT
is always used for
outbound connections.
Name |
Description |
REDIRECT |
The REDIRECT mode uses iptables REDIRECT to NAT and redirect to Envoy. This mode loses
source IP addresses during redirection. This is the default redirection mode.
|
TPROXY |
The TPROXY mode uses iptables TPROXY to redirect to Envoy. This mode preserves both the
source and destination IP addresses and ports, so that they can be used for advanced
filtering and manipulation. This mode also configures the sidecar to run with the
CAP_NET_ADMIN capability, which is required to use TPROXY .
|
NONE |
The NONE mode does not configure redirect to Envoy at all. This is an advanced
configuration that typically requires changes to user applications.
|
AuthenticationPolicy
AuthenticationPolicy defines how the proxy is authenticated when it connects to the control plane.
It can be set for two different scopes, mesh-wide or set on a per-pod basis using the ProxyConfig annotation.
Mesh policy cannot be INHERIT.
Name |
Description |
NONE |
Do not encrypt proxy to control plane traffic.
|
MUTUAL_TLS |
Proxy to control plane traffic is wrapped into mutual TLS connections.
|
INHERIT |
Use the policy defined by the parent scope. Should not be used for mesh
policy.
|
ForwardClientCertDetails
ForwardClientCertDetails controls how the x-forwarded-client-cert (XFCC)
header is handled by a proxy.
See Envoy XFCC
header handling for more details.
Name |
Description |
UNDEFINED |
Field is not set
|
SANITIZE |
Do not send the XFCC header to the next hop.
|
FORWARD_ONLY |
When the client connection is mTLS (Mutual TLS), forward the XFCC header
in the request.
|
APPEND_FORWARD |
When the client connection is mTLS, append the client certificate
information to the request’s XFCC header and forward it. This is the default value for sidecar proxies.
|
SANITIZE_SET |
When the client connection is mTLS, reset the XFCC header with the client
certificate information and send it to the next hop. This is the default value for gateway proxies.
|
ALWAYS_FORWARD_ONLY |
Always forward the XFCC header in the request, regardless of whether the
client connection is mTLS.
|