chore: update hybrid deployment documentation #1315

hari-dhanushkodi · 2025-11-06T16:45:12Z

Overview

Updating the listener/hybrid docs after many support cases with customers. Adding the following:

Recommend using gateway for production deploys - ingress will not work if listener is watching multiple namespaces
Remove confusing use cases in the listener use cases section
Add documentation for fully self hosted customers to connect additional data planes
Update hybrid deploy section to include the redis instance we bring up that the listener uses

Checklist

I have read the contributing guidelines
I have tested my changes locally using docs dev
All code examples have been tested and work correctly
I have used root relative paths for internal links
I have updated navigation in src/docs.json if needed
I have gotten approval from the relevant reviewers
(Internal team members only / optional) I have created a preview deployment using the Create Preview Branch workflow

Additional notes

katmayb

lgtm from a docs perpective @hari-dhanushkodi! I merged a new section on the self-hosted-full-platform page yesterday where you have placed yours, so you'll have to resolve that conflict — Feel free to order your new optional section and the one I added, how you think is best.

katmayb · 2025-11-06T16:57:32Z

src/langsmith/deploy-hybrid.mdx

-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.


Suggested change

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.

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.

katmayb · 2025-11-06T17:00:33Z

src/langsmith/deploy-hybrid.mdx

    - `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).


Should the langgraph-listener mention on line 50 be updated to langgraph-dataplane-listener too?

katmayb · 2025-11-06T17:02:11Z

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


    Your self-hosted infrastructure is now ready to create deployments.

+### (Optional) Configuring Additional Data Planes


Suggested change

### (Optional) Configuring Additional Data Planes

### (Optional) Configure additional data planes

katmayb · 2025-11-06T17:03:27Z

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

+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.


Suggested change

Note down the workspace id you choose as you will need this for future steps.

Note down the workspace ID you choose as you will need this for future steps.

katmayb · 2025-11-06T17:03:42Z

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

+```
+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.


Suggested change

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.

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.

katmayb · 2025-11-06T17:05:52Z

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


    Your self-hosted infrastructure is now ready to create deployments.

+### (Optional) Configuring Additional Data Planes


I merged a section on this page yesterday, right in the same place, so you'll have to resolve the merge conflict. (Sorry!)

andrewnguonly · 2025-11-06T20:01:40Z

src/langsmith/deploy-hybrid.mdx

    </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).


Side question: Is this deployment still called langgraph-dataplane-listener? Or did we change it to langgsmith-dataplane-listener?

andrewnguonly · 2025-11-06T20:03:17Z

src/langsmith/deploy-hybrid.mdx

    - `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.


langgraph-platform-operator -> langgraph-dataplane-operator

andrewnguonly · 2025-11-06T20:04:03Z

src/langsmith/deploy-hybrid.mdx

    - `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.


Feedback: installations <-- Can we be more literal here? What does installations refer to?

andrewnguonly · 2025-11-06T20:04:46Z

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

+### (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.


Suggestion: how to best organize this --> how to best organize this for your use case.

andrewnguonly · 2025-11-06T20:05:59Z

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

+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.


Feedback: What does step 5 refer to? Any way to be more targeted/specific?

andrewnguonly · 2025-11-06T20:06:31Z

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

+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.


Feedback: managed control plane <-- Can we be more literal/specific?

andrewnguonly · 2025-11-06T20:06:55Z

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

+
+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:


Suggestion: postgres --> Postgres (proper noun)

andrewnguonly · 2025-11-06T20:07:58Z

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

+
+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:


Suggestion: LangSmith postgres <-- Even this might be ambiguous. People get confused about all the different Postgres instances we create. How can we make this unambiguous? Should we reference langchainplusdb or whatever it's actually called?

chore: update hybrid deployment documentation

1cd802f

hari-dhanushkodi requested a review from katmayb as a code owner November 6, 2025 16:45

hari-dhanushkodi requested review from andrewnguonly and Copilot and removed request for Copilot and katmayb November 6, 2025 16:45

github-actions bot added the langsmith For docs changes to LangSmith label Nov 6, 2025

hari-dhanushkodi requested review from katmayb and langchain-infra November 6, 2025 16:49

katmayb approved these changes Nov 6, 2025

View reviewed changes

andrewnguonly requested changes Nov 6, 2025

View reviewed changes


		Your self-hosted infrastructure is now ready to create deployments.

		### (Optional) Configuring Additional Data Planes

	### (Optional) Configuring Additional Data Planes
	### (Optional) Configure additional data planes

	Note down the workspace id you choose as you will need this for future steps.
	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.
	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.

chore: update hybrid deployment documentation #1315

Are you sure you want to change the base?

chore: update hybrid deployment documentation #1315

Conversation

hari-dhanushkodi commented Nov 6, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Overview

Checklist

Additional notes

Uh oh!

katmayb left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

hari-dhanushkodi commented Nov 6, 2025 •

edited

Loading