Requirements
Before enabling SmithDB, provide:- A dedicated, empty PostgreSQL database for the SmithDB metastore. Do not use the PostgreSQL database that stores the rest of LangSmith operational data.
- A dedicated object-storage bucket for SmithDB durable data.
- A Kubernetes cluster that can provision enough local SSD-backed ephemeral storage for SmithDB caches.
- Private network connectivity to the database and object store, plus credentials or workload identity for both.
PostgreSQL metastore
The metastore holds SmithDB catalog and coordination data. Start with an empty database. The SmithDB migration Job owns its schema. SmithDB requires PostgreSQL 18 or later on a service reachable from the cluster. Common choices include Amazon RDS for PostgreSQL, Aurora PostgreSQL, AlloyDB, Cloud SQL for PostgreSQL, and Azure Database for PostgreSQL.Metastore Secret
Create an existing Kubernetes Secret in the LangSmith release namespace containing the database host, name, username, and password. Map its keys throughsmithdb.config.metastore.
Metastore Secret and Helm values
Metastore Secret and Helm values
DB_NAME may be any dedicated, empty PostgreSQL database, such as smithdb. The chart does not require these exact Secret key names. The Helm values map your chosen names.Object storage
Object storage is SmithDB’s durable data layer. Use a bucket reserved for SmithDB data. A regional bucket near the Kubernetes cluster is a practical starting point for lower latency and transfer costs.- AWS: Use an S3 Gateway VPC endpoint on the cluster’s private route tables.
- GCP: Use Private Google Access with private Google APIs DNS.
- Azure: Use a private endpoint for Blob Storage.
smithdb.serviceAccount.- Default: The chart creates
<HELM_RELEASE>-smithdb. - Custom: Set
nameto create a differently named account. - Existing: Set
create: falseandname. Configure workload identity externally.
create: false, name is required. Otherwise pods use the default ServiceAccount.Migration source-bucket access
When migration and LangSmith blob storage are enabled, grantsmithdb.serviceAccount read access to the existing LangSmith blob-storage bucket in addition to its access to the SmithDB destination bucket.
Prefer Workload Identity for GCS blob access. If LangSmith must use GCS HMAC keys, set smithdb.migration.deployment.extraEnv to force the S3-compatible source and reference the existing LangSmith secret (blob_storage_access_key / blob_storage_access_key_secret):
GCS HMAC migration configuration
GCS HMAC migration configuration
Local SSD cache
Local SSD is volatile cache capacity. Losing a pod or node can discard the cache without deleting the durable object-storage copy. Attaching an SSD is not sufficient. Its filesystem must back Kubernetes local ephemeral storage, and usable capacity must appear as node allocatableephemeral-storage. SmithDB consumes that capacity through emptyDir volumes.
Use scheduling controls to keep SmithDB cache workloads on SSD-backed nodes. Size nodes with headroom above pod requests, images, logs, and Kubernetes reservations.
Schedule SmithDB workloads
Place query, ingestion, compaction worker, and migration on the local SSD pool. Place compaction and cluster manager on the general compute pool. Node-pool labels and taints must match the Helm selectors and tolerations. KeepmetastoreMigration unpinned so the pre-install hook can run on any available node.
Helm scheduling values
Helm scheduling values
Verify local SSD capacity
Verify local SSD capacity
emptyDir uses the boot disk, and evictions when the node lacks headroom.Provider notes
AWS
A common AWS mapping is EKS, RDS for PostgreSQL, S3, IRSA, and EC2 instance store. Scope S3 access to bucket listing and location plus object read, write, delete, and multipart operations. For migration source reads, grants3:ListBucket and s3:GetObject on the LangSmith blob-storage bucket.
Configure S3 workload identity
Choose IRSA or EKS Pod Identity. IRSA requires the role annotation and trust forsystem:serviceaccount:<NAMESPACE>:<HELM_RELEASE>-smithdb. Pod Identity uses an external association and no annotation.
IRSA Helm values
IRSA Helm values
Provision EKS nodes with Karpenter
Karpenter is a recommended way to provision SmithDB capacity on EKS, but it is not required. Other node provisioners must produce the same labels, taints, and Kubernetes-visible ephemeral-storage capacity. Install Karpenter v1 and its CRDs by following the Karpenter EKS guide. Before applying the example below:- Replace
CLUSTER_NAMEandKarpenterNodeRole-CLUSTER_NAME. - Tag the selected subnets and security group with
karpenter.sh/discovery: CLUSTER_NAME, or replace the selectors with tags or IDs used by your environment. - Confirm the node IAM role and EKS access entry are configured for Karpenter-provisioned nodes.
Karpenter EC2NodeClass and NodePool example
Karpenter EC2NodeClass and NodePool example
instanceStorePolicy: RAID0 makes local NVMe available as node ephemeral storage. The smithdb-instance-store NodePool requires at least 800 GiB and consolidates only when empty, avoiding unnecessary churn of nodes with warm caches.Provision EKS managed node groups
For cases where Karpenter is unavailable, these examples use EKS Managed Node Groups to configure instance-store NVMe as RAID0 and apply the label and taint used by the Helm scheduling values.AWS CLI
AWS CLI
nodeadm configuration.eksctl 0.199.0+
eksctl 0.199.0+
Terraform
Terraform
GCP
A common GCP mapping is GKE Standard, AlloyDB or another compatible PostgreSQL service, Cloud Storage, Workload Identity, and Local SSD-backed ephemeral storage. Grantroles/storage.objectAdmin, or an equivalent custom role, on the SmithDB destination bucket. For migration source reads, grant roles/storage.objectViewer on the LangSmith blob-storage bucket.
Configure Cloud Storage workload identity
serviceAccount:<PROJECT_ID>.svc.id.goog[<NAMESPACE>/<HELM_RELEASE>-smithdb] to impersonate it.
GKE Workload Identity Helm values
GKE Workload Identity Helm values
Provision GKE Local SSD nodes
Use Local SSD-backed ephemeral storage, which integrates withemptyDir, container layers, and scheduler capacity. Raw block Local SSD does not provide the same integration.
GKE Local SSD node-pool example
GKE Local SSD node-pool example
Terraform GKE Local SSD node-pool example
Terraform GKE Local SSD node-pool example
Azure
A common Azure mapping is AKS, Azure Database for PostgreSQL, Azure Blob Storage, Workload Identity, and the VM temporary disk as Kubernetes ephemeral storage. GrantStorage Blob Data Contributor on the SmithDB storage account. For migration source reads, grant Storage Blob Data Reader on the LangSmith blob-storage account.
Configure Blob Storage workload identity
smithdb.config.objectStore.bucket is the Blob container name. azure.accountName is required. Leave accessKeySecretKey empty when using Workload Identity.
Annotate the SmithDB ServiceAccount with the user-assigned managed identity client ID. Add the azure.workload.identity/use: "true" label to every SmithDB workload.
AKS Workload Identity Helm values
AKS Workload Identity Helm values
Provision AKS nodes with a temporary disk
AKS does not attach a separate Local SSD volume foremptyDir. Set kubelet-disk-type to Temporary so kubelet, container images, logs, and emptyDir use the VM temporary disk. That disk is local SSD or NVMe and is wiped on deallocate or host move.
Use a VM size with enough temporary-disk capacity for SmithDB cache requests. Standard_L16s_v3 is an L-series size with a large local NVMe temporary disk. A SKU without a suitable temporary disk leaves emptyDir too small even if AKS accepts the node pool. Confirm allocatable ephemeral-storage after the pool is ready.
Azure CLI node-pool example
Azure CLI node-pool example
Terraform AKS node-pool example
Terraform AKS node-pool example

