Resource Annotations

This page presents the various resource annotations that Istio supports to control its behavior.

ambient.istio.io/redirection

Nameambient.istio.io/redirection
Feature StatusBeta
Resource Types[Pod]
Description

Automatically configured by Istio to indicate a Pod was successfully enrolled in ambient mode. This shows the actual state; to specify intent that a workload should be in ambient mode, see istio.io/dataplane-mode. User should not manually modify this annotation.

galley.istio.io/analyze-suppress

Namegalley.istio.io/analyze-suppress
Feature StatusAlpha
Resource Types[Any]
Description

A comma separated list of configuration analysis message codes to suppress when Istio analyzers are run. For example, to suppress reporting of IST0103 (PodMissingProxy) and IST0108 (UnknownAnnotation) on a resource, apply the annotation ‘galley.istio.io/analyze-suppress=IST0108,IST0103’. If the value is ‘*’, then all configuration analysis messages are suppressed.

inject.istio.io/templates

Nameinject.istio.io/templates
Feature StatusAlpha
Resource Types[Pod]
Description

The name of the inject template(s) to use, as a comma separate list. See https://istio.io/latest/docs/setup/additional-setup/sidecar-injection/#custom-templates-experimental for more information.

istio.io/dry-run

Nameistio.io/dry-run
Feature StatusAlpha
Resource Types[AuthorizationPolicy]
Description

Specifies whether or not the given resource is in dry-run mode. See https://istio.io/latest/docs/tasks/security/authorization/authz-dry-run/ for more information.

istio.io/rev

Nameistio.io/rev
Feature StatusAlpha
Resource Types[Pod]
Description

Specifies a control plane revision to which a given proxy is connected. This annotation is added automatically, not set by a user. In contrary to the label istio.io/rev, it represents the actual revision, not the requested revision.

kubernetes.io/ingress.class

Namekubernetes.io/ingress.class
Feature StatusStable
Resource Types[Ingress]
Description

Annotation on an Ingress resources denoting the class of controllers responsible for it.

networking.istio.io/exportTo

Namenetworking.istio.io/exportTo
Feature StatusAlpha
Resource Types[Service]
Description

Specifies the namespaces to which this service should be exported to. A value of ‘*’ indicates it is reachable within the mesh ‘.’ indicates it is reachable within its namespace.

networking.istio.io/traffic-distribution

Namenetworking.istio.io/traffic-distribution
Feature StatusAlpha
Resource Types[Service ServiceEntry]
Description

Controls how traffic is distributed across the set of available endpoints.

At this time, this annotation only impacts routing done by Ztunnel.

Accepted values:

  • PreferClose: endpoints will be categorized by how “close” they are, consider network, region, zone, and subzone. Traffic will be prioritized to the closest healthy endpoints. For example, if I have a Service with PreferClose set, with endpoints in zones us-west,us-west,us-east. When sending traffic from a client in zone us-west, all traffic will go to the two us-west backends. If one those backends become unhealthy, all traffic will go to the remaining endpoint in us-west. If that backend becomes unhealthy, traffic will sent to us-east.

prometheus.istio.io/merge-metrics

Nameprometheus.istio.io/merge-metrics
Feature StatusAlpha
Resource Types[Pod]
Description

Specifies if application Prometheus metric will be merged with Envoy metrics for this workload.

proxy.istio.io/config

Nameproxy.istio.io/config
Feature StatusBeta
Resource Types[Pod]
Description

Overrides for the proxy configuration for this specific proxy. Available options can be found at https://istio.io/docs/reference/config/istio.mesh.v1alpha1/#ProxyConfig.

readiness.status.sidecar.istio.io/applicationPorts

Namereadiness.status.sidecar.istio.io/applicationPorts
Feature StatusAlpha
Resource Types[Pod]
Description

Specifies the list of ports exposed by the application container. Used by the Envoy sidecar readiness probe to determine that Envoy is configured and ready to receive traffic.

readiness.status.sidecar.istio.io/failureThreshold

Namereadiness.status.sidecar.istio.io/failureThreshold
Feature StatusAlpha
Resource Types[Pod]
Description

Specifies the failure threshold for the Envoy sidecar readiness probe.

readiness.status.sidecar.istio.io/initialDelaySeconds

Namereadiness.status.sidecar.istio.io/initialDelaySeconds
Feature StatusAlpha
Resource Types[Pod]
Description

Specifies the initial delay (in seconds) for the Envoy sidecar readiness probe.

readiness.status.sidecar.istio.io/periodSeconds

Namereadiness.status.sidecar.istio.io/periodSeconds
Feature StatusAlpha
Resource Types[Pod]
Description

Specifies the period (in seconds) for the Envoy sidecar readiness probe.

