[[["易于理解","easyToUnderstand","thumb-up"],["解决了我的问题","solvedMyProblem","thumb-up"],["其他","otherUp","thumb-up"]],[["很难理解","hardToUnderstand","thumb-down"],["信息或示例代码不正确","incorrectInformationOrSampleCode","thumb-down"],["没有我需要的信息/示例","missingTheInformationSamplesINeed","thumb-down"],["翻译问题","translationIssue","thumb-down"],["其他","otherDown","thumb-down"]],["最后更新时间 (UTC):2025-08-19。"],[],[],null,["# Canonical Service Best Practices\n================================\n\n\n**Note:** Canonical Services are supported automatically in Cloud Service Mesh version 1.6.8 and higher.\n\n[Canonical Services](/service-mesh/v1.19/docs/canonical-service) allow you to navigate many\ndifferent configurations. For the best experience with Cloud Service Mesh Service\nDashboards, consider the following standard practices when setting up your\nservices:\n\n- Reserve a unique service \\[namespace, name\\] across the whole mesh.\n- Define one software application per Canonical Service.\n - Do not group Canonical Services across environments (for example, prod/stage/dev).\n - Use [Cloud Monitoring dashboards](/monitoring/charts/dashboards) for higher-level views of multiple services.\n- Plan for Canonical Services to be long-lived in production.\n\nReserve a unique service \\[namespace, name\\] across the whole mesh\n------------------------------------------------------------------\n\nIf a Canonical Service deployed in one cluster or region has the same Kubernetes\nnamespace and Canonical Service name as one deployed in another cluster or\nregion, Cloud Service Mesh assumes that it is the same logical service.\n\nThis behavior is consistent with the\n[fleet principle of \"sameness\"](https://cloud.google.com/anthos/multicluster-management/fleets#sameness),\nwhich says that a namespace should have the same meaning and represent the same\nentity across the entire fleet.\n| **Important:** Make sure that logically different services (for example, payment accounting API and payment transaction API) do not use the same \\[namespace, name\\] pair (e.g., \"payments/api\") because they inadvertently join into one Service Dashboard. Note that this conceptual joining occurs even across regional boundaries. Moreover, the function of the services may be impacted.\n\nOne software application per Canonical Service\n----------------------------------------------\n\nCanonical Services are meant to represent a single logical service or\nmicroservice. They are meant to span *homogenous* binaries/workloads that\nrepresent the same software application and business function.\n\nWhile you could define a Canonical Service to group several conceptually\ndifferent microservices together, the Service Dashboards would not provide their\nfull value.The Service Dashboards would display an aggregation of dissimilar\ncomponents which may individually be performing and configured very differently.\nIt would be difficult or even impossible to understand the health, performance,\nand configuration of the whole.\n\nThe following are not necessarily bad practices, but your Canonical Service\nmay be too big if:\n\n- There is network traffic between different workloads within a single Canonical Service.\n- A Canonical Service comprises multiple workloads that are deployed on different release schedules.\n- Different teams within your organization are responsible for operating different pieces of a single Canonical Service.\n\n### Do not group a Canonical Service across environments\n\nMany technology organizations employ multiple deployment environments to ensure\nsoftware quality and limit risk. These environments most often include dev, test,\nstaging, prod, or some subset.\n\nEven if you deploy the same conceptual service across each of your various\nenvironments, it is bad practice to make them a single Canonical Service. These\nservices are not the same and do not represent the same level of operational\nconcern or focus for your organization.\n\nFor instance, a failure on a critical production service may cause 3AM pages and\nfirefights. You do not want to alert anybody if the \"dev\" deployment fails in\nthe middle of the night. The same goes for understanding performance, capacity,\nand release safety.\n| **Important:** We recommend that you separate services in your various environments into **separate** Canonical Services. You can do this in one of three ways.\n\nFrom the easiest but least rigorous, to the highest-effort but most powerful,\nthere are three ways to separate services into different environments:\n\n1. Separate using multiple **service names** , for example, `payments-prod` and `payments-test`.\n2. Separate using multiple **namespaces** , for example `billing-team` and `billing-team-test`.\n3. Separate using multiple [fleets](/anthos/multicluster-management/fleets), one for each environment.\n\n### Prefer Cloud Monitoring custom dashboards for arbitrary aggregations\n\nRather than artificially bloating Canonical Services into larger scopes for\naggregate data, use [Cloud Monitoring dashboards](/monitoring/charts/dashboards)\nto create higher-level views of multiple logical services at once.\n\nCanonical Services are meant to be long-lived\n---------------------------------------------\n\nOutside of development, exploration, and testing use cases, Canonical Services\nshould represent global, high-level logical services. These services are\nslow-changing and tend to be long-lived. This longevity includes not changing\nservice names. While you can change their names, doing so impacts metrics, SLOs,\nand logs. However, you can freely adjust the `Display name` field without\ndisruption.\n\nA new Canonical Service often represents new or updated software while a\nCanonical Service going away often represents a service deprecation. Your\nability to see the historical performance of your service, plan, and project\ncapacity all depend on maintaining a single notion of that service in\nCloud Service Mesh for the duration of its life.\n\nNote that this contrasts to lower-level resources like VM instances, Kubernetes\nPods/Deployments, and even whole clusters, which often come and go as part of\nupdating and maintaining production systems.\n\nWhat's next\n-----------\n\n- [Learn more about Canonical Services](/service-mesh/v1.19/docs/canonical-service).\n- [Learn how to define a Canonical Service](/service-mesh/v1.19/docs/observability/defining-canonical-service)."]]