Defining a Canonical Service

Note: Canonical Services are supported automaticallyin Cloud Service Mesh version 1.6.8 and higher.

Canonical Services is a group of workloadsthat implement the same service(s) and API(s). For supported workload types,Cloud Service Mesh automatically creates Canonical Service resources based on existinginformation from the Kubernetes API Server. This page explains what labelsautomatically define Canonical Services and how you can manually adjust theboundaries of your services.The currently supported workload instance types are:

  • Kubernetes Pods (including via Kubernetes Deployments, Kube Run Services, etc.)
  • Virtual Machine instances
  • Mesh-external services (specifically, ServiceEntry resources with a locationofMESH_EXTERNAL)

What defines Canonical Services

Cloud Service Mesh determines the Canonical Service membership by reading theservice.istio.io/canonical-namelabel on the Kubernetes configuration resource associated with each workload instance:

  • For Pods, the label is in the Kubernetes Pod resource
  • For VMs, the label in the IstioWorkloadEntry resource
  • For external services, the label is in the IstioServiceEntry resource

Canonical Services have the sameKubernetes namespace as their associated workload instances and cannot span namespaces.

Automatic labeling rules

Cloud Service Mesh automatically groups your Pod- and VM-based workloads intoCanonical Services with no action on your part.You only need to take action to:

  • Adjust labels for user/reader clarity
  • Override the default behavior.

Automatic labeling in Kubernetes Pods

Canonical Services focus around the Kubernetesapp.kubernetes.io/name andapp labels. Note that the former label takes precedence.If you use either of these two labels on your workloads, no further work isrequired.

Automatic labeling in Virtual Machines

To build Canonical Services on your VMs, you must add your VMs to aservice mesh by configuring aWorkloadEntry resource in your Kubernetes API server.

Manually labeling

To manually apply or override a Canonical Service label apply theservice.istio.io/canonical-name label to supported workload resourceconfigurations.In order for an external service to be recognized as a Canonical Service, youmust manually label the applicable ServiceEntry.

Manual labeling in Kubernetes Pods

To deploy many Pods at once using aDeployment,set theservice.istio.io/canonical-name label on the PodTemplateSpec:

apiVersion:apps/v1kind:Deploymentmetadata:name:my-deploymentnamespace:my-namespacespec:replicas:3template:metadata:labels:service.istio.io/canonical-name:my-servicespec:containers:...

To label the Canonical Service of a single Pod, add theservice.istio.io/canonical-name label to thelabels section of your Podconfiguration:

apiVersion:v1kind:Podmetadata:name:my-test-podnamespace:my-namespacelabels:service.istio.io/canonical-name:my-servicespec:...

Label virtual machines manually

To label the Canonical Service of a single VM/WorkloadEntry, add theservice.istio.io/canonical-name label to the "labels" section of yourWorkloadEntry configuration:

apiVersion:networking.istio.io/v1alpha3kind:WorkloadEntrymetadata:name:my-vm-123namespace:my-namespacelabels:service.istio.io/canonical-name:my-servicespec:...

Label external services manually

To label the Canonical Service of a single external service/ServiceEntry, add theservice.istio.io/canonical-name label to the "labels" section of yourServiceEntry configuration:

apiVersion:networking.istio.io/v1alpha3kind:ServiceEntrymetadata:name:example-comnamespace:my-namespacelabels:service.istio.io/canonical-name:an-external-servicespec:location:MESH_EXTERNAL...

What's next

Except as otherwise noted, the content of this page is licensed under theCreative Commons Attribution 4.0 License, and code samples are licensed under theApache 2.0 License. For details, see theGoogle Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.

Last updated 2026-02-19 UTC.