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

First, install VPA. You only need the recommender part:

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

helm install vpa fairwinds-stable/vpa \
  --namespace vpa \
  --create-namespace \
  --set recommender.enabled=true \
  --set updater.enabled=false \
  --set admissionController.enabled=false \
  --set metrics-server.enabled=false

The updater and admission controller are disabled. This setup only provides CPU and memory recommendations, not auto-updates. metrics-server is also disabled because it is already installed as a separate chart.

Check if VPA is running. The vpa-recommender pod analyzes pod resource usage from metrics-server and generates CPU and memory recommendations:

kubectl get pods -n vpa

NAME                                        READY   STATUS    RESTARTS   AGE
vpa-recommender-5c4f8d8b9f-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:

Install Goldilocks

Now install Goldilocks:

helm install goldilocks fairwinds-stable/goldilocks \
  --namespace goldilocks \
  --create-namespace

Check if Goldilocks is 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

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:

helm uninstall goldilocks -n goldilocks
kubectl delete namespace goldilocks

To remove VPA:

helm uninstall vpa -n vpa
kubectl delete namespace vpa

Remove labels from namespaces:

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

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.