Destination Rule CRD reference-Alibaba Cloud Service Mesh-阿里云帮助中心

A destination rule is a key Service Mesh (ASM) resource for traffic routing. A destination rule defines policies that apply to traffic for a service after routing has occurred. It specifies settings such as load balancing, sidecar connection pool size, and outlier detection. These settings help detect and remove unhealthy hosts from the load balancing pool. This topic provides configuration examples and field descriptions for destination rules.

Configuration examples

Example 1: Simple load balancing policy

The following destination rule uses the least request (LEAST_REQUEST) load balancing algorithm. This algorithm prioritizes endpoints with the fewest outstanding requests when it distributes the load.

apiVersion: networking.istio.io/v1beta1
kind: DestinationRule
metadata:
  name: bookinfo-ratings
spec:
  host: ratings.prod.svc.cluster.local
  trafficPolicy:
    loadBalancer:
      simple: LEAST_REQUEST

Example 2: Custom configuration for a port

You can customize traffic policies for specific ports. The following destination rule applies the least request (LEAST_REQUEST) load balancing policy to traffic on port 80 and the round robin (ROUND_ROBIN) load balancing policy to traffic on port 9080.

apiVersion: networking.istio.io/v1beta1
kind: DestinationRule
metadata:
  name: bookinfo-ratings-port
spec:
  host: ratings.prod.svc.cluster.local
  trafficPolicy: # Apply to all ports.
    portLevelSettings:
    - port:
        number: 80
      loadBalancer:
        simple: LEAST_REQUEST
    - port:
        number: 9080
      loadBalancer:
        simple: ROUND_ROBIN

Example 3: Custom configuration for a specific workload

The following example uses the workloadSelector configuration to apply the destination rule to a specific workload.

apiVersion: networking.istio.io/v1beta1
kind: DestinationRule
metadata:
  name: configure-client-mtls-dr-with-workloadselector
spec:
  host: example.com
  workloadSelector:
    matchLabels:
      app: ratings
  trafficPolicy:
    loadBalancer:
      simple: ROUND_ROBIN
    portLevelSettings:
    - port:
        number: 31443
      tls:
        credentialName: client-credential
        mode: MUTUAL

Field reference

DestinationRule

A destination rule defines policies that apply to traffic for a destination service after routing has occurred.

Field	Type	Required	Description
host	String	Yes	The name of a service in the service registry. The service name is looked up in the platform's service registry, such as Kubernetes services or Consul services, and in the hosts declared by ServiceEntry resources. Rules for services that are not defined in the service registry are ignored. This field applies to HTTP and TCP services. Notes for Kubernetes: When you use a short name, such as `reviews` instead of `reviews.default.svc.cluster.local`, Istio resolves the short name based on the namespace of the routing rule, not the service. A rule in the default namespace that contains a host named `reviews` is interpreted as `reviews.default.svc.cluster.local`, regardless of the actual namespace of the `reviews` service. To avoid potential misconfigurations, always use a fully qualified domain name (FQDN) instead of a short name.
trafficPolicy	TrafficPolicy	No	The traffic policy to apply, such as load balancing policy, connection pool size, and outlier detection.
subsets	Subset[]	No	One or more subsets that represent different versions of a service. The base traffic policy for the service can be overridden at the subset level.
exportTo	String[]	No	A list of namespaces to which the destination rule is exported. A destination rule is resolved in the context of a namespace. Exporting a destination rule allows it to be included in the resolution hierarchy for services in other namespaces. This feature provides a mechanism for service owners and mesh administrators to control the visibility of destination rules across namespace boundaries. If no namespace is specified, the destination rule is exported to all namespaces by default. The value `.` is reserved and defines an export to the same namespace as the destination rule. The value `*` is reserved and defines an export to all namespaces.
workloadSelector	WorkloadSelector	No	Criteria used to select the pods to which this destination rule applies. If specified, the destination rule configuration applies only to workload instances that match the labels in the same namespace. The workload selector does not match across namespaces. If not specified, the destination rule falls back to the default behavior, which is to apply to all workloads of the destination service. For example, you can specify a workload selector if a specific sidecar requires an egress TLS setting for a service outside the mesh, instead of having every sidecar in the mesh require that configuration, which is the default behavior.

