Upgrade an installation

Downgrades are not officially supported. LangSmith upgrades may include database migrations and other changes that are not backward-compatible. If you need to roll back to a previous version, contact technical support via the Support Portal for guidance.

If you don’t have the repo added, run the following command to add it:

helm repo add langchain https://langchain-ai.github.io/helm/

Update your local helm repo

helm repo update

Update your helm chart config file with any updates that are needed in the new version. These will be detailed in the release notes for the new version.

Run the following command to upgrade the chart (replace version with the version you want to upgrade to):

If you are using a namespace other than the default namespace, you will need to specify the namespace in the helm and kubectl commands by using the -n <namespace flag.

Find the latest version of the chart. You can find this in the LangSmith Helm Chart GitHub repository or by running the following command:

helm search repo langchain/langsmith --versions

You should see output similar to this:

NAME                             	CHART VERSION	APP VERSION	DESCRIPTION
langchain/langsmith              	0.17.2       	0.17.30    	Helm chart to deploy the langsmith application ...
langchain/langsmith              	0.17.1       	0.17.30    	Helm chart to deploy the langsmith application ...
langchain/langsmith              	0.17.0       	0.17.29    	Helm chart to deploy the langsmith application ...
langchain/langsmith              	0.16.41      	0.16.70    	Helm chart to deploy the langsmith application ...
langchain/langsmith              	0.16.40      	0.16.70    	Helm chart to deploy the langsmith application ...

Choose the version you want to upgrade to (generally the latest version is recommended) and note the version number:

If your installation is more than one major version behind the latest chart, upgrade one major version at a time. Do not skip major versions. Repeat this upgrade procedure for each intervening major version before upgrading to the latest supported version.

For example, to upgrade from 0.15 to 0.17, first upgrade to the latest 0.16 chart, then upgrade to the latest 0.17 chart.

helm upgrade <release-name> langchain/langsmith --version <version> --values <path-to-values-file> --wait --debug

Verify that the upgrade was successful:

helm status <release-name>

All pods should be in the Running state. Verify that ClickHouse is running and that both migrations jobs have completed.

kubectl get pods
NAME                                     READY   STATUS      RESTARTS   AGE
langsmith-backend-95b6d54f5-gz48b        1/1     Running     0          15h
langsmith-pg-migrations-d2z6k            0/1     Completed   0          5h48m
langsmith-ch-migrations-gasvk            0/1     Completed   0          5h48m
langsmith-clickhouse-0                   1/1     Running     0          26h
langsmith-frontend-84687d9d45-6cg4r      1/1     Running     0          15h
langsmith-hub-backend-66ffb75fb4-qg6kl   1/1     Running     0          15h
langsmith-playground-85b444d8f7-pl589    1/1     Running     0          15h
langsmith-queue-d58cb64f7-87d68          1/1     Running     0          15h

Validate your deployment

1. Run kubectl get services

   Output will be similar to:

   NAME                         TYPE           CLUSTER-IP       EXTERNAL-IP     PORT(S)                      AGE
   kubernetes                   ClusterIP      172.20.0.1       <none>          443/TCP                      27d
   langsmith-backend            ClusterIP      172.20.22.34     <none>          1984/TCP                     21d
   langsmith-clickhouse         ClusterIP      172.20.117.62    <none>          8123/TCP,9000/TCP            21d
   langsmith-frontend           LoadBalancer   172.20.218.30    <external ip>   80:30093/TCP,443:31130/TCP   21d
   langsmith-platform-backend   ClusterIP      172.20.232.183   <none>          1986/TCP                     21d
   langsmith-playground         ClusterIP      172.20.167.132   <none>          3001/TCP                     21d
   langsmith-postgres           ClusterIP      172.20.59.63     <none>          5432/TCP                     21d
   langsmith-redis              ClusterIP      172.20.229.98    <none>          6379/TCP                     20d
   

