Merge pull request #54998 from tengqm/autoscale-api-doc

Automatic merge from submit-queue (batch tested with PRs 56410, 56707, 56661, 54998, 56722). If you want to cherry-pick this change to another branch, please follow the instructions <a href="https://github.com/kubernetes/community/blob/master/contributors/devel/cherry-picks.md">here</a>.

Fix autoscaling API documentation

**What this PR does / why we need it**:
This PR fixes the API documentation generated for HorizontalPodAutoscaler resource.

**Which issue(s) this PR fixes**:
The current API doc for `MetricSpec` and `MetricStatus` is confusing. Users get no idea what can be used as the value for the `type` field, because the doc says this:

```
type is the type of metric source. It should match one of the fields below.
```

While acceptable in the source code, it makes no senses when reading the API doc, especially when the "`type`" field is listed as the last row in a table (see: https://kubernetes.io/docs/api-reference/v1.8/#metricspec-v2beta1-autoscaling )

**Special notes for your reviewer**:
This PR makes no changes to the code behavior.

**Release note**:
```release-note
NONE
```

api/openapi-spec/swagger.json

@@ -73604,7 +73604,7 @@
       "$ref": "#/definitions/io.k8s.api.autoscaling.v2beta1.ResourceMetricSource"
      },
      "type": {
-      "description": "type is the type of metric source.  It should match one of the fields below.",
+      "description": "type is the type of metric source.  It should be one of \"Object\", \"Pods\" or \"Resource\", each mapping to a matching field in the object.",
       "type": "string"
      }
     }
@@ -73628,7 +73628,7 @@
       "$ref": "#/definitions/io.k8s.api.autoscaling.v2beta1.ResourceMetricStatus"
      },
      "type": {
-      "description": "type is the type of metric source.  It will match one of the fields below.",
+      "description": "type is the type of metric source.  It will be one of \"Object\", \"Pods\" or \"Resource\", each corresponds to a matching field in the object.",
       "type": "string"
      }
     }

api/swagger-spec/autoscaling_v2beta1.json

