Skip to main content
SmithDB is optional and available in beta. These requirements apply only if you choose to enable SmithDB on an existing Kubernetes installation.
SmithDB adds three infrastructure dependencies to an existing LangSmith self-hosted deployment: a PostgreSQL metastore, object storage, and node-local SSD cache capacity.
These are integration requirements and practical recommendations, not a prescribed cloud architecture. Provider examples cover AWS (EKS), GCP (GKE), and Azure (AKS). Minimum LangSmith version depends on cloud. See Check cloud support.

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.
AlloyDB Auth Proxy sidecar configuration is not included in this guide. Provide a reachable PostgreSQL 18 or later instance and an empty dedicated database. If you need Auth Proxy support, contact LangChain through the Support Portal.

Metastore Secret

Create an existing Kubernetes Secret in the LangSmith release namespace containing the database host, name, username, and password. Map its keys through smithdb.config.metastore.
Configure the chart to use the corresponding keys:
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.
Use private object-storage connectivityKeep SmithDB traffic off public egress paths to avoid unnecessary data-transfer and NAT gateway 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.
Configure access so SmithDB can list the bucket and read, write, and delete objects. Prefer IRSA on EKS, Workload Identity on GKE, or Azure Workload Identity on AKS over static credentials. Block public access and require encrypted transport.
ServiceAccount selectionSmithDB workloads share smithdb.serviceAccount.
  • Default: The chart creates <HELM_RELEASE>-smithdb.
  • Custom: Set name to create a differently named account.
  • Existing: Set create: false and name. Configure workload identity externally.
Workload identity must target the selected namespace and name. With create: false, name is required. Otherwise pods use the default ServiceAccount.
Do not expire objects independently of SmithDB’s data lifecycle. Deleting live objects can make data unavailable. This bucket is separate from optional LangSmith blob storage, which stores payloads and attachments for the broader LangSmith deployment.

Migration source-bucket access

When migration and LangSmith blob storage are enabled, grant smithdb.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):

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 allocatable ephemeral-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. Keep metastoreMigration unpinned so the pre-install hook can run on any available node.
Confirm the intended labels, taints, scheduler-visible capacity, pod placement, and cache filesystem:
Common symptoms are pods remaining pending when requests exceed allocatable capacity, slow cache I/O when 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, grant s3: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 for system:serviceaccount:<NAMESPACE>:<HELM_RELEASE>-smithdb. Pod Identity uses an external association and no annotation.

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_NAME and KarpenterNodeRole-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.
Applying these manifests creates provisioning configuration. EC2 nodes launch when matching SmithDB pods require capacity.
In this 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.
Other provisioners must provide equivalent labels, taints, Kubernetes-visible ephemeral storage, and disruption behavior. With custom AMIs, bootstrap must format and mount instance-store devices for kubelet and container-runtime storage.

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.
Example only: Replace uppercase placeholders. Choose instance type and capacity based on your sizing baseline and regional availability. Match AMI_TYPE to the instance architecture. For example, i8g.4xlarge uses AL2023_ARM_64_STANDARD.
AWS CLI requires an EC2 launch template for the nodeadm configuration.

GCP

A common GCP mapping is GKE Standard, AlloyDB or another compatible PostgreSQL service, Cloud Storage, Workload Identity, and Local SSD-backed ephemeral storage. Grant roles/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

Use a single-region bucket to avoid data replication costs and provide predictable tail latencies.
Grant a Google service account access to the bucket, then allow serviceAccount:<PROJECT_ID>.svc.id.goog[<NAMESPACE>/<HELM_RELEASE>-smithdb] to impersonate it.

Provision GKE Local SSD nodes

Use Local SSD-backed ephemeral storage, which integrates with emptyDir, container layers, and scheduler capacity. Raw block Local SSD does not provide the same integration.
This example only configures Local SSD and workload scheduling. Configure node IAM, networking, security settings, and scaling separately. Values are illustrative. For regional clusters, node_count applies per zone.
Supported disk counts and machine types vary by zone and machine generation. Verify availability in every zone used by the node pool.

Azure

Azure (AKS) support for SmithDB requires LangSmith 0.17. Do not enable SmithDB on AKS at 0.16.
A common Azure mapping is AKS, Azure Database for PostgreSQL, Azure Blob Storage, Workload Identity, and the VM temporary disk as Kubernetes ephemeral storage. Grant Storage 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.

Provision AKS nodes with a temporary disk

AKS does not attach a separate Local SSD volume for emptyDir. 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.
This example only configures the temporary-disk cache pool and workload scheduling. Configure node IAM, networking, security settings, and scaling separately. Values are illustrative. Confirm that Standard_L16s_v3, or an equivalent SKU with enough temporary-disk capacity, is available in the target region.

See also