2. Curl the external ip of the langsmith-frontend service:

   curl <external ip>/api/info
   {"version":"0.5.7","license_expiration_time":"2033-05-20T20:08:06","batch_ingest_config":{"scale_up_qsize_trigger":1000,"scale_up_nthreads_limit":16,"scale_down_nempty_trigger":4,"size_limit":100,"size_limit_bytes":20971520}}
   

   Check that the version matches the version you upgraded to.

3. Visit the external IP for the langsmith-frontend service on your browser. The LangSmith UI should be visible and operational.

   

Upgrade from v16 to v17

Chart v17 changes the values for SmithDB, sandboxes, and Engine. Update your values file before you run helm upgrade. Chart v17 fails to render the SmithDB, sandbox, and Engine values below until you change them. If you deploy with the Terraform modules, follow the upgrade steps in the AWS, GCP, or Azure deploy guide, which apply these changes to the module’s values files.

Downgrading from chart v17 to v16 is not supported. Back up the database before you upgrade.

• SmithDB: Move smithdb.migration.deployment to smithdb.migration.job. With smithdb.enabled: true, move the flat autoscaling keys (enabled, minReplicas, maxReplicas, and the rest) on query, ingestion, mutations, runRules, statsQuery, and compactionWorker under autoscaling.hpa.*. For compactionWorker, you can use autoscaling.keda.* instead, but enable only one scaler. For the cache volume changes, see Cache storage.

• Sandboxes: Chart v17 removes the bundled JuiceFS CSI driver, and sandbox-host mounts JuiceFS itself. Chart v17 ignores a leftover sandboxes.juicefs.csi block, and its validation then fails with sandboxes.juicefs.redis.metaURL is required when sandboxes.enabled is true and sandboxes.juicefs.existingSecretName is not set. Move the settings:

  • sandboxes.juicefs.csi.existingSecretName becomes sandboxes.juicefs.existingSecretName. The Secret keeps its keys.
  • The cache options in sandboxes.juicefs.csi.mountPodPatch move to sandboxes.juicefs.hostMount. cacheDirs sets the host paths for the JuiceFS cache and defaults to /var/cache/juicefs. If you override it, list at least one absolute path. Set other JuiceFS options in mountOptions in the --flag=value form, and do not set --cache-dir there. The default cache size drops from 300 GiB (cache-size=307200) to 50 GiB (--cache-size=51200).
  • Move the IRSA or Workload Identity annotation from sandboxes.juicefs.csi.node.serviceAccount.annotations to sandboxes.sandboxHost.serviceAccount.annotations. On GKE, sandbox-host runs on the host network, and GKE does not give Workload Identity to host-network pods, so the annotation serves only the juicefs-format Job. Also grant the sandbox node pool’s service account roles/storage.objectAdmin on the bucket, limited by an IAM condition to the JuiceFS prefix. Without that grant, the mount gets 403 from Cloud Storage.

  Before the upgrade, drain the JuiceFS volumes while the CSI driver still runs. Otherwise the old sandbox-host pods stay in Terminating. With the default release name:

  kubectl delete -n langsmith deployment.apps/langsmith-sandbox-host
  kubectl delete -n langsmith persistentvolumeclaim/smithbox-juicefs-csi
  kubectl delete -n langsmith persistentvolumeclaim/smithbox-juicefs-csi-host
  kubectl get pods -n langsmith | grep juicefs   # wait until only juicefs-csi-* pods remain
  

  Running sandboxes stop. Their data stays in object storage and Redis, because both chart v16 PersistentVolumes use the Retain reclaim policy.

• Engine: With Engine enabled, set engine.usageSigningSecret to a value of at least 32 characters (generate one with openssl rand -hex 32), or, when you use config.existingSecretName, add an engine_usage_signing_secret key to that Secret instead. The default engine.intelligenceBaseUrl changes to https://beacon.langchain.com/intelligence, which records usage only. To keep running Engine on LangSmith Intelligence models, as on chart v16, keep https://beacon.aws.langchain.com/intelligence and select LangSmith Intelligence under Settings > Engine > Model providers. For details, see LangSmith Engine on Self-hosted.

---

Connect these docs to your agent of choice via MCP for real-time answers.

Edit this page on GitHub or file an issue.