From 54fc95d129140f54b3db79888731336bd541b500 Mon Sep 17 00:00:00 2001
From: Ashleigh Brennan <40172997+abrennan89@users.noreply.github.com>
Date: Tue, 17 Sep 2019 19:02:45 +0100
Subject: [PATCH] Added new section for custom-metrics API details (#1566)

* Added new section for custom-metrics API details

* Minor update

* Updated based on Sam's comments
---
 docs/serving/custom-metrics-API.md | 29 +++++++++++++++++++++++++++++
 1 file changed, 29 insertions(+)
 create mode 100644 docs/serving/custom-metrics-API.md

diff --git a/docs/serving/custom-metrics-API.md b/docs/serving/custom-metrics-API.md
new file mode 100644
index 000000000..22556753b
--- /dev/null
+++ b/docs/serving/custom-metrics-API.md
@@ -0,0 +1,29 @@
+---
+title: "Custom-metrics API"
+weight: 10
+type: "docs"
+---
+
+The `custom-metrics` API is installed by default when you install Knative Serving, and allows users to configure concurrency based scaling when using the Horizontal Pod Autoscaler (HPA).
+
+>**IMPORTANT:** If you already have an existing `custom-metrics` API implementation in your cluster, you must delete this so that Knative Serving can use the default Knative Serving installation of the `custom-metrics` API. Enabling both implementations can cause issues.
+>
+>If you intend to use an existing `custom-metrics` API implementation in your cluster, you will not be able to use custom metrics or HPA concurrency metrics on that cluster. These features require the Knative Serving `custom-metrics` API implementation.
+
+# Checking for existing custom-metrics API implementations
+
+To check if your cluster has an existing `custom-metrics` API implementation, use the following command.
+
+```
+kubectl get apiservice | grep v1beta1.custom.metrics.k8s.io
+```
+
+# Deleting existing custom-metrics API installations
+
+If you have an existing `custom-metrics` API implementation in your cluster, you must delete this using the following command.
+
+```
+kubectl delete apiservice v1beta1.custom.metrics.k8s.io
+```
+
+**IMPORTANT:** This step is not required for inexperienced users, as it is possible to break consumers of a custom-metrics API by deleting this. Only delete API implementations if you are sure that it is safe to do so.