From 1cd802f2cfa63374827fcf5c65a1ba2287204b54 Mon Sep 17 00:00:00 2001 From: hari-dhanushkodi Date: Thu, 6 Nov 2025 11:40:45 -0500 Subject: [PATCH] chore: update hybrid deployment documentation --- src/langsmith/deploy-hybrid.mdx | 14 ++++++++------ .../deploy-self-hosted-full-platform.mdx | 14 ++++++++++++++ src/langsmith/hybrid.mdx | 17 +++++++---------- 3 files changed, 29 insertions(+), 16 deletions(-) diff --git a/src/langsmith/deploy-hybrid.mdx b/src/langsmith/deploy-hybrid.mdx index f0c8962853..84d2e181b3 100644 --- a/src/langsmith/deploy-hybrid.mdx +++ b/src/langsmith/deploy-hybrid.mdx @@ -22,9 +22,10 @@ The following steps describe how to connect your self-hosted data plane to the m helm repo add kedacore https://kedacore.github.io/charts helm install keda kedacore/keda --namespace keda --create-namespace ``` -2. A valid `Ingress` controller is installed on your cluster. For more information about configuring ingress for your deployment, refer to [Create an ingress for installations](/langsmith/self-host-ingress). -3. You have slack space in your cluster for multiple deployments. `Cluster-Autoscaler` is recommended to automatically provision new nodes. -4. You will need to enable egress to two control plane URLs. The listener polls these endpoints for deployments: +2. A valid `Ingress` controller is installed on your cluster. For more information about configuring ingress for your deployment, refer to [Create an ingress for installations](/langsmith/self-host-ingress). We highly recommend using the modern [Gateway API](/langsmith/self-host-ingress#option-2%3A-gateway-api) in a production setup. +3. If you plan to have the listener watch multiple namespaces, you **MUST** use the [Gateway API](/langsmith/self-host-ingress#option-2%3A-gateway-api) or an [Istio Gateway](/langsmith/self-host-ingress#option-3%3A-istio-gateway) instead of the [Standard Ingress](/langsmith/self-host-ingress#option-1%3A-standard-ingress) resource. A Standard Ingress resource can only route traffic to services in the same namespace, whereas a Gateway or Istio Gateway can route traffic to services across multiple namespaces. +4. You have slack space in your cluster for multiple deployments. `Cluster-Autoscaler` is recommended to automatically provision new nodes. +5. You will need to enable egress to two control plane URLs. The listener polls these endpoints for deployments: - https://api.host.langchain.com - https://api.smith.langchain.com @@ -43,9 +44,10 @@ The following steps describe how to connect your self-hosted data plane to the m Creating a listener from the LangSmith UI does not install the "listener" application in the Kubernetes cluster. 3. A [Helm chart](https://github.com/langchain-ai/helm/tree/main/charts/langgraph-dataplane) is provided to install the necesssary components in your Kubernetes cluster. - - `langgraph-listener`: This is a service that listens to LangChain's [control plane](/langsmith/control-plane) for changes to your deployments and creates/updates downstream CRDs. This is the ["listener" application](/langsmith/data-plane#”listener”-application). + - `langgraph-dataplane-listener`: This is a service that listens to LangChain's [control plane](/langsmith/control-plane) for changes to your deployments and creates/updates downstream CRDs. This is the ["listener" application](/langsmith/data-plane#”listener”-application). - `LangGraphPlatform CRD`: A CRD for LangSmith Deployment. This contains the spec for managing an instance of a LangSmith Deployment. - - `langgraph-platform-operator`: This operator handles changes to your LangSmith CRDs. + - `langgraph-dataplane-operator`: This operator handles changes to your LangSmith CRDs. + - `langgraph-dataplane-redis`: A Redis instance is used by the `langgraph-listener` to manage various tasks (mainly creating and deleting deployments). 4. Configure your `langgraph-dataplane-values.yaml` file. ```bash config: @@ -70,7 +72,7 @@ The following steps describe how to connect your self-hosted data plane to the m - `config.watchNamespaces`: A comma-separated list of Kubernetes namespaces that the `langgraph-listener` deployment will deploy to. This list should match the list of namespaces specified in step 2d. - `config.enableLGPDeploymentHealthCheck`: To disable the Agent Server health check, set this to `false`. - `ingress.hostname`: As part of the deployment workflow, the `langgraph-listener` deployment attempts to call the Agent Server health check endpoint (`GET /ok`) to verify that the application has started up correctly. A typical setup involves creating a shared DNS record or domain for Agent Server deployments. This is not managed by LangSmith. Once created, set `ingress.hostname` to the domain, which will be used to complete the health check. - - `operator.enabled`: There can only be 1 instance of the `langgraph-platform-operator` deployed in a Kubernetes namespace. Set this to `false` if there is already an instance of `langgraph-platform-operator` deployed in the current Kubernetes namespace. + - `operator.enabled`: There can only be 1 instance of the `langgraph-platform-operator` deployed in a Kubernetes namespace. Set this to `false` if there is already an instance of `langgraph-platform-operator` deployed in the current Kubernetes namespace. This should only be relevant if you plan to have multiple installations watch the same namespace. - `operator.createCRDs`: Set this value to `false` if the Kubernetes cluster already has the `LangGraphPlatform CRD` installed. During installation, an error will occur if the CRD is already installed. This situation may occur if multiple listeners are deployed on the same Kubernetes cluster. 5. Deploy `langgraph-dataplane` Helm chart. ```bash diff --git a/src/langsmith/deploy-self-hosted-full-platform.mdx b/src/langsmith/deploy-self-hosted-full-platform.mdx index 70f8750ee7..71112b4f02 100644 --- a/src/langsmith/deploy-self-hosted-full-platform.mdx +++ b/src/langsmith/deploy-self-hosted-full-platform.mdx @@ -80,6 +80,20 @@ As of v0.12.0, the `langgraphPlatform` option is deprecated. Use `config.deploym Your self-hosted infrastructure is now ready to create deployments. +### (Optional) Configuring Additional Data Planes +In addition to the existing data plane already created in the above steps, you can create more data planes that reside in different Kubernetes clusters. + +1. Read through the cluster organization guide in the [hybrid deployment documentation](/langsmith/hybrid#listeners) to understand how to best organize this. +2. Verify the prerequisites mentioned in the [hybrid](/langsmith/deploy-hybrid#prerequisites) section are met for the new cluster. Note that for step 5, you need to enable egress to your [self-hosted LangSmith instance](/langsmith/self-host-usage#configuring-the-application-you-want-to-use-with-langsmith) instead of the managed control plane. +3. Run the following commands against your LangSmith postgres instance to enable this feature: +``` +update organizations set config = config || '{"enable_lgp_listeners_page": true}' where id = ''; +update tenants set config = config || '{"langgraph_remote_reconciler_enabled": true}' where id = ''; +``` +Note down the workspace id you choose as you will need this for future steps. + +4. Follow steps 2-6 in the [hybrid setup guide](/langsmith/deploy-hybrid#setup). The `config.langsmithWorkspaceId` value should be set to the workspace id you noted in prerequisites. + ## Next steps Once your infrastructure is set up, you're ready to deploy applications. See the deployment guides in the [Deployment tab](/langsmith/deployments) for instructions on building and deploying your applications. diff --git a/src/langsmith/hybrid.mdx b/src/langsmith/hybrid.mdx index 47664a06f0..7407bb034d 100644 --- a/src/langsmith/hybrid.mdx +++ b/src/langsmith/hybrid.mdx @@ -22,7 +22,7 @@ Learn more about the [control plane](/langsmith/control-plane), [data plane](/la | Component | Responsibilities | Where it runs | Who manages it | |----------------|------------------|---------------|----------------| | Control plane |
  • UI for creating deployments and revisions
  • APIs for managing deployments
  • Observability data storage
