Scaling and storage

These settings size the API and Brainstore compute for your workload. The defaults are suitable for most deployments. Tune them for high ingestion volume, heavy eval workloads, or cluster capacity constraints.

Configure AWS API ECS services

On AWS, Terraform module v6.0 introduces ECS as the target runtime for the API, split into three services by workload type. Each service scales automatically through Application Auto Scaling, adjusting its running task count between a minimum and maximum based on multiple metrics, including CPU target tracking and event loop timing. The module exposes optional variables to tune per-task size and task counts. The defaults are suitable for most deployments. See Upgrade to Terraform module v6.0 for the migration. 1024 CPU units equal 1 vCPU. braintrust-api handles general API traffic.

Variable	Default
`braintrust_api_cpu`	1024
`braintrust_api_memory`	8192
`braintrust_api_min_count`	3
`braintrust_api_max_count`	50

braintrust-api-ingest handles ingestion paths (/logs3, /otel/v1/traces).

Variable	Default
`braintrust_api_ingest_cpu`	1024
`braintrust_api_ingest_memory`	8192
`braintrust_api_ingest_min_count`	6
`braintrust_api_ingest_max_count`	200

braintrust-api-background handles background paths (evals, function invocation, proxy).

Variable	Default
`braintrust_api_background_cpu`	1024
`braintrust_api_background_memory`	8192
`braintrust_api_background_min_count`	3
`braintrust_api_background_max_count`	50

For example, to raise the ingestion service’s floor for a high-volume deployment:

braintrust_api_ingest_cpu = 2048
braintrust_api_ingest_min_count = 12

Raise braintrust_api_ingest_min_count for deployments with spiky ingestion volume or if you expect a launch that will suddenly increase log traffic, and braintrust_api_background_min_count for heavy eval workloads.

Configure Brainstore fast readers

Fast readers are isolated Brainstore nodes dedicated to serving predictable UI queries (paginated viewers, span and trace lookups), preventing resource-intensive ad-hoc queries from making the UI unresponsive.

GCP and Azure: Fast readers are enabled by default starting in Helm chart v5.0.0. See the configuration reference below.
AWS: Fast readers are enabled by default (2 nodes) starting in Terraform module v5.5.0. On earlier module versions they are disabled by default. Set brainstore_fast_reader_instance_count in your Terraform configuration to control the node count, or set it to 0 to opt out (recommended for sandbox or non-production deployments).

Upgrading to Helm chart v5.0.0 from an earlier version automatically creates fast reader nodes. By default, 2 fast reader nodes are created with the same resource profile as standard reader nodes (CPU: 16, memory: 32Gi). Verify that your cluster has capacity for these additional nodes before upgrading.

If you have custom brainstore.readinessProbe overrides pointing to /status, remove them before upgrading to Helm chart v5.0.0+. The /status readiness endpoint has a bug where it never recovers after a failure, which can permanently mark Brainstore nodes as not ready. Remove any brainstore.readinessProbe or brainstore.fastreader.readinessProbe customizations and rely on the chart defaults.

Configuration reference

Fast readers are configured under the brainstore.fastreader key in your values.yaml. If you have customized brainstore.reader settings, mirror those customizations to brainstore.fastreader.

Key	Default	Description
`brainstore.fastreader.name`	`brainstore-fastreader`	Name of the Deployment, Service, and ConfigMap
`brainstore.fastreader.replicas`	`2`	Number of fast reader pod replicas
`brainstore.fastreader.service.port`	`4000`	Service port
`brainstore.fastreader.service.type`	`ClusterIP`	Kubernetes service type
`brainstore.fastreader.resources.requests.cpu`	`16`	CPU request
`brainstore.fastreader.resources.requests.memory`	`32Gi`	Memory request
`brainstore.fastreader.resources.limits.cpu`	`16`	CPU limit
`brainstore.fastreader.resources.limits.memory`	`32Gi`	Memory limit
`brainstore.fastreader.objectStoreCacheMemoryLimit`	`1Gi`	Object store memory cache limit
`brainstore.fastreader.objectStoreCacheFileSize`	`1000Gi`	Object store file cache size
`brainstore.fastreader.cacheDir`	`/mnt/tmp/brainstore`	Local cache mount path
`brainstore.fastreader.volume.size`	`""`	Ephemeral storage size; required for Azure ACS
`brainstore.fastreader.extraEnvVars`	`[]`	Additional environment variables
`brainstore.fastreader.nodeSelector`	`{}`	Node selector for scheduling
`brainstore.fastreader.tolerations`	`[]`	Pod tolerations
`brainstore.fastreader.affinity`	`{}`	Pod affinity rules

