kube-startup-cpu-boost borrows CPU for the cold start and gives it back

A temporary CPU raise with an automatic rollback

The problem this solves is narrow and real. Some workloads need far more CPU than they need in steady state, and the extra is only needed for the first seconds or minutes. A JVM application loading classes, warming caches and connecting to its database is the case the README names, and it says the primary use cases are workloads requiring extra CPU during the startup phase, typically JVM based applications.

The controller raises the CPU resource requests and limits of the affected Pods while the workload starts, and once the workload is up and running the resources are set back to their original values. The word temporarily is doing real work in that description, because the whole value proposition is that you do not have to permanently size your Pods for the worst case of startup.

The implementation is a Kubernetes operator with a custom resource, a mutating admission webhook and a restore path. The mutation happens at admission time, so the boosted values are what the Pod is created with, and the restore happens later by the operator, once a duration condition is met.

The project is hosted under the google organisation and the README says plainly that this is not an officially supported Google product. That line matters for adoption decisions, and it also tells you what kind of code to expect: an operator built by Google engineers for their own workloads, published without the support commitment that would come with a commercial product.

The licence is Apache 2.0, with the usual LICENSE file, and the repository is a Go project built with controller-runtime.

In-place resize is what makes the rollback possible

The reason the controller can put the CPU back without disturbing running Pods is the In-place Resource Resize for Kubernetes Pods feature, introduced in Kubernetes 1.27. The README credits that feature explicitly, and says it allows reverting a workload's CPU resource requests and limits back to their original values without the need to recreate the Pods.

That last clause is the entire point. Without in-place resize, lowering a Pod's resources means deleting it and letting the controller create a replacement, which is a restart, which defeats the purpose of a startup optimisation. With it, the resources of a running container change underneath the process.

The version requirement follows directly. The prerequisites say Kubernetes 1.33 or newer is required, and for older clusters of version 1.27 or above you can enable the InPlacePodVerticalScaling feature gate. Below 1.27 the mechanism does not exist, and the project does not claim to support it.

That is a hard boundary to check before anything else, because the whole controller is built on a cluster capability rather than on a workaround. The go.mod file shows the Kubernetes libraries pinned at the 0.37.1 line for api, apimachinery and client-go, and controller-runtime at 0.25.2, so the controller is built against recent Kubernetes APIs rather than an older compatibility surface.

The second mechanism is the admission webhook. The increase in resources is achieved via a Mutating Admission Webhook, and when configured the webhook also removes CPU resource limits if present. That is worth pausing on: a boosted Pod is not just given more CPU, it is given more CPU without a ceiling, and the ceiling comes back later with the restore.

Writing the boost: a StartupCPUBoost object per workload

The interface is a custom resource in the autoscaling.x-k8s.io API group, created in the namespace of the workload you want to boost. The example in the README shows the full shape:

   apiVersion: autoscaling.x-k8s.io/v1alpha1
   kind: StartupCPUBoost
   metadata:
     name: boost-001
     namespace: demo
   selector:
     matchExpressions:
     - key: app.kubernetes.io/name
       operator: In
       values: ["spring-demo-app"]
   spec:
     resourcePolicy:
       containerPolicies:
       - matchContainers:
           type: ExactName
           value: spring-rest-jpa
         percentageIncrease:
           value: 50
     durationPolicy:
       podCondition:
         type: Ready
         status: "True"

Three separate selectors appear here, and each one narrows who gets boosted. The metadata namespace says where the object lives and therefore which workload namespace it governs. The selector with matchExpressions picks the Pods by label, here the app.kubernetes.io/name label with value spring-demo-app. The containerPolicies entry then picks which container inside those Pods is affected, using an ExactName matcher for spring-rest-jpa, so a sidecar or a second container is not touched by accident.

The policy is then expressed twice. percentageIncrease with value 50 raises the CPU of the matched container by half. durationPolicy with a podCondition of type Ready and status True says the boost lasts until the Pod reports Ready, and the README says the resources are increased by 50% until that Pod condition becomes True.

The API version is v1alpha1, which is a signal about how settled the surface is. The feature list also names the alternative shapes: a fixed target instead of a percentage increase, a fixed time instead of a Pod condition, and a container matcher as an alternative to exact names.

Three install paths, and the same controller under each

Installation is offered in three flavours, and all of them deploy the same components into the kube-startup-cpu-boost-system namespace.

The quickest is a single apply of the release manifest:

kubectl apply -f https://github.com/google/kube-startup-cpu-boost/releases/download/v0.21.3/manifests.yaml

The second is Kustomize, where you write your own kustomization file and pipe the rendered output into kubectl:

