# Defining a Canonical Service


**Note:** Canonical Services are supported automatically in Cloud Service Mesh version 1.6.8 and higher.

[Canonical Services](https://docs.cloud.google.com/service-mesh/v1.27/docs/canonical-service.md.txt) is a group of workloads
that implement the same service(s) and API(s). For supported workload types,
Cloud 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
- Mesh-external services (specifically, ServiceEntry resources with a location of `MESH_EXTERNAL`)

## What defines Canonical Services

Cloud Service Mesh determines the Canonical Service membership by reading the
`service.istio.io/canonical-name`
[label](https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/)
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](https://istio.io/v1.27/docs/reference/config/networking/workload-entry/) resource
- For external services, the label is in the Istio [ServiceEntry](https://istio.io/v1.27/docs/reference/config/networking/service-entry/) resource

Canonical Services have the same
[Kubernetes namespace](https://kubernetes.io/docs/concepts/overview/working-with-objects/namespaces/)
as their associated workload instances and cannot span namespaces.

## Automatic labeling rules

Cloud Service Mesh automatically groups your Pod- and VM-based 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](https://istio.io/latest/docs/reference/config/networking/workload-entry/)
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 supported workload resource
configurations.
In order for an external service to be recognized as a Canonical Service, you
must manually label the applicable ServiceEntry.

### Manual labeling in Kubernetes Pods

To deploy many Pods at once using a
[Deployment](https://kubernetes.io/docs/concepts/workloads/controllers/deployment/),
set the `service.istio.io/canonical-name` label on the PodTemplateSpec:

```yaml
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:

```yaml
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:

```yaml
apiVersion: networking.istio.io/v1alpha3
kind: WorkloadEntry
metadata:
  name: my-vm-123
  namespace: my-namespace
  labels:
    service.istio.io/canonical-name: my-service
spec:
  ...
```

### Label external services manually

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

```yaml
apiVersion: networking.istio.io/v1alpha3
kind: ServiceEntry
metadata:
  name: example-com
  namespace: my-namespace
  labels:
    service.istio.io/canonical-name: an-external-service
spec:
   location: MESH_EXTERNAL
  ...
```

## What's next

- [Learn about Canonical Services](https://docs.cloud.google.com/service-mesh/v1.27/docs/canonical-service.md.txt)
- [Learn about best practices in Canonical Services](https://docs.cloud.google.com/service-mesh/v1.27/docs/canonical-service-best-practices.md.txt)