Add docs and small naming/format changes

Author: mveroone

docs/gitbook/usage/metrics.md

@@ -326,6 +326,22 @@ Reference the template in the canary analysis:
         interval: 1m
 ```
 
+### Datadog Rate Limits
+
+For bigger setups, you might run into rate limits on the Datadog API. To avoid this,
+you can use the Datadog Cluster Agent to retrieve metrics in batches instead. It will then
+expose these metrics as an external metrics server.
+
+See [Datadog Documentation](https://docs.datadoghq.com/containers/guide/cluster_agent_autoscaling_metrics).
+
+Once you have enabled Datadog's external metrics endpoint and `DatadogMetric` CRD (without
+necessarily using `registerAPIService`), you can use Flagger's
+[External Metrics Provider](#kubernetes-external-metrics) to query the metrics from there.
+
+The server address is usually `datadog-cluster-agent-metrics-server` and exposed on port 8443.
+ExternalMetrics will be named as `datadogmetric@<namespace>:<metricname>`, for example
+`datadogmetric@istio-system:istio-mesh-request-count`.
+
 ## Amazon CloudWatch
 
 You can create custom metric checks using the CloudWatch metrics provider.
@@ -781,3 +797,37 @@ Reference the template in the canary analysis:
           max: 99
         interval: 1m
 ```
+
+## Kubernetes External Metrics
+
+You can query an external metrics provider that implements the
+[Kubernetes External Metrics API](https://kubernetes.io/docs/reference/external-api/external-metrics.v1beta1/).
+
+By default, Flagger will use its bound Service Account for authentication. *Optionally* you can provide a Bearer token through a Secret (that must contain a field named `token`) :
+
+```yaml
+apiVersion: v1
+kind: Secret
+metadata:
+  name: external-metric-server-token
+  namespace: default
+data:
+  token: your-access-token
+```
+
+External Metrics template example:
+
+```yaml
+apiVersion: flagger.app/v1beta1
+kind: MetricTemplate
+metadata:
+  name: my-external-metric
+  namespace: default
+spec:
+  provider:
+    type: externalmetrics
+    address: https://external-metrics-server.default.svc.cluster.local:8443
+    secretRef: # Optional
+      name: external-metric-server-token
+  query: webapp-frontend/job-success-rate?labelSelector=env%3Dproduction
+```

pkg/metrics/providers/externalmetrics.go

@@ -59,7 +59,7 @@ func NewExternalMetricsProvider(metricInterval string,
 		return nil, fmt.Errorf("the Url of the external metric service must be provided")
 	}
 
-	externalMetrics := ExternalMetricsProvider{
+	emp := ExternalMetricsProvider{
 		metricServiceEndpoint: fmt.Sprintf("%s%s", provider.Address, metricServiceEndpointPath),
 		timeout:               5 * time.Second,
 		client:                http.DefaultClient,
@@ -68,33 +68,33 @@ func NewExternalMetricsProvider(metricInterval string,
 	if provider.InsecureSkipVerify {
 		t := http.DefaultTransport.(*http.Transport).Clone()
 		t.TLSClientConfig = &tls.Config{InsecureSkipVerify: true}
-		externalMetrics.client = &http.Client{Transport: t}
+		emp.client = &http.Client{Transport: t}
 	}
 
 	if b, ok := credentials[applicationBearerToken]; ok {
-		externalMetrics.bearerToken = string(b)
+		emp.bearerToken = string(b)
 	} else {
-		// Read service account token from volume mount
+		// In the absence of a provided token, 
+		// read service account token from volume mount
 		token, err := os.ReadFile("/var/run/secrets/kubernetes.io/serviceaccount/token")
 		if err != nil {
 			return nil, fmt.Errorf("error reading service account token: %w", err)
 		}
 		if len(token) == 0 {
 			return nil, fmt.Errorf("pod's service account token is empty")
 		}
-		externalMetrics.bearerToken = string(token)
+		emp.bearerToken = string(token)
 	}
 
-	return &externalMetrics, nil
+	return &emp, nil
 }
 
 // RunQuery retrieves the ExternalMetricValue from the ExternalMetricsProvider.metricServiceUrl
 // and returns the first result as a float64
 func (p *ExternalMetricsProvider) RunQuery(query string) (float64, error) {
+	u := fmt.Sprintf("%s%s%s", p.metricServiceEndpoint, namespacesPath, query)
 
-	metricsQueryUrl := fmt.Sprintf("%s%s%s", p.metricServiceEndpoint, namespacesPath, query)
-
-	req, err := http.NewRequest("GET", metricsQueryUrl, nil)
+	req, err := http.NewRequest("GET", u, nil)
 	if err != nil {
 		return 0, fmt.Errorf("error http.NewRequest: %w", err)
 	}
@@ -134,19 +134,19 @@ func (p *ExternalMetricsProvider) RunQuery(query string) (float64, error) {
 }
 
 // IsOnline will only check the TCP endpoint reachability,
-// given that external metric servers don't have a common health check endpoint defined
+// given that external metric servers don't have a standard health check endpoint defined
 func (p *ExternalMetricsProvider) IsOnline() (bool, error) {
 	var d net.Dialer
 
 	ctx, cancel := context.WithTimeout(context.Background(), p.timeout)
 	defer cancel()
 
-	metricServiceUrl, err := url.Parse(p.metricServiceEndpoint)
+	u, err := url.Parse(p.metricServiceEndpoint)
 	if err != nil {
 		return false, fmt.Errorf("error parsing metric service url: %w", err)
 	}
 
-	conn, err := d.DialContext(ctx, "tcp", metricServiceUrl.Host)
+	conn, err := d.DialContext(ctx, "tcp", u.Host)
 	defer conn.Close()
 	if err != nil {
 		return false, fmt.Errorf("connection failed: %w", err)

pkg/metrics/providers/externalmetrics_test.go

@@ -53,7 +53,7 @@ func TestNewExternalMetricsProvider(t *testing.T) {
 		applicationBearerToken: []byte(testBearerToken),
 	}
 
-	providermetric:= flaggerv1.MetricTemplateProvider{
+	providermetric := flaggerv1.MetricTemplateProvider{
 		Address:            testMetricServerAddress,
 		InsecureSkipVerify: false,
 	}