TrafficPolicy

A traffic policy that applies to traffic for a specific destination. This policy applies to all ports of the destination.

Field	Type	Required	Description
loadBalancer	LoadBalancerSettings	No	Settings for the load balancing algorithm.
connectionPool	ConnectionPoolSettings	No	Settings for the connection pool for an upstream service.
outlierDetection	OutlierDetection	No	Settings for how to remove unhealthy hosts from the load balancing pool.
tls	ClientTLSSettings	No	TLS-related settings for connections to an upstream service.
portLevelSettings	PortTrafficPolicy[]	No	Traffic policies for specific ports. Port-level settings override destination-level settings. When a port-level traffic policy overrides a destination-level setting, other fields at the destination level are not inherited. Fields that are omitted in the port-level traffic policy use their default values.
tunnel	TunnelSettings	No	Tunnels TCP traffic through other transport-layer or application-layer protocols for the host specified in the destination rule. TunnelSettings can be applied to TCP or TLS routes, but not to HTTP routes.

Subset

A subset is a collection of endpoints for a service. You can use subsets for scenarios such as A/B testing or routing to a specific version of a service. Traffic policies defined at the service level can be overridden at the subset level. For more information, see Virtual Service CRD reference.

Destination rules can specify named service subsets, such as grouping all instances of a given service by version. These service subsets are used in the routing rules of a virtual service to control traffic to different instances of a service. You can specify policies for a specific version in a subset to override the settings at the service level. The following destination rule uses the round robin (ROUND_ROBIN) load balancing policy to send all traffic to a subset named testversion. This subset consists of endpoints with the label version: v3.

Note

The load balancing policy specified for a subset takes effect only when the destination rule sends traffic to that subset.

Click to view a YAML example

apiVersion: networking.istio.io/v1beta1
kind: DestinationRule
metadata:
  name: bookinfo-ratings
spec:
  host: ratings.prod.svc.cluster.local
  trafficPolicy:
    loadBalancer:
      simple: LEAST_REQUEST
  subsets:
  - name: testversion
    labels:
      version: v3
    trafficPolicy:
      loadBalancer:
        simple: ROUND_ROBIN

Typically, one or more labels are required to specify the targets included in a subset. A subset without labels can be ambiguous when the hostname represented by the destination rule supports multiple SNI hostnames, such as an egress gateway. In this case, you can use a traffic policy that includes ClientTLSSettings to identify the specific SNI host that corresponds to the named subset.

Field	Type	Required	Description
name	String	Yes	The name of the subset. The service name and subset name can be used for traffic splitting in a routing rule.
labels	Map<String, String>	No	Labels used to create a filter that selects endpoints of the service in the service registry.
trafficPolicy	TrafficPolicy	No	The traffic policy to apply to this subset. A subset inherits the traffic policy specified at the DestinationRule level. Settings specified at the subset level override the corresponding settings at the DestinationRule level.

LoadBalancerSettings

Load balancing policies for a specific destination. For more information, see Load Balancing.

The following destination rule uses the round robin load balancing policy for all traffic sent to the ratings service.

Click to view a load balancing policy YAML example

apiVersion: networking.istio.io/v1beta1
kind: DestinationRule
metadata:
  name: bookinfo-ratings
spec:
  host: ratings.prod.svc.cluster.local
  trafficPolicy:
    loadBalancer:
      simple: ROUND_ROBIN

The following destination rule configures session persistence for the ratings service. It uses a hash-based load balancer and sets the httpCookie field to use the user cookie as the hash key.

Click to view a session persistence YAML example

apiVersion: networking.istio.io/v1alpha3
kind: DestinationRule
metadata:
  name: bookinfo-ratings
spec:
  host: ratings.prod.svc.cluster.local
  trafficPolicy:
    loadBalancer:
      consistentHash:
        httpCookie:
          name: user
          ttl: 0s

Note

In the following table, oneof in the Type column indicates that you can set only one of the available fields.