| LangChain's cloud | LangChain | -| Data plane |
  • Listener to sync with control plane
  • Agent Servers (your agents)
  • Backing services (Postgres, Redis, etc.)
| Your cloud | You | +| Data plane |
  • Operator/listener to reconcile deployments
  • Agent Servers (agents/graphs)
  • Backing services (Postgres, Redis, etc.)
| Your cloud | You | When running LangSmith in a hybrid model, you authenticate with a [LangSmith API key](/langsmith/create-account-api-key). @@ -71,7 +71,7 @@ AWS/Azure PrivateLink or GCP Private Service Connect is currently not supported. ## Listeners -In the hybrid option, one or more ["listener" applications](/langsmith/data-plane#listener-application) can run depending on how your LangSmith workspaces and Kubernetes clusters are organized. +In the hybrid option, one or more ["listener" applications](/langsmith/data-plane#”listener”-application) can run depending on how your LangSmith workspaces and Kubernetes clusters are organized. ### Kubernetes cluster organization - One or more listeners can run in a Kubernetes cluster. @@ -80,6 +80,7 @@ In the hybrid option, one or more ["listener" applications](/langsmith/data-plan ### LangSmith workspace organization - A workspace can be associated with one or more listeners. +- A listener can only be associated with one workspace. LangSmith workspace to listener is a one-to-many relationship. - A workspace can only deploy to Kubernetes clusters where all of its listeners are deployed. ## Use Cases @@ -90,16 +91,12 @@ Here are some common listener configurations (not strict requirements): - Cluster `alpha` runs workspace `A` - Cluster `beta` runs workspace `B` -### Separate clusters, with shared “dev” cluster -- Cluster `alpha` runs workspace `A` -- Cluster `beta` runs workspace `B` -- Cluster `dev` runs workspaces `A` and `B` -- Both workspaces have two listeners; cluster `dev` has two listener deployments - ### One cluster, one namespace per workspace - Cluster `alpha`, namespace `1` runs workspace `A` - Cluster `alpha`, namespace `2` runs workspace `B` -### One cluster, single namespace for multiple workspaces +### Separate clusters, with shared “dev” cluster - Cluster `alpha` runs workspace `A` -- Cluster `alpha` runs workspace `B` +- Cluster `beta` runs workspace `B` +- Cluster `dev` runs workspaces `A` and `B` +- Both workspaces have two listeners; cluster `dev` has two listener deployments