feat(goldilocks): install Goldilocks and VPA

vpa/README.md

@@ -0,0 +1,238 @@
+# Vertical Pod Autoscaler (VPA)
+
+Kubernetes resource monitoring and recommendation system:
+
+- **Monitoring-only mode**: Observes workloads without automatic scaling
+- **Prometheus integration**: Metrics collection via Prometheus instead of metrics-server
+- **Resource recommendations**: Generates CPU and memory suggestions based on actual usage
+- **Goldilocks integration**: Works with Goldilocks dashboard for visualization
+- **Non-intrusive**: Does not modify running workloads
+
+## Important Note
+
+**This VPA installation is configured for monitoring and recommendation only**:
+
+- ✅ **Recommender**: Enabled - Analyzes workload metrics and generates recommendations
+- ❌ **Updater**: Disabled - Does NOT automatically apply recommendations to pods
+- ❌ **Admission Controller**: Disabled - Does NOT modify pod resources at creation time
+
+This configuration ensures VPA observes your workloads without affecting them. You can review recommendations and manually adjust resource settings.
+
+## Prerequisites
+
+- Kubernetes cluster (k3s)
+- Prometheus (kube-prometheus-stack) installed
+
+VPA requires Prometheus to collect historical metrics data. Install Prometheus first:
+
+```bash
+just prometheus::install
+```
+
+## Installation
+
+```bash
+just vpa::install
+```
+
+The installation will automatically detect Prometheus and configure VPA to use it as the metrics source.
+
+## Configuration
+
+Environment variables (set in `.env.local` or override):
+
+```bash
+VPA_NAMESPACE=vpa                                                   # VPA namespace
+PROMETHEUS_NAMESPACE=monitoring                                     # Prometheus namespace
+PROMETHEUS_ADDRESS=http://kube-prometheus-stack-prometheus.monitoring.svc:9090  # Prometheus URL
+```
+
+## Usage
+
+### View VPA Status
+
+```bash
+just vpa::status
+```
+
+### View Recommender Logs
+
+```bash
+just vpa::logs-recommender
+```
+
+### View VPA Resources
+
+List all VPA resources across namespaces:
+
+```bash
+kubectl get vpa -A
+```
+
+View specific VPA recommendations:
+
+```bash
+kubectl describe vpa <vpa-name> -n <namespace>
+```
+
+Get recommendation in JSON format:
+
+```bash
+kubectl get vpa <vpa-name> -n <namespace> -o jsonpath='{.status.recommendation}' | jq
+```
+
+### Manual VPA Resource Creation
+
+Create a VPA resource for monitoring:
+
+```yaml
+apiVersion: autoscaling.k8s.io/v1
+kind: VerticalPodAutoscaler
+metadata:
+  name: my-app-vpa
+  namespace: default
+spec:
+  targetRef:
+    apiVersion: apps/v1
+    kind: Deployment
+    name: my-app
+  updatePolicy:
+    updateMode: "Off"  # Monitoring only
+```
+
+Apply with:
+
+```bash
+kubectl apply -f vpa-resource.yaml
+```
+
+## Integration with Goldilocks
+
+VPA alone provides raw recommendations through kubectl commands. For a user-friendly dashboard experience, use Goldilocks:
+
+```bash
+# Install Goldilocks
+just goldilocks::install
+
+# Enable monitoring for specific namespaces
+just goldilocks::enable-namespace <namespace>
+```
+
+Goldilocks automatically creates VPA resources for all workloads in labeled namespaces and presents recommendations in a web dashboard.
+
+## Enabling Automatic Scaling
+
+If you want to enable automatic pod resource updates, modify `values.gomplate.yaml`:
+
+```yaml
+updater:
+  enabled: true
+  replicaCount: 1
+  resources:
+    requests:
+      cpu: 50m
+      memory: 500Mi
+    limits:
+      cpu: 200m
+      memory: 1Gi
+  podMonitor:
+    enabled: true
+
+admissionController:
+  enabled: true
+  replicaCount: 1
+  generateCertificate: true
+  mutatingWebhookConfiguration:
+    failurePolicy: Ignore
+  resources:
+    requests:
+      cpu: 50m
+      memory: 200Mi
+    limits:
+      cpu: 200m
+      memory: 500Mi
+```
+
+Then reinstall:
+
+```bash
+just vpa::install
+```
+
+⚠️ **Warning**: Enabling updater and admission controller will cause VPA to automatically modify pod resources. Test thoroughly before enabling in production.
+
+## VPA Update Modes
+
+VPA supports three update modes (configured in VPA resource):
+
+- **Off** (Monitoring only - Current configuration): Generates recommendations but does not apply them
+- **Initial**: Applies recommendations only when pods are created
+- **Auto**: Automatically applies recommendations by evicting and recreating pods
+
+## Management
+
+### Uninstall
+
+```bash
+just vpa::uninstall
+```
+
+This removes:
+
+- Helm release
+- VPA CRDs
+- Namespace
+
+## Troubleshooting
+
+### Recommender Not Starting
+
+Check Prometheus connectivity:
+
+```bash
+just vpa::logs-recommender
+```
+
+Verify Prometheus is running:
+
+```bash
+kubectl get pods -n monitoring -l app.kubernetes.io/name=prometheus
+```
+
+### No Recommendations Generated
+
+VPA requires workload metrics over time:
+
+- Minimum: A few minutes of runtime
+- Recommended: 24+ hours for accurate recommendations
+
+Verify workload is running and generating metrics:
+
+```bash
+kubectl get pods -n <namespace>
+kubectl top pods -n <namespace>
+```
+
+### VPA Resource Not Created
+
+For Goldilocks-managed VPA resources, ensure:
+
+1. Namespace has label: `goldilocks.fairwinds.com/enabled=true`
+2. Workload is managed by a controller (Deployment, StatefulSet, etc.)
+3. Goldilocks controller is running: `kubectl get pods -n goldilocks`
+
+### Check VPA Components
+
+```bash
+kubectl get pods -n vpa
+```
+
+Should show:
+
+- `vpa-recommender-*`: Running
+
+## References
+
+- [Kubernetes VPA Documentation](https://github.com/kubernetes/autoscaler/tree/master/vertical-pod-autoscaler)
+- [Fairwinds VPA Helm Chart](https://github.com/FairwindsOps/charts/tree/master/stable/vpa)
+- [VPA Design Proposals](https://github.com/kubernetes/design-proposals-archive/blob/main/autoscaling/vertical-pod-autoscaler.md)