Migrating between API versions of VerticalPodAutoscaler

Beta

This product or feature is covered by the Pre-GA Offerings Terms of the Google Cloud Terms of Service. Pre-GA products and features might have limited support, and changes to pre-GA products and features might not be compatible with other pre-GA versions. For more information, see the launch stage descriptions.

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

Before you begin

Before you start, make sure you have performed the following tasks:

• Ensure that you have enabled the Google Kubernetes Engine API.
Enable Google Kubernetes Engine API
• Ensure that you have installed the Cloud SDK.

Set up default gcloud settings using one of the following methods:

• Using gcloud init, if you want to be walked through setting defaults.
• Using gcloud config, to individually set your project ID, zone, and region.

Using gcloud init

If you receive the error One of [--zone, --region] must be supplied: Please specify location, complete this section.

1. Run gcloud init and follow the directions:

   gcloud init

   If you are using SSH on a remote server, use the --console-only flag to prevent the command from launching a browser:

   gcloud init --console-only

2. Follow the instructions to authorize gcloud to use your Google Cloud account.
3. Create a new configuration or select an existing one.
4. Choose a Google Cloud project.
5. Choose a default Compute Engine zone for zonal clusters or a region for regional or Autopilot clusters.

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

Using gcloud config

• 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 Autopilot or 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 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 new cluster.

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

gcloud beta container clusters update cluster-name --enable-vertical-pod-autoscaling

where cluster-name is the name of the existing 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 Deployment.
• This change aligns VPA with the HorizontalPodAutoscaler API.

With the v1beta2 API, a VerticalPodAutoscaler object points directly at a controller, for example 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 sample manifest for a Deployment:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: deployment-name
  labels:
    label: vpa-label
spec:
  replicas: 2
  selector:
    matchLabels:
      label: vpa-label
  template:
    metadata:
      labels:
        label: vpa-label
    spec:
      containers:
      - {...}

In v1beta1, you scale the VerticalPodAutoscaler 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: "apps/v1"
    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 the following command:

kubectl apply -f vpa-v1beta2.yaml

The VerticalPodAutoscaler will keep recommendations during the switch.

If your updateMode is turned on ("Initial", "Auto" or "Recreate"), perform the migration in multiple steps:

1. Create a v1beta2 VerticalPodAutoscaler manifest with a new name (vpa-name-new), and with the updateMode field set to "Off":

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

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

3. Create the new VerticalPodAutoscaler object:

   kubectl apply -f vpa-v1beta1-off.yaml
   

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

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

   kubectl delete vpa-name
   

6. 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: "apps/v1"
       kind:       Deployment
       name:       deployment-name
     updatePolicy:
       updateMode: "Auto" # Mode switched to auto
   

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

8. 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.