Field	Type	Required	Description
simple	SimpleLB (oneof)	No	Specifies a simple load balancing algorithm.
consistentHash	ConsistentHashLB (oneof)	No	Specifies a consistent hashing load balancing algorithm.
localityLbSetting	LocalityLoadBalancerSetting	No	Locality load balancer settings. This configuration completely overrides the mesh-wide settings. This object and the object in MeshConfig are not merged.
warmupDurationSecs	Duration	No	This parameter is deprecated in ASM instances 1.24 and later. Use `warmup`. The warmup duration for the service. If this field is set, new endpoints of the service enter a warmup mode for the specified duration, starting from their creation time. During this period, Istio gradually increases the traffic to the endpoint instead of sending a proportional amount of traffic. Enable this configuration for services that require a warmup period to reach full working capacity at an appropriate latency. This configuration is most effective when there are a small number of new endpoints, such as during a Kubernetes scale-out event. It is less effective when all endpoints are relatively new, such as during a new deployment, because all endpoints eventually receive the same number of requests. This configuration supports only the `ROUND_ROBIN` and `LEAST_REQUEST` load balancing algorithms.
warmup	WarmupConfiguration	No	The warmup duration for the service. If this field is set, new endpoints of the service enter a warmup mode for the specified duration, starting from their creation time. During this period, Istio gradually increases the traffic to the endpoint instead of sending a proportional amount of traffic. Enable this configuration for services that require a warmup period to reach full working capacity at an appropriate latency. This configuration is most effective when there are a small number of new endpoints, such as during a Kubernetes scale-out event. It is less effective when all endpoints are relatively new, such as during a new deployment, because all endpoints eventually receive the same number of requests. This configuration supports only the `ROUND_ROBIN` and `LEAST_REQUEST` load balancing algorithms.

WarmupConfiguration

Field	Type	Required	Description
duration	Duration	Yes	The warmup duration.
minimumPercent	DoubleValue	No	Configures the minimum percentage of traffic relative to normal traffic. Default value: 10.
aggression	DoubleValue	No	This parameter controls how quickly traffic increases during the warmup period. The default value is 1.0, which causes the node to increase traffic linearly. If you increase this parameter, the traffic increases non-linearly.

ConnectionPoolSettings

Connection pool settings for connections to an upstream host. These settings apply to each host in the upstream service. For more information, see Envoy's circuit breaker. You can apply connection pool settings at the TCP and HTTP levels.

For example, the following rule sets a limit of 100 connections and a connection timeout of 30 ms for a Redis service named myredissrv.

Click to view a DestinationRule YAML example

apiVersion: networking.istio.io/v1beta1
kind: DestinationRule
metadata:
  name: bookinfo-redis
spec:
  host: myredissrv.prod.svc.cluster.local
  trafficPolicy:
    connectionPool:
      tcp:
        maxConnections: 100
        connectTimeout: 30ms
        tcpKeepalive:
          time: 7200s
          interval: 75s

Field	Type	Required	Description
tcp	TCPSettings	No	Common settings for HTTP and TCP upstream connections.
http	HTTPSettings	No	HTTP connection pool settings.

OutlierDetection

A circuit breaker that tracks the status of hosts in an upstream service. It applies to HTTP and TCP services.

For HTTP services, a host that continuously returns 5xx errors for API calls is removed from the pool of available hosts for a specified period.
For TCP services, connection timeouts or connection failures for a given host are considered errors when calculating the consecutive error metric. For more information, see Envoy's outlier detection.

The following destination rule sets the connection pool size to 100 HTTP/1 connections and allows no more than 10 requests or connections to the reviews service. It sets a limit of 1,000 concurrent requests for HTTP/2 and configures upstream hosts to be scanned every 5 minutes. Any host that returns a 502, 503, or 504 error code for 7 consecutive times is ejected for 15 minutes.

Click to view a DestinationRule YAML example

apiVersion: networking.istio.io/v1beta1
kind: DestinationRule
metadata:
  name: reviews-cb-policy
spec:
  host: reviews.prod.svc.cluster.local
  trafficPolicy:
    connectionPool:
      tcp:
        maxConnections: 100
      http:
        http2MaxRequests: 1000
        maxRequestsPerConnection: 10
    outlierDetection:
      consecutive5xxErrors: 7
      interval: 5m
      baseEjectionTime: 15m

