From 18a7025383cbb5ef41ee6c709dcb8f5be2616f0e Mon Sep 17 00:00:00 2001
From: Han Kang <hankang@google.com>
Date: Tue, 25 Jul 2023 08:57:54 -0700
Subject: [PATCH] update documentation with descriptions

---
 test/instrumentation/documentation/documentation.md | 8 +++++++-
 test/instrumentation/documentation/main.go          | 6 ++++++
 2 files changed, 13 insertions(+), 1 deletion(-)

diff --git a/test/instrumentation/documentation/documentation.md b/test/instrumentation/documentation/documentation.md
index ee628c0336a..d07d8c9516b 100644
--- a/test/instrumentation/documentation/documentation.md
+++ b/test/instrumentation/documentation/documentation.md
@@ -8,13 +8,15 @@ description: >-
 
 ## Metrics (v1.28)
 
-<!-- (auto-generated 2023 Jul 20) -->
+<!-- (auto-generated 2023 Jul 25) -->
 <!-- (auto-generated v1.28) -->
 This page details the metrics that different Kubernetes components export. You can query the metrics endpoint for these 
 components using an HTTP scrape, and fetch the current metrics data in Prometheus format.
 
 ### List of Stable Kubernetes Metrics
 
+Stable metrics observe strict API contracts and no labels can be added or removed from stable metrics during their lifetime.
+
 <table class="table metrics" caption="This is the list of STABLE metrics emitted from core Kubernetes components">
 <thead>
 	<tr>
@@ -223,6 +225,8 @@ components using an HTTP scrape, and fetch the current metrics data in Prometheu
 
 ### List of Beta Kubernetes Metrics
 
+Beta metrics observe a looser API contract than its stable counterparts. No labels can be removed from beta metrics during their lifetime, however, labels can be added while the metric is in the beta stage. This offers the assurance that beta metrics will honor existing dashboards and alerts, while allowing for amendments in the future. 
+
 <table class="table metrics" caption="This is the list of BETA metrics emitted from core Kubernetes components">
 <thead>
 	<tr>
@@ -333,6 +337,8 @@ components using an HTTP scrape, and fetch the current metrics data in Prometheu
 
 ### List of Alpha Kubernetes Metrics
 
+Alpha metrics do not have any API guarantees. These metrics must be used at your own risk, subsequent versions of Kubernetes may remove these metrics altogether, or mutate the API in such a way that breaks existing dashboards and alerts. 
+
 <table class="table metrics" caption="This is the list of ALPHA metrics emitted from core Kubernetes components">
 <thead>
 	<tr>
diff --git a/test/instrumentation/documentation/main.go b/test/instrumentation/documentation/main.go
index 483c7dd4dad..c8a2b37c6d9 100755
--- a/test/instrumentation/documentation/main.go
+++ b/test/instrumentation/documentation/main.go
@@ -58,6 +58,8 @@ components using an HTTP scrape, and fetch the current metrics data in Prometheu
 
 ### List of Stable Kubernetes Metrics
 
+Stable metrics observe strict API contracts and no labels can be added or removed from stable metrics during their lifetime.
+
 <table class="table metrics" caption="This is the list of STABLE metrics emitted from core Kubernetes components">
 <thead>
 	<tr>
@@ -84,6 +86,8 @@ components using an HTTP scrape, and fetch the current metrics data in Prometheu
 
 ### List of Beta Kubernetes Metrics
 
+Beta metrics observe a looser API contract than its stable counterparts. No labels can be removed from beta metrics during their lifetime, however, labels can be added while the metric is in the beta stage. This offers the assurance that beta metrics will honor existing dashboards and alerts, while allowing for amendments in the future. 
+
 <table class="table metrics" caption="This is the list of BETA metrics emitted from core Kubernetes components">
 <thead>
 	<tr>
@@ -110,6 +114,8 @@ components using an HTTP scrape, and fetch the current metrics data in Prometheu
 
 ### List of Alpha Kubernetes Metrics
 
+Alpha metrics do not have any API guarantees. These metrics must be used at your own risk, subsequent versions of Kubernetes may remove these metrics altogether, or mutate the API in such a way that breaks existing dashboards and alerts. 
+
 <table class="table metrics" caption="This is the list of ALPHA metrics emitted from core Kubernetes components">
 <thead>
 	<tr>