VPA switches to 0.4.0

Change default version
Update docs

vertical-pod-autoscaler/README.md

@@ -12,49 +12,119 @@ It can both down-scale pods that are over-requesting resources, and also up-scal
 
 Autoscaling is configured with a
 [Custom Resource Definition object](https://kubernetes.io/docs/concepts/api-extension/custom-resources/)
-called [VerticalPodAutoscaler](https://github.com/kubernetes/autoscaler/blob/master/vertical-pod-autoscaler/pkg/apis/autoscaling.k8s.io/v1beta1/types.go).
-It allows to specify which pods should be under vertically autoscaled as well as if/how the
+called [VerticalPodAutoscaler](https://github.com/kubernetes/autoscaler/blob/master/vertical-pod-autoscaler/pkg/apis/autoscaling.k8s.io/v1beta2/types.go).
+It allows to specify which pods should be vertically autoscaled as well as if/how the
 resource recommendations are applied.
 
 To enable vertical pod autoscaling on your cluster please follow the installation
 procedure described below.
 
-
 # Installation
 
-### Notice on switching from alpha to beta (<0.3.0 to >=0.3.0)
+The current default version is Vertical Pod Autoscaler 0.4.0
+
+**NOTE:** version 0.4 requires at least Kubernetes 1.11 to work (needs certain
+Custom Resource Definition capabilities). With older Kubernetes versions we
+suggest using the [latest 0.3 version](https://github.com/kubernetes/autoscaler/blob/vpa-release-0.3/vertical-pod-autoscaler/README.md) 
+
+### Notice on switching to v1beta2 version (0.3.X to >=0.4.0)
 
-Between versions 0.2.x and 0.3.x there is an alpha to beta switch which includes
-a change of VPA apiVersion from `poc.autoscaling.k8s.io/v1alpha1` to `autoscaling.k8s.io/v1beta1`.
-The safest way to switch is to use `vpa-down.sh` script to tear down
-the old installation of VPA first. This will delete your old VPA objects that
-have been defined with `poc.autoscaling.k8s.io/v1alpha1` apiVersion.
-Then use `vpa-up.sh` to bring up the new version of VPA and create you VPA
-objects from the scratch, passing apiVersion `autoscaling.k8s.io/v1beta1`
-(See [example](./examples/hamster.yaml)).
+In 0.4.0 we introduced a new version of the API - `autoscaling.k8s.io/v1beta2`.
+Full API is accessible [here](https://github.com/kubernetes/autoscaler/blob/master/vertical-pod-autoscaler/pkg/apis/autoscaling.k8s.io/v1beta2/types.go).
 
-If you want to migrate your objects between versions, you can use the [object conversion script](./hack/convert-alpha-objects.sh).
-It will save your VPA objects into temporary yaml files with the new apiVersion.
-After running the script:
-1. disable alpha VPA via vpa-down.sh script
-1. enable beta VPA via vpa-up.sh script
-1. re-create VPA objects following the instructions from the script.
+The change introduced is in the way you express which pods should be scaled by a
+given Vertical Pod Autoscaler. In short we are moving from label selectors to
+controller references. This change is introduced due to two main reasons:
+* Use of selectors is prone to misconfigurations - e.g. VPA objects targeting
+all pods, overlaping VPA objects
+* This change aligns VPA with [Horizontal Pod Autoscaler
+  API](https://github.com/kubernetes/api/blob/master/autoscaling/v1/types.go)
 
-**NOTE: ** The script is experimental. Please check that the yaml files it generates are correct.
-When switching between alpha and beta, VPA recommendations will NOT be kept and there
-will be a brief disruption period until the new VPA computes new recommendations.
+Let's see an example ilustrating the change:
 
-To use the script:
+**[DEPRECATED]** In `v1beta1` pods to scale by VPA are specified by a
+[kubernetes label selector](https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/#label-selectors).
+
+```yaml
+apiVersion: "autoscaling.k8s.io/v1beta1"
+kind: VerticalPodAutoscaler
+metadata:
+  name: hamster-vpa-deprecated
+spec:
+  selector: # selector is the deprecated way
+    matchLabels:
+      app: hamster
 ```
-./hack/convert-alpha-objects.sh
+
+**[RECOMMENDED]** In `v1beta2` pods to scale by VPA are specified by a
+target reference. This target will usually be a Deployment, as configured in the
+example below.
+
+```yaml
+apiVersion: "autoscaling.k8s.io/v1beta2"
+kind: VerticalPodAutoscaler
+metadata:
+  name: hamster-vpa
+spec:
+  targetRef:
+    apiVersion: "extensions/v1beta1"
+    kind:       Deployment
+    name:       hamster
+```
+
+The target object can be a well known controller (Deployment, ReplicaSet, DaemonSet, StatefulSet etc.)
+or any object that implements the scale subresource. VPA uses ScaleStatus to
+retrieve the pod set controlled by this object.
+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 this controller.
+
+See complete examples:
+* [v1beta2](./examples/hamster.yaml)
+* [v1beta1](./examples/hamster-deprecated.yaml)
+
+You can perform a 0.3 to 0.4 upgrade without losing your VPA objects.
+The recommended way is as follows:
+
+1. Run `./hack/vpa-apply-upgrade.sh` - this will restart your VPA installation with
+a new version, add the new API and keep all your VPA objects.
+1. Your `v1beta1` objects will be marked as deprecated but still work
+1. Switch your VPA definition to
+`apiVersion: "autoscaling.k8s.io/v1beta2"`
+1. Modify the VPA spec to:
+```yaml
+spec:
+  # Note the empty selector field - this is needed to remove previously defined selector
+  selector:
+  targetRef:
+    apiVersion: "extensions/v1beta1"
+    kind:       "Deployment"
+    name:       "<deployment_name>" # This matches the deployment name
 ```
+5. Kubectl apply -f the above
+
+You can also first try the new API in the `"Off"` mode.
+
+### Notice on switching from alpha to beta (<0.3.0 to 0.4.0+)
+
+**NOTE:** We highly recommend switching to the 0.4.X version. However,
+for instructions on switching to 0.3.X see the [0.3 version README](https://github.com/kubernetes/autoscaler/blob/vpa-release-0.3/vertical-pod-autoscaler/README.md)
+
+Between versions 0.2.x and 0.4.x there is an alpha to beta switch which includes
+a change of VPA apiVersion. The safest way to switch is to use `vpa-down.sh`
+script to tear down the old installation of VPA first. This will delete your old
+VPA objects that have been defined with `poc.autoscaling.k8s.io/v1alpha1`
+apiVersion. Then use `vpa-up.sh` to bring up the new version of VPA and create
+your VPA objects from the scratch, passing apiVersion
+`autoscaling.k8s.io/v1beta2` and switching from selector to targetRef, as
+described in the prevous section.
 
 ### Prerequisites
 
-* It is strongly recommended to use Kubernetes 1.9 or greater.
-  Your cluster must support MutatingAdmissionWebhooks, which are enabled by default
-  since 1.9 ([#58255](https://github.com/kubernetes/kubernetes/pull/58255)).
-  Read more about [VPA Admission Webhook](./pkg/admission-controller/README.md#running).
+* VPA version 0.4+ requires Kubernetes 1.11. For older versions see [latest 0.3 version](https://github.com/kubernetes/autoscaler/blob/vpa-release-0.3/vertical-pod-autoscaler/README.md)
 * `kubectl` should be connected to the cluster you want to install VPA in.
 * The metrics server must be deployed in your cluster. Read more about [Metrics Server](https://github.com/kubernetes-incubator/metrics-server).
 * If you are using a GKE Kubernetes cluster, you will need to grant your current Google
@@ -97,16 +167,15 @@ with the API server.
 After [installation](#installation) the system is ready to recommend and set
 resource requests for your pods.
 In order to use it you need to insert a *Vertical Pod Autoscaler* resource for
-each logical group of pods that have similar resource requirements.
-We recommend to insert a *VPA* per each *Deployment* you want to control
-automatically and use the same label selector as the *Deployment* uses.
+each controller that you want to have automatically computed resource requirements.
+This will be most commonly a **Deployment**.
 There are three modes in which *VPAs* operate:
 
 * `"Auto"`: VPA assigns resource requests on pod creation as well as updates
   them on existing pods using the preferred update mechanism. Currently this is
   equivalent to `"Recreate"` (see below). Once restart free ("in-place") update
   of pod requests is available, it may be used as the preferred update mechanism by
-  the `"Auto"` mode. **NOTE:** This feature of VPA is experimental and may cause downtime 
+  the `"Auto"` mode. **NOTE:** This feature of VPA is experimental and may cause downtime
   for your applications.
 * `"Recreate"`: VPA assigns resource requests on pod creation as well as updates
   them on existing pods by evicting them when the requested resources differ significantly
@@ -130,7 +199,7 @@ kubectl create -f examples/hamster.yaml
 
 The above command creates a deployment with 2 pods, each running a single container
 that requests 100 millicores and tries to utilize slightly above 500 millicores.
-The command also creates a VPA config with selector that matches the pods in the deployment.
+The command also creates a VPA config pointing at the deployment.
 VPA will observe the behavior of the pods and after about 5 minutes they should get
 updated with a higher CPU request
 (note that VPA does not modify the template in the deployment, but the actual requests
@@ -146,14 +215,15 @@ You may need to add more nodes or adjust examples/hamster.yaml to use less CPU.*
 ### Example VPA configuration
 
 ```
-apiVersion: autoscaling.k8s.io/v1beta1
+apiVersion: autoscaling.k8s.io/v1beta2
 kind: VerticalPodAutoscaler
 metadata:
   name: my-app-vpa
 spec:
-  selector:
-    matchLabels:
-      app: my-app
+  targetRef:
+    apiVersion: "extensions/v1beta1"
+    kind:       Deployment
+    name:       my-app
   updatePolicy:
     updateMode: "Auto"
 ```
@@ -242,4 +312,4 @@ kubectl delete clusterrolebinding myname-cluster-admin-binding
 * [Design
   proposal](https://github.com/kubernetes/community/blob/master/contributors/design-proposals/autoscaling/vertical-pod-autoscaler.md)
 * [API
-  definition](pkg/apis/autoscaling.k8s.io/v1beta1/types.go)
+  definition](pkg/apis/autoscaling.k8s.io/v1beta2/types.go)

vertical-pod-autoscaler/deploy/admission-controller-deployment.yaml

@@ -14,7 +14,7 @@ spec:
       serviceAccountName: vpa-admission-controller
       containers:
       - name: admission-controller
-        image: k8s.gcr.io/vpa-admission-controller:0.3.1
+        image: k8s.gcr.io/vpa-admission-controller:0.4.0
         imagePullPolicy: Always
         env:
         - name: NAMESPACE

vertical-pod-autoscaler/deploy/recommender-deployment.yaml

@@ -20,7 +20,7 @@ spec:
       serviceAccountName: vpa-recommender
       containers:
       - name: recommender
-        image: k8s.gcr.io/vpa-recommender:0.3.1
+        image: k8s.gcr.io/vpa-recommender:0.4.0
         imagePullPolicy: Always
         resources:
           limits:

vertical-pod-autoscaler/deploy/updater-deployment.yaml

@@ -20,7 +20,7 @@ spec:
       serviceAccountName: vpa-updater
       containers:
       - name: updater
-        image: k8s.gcr.io/vpa-updater:0.3.1
+        image: k8s.gcr.io/vpa-updater:0.4.0
         imagePullPolicy: Always
         resources:
           limits:

vertical-pod-autoscaler/examples/hamster-deprecated.yaml

@@ -0,0 +1,34 @@
+# This config creates a deployment with two pods, each requesting 100 millicores
+# and trying to utilize slightly above 500 millicores (repeatedly using CPU for
+# 0.5s and sleeping 0.5s).
+# It also creates a corresponding Vertical Pod Autoscaler that adjusts the requests.
+# Note that the update mode is left unset, so it defaults to "Auto" mode.
+apiVersion: "autoscaling.k8s.io/v1beta1"
+kind: VerticalPodAutoscaler
+metadata:
+  name: hamster-vpa-deprecated
+spec:
+  selector:
+    matchLabels:
+      app: hamster
+---
+apiVersion: extensions/v1beta1
+kind: Deployment
+metadata:
+  name: hamster
+spec:
+  replicas: 2
+  template:
+    metadata:
+      labels:
+        app: hamster
+    spec:
+      containers:
+      - name: hamster
+        image: k8s.gcr.io/ubuntu-slim:0.1
+        resources:
+          requests:
+            cpu: 100m
+            memory: 50Mi
+        command: ["/bin/sh"]
+        args: ["-c", "while true; do timeout 0.5s yes >/dev/null; sleep 0.5s; done"]

vertical-pod-autoscaler/examples/hamster.yaml

@@ -3,14 +3,15 @@
 # 0.5s and sleeping 0.5s).
 # It also creates a corresponding Vertical Pod Autoscaler that adjusts the requests.
 # Note that the update mode is left unset, so it defaults to "Auto" mode.
-apiVersion: "autoscaling.k8s.io/v1beta1"
+apiVersion: "autoscaling.k8s.io/v1beta2"
 kind: VerticalPodAutoscaler
 metadata:
   name: hamster-vpa
 spec:
-  selector:
-    matchLabels:
-      app: hamster
+  targetRef:
+    apiVersion: "extensions/v1beta1"
+    kind:       Deployment
+    name:       hamster
 ---
 apiVersion: extensions/v1beta1
 kind: Deployment

vertical-pod-autoscaler/examples/redis-deprecated.yaml

@@ -0,0 +1,32 @@
+apiVersion: autoscaling.k8s.io/v1beta1
+kind: VerticalPodAutoscaler
+metadata:
+  name: redis-vpa
+spec:
+  selector:
+    matchLabels:
+      app: redis
+---
+apiVersion: apps/v1beta2 # for versions before 1.8.0 use apps/v1beta1
+kind: Deployment
+metadata:
+  name: redis-master
+spec:
+  selector:
+    matchLabels:
+      app: redis
+  replicas: 3
+  template:
+    metadata:
+      labels:
+        app: redis
+    spec:
+      containers:
+      - name: master
+        image: k8s.gcr.io/redis:e2e  # or just image: redis
+        resources:
+          requests:
+            cpu: 100m
+            memory: 100Mi
+        ports:
+        - containerPort: 6379

vertical-pod-autoscaler/examples/redis.yaml

@@ -1,11 +1,12 @@
-apiVersion: autoscaling.k8s.io/v1beta1
+apiVersion: autoscaling.k8s.io/v1beta2
 kind: VerticalPodAutoscaler
 metadata:
   name: redis-vpa
 spec:
-  selector:
-    matchLabels:
-      app: redis
+  targetRef:
+    apiVersion: "extensions/v1beta1"
+    kind:       Deployment
+    name:       redis-master
 ---
 apiVersion: apps/v1beta2 # for versions before 1.8.0 use apps/v1beta1
 kind: Deployment

vertical-pod-autoscaler/hack/vpa-process-yaml.sh

@@ -32,7 +32,7 @@ if [ $# -eq 0 ]; then
 fi
 
 DEFAULT_REGISTRY="k8s.gcr.io"
-DEFAULT_TAG="0.3.1"
+DEFAULT_TAG="0.4.0"
 
 REGISTRY_TO_APPLY=${REGISTRY-$DEFAULT_REGISTRY}
 TAG_TO_APPLY=${TAG-$DEFAULT_TAG}