Field	Type	Required	Description
splitExternalLocalOriginErrors	Bool	No	Specifies whether to distinguish between local origin failures and external errors. The default value is false. If set to true, consecutiveLocalOriginFailures is used in the outlier detection calculation. Use this feature in the following scenarios. Calculate the outlier status based on locally observed errors, such as connection failures and connection timeouts, instead of the status codes returned by the upstream service. Ignore responses from the upstream service to determine the outlier detection status of a host when the upstream service explicitly returns 5xx for some requests.
consecutiveLocalOriginFailures	UInt32Value	No	The number of consecutive local origin failures required to trigger an ejection. The default value is 5. This field takes effect only when splitExternalLocalOriginErrors is set to true.
consecutiveGatewayErrors	UInt32Value	No	The number of gateway errors required to eject a host from the connection pool. When an upstream host is accessed over HTTP, 502, 503, or 504 return codes are considered gateway errors. When an upstream host is accessed over an opaque TCP connection, connection timeout and connection error/failure events are considered gateway errors. This feature is disabled by default or when the value is set to 0. Note `consecutiveGatewayErrors` and `consecutive5xxErrors` can be used independently or together. Because the errors counted by `consecutiveGatewayErrors` are also included in `consecutive5xxErrors`, `consecutiveGatewayErrors` has no effect if its value is greater than or equal to the value of `consecutive5xxErrors`.
consecutive5xxErrors	UInt32Value	No	The number of 5xx errors required to eject a host from the connection pool. When an upstream host is accessed over an opaque TCP connection, connection timeouts, connection errors or failures, and request failure events are all considered 5xx errors. The default value is 5. You can disable this feature by setting the value to 0.
interval	Duration	No	The time interval for ejection scanning. The format is `1h`/`1m`/`1s`/`1ms`. The value must be ≥ `1ms`. The default value is 10s.
baseEjectionTime	Duration	No	The minimum ejection duration. The time a host is ejected from the connection pool is the product of the minimum ejection duration and the number of times the host has been ejected. This field allows the system to automatically increase the ejection time for unhealthy upstream servers. The format is `1h`/`1m`/`1s`/`1ms`. The value must be ≥ `1ms`. The default value is 30s.
maxEjectionPercent	Int32	No	The maximum percentage of upstream service hosts in the load balancing pool that can be ejected. The default value is 10%.
minHealthPercent	Int32	No	Enables outlier detection when at least `min_health_percent` of the hosts in the load balancing pool are healthy. When the percentage of healthy hosts in the load balancing pool falls below this threshold, outlier detection is disabled, and the proxy load balances across all hosts in the pool, both healthy and unhealthy. You can disable this threshold by setting it to 0%. The default value is 0% because it is generally not applicable to Kubernetes environments where each service has only a few pods.

ClientTLSSettings

SSL/TLS settings for upstream connections. This configuration applies to HTTP and TCP upstreams. For more information, see Envoy's TLS context.

The following destination rule configures the client to use a mutual TLS connection to an upstream database cluster.

Click to view a YAML example

apiVersion: networking.istio.io/v1beta1
kind: DestinationRule
metadata:
  name: db-mtls
spec:
  host: mydbserver.prod.svc.cluster.local
  trafficPolicy:
    tls:
      mode: MUTUAL
      clientCertificate: /etc/certs/myclientcert.pem
      privateKey: /etc/certs/client_private_key.pem
      caCertificates: /etc/certs/rootcacerts.pem

The following destination rule configures the client to use TLS when communicating with external services that match the domain name *.foo.com.
Click to view a YAML example
```
apiVersion: networking.istio.io/v1beta1
kind: DestinationRule
metadata:
  name: tls-foo
spec:
  host: "*.foo.com"
  trafficPolicy:
    tls:
      mode: SIMPLE
```

The following destination rule configures the client to use Istio mutual TLS when communicating with the ratings service.

Click to view a YAML example

apiVersion: networking.istio.io/v1beta1
kind: DestinationRule
metadata:
  name: ratings-istio-mtls
spec:
  host: ratings.prod.svc.cluster.local
  trafficPolicy:
    tls:
      mode: ISTIO_MUTUAL

