kubernetes
/
autoscaler
mirror of https://github.com/kubernetes/autoscaler.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity
autoscaler/vertical-pod-autoscaler/docs/api.md

21 KiB
Raw Blame History

API Reference

Packages

autoscaling.k8s.io/v1

Package v1 contains definitions of Vertical Pod Autoscaler related objects.

ContainerControlledValues

Underlying type: string

ContainerControlledValues controls which resource value should be autoscaled.

Validation:

  • Enum: [RequestsAndLimits RequestsOnly]

Appears in:

Field Description
RequestsAndLimits ContainerControlledValuesRequestsAndLimits means resource request and limits
are scaled automatically. The limit is scaled proportionally to the request.
RequestsOnly ContainerControlledValuesRequestsOnly means only requested resource is autoscaled.

ContainerResourcePolicy

ContainerResourcePolicy controls how autoscaler computes the recommended resources for a specific container.

Appears in:

Field Description Default Validation
containerName string Name of the container or DefaultContainerResourcePolicy, in which
case the policy is used by the containers that don't have their own
policy specified.
mode ContainerScalingMode Whether autoscaler is enabled for the container. The default is "Auto". Enum: [Auto Off]
minAllowed ResourceList Specifies the minimal amount of resources that will be recommended
for the container. The default is no minimum.
maxAllowed ResourceList Specifies the maximum amount of resources that will be recommended
for the container. The default is no maximum.
controlledResources ResourceName Specifies the type of recommendations that will be computed
(and possibly applied) by VPA.
If not specified, the default of [ResourceCPU, ResourceMemory] will be used.
controlledValues ContainerControlledValues Specifies which resource values should be controlled.
The default is "RequestsAndLimits".		 Enum: [RequestsAndLimits RequestsOnly]
oomBumpUpRatio float OOMBumpUpRatio is the ratio to increase resources when OOM is detected. Minimum: 1
oomMinBumpUp float OOMMinBumpUp is the minimum increase in resources when OOM is detected. Minimum: 0

ContainerScalingMode

Underlying type: string

ContainerScalingMode controls whether autoscaler is enabled for a specific container.

Validation:

  • Enum: [Auto Off]

Appears in:

Field Description
Auto ContainerScalingModeAuto means autoscaling is enabled for a container.
Off ContainerScalingModeOff means autoscaling is disabled for a container.

EvictionChangeRequirement

Underlying type: string

EvictionChangeRequirement refers to the relationship between the new target recommendation for a Pod and its current requests, what kind of change is necessary for the Pod to be evicted

Validation:

  • Enum: [TargetHigherThanRequests TargetLowerThanRequests]

Appears in:

Field Description
TargetHigherThanRequests TargetHigherThanRequests means the new target recommendation for a Pod is higher than its current requests, i.e. the Pod is scaled up
TargetLowerThanRequests TargetLowerThanRequests means the new target recommendation for a Pod is lower than its current requests, i.e. the Pod is scaled down

EvictionRequirement

EvictionRequirement defines a single condition which needs to be true in order to evict a Pod

Appears in:

Field Description Default Validation
resources ResourceName array Resources is a list of one or more resources that the condition applies
to. If more than one resource is given, the EvictionRequirement is fulfilled
if at least one resource meets changeRequirement.
changeRequirement EvictionChangeRequirement Enum: [TargetHigherThanRequests TargetLowerThanRequests]

HistogramCheckpoint

HistogramCheckpoint contains data needed to reconstruct the histogram.

Appears in:

Field Description Default Validation
referenceTimestamp Time Reference timestamp for samples collected within this histogram.
bucketWeights object (keys:integer, values:integer) Map from bucket index to bucket weight. Type: object
XPreserveUnknownFields: {}
totalWeight float Sum of samples to be used as denominator for weights from BucketWeights.

PodResourcePolicy

PodResourcePolicy controls how autoscaler computes the recommended resources for containers belonging to the pod. There can be at most one entry for every named container and optionally a single wildcard entry with containerName = '*', which handles all containers that don't have individual policies.

Appears in:

Field Description Default Validation
containerPolicies ContainerResourcePolicy array Per-container resource policies.

PodUpdatePolicy

PodUpdatePolicy describes the rules on how changes are applied to the pods.

Appears in:

