Note: Canonical Services are supported automatically in Anthos Service Mesh version 1.6.8 and higher.
Canonical Services is a group of workloads that implement the same service(s) and API(s). For supported workload types, Anthos Service Mesh automatically creates Canonical Service resources based on existing information from the Kubernetes API Server. This page explains what labels automatically define Canonical Services and how you can manually adjust the boundaries of your services.
The currently supported workload instance types are:
- Kubernetes Pods (including via Kubernetes Deployments, Kube Run Services, etc.)
- Virtual Machine instances
What defines Canonical Services
Anthos Service Mesh determines the Canonical Service membership by reading the
service.istio.io/canonical-name
label
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 Istio WorkloadEntry resource
Canonical Services have the same Kubernetes namespace as their associated workload instances and cannot span namespaces.
Automatic labeling rules
Anthos Service Mesh automatically groups your workloads into Canonical 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 Kubernetes app.kubernetes.io/name
and
app
labels. Note that the former label takes precedence.
If you use either of these two labels on your workloads, no further work is required.
Automatic labeling in Virtual Machines
To build Canonical Services on your VMs, you must add your VMs to a service mesh by configuring a WorkloadEntry resource in your Kubernetes API server.
Manually labeling
To manually apply or override a Canonical Service label apply the
service.istio.io/canonical-name
label to your Pod or WorkloadEntry
configurations.
Manual labeling in Kubernetes Pods
To deploy many Pods at once using a Deployment,
set the service.istio.io/canonical-name
label on the PodTemplateSpec:
apiVersion: apps/v1
kind: Deployment
metadata:
name: my-deployment
namespace: my-namespace
spec:
replicas: 3
template:
metadata:
labels:
service.istio.io/canonical-name: my-service
spec:
containers:
...
To label the Canonical Service of a single Pod, add the
service.istio.io/canonical-name
label to the labels
section of your Pod
configuration:
apiVersion: v1
kind: Pod
metadata:
name: my-test-pod
namespace: my-namespace
labels:
service.istio.io/canonical-name: my-service
spec:
...
Label virtual machines manually
To label the Canonical Service of a single VM/WorkloadEntry, add the
service.istio.io/canonical-name
label to the "labels" section of your
WorkloadEntry configuration:
apiVersion: networking.istio.io/v1alpha3
kind: WorkloadEntry
metadata:
name: my-vm-123
namespace: my-namespace
labels:
service.istio.io/canonical-name: my-service
spec:
...