Zack Williams | e940c7a | 2019-08-21 14:25:39 -0700 | [diff] [blame] | 1 | /* |
| 2 | Copyright 2018 The Kubernetes Authors. |
| 3 | |
| 4 | Licensed under the Apache License, Version 2.0 (the "License"); |
| 5 | you may not use this file except in compliance with the License. |
| 6 | You may obtain a copy of the License at |
| 7 | |
| 8 | http://www.apache.org/licenses/LICENSE-2.0 |
| 9 | |
| 10 | Unless required by applicable law or agreed to in writing, software |
| 11 | distributed under the License is distributed on an "AS IS" BASIS, |
| 12 | WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| 13 | See the License for the specific language governing permissions and |
| 14 | limitations under the License. |
| 15 | */ |
| 16 | |
| 17 | // +k8s:openapi-gen=true |
| 18 | |
| 19 | package v2beta2 |
| 20 | |
| 21 | import ( |
| 22 | "k8s.io/api/core/v1" |
| 23 | "k8s.io/apimachinery/pkg/api/resource" |
| 24 | metav1 "k8s.io/apimachinery/pkg/apis/meta/v1" |
| 25 | ) |
| 26 | |
| 27 | // +genclient |
| 28 | // +k8s:deepcopy-gen:interfaces=k8s.io/apimachinery/pkg/runtime.Object |
| 29 | |
| 30 | // HorizontalPodAutoscaler is the configuration for a horizontal pod |
| 31 | // autoscaler, which automatically manages the replica count of any resource |
| 32 | // implementing the scale subresource based on the metrics specified. |
| 33 | type HorizontalPodAutoscaler struct { |
| 34 | metav1.TypeMeta `json:",inline"` |
| 35 | // metadata is the standard object metadata. |
| 36 | // More info: https://git.k8s.io/community/contributors/devel/api-conventions.md#metadata |
| 37 | // +optional |
| 38 | metav1.ObjectMeta `json:"metadata,omitempty" protobuf:"bytes,1,opt,name=metadata"` |
| 39 | |
| 40 | // spec is the specification for the behaviour of the autoscaler. |
| 41 | // More info: https://git.k8s.io/community/contributors/devel/api-conventions.md#spec-and-status. |
| 42 | // +optional |
| 43 | Spec HorizontalPodAutoscalerSpec `json:"spec,omitempty" protobuf:"bytes,2,opt,name=spec"` |
| 44 | |
| 45 | // status is the current information about the autoscaler. |
| 46 | // +optional |
| 47 | Status HorizontalPodAutoscalerStatus `json:"status,omitempty" protobuf:"bytes,3,opt,name=status"` |
| 48 | } |
| 49 | |
| 50 | // HorizontalPodAutoscalerSpec describes the desired functionality of the HorizontalPodAutoscaler. |
| 51 | type HorizontalPodAutoscalerSpec struct { |
| 52 | // scaleTargetRef points to the target resource to scale, and is used to the pods for which metrics |
| 53 | // should be collected, as well as to actually change the replica count. |
| 54 | ScaleTargetRef CrossVersionObjectReference `json:"scaleTargetRef" protobuf:"bytes,1,opt,name=scaleTargetRef"` |
| 55 | // minReplicas is the lower limit for the number of replicas to which the autoscaler can scale down. |
| 56 | // It defaults to 1 pod. |
| 57 | // +optional |
| 58 | MinReplicas *int32 `json:"minReplicas,omitempty" protobuf:"varint,2,opt,name=minReplicas"` |
| 59 | // maxReplicas is the upper limit for the number of replicas to which the autoscaler can scale up. |
| 60 | // It cannot be less that minReplicas. |
| 61 | MaxReplicas int32 `json:"maxReplicas" protobuf:"varint,3,opt,name=maxReplicas"` |
| 62 | // metrics contains the specifications for which to use to calculate the |
| 63 | // desired replica count (the maximum replica count across all metrics will |
| 64 | // be used). The desired replica count is calculated multiplying the |
| 65 | // ratio between the target value and the current value by the current |
| 66 | // number of pods. Ergo, metrics used must decrease as the pod count is |
| 67 | // increased, and vice-versa. See the individual metric source types for |
| 68 | // more information about how each type of metric must respond. |
| 69 | // If not set, the default metric will be set to 80% average CPU utilization. |
| 70 | // +optional |
| 71 | Metrics []MetricSpec `json:"metrics,omitempty" protobuf:"bytes,4,rep,name=metrics"` |
| 72 | } |
| 73 | |
| 74 | // CrossVersionObjectReference contains enough information to let you identify the referred resource. |
| 75 | type CrossVersionObjectReference struct { |
| 76 | // Kind of the referent; More info: https://git.k8s.io/community/contributors/devel/api-conventions.md#types-kinds" |
| 77 | Kind string `json:"kind" protobuf:"bytes,1,opt,name=kind"` |
| 78 | // Name of the referent; More info: http://kubernetes.io/docs/user-guide/identifiers#names |
| 79 | Name string `json:"name" protobuf:"bytes,2,opt,name=name"` |
| 80 | // API version of the referent |
| 81 | // +optional |
| 82 | APIVersion string `json:"apiVersion,omitempty" protobuf:"bytes,3,opt,name=apiVersion"` |
| 83 | } |
| 84 | |
| 85 | // MetricSpec specifies how to scale based on a single metric |
| 86 | // (only `type` and one other matching field should be set at once). |
| 87 | type MetricSpec struct { |
| 88 | // type is the type of metric source. It should be one of "Object", |
| 89 | // "Pods" or "Resource", each mapping to a matching field in the object. |
| 90 | Type MetricSourceType `json:"type" protobuf:"bytes,1,name=type"` |
| 91 | |
| 92 | // object refers to a metric describing a single kubernetes object |
| 93 | // (for example, hits-per-second on an Ingress object). |
| 94 | // +optional |
| 95 | Object *ObjectMetricSource `json:"object,omitempty" protobuf:"bytes,2,opt,name=object"` |
| 96 | // pods refers to a metric describing each pod in the current scale target |
| 97 | // (for example, transactions-processed-per-second). The values will be |
| 98 | // averaged together before being compared to the target value. |
| 99 | // +optional |
| 100 | Pods *PodsMetricSource `json:"pods,omitempty" protobuf:"bytes,3,opt,name=pods"` |
| 101 | // resource refers to a resource metric (such as those specified in |
| 102 | // requests and limits) known to Kubernetes describing each pod in the |
| 103 | // current scale target (e.g. CPU or memory). Such metrics are built in to |
| 104 | // Kubernetes, and have special scaling options on top of those available |
| 105 | // to normal per-pod metrics using the "pods" source. |
| 106 | // +optional |
| 107 | Resource *ResourceMetricSource `json:"resource,omitempty" protobuf:"bytes,4,opt,name=resource"` |
| 108 | // external refers to a global metric that is not associated |
| 109 | // with any Kubernetes object. It allows autoscaling based on information |
| 110 | // coming from components running outside of cluster |
| 111 | // (for example length of queue in cloud messaging service, or |
| 112 | // QPS from loadbalancer running outside of cluster). |
| 113 | // +optional |
| 114 | External *ExternalMetricSource `json:"external,omitempty" protobuf:"bytes,5,opt,name=external"` |
| 115 | } |
| 116 | |
| 117 | // MetricSourceType indicates the type of metric. |
| 118 | type MetricSourceType string |
| 119 | |
| 120 | var ( |
| 121 | // ObjectMetricSourceType is a metric describing a kubernetes object |
| 122 | // (for example, hits-per-second on an Ingress object). |
| 123 | ObjectMetricSourceType MetricSourceType = "Object" |
| 124 | // PodsMetricSourceType is a metric describing each pod in the current scale |
| 125 | // target (for example, transactions-processed-per-second). The values |
| 126 | // will be averaged together before being compared to the target value. |
| 127 | PodsMetricSourceType MetricSourceType = "Pods" |
| 128 | // ResourceMetricSourceType is a resource metric known to Kubernetes, as |
| 129 | // specified in requests and limits, describing each pod in the current |
| 130 | // scale target (e.g. CPU or memory). Such metrics are built in to |
| 131 | // Kubernetes, and have special scaling options on top of those available |
| 132 | // to normal per-pod metrics (the "pods" source). |
| 133 | ResourceMetricSourceType MetricSourceType = "Resource" |
| 134 | // ExternalMetricSourceType is a global metric that is not associated |
| 135 | // with any Kubernetes object. It allows autoscaling based on information |
| 136 | // coming from components running outside of cluster |
| 137 | // (for example length of queue in cloud messaging service, or |
| 138 | // QPS from loadbalancer running outside of cluster). |
| 139 | ExternalMetricSourceType MetricSourceType = "External" |
| 140 | ) |
| 141 | |
| 142 | // ObjectMetricSource indicates how to scale on a metric describing a |
| 143 | // kubernetes object (for example, hits-per-second on an Ingress object). |
| 144 | type ObjectMetricSource struct { |
| 145 | DescribedObject CrossVersionObjectReference `json:"describedObject" protobuf:"bytes,1,name=describedObject"` |
| 146 | // target specifies the target value for the given metric |
| 147 | Target MetricTarget `json:"target" protobuf:"bytes,2,name=target"` |
| 148 | // metric identifies the target metric by name and selector |
| 149 | Metric MetricIdentifier `json:"metric" protobuf:"bytes,3,name=metric"` |
| 150 | } |
| 151 | |
| 152 | // PodsMetricSource indicates how to scale on a metric describing each pod in |
| 153 | // the current scale target (for example, transactions-processed-per-second). |
| 154 | // The values will be averaged together before being compared to the target |
| 155 | // value. |
| 156 | type PodsMetricSource struct { |
| 157 | // metric identifies the target metric by name and selector |
| 158 | Metric MetricIdentifier `json:"metric" protobuf:"bytes,1,name=metric"` |
| 159 | // target specifies the target value for the given metric |
| 160 | Target MetricTarget `json:"target" protobuf:"bytes,2,name=target"` |
| 161 | } |
| 162 | |
| 163 | // ResourceMetricSource indicates how to scale on a resource metric known to |
| 164 | // Kubernetes, as specified in requests and limits, describing each pod in the |
| 165 | // current scale target (e.g. CPU or memory). The values will be averaged |
| 166 | // together before being compared to the target. Such metrics are built in to |
| 167 | // Kubernetes, and have special scaling options on top of those available to |
| 168 | // normal per-pod metrics using the "pods" source. Only one "target" type |
| 169 | // should be set. |
| 170 | type ResourceMetricSource struct { |
| 171 | // name is the name of the resource in question. |
| 172 | Name v1.ResourceName `json:"name" protobuf:"bytes,1,name=name"` |
| 173 | // target specifies the target value for the given metric |
| 174 | Target MetricTarget `json:"target" protobuf:"bytes,2,name=target"` |
| 175 | } |
| 176 | |
| 177 | // ExternalMetricSource indicates how to scale on a metric not associated with |
| 178 | // any Kubernetes object (for example length of queue in cloud |
| 179 | // messaging service, or QPS from loadbalancer running outside of cluster). |
| 180 | type ExternalMetricSource struct { |
| 181 | // metric identifies the target metric by name and selector |
| 182 | Metric MetricIdentifier `json:"metric" protobuf:"bytes,1,name=metric"` |
| 183 | // target specifies the target value for the given metric |
| 184 | Target MetricTarget `json:"target" protobuf:"bytes,2,name=target"` |
| 185 | } |
| 186 | |
| 187 | // MetricIdentifier defines the name and optionally selector for a metric |
| 188 | type MetricIdentifier struct { |
| 189 | // name is the name of the given metric |
| 190 | Name string `json:"name" protobuf:"bytes,1,name=name"` |
| 191 | // selector is the string-encoded form of a standard kubernetes label selector for the given metric |
| 192 | // When set, it is passed as an additional parameter to the metrics server for more specific metrics scoping. |
| 193 | // When unset, just the metricName will be used to gather metrics. |
| 194 | // +optional |
| 195 | Selector *metav1.LabelSelector `json:"selector,omitempty" protobuf:"bytes,2,name=selector"` |
| 196 | } |
| 197 | |
| 198 | // MetricTarget defines the target value, average value, or average utilization of a specific metric |
| 199 | type MetricTarget struct { |
| 200 | // type represents whether the metric type is Utilization, Value, or AverageValue |
| 201 | Type MetricTargetType `json:"type" protobuf:"bytes,1,name=type"` |
| 202 | // value is the target value of the metric (as a quantity). |
| 203 | // +optional |
| 204 | Value *resource.Quantity `json:"value,omitempty" protobuf:"bytes,2,opt,name=value"` |
| 205 | // averageValue is the target value of the average of the |
| 206 | // metric across all relevant pods (as a quantity) |
| 207 | // +optional |
| 208 | AverageValue *resource.Quantity `json:"averageValue,omitempty" protobuf:"bytes,3,opt,name=averageValue"` |
| 209 | // averageUtilization is the target value of the average of the |
| 210 | // resource metric across all relevant pods, represented as a percentage of |
| 211 | // the requested value of the resource for the pods. |
| 212 | // Currently only valid for Resource metric source type |
| 213 | // +optional |
| 214 | AverageUtilization *int32 `json:"averageUtilization,omitempty" protobuf:"bytes,4,opt,name=averageUtilization"` |
| 215 | } |
| 216 | |
| 217 | // MetricTargetType specifies the type of metric being targeted, and should be either |
| 218 | // "Value", "AverageValue", or "Utilization" |
| 219 | type MetricTargetType string |
| 220 | |
| 221 | var ( |
| 222 | // UtilizationMetricType declares a MetricTarget is an AverageUtilization value |
| 223 | UtilizationMetricType MetricTargetType = "Utilization" |
| 224 | // ValueMetricType declares a MetricTarget is a raw value |
| 225 | ValueMetricType MetricTargetType = "Value" |
| 226 | // AverageValueMetricType declares a MetricTarget is an |
| 227 | AverageValueMetricType MetricTargetType = "AverageValue" |
| 228 | ) |
| 229 | |
| 230 | // HorizontalPodAutoscalerStatus describes the current status of a horizontal pod autoscaler. |
| 231 | type HorizontalPodAutoscalerStatus struct { |
| 232 | // observedGeneration is the most recent generation observed by this autoscaler. |
| 233 | // +optional |
| 234 | ObservedGeneration *int64 `json:"observedGeneration,omitempty" protobuf:"varint,1,opt,name=observedGeneration"` |
| 235 | |
| 236 | // lastScaleTime is the last time the HorizontalPodAutoscaler scaled the number of pods, |
| 237 | // used by the autoscaler to control how often the number of pods is changed. |
| 238 | // +optional |
| 239 | LastScaleTime *metav1.Time `json:"lastScaleTime,omitempty" protobuf:"bytes,2,opt,name=lastScaleTime"` |
| 240 | |
| 241 | // currentReplicas is current number of replicas of pods managed by this autoscaler, |
| 242 | // as last seen by the autoscaler. |
| 243 | CurrentReplicas int32 `json:"currentReplicas" protobuf:"varint,3,opt,name=currentReplicas"` |
| 244 | |
| 245 | // desiredReplicas is the desired number of replicas of pods managed by this autoscaler, |
| 246 | // as last calculated by the autoscaler. |
| 247 | DesiredReplicas int32 `json:"desiredReplicas" protobuf:"varint,4,opt,name=desiredReplicas"` |
| 248 | |
| 249 | // currentMetrics is the last read state of the metrics used by this autoscaler. |
| 250 | // +optional |
| 251 | CurrentMetrics []MetricStatus `json:"currentMetrics" protobuf:"bytes,5,rep,name=currentMetrics"` |
| 252 | |
| 253 | // conditions is the set of conditions required for this autoscaler to scale its target, |
| 254 | // and indicates whether or not those conditions are met. |
| 255 | Conditions []HorizontalPodAutoscalerCondition `json:"conditions" protobuf:"bytes,6,rep,name=conditions"` |
| 256 | } |
| 257 | |
| 258 | // HorizontalPodAutoscalerConditionType are the valid conditions of |
| 259 | // a HorizontalPodAutoscaler. |
| 260 | type HorizontalPodAutoscalerConditionType string |
| 261 | |
| 262 | var ( |
| 263 | // ScalingActive indicates that the HPA controller is able to scale if necessary: |
| 264 | // it's correctly configured, can fetch the desired metrics, and isn't disabled. |
| 265 | ScalingActive HorizontalPodAutoscalerConditionType = "ScalingActive" |
| 266 | // AbleToScale indicates a lack of transient issues which prevent scaling from occurring, |
| 267 | // such as being in a backoff window, or being unable to access/update the target scale. |
| 268 | AbleToScale HorizontalPodAutoscalerConditionType = "AbleToScale" |
| 269 | // ScalingLimited indicates that the calculated scale based on metrics would be above or |
| 270 | // below the range for the HPA, and has thus been capped. |
| 271 | ScalingLimited HorizontalPodAutoscalerConditionType = "ScalingLimited" |
| 272 | ) |
| 273 | |
| 274 | // HorizontalPodAutoscalerCondition describes the state of |
| 275 | // a HorizontalPodAutoscaler at a certain point. |
| 276 | type HorizontalPodAutoscalerCondition struct { |
| 277 | // type describes the current condition |
| 278 | Type HorizontalPodAutoscalerConditionType `json:"type" protobuf:"bytes,1,name=type"` |
| 279 | // status is the status of the condition (True, False, Unknown) |
| 280 | Status v1.ConditionStatus `json:"status" protobuf:"bytes,2,name=status"` |
| 281 | // lastTransitionTime is the last time the condition transitioned from |
| 282 | // one status to another |
| 283 | // +optional |
| 284 | LastTransitionTime metav1.Time `json:"lastTransitionTime,omitempty" protobuf:"bytes,3,opt,name=lastTransitionTime"` |
| 285 | // reason is the reason for the condition's last transition. |
| 286 | // +optional |
| 287 | Reason string `json:"reason,omitempty" protobuf:"bytes,4,opt,name=reason"` |
| 288 | // message is a human-readable explanation containing details about |
| 289 | // the transition |
| 290 | // +optional |
| 291 | Message string `json:"message,omitempty" protobuf:"bytes,5,opt,name=message"` |
| 292 | } |
| 293 | |
| 294 | // MetricStatus describes the last-read state of a single metric. |
| 295 | type MetricStatus struct { |
| 296 | // type is the type of metric source. It will be one of "Object", |
| 297 | // "Pods" or "Resource", each corresponds to a matching field in the object. |
| 298 | Type MetricSourceType `json:"type" protobuf:"bytes,1,name=type"` |
| 299 | |
| 300 | // object refers to a metric describing a single kubernetes object |
| 301 | // (for example, hits-per-second on an Ingress object). |
| 302 | // +optional |
| 303 | Object *ObjectMetricStatus `json:"object,omitempty" protobuf:"bytes,2,opt,name=object"` |
| 304 | // pods refers to a metric describing each pod in the current scale target |
| 305 | // (for example, transactions-processed-per-second). The values will be |
| 306 | // averaged together before being compared to the target value. |
| 307 | // +optional |
| 308 | Pods *PodsMetricStatus `json:"pods,omitempty" protobuf:"bytes,3,opt,name=pods"` |
| 309 | // resource refers to a resource metric (such as those specified in |
| 310 | // requests and limits) known to Kubernetes describing each pod in the |
| 311 | // current scale target (e.g. CPU or memory). Such metrics are built in to |
| 312 | // Kubernetes, and have special scaling options on top of those available |
| 313 | // to normal per-pod metrics using the "pods" source. |
| 314 | // +optional |
| 315 | Resource *ResourceMetricStatus `json:"resource,omitempty" protobuf:"bytes,4,opt,name=resource"` |
| 316 | // external refers to a global metric that is not associated |
| 317 | // with any Kubernetes object. It allows autoscaling based on information |
| 318 | // coming from components running outside of cluster |
| 319 | // (for example length of queue in cloud messaging service, or |
| 320 | // QPS from loadbalancer running outside of cluster). |
| 321 | // +optional |
| 322 | External *ExternalMetricStatus `json:"external,omitempty" protobuf:"bytes,5,opt,name=external"` |
| 323 | } |
| 324 | |
| 325 | // ObjectMetricStatus indicates the current value of a metric describing a |
| 326 | // kubernetes object (for example, hits-per-second on an Ingress object). |
| 327 | type ObjectMetricStatus struct { |
| 328 | // metric identifies the target metric by name and selector |
| 329 | Metric MetricIdentifier `json:"metric" protobuf:"bytes,1,name=metric"` |
| 330 | // current contains the current value for the given metric |
| 331 | Current MetricValueStatus `json:"current" protobuf:"bytes,2,name=current"` |
| 332 | |
| 333 | DescribedObject CrossVersionObjectReference `json:"describedObject" protobuf:"bytes,3,name=describedObject"` |
| 334 | } |
| 335 | |
| 336 | // PodsMetricStatus indicates the current value of a metric describing each pod in |
| 337 | // the current scale target (for example, transactions-processed-per-second). |
| 338 | type PodsMetricStatus struct { |
| 339 | // metric identifies the target metric by name and selector |
| 340 | Metric MetricIdentifier `json:"metric" protobuf:"bytes,1,name=metric"` |
| 341 | // current contains the current value for the given metric |
| 342 | Current MetricValueStatus `json:"current" protobuf:"bytes,2,name=current"` |
| 343 | } |
| 344 | |
| 345 | // ResourceMetricStatus indicates the current value of a resource metric known to |
| 346 | // Kubernetes, as specified in requests and limits, describing each pod in the |
| 347 | // current scale target (e.g. CPU or memory). Such metrics are built in to |
| 348 | // Kubernetes, and have special scaling options on top of those available to |
| 349 | // normal per-pod metrics using the "pods" source. |
| 350 | type ResourceMetricStatus struct { |
| 351 | // Name is the name of the resource in question. |
| 352 | Name v1.ResourceName `json:"name" protobuf:"bytes,1,name=name"` |
| 353 | // current contains the current value for the given metric |
| 354 | Current MetricValueStatus `json:"current" protobuf:"bytes,2,name=current"` |
| 355 | } |
| 356 | |
| 357 | // ExternalMetricStatus indicates the current value of a global metric |
| 358 | // not associated with any Kubernetes object. |
| 359 | type ExternalMetricStatus struct { |
| 360 | // metric identifies the target metric by name and selector |
| 361 | Metric MetricIdentifier `json:"metric" protobuf:"bytes,1,name=metric"` |
| 362 | // current contains the current value for the given metric |
| 363 | Current MetricValueStatus `json:"current" protobuf:"bytes,2,name=current"` |
| 364 | } |
| 365 | |
| 366 | // MetricValueStatus holds the current value for a metric |
| 367 | type MetricValueStatus struct { |
| 368 | // value is the current value of the metric (as a quantity). |
| 369 | // +optional |
| 370 | Value *resource.Quantity `json:"value,omitempty" protobuf:"bytes,1,opt,name=value"` |
| 371 | // averageValue is the current value of the average of the |
| 372 | // metric across all relevant pods (as a quantity) |
| 373 | // +optional |
| 374 | AverageValue *resource.Quantity `json:"averageValue,omitempty" protobuf:"bytes,2,opt,name=averageValue"` |
| 375 | // currentAverageUtilization is the current value of the average of the |
| 376 | // resource metric across all relevant pods, represented as a percentage of |
| 377 | // the requested value of the resource for the pods. |
| 378 | // +optional |
| 379 | AverageUtilization *int32 `json:"averageUtilization,omitempty" protobuf:"bytes,3,opt,name=averageUtilization"` |
| 380 | } |
| 381 | |
| 382 | // +k8s:deepcopy-gen:interfaces=k8s.io/apimachinery/pkg/runtime.Object |
| 383 | |
| 384 | // HorizontalPodAutoscalerList is a list of horizontal pod autoscaler objects. |
| 385 | type HorizontalPodAutoscalerList struct { |
| 386 | metav1.TypeMeta `json:",inline"` |
| 387 | // metadata is the standard list metadata. |
| 388 | // +optional |
| 389 | metav1.ListMeta `json:"metadata,omitempty" protobuf:"bytes,1,opt,name=metadata"` |
| 390 | |
| 391 | // items is the list of horizontal pod autoscaler objects. |
| 392 | Items []HorizontalPodAutoscaler `json:"items" protobuf:"bytes,2,rep,name=items"` |
| 393 | } |