braintrustdata · brianvans (brianvans) · Jul 23, 2026 · Jul 30, 2026 · Jul 30, 2026 · Jul 31, 2026
diff --git a/braintrust/README.md b/braintrust/README.md
@@ -217,6 +217,31 @@ Size the request for the pod's full local-storage usage:
 
 When you enable `tmpVolume`, make sure the `ephemeralStorage.request` still covers that extra space.
 
+## GKE API Autoscaling
+
+The API can autoscale on GKE using a Horizontal Pod Autoscaler backed by GKE's native `AutoscalingMetric` resource. When enabled, the API scales on three signals - CPU, Node.js event-loop utilization, and mean event-loop delay.
+
+This is underpinned by a **Preview (Pre-GA)** GKE feature. It requires:
+
+- GKE **1.35.1-gke.1396000** or later
+- The Performance HPA profile and the Autoscaling API enabled on the cluster
+- `roles/autoscaling.metricsWriter` granted to all node service accounts
+- The Autoscaling API included in your service perimeter when using VPC Service Controls
+
+See [Expose custom metrics for autoscaling](https://docs.cloud.google.com/kubernetes-engine/docs/how-to/expose-custom-metrics-autoscaling) for more details on `AutoscalingMetric` in GKE.
+
+Enable it in your values:
+
+```yaml
+api:
+  autoscaling:
+    enabled: true
+    minReplicas: 4
+    maxReplicas: 50
+```
+
+When enabled, `api.replicas` is ignored and the HPA controls the replica count.
+
 ## Testing
 
 This Helm chart includes comprehensive automated unit tests.

diff --git a/braintrust/examples/google-autopilot-cel/values.yaml b/braintrust/examples/google-autopilot-cel/values.yaml
@@ -25,6 +25,14 @@ api:
     service:
       networking.gke.io/load-balancer-type: "Internal"
   replicas: 4
+  # Alternatively, autoscale the API on CPU and event-loop metrics.
+  # This is a Preview (Pre-GA) GKE feature requiring 1.35.1-gke.1396000 or later
+  # and the prerequisites documented in the main values.yaml.
+  # See api.autoscaling in the main values.yaml file for more details.
+  # autoscaling:
+  #   enabled: true
+  #   minReplicas: 4
+  #   maxReplicas: 50
   service:
     type: LoadBalancer
     port: 8000

diff --git a/braintrust/examples/google-autopilot/values.yaml b/braintrust/examples/google-autopilot/values.yaml
@@ -33,6 +33,14 @@ api:
     service:
       networking.gke.io/load-balancer-type: "Internal"
   replicas: 4
+  # Alternatively, autoscale the API on CPU and event-loop metrics.
+  # This is a Preview (Pre-GA) GKE feature requiring 1.35.1-gke.1396000 or later
+  # and the prerequisites documented in the main values.yaml.
+  # See api.autoscaling in the main values.yaml file for more details.
+  # autoscaling:
+  #   enabled: true
+  #   minReplicas: 4
+  #   maxReplicas: 50
   # Uncomment the following section to use a different image or tag from the version in the Helm release
   #image:
     #repository: public.ecr.aws/braintrust/standalone-api

diff --git a/braintrust/templates/_helpers.tpl b/braintrust/templates/_helpers.tpl
@@ -39,6 +39,18 @@ Internal cluster URL for the AI Gateway service.
 http://{{ .Values.aiGateway.service.name | default .Values.aiGateway.name }}.{{ include "braintrust.namespace" . }}:{{ .Values.aiGateway.service.port }}
 {{- end -}}
 
+{{/*
+Validate API autoscaling prerequisites (GKE + AutoscalingMetric CRD).
+*/}}
+{{- define "braintrust.apiAutoscaling.validate" -}}
+{{- if ne .Values.cloud "google" }}
+{{- fail "api.autoscaling is currently only supported when cloud is google (GKE)" }}
+{{- end }}
+{{- if not (.Capabilities.APIVersions.Has "autoscaling.gke.io/v1beta1") }}
+{{- fail "api.autoscaling requires the AutoscalingMetric API (autoscaling.gke.io/v1beta1). Use GKE 1.35.1 or later, or verify with: kubectl api-resources | grep autoscalingmetric. For helm template without a cluster, pass --api-versions=autoscaling.gke.io/v1beta1." }}
+{{- end }}
+{{- end -}}
+
 {{/*
 Render Brainstore container resources with provider-specific ephemeral storage.
 

diff --git a/braintrust/templates/api-autoscaling-metric.yaml b/braintrust/templates/api-autoscaling-metric.yaml
@@ -0,0 +1,34 @@
+{{- if .Values.api.autoscaling.enabled }}
+{{- include "braintrust.apiAutoscaling.validate" . }}
+apiVersion: autoscaling.gke.io/v1beta1
+kind: AutoscalingMetric
+metadata:
+  name: {{ .Values.api.name }}
+  namespace: {{ include "braintrust.namespace" . }}
+  {{- with (merge (deepCopy .Values.api.labels) .Values.global.labels) }}
+  labels:
+    {{- toYaml . | nindent 4 }}
+  {{- end }}
+  {{- with .Values.api.annotations.autoscalingMetric }}
+  annotations:
+    {{- toYaml . | nindent 4 }}
+  {{- end }}
+spec:
+  metrics:
+  - pod:
+      selector:
+        matchLabels:
+          app: {{ .Values.api.name }}
+      containers:
+      - endpoint:
+          port: {{ .Values.api.healthServer.port }}
+          path: {{ .Values.api.autoscaling.metricsPath }}
+        metrics:
+        - gauge:
+            # GKE gauge names must match ^[a-z]([-a-z0-9]*[a-z0-9])?
+            name: braintrust-api-event-loop-utilization-ratio
+            prometheusMetricName: braintrust_api_event_loop_utilization_ratio
+        - gauge:
+            name: braintrust-api-event-loop-delay-mean-seconds
+            prometheusMetricName: braintrust_api_event_loop_delay_mean_seconds
+{{- end }}
diff --git a/braintrust/templates/api-deployment.yaml b/braintrust/templates/api-deployment.yaml
@@ -23,7 +23,9 @@ metadata:
     {{- toYaml . | nindent 4 }}
   {{- end }}
 spec:
+  {{- if not .Values.api.autoscaling.enabled }}
   replicas: {{ .Values.api.replicas }}
+  {{- end }}
   strategy:
     type: RollingUpdate
     rollingUpdate:
@@ -81,6 +83,9 @@ spec:
           {{- end }}
           ports:
             - containerPort: {{ .Values.api.service.port }}
+            {{- if .Values.api.autoscaling.enabled }}
+            - containerPort: {{ .Values.api.healthServer.port }}
+            {{- end }}
           resources:
             {{- toYaml .Values.api.resources | nindent 12 }}
           {{- with .Values.api.livenessProbe }}
@@ -156,6 +161,10 @@ spec:
             {{- if .Values.api.extraEnvVars }}
             {{- toYaml .Values.api.extraEnvVars | nindent 12 }}
             {{- end }}
+            {{- if .Values.api.autoscaling.enabled }}
+            - name: ENABLE_PROMETHEUS_METRICS
+              value: "true"
+            {{- end }}
           {{- if or .Values.api.tmpVolume.enabled (and (eq .Values.cloud "azure") .Values.azure.enableAzureKeyVaultDriver) $customCA.enabled }}
           volumeMounts:
             {{- if .Values.api.tmpVolume.enabled }}

diff --git a/braintrust/templates/api-hpa.yaml b/braintrust/templates/api-hpa.yaml
@@ -0,0 +1,48 @@
+{{- if .Values.api.autoscaling.enabled }}
+{{- include "braintrust.apiAutoscaling.validate" . }}
+apiVersion: autoscaling/v2
+kind: HorizontalPodAutoscaler
+metadata:
+  name: {{ .Values.api.name }}
+  namespace: {{ include "braintrust.namespace" . }}
+  {{- with (merge (deepCopy .Values.api.labels) .Values.global.labels) }}
+  labels:
+    {{- toYaml . | nindent 4 }}
+  {{- end }}
+  {{- with .Values.api.annotations.hpa }}
+  annotations:
+    {{- toYaml . | nindent 4 }}
+  {{- end }}
+spec:
+  scaleTargetRef:
+    apiVersion: apps/v1
+    kind: Deployment
+    name: {{ .Values.api.name }}
+  minReplicas: {{ .Values.api.autoscaling.minReplicas }}
+  maxReplicas: {{ .Values.api.autoscaling.maxReplicas }}
+  metrics:
+    - type: Resource
+      resource:
+        name: cpu
+        target:
+          type: Utilization
+          averageUtilization: {{ .Values.api.autoscaling.cpu.targetAverageUtilization }}
+    - type: Pods
+      pods:
+        metric:
+          name: autoscaling.gke.io|{{ .Values.api.name }}|braintrust-api-event-loop-utilization-ratio
+        target:
+          type: AverageValue
+          averageValue: {{ .Values.api.autoscaling.eventLoopUtilization.targetAverageValue | quote }}
+    - type: Pods
+      pods:
+        metric:
+          name: autoscaling.gke.io|{{ .Values.api.name }}|braintrust-api-event-loop-delay-mean-seconds
+        target:
+          type: AverageValue
+          averageValue: {{ .Values.api.autoscaling.eventLoopDelayMean.targetAverageValue | quote }}
+  {{- with .Values.api.autoscaling.behavior }}
+  behavior:
+    {{- toYaml . | nindent 4 }}
+  {{- end }}
+{{- end }}
diff --git a/braintrust/tests/api-autoscaling-crd_test.yaml b/braintrust/tests/api-autoscaling-crd_test.yaml
@@ -0,0 +1,17 @@
+suite: test API autoscaling CRD requirement
+templates:
+  - api-hpa.yaml
+# Do not advertise autoscaling.gke.io here — this suite asserts the fail path.
+tests:
+  - it: should fail when AutoscalingMetric API is unavailable
+    template: api-hpa.yaml
+    values:
+      - __fixtures__/base-values.yaml
+    set:
+      cloud: google
+      api.autoscaling.enabled: true
+    release:
+      namespace: "braintrust"
+    asserts:
+      - failedTemplate:
+          errorPattern: "api\\.autoscaling requires the AutoscalingMetric API \\(autoscaling\\.gke\\.io/v1beta1\\)"