@@ -1547,7 +1547,7 @@
     "properties": {
      "type": {
       "type": "string",
-      "description": "type is the type of metric source.  It should match one of the fields below."
+      "description": "type is the type of metric source.  It should be one of \"Object\", \"Pods\" or \"Resource\", each mapping to a matching field in the object."
      },
      "object": {
       "$ref": "v2beta1.ObjectMetricSource",
@@ -1680,7 +1680,7 @@
     "properties": {
      "type": {
       "type": "string",
-      "description": "type is the type of metric source.  It will match one of the fields below."
+      "description": "type is the type of metric source.  It will be one of \"Object\", \"Pods\" or \"Resource\", each corresponds to a matching field in the object."
      },
      "object": {
       "$ref": "v2beta1.ObjectMetricStatus",

docs/api-reference/autoscaling/v2beta1/definitions.html

@@ -871,7 +871,7 @@ span.icon > [class^="icon-"], span.icon > [class*=" icon-"] { cursor: default; }
 <tbody>
 <tr>
 <td class="tableblock halign-left valign-top"><p class="tableblock">type</p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">type is the type of metric source.  It will match one of the fields below.</p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock">type is the type of metric source.  It will be one of "Object", "Pods" or "Resource", each corresponds to a matching field in the object.</p></td>
 <td class="tableblock halign-left valign-top"><p class="tableblock">true</p></td>
 <td class="tableblock halign-left valign-top"><p class="tableblock">string</p></td>
 <td class="tableblock halign-left valign-top"></td>
@@ -1828,7 +1828,7 @@ Examples:<br>
 <tbody>
 <tr>
 <td class="tableblock halign-left valign-top"><p class="tableblock">type</p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">type is the type of metric source.  It should match one of the fields below.</p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock">type is the type of metric source.  It should be one of "Object", "Pods" or "Resource", each mapping to a matching field in the object.</p></td>
 <td class="tableblock halign-left valign-top"><p class="tableblock">true</p></td>
 <td class="tableblock halign-left valign-top"><p class="tableblock">string</p></td>
 <td class="tableblock halign-left valign-top"></td>

pkg/apis/autoscaling/types.go

@@ -116,7 +116,8 @@ var (
 // MetricSpec specifies how to scale based on a single metric
 // (only `type` and one other matching field should be set at once).
 type MetricSpec struct {
-	// Type is the type of metric source.  It should match one of the fields below.
+	// Type is the type of metric source.  It should be one of "Object",
+	// "Pods" or "Resource", each mapping to a matching field in the object.
 	Type MetricSourceType
 
 	// Object refers to a metric describing a single kubernetes object
@@ -261,7 +262,8 @@ type HorizontalPodAutoscalerCondition struct {
 
 // MetricStatus describes the last-read state of a single metric.
 type MetricStatus struct {
-	// Type is the type of metric source.  It will match one of the fields below.
+	// Type is the type of metric source.  It will be one of "Object",
+	// "Pods" or "Resource", each corresponds to a matching field in the object.
 	Type MetricSourceType
 
 	// Object refers to a metric describing a single kubernetes object

staging/src/k8s.io/api/autoscaling/v1/generated.proto

@@ -138,7 +138,8 @@ message HorizontalPodAutoscalerStatus {
 // MetricSpec specifies how to scale based on a single metric
 // (only `type` and one other matching field should be set at once).
 message MetricSpec {
-  // type is the type of metric source.  It should match one of the fields below.
+  // type is the type of metric source.  It should be one of "Object",
+  // "Pods" or "Resource", each mapping to a matching field in the object.
   optional string type = 1;
 
   // object refers to a metric describing a single kubernetes object
@@ -163,7 +164,8 @@ message MetricSpec {
 
 // MetricStatus describes the last-read state of a single metric.
 message MetricStatus {
-  // type is the type of metric source.  It will match one of the fields below.
+  // type is the type of metric source.  It will be one of "Object",
+  // "Pods" or "Resource", each corresponds to a matching field in the object.
   optional string type = 1;
 
   // object refers to a metric describing a single kubernetes object

staging/src/k8s.io/api/autoscaling/v1/types.go

@@ -166,7 +166,8 @@ var (
 // MetricSpec specifies how to scale based on a single metric
 // (only `type` and one other matching field should be set at once).
 type MetricSpec struct {
-	// type is the type of metric source.  It should match one of the fields below.
+	// type is the type of metric source.  It should be one of "Object",
+	// "Pods" or "Resource", each mapping to a matching field in the object.
 	Type MetricSourceType `json:"type" protobuf:"bytes,1,name=type"`
 
 	// object refers to a metric describing a single kubernetes object
@@ -235,7 +236,8 @@ type ResourceMetricSource struct {
 
 // MetricStatus describes the last-read state of a single metric.
 type MetricStatus struct {
-	// type is the type of metric source.  It will match one of the fields below.
+	// type is the type of metric source.  It will be one of "Object",
+	// "Pods" or "Resource", each corresponds to a matching field in the object.
 	Type MetricSourceType `json:"type" protobuf:"bytes,1,name=type"`
 
 	// object refers to a metric describing a single kubernetes object

staging/src/k8s.io/api/autoscaling/v1/types_swagger_doc_generated.go

@@ -99,7 +99,7 @@ func (HorizontalPodAutoscalerStatus) SwaggerDoc() map[string]string {
 
 var map_MetricSpec = map[string]string{
 	"":         "MetricSpec specifies how to scale based on a single metric (only `type` and one other matching field should be set at once).",
-	"type":     "type is the type of metric source.  It should match one of the fields below.",
+	"type":     "type is the type of metric source.  It should be one of \"Object\", \"Pods\" or \"Resource\", each mapping to a matching field in the object.",
 	"object":   "object refers to a metric describing a single kubernetes object (for example, hits-per-second on an Ingress object).",
 	"pods":     "pods refers to a metric describing each pod in the current scale target (for example, transactions-processed-per-second).  The values will be averaged together before being compared to the target value.",
 	"resource": "resource refers to a resource metric (such as those specified in requests and limits) known to Kubernetes describing each pod in the current scale target (e.g. CPU or memory). Such metrics are built in to Kubernetes, and have special scaling options on top of those available to normal per-pod metrics using the \"pods\" source.",
@@ -111,7 +111,7 @@ func (MetricSpec) SwaggerDoc() map[string]string {
 
 var map_MetricStatus = map[string]string{
 	"":         "MetricStatus describes the last-read state of a single metric.",
-	"type":     "type is the type of metric source.  It will match one of the fields below.",
+	"type":     "type is the type of metric source.  It will be one of \"Object\", \"Pods\" or \"Resource\", each corresponds to a matching field in the object.",
 	"object":   "object refers to a metric describing a single kubernetes object (for example, hits-per-second on an Ingress object).",
 	"pods":     "pods refers to a metric describing each pod in the current scale target (for example, transactions-processed-per-second).  The values will be averaged together before being compared to the target value.",
 	"resource": "resource refers to a resource metric (such as those specified in requests and limits) known to Kubernetes describing each pod in the current scale target (e.g. CPU or memory). Such metrics are built in to Kubernetes, and have special scaling options on top of those available to normal per-pod metrics using the \"pods\" source.",

staging/src/k8s.io/api/autoscaling/v2beta1/generated.proto

@@ -153,7 +153,8 @@ message HorizontalPodAutoscalerStatus {
 // MetricSpec specifies how to scale based on a single metric
 // (only `type` and one other matching field should be set at once).
 message MetricSpec {
-  // type is the type of metric source.  It should match one of the fields below.
+  // type is the type of metric source.  It should be one of "Object",
+  // "Pods" or "Resource", each mapping to a matching field in the object.
   optional string type = 1;
 
   // object refers to a metric describing a single kubernetes object
@@ -178,7 +179,8 @@ message MetricSpec {
 
 // MetricStatus describes the last-read state of a single metric.
 message MetricStatus {
-  // type is the type of metric source.  It will match one of the fields below.
+  // type is the type of metric source.  It will be one of "Object",
+  // "Pods" or "Resource", each corresponds to a matching field in the object.
   optional string type = 1;
 
   // object refers to a metric describing a single kubernetes object

staging/src/k8s.io/api/autoscaling/v2beta1/types.go

@@ -78,7 +78,8 @@ var (
 // MetricSpec specifies how to scale based on a single metric
 // (only `type` and one other matching field should be set at once).
 type MetricSpec struct {
-	// type is the type of metric source.  It should match one of the fields below.
+	// type is the type of metric source.  It should be one of "Object",
+	// "Pods" or "Resource", each mapping to a matching field in the object.
 	Type MetricSourceType `json:"type" protobuf:"bytes,1,name=type"`
 
 	// object refers to a metric describing a single kubernetes object
@@ -210,7 +211,8 @@ type HorizontalPodAutoscalerCondition struct {
 
 // MetricStatus describes the last-read state of a single metric.
 type MetricStatus struct {
-	// type is the type of metric source.  It will match one of the fields below.
+	// type is the type of metric source.  It will be one of "Object",
+	// "Pods" or "Resource", each corresponds to a matching field in the object.
 	Type MetricSourceType `json:"type" protobuf:"bytes,1,name=type"`
 
 	// object refers to a metric describing a single kubernetes object

staging/src/k8s.io/api/autoscaling/v2beta1/types_swagger_doc_generated.go

@@ -100,7 +100,7 @@ func (HorizontalPodAutoscalerStatus) SwaggerDoc() map[string]string {
 
 var map_MetricSpec = map[string]string{
 	"":         "MetricSpec specifies how to scale based on a single metric (only `type` and one other matching field should be set at once).",
-	"type":     "type is the type of metric source.  It should match one of the fields below.",
+	"type":     "type is the type of metric source.  It should be one of \"Object\", \"Pods\" or \"Resource\", each mapping to a matching field in the object.",
 	"object":   "object refers to a metric describing a single kubernetes object (for example, hits-per-second on an Ingress object).",
 	"pods":     "pods refers to a metric describing each pod in the current scale target (for example, transactions-processed-per-second).  The values will be averaged together before being compared to the target value.",
 	"resource": "resource refers to a resource metric (such as those specified in requests and limits) known to Kubernetes describing each pod in the current scale target (e.g. CPU or memory). Such metrics are built in to Kubernetes, and have special scaling options on top of those available to normal per-pod metrics using the \"pods\" source.",
@@ -112,7 +112,7 @@ func (MetricSpec) SwaggerDoc() map[string]string {
 
 var map_MetricStatus = map[string]string{
 	"":         "MetricStatus describes the last-read state of a single metric.",
-	"type":     "type is the type of metric source.  It will match one of the fields below.",
+	"type":     "type is the type of metric source.  It will be one of \"Object\", \"Pods\" or \"Resource\", each corresponds to a matching field in the object.",
 	"object":   "object refers to a metric describing a single kubernetes object (for example, hits-per-second on an Ingress object).",
 	"pods":     "pods refers to a metric describing each pod in the current scale target (for example, transactions-processed-per-second).  The values will be averaged together before being compared to the target value.",
 	"resource": "resource refers to a resource metric (such as those specified in requests and limits) known to Kubernetes describing each pod in the current scale target (e.g. CPU or memory). Such metrics are built in to Kubernetes, and have special scaling options on top of those available to normal per-pod metrics using the \"pods\" source.",