Field Description Default Validation
updateMode UpdateMode Controls when autoscaler applies changes to the pod resources.
The default is 'Auto'.		 Enum: [Off Initial Recreate InPlaceOrRecreate Auto]
minReplicas integer Minimal number of replicas which need to be alive for Updater to attempt
pod eviction (pending other checks like PDB). Only positive values are
allowed. Overrides global '--min-replicas' flag.
evictionRequirements EvictionRequirement array EvictionRequirements is a list of EvictionRequirements that need to
evaluate to true in order for a Pod to be evicted. If more than one
EvictionRequirement is specified, all of them need to be fulfilled to allow eviction.

RecommendedContainerResources

RecommendedContainerResources is the recommendation of resources computed by autoscaler for a specific container. Respects the container resource policy if present in the spec. In particular the recommendation is not produced for containers with ContainerScalingMode set to 'Off'.

Appears in:

Field Description Default Validation
containerName string Name of the container.
target ResourceList Recommended amount of resources. Observes ContainerResourcePolicy.
lowerBound ResourceList Minimum recommended amount of resources. Observes ContainerResourcePolicy.
This amount is not guaranteed to be sufficient for the application to operate in a stable way, however
running with less resources is likely to have significant impact on performance/availability.
upperBound ResourceList Maximum recommended amount of resources. Observes ContainerResourcePolicy.
Any resources allocated beyond this value are likely wasted. This value may be larger than the maximum
amount of application is actually capable of consuming.
uncappedTarget ResourceList The most recent recommended resources target computed by the autoscaler
for the controlled pods, based only on actual resource usage, not taking
into account the ContainerResourcePolicy.
May differ from the Recommendation if the actual resource usage causes
the target to violate the ContainerResourcePolicy (lower than MinAllowed
or higher that MaxAllowed).
Used only as status indication, will not affect actual resource assignment.

RecommendedPodResources

RecommendedPodResources is the recommendation of resources computed by autoscaler. It contains a recommendation for each container in the pod (except for those with ContainerScalingMode set to 'Off').

Appears in:

Field Description Default Validation
containerRecommendations RecommendedContainerResources array Resources recommended by the autoscaler for each container.

UpdateMode

Underlying type: string

UpdateMode controls when autoscaler applies changes to the pod resources.

Validation:

  • Enum: [Off Initial Recreate InPlaceOrRecreate Auto]

Appears in:

Field Description
Off UpdateModeOff means that autoscaler never changes Pod resources.
The recommender still sets the recommended resources in the
VerticalPodAutoscaler object. This can be used for a "dry run".
Initial UpdateModeInitial means that autoscaler only assigns resources on pod
creation and does not change them during the lifetime of the pod.
Recreate UpdateModeRecreate means that autoscaler assigns resources on pod
creation and additionally can update them during the lifetime of the
pod by deleting and recreating the pod.
Auto Deprecated - UpdateModeAuto means that autoscaler assigns resources on pod creation
and additionally can update them during the lifetime of the pod,
using any available update method. Currently this is equivalent to
Recreate. This mode is deprecated and will be removed in a future API version.
Use explicit modes like "Recreate", "Initial", or "InPlaceOrRecreate" instead.
See issue #8424 for more details.
InPlaceOrRecreate UpdateModeInPlaceOrRecreate means that autoscaler tries to assign resources in-place.
If this is not possible (e.g., resizing takes too long or is infeasible), it falls back to the
"Recreate" update mode.
Requires VPA level feature gate "InPlaceOrRecreate" to be enabled
on the admission and updater pods.
Requires cluster feature gate "InPlacePodVerticalScaling" to be enabled.

VerticalPodAutoscaler

VerticalPodAutoscaler is the configuration for a vertical pod autoscaler, which automatically manages pod resources based on historical and real time resource utilization.

Appears in:

Field Description Default Validation
kind string Kind is a string value representing the REST resource this object represents.
Servers may infer this from the endpoint the client submits requests to.
Cannot be updated.
In CamelCase.
More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds
apiVersion string APIVersion defines the versioned schema of this representation of an object.
Servers should convert recognized schemas to the latest internal value, and
may reject unrecognized values.
More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources
metadata ObjectMeta Refer to Kubernetes API documentation for fields of metadata.
spec VerticalPodAutoscalerSpec Specification of the behavior of the autoscaler.
More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#spec-and-status.
status VerticalPodAutoscalerStatus Current information about the autoscaler.

VerticalPodAutoscalerCheckpoint

VerticalPodAutoscalerCheckpoint is the checkpoint of the internal state of VPA that is used for recovery after recommender's restart.

Appears in:

