Global Mesh Options

Configuration affecting the service mesh as a whole.

MeshConfig

MeshConfig defines mesh-wide settings for the Istio service mesh.

FieldTypeDescriptionRequired
proxyListenPortint32

Port on which Envoy should listen for all outbound traffic to other services. Default port is 15001.

No
proxyInboundListenPortint32

Port on which Envoy should listen for all inbound traffic to the pod/vm will be captured to. Default port is 15006.

No
proxyHttpPortint32

Port on which Envoy should listen for HTTP PROXY requests if set.

No
connectTimeoutDuration

Connection timeout used by Envoy. (MUST BE >=1ms) Default timeout is 10s.

No
tcpKeepaliveTcpKeepalive

If set then set SOKEEPALIVE on the socket to enable TCP Keepalives.

No
ingressClassstring

Class of ingress resources to be processed by Istio ingress controller. This corresponds to the value of kubernetes.io/ingress.class annotation.

No
ingressServicestring

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
ingressControllerModeIngressControllerMode

Defines whether to use Istio ingress controller for annotated or all ingress resources. Default mode is STRICT.

No
ingressSelectorstring

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

No
enableTracingbool

Flag to control generation of trace spans and request IDs. Requires a trace span collector defined in the proxy configuration.

No
accessLogFilestring

File address for the proxy access log (e.g. /dev/stdout). Empty value disables access logging.

No
accessLogFormatstring

Format for the proxy access log Empty value results in proxy’s default access log format

No
accessLogEncodingAccessLogEncoding

Encoding for the proxy access log (TEXT or JSON). Default value is TEXT.

No
enableEnvoyAccessLogServicebool

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
disableEnvoyListenerLogbool

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
defaultConfigProxyConfig

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
outboundTrafficPolicyOutboundTrafficPolicy

Set the default behavior of the sidecar for handling outbound traffic from the application. If your application uses one or more external services that are not known apriori, setting the policy to ALLOW_ANY will cause the sidecars to route any unknown traffic originating from the application to its requested destination. Users are strongly encouraged to use ServiceEntries to explicitly declare any external dependencies, instead of using ALLOW_ANY, so that traffic to these services can be monitored. 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
inboundTrafficPolicyInboundTrafficPolicy

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
configSourcesConfigSource[]

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
enableAutoMtlsBoolValue

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
trustDomainstring

The trust domain corresponds to the trust root of a system. Refer to SPIFFE-ID

No
trustDomainAliasesstring[]

The trust domain aliases represent the aliases of trust_domain. For example, if we have

  1. trustDomain: td1
  2. 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
caCertificatesCertificateData[]

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
defaultServiceExportTostring[]

The default value for the ServiceEntry.export_to 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:

  1. - All Namespaces
  2. . - Current Namespace
  3. ~ - 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
defaultVirtualServiceExportTostring[]

The default value for the VirtualService.export_to field. Has the same syntax as default_service_export_to.

If not set the system will use “” as the default value which implies that virtual services are exported to all namespaces

No
defaultDestinationRuleExportTostring[]

The default value for the DestinationRule.export_to field. Has the same syntax as default_service_export_to.

If not set the system will use “” as the default value which implies that destination rules are exported to all namespaces

No
rootNamespacestring

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
localityLbSettingLocalityLoadBalancerSetting

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
dnsRefreshRateDuration

Configures DNS refresh rate for Envoy clusters of type STRICT_DNS Default refresh rate is 60s.

No
h2UpgradePolicyH2UpgradePolicy

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
inboundClusterStatNamestring

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 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%%SERVICEPORT% will use reviews.prod.svc.cluster.local_7443 as the stats name.
  • %SERVICE% will use reviews.prod as the stats name.
No
outboundClusterStatNamestring

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

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
extensionProvidersExtensionProvider[]

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
defaultProvidersDefaultProviders

Specifies extension providers to use by default in Istio configuration resources.

No
discoverySelectorsLabelSelector[]

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:

  1. The namespace has both of these labels: env: prod and region: us-east1
  2. The namespace has label app equal to cassandra or spark.
  1. discoverySelectors:
  2. - matchLabels:
  3. env: prod
  4. region: us-east1
  5. - matchExpressions:
  6. - key: app
  7. operator: In
  8. values:
  9. - cassandra
  10. - spark

Refer to the Kubernetes selector docs for additional detail on selector semantics.

No
pathNormalizationProxyPathNormalization

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
defaultHttpRetryPolicyHTTPRetry

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
meshMTLSTLSConfig

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:

  1. meshConfig:
  2. meshMTLS:
  3. minProtocolVersion: TLSV1_3
  4. tlsDefaults:
  5. Note: applicable only for non ISTIO_MUTUAL scenarios
  6. ecdhCurves:
  7. - P-256
  8. - P-512