sidecar.istio.io/agentLogLevel

Namesidecar.istio.io/agentLogLevel
Feature StatusAlpha
Resource Types[Pod]
Description

Specifies the log output level for pilot-agent.

sidecar.istio.io/bootstrapOverride

Namesidecar.istio.io/bootstrapOverride
Feature StatusAlpha
Resource Types[Pod]
Description

Specifies an alternative Envoy bootstrap configuration file.

sidecar.istio.io/componentLogLevel

Namesidecar.istio.io/componentLogLevel
Feature StatusAlpha
Resource Types[Pod]
Description

Specifies the component log level for Envoy.

sidecar.istio.io/discoveryAddress

Namesidecar.istio.io/discoveryAddress
Feature StatusDeprecated
Resource Types[Pod]
Description

Specifies the XDS discovery address to be used by the Envoy sidecar.

sidecar.istio.io/extraStatTags

Namesidecar.istio.io/extraStatTags
Feature StatusDeprecated
Resource Types[Pod]
Description

An additional list of tags to extract from the in-proxy Istio Wasm telemetry. Each additional tag needs to be present in this list.

sidecar.istio.io/inject

Namesidecar.istio.io/inject
Feature StatusDeprecated
Resource Types[Pod]
Description

Specifies whether or not an Envoy sidecar should be automatically injected into the workload. This annotation has been deprecated in favor of the sidecar.istio.io/inject label documented here.

sidecar.istio.io/interceptionMode

Namesidecar.istio.io/interceptionMode
Feature StatusAlpha
Resource Types[Pod]
Description

Specifies the mode used to redirect inbound connections to Envoy (REDIRECT or TPROXY).

sidecar.istio.io/logLevel

Namesidecar.istio.io/logLevel
Feature StatusAlpha
Resource Types[Pod]
Description

Specifies the log level for Envoy.

sidecar.istio.io/nativeSidecar

Namesidecar.istio.io/nativeSidecar
Feature StatusAlpha
Resource Types[Pod]
Description

Specifies if the istio-proxy sidecar should be injected as a native sidecar or not. Takes precedence over the ENABLE_NATIVE_SIDECARS environment variable.

sidecar.istio.io/proxyCPU

Namesidecar.istio.io/proxyCPU
Feature StatusAlpha
Resource Types[Pod]
Description

Specifies the requested CPU setting for the Envoy sidecar.

sidecar.istio.io/proxyCPULimit

Namesidecar.istio.io/proxyCPULimit
Feature StatusAlpha
Resource Types[Pod]
Description

Specifies the CPU limit for the Envoy sidecar.

sidecar.istio.io/proxyImage

Namesidecar.istio.io/proxyImage
Feature StatusAlpha
Resource Types[Pod]
Description

Specifies the Docker image to be used by the Envoy sidecar.

sidecar.istio.io/proxyImageType

Namesidecar.istio.io/proxyImageType
Feature StatusAlpha
Resource Types[Pod]
Description

Specifies the Docker image type to be used by the Envoy sidecar. Istio publishes debug and distroless image types for every release tag.

sidecar.istio.io/proxyMemory

Namesidecar.istio.io/proxyMemory
Feature StatusAlpha
Resource Types[Pod]
Description

Specifies the requested memory setting for the Envoy sidecar.

sidecar.istio.io/proxyMemoryLimit

Namesidecar.istio.io/proxyMemoryLimit
Feature StatusAlpha
Resource Types[Pod]
Description

Specifies the memory limit for the Envoy sidecar.

sidecar.istio.io/rewriteAppHTTPProbers

Namesidecar.istio.io/rewriteAppHTTPProbers
Feature StatusAlpha
Resource Types[Pod]
Description

Rewrite HTTP readiness and liveness probes to be redirected to the Envoy sidecar.

sidecar.istio.io/statsHistogramBuckets

Namesidecar.istio.io/statsHistogramBuckets
Feature StatusAlpha
Resource Types[Pod]
Description

Specifies the custom histogram buckets with a prefix matcher to separate the Istio mesh metrics from the Envoy stats, e.g. {"istiocustom":[1,5,10,50,100,500,1000,5000,10000],"cluster.xds-grpc":[1,5,10,25,50,100,250,500,1000,2500,5000,10000]}. Default buckets are [0.5,1,5,10,25,50,100,250,500,1000,2500,5000,10000,30000,60000,300000,600000,1800000,3600000].

sidecar.istio.io/statsInclusionPrefixes

Namesidecar.istio.io/statsInclusionPrefixes
Feature StatusDeprecated
Resource Types[Pod]
Description

Specifies the comma separated list of prefixes of the stats to be emitted by Envoy.

sidecar.istio.io/statsInclusionRegexps