Azure
GCP Autopilot

Azure users must explicitly set brainstore.fastreader.volume.size when using Azure Container Storage (enableAzureContainerStorageDriver: true):

brainstore:
  fastreader:
    volume:
      size: "100Gi"

On GKE Autopilot, set brainstore.fastreader.volume.size to configure ephemeral storage requests. Match the resource profile of your standard reader nodes:

brainstore:
  fastreader:
    resources:
      requests:
        cpu: "16"
        memory: "32Gi"
      limits:
        cpu: "16"
        memory: "32Gi"
    objectStoreCacheFileSize: "900Gi"
    volume:
      size: "1000Gi"

Brainstore resource configuration

This section applies to GCP and Azure deployments using the Helm chart (v5.0.1+). AWS deployments manage Brainstore resources automatically.

Starting in Helm chart v5.0.1, the resources block for each Brainstore component (brainstore.reader, brainstore.writer, brainstore.fastreader) is passed through as-is to the Kubernetes pod spec. You can omit limits entirely, set them to {}, or supply any valid Kubernetes resource spec.

Omitting limits sets the pod QoS class to Burstable, which prevents CPU throttling and allows pods to use available node capacity. This can improve query performance on nodes with spare capacity, but increases the risk of resource contention if multiple pods compete for the same node.

# With limits (Guaranteed QoS — default)
brainstore:
  reader:
    resources:
      requests:
        cpu: "16"
        memory: "32Gi"
      limits:
        cpu: "16"
        memory: "32Gi"

# Without limits (Burstable QoS — allows burst CPU/memory)
brainstore:
  reader:
    resources:
      requests:
        cpu: "16"
        memory: "32Gi"
  writer:
    resources:
      requests:
        cpu: "4"
        memory: "16Gi"
  fastreader:
    resources:
      requests:
        cpu: "16"
        memory: "32Gi"

Auto-derived Brainstore environment variables

As of Helm chart v5.1.0, BRAINSTORE_RESPONSE_CACHE_URI and BRAINSTORE_CODE_BUNDLE_URI are automatically populated from your objectStorage configuration and do not need to be set manually. The chart derives these values as follows:

Cloud	Source key	`BRAINSTORE_RESPONSE_CACHE_URI`	`BRAINSTORE_CODE_BUNDLE_URI`
AWS	`objectStorage.aws.responseBucket` / `objectStorage.aws.codeBundleBucket`	`s3://<responseBucket>/brainstore-cache`	`s3://<codeBundleBucket>`
Azure	`objectStorage.azure.responseContainer` / `objectStorage.azure.codeBundleContainer`	`az://<responseContainer>/brainstore-cache`	`az://<codeBundleContainer>`
GCP	`objectStorage.google.apiBucket`	`gs://<apiBucket>/brainstore-cache`	`gs://<apiBucket>`

If you previously configured these via extraEnvVars, remove those overrides after upgrading to v5.1.0 to avoid conflicts.

Start

Instrument

Observe

Annotate

Evaluate

Deploy

Admin

Best practices

Configure AWS API ECS services

Configure Brainstore fast readers

Configuration reference

Brainstore resource configuration

Auto-derived Brainstore environment variables

​Configure AWS API ECS services

​Configure Brainstore fast readers

​Configuration reference

​Brainstore resource configuration

​Auto-derived Brainstore environment variables

Configure AWS API ECS services

Configure Brainstore fast readers

Configuration reference

Brainstore resource configuration

Auto-derived Brainstore environment variables