Field Description Default Validation
kind string Kind is a string value representing the REST resource this object represents.
Servers may infer this from the endpoint the client submits requests to.
Cannot be updated.
In CamelCase.
More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds
apiVersion string APIVersion defines the versioned schema of this representation of an object.
Servers should convert recognized schemas to the latest internal value, and
may reject unrecognized values.
More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources
metadata ObjectMeta Refer to Kubernetes API documentation for fields of metadata.
spec VerticalPodAutoscalerCheckpointSpec Specification of the checkpoint.
More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#spec-and-status.
status VerticalPodAutoscalerCheckpointStatus Data of the checkpoint.

VerticalPodAutoscalerCheckpointSpec

VerticalPodAutoscalerCheckpointSpec is the specification of the checkpoint object.

Appears in:

Field Description Default Validation
vpaObjectName string Name of the VPA object that stored VerticalPodAutoscalerCheckpoint object.
containerName string Name of the checkpointed container.

VerticalPodAutoscalerCheckpointStatus

VerticalPodAutoscalerCheckpointStatus contains data of the checkpoint.

Appears in:

Field Description Default Validation
lastUpdateTime Time The time when the status was last refreshed.
version string Version of the format of the stored data.
cpuHistogram HistogramCheckpoint Checkpoint of histogram for consumption of CPU.
memoryHistogram HistogramCheckpoint Checkpoint of histogram for consumption of memory.
firstSampleStart Time Timestamp of the fist sample from the histograms.
lastSampleStart Time Timestamp of the last sample from the histograms.
totalSamplesCount integer Total number of samples in the histograms.

VerticalPodAutoscalerCondition

VerticalPodAutoscalerCondition describes the state of a VerticalPodAutoscaler at a certain point.

Appears in:

Field Description Default Validation
type VerticalPodAutoscalerConditionType type describes the current condition
status ConditionStatus status is the status of the condition (True, False, Unknown)
lastTransitionTime Time lastTransitionTime is the last time the condition transitioned from
one status to another
reason string reason is the reason for the condition's last transition.
message string message is a human-readable explanation containing details about
the transition

VerticalPodAutoscalerConditionType

Underlying type: string

VerticalPodAutoscalerConditionType are the valid conditions of a VerticalPodAutoscaler.

Appears in:

VerticalPodAutoscalerRecommenderSelector

VerticalPodAutoscalerRecommenderSelector points to a specific Vertical Pod Autoscaler recommender. In the future it might pass parameters to the recommender.

Appears in:

Field Description Default Validation
name string Name of the recommender responsible for generating recommendation for this object.

VerticalPodAutoscalerSpec

VerticalPodAutoscalerSpec is the specification of the behavior of the autoscaler.

Appears in:

Field Description Default Validation
targetRef CrossVersionObjectReference TargetRef points to the controller managing the set of pods for the
autoscaler to control - e.g. Deployment, StatefulSet. VerticalPodAutoscaler
can be targeted at controller implementing scale subresource (the pod set is
retrieved from the controller's ScaleStatus) or some well known controllers
(e.g. for DaemonSet the pod set is read from the controller's spec).
If VerticalPodAutoscaler cannot use specified target it will report
ConfigUnsupported condition.
Note that VerticalPodAutoscaler does not require full implementation
of scale subresource - it will not use it to modify the replica count.
The only thing retrieved is a label selector matching pods grouped by
the target resource.
updatePolicy PodUpdatePolicy Describes the rules on how changes are applied to the pods.
If not specified, all fields in the PodUpdatePolicy are set to their
default values.
resourcePolicy PodResourcePolicy Controls how the autoscaler computes recommended resources.
The resource policy may be used to set constraints on the recommendations
for individual containers.
If any individual containers need to be excluded from getting the VPA recommendations, then
it must be disabled explicitly by setting mode to "Off" under containerPolicies.
If not specified, the autoscaler computes recommended resources for all containers in the pod,
without additional constraints.
recommenders VerticalPodAutoscalerRecommenderSelector array Recommender responsible for generating recommendation for this object.
List should be empty (then the default recommender will generate the
recommendation) or contain exactly one recommender.

VerticalPodAutoscalerStatus

VerticalPodAutoscalerStatus describes the runtime state of the autoscaler.

Appears in:

Field Description Default Validation
recommendation RecommendedPodResources The most recently computed amount of resources recommended by the
autoscaler for the controlled pods.
conditions VerticalPodAutoscalerCondition array Conditions is the set of conditions required for this autoscaler to scale its target,
and indicates whether or not those conditions are met.