Configuration of mTLS for traffic between workloads with ISTIO_MUTUAL TLS traffic.

Note: Mesh mTLS does not respect ECDH curves.

No
tlsDefaultsTLSConfig

Configuration of TLS for all traffic except for ISTIO_MUTUAL mode. Currently, this supports configuration of ecdh_curves and cipher_suites only. For ISTIO_MUTUAL TLS settings, use meshMTLS configuration.

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.

FieldTypeDescriptionRequired
addressstring

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
tlsSettingsClientTLSSettings

Use the tls_settings 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
subscribedResourcesResource[]

Describes the source of configuration, if nothing is specified default is MCP

No

MeshConfig.OutboundTrafficPolicy

FieldTypeDescriptionRequired
modeModeNo

MeshConfig.InboundTrafficPolicy

FieldTypeDescriptionRequired
modeModeNo

MeshConfig.CertificateData

FieldTypeDescriptionRequired
pemstring (oneof)

The PEM data of the certificate.

No
spiffeBundleUrlstring (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
certSignersstring[]

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
trustDomainsstring[]

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 trust_domain. In that case, trustAnchors with a same trust domain will be merged and used together to verify peer certificates. If neither cert_signers nor trust_domains is set, this trustAnchor is used for all trust domains and all signers. If only trust_domains is set, this trustAnchor is used for these trust_domains and all signers. If only cert_signers is set, this trustAnchor is used for these cert_signers and all trust domains. If both cert_signers and trust_domains is set, this trustAnchor is only used for these signers and trust domains.

No

MeshConfig.CA

FieldTypeDescriptionRequired
addressstring

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
tlsSettingsClientTLSSettings

Use the tls_settings to specify the tls mode to use. Regarding tls_settings:

  • 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
requestTimeoutDuration

timeout for forward CSR requests from Istiod to External CA Default: 10s

No
istiodSidebool

Use istiod_side to specify CA Server integrate to Istiod side or Agent side Default: true

No

MeshConfig.ExtensionProvider

FieldTypeDescriptionRequired
namestring

REQUIRED. A unique name identifying the extension provider.

No
envoyExtAuthzHttpEnvoyExternalAuthorizationHttpProvider (oneof)

Configures an external authorizer that implements the Envoy ext_authz filter authorization check service using the HTTP API.

No
envoyExtAuthzGrpcEnvoyExternalAuthorizationGrpcProvider (oneof)

Configures an external authorizer that implements the Envoy ext_authz filter authorization check service using the gRPC API.

No
zipkinZipkinTracingProvider (oneof)

Configures a tracing provider that uses the Zipkin API.

No
datadogDatadogTracingProvider (oneof)

Configures a Datadog tracing provider.

No
stackdriverStackdriverProvider (oneof)

Configures a Stackdriver provider.

No
skywalkingSkyWalkingTracingProvider (oneof)

Configures a Apache SkyWalking provider.

No
opentelemetryOpenTelemetryTracingProvider (oneof)

Configures an OpenTelemetry tracing provider.

No
prometheusPrometheusMetricsProvider (oneof)

Configures a Prometheus metrics provider.

No
envoyFileAccessLogEnvoyFileAccessLogProvider (oneof)

Configures an Envoy File Access Log provider.

No
envoyHttpAlsEnvoyHttpGrpcV3LogProvider (oneof)

Configures an Envoy Access Logging Service provider for HTTP traffic.

No
envoyTcpAlsEnvoyTcpGrpcV3LogProvider (oneof)

Configures an Envoy Access Logging Service provider for TCP traffic.

No
envoyOtelAlsEnvoyOpenTelemetryLogProvider (oneof)

Configures an Envoy Open Telemetry Access Logging Service provider.

No

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 extension_providers that is one of the supported tracing providers.

FieldTypeDescriptionRequired
tracingstring[]

Name of the default provider(s) for tracing.

No
metricsstring[]

Name of the default provider(s) for metrics.

No
accessLoggingstring[]

Name of the default provider(s) for access logging.

No

MeshConfig.ProxyPathNormalization

FieldTypeDescriptionRequired
normalizationNormalizationTypeNo

MeshConfig.TLSConfig

FieldTypeDescriptionRequired
minProtocolVersionTLSProtocol

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
ecdhCurvesstring[]

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
cipherSuitesstring[]

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:

  1. ECDHE-ECDSA-AES256-GCM-SHA384
  2. ECDHE-RSA-AES256-GCM-SHA384
  3. ECDHE-ECDSA-AES128-GCM-SHA256
  4. ECDHE-RSA-AES128-GCM-SHA256
  5. AES256-GCM-SHA384
  6. AES128-GCM-SHA256
No

MeshConfig.ServiceSettings.Settings

Settings for the selected services.

FieldTypeDescriptionRequired
clusterLocalbool

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

FieldTypeDescriptionRequired
maxRequestBytesuint32

Sets the maximum size of a message body that the ext-authz filter will hold in memory. If max_request_bytes is reached, and allow_partial_message 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 fail_open field, the 413 will be returned even when the fail_open is set to true.

No
allowPartialMessagebool

When this field is true, ext-authz filter will buffer the message until max_request_bytes 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
packAsBytesbool

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 envoy_ext_authz_grpc provider and has no effect for the envoy_ext_authz_http provider.

No

MeshConfig.ExtensionProvider.EnvoyExternalAuthorizationHttpProvider

FieldTypeDescriptionRequired
servicestring

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
portuint32

REQUIRED. Specifies the port of the service.

No
timeoutDuration

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 fail_open field.

No
pathPrefixstring

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
failOpenbool

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
statusOnErrorstring

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
includeRequestHeadersInCheckstring[]

List of client request headers that should be included in the authorization request sent to the authorization service. Note that in addition to the headers specified here following headers are included by default:

  1. Host, Method, Path and Content-Length are automatically sent.
  2. Content-Length will be set to 0 and the request will not have a message body. However, the authorization request can include the buffered client request body (controlled by include_request_body_in_check setting), consequently the value of Content-Length of the authorization request reflects the size of its payload size.

Exact, prefix and suffix matches are supported (similar to the authorization policy rule syntax except the presence match):

  • Exact match: “abc” will match on value “abc”.
  • Prefix match: “abc” will match on value “abc” and “abcd”.
  • Suffix match: “abc” will match on value “abc” and “xabc”.
No
includeAdditionalHeadersInCheckmap<string, string>

Set of additional fixed headers that should be included in the authorization request sent to the authorization service. Key is the header name and value is the header value. Note that client request of the same key or headers specified in include_request_headers_in_check will be overridden.

No
includeRequestBodyInCheckEnvoyExternalAuthorizationRequestBody

If set, the client request body will be included in the authorization request sent to the authorization service.

No
headersToUpstreamOnAllowstring[]

List of headers from the authorization service that should be added or overridden in the original request and forwarded to the upstream when the authorization check result is allowed (HTTP code 200). If not specified, the original request will not be modified and forwarded to backend as-is. Note, any existing headers will be overridden.

Exact, prefix and suffix matches are supported (similar to the authorization policy rule syntax except the presence match):

  • Exact match: “abc” will match on value “abc”.
  • Prefix match: “abc” will match on value “abc” and “abcd”.
  • Suffix match: “abc” will match on value “abc” and “xabc”.
No
headersToDownstreamOnDenystring[]

List of headers from the authorization service that should be forwarded to downstream when the authorization check result is not allowed (HTTP code other than 200). If not specified, all the authorization response headers, except Authority (Host) will be in the response to the downstream. When a header is included in this list, Path, Status, Content-Length, WWWAuthenticate and Location are automatically added. Note, the body from the authorization service is always included in the response to downstream.

Exact, prefix and suffix matches are supported (similar to the authorization policy rule syntax except the presence match):

  • Exact match: “abc” will match on value “abc”.
  • Prefix match: “abc” will match on value “abc” and “abcd”.
  • Suffix match: “abc” will match on value “abc” and “xabc”.
No
headersToDownstreamOnAllowstring[]

List of headers from the authorization service that should be forwarded to downstream when the authorization check result is allowed (HTTP code 200). If not specified, the original response will not be modified and forwarded to downstream as-is. Note, any existing headers will be overridden.

Exact, prefix and suffix matches are supported (similar to the authorization policy rule syntax except the presence match):

  • Exact match: “abc” will match on value “abc”.
  • Prefix match: “abc” will match on value “abc” and “abcd”.
  • Suffix match: “abc” will match on value “abc” and “xabc”.
No
includeHeadersInCheckstring[]

DEPRECATED. Use include_request_headers_in_check instead.

No

MeshConfig.ExtensionProvider.EnvoyExternalAuthorizationGrpcProvider

FieldTypeDescriptionRequired
servicestring

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
portuint32

REQUIRED. Specifies the port of the service.

No
timeoutDuration

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 fail_open field.

No
failOpenbool

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
statusOnErrorstring

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
includeRequestBodyInCheckEnvoyExternalAuthorizationRequestBody

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.

FieldTypeDescriptionRequired
servicestring

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
portuint32

REQUIRED. Specifies the port of the service.

No
maxTagLengthuint32

Optional. Controls the overall path length allowed in a reported span. NOTE: currently only controls max length of the path tag.

No
enable64bitTraceIdbool

Optional. A 128 bit trace id will be used in Istio. If true, will result in a 64 bit trace id being used.

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.

FieldTypeDescriptionRequired
servicestring

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
portuint32

REQUIRED. Specifies the port of the service.

No
accessTokenstring

The Lightstep access token.

No
maxTagLengthuint32

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.

FieldTypeDescriptionRequired
servicestring

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
portuint32

REQUIRED. Specifies the port of the service.

No
maxTagLengthuint32

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.

FieldTypeDescriptionRequired
servicestring

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
portuint32

REQUIRED. Specifies the port of the service.

No
accessTokenstring

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.

FieldTypeDescriptionRequired
maxTagLengthuint32

Optional. Controls the overall path length allowed in a reported span. NOTE: currently only controls max length of the path tag.

No
loggingLogging

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.

FieldTypeDescriptionRequired
servicestring

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
portuint32

REQUIRED. Specifies the port of the service.

No
contextTraceContext[]

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
maxTagLengthuint32

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

FieldTypeDescriptionRequired
pathstring

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
logFormatLogFormat

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.

FieldTypeDescriptionRequired
servicestring

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
portuint32

REQUIRED. Specifies the port of the service.

No
logNamestring

Optional. The friendly name of the access log. Defaults:

  • “http_envoy_accesslog”
  • “listener_envoy_accesslog”
No
filterStateObjectsToLogstring[]

Optional. Additional filter state objects to log.

No
additionalRequestHeadersToLogstring[]

Optional. Additional request headers to log.

No
additionalResponseHeadersToLogstring[]

Optional. Additional response headers to log.

No
additionalResponseTrailersToLogstring[]

Optional. Additional response trailers to log.

No

MeshConfig.ExtensionProvider.EnvoyTcpGrpcV3LogProvider

Defines configuration for an Envoy Access Logging Service integration for TCP traffic.

FieldTypeDescriptionRequired
servicestring

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
portuint32

REQUIRED. Specifies the port of the service.

No
logNamestring

Optional. The friendly name of the access log. Defaults:

  • “tcp_envoy_accesslog”
  • “listener_envoy_accesslog”
No
filterStateObjectsToLogstring[]

Optional. Additional filter state objects to log.

No

MeshConfig.ExtensionProvider.EnvoyOpenTelemetryLogProvider

Defines configuration for an Envoy OpenTelemetry (gRPC) Access Log

FieldTypeDescriptionRequired
servicestring

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
portuint32

REQUIRED. Specifies the port of the service.

No
logNamestring

Optional. The friendly name of the access log. Defaults:

  • “otel_envoy_accesslog”
No
logFormatLogFormat

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.

FieldTypeDescriptionRequired
servicestring

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
portuint32

REQUIRED. Specifies the port of the service.

No
maxTagLengthuint32

Optional. Controls the overall path length allowed in a reported span. NOTE: currently only controls max length of the path tag.

No
httpHttpService

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:

  1. Add/change the OpenTelemetry extension provider in MeshConfig
  1. - name: otel-tracing
  2. opentelemetry:
  3. port: 443
  4. service: my.olly-backend.com
  5. http:
  6. path: “/api/otlp/traces
  7. timeout: 10s
  8. headers:
  9. - name: my-custom-header
  10. value: some value
  1. Deploy a ServiceEntry for the observability back-end
  1. apiVersion: networking.istio.io/v1alpha3
  2. kind: ServiceEntry
  3. metadata:
  4. name: my-olly-backend
  5. spec:
  6. hosts:
  7. - my.olly-backend.com
  8. ports:
  9. - number: 443
  10. name: https-port
  11. protocol: HTTPS
  12. resolution: DNS
  13. location: MESH_EXTERNAL
  14. —-
  15. apiVersion: networking.istio.io/v1alpha3
  16. kind: DestinationRule
  17. metadata:
  18. name: my-olly-backend
  19. spec:
  20. host: my.olly-backend.com
  21. trafficPolicy:
  22. portLevelSettings:
  23. - port:
  24. number: 443
  25. tls:
  26. mode: SIMPLE
No
resourceDetectorsResourceDetectors

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:

  1. - name: otel-tracing
  2. opentelemetry:
  3. port: 443
  4. service: my.olly-backend.com
  5. resource_detectors:
  6. environment: {}
No
dynatraceSamplerDynatraceSampler (oneof)

The Dynatrace adaptive traffic management (ATM) sampler.

Example configuration:

  1. - name: otel-tracing
  2. opentelemetry:
  3. port: 443
  4. service: “{your-environment-id}.live.dynatrace.com
  5. http:
  6. path: “/api/v2/otlp/v1/traces
  7. timeout: 10s
  8. headers:
  9. - name: Authorization
  10. value: Api-Token dt0c01.”
  11. resource_detectors:
  12. dynatrace: {}
  13. dynatrace_sampler:
  14. tenant: “{your-environment-id}”
  15. cluster_id: 1234
No

MeshConfig.ExtensionProvider.HttpService

Defines configuration for an HTTP service that can be used by an Extension Provider. that does communication via HTTP.

FieldTypeDescriptionRequired
pathstring

REQUIRED. Specifies the path on the service.

No
timeoutDuration

Optional. Specifies the timeout for the HTTP request. If not specified, the default is 3s.

No
headersHttpHeader[]

Optional. Allows specifying custom HTTP headers that will be added to each HTTP request sent.

No

MeshConfig.ExtensionProvider.HttpHeader

FieldTypeDescriptionRequired
namestring

REQUIRED. The HTTP header name.

No
valuestring

REQUIRED. The HTTP header value.

No

MeshConfig.ExtensionProvider.ResourceDetectors

FieldTypeDescriptionRequired
environmentEnvironmentResourceDetectorNo
dynatraceDynatraceResourceDetectorNo

MeshConfig.ExtensionProvider.StackdriverProvider.Logging

FieldTypeDescriptionRequired
labelsmap<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

MeshConfig.ExtensionProvider.EnvoyFileAccessLogProvider.LogFormat

FieldTypeDescriptionRequired
textstring (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
labelsStruct (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:

  1. labels:
  2. status: “%RESPONSE_CODE%”
  3. message: “%LOCAL_REPLY_BODY%”
No

MeshConfig.ExtensionProvider.EnvoyOpenTelemetryLogProvider.LogFormat

FieldTypeDescriptionRequired
textstring

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 filed in Open Telemetry Example: text: “%LOCAL_REPLY_BODY%:%RESPONSE_CODE%:path=%REQ(:path)%”

No
labelsStruct

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 filed in Open Telemetry

Example:

  1. labels:
  2. status: “%RESPONSE_CODE%”
  3. message: “%LOCAL_REPLY_BODY%”
No

MeshConfig.ExtensionProvider.OpenTelemetryTracingProvider.DynatraceSampler

FieldTypeDescriptionRequired
tenantstring

REQUIRED. The Dynatrace customer’s tenant identifier.

The value can be obtained from the Istio deployment page in Dynatrace.

No
clusterIdint32

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
rootSpansPerMinuteuint32

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:

  • root_spans_per_minute is unset
  • root_spans_per_minute is set to 0
No
httpServiceDynatraceApi

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

FieldTypeDescriptionRequired
servicestring

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
portuint32

REQUIRED. Specifies the port of the service.

No
httpHttpService

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

Dynatrace Resource Detector. The resource detector reads from the Dynatrace enrichment files and adds host/process related attributes to the OpenTelemetry resource.

See: Enrich ingested data with Dynatrace-specific dimensions

k8s.io.apimachinery.pkg.apis.meta.v1.LabelSelector

A label selector is a label query over a set of resources. The result of matchLabels and matchExpressions are ANDed. An empty label selector matches all objects. A null label selector matches no objects.

FieldTypeDescriptionRequired
matchLabelsmap<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
matchExpressionsLabelSelectorRequirement[]

matchExpressions is a list of label selector requirements. The requirements are ANDed.

No

Tracing

Tracing defines configuration for the tracing performed by Envoy instances.

FieldTypeDescriptionRequired
zipkinZipkin (oneof)

Use a Zipkin tracer.

No
lightstepLightstep (oneof)

Use a Lightstep tracer. NOTE: For Istio 1.15+, this configuration option will result in using OpenTelemetry-based Lightstep integration.

No
datadogDatadog (oneof)

Use a Datadog tracer.

No
stackdriverStackdriver (oneof)

Use a Stackdriver tracer.

No
openCensusAgentOpenCensusAgent (oneof)

Use an OpenCensus tracer exporting to an OpenCensus agent.

No
samplingdouble

The percentage of requests (0.0 - 100.0) that will be randomly selected for trace generation, if not requested by the client or not forced. Default is 1.0.

No
tlsSettingsClientTLSSettings

Use the tls_settings to specify the tls mode to use. If the remote tracing service uses Istio mutual TLS and shares the root CA with Pilot, specify the TLS mode as ISTIO_MUTUAL.

No

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.

FieldTypeDescriptionRequired
numTrustedProxiesuint32

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 num_trusted_proxies is 0. See Envoy XFF header handling for more details.

No
forwardClientCertDetailsForwardClientCertDetails

Configures how the gateway proxy handles x-forwarded-client-cert (XFCC) header in the incoming request.

No
proxyProtocolProxyProtocolConfiguration

Enables PROXY protocol for downstream connections on a gateway.

No

PrivateKeyProvider

PrivateKeyProvider defines private key configuration for gateways and sidecars. This can be configured mesh wide or individual per-workload basis.

FieldTypeDescriptionRequired
cryptombCryptoMb (oneof)

Use CryptoMb private key provider

No
qatQAT (oneof)

Use QAT private key provider

No

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:

  1. meshConfig:
  2. defaultConfig:
  3. 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:

  1. annotations:
  2. proxy.istio.io/config: |
  3. 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.

FieldTypeDescriptionRequired
configPathstring

Path to the generated configuration file directory. Proxy agent generates the actual configuration and stores it in this directory.

No
binaryPathstring

Path to the proxy binary

No
serviceClusterstring (oneof)

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

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

No
tracingServiceNameTracingServiceName (oneof)

Used by Envoy proxies to assign the values for the service names in trace spans.

No
drainDurationDuration

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
discoveryAddressstring

Address of the discovery service exposing xDS with mTLS connection. The inject configuration may override this value.

No
statsdUdpAddressstring

IP Address and Port of a statsd UDP listener (e.g. 10.75.241.127:9125).

No
proxyAdminPortint32

Port on which Envoy should listen for administrative commands. Default port is 15000.

No
controlPlaneAuthPolicyAuthenticationPolicy

AuthenticationPolicy defines how the proxy is authenticated when it connects to the control plane. Default is set to MUTUAL_TLS.

No
customConfigFilestring

File path of custom proxy configuration, currently used by proxies in front of Mixer and Pilot.

No
statNameLengthint32

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
concurrencyInt32Value

The number of worker threads to run. If unset, this will be automatically determined based on CPU requests/limits. If set to 0, all cores on the machine will be used. Default is 2 worker threads.

No
proxyBootstrapTemplatePathstring

Path to the proxy bootstrap template file

No
interceptionModeInboundInterceptionMode

The mode used to redirect inbound traffic to Envoy.

No
tracingTracing

Tracing configuration to be used by the proxy.

No
envoyAccessLogServiceRemoteService

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
envoyMetricsServiceRemoteService

Address of the Envoy Metrics Service implementation (e.g. metrics-service:15000). See Metric Service for details about Envoy’s Metrics Service API.

No
proxyMetadatamap<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
runtimeValuesmap<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
statusPortint32

Port on which the agent should listen for administrative commands such as readiness probe. Default is set to port 15020.

No
extraStatTagsstring[]

An additional list of tags to extract from the in-proxy Istio telemetry. These extra tags can be added by configuring the telemetry extension. Each additional tag needs to be present in this list. Extra tags emitted by the telemetry extensions must be listed here so that they can be processed and exposed as Prometheus metrics. Deprecated: istio.stats is a native filter now, this field is no longer needed.

No
gatewayTopologyTopology

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
terminationDrainDurationDuration

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 draining, preventing any new connections and allowing existing connections to complete. It then sleeps for the terminationdrain_duration and then kills any remaining active Envoy processes. If not set, a default of 5s will be applied.

No
meshIdstring

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
readinessProbeReadinessProbe

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
proxyStatsMatcherProxyStatsMatcher

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:

  1. proxyStatsMatcher:
  2. inclusionRegexps:
  3. - .outlier_detection.
  4. - .upstream_rq_retry.
  5. - .*upstream_cx.*
  6. inclusionSuffixes:
  7. - 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
holdApplicationUntilProxyStartsBoolValue

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
caCertificatesPemstring[]

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
imageProxyImage

Specifies the details of the proxy image.

No
privateKeyProviderPrivateKeyProvider

Specifies the details of the Private Key Provider configuration for gateway and sidecar proxies.

No
proxyHeadersProxyHeaders

Define the set of headers to add/modify for HTTP request/responses.

To enable an optional header, simply set the field. If no specific configuration is required, an empty object ({}) will enable it. Note: currently all headers are enabled by default.

Below shows an example of customizing the server header and disabling the X-Envoy-Attempt-Count header:

  1. proxyHeaders:
  2. server:
  3. value: my-custom-server
  4. requestId: {} // Explicitly enable Request IDs. As this is the default, this has no effect.
  5. attemptCount:
  6. disabled: true

Some headers are enabled by default, and require explicitly disabling. See below for an example of disabling all default-enabled headers:

  1. proxyHeaders:
  2. forwardedClientCert: SANITIZE
  3. server:
  4. disabled: true
  5. requestId:
  6. disabled: true
  7. attemptCount:
  8. disabled: true
  9. envoyDebugHeaders:
  10. disabled: true
  11. metadataExchangeHeaders:
  12. mode: IN_MESH
No
zipkinAddressstring

Address of the Zipkin service (e.g. zipkin:9411). DEPRECATED: Use tracing instead.

No

RemoteService

FieldTypeDescriptionRequired
addressstring

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
tlsSettingsClientTLSSettings

Use the tls_settings 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
tcpKeepaliveTcpKeepalive

If set then set SO_KEEPALIVE on the socket to enable TCP Keepalives.

No

Tracing.Zipkin

Zipkin defines configuration for a Zipkin tracer.

FieldTypeDescriptionRequired
addressstring

Address of the Zipkin service (e.g. zipkin:9411).

No

Tracing.Datadog

Datadog defines configuration for a Datadog tracer.

FieldTypeDescriptionRequired
addressstring

Address of the Datadog Agent.

No

Tracing.Stackdriver

Stackdriver defines configuration for a Stackdriver tracer. See Envoy’s OpenCensus trace configuration and OpenCensus trace config for details.

FieldTypeDescriptionRequired

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.

FieldTypeDescriptionRequired
addressstring

gRPC address for the OpenCensus agent (e.g. dns://authority/host:port or unix:path). See gRPC naming docs for details.

No
contextTraceContext[]

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

FieldTypeDescriptionRequired
pollDelayDuration

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
fallbackBoolValue

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

FieldTypeDescriptionRequired
pollDelayDuration

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
fallbackBoolValue

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.

FieldTypeDescriptionRequired
inclusionPrefixesstring[]

Proxy stats name prefix matcher for inclusion.

No
inclusionSuffixesstring[]

Proxy stats name suffix matcher for inclusion.

No
inclusionRegexpsstring[]

Proxy stats name regexps matcher for inclusion.

No

ProxyConfig.ProxyHeaders

FieldTypeDescriptionRequired
forwardedClientCertForwardClientCertDetails

Controls the X-Forwarded-Client-Cert header for inbound sidecar requests. To set this on gateways, use the Topology setting. To disable the header, configure either SANITIZE (to always remove the header, if present) or FORWARD_ONLY (to leave the header as-is). By default, APPEND_FORWARD will be used.

No
requestIdRequestId

Controls the X-Request-Id header. If enabled, a request ID is generated for each request if one is not already set. This applies to all types of traffic (inbound, outbound, and gateways). If disabled, no request ID will be generate for the request. If it is already present, it will be preserved. Warning: request IDs are a critical component to mesh tracing and logging, so disabling this is not recommended. This header is enabled by default if not configured.

No
serverServer

Controls the server header. If enabled, the Server: istio-envoy header is set in response headers for inbound traffic (including gateways). If disabled, the Server header is not modified. If it is already present, it will be preserved.

No
attemptCountAttemptCount

Controls the X-Envoy-Attempt-Count header. If enabled, this header will be added on outbound request headers (including gateways) that have retries configured. If disabled, this header will not be set. If it is already present, it will be preserved. This header is enabled by default if not configured.

No
envoyDebugHeadersEnvoyDebugHeaders

Controls various X-Envoy-* headers, such as X-Envoy-Overloaded and `X-Envoy-Upstream-Service-Time. If enabled, these headers will be included. If disabled, these headers will not be set. If they are already present, they will be preserved. See the Envoy documentation for more details. These headers are enabled by default if not configured.

No
metadataExchangeHeadersMetadataExchangeHeaders

Controls Istio metadata exchange headers X-Envoy-Peer-Metadata and X-Envoy-Peer-Metadata-Id. By default, the behavior is unspecified. If IN_MESH, these headers will not be appended to outbound requests from sidecars to services not in-mesh.

No

ProxyConfig.ProxyHeaders.Server

FieldTypeDescriptionRequired
disabledBoolValueNo
valuestring

If set, and the server header is enabled, this value will be set as the server header. By default, istio-envoy will be used.

No

ProxyConfig.ProxyHeaders.RequestId

FieldTypeDescriptionRequired
disabledBoolValueNo

ProxyConfig.ProxyHeaders.AttemptCount

FieldTypeDescriptionRequired
disabledBoolValueNo

ProxyConfig.ProxyHeaders.EnvoyDebugHeaders

FieldTypeDescriptionRequired
disabledBoolValueNo

ProxyConfig.ProxyHeaders.MetadataExchangeHeaders

FieldTypeDescriptionRequired
modeMetadataExchangeModeNo

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.

FieldTypeDescriptionRequired
endpointsNetworkEndpoints[]

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
gatewaysIstioNetworkGateway[]

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

  1. networks:
  2. network1:
  3. endpoints:
  4. - fromRegistry: registry1 #must match kubeconfig name in Kubernetes secret
  5. - fromCidr: 192.168.100.0/22 #a VM network for example
  6. gateways:
  7. - registryServiceName: istio-ingressgateway.istio-system.svc.cluster.local
  8. port: 15443
  9. locality: us-east-1a
  10. - address: 192.168.100.1
  11. port: 15443
  12. locality: us-east-1a
FieldTypeDescriptionRequired
networksmap<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:

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

  2. Explicitly:

    a. By matching the registry name with one of the “fromRegistry” in the mesh config. A “from_registry” 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.

FieldTypeDescriptionRequired
fromCidrstring (oneof)

A CIDR range for the set of endpoints in this network. The CIDR ranges for endpoints from different networks must not overlap.

No
fromRegistrystring (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.

FieldTypeDescriptionRequired
registryServiceNamestring (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
addressstring (oneof)

IP address or externally resolvable DNS address associated with the gateway.

No
portuint32

The port associated with the gateway.

Yes
localitystring

The locality associated with an explicitly specified gateway (i.e. ip)

No

MeshConfig.OutboundTrafficPolicy.Mode

NameDescription
REGISTRY_ONLY

outbound traffic will be restricted to services defined in the service registry as well as those defined through ServiceEntries

ALLOW_ANY

outbound traffic to unknown destinations will be allowed, in case there are no services or ServiceEntries for the destination port

MeshConfig.InboundTrafficPolicy.Mode

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

NameDescription
W3C_TRACE_CONTEXT

Use W3C Trace Context propagation using the traceparent HTTP header. See the Trace Context documentation for details.

GRPC_BIN

Use gRPC binary context propagation using the grpc-trace-bin http header.

CLOUD_TRACE_CONTEXT

Use Cloud Trace context propagation using the X-Cloud-Trace-Context http header.

B3

Use multi-header B3 context propagation using the X-B3-TraceId, X-B3-SpanId, and X-B3-Sampled HTTP headers. See B3 header propagation README for details.

MeshConfig.ProxyPathNormalization.NormalizationType

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

NameDescription
TLS_AUTO

Automatically choose the optimal TLS version.

TLSV1_2

TLS version 1.2

TLSV1_3

TLS version 1.3

MeshConfig.IngressControllerMode

NameDescription
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 ingress_class 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 ingress_class 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

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

NameDescription
DO_NOT_UPGRADE

Do not upgrade connections to http2.

UPGRADE

Upgrade the connections to http2.

Resource

Resource describes the source of configuration

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

NameDescription
W3C_TRACE_CONTEXT

Use W3C Trace Context propagation using the traceparent HTTP header. See the Trace Context documentation for details.

GRPC_BIN

Use gRPC binary context propagation using the grpc-trace-bin http header.

CLOUD_TRACE_CONTEXT

Use Cloud Trace context propagation using the X-Cloud-Trace-Context http header.

B3

Use multi-header B3 context propagation using the X-B3-TraceId, X-B3-SpanId, and X-B3-Sampled HTTP headers. See B3 header propagation README for details.

ProxyConfig.ProxyHeaders.MetadataExchangeMode

NameDescription
UNDEFINED

Existing Istio behavior for the metadata exchange headers is unchanged.

IN_MESH

Only append the istio metadata exchange headers for services considered in-mesh. Traffic is considered in-mesh if it is secured with Istio mutual TLS. This means that MESH_EXTERNAL services, unmatched passthrough traffic, and requests to workloads without Istio enabled will be considered out of mesh.

ProxyConfig.TracingServiceName

Allows specification of various Istio-supported naming schemes for the Envoy service_cluster value. The servce_cluster value is primarily used by Envoys to provide service names for tracing spans.

NameDescription
APP_LABEL_AND_NAMESPACE

Default scheme. Uses the app label and workload namespace to construct a cluster name. If the app label does not exist istio-proxy is used.

CANONICAL_NAME_ONLY

Uses the canonical name for a workload (excluding namespace).

CANONICAL_NAME_AND_NAMESPACE

Uses the canonical name and namespace for a workload.

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.

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

NameDescription
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 the gateway proxy. See Envoy XFCC header handling for more details.

NameDescription
UNDEFINED

Field is not set

SANITIZE

Do not send the XFCC header to the next hop. This is the default value.

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.

SANITIZE_SET

When the client connection is mTLS, reset the XFCC header with the client certificate information and send it to the next hop.

ALWAYS_FORWARD_ONLY

Always forward the XFCC header in the request, regardless of whether the client connection is mTLS.