diff --git a/docs/gitbook/dev/upgrade-guide.md b/docs/gitbook/dev/upgrade-guide.md
index 2700bd46..675e6472 100644
--- a/docs/gitbook/dev/upgrade-guide.md
+++ b/docs/gitbook/dev/upgrade-guide.md
@@ -11,6 +11,7 @@ Canary CRD changes in `canaries.flagger.app/v1beta1`:
 * the `spec.analysis.alerts` array can reference `alertproviders.flagger.app/v1beta1` resources
 * the `spec.analysis.metrics[].templateRef` can reference a `metrictemplate.flagger.app/v1beta1` resource
 * the `metric.threshold` field has been deprecated and replaced with `metric.thresholdRange`
+* the `metric.query` field has been deprecated and replaced with `metric.templateRef`
 * the `spec.targetRef` can reference `DaemonSet` kind
 
 Upgrade procedure:
diff --git a/pkg/apis/flagger/v1beta1/canary.go b/pkg/apis/flagger/v1beta1/canary.go
index f13bd908..05568782 100644
--- a/pkg/apis/flagger/v1beta1/canary.go
+++ b/pkg/apis/flagger/v1beta1/canary.go
@@ -214,14 +214,14 @@ type CanaryMetric struct {
 	// Interval represents the windows size
 	Interval string `json:"interval,omitempty"`
 
-	// Max value accepted for this metric
+	// Deprecated: Max value accepted for this metric (replaced by ThresholdRange)
 	Threshold float64 `json:"threshold"`
 
 	// Range value accepted for this metric
 	// +optional
 	ThresholdRange *CanaryThresholdRange `json:"thresholdRange,omitempty"`
 
-	// Prometheus query for this metric (deprecated in favor of TemplateRef)
+	// Deprecated: Prometheus query for this metric (replaced by TemplateRef)
 	// +optional
 	Query string `json:"query,omitempty"`