1 /* 2 Copyright 2016 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 package autoscaling 18 19 import ( 20 "k8s.io/apimachinery/pkg/api/resource" 21 metav1 "k8s.io/apimachinery/pkg/apis/meta/v1" 22 api "k8s.io/kubernetes/pkg/apis/core" 23 ) 24 25 // +k8s:deepcopy-gen:interfaces=k8s.io/apimachinery/pkg/runtime.Object 26 27 // Scale represents a scaling request for a resource. 28 type Scale struct { 29 metav1.TypeMeta 30 // Standard object metadata; More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata. 31 // +optional 32 metav1.ObjectMeta 33 34 // spec defines the behavior of the scale. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#spec-and-status. 35 // +optional 36 Spec ScaleSpec 37 38 // status represents the current status of the scale. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#spec-and-status. Read-only. 39 // +optional 40 Status ScaleStatus 41 } 42 43 // ScaleSpec describes the attributes of a scale subresource. 44 type ScaleSpec struct { 45 // replicas is the desired number of instances for the scaled object. 46 // +optional 47 Replicas int32 48 } 49 50 // ScaleStatus represents the current status of a scale subresource. 51 type ScaleStatus struct { 52 // replicas is the actual number of observed instances of the scaled object. 53 Replicas int32 54 55 // label query over pods that should match the replicas count. This is same 56 // as the label selector but in the string format to avoid introspection 57 // by clients. The string will be in the same format as the query-param syntax. 58 // More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/#label-selectors 59 // +optional 60 Selector string 61 } 62 63 // CrossVersionObjectReference contains enough information to let you identify the referred resource. 64 type CrossVersionObjectReference struct { 65 // kind is the kind of the referent; More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds" 66 Kind string 67 68 // name is the name of the referent; More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names 69 Name string 70 71 // apiVersion is the API version of the referent 72 // +optional 73 APIVersion string 74 } 75 76 // HorizontalPodAutoscalerSpec describes the desired functionality of the HorizontalPodAutoscaler. 77 type HorizontalPodAutoscalerSpec struct { 78 // scaleTargetRef points to the target resource to scale, and is used to the pods for which metrics 79 // should be collected, as well as to actually change the replica count. 80 ScaleTargetRef CrossVersionObjectReference 81 82 // minReplicas is the lower limit for the number of replicas to which the autoscaler 83 // can scale down. It defaults to 1 pod. minReplicas is allowed to be 0 if the 84 // alpha feature gate HPAScaleToZero is enabled and at least one Object or External 85 // metric is configured. Scaling is active as long as at least one metric value is 86 // available. 87 // +optional 88 MinReplicas *int32 89 90 // maxReplicas is the upper limit for the number of replicas to which the autoscaler can scale up. 91 // It cannot be less that minReplicas. 92 MaxReplicas int32 93 94 // metrics contains the specifications for which to use to calculate the 95 // desired replica count (the maximum replica count across all metrics will 96 // be used). The desired replica count is calculated multiplying the 97 // ratio between the target value and the current value by the current 98 // number of pods. Ergo, metrics used must decrease as the pod count is 99 // increased, and vice-versa. See the individual metric source types for 100 // more information about how each type of metric must respond. 101 // +optional 102 Metrics []MetricSpec 103 104 // behavior configures the scaling behavior of the target 105 // in both Up and Down directions (scaleUp and scaleDown fields respectively). 106 // If not set, the default HPAScalingRules for scale up and scale down are used. 107 // +optional 108 Behavior *HorizontalPodAutoscalerBehavior 109 } 110 111 // HorizontalPodAutoscalerBehavior configures a scaling behavior for Up and Down direction 112 // (scaleUp and scaleDown fields respectively). 113 type HorizontalPodAutoscalerBehavior struct { 114 // scaleUp is scaling policy for scaling Up. 115 // If not set, the default value is the higher of: 116 // * increase no more than 4 pods per 60 seconds 117 // * double the number of pods per 60 seconds 118 // No stabilization is used. 119 // +optional 120 ScaleUp *HPAScalingRules 121 // scaleDown is scaling policy for scaling Down. 122 // If not set, the default value is to allow to scale down to minReplicas pods, with a 123 // 300 second stabilization window (i.e., the highest recommendation for 124 // the last 300sec is used). 125 // +optional 126 ScaleDown *HPAScalingRules 127 } 128 129 // ScalingPolicySelect is used to specify which policy should be used while scaling in a certain direction 130 type ScalingPolicySelect string 131 132 const ( 133 // MaxPolicySelect selects the policy with the highest possible change. 134 MaxPolicySelect ScalingPolicySelect = "Max" 135 // MinPolicySelect selects the policy with the lowest possible change. 136 MinPolicySelect ScalingPolicySelect = "Min" 137 // DisabledPolicySelect disables the scaling in this direction. 138 DisabledPolicySelect ScalingPolicySelect = "Disabled" 139 ) 140 141 // HPAScalingRules configures the scaling behavior for one direction. 142 // These Rules are applied after calculating DesiredReplicas from metrics for the HPA. 143 // They can limit the scaling velocity by specifying scaling policies. 144 // They can prevent flapping by specifying the stabilization window, so that the 145 // number of replicas is not set instantly, instead, the safest value from the stabilization 146 // window is chosen. 147 type HPAScalingRules struct { 148 // StabilizationWindowSeconds is the number of seconds for which past recommendations should be 149 // considered while scaling up or scaling down. 150 // StabilizationWindowSeconds must be greater than or equal to zero and less than or equal to 3600 (one hour). 151 // If not set, use the default values: 152 // - For scale up: 0 (i.e. no stabilization is done). 153 // - For scale down: 300 (i.e. the stabilization window is 300 seconds long). 154 // +optional 155 StabilizationWindowSeconds *int32 156 // selectPolicy is used to specify which policy should be used. 157 // If not set, the default value MaxPolicySelect is used. 158 // +optional 159 SelectPolicy *ScalingPolicySelect 160 // policies is a list of potential scaling polices which can used during scaling. 161 // At least one policy must be specified, otherwise the HPAScalingRules will be discarded as invalid 162 // +optional 163 Policies []HPAScalingPolicy 164 } 165 166 // HPAScalingPolicyType is the type of the policy which could be used while making scaling decisions. 167 type HPAScalingPolicyType string 168 169 const ( 170 // PodsScalingPolicy is a policy used to specify a change in absolute number of pods. 171 PodsScalingPolicy HPAScalingPolicyType = "Pods" 172 // PercentScalingPolicy is a policy used to specify a relative amount of change with respect to 173 // the current number of pods. 174 PercentScalingPolicy HPAScalingPolicyType = "Percent" 175 ) 176 177 // HPAScalingPolicy is a single policy which must hold true for a specified past interval. 178 type HPAScalingPolicy struct { 179 // Type is used to specify the scaling policy. 180 Type HPAScalingPolicyType 181 // Value contains the amount of change which is permitted by the policy. 182 // It must be greater than zero 183 Value int32 184 // PeriodSeconds specifies the window of time for which the policy should hold true. 185 // PeriodSeconds must be greater than zero and less than or equal to 1800 (30 min). 186 PeriodSeconds int32 187 } 188 189 // MetricSourceType indicates the type of metric. 190 type MetricSourceType string 191 192 const ( 193 // ObjectMetricSourceType is a metric describing a kubernetes object 194 // (for example, hits-per-second on an Ingress object). 195 ObjectMetricSourceType MetricSourceType = "Object" 196 // PodsMetricSourceType is a metric describing each pod in the current scale 197 // target (for example, transactions-processed-per-second). The values 198 // will be averaged together before being compared to the target value. 199 PodsMetricSourceType MetricSourceType = "Pods" 200 // ResourceMetricSourceType is a resource metric known to Kubernetes, as 201 // specified in requests and limits, describing each pod in the current 202 // scale target (e.g. CPU or memory). Such metrics are built in to 203 // Kubernetes, and have special scaling options on top of those available 204 // to normal per-pod metrics (the "pods" source). 205 ResourceMetricSourceType MetricSourceType = "Resource" 206 // ExternalMetricSourceType is a global metric that is not associated 207 // with any Kubernetes object. It allows autoscaling based on information 208 // coming from components running outside of cluster 209 // (for example length of queue in cloud messaging service, or 210 // QPS from loadbalancer running outside of cluster). 211 ExternalMetricSourceType MetricSourceType = "External" 212 // ContainerResourceMetricSourceType is a resource metric known to Kubernetes, as 213 // specified in requests and limits, describing a single container in each pod in the current 214 // scale target (e.g. CPU or memory). Such metrics are built in to 215 // Kubernetes, and have special scaling options on top of those available 216 // to normal per-pod metrics (the "pods" source). 217 ContainerResourceMetricSourceType MetricSourceType = "ContainerResource" 218 ) 219 220 // MetricSpec specifies how to scale based on a single metric 221 // (only `type` and one other matching field should be set at once). 222 type MetricSpec struct { 223 // Type is the type of metric source. It should be one of "Object", 224 // "Pods" or "Resource", each mapping to a matching field in the object. 225 Type MetricSourceType 226 227 // Object refers to a metric describing a single kubernetes object 228 // (for example, hits-per-second on an Ingress object). 229 // +optional 230 Object *ObjectMetricSource 231 // Pods refers to a metric describing each pod in the current scale target 232 // (for example, transactions-processed-per-second). The values will be 233 // averaged together before being compared to the target value. 234 // +optional 235 Pods *PodsMetricSource 236 // Resource refers to a resource metric (such as those specified in 237 // requests and limits) known to Kubernetes describing each pod in the 238 // current scale target (e.g. CPU or memory). Such metrics are built in to 239 // Kubernetes, and have special scaling options on top of those available 240 // to normal per-pod metrics using the "pods" source. 241 // +optional 242 Resource *ResourceMetricSource 243 // ContainerResource refers to a resource metric (such as those specified in 244 // requests and limits) known to Kubernetes describing a single container in each pod of the 245 // current scale target (e.g. CPU or memory). Such metrics are built in to 246 // Kubernetes, and have special scaling options on top of those available 247 // to normal per-pod metrics using the "pods" source. 248 // +optional 249 ContainerResource *ContainerResourceMetricSource 250 // External refers to a global metric that is not associated 251 // with any Kubernetes object. It allows autoscaling based on information 252 // coming from components running outside of cluster 253 // (for example length of queue in cloud messaging service, or 254 // QPS from loadbalancer running outside of cluster). 255 // +optional 256 External *ExternalMetricSource 257 } 258 259 // ObjectMetricSource indicates how to scale on a metric describing a 260 // kubernetes object (for example, hits-per-second on an Ingress object). 261 type ObjectMetricSource struct { 262 DescribedObject CrossVersionObjectReference 263 Target MetricTarget 264 Metric MetricIdentifier 265 } 266 267 // PodsMetricSource indicates how to scale on a metric describing each pod in 268 // the current scale target (for example, transactions-processed-per-second). 269 // The values will be averaged together before being compared to the target 270 // value. 271 type PodsMetricSource struct { 272 // metric identifies the target metric by name and selector 273 Metric MetricIdentifier 274 // target specifies the target value for the given metric 275 Target MetricTarget 276 } 277 278 // ResourceMetricSource indicates how to scale on a resource metric known to 279 // Kubernetes, as specified in requests and limits, describing each pod in the 280 // current scale target (e.g. CPU or memory). The values will be averaged 281 // together before being compared to the target. Such metrics are built in to 282 // Kubernetes, and have special scaling options on top of those available to 283 // normal per-pod metrics using the "pods" source. Only one "target" type 284 // should be set. 285 type ResourceMetricSource struct { 286 // Name is the name of the resource in question. 287 Name api.ResourceName 288 // Target specifies the target value for the given metric 289 Target MetricTarget 290 } 291 292 // ContainerResourceMetricSource indicates how to scale on a resource metric known to 293 // Kubernetes, as specified in the requests and limits, describing a single container in 294 // each of the pods of the current scale target(e.g. CPU or memory). The values will be 295 // averaged together before being compared to the target. Such metrics are built into 296 // Kubernetes, and have special scaling options on top of those available to 297 // normal per-pod metrics using the "pods" source. Only one "target" type 298 // should be set. 299 type ContainerResourceMetricSource struct { 300 // name is the name of the of the resource 301 Name api.ResourceName 302 // container is the name of the container in the pods of the scaling target. 303 Container string 304 // target specifies the target value for the given metric 305 Target MetricTarget 306 } 307 308 // ExternalMetricSource indicates how to scale on a metric not associated with 309 // any Kubernetes object (for example length of queue in cloud 310 // messaging service, or QPS from loadbalancer running outside of cluster). 311 type ExternalMetricSource struct { 312 // Metric identifies the target metric by name and selector 313 Metric MetricIdentifier 314 // Target specifies the target value for the given metric 315 Target MetricTarget 316 } 317 318 // MetricIdentifier defines the name and optionally selector for a metric 319 type MetricIdentifier struct { 320 // Name is the name of the given metric 321 Name string 322 // Selector is the selector for the given metric 323 // it is the string-encoded form of a standard kubernetes label selector 324 // +optional 325 Selector *metav1.LabelSelector 326 } 327 328 // MetricTarget defines the target value, average value, or average utilization of a specific metric 329 type MetricTarget struct { 330 // Type represents whether the metric type is Utilization, Value, or AverageValue 331 Type MetricTargetType 332 // Value is the target value of the metric (as a quantity). 333 Value *resource.Quantity 334 // TargetAverageValue is the target value of the average of the 335 // metric across all relevant pods (as a quantity) 336 AverageValue *resource.Quantity 337 338 // AverageUtilization is the target value of the average of the 339 // resource metric across all relevant pods, represented as a percentage of 340 // the requested value of the resource for the pods. 341 // Currently only valid for Resource metric source type 342 AverageUtilization *int32 343 } 344 345 // MetricTargetType specifies the type of metric being targeted, and should be either 346 // "Value", "AverageValue", or "Utilization" 347 type MetricTargetType string 348 349 const ( 350 // UtilizationMetricType is a possible value for MetricTarget.Type. 351 UtilizationMetricType MetricTargetType = "Utilization" 352 // ValueMetricType is a possible value for MetricTarget.Type. 353 ValueMetricType MetricTargetType = "Value" 354 // AverageValueMetricType is a possible value for MetricTarget.Type. 355 AverageValueMetricType MetricTargetType = "AverageValue" 356 ) 357 358 // HorizontalPodAutoscalerStatus describes the current status of a horizontal pod autoscaler. 359 type HorizontalPodAutoscalerStatus struct { 360 // ObservedGeneration is the most recent generation observed by this autoscaler. 361 // +optional 362 ObservedGeneration *int64 363 364 // LastScaleTime is the last time the HorizontalPodAutoscaler scaled the number of pods, 365 // used by the autoscaler to control how often the number of pods is changed. 366 // +optional 367 LastScaleTime *metav1.Time 368 369 // CurrentReplicas is current number of replicas of pods managed by this autoscaler, 370 // as last seen by the autoscaler. 371 CurrentReplicas int32 372 373 // DesiredReplicas is the desired number of replicas of pods managed by this autoscaler, 374 // as last calculated by the autoscaler. 375 DesiredReplicas int32 376 377 // CurrentMetrics is the last read state of the metrics used by this autoscaler. 378 // +optional 379 CurrentMetrics []MetricStatus 380 381 // Conditions is the set of conditions required for this autoscaler to scale its target, 382 // and indicates whether or not those conditions are met. 383 Conditions []HorizontalPodAutoscalerCondition 384 } 385 386 // ConditionStatus indicates the status of a condition (true, false, or unknown). 387 type ConditionStatus string 388 389 // These are valid condition statuses. "ConditionTrue" means a resource is in the condition; 390 // "ConditionFalse" means a resource is not in the condition; "ConditionUnknown" means kubernetes 391 // can't decide if a resource is in the condition or not. In the future, we could add other 392 // intermediate conditions, e.g. ConditionDegraded. 393 const ( 394 ConditionTrue ConditionStatus = "True" 395 ConditionFalse ConditionStatus = "False" 396 ConditionUnknown ConditionStatus = "Unknown" 397 ) 398 399 // HorizontalPodAutoscalerConditionType are the valid conditions of 400 // a HorizontalPodAutoscaler. 401 type HorizontalPodAutoscalerConditionType string 402 403 const ( 404 // ScalingActive indicates that the HPA controller is able to scale if necessary: 405 // it's correctly configured, can fetch the desired metrics, and isn't disabled. 406 ScalingActive HorizontalPodAutoscalerConditionType = "ScalingActive" 407 // AbleToScale indicates a lack of transient issues which prevent scaling from occurring, 408 // such as being in a backoff window, or being unable to access/update the target scale. 409 AbleToScale HorizontalPodAutoscalerConditionType = "AbleToScale" 410 // ScalingLimited indicates that the calculated scale based on metrics would be above or 411 // below the range for the HPA, and has thus been capped. 412 ScalingLimited HorizontalPodAutoscalerConditionType = "ScalingLimited" 413 ) 414 415 // HorizontalPodAutoscalerCondition describes the state of 416 // a HorizontalPodAutoscaler at a certain point. 417 type HorizontalPodAutoscalerCondition struct { 418 // Type describes the current condition 419 Type HorizontalPodAutoscalerConditionType 420 // Status is the status of the condition (True, False, Unknown) 421 Status ConditionStatus 422 // LastTransitionTime is the last time the condition transitioned from 423 // one status to another 424 // +optional 425 LastTransitionTime metav1.Time 426 // Reason is the reason for the condition's last transition. 427 // +optional 428 Reason string 429 // Message is a human-readable explanation containing details about 430 // the transition 431 // +optional 432 Message string 433 } 434 435 // MetricStatus describes the last-read state of a single metric. 436 type MetricStatus struct { 437 // Type is the type of metric source. It will be one of "Object", 438 // "Pods" or "Resource", each corresponds to a matching field in the object. 439 Type MetricSourceType 440 441 // Object refers to a metric describing a single kubernetes object 442 // (for example, hits-per-second on an Ingress object). 443 // +optional 444 Object *ObjectMetricStatus 445 // Pods refers to a metric describing each pod in the current scale target 446 // (for example, transactions-processed-per-second). The values will be 447 // averaged together before being compared to the target value. 448 // +optional 449 Pods *PodsMetricStatus 450 // Resource refers to a resource metric (such as those specified in 451 // requests and limits) known to Kubernetes describing each pod in the 452 // current scale target (e.g. CPU or memory). Such metrics are built in to 453 // Kubernetes, and have special scaling options on top of those available 454 // to normal per-pod metrics using the "pods" source. 455 // +optional 456 Resource *ResourceMetricStatus 457 // ContainerResource refers to a resource metric (such as those specified in 458 // requests and limits) known to Kubernetes describing a single container in each pod in the 459 // current scale target (e.g. CPU or memory). Such metrics are built in to 460 // Kubernetes, and have special scaling options on top of those available 461 // to normal per-pod metrics using the "pods" source. 462 // +optional 463 ContainerResource *ContainerResourceMetricStatus 464 // External refers to a global metric that is not associated 465 // with any Kubernetes object. It allows autoscaling based on information 466 // coming from components running outside of cluster 467 // (for example length of queue in cloud messaging service, or 468 // QPS from loadbalancer running outside of cluster). 469 // +optional 470 External *ExternalMetricStatus 471 } 472 473 // ObjectMetricStatus indicates the current value of a metric describing a 474 // kubernetes object (for example, hits-per-second on an Ingress object). 475 type ObjectMetricStatus struct { 476 Metric MetricIdentifier 477 Current MetricValueStatus 478 479 DescribedObject CrossVersionObjectReference 480 } 481 482 // PodsMetricStatus indicates the current value of a metric describing each pod in 483 // the current scale target (for example, transactions-processed-per-second). 484 type PodsMetricStatus struct { 485 Metric MetricIdentifier 486 Current MetricValueStatus 487 } 488 489 // ResourceMetricStatus indicates the current value of a resource metric known to 490 // Kubernetes, as specified in requests and limits, describing each pod in the 491 // current scale target (e.g. CPU or memory). Such metrics are built in to 492 // Kubernetes, and have special scaling options on top of those available to 493 // normal per-pod metrics using the "pods" source. 494 type ResourceMetricStatus struct { 495 // name is the name of the resource in question. 496 Name api.ResourceName 497 Current MetricValueStatus 498 } 499 500 // ContainerResourceMetricStatus indicates the current value of a resource metric known to 501 // Kubernetes, as specified in requests and limits, describing each pod in the 502 // current scale target (e.g. CPU or memory). Such metrics are built in to 503 // Kubernetes, and have special scaling options on top of those available to 504 // normal per-pod metrics using the "pods" source. 505 type ContainerResourceMetricStatus struct { 506 // name is the name of the resource in question. 507 Name api.ResourceName 508 Container string 509 Current MetricValueStatus 510 } 511 512 // ExternalMetricStatus indicates the current value of a global metric 513 // not associated with any Kubernetes object. 514 type ExternalMetricStatus struct { 515 Metric MetricIdentifier 516 Current MetricValueStatus 517 } 518 519 // MetricValueStatus indicates the current value of a metric. 520 type MetricValueStatus struct { 521 Value *resource.Quantity 522 AverageValue *resource.Quantity 523 AverageUtilization *int32 524 } 525 526 // +k8s:deepcopy-gen:interfaces=k8s.io/apimachinery/pkg/runtime.Object 527 528 // HorizontalPodAutoscaler is the configuration for a horizontal pod 529 // autoscaler, which automatically manages the replica count of any resource 530 // implementing the scale subresource based on the metrics specified. 531 type HorizontalPodAutoscaler struct { 532 metav1.TypeMeta 533 // Metadata is the standard object metadata. 534 // More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata 535 // +optional 536 metav1.ObjectMeta 537 538 // spec is the specification for the behaviour of the autoscaler. 539 // More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#spec-and-status. 540 // +optional 541 Spec HorizontalPodAutoscalerSpec 542 543 // status is the current information about the autoscaler. 544 // +optional 545 Status HorizontalPodAutoscalerStatus 546 } 547 548 // +k8s:deepcopy-gen:interfaces=k8s.io/apimachinery/pkg/runtime.Object 549 550 // HorizontalPodAutoscalerList is a list of horizontal pod autoscaler objects. 551 type HorizontalPodAutoscalerList struct { 552 metav1.TypeMeta 553 // Metadata is the standard list metadata. 554 // +optional 555 metav1.ListMeta 556 557 // items is the list of horizontal pod autoscaler objects. 558 Items []HorizontalPodAutoscaler 559 } 560