Migrating between API versions of VerticalPodAutoscaler

Beta

This is a Beta release of Vertical Pod Autoscaler; it is provided free of charge in GKE Release 1.11.3. This feature may be charged for in the future. This feature is not covered by any SLA or deprecation policy and might be subject to backward-incompatible changes.

This page explains how to migrate VerticalPodAutoscaler objects from API versions v1beta1 to v1beta2.

Before you begin

To prepare for this task, perform the following steps:

• Ensure that you have enabled the Google Kubernetes Engine API.
Enable Google Kubernetes Engine API
• Ensure that you have installed the Cloud SDK.
• Set your default project ID:

  gcloud config set project [PROJECT_ID]

• If you are working with zonal clusters, set your default compute zone:

  gcloud config set compute/zone [COMPUTE_ZONE]

• If you are working with regional clusters, set your default compute region:

  gcloud config set compute/region [COMPUTE_REGION]

• Update gcloud to the latest version:

  gcloud components update

Note: You can override these default settings in gcloud commands using the --project, --zone, and --region operational flags.

Enabling vertical pod autoscaling for a cluster

To create a new cluster with vertical pod autoscaling enabled, enter this command:

gcloud beta container clusters create [CLUSTER_NAME] --enable-vertical-pod-autoscaling

where [CLUSTER_NAME] is a name that you choose for your cluster.

To enable vertical pod autoscaling for an existing cluster, enter this command:

cloud beta container clusters update [CLUSTER-NAME] --enable-vertical-pod-autoscaling

where [CLUSTER_NAME] is the name of the cluster.

Introducing v1beta2 API

Vertical pod autoscaling is a Beta feature introduced in version 1.11 of GKE. The v1beta1 API uses a label selector to specify which Pods belong to a certain VerticalPodAutoscaler. We gathered user feedback and decided to modify the API due to usability reasons:

• Use of selectors is prone to misconfigurations. For example, a VerticalPodAutoscaler objects targeting all Pods in a cluster, or Pods belonging to more than one VerticalPodAutoscaler object.
• The most common use case, by far, is for a VerticalPodAutoscaler to target an entire Deloyment.
• This change aligns VPA with the HorizontalPodAutoscaler API.

With the v1beta2 API, a VerticalPodAutoscaler object points directly at a controller, for examplem a Deployment or a DaemonSet.

Note: The v1beta2 API is available in Google Kubernetes Engine version 1.11 starting with version 1.11.8 and in all clusters with version 1.12.6 or higher. The v1beta1 API is deprecated in version 1.12 and will be removed with 1.13.

Migrating from v1beta1 to v1beta2 API

This guide shows how to safely migrate a Deployment scaled by a VerticalPodAutoscaler from v1beta1 to v1beta2.

Here is a manifest for a Deployment:

apiVersion: extensions/v1beta1
kind: Deployment
metadata:
  name: deployment-name
  labels:
    label: vpa-label
spec:
  replicas: 2
  template:
    metadata:
      labels:
        label: vpa-label
    spec:
      containers:
      - {...}

In v1beta1 you would scale it by specifying a selector to match all Pods in the Deployment:

apiVersion: autoscaling.k8s.io/v1beta1
kind: VerticalPodAutoscaler
metadata:
  name: vpa-name
spec:
  selector:
    matchLabels:
      label: vpa-label
  updatePolicy:
    updateMode: {...}

In v1beta2, the VerticalPodAutoscaler targets the Deployment directly:

apiVersion: autoscaling.k8s.io/v1beta2 # different API version
kind: VerticalPodAutoscaler
metadata:
  name: vpa-name
spec:
  targetRef:
    apiVersion: "extensions/v1beta1"
    kind:       Deployment
    name:       deployment-name
  updatePolicy:
    updateMode: {...}

Save the v1beta2 manifest to a file named vpa-v1beta2.yaml.

If your updateMode is set to "Off", you can run kubectl apply -f vpa-v1beta2.yaml. The VerticalPodAutoscaler will keep recommendations during the switch.

If you have actuation turned on (updateMode "Initial", "Auto" or "Recreate"), fo the migration in multiple steps:

1. Create a v1beta2 VerticalPodAutoscaler manifest with a new name and with updateMode: "Off":

apiVersion: autoscaling.k8s.io/v1beta2
kind: VerticalPodAutoscaler
metadata:
  name: vpa-name-new # Different name
spec:
  targetRef:
    apiVersion: "extensions/v1beta1"
    kind:       Deployment
    name:       deployment-name
  updatePolicy:
    updateMode: "Off" # Recommendation only mode.

1. Save this manifest as vpa-v1beta1-off.yaml.

2. Create the new VerticalPodAutoscaler object:

   kubectl apply -f vpa-v1beta1-off.yaml

