chore: update hybrid deployment documentation

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.
     </Info>
 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-dataplane-listener` to manage various tasks (mainly creating and deleting deployments).
 4. Configure your `langgraph-dataplane-values.yaml` file.
     ```bash
       config:
@@ -61,7 +63,7 @@ The following steps describe how to connect your self-hosted data plane to the m
         hostname: "" # specify a hostname that will be configured for all deployments
 
       operator:
-        enabled: true # set this to `false` if the operator is already deployed in the current Kubernetes namespace
+        enabled: true
         createCRDs: true # set this to `false` if the CRD has been previously installed in the current Kubernetes cluster
     ```
     - `config.langsmithApiKey`: The `langgraph-listener` deployment authenticates with LangChain's LangGraph control plane API with the `langsmithApiKey`.
@@ -70,7 +72,6 @@ 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.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
@@ -88,6 +89,14 @@ The following steps describe how to connect your self-hosted data plane to the m
 
     Your hybrid infrastructure is now ready to create deployments.
 
+### Configuring additional data planes in the same cluster
+To create a data plane in a different namespace in the same cluster, repeat the above steps and pass a `-n` option to `helm upgrade` to specify a different namespace.
+
+**When installing multiple data planes in the same cluster, it is very important to follow the rules below:**
+1. The `config.watchNamespaces` list should never intersect with other installations `config.watchNamespaces`. For example, if installation A is watching namespaces `foo,bar`, installation B cannot watch either `foo` or `bar`. Multiple operators or listeners watching the same namespace will lead to unexpected behavior. This means that multiple LangSmith workspaces cannot deploy to the same namespace! Please review the [cluster organization](/langsmith/hybrid#kubernetes-cluster-organization) section to understand this better. 
+2. It is required to 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). Relying on the [standard ingress](/langsmith/self-host-ingress#option-1%3A-standard-ingress) resource can cause conflicts with Ingress objects created by other data planes in the same cluster. Because behavior in these cases depends on the specific ingress controller, this may result in unpredictable or undesired outcomes.
+
+
 ## 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.

src/langsmith/deploy-self-hosted-full-platform.mdx

@@ -81,6 +81,30 @@ As of v0.12.0, the `langgraphPlatform` option is deprecated. Use `config.deploym
 
     Your self-hosted infrastructure is now ready to create deployments.
 
+## (Optional) Configure 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 or the same cluster in a different namespace.
+
+### Prerequisites
+1. Read through the cluster organization guide in the [hybrid deployment documentation](/langsmith/hybrid#listeners) to understand how to best organize this for your use case.
+2. Verify the prerequisites mentioned in the [hybrid](/langsmith/deploy-hybrid#prerequisites) section are met for the new cluster. Note that in step 5 of [this section](/langsmith/deploy-hybrid#prerequisites), 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 https://api.host.langchain.com and https://api.smith.langchain.com.
+3. Run the following commands against your LangSmith Postgres instance to enable this feature. This is the [Postgres instance](/langsmith/kubernetes#validate-your-deployment%3A) that comes with your self-hosted LangSmith setup.
+```
+update organizations set config = config || '{"enable_lgp_listeners_page": true}' where id = '<org id here>';
+update tenants set config = config || '{"langgraph_remote_reconciler_enabled": true}' where id = '<workspace id here>';
+```
+Note down the workspace ID you choose as you will need this for future steps.
+
+### Deploying to a different cluster
+1. 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 the prerequisites.
+2. To deploy more than one data plane to the cluster, follow the rules listed [here](/langsmith/deploy-hybrid#configuring-additional-data-planes-in-the-same-cluster).
+
+### Deploying to a different namespace in the same cluster
+1. You will need to make some modifications to the `langsmith_config.yaml` file you created in step 3 of the [above setup instructions](/langsmith/deploy-self-hosted-full-platform#setup):
+    - Set the `operator.watchNamespaces` field to the current namespace your self-hosted LangSmith instance is running in. This is to prevent clashes with the operator that will be added as part of the new data plane.
+    - It is required to 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). Please adjust your `langsmith_config.yaml` file accordingly.
+2. Run a `helm upgrade` to update your self hosted LangSmith instance with the new config.
+3. 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 the prerequisites. Remember that `config.watchNamespaces` should be set to different namespaces than the one used by the existing data plane!
+
 ## (Optional) Configure authentication for private registries
 
 If your [Agent Server deployments](/langsmith/agent-server) will use images from private container registries (e.g., AWS ECR, Azure ACR, GCP Artifact Registry, private Docker registry), configure image pull secrets. This is a one-time infrastructure configuration that allows all deployments to automatically authenticate with your private registry.

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 |
 |----------------|------------------|---------------|----------------|
 | <Tooltip tip="The LangSmith UI and APIs for managing deployments.">Control plane</Tooltip> | <ul><li>UI for creating deployments and revisions</li><li>APIs for managing deployments</li><li>Observability data storage</li></ul> | LangChain's cloud | LangChain |
-| <Tooltip tip="The runtime environment where your Agent Servers and agents execute.">Data plane</Tooltip> | <ul><li>Listener to sync with control plane</li><li>Agent Servers (your agents)</li><li>Backing services (Postgres, Redis, etc.)</li></ul> | Your cloud | You |
+| <Tooltip tip="The runtime environment where your Agent Servers and agents execute.">Data plane</Tooltip> | <ul><li>Operator/listener to reconcile deployments</li><li>Agent Servers (agents/graphs)</li><li>Backing services (Postgres, Redis, etc.)</li></ul> | Your cloud | You |
 
 When running LangSmith in a hybrid model, you authenticate with a [LangSmith API key](/langsmith/create-account-api-key).
 
@@ -71,15 +71,17 @@ 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.
 - A listener can deploy into one or more namespaces in that cluster.
+- Multiple listeners cannot deploy to the same namespace.
 - Cluster owners are responsible for planning listener layout and Agent Server deployments.
 
 ### 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 +92,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