# Canonical Service


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

This page explains what a Canonical Service is in Cloud Service Mesh.

## What is a Canonical Service?

Cloud Service Mesh 1.6.8 introduces support for Canonical Services, a conceptual and
architectural model for representing your production workloads as a singular
service that is easier to observe and manage. These workloads can span multiple
clusters, disparate backend platforms, and different schemas and configurations.

**For Kubernetes users:** Canonical Service is roughly analogous to the
Kubernetes "app" concept and the Application CRD.

**For Serverless users:** Canonical Service is very similar to
[App Engine service](https://docs.cloud.google.com/appengine/docs/flexible/java/an-overview-of-app-engine#services)
and [Cloud Run service](https://docs.cloud.google.com/run/docs/resource-model.md.txt#services) concepts.
The one difference is that Google Serverless services are inherently regional
whereas Canonical Services are a global / multi-region abstraction.

For example, the following scenarios all describe ways that you might refer to a
Canonical Service:

- A service has an outage.
- A service runs both on-premise and on a public cloud.
- Deploying a new revision of a service.
- The service Foo is sending too much traffic and may exceed our capacity.

Canonical Services exist within a single Mesh, which in Cloud Service Mesh means that
they are also unique within a
[fleet](https://docs.cloud.google.com/anthos/multicluster-management/fleets) and a Google Cloud
Project (all of which are one-to-one with Mesh).

A given workload is only allowed to be part of one Canonical Service.

You can determine the full scope of a Canonical Service from the group of
workloads that define it including:

- **Hostnames and IP addresses**
- **Network(s)**
- **Network and security policies**
- **Routing and load balancing**
- **VM and container images**
- **Physical or virtual infrastructure**
- **Geographic region(s)**
- **CI/CD system**
- **Source code**
- **Telemetry**
- **Service level objectives and alerts**

You can view dashboards that display these operational details for each service
on the [Services page](https://console.cloud.google.com/kubernetes/services).

## Canonical Service requirements and limitations

Canonical Services are only available on Cloud Service Mesh version 1.6.8 and
higher.

Each Canonical Service exists inside of a single Kubernetes/Istio namespace and
cannot cross namespace boundaries.

You must give a Canonical Service a unique name within its parent namespace. For
more information, see
[define a Canonical Service](https://docs.cloud.google.com/service-mesh/v1.28/docs/define-canonical-service.md.txt).

Canonical Services can exist across multiple clusters and regions. While it is
possible to break down resources and telemetry by cluster and region, those are
not factors in determining the scope or uniqueness of a service.

Therefore, the unique identity of a Canonical Service is determined by:

    mesh id + namespace + canonical name.

## Revisions

Revisions refer to incremental changes to a service which you can use to
distinguish and identify different "versions" or "releases" of your services.

Differentiate between revisions of a Canonical Service by labeling an individual
workload with its "canonical revision." This label is an arbitrary string that
you can define. While the label may be set automatically in some cases, you or
the CI/CD system that deploys the service must apply the label. For guidance on
setting this label, see [Define a Canonical Service](https://docs.cloud.google.com/service-mesh/v1.28/docs/define-canonical-service.md.txt).

Note that multiple revisions can be in production at the same time. Running
multiple revisions at once is most often used to accomplish:

- The progressive roll-out of a new binary, a new configuration, or both across all of the instances of one's service. In this case, both the old and new revisions are live during the transition.
- An "A/B test" or "live experiment," in which two different versions of the service are exposed to subsets of downstream callers to test the effect of a change.

## What's next

- [Define a Canonical Service](https://docs.cloud.google.com/service-mesh/v1.28/docs/define-canonical-service.md.txt).
- [Canonical Services best practices](https://docs.cloud.google.com/service-mesh/v1.28/docs/canonical-service-best-practices.md.txt).
- [Troubleshooting Canonical Services](https://docs.cloud.google.com/service-mesh/v1.28/docs/troubleshooting/troubleshoot-canonical-service.md.txt).