Namesidecar.istio.io/statsInclusionRegexps
Feature StatusDeprecated
Resource Types[Pod]
Description

Specifies the comma separated list of regexes the stats should match to be emitted by Envoy.

sidecar.istio.io/statsInclusionSuffixes

Namesidecar.istio.io/statsInclusionSuffixes
Feature StatusDeprecated
Resource Types[Pod]
Description

Specifies the comma separated list of suffixes of the stats to be emitted by Envoy.

sidecar.istio.io/status

Namesidecar.istio.io/status
Feature StatusAlpha
Resource Types[Pod]
Description

Generated by Envoy sidecar injection that indicates the status of the operation. Includes a version hash of the executed template, as well as names of injected resources.

sidecar.istio.io/userVolume

Namesidecar.istio.io/userVolume
Feature StatusAlpha
Resource Types[Pod]
Description

Specifies one or more user volumes (as a JSON array) to be added to the Envoy sidecar.

sidecar.istio.io/userVolumeMount

Namesidecar.istio.io/userVolumeMount
Feature StatusAlpha
Resource Types[Pod]
Description

Specifies one or more user volume mounts (as a JSON array) to be added to the Envoy sidecar.

status.sidecar.istio.io/port

Namestatus.sidecar.istio.io/port
Feature StatusAlpha
Resource Types[Pod]
Description

Specifies the HTTP status Port for the Envoy sidecar. If zero, the sidecar will not provide status.

topology.istio.io/controlPlaneClusters

Nametopology.istio.io/controlPlaneClusters
Feature StatusAlpha
Resource Types[Namespace]
Description

A comma-separated list of clusters (or * for any) running istiod that should attempt leader election for a remote cluster thats system namespace includes this annotation. Istiod will not attempt to lead unannotated remote clusters.

traffic.istio.io/nodeSelector

Nametraffic.istio.io/nodeSelector
Feature StatusStable
Resource Types[Service]
Description

This annotation is a set of node-labels (key1=value,key2=value). If the annotated Service is of type NodePort and is a multi-network gateway (see topology.istio.io/network), the addresses for selected nodes will be used for cross-network communication.

traffic.sidecar.istio.io/excludeInboundPorts

Nametraffic.sidecar.istio.io/excludeInboundPorts
Feature StatusAlpha
Resource Types[Pod]
Description

A comma separated list of inbound ports to be excluded from redirection to Envoy. Only applies when all inbound traffic (i.e. ‘*’) is being redirected.

traffic.sidecar.istio.io/excludeInterfaces

Nametraffic.sidecar.istio.io/excludeInterfaces
Feature StatusAlpha
Resource Types[Pod]
Description

A comma separated list of interfaces to be excluded from Istio traffic capture

traffic.sidecar.istio.io/excludeOutboundIPRanges

Nametraffic.sidecar.istio.io/excludeOutboundIPRanges
Feature StatusAlpha
Resource Types[Pod]
Description

A comma separated list of IP ranges in CIDR form to be excluded from redirection. Only applies when all outbound traffic (i.e. ‘*’) is being redirected.

traffic.sidecar.istio.io/excludeOutboundPorts

Nametraffic.sidecar.istio.io/excludeOutboundPorts
Feature StatusAlpha
Resource Types[Pod]
Description

A comma separated list of outbound ports to be excluded from redirection to Envoy.

traffic.sidecar.istio.io/includeInboundPorts

Nametraffic.sidecar.istio.io/includeInboundPorts
Feature StatusAlpha
Resource Types[Pod]
Description

A comma separated list of inbound ports for which traffic is to be redirected to Envoy. The wildcard character ‘*’ can be used to configure redirection for all ports. An empty list will disable all inbound redirection.

traffic.sidecar.istio.io/includeOutboundIPRanges

Nametraffic.sidecar.istio.io/includeOutboundIPRanges
Feature StatusAlpha
Resource Types[Pod]
Description

A comma separated list of IP ranges in CIDR form to redirect to Envoy (optional). The wildcard character ‘*’ can be used to redirect all outbound traffic. An empty list will disable all outbound redirection.

traffic.sidecar.istio.io/includeOutboundPorts

Nametraffic.sidecar.istio.io/includeOutboundPorts
Feature StatusAlpha
Resource Types[Pod]
Description

A comma separated list of outbound ports for which traffic is to be redirected to Envoy, regardless of the destination IP.

traffic.sidecar.istio.io/kubevirtInterfaces

Nametraffic.sidecar.istio.io/kubevirtInterfaces
Feature StatusAlpha
Resource Types[Pod]
Description

A comma separated list of virtual interfaces whose inbound traffic (from VM) will be treated as outbound.

Was this information useful?
Do you have any suggestions for improvement?

Thanks for your feedback!