2025-12-15 goldilocks vpa

Overview

Goldilocks is a tool that helps you find the right CPU and memory for your pods. It uses the VPA (Vertical Pod Autoscaler) recommender to show you what resources your workloads really need.

The name comes from the fairy tale "Goldilocks and the Three Bears" - not too much, not too little, but just right.

Why use Goldilocks

Setting pod resources is hard. If you set too low, your app crashes. If you set too high, you waste money.

Goldilocks solves this problem:

ProblemHow Goldilocks helps
OOMKilled podsShows memory you actually need
CPU throttlingShows CPU you actually need
Wasted resourcesFinds over-provisioned pods
Guessing gameGives data-based suggestions

How it works

Goldilocks has two parts:

  1. Controller - Watches namespaces with a special label. Creates VPA objects in recommendation mode.
  2. Dashboard - Shows all VPA recommendations in a web UI.

The VPA recommender watches your pods and collects metrics. After some time, it gives you CPU and memory suggestions based on real usage.

flowchart LR
    GC[Goldilocks<br>Controller] -->|Create VPA| VPA[VPA<br>Recommender]
    VPA -->|Get metrics| MS[metrics-server]
    MS -->|Collect usage| D[Deployment]

Goldilocks is installed via goldilocks chart, and VPA is installed via vpa chart. Both charts are from Fairwinds.

Prerequisites

Before you install Goldilocks, you need:

Install

VPA is included as a subchart of Goldilocks. You can install both with a single Helm release.

Installed charts:

helm repo add fairwinds-stable https://charts.fairwinds.com/stable
helm repo update

Checkpoint mode (default)

Stores recommendation data in memory. Simple setup but has limitations:

# values.yaml
vpa:
  enabled: true
  recommender:
    extraArgs:
      v: "4"
      storage: checkpoint
      pod-recommendation-min-cpu-millicores: 15
      pod-recommendation-min-memory-mb: 100
  updater:
    enabled: false
  admissionController:
    enabled: false

Uses Prometheus as history provider. Better for production:

# values.yaml
vpa:
  enabled: true
  recommender:
    extraArgs:
      v: "4"
      storage: prometheus
      prometheus-address: http://kube-prometheus-stack-prometheus.monitoring.svc.cluster.local:9090
      pod-recommendation-min-cpu-millicores: 15
      pod-recommendation-min-memory-mb: 100
  updater:
    enabled: false
  admissionController:
    enabled: false

Run install

Install Goldilocks with VPA subchart:

helm install goldilocks fairwinds-stable/goldilocks \
  --namespace goldilocks \
  --create-namespace \
  -f values.yaml

Check if pods are running:

kubectl get pods -n goldilocks

NAME                                        READY   STATUS    RESTARTS   AGE
goldilocks-controller-xxxxx-xxxxx           1/1     Running   0          1m
goldilocks-dashboard-xxxxx-xxxxx            1/1     Running   0          1m
goldilocks-vpa-recommender-xxxxx-xxxxx      1/1     Running   0          1m

VPA Recommender storage mode

VPA Recommender has two storage modes:

By default, VPA Recommender uses checkpoint mode. ⚠️ This mode has some data retention limits:

This means your recommendations may be inaccurate right after a VPA Recommender pod restart or cluster upgrade.

For production, use prometheus mode:

To use prometheus mode, set the following in your Helm values. This stores history in Prometheus:

# values.yaml for Fairwinds VPA chart
recommender:
  extraArgs:
    v: "4"
    storage: prometheus
    prometheus-address: http://prometheus.monitoring.svc:9090
    history-length: 30d
    pod-recommendation-min-cpu-millicores: 15
    pod-recommendation-min-memory-mb: 100

For all available flags, see VPA flags.md. Key flags and defaults:

Enable namespace

Goldilocks only watches namespaces with the goldilocks.fairwinds.com/enabled=true label. This is the default behavior controlled by the Helm chart.

Add this label to namespaces you want to observe:

kubectl label namespace <your-namespace> goldilocks.fairwinds.com/enabled=true

For example:

kubectl label namespace default goldilocks.fairwinds.com/enabled=true

This gives you full control over which namespaces Goldilocks watches. It prevents VPA objects from being created in system namespaces like kube-system or namespaces that don't need resource tuning.

Auto-created VPA objects

After you enable a namespace, Goldilocks controller automatically creates VPA objects for all Deployments in that namespace.

The flow is:

  1. You label a namespace with goldilocks.fairwinds.com/enabled=true
  2. Goldilocks controller detects the label
  3. Controller creates VPA objects in recommendation mode for each Deployment
  4. VPA recommender collects metrics and generates suggestions
  5. Goldilocks dashboard shows the recommendations

The VPA objects Goldilocks creates look like this:

apiVersion: autoscaling.k8s.io/v1
kind: VerticalPodAutoscaler
metadata:
  name: goldilocks-<deployment-name>
  namespace: <your-namespace>
spec:
  targetRef:
    apiVersion: apps/v1
    kind: Deployment
    name: <deployment-name>
  updatePolicy:
    updateMode: "Off"  # Recommendation only, no auto-update

updateMode: "Off" means VPA only gives recommendations. It does not change your pod resources automatically.

Check created VPA objects:

kubectl get vpa -n <your-namespace>

Access dashboard

Open the Goldilocks dashboard:

kubectl port-forward -n goldilocks svc/goldilocks-dashboard 8080:80

Now go to http://localhost:8080 in your browser.

Goldilocks Dashboard

The dashboard shows:

Read recommendations

The dashboard shows different QoS (Quality of Service) classes:

QoS ClassDescription
Guaranteedrequests = limits (most stable)
Burstablerequests < limits (good balance)

For each class, you see CPU and memory suggestions:

Example output

Here is what you might see:

# Current
resources:
  requests:
    cpu: 100m
    memory: 128Mi
  limits:
    cpu: 500m
    memory: 512Mi

# Goldilocks recommendation (Target)
resources:
  requests:
    cpu: 25m
    memory: 64Mi
  limits:
    cpu: 25m
    memory: 64Mi

In this case, the pod was over-provisioned. Goldilocks found it only needs 25m CPU and 64Mi memory.

Best practices

Troubleshooting

VPA objects not created

Check if the namespace has the correct label:

kubectl get namespace <your-namespace> --show-labels

Check Goldilocks controller logs:

kubectl logs -n goldilocks -l app.kubernetes.io/name=goldilocks,app.kubernetes.io/component=controller

No recommendations showing

VPA needs time to collect data. Wait a few hours and check again.

Make sure metrics-server is working:

kubectl top pods -n <your-namespace>

Dashboard not loading

Check if the dashboard pod is running:

kubectl get pods -n goldilocks -l app.kubernetes.io/component=dashboard

Clean up

To remove Goldilocks and VPA:

helm uninstall goldilocks -n goldilocks
kubectl delete namespace goldilocks

Remove labels from namespaces.

kubectl label namespace <your-namespace> goldilocks.fairwinds.com/enabled-

If Goldilocks is still running, removing the label triggers automatic deletion of VPA objects in that namespace.

Summary

Goldilocks + VPA Recommender helps you with resource right-sizing and cost optimization:

Start with one namespace, review the recommendations, and apply changes step by step.