Field	Type	Required	Description
mode	TLSmode	Yes	Specifies whether to secure connections to this port with TLS. The value of this field determines how TLS is applied.
clientCertificate	String	No	The file path of the client-side TLS certificate. This field is required if `mode` is `MUTUAL`. This field must be empty if `mode` is `ISTIO_MUTUAL`.
privateKey	String	No	The file path of the client private key. This field is required if `mode` is `MUTUAL`. This field must be empty if `mode` is `ISTIO_MUTUAL`.
caCertificates	String	No	The file path of the CA certificate used to verify the certificate. If omitted, the proxy does not verify the server's certificate. This field must be empty if `mode` is `ISTIO_MUTUAL`.
credentialName	String	No	The name of the secret that stores the client TLS certificate, including the CA certificate. The secret must exist in the same namespace as the proxy that uses the certificate. Both `generic` and `tls` secret types are supported. If the secret type is `generic`, it should contain the following keys and values: `key: <privateKey>, cert: <clientCert>, cacert: <CACertificate>`. The `CACertificate` is used to verify the server certificate. If the secret type is tls, it should contain the client certificate and the `ca.crt` key from the CA certificate. You can specify only one of the following at a time. `clientCertificate` and `caCertificates` `credentialName` Note This field takes effect for a sidecar only when a workload selector (workloadSelector) is specified in the `DestinationRule`. Otherwise, this field applies only to gateways, and sidecars continue to use the certificate path.
subjectAltNames	String[]	No	A list of subject alternative names used to verify the identity of the subject in the certificate. If specified, the proxy verifies that the subject alternative name of the server certificate matches one of the values in the specified list. This list overrides the value of `subjectAltNames` in the ServiceEntry. If not specified, when the `VERIFY_CERTIFICATE_AT_CLIENT` and `ENABLE_AUTO_SNI` environment variables are set to true, the upstream-presented certificate is automatically verified against the downstream HTTP Host or Authority header.
sni	String	No	The SNI string presented to the server during the TLS handshake. If not specified, when the `ENABLE_AUTO_SNI` environment variable is set to `true`, the SNI is automatically set based on the downstream HTTP Host or Authority header in simple TLS and mutual TLS modes.
insecureSkipVerify	BoolValue	No	This field specifies whether the proxy skips verifying the CA signature and SAN of the server certificate corresponding to the host. The default value is false. Set this flag only when global CA signature verification is enabled, the `VerifyCertAtClient` environment variable is set to `true`, and you do not want to perform verification for a specific host. If `InsecureSkipVerify` is enabled, verification of the CA signature and SAN is skipped, regardless of whether `VerifyCertAtClient` is enabled.

LocalityLoadBalancerSetting

Provides locality-weighted load balancing, which allows administrators to control the proportion of traffic distributed to endpoints based on the traffic's source and destination locations. You can specify locality information using labels. These labels specify the hierarchy of a locality in the format {region}/{zone}/{sub-zone}. For more information, see Locality Weight.

The following example shows how to set locality weighting across the entire mesh. Assume a mesh with workloads and services is deployed to the localities hangzhou/zone1/ and hangzhou/zone2/. This example specifies that when traffic to a service originates from a workload in hangzhou/zone1/, 80% of the traffic is sent to endpoints in hangzhou/zone1/ (the same locality), and the remaining 20% is sent to endpoints in hangzhou/zone2/. This setting prioritizes routing traffic to endpoints in the same locality. A similar setting is specified for traffic originating from hangzhou/zone2/.
Click to view a YAML example
```
  distribute:
    - from: hangzhou/zone1/*
      to:
        "hangzhou/zone1/*": 80
        "hangzhou/zone2/*": 20
    - from: hangzhou/zone2/*
      to:
        "hangzhou/zone1/*": 20
        "hangzhou/zone2/*": 80
```
If your goal is to limit failover locality rather than distribute the load across regions or zones, you can set a failover policy instead of a distribute policy.
The following example sets a locality failover policy. Assume the service resides in the Hangzhou, Beijing, and Shanghai regions. This policy specifies that when endpoints in Hangzhou become unhealthy, traffic is transferred to endpoints in the Beijing region or sub-region. Similarly, when endpoints in Beijing become unhealthy, traffic is transferred to endpoints in Shanghai.
Click to view a YAML example
```
 failover:
   - from: hangzhou
     to: beijing
   - from: beijing
     to: shanghai
```

