ASM configuration recommendations

Mesh diagnosis

ASM supports mesh diagnosis for your instance. Diagnostic items include data plane version checks, service port checks, and service association checks. We recommend that you regularly use the mesh diagnosis feature to validate your configurations. For any check that fails, modify your configuration according to the provided prompts. For more information, see Use ASM Mesh Diagnosis. On the Mesh Diagnosis page, you can view the result status of each diagnostic item, which is either Warning or Passed.

Gateway

• Do not associate multiple Gateway CRs with the same domain name.

• Map one VirtualService to each Gateway. If you must associate multiple VirtualServices with a single Gateway, do not configure the same URI or URI range across the VirtualServices. This avoids unexpected routing priorities caused by the configuration merge order.

  • We recommend creating a separate VirtualService for each destination service.

  • When using the VirtualService Delegate feature, ensure that your CI/CD process can deploy a service independently with its own associated route configuration.

• Use one DestinationRule for each backend application service. In earlier versions, multiple DestinationRules for a single service could cause inconsistent configuration synchronization (xDS).

Mesh

• Traffic control rules for the same host cannot be distributed across multiple VirtualService resources. If multiple VirtualServices exist for the same host, only the most recently created one takes effect.

• Create the VirtualService and DestinationRule in the same namespace as the service.

• For a service that is also exposed at an ingress gateway, configure east-west traffic (routing for Sidecars) and north-south traffic (routing for the Gateway) separately.

API

General rules

• A custom resource (CR) in the istio-system namespace that does not include a workloadSelector typically applies to the entire cluster.

• A CR outside the istio-system namespace that does not include a workloadSelector typically applies to the namespace where it is defined.

ServiceEntry

• Closely monitor the addition of ServiceEntry resources to prevent granting arbitrary external access to a namespace.

• Hostname

  • A given hostname can have only one ServiceEntry. Multiple ServiceEntries for the same hostname lead to undefined behavior.

  • Do not create multiple ServiceEntries with overlapping hostnames. For example, two ServiceEntries with the hosts xx.example.com and example.com lead to undefined behavior at runtime.

  • You must use a fully qualified domain name (FQDN) as the hostname. Do not use short names that lack a period (.).

• Address

• Avoid using the NONE resolution mode unless the address field contains a CIDR block. A NONE-resolution ServiceEntry without an address field allows traffic to any IP address on the ports specified in the ServiceEntry.

VirtualService

• VirtualServices do not support inheritance. Therefore, the settings for a VirtualService that targets xx.example.com are independent of the settings for a VirtualService that targets example.com. If multiple VirtualServices with different wildcard hosts match a given hostname, only the settings from the most specific VirtualService are applied at runtime.

• For HTTP rules, prefer exact or prefix URL matches over regular expressions. Matching with regular expressions is slower and can cause unexpected behavior.

• Use only one VirtualService per hostname within the mesh, as multiple VirtualServices for the same host cause unexpected behavior. Avoid using short names for hosts in a VirtualService; their interpretation depends on the runtime context, and they can be ambiguous and are not guaranteed to be unique.

DestinationRule

A DestinationRule defines policies applied to network traffic after routing occurs. You can configure the following in a DestinationRule:

• Network traffic policies

• load balancing policy

• connection pool settings

• mTLS

• Resiliency

• Use labels (label) to specify service subsets, which can then be used in a VirtualService.

When configuring a DestinationRule, note the following:

• When you create subsets for traffic shifting, wait a few seconds after creating the DestinationRule with the subsets and before creating the VirtualService that routes to those subsets. This ensures that the corresponding Envoy upstream configuration is ready before Pilot sends the routing configuration that points to these subsets.

• You can use a wildcard DestinationRule to apply a single rule to a range of hosts. For example, a global DestinationRule in the istio-system root namespace can configure mTLS for all services that match the .local hostname. When you create a DestinationRule for a more specific hostname, such as .ns1.svc.cluster.local or svc1.ns1.svc.cluster.local, the most specific DestinationRule applies. Settings from other wildcard DestinationRules are not inherited. Therefore, any DestinationRule you write must include all the required options from the global DestinationRule, such as mTLS.

VirtualService and DestinationRule visibility

If access control is not strictly enforced, mesh operators might create a rule with an exportTo value of '.' in a client namespace to override the DestinationRule and VirtualService specified by the server. The DestinationRule and VirtualService for a service (defined in Kubernetes or a ServiceEntry) affect all Sidecars that communicate with that service. For example, settings like outlier detection and retry policies are enforced on the client-side Sidecar. Although letting each service consumer namespace write its own VirtualService and DestinationRule for a service in another namespace may seem convenient, this practice can lead to undefined behavior if the visibility of these custom configurations is not restricted.

Sidecar

• If access control is not strictly enforced, a namespace owner might override a globally specified Sidecar by declaring a dependency on */* in the egress.hosts section or by importing services and configurations from multiple namespaces with potentially conflicting settings. This makes the mesh behave as if no Sidecar resource exists.

• Use the Istio Sidecar resource to limit each workload's dependencies on other workloads in the system. A single Sidecar resource without a workloadSelector is sufficient to configure the default settings for an entire namespace. Each Sidecar resource specifies the hosts that workloads in the namespace need to access. These hosts correspond to the hostnames in Kubernetes services, Istio ServiceEntries, and Istio VirtualServices. Based on the imported service hostnames, the appropriate DestinationRules are also automatically imported from the services' namespaces. Sidecars declare dependencies on services in other namespaces in the egress.hosts field. Declaring a dependency on a hostname, with or without a wildcard, causes Pilot to search all namespaces where that host exists and import the configuration from all matching namespaces.

  #Example 1
  egress:
  - hosts:
    - "_/_"
  #Example 2
  egress:
  - hosts:
    - foo.example.com
    - .fun.com

  If conflicting ServiceEntries for the same host exist in multiple namespaces, or if conflicting VirtualServices for the same host exist in multiple namespaces (for example, with exportTo: *), the creation order of those resources determines which one is applied. This behavior can lead to unpredictable consequences in a production environment.

  • Sidecar resources do not support inheritance. If a namespace declares a Sidecar resource, the namespace-local Sidecar takes precedence over the global default Sidecar.

  • When multiple Sidecars have overlapping workloadSelectors, the Sidecar resource for a given pod is chosen at random. Therefore, when writing Sidecars with workloadSelectors, ensure that each Sidecar targets a distinct set of pods within its namespace.

Telemetry

• Do not configure two Telemetry CRs without a defined workloadSelector in the same namespace. If multiple are defined, which one takes effect is non-deterministic.

• In the same namespace, do not configure two Telemetry CRs with overlapping workloadSelector fields. If they overlap, which one takes effect is non-deterministic.

Service governance

Service governance can be configured at three levels: global, namespace, and workload. For example, you can create a permissive rule at the global scope (the istio-system namespace) and then override it with more specific configurations in certain namespaces based on business requirements. For critical applications, you can also use workload-level configurations to apply targeted settings.