.png&w=640&q=75){kind=small}
This article covers how to migrate a self-hosted LangSmith (with LangSmith deployments enabled) from one Kubernetes cluster to another, and the key gotchas to avoid.
Migrating LangSmith data
Use the data migration tool (https://github.com/langchain-ai/langsmith-data-migration-tool) to move LangSmith-managed resources between instances. Point it at your old and new cluster URLs. It supports migrating:
- Datasets
- Experiments
- Annotation queues
- Prompts
- Project rules
- Charts
Note: trace migration is not currently supported.
Redis: do not share across clusters
This is the most common pitfall during cluster migration.
Each LangSmith installation must have its own dedicated Redis instance. Do not point your new cluster at the same external Redis instance used by the old cluster.
Why: The langsmith-listener continuously polls the control plane for deployment changes and enqueues tasks to Redis. The langsmith-operator pulls from that same queue and reconciles Kubernetes resources. If two installations share one Redis instance, the old cluster's listener will keep consuming tasks and attempt to create or update deployments in the old cluster, even after you intend to be running on the new one.
This is true even if you use different Redis DB numbers. DB-level sharing is only supported between Agent Server deployments within a single LangSmith installation, not across separate installations.
Recommended migration order
1. Set up the new cluster using the standard installation guide (https://docs.langchain.com/langsmith/kubernetes), with a fresh, dedicated Redis instance.
2. Before or immediately after the new cluster's langsmith-listener comes online, scale down the listener and operator in the old cluster:
kubectl scale deployment langsmith-listener --replicas=0
kubectl scale deployment langsmith-operator --replicas=0
This prevents both clusters from consuming the same queue and routing deployments to the wrong place.
3. Run the data migration tool to copy LangSmith resources from the old instance to the new one.
4. Verify the new cluster's listener is healthy and reconciling before decommissioning the old cluster. Look for the log line Reconciling projects... appearing every ~10 seconds in the langsmith-listener pod logs.
5. Update DNS/ingress to point to the new cluster.
6. Decommission the old cluster once traffic has fully shifted.
What you do not need to migrate
Redis data is entirely ephemeral. It holds task queues, streaming pub/sub channels, and short-lived retry counters. None of it needs to be migrated. All durable state (threads, runs, checkpoints, long-term memory) lives in Postgres.
Reference
- Self-hosted LangSmith on Kubernetes: https://docs.langchain.com/langsmith/kubernetes
- Configure for scale: https://docs.langchain.com/langsmith/self-host-scale
- Connect to an external Redis: https://docs.langchain.com/langsmith/self-host-external-redis
- Data migration tool: https://github.com/langchain-ai/langsmith-data-migration-tool
- Practical Q&A - deploying on Kubernetes: https://kb.langchain.com/articles/3969485352-deploying-langsmith-langgraph-on-kubernetes-a-practical-q-a
- Best practices for scaling self-hosted LangSmith: https://kb.langchain.com/articles/5142502915-best-practices-for-scaling-self-hosted-langsmith