cat <<EOF > kustomization.yaml
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
resources:
- https://github.com/google/kube-startup-cpu-boost?ref=v0.21.3
EOF
kubectl kustomize | kubectl apply -f -

The third is Helm, against a self-hosted chart repository at google.github.io/kube-startup-cpu-boost:

helm repo add kube-startup-cpu-boost https://google.github.io/kube-startup-cpu-boost
helm repo update
helm install --create-namespace -n kube-startup-cpu-boost-system kube-startup-cpu-boost kube-startup-cpu-boost/kube-startup-cpu-boost

High availability is a first class option rather than an afterthought. The controller supports multi-replica deployments and needs leader election enabled, which the README says is enabled by default through the LEADER_ELECTION=true environment variable. With Helm you scale replicas and add a PodDisruptionBudget, with two replicas and minAvailable of one:

helm install \
  --create-namespace -n kube-startup-cpu-boost-system \
  kube-startup-cpu-boost kube-startup-cpu-boost/kube-startup-cpu-boost \
  --set controllerManager.replicas=2 \
  --set controllerManager.pdb.create=true \
  --set controllerManager.pdb.minAvailable=1

With Kustomize you uncomment the HA component in config/default/kustomization.yaml instead, which increases replicas and adds the PodDisruptionBudget.

The chart lives in the charts/ directory of the repository, and releases are published as a pair: a version tag such as v0.21.3 and a matching chart tag such as v0.21.3-chart.

Boosting again after a container restart

One behaviour deserves its own section, because it changes what the feature means in production.

Since version 0.21.0, the operator can re-apply CPU boosts to existing Pods when their containers restart, so the boost is applied across the whole lifecycle of the workload rather than only at the first startup. The mechanism is that the operator keeps watching Pods even after the CPU resources have been restored to their original values, and it detects restarts by observing container status changes and reacting to the terminated state.

That is the right design for a long-lived JVM service, because a container that restarts on an out-of-memory kill or an OOM kill is exactly the case that needs the extra CPU again to get past startup. Without this, a restarted container would come back with its steady-state sizing and could fail again, in a loop.

The feature is opt-in through an environment variable: the BOOST_ON_RESTART environment variable has to be set to true. That is worth noting because it means the default install does not re-boost, and a cluster that needs the behaviour will fail to get it unless someone sets the variable in the deployment manifest.

The rest of the policy surface is the same shape as the resource policy: a label selector for the target Pods, a container matcher for which container inside them, a percentage increase or a fixed target for the amount, and a fixed time or a Pod condition for the duration.

The side effects the README warns about

The README carries a warning box, and it deserves to be quoted in substance. It says that while kube-startup-cpu-boost significantly reduces container cold-start times, dynamically mutating pod resources at runtime can introduce unintended side effects in specific environments, and it points to a Side Effects section for detail. The section itself was not in the excerpt available here, which means the specifics of that warning are something you have to read on the project page before deploying.

What the warning points at is real even without the section. Removing the CPU limit during the boost means a container that goes into a hot loop can use every core on the node until the restore happens, and in a cluster with a shared node pool that is a noisy neighbour problem you are introducing deliberately. A namespace that had no limit policy now briefly has none.

There is a second consequence in the design. The restore path restores the values the Pod was originally created with, which means the boost is expressed as a deviation from the admission-time value. If a workload is redeployed with different resources while a boost is in flight, the original values the operator remembers and the values in the new spec can disagree, and the README does not describe how that is resolved.

The third is operational. The controller is a webhook in the API server path, and a mutating admission webhook that adds or removes resource fields is in the request path of every Pod creation in the cluster, even for workloads you did not intend to boost, since the webhook has to evaluate every Pod and then decide not to change it.

The licensing is Apache 2.0 and the build is a plain Go container image, built from golang:1.26 with CGO disabled and published as ghcr.io/google/kube-startup-cpu-boost. The project also carries a demo-app/ directory, hack/ and scripts/ directories, a release-please configuration and a goreleaser setup, and the Makefile pins the envtest Kubernetes version for the local test environment.

Editorial conclusion

Adopt kube-startup-cpu-boost if you run JVM or similar slow-to-warm workloads, you can live with a mutating webhook in your API server, and your cluster is on Kubernetes 1.33 or you can enable the InPlacePodVerticalScaling feature gate. Do not adopt it if you are on an older cluster that cannot enable that gate, if you cannot accept runtime mutation of pod resources, or if you need a supported product, since the README states this is not an officially supported Google product. Before you deploy, read the Side Effects section of the README, confirm the cluster version and feature gate, and verify that removing CPU limits during the boost does not conflict with your quota and policy settings.

Frequently asked questions

Official sources

1. google/kube-startup-cpu-boost on GitHub
2. Issues
3. License: Apache-2.0
4. README
5. Releases