Field	Type	Required	Description
distribute	Distribute[]	No	Explicitly specifies load balancing weights across different regions and geographical locations. If empty, locality weights are set based on the number of endpoints in them. For more information, see Locality weighted load balancing. Note You can set only one of the `distribute`, `failover`, and `failoverPriority` configuration items at a time.
failover	Failover[]	No	Explicitly specifies which locality traffic will be transferred to when endpoints in the local locality become unhealthy. This field needs to be used with `OutlierDetection` to detect unhealthy endpoints. If `OutlierDetection` is not specified, this setting will not take effect.
failoverPriority	String[]	No	An ordered list of labels used to sort endpoints for priority-based load balancing. This field is used to support traffic failover across different endpoint groups. This field needs to be used with `OutlierDetection` to monitor unhealthy endpoints. If `OutlierDetection` is not specified, this setting will not take effect. Assume a total of N labels are specified: Endpoints that match all N labels with the client proxy have priority P(0), which is the highest priority. Endpoints that match the first N-1 labels with the client proxy have priority P(1), which is the second-highest priority. By extending this logic, endpoints that only match the first label with the client proxy have priority P(N-1), which is the second-lowest priority. All other endpoints have priority P(N), which is the lowest priority. Note For a label to match, all preceding labels must also match. That is, the Nth label is considered a match only if the first N-1 labels also match. This field can be any label specified on the client and server workloads and supports the following labels with special semantics: `topology.istio.io/network`: Used to match the network metadata of the endpoint. It can be specified by the pod or namespace label `topology.istio.io/network` and the sidecar environment variable `ISTIO_META_NETWORK`. `topology.istio.io/cluster`: Used to match the clusterID of the endpoint. It can be specified by the pod label `topology.istio.io/cluster` or the pod environment variable `ISTIO_META_CLUSTER_ID`. `topology.kubernetes.io/region`: Used to match the region metadata of the endpoint. It maps to the Kubernetes node label `topology.kubernetes.io/region` or the deprecated label `failure-domain.beta.kubernetes.io/region`. `topology.kubernetes.io/zone`: Used to match the zone metadata of the endpoint. It maps to the Kubernetes node label `topology.kubernetes.io/zone` or the deprecated label `failure-domain.beta.kubernetes.io/zone`. `topology.istio.io/subzone`: Used to match the sub-zone metadata of the endpoint. It maps to the Istio node label `topology.istio.io/subzone`. The priorities for the following topology configuration are described as follows: `failoverPriority: - "topology.istio.io/network" - "topology.kubernetes.io/region" - "topology.kubernetes.io/zone" - "topology.istio.io/subzone"` Endpoints with the same `network`, `region`, `zone`, and `subzone` labels as the client proxy have the highest priority. Endpoints with the same `network`, `region`, and `zone` labels as the client proxy but a different `subzone` label have the second-highest priority. Endpoints with the same `network` and `region` labels as the client proxy but a different `zone` label have the third-highest priority. All other endpoints with a different `network` label than the client proxy have the lowest priority.
enabled	BoolValue	No	Enables locality load balancing. This configuration is at the DestinationRule level and will completely override the mesh-level settings. For example, if this field is configured as true, locality load balancing is enabled for this DestinationRule regardless of the mesh-level settings.

TrafficPolicy.PortTrafficPolicy

A traffic policy for a specific port of a service.

Field	Type	Required	Description
port	PortSelector	No	Specifies the port number on the destination service to which this policy applies.
loadBalancer	LoadBalancerSettings	No	Controls the load balancer algorithm.
connectionPool	ConnectionPoolSettings	No	Controls the number of connections to the upstream service.
outlierDetection	OutlierDetection	No	Controls the ejection of unhealthy hosts from the load balancing pool.
tls	ClientTLSSettings	No	TLS-related settings for connections to an upstream service.

LoadBalancerSettings.ConsistentHashLB

You can use consistent hash-based load balancing to provide soft session persistence based on HTTP headers, cookies, or other properties. Consistent hashing is weaker than traditional hostname-based session persistence. When one or more hosts are added or removed, load balancing using a consistent hashing algorithm causes a small fraction of requests to lose session persistence. Hostname-based session persistence typically encodes a specific destination in a cookie, ensuring that the association is maintained as long as the backend remains unchanged.

The advantage of consistent hashing is that it can achieve better load balancing and is more suitable for cloud-based systems.

Consistent hashing depends on each proxy having a consistent view of the endpoints. When locality load balancing is enabled, it is not guaranteed that each proxy has a consistent view of the endpoints. Locality load balancing and consistent hashing can only work together when all proxies are in the same locality, or when a higher-level load balancer is used to handle locality affinity.

Field	Type	Required	Description
httpHeaderName	String	No	Hash based on a specific HTTP header. You can configure only one of `httpHeaderName`, `httpCookie`, `useSourceIp`, and `httpQueryParameterName` at a time.
httpCookie	HTTPCookie	No	Hash based on an HTTP cookie.
useSourceIp	Bool	No	Hash based on the source IP address. This applies to TCP and HTTP connections.
httpQueryParameterName	String	No	Hash based on a specified HTTP query parameter.
ringHash	RingHash	No	The Ring or Modulo load balancer implements consistent hashing for backend hosts. You can configure only one of the `ringHash` and `maglev` parameters at a time. If neither is configured, `ringHash` is used by default.
maglev	MagLev	No	The Maglev load balancer implements consistent hashing for backend hosts. ASM supports the `maglev` algorithm starting from version 1.16.
minimumRingSize	Uint64	No	Deprecated. Use `ringHash` instead.

LoadBalancerSettings.ConsistentHashLB.RingHash

Field	Type	Required	Description
minimumRingSize	Uint64	No	The minimum number of virtual nodes for the Ring algorithm. The default value is 1024. A larger ring results in more fine-grained load distribution. If the number of hosts in the load balancing pool is greater than the ring size, each host will be assigned one virtual node.

LoadBalancerSettings.ConsistentHashLB.MagLev

Field	Type	Required	Description
tableSize	Uint64	No	The size of the hash table in the Maglev algorithm, which helps control disruption when backend hosts change. Increasing the table size can reduce the degree of disruption.

LoadBalancerSettings.ConsistentHashLB.HTTPCookie

Specifies the cookie that will be used as the hash key for the consistent hash load balancer. If the cookie does not exist, it will be generated.

Field	Type	Required	Description
name	String	Yes	The content of this cookie will be used as the hash key. If this cookie does not exist and the ttl below is not set, no hash will be generated.
path	String	No	If specified, a cookie with a TTL will be generated when this cookie does not exist. If the TTL exists and is equal to zero, the generated cookie will be a session cookie.
ttl	Duration	Yes	The lifecycle of the cookie.

ConnectionPoolSettings.TCPSettings

Common settings for HTTP and TCP upstream connections.

Field	Type	Required	Description
maxConnections	Int32	No	The maximum number of HTTP/1 or TCP connections to a destination host. The default value is 4294967295.
connectTimeout	Duration	No	The TCP connection timeout duration. The format is `1h`/`1m`/`1s`/`1ms`. The value must be ≥ `1ms`. The default value is 10s.
tcpKeepalive	TcpKeepalive	No	If set, SO_KEEPALIVE needs to be set on the socket to enable TCP keepalive.
maxConnectionDuration	Duration	No	The maximum duration of a connection. The duration is defined as the interval since the connection was established. If not set, there is no maximum duration. When `maxConnectionDuration` is reached, the connection will be closed. The duration must be at least `1ms`.

ConnectionPoolSettings.HTTPSettings

Settings applicable to HTTP/1.1, HTTP/2, and gRPC connections.

Field	Type	Required	Description
http1MaxPendingRequests	Int32	No	The maximum number of requests that can be queued waiting for a connection to be ready. The default value is 1024. This configuration applies to HTTP/1.1 and HTTP/2. For information about when a new connection is created for HTTP/2, see circuit_breaking.
http2MaxRequests	Int32	No	The maximum number of active requests to a destination. The default value is 1024. This configuration applies to HTTP/1.1 and HTTP/2.
maxRequestsPerConnection	Int32	No	The maximum number of requests per connection. Setting this parameter to 1 disables HTTP keepalive. The default value is 0, which means no limit. The maximum value is 2^29.
maxRetries	Int32	No	The maximum number of retries that can be made to all hosts in a cluster at a given time. The default value is 4294967295.
idleTimeout	Duration	No	The idle timeout for connections in the upstream connection pool. The idle timeout is the period during which there are no active requests. If not set, the default is 1 hour. When the idle timeout is reached, the connection is closed. If the connection is an HTTP/2 connection, a Drain Sequence is sent before the connection is closed. A request-based timeout indicates that an HTTP/2 PING will not keep the connection alive. This configuration applies to HTTP/1.1 and HTTP/2 connections.
h2UpgradePolicy	H2UpgradePolicy	No	Specifies whether to upgrade HTTP/1.1 connections to the corresponding destination to HTTP/2 connections.
useClientProtocol	Bool	No	If set to `true`, the protocol used by the client will be preserved when initiating a connection to the backend, and `h2UpgradePolicy` will be invalid. This means the client connection will not be upgraded to HTTP/2.

ConnectionPoolSettings.TCPSettings.TcpKeepalive

Settings related to TCP keepalive.

Field	Type	Required	Description
probes	Uint32	No	The maximum number of keepalive probes to send without a response before determining the connection is dead. The default uses the operating system-level configuration unless overridden. The default for Linux is `9`.
time	Duration	No	The duration a connection needs to be idle before keepalive probes start being sent. The default uses the operating system-level configuration unless overridden. The default for Linux is `7200s`, which is two hours.
interval	Duration	No	The interval between keepalive probes. The default uses the operating system-level configuration unless overridden. The default for Linux is `75s`.

google.protobuf.UInt32Value

Wrapper message for Uint32.

Field	Type	Required	Description
value	Uint32	No	The Uint32 value. In JSON, `UInt32Value` needs to be represented as a JSON numeric value.

LoadBalancerSettings.SimpleLB

Standard load balancing algorithms.

Field	Description
UNSPECIFIED	Does not specify a load balancing algorithm. Istio will choose a suitable default.
RANDOM	The random load balancing algorithm randomly selects a healthy host. If no health check policy is configured, the random load balancer generally performs better than round robin.
PASSTHROUGH	This option forwards the connection to the original IP address requested by the caller without any form of load balancing. This is an advanced use case. Use with caution. For more information, see Original destination.
ROUND_ROBIN	The basic round robin load balancing policy. It is less safe in many scenarios, such as when using endpoint weighting, because it can overload endpoints. In general, it is better to use `LEAST_REQUEST` as an alternative to `ROUND_ROBIN`.
LEAST_REQUEST	The least request load balancer prioritizes endpoints with the fewest outstanding requests when distributing the load. It is generally safer and superior to `ROUND_ROBIN` in almost all cases. Use `LEAST_REQUEST` as an alternative to `ROUND_ROBIN`.
LEAST_CONN	Deprecated. Use `LEAST_REQUEST` instead.

ConnectionPoolSettings.HTTPSettings.H2UpgradePolicy

Policy for upgrading HTTP/1.1 connections to HTTP/2.

Field	Description
DEFAULT	Use the global default value.
DO_NOT_UPGRADE	Do not upgrade the connection to HTTP/2.
UPGRADE	Upgrade the connection to HTTP/2.

ClientTLSSettings.TLSmode

TLS connection mode.

Field	Description
DISABLE	Do not establish a TLS connection to the upstream endpoint.
SIMPLE	Establish a TLS connection to the upstream endpoint.
MUTUAL	Secure the connection to the upstream with mutual TLS by providing a client certificate for authentication.
ISTIO_MUTUAL	Secure the connection to the upstream with mutual TLS by providing a client certificate for authentication. Compared to the `Mutual` mode, this mode uses Istio-auto-generated certificates for mTLS authentication. When using this mode, all other fields in `ClientTLSSettings` should be empty.