3. Wait for recommendation to be populated and compare it to the one on the original VerticalPodAutoscaler object.

4. Once you are satisfied that the recommendations match, delete the v1beta1 VerticalPodAutoscaler object:

   kubectl delete vpa-name

5. Update the new VerticalPodAutoscaler to your original update strategy. For example for updateMode: "Auto"

   apiVersion: autoscaling.k8s.io/v1beta2
   kind: VerticalPodAutoscaler
   metadata:
     name: vpa-name-new
   spec:
     targetRef:
       apiVersion: "extensions/v1beta1"
       kind:       Deployment
       name:       deployment-name
     updatePolicy:
       updateMode: "Auto" # Mode switched to auto
   

6. Save this manifest as vpa-v1beta1-final.yaml

7. Apply the new configuration kubectl apply -f vpa-v1beta1-final.yaml

Reference

This is the v1beta1 API reference. You can also check the v1beta2 reference

VerticalPodAutoscaler v1beta1 autoscaling.k8s.io

Fields
	TypeMeta API group, version, and kind.
metadata	ObjectMeta Standard object metadata.
spec	VerticalPodAutoscalerSpec The desired behavior of the VerticalPodAutoscaler.
status	VerticalPodAutosclerStatus The most recently observed status of the VerticalPodAutoscaler.

VerticalPodAutoscalerSpec v1beta1 autoscaling.k8s.io

Fields
selector	LabelSelector A label query that determines the set of Pods controlled by the VerticalPodAutoscaler.
updatePolicy	PodUpdatePolicy Specifies whether recommended updates are applied when a Pod is started and whether recommended updates are applied during the life of a Pod.
resourcePolicy	PodResourcePolicy Specifies policies for how CPU and memory requests are adjusted for individual containers.

VerticalPodAutoscalerList v1beta1 autoscaling.k8s.io

Fields
	TypeMeta API group, version, and kind.
metadata	ObjectMeta Standard object metadata.
items	VerticalPodAutoscaler array A list of VerticalPodAutoscaler objects.

PodUpdatePolicy v1beta1 autoscaling.k8s.io

Fields
updateMode	string Specifies whether recommended updates are applied when a Pod is started and whether recommended updates are applied during the life of a Pod. Possible values are "Off", "Initial", "Recreate", and "Auto".

PodResourcePolicy v1beta1 autoscaling.k8s.io

Fields
containerPolicies	ContainerResourcePolicy array An array of resource policies for individual containers.

ContainerResourcePolicy v1beta1 autoscaling.k8s.io

Fields
containerName	string The name of the container that the policy applies to. If not specified, the policy serves as the default policy.
mode	ContainerScalingMode Specifies whether recommended updates are applied to the container when it is started and whether recommended updates are applied during the life of the container. Possible values are "Off" and "Auto".
minAllowed	ResourceList Specifies the minimum CPU request and memory request allowed for the container.
maxAllowed	ResourceList Specifies the maximum CPU request and memory request allowed for the container.

VerticalPodAutoscalerStatus v1beta1 autoscaling.k8s.io

Fields
recommendation	RecommendedPodResources The most recently recommended CPU and memory requests.
conditions	VerticalPodAutoscalerCondition array Describes the current state of the VerticalPodAutoscaler.

RecommendedPodResources v1beta1 autoscaling.k8s.io

Fields
containerRecommendation	RecommendedContainerResources array An array of resource recommendations for individual containers.

RecommendedContainerResources v1beta1 autoscaling.k8s.io

Fields
containerName	string The name of the container that the recommendation applies to.
target	ResourceList The recommended CPU request and memory request for the container.
lowerBound	ResourceList The minimum recommended CPU request and memory request for the container. This amount is not guaranteed to be sufficient for the application to be stable. Running with smaller CPU and memory requests is likely to have a significant impact on performance or availability.
upperBound	ResourceList The maximum recommended CPU request and memory request for the container. CPU and memory requests higher than these values are likely to be wasted.
uncappedTarget	ResourceList The most recent resource recommendation computed by the autoscaler, based only on actual resource usage, not taking into account the ContainerResourcePolicy. May differ from the bounded recommendation if the actual resource usage causes the target to violate the ContainerResourcePolicy. This field is used only as status indication; it will not affect actual resource assignment.

VerticalPodAutoscalerCondition v1beta1 autoscaling.k8s.io

Fields
type	VerticalPodAutoscalerConditionType The type of condition being described. Possible values are "RecommendationProvided", "LowConfidence", "NoPodsMatched", and "FetchingHistory".
status	ConditionStatus The status of the condition. Possible values are True, False, and Unknown.
lastTransitionTime	Time The last time the condition made a transition from one status to another.
reason	string The reason for the last transition from one status to another.
message	string A human-readable string that gives details about the last transition from one status to another.