From 447766e35565065f4a0e539079c74cf60c1102d9 Mon Sep 17 00:00:00 2001 From: romain-priour-lc Date: Fri, 5 Dec 2025 14:20:04 -0800 Subject: [PATCH 1/4] Done --- src/langsmith/self-host-external-postgres.mdx | 112 +++++++++++++++++- src/langsmith/self-host-external-redis.mdx | 29 ++++- 2 files changed, 132 insertions(+), 9 deletions(-) diff --git a/src/langsmith/self-host-external-postgres.mdx b/src/langsmith/self-host-external-postgres.mdx index 36df045b7f..7250158d85 100644 --- a/src/langsmith/self-host-external-postgres.mdx +++ b/src/langsmith/self-host-external-postgres.mdx @@ -3,7 +3,7 @@ title: Connect to an external PostgreSQL database sidebarTitle: Connect to an external PostgreSQL database --- -LangSmith uses a PostgreSQL database as the primary data store for transactional workloads and operational data (almost everything besides runs). By default, LangSmith Self-Hosted will use an internal PostgreSQL database. However, you can configure LangSmith to use an external PostgreSQL database (). By configuring an external PostgreSQL database, you can more easily manage backups, scaling, and other operational tasks for your database. +LangSmith uses a PostgreSQL database as the primary data store for transactional workloads and operational data (almost everything besides runs). By default, LangSmith Self-Hosted will use an internal PostgreSQL database. However, you can configure LangSmith to use an external PostgreSQL database. By configuring an external PostgreSQL database, you can more easily manage backups, scaling, and other operational tasks for your database. ## Requirements @@ -17,13 +17,13 @@ LangSmith uses a PostgreSQL database as the primary data store for transactional * A user with admin access to the PostgreSQL database. This user will be used to create the necessary tables, indexes, and schemas. -* This user will also need to have the ability to create extensions in the database. We use/will try to install the btree\_gin, btree\_gist, pgcrypto, citext, ltree, and pg\_trgm extensions. +* This user will also need to have the ability to create extensions in the database. We use/will try to install the `btree_gin`, `btree_gist`, `pgcrypto`, `citext`, `ltree`, and `pg_trgm` extensions. * If using a schema other than public, ensure that you do not have any other schemas with the extensions enabled, or you must include that in your search path. * Support for pgbouncer and other connection poolers is community-based. Community members have reported that pgbouncer has worked with `pool_mode` = `session` and a suitable setting for `ignore_startup_parameters` (as of writing, `search_path` and `lock_timeout` need to be ignored). Care is needed to avoid polluting connection pools; some level of PostgreSQL expertise is advisable. LangChain Inc currently does not have roadmap plans for formal test coverage or commercial support of pgbouncer or amazon rds proxy or any other poolers, but the community is welcome to discuss and collaborate on support through GitHub issues. -* By default, we recommend an instance with at least 2 vCPUs and 8GB of memory. However, the actual requirements will depend on your workload and the number of users you have. We recommend monitoring your PostgreSQL instance and scaling up as needed. +* By default, we recommend an instance with **at least 2 vCPUs and 8GB of memory**. However, the actual requirements will depend on your workload and the number of users you have. We recommend monitoring your PostgreSQL instance and scaling up as needed. ## Connection String @@ -33,7 +33,7 @@ You will need to provide a connection string to your PostgreSQL database. This c * Port * Database * Username -* Password(Make sure to url encode this if there are any special characters) +* Password (Make sure to url encode this if there are any special characters) * URL params This will take the form of: @@ -75,3 +75,107 @@ POSTGRES_DATABASE_URI="Your connection url" Once configured, you should be able to reinstall your LangSmith instance. If everything is configured correctly, your LangSmith instance should now be using your external PostgreSQL database. + +## TLS with PostgreSQL + +Use this section to configure TLS for PostgreSQL connections. For mounting internal/public CAs so LangSmith trusts your PostgreSQL server certificate, see [Configure custom TLS certificates](/langsmith/self-host-custom-tls-certificates#mount-internal-cas-for-tls). + +### Server TLS (one-way) + +To validate the PostgreSQL server certificate: + +- Provide a CA bundle using `config.customCa.secretName` and `config.customCa.secretKey`. +- Use `sslmode=require` or `sslmode=verify-full`, as well as `sslrootcert=system` to your connection URL. + + +Mount a custom CA only when your PostgreSQL server uses an internal or private CA. Publicly trusted CAs do not require this configuration. + + + + +```yaml Helm (server TLS) +config: + customCa: + secretName: "langsmith-custom-ca" # Secret containing your CA bundle + secretKey: "ca.crt" # Key in the Secret with the CA bundle +postgres: + external: + enabled: true + connectionUrl: "myuser:mypassword@myhost:5432/mydatabase?sslmode=verify-full&sslrootcert=system" +``` + +```yaml Kubernetes Secret (CA bundle) +apiVersion: v1 +kind: Secret +metadata: + name: langsmith-custom-ca +type: Opaque +stringData: + ca.crt: | + -----BEGIN CERTIFICATE----- + + -----END CERTIFICATE----- +``` + + + +### Mutual TLS with Client Auth (mTLS) + +As of LangSmith helm chart version **0.12.28**, we support mTLS for PostgreSQL clients. For server-side authentication in mTLS, use the Server TLS steps above (custom CA) in addition to the client certificate configuration below. + +If your PostgreSQL server requires client certificate authentication: + +- Provide a Secret with your client certificate and key. +- Reference it via `postgres.external.clientCert.secretName` and specify the keys with `certSecretKey` and `keySecretKey`. +- Use `sslmode=verify-full` and `sslrootcert=system` in your connection URL. + + + +```yaml Helm (client Auth) +postgres: + external: + enabled: true + connectionUrl: "myuser:mypassword@myhost:5432/mydatabase?sslmode=verify-full&sslrootcert=system" + clientCert: + secretName: "postgres-mtls-secret" + certSecretKey: "tls.crt" + keySecretKey: "tls.key" +``` + +```yaml Kubernetes Secret (client cert/key) +apiVersion: v1 +kind: Secret +metadata: + name: postgres-mtls-secret +type: Opaque +stringData: + tls.crt: | + -----BEGIN CERTIFICATE----- + + -----END CERTIFICATE----- + tls.key: | + -----BEGIN PRIVATE KEY----- + + -----END PRIVATE KEY----- +``` + + + +#### Pod security context for certificate volumes + +The certificate volumes mounted for mTLS are protected by file access restrictions. To ensure all LangSmith pods can read the certificate files, you must set `fsGroup: 1000` in the pod security context. + +You can configure this in one of two ways: + +**Option 1: Use `commonPodSecurityContext`** + +Set the `fsGroup` at the top level to apply it to all pods: + +```yaml +commonPodSecurityContext: + fsGroup: 1000 +``` + +**Option 2: Add to individual pod security contexts** + +If you need more granular control, add the `fsGroup` to each pod's security context individually. See the [mTLS configuration example](https://github.com/langchain-ai/helm/blob/main/charts/langsmith/examples/mtls_config.yaml) for a complete reference. diff --git a/src/langsmith/self-host-external-redis.mdx b/src/langsmith/self-host-external-redis.mdx index d080ca51f9..7736cd6e17 100644 --- a/src/langsmith/self-host-external-redis.mdx +++ b/src/langsmith/self-host-external-redis.mdx @@ -252,7 +252,7 @@ stringData: ### Mutual TLS with Client Auth (mTLS) -As of LangSmith helm chart version **0.12.26**, we support mTLS for Redis clients. For server-side authentication in mTLS, use the Server TLS steps above (custom CA) in addition to the client certificate configuration below. +As of LangSmith helm chart version **0.12.28**, we support mTLS for Redis clients. For server-side authentication in mTLS, use the Server TLS steps above (custom CA) in addition to the client certificate configuration below. If your Redis server requires client certificate authentication: @@ -269,8 +269,8 @@ redis: enabled: true clientCert: secretName: "redis-mtls-secret" - certSecretKey: "client.crt" - keySecretKey: "client.key" + certSecretKey: "tls.crt" + keySecretKey: "tls.key" # Standalone example: # connectionUrl: "rediss://host:6380/0?password=" # Or, for Cluster: @@ -291,14 +291,33 @@ metadata: name: redis-mtls-secret type: Opaque stringData: - client.crt: | + tls.crt: | -----BEGIN CERTIFICATE----- -----END CERTIFICATE----- - client.key: | + tls.key: | -----BEGIN PRIVATE KEY----- -----END PRIVATE KEY----- ``` + +#### Pod security context for certificate volumes + +The certificate volumes mounted for mTLS are protected by file access restrictions. To ensure all LangSmith pods can read the certificate files, you must set `fsGroup: 1000` in the pod security context. + +You can configure this in one of two ways: + +**Option 1: Use `commonPodSecurityContext`** + +Set the `fsGroup` at the top level to apply it to all pods: + +```yaml +commonPodSecurityContext: + fsGroup: 1000 +``` + +**Option 2: Add to individual pod security contexts** + +If you need more granular control, add the `fsGroup` to each pod's security context individually. See the [mtls configuration example](https://github.com/langchain-ai/helm/blob/main/charts/langsmith/examples/mtls_config.yaml) for a complete reference. From 5891cfc4b3e217a913f6f098670c584e74bdb2b9 Mon Sep 17 00:00:00 2001 From: romain-priour-lc Date: Fri, 5 Dec 2025 14:25:18 -0800 Subject: [PATCH 2/4] Add the customTls helm value --- src/langsmith/self-host-external-postgres.mdx | 2 ++ 1 file changed, 2 insertions(+) diff --git a/src/langsmith/self-host-external-postgres.mdx b/src/langsmith/self-host-external-postgres.mdx index 7250158d85..8222549cb9 100644 --- a/src/langsmith/self-host-external-postgres.mdx +++ b/src/langsmith/self-host-external-postgres.mdx @@ -102,6 +102,7 @@ postgres: external: enabled: true connectionUrl: "myuser:mypassword@myhost:5432/mydatabase?sslmode=verify-full&sslrootcert=system" + customTls: true ``` ```yaml Kubernetes Secret (CA bundle) @@ -136,6 +137,7 @@ postgres: external: enabled: true connectionUrl: "myuser:mypassword@myhost:5432/mydatabase?sslmode=verify-full&sslrootcert=system" + customTls: true clientCert: secretName: "postgres-mtls-secret" certSecretKey: "tls.crt" From f5e34b426a625f42e8f7f9955ea79414a776ed2d Mon Sep 17 00:00:00 2001 From: romain-priour-lc Date: Sat, 6 Dec 2025 15:30:26 -0800 Subject: [PATCH 3/4] Clickhouse MTLS Docs done --- .../self-host-external-clickhouse.mdx | 150 ++++++++++++++++-- src/langsmith/self-host-external-postgres.mdx | 2 +- src/langsmith/self-host-external-redis.mdx | 2 +- 3 files changed, 143 insertions(+), 11 deletions(-) diff --git a/src/langsmith/self-host-external-clickhouse.mdx b/src/langsmith/self-host-external-clickhouse.mdx index e919a0b9f1..c6f67e1a4a 100644 --- a/src/langsmith/self-host-external-clickhouse.mdx +++ b/src/langsmith/self-host-external-clickhouse.mdx @@ -88,13 +88,13 @@ For more information, refer to the [managed ClickHouse](/langsmith/langsmith-man You will need to provide several parameters to your LangSmith installation to configure an external ClickHouse database. These parameters include: -* Host: The hostname or IP address of the ClickHouse database -* HTTP Port: The port that the ClickHouse database listens on for HTTP connections -* Native Port: The port that the ClickHouse database listens on for [native connections](https://clickhouse.com/docs/en/interfaces/tcp) -* Database: The name of the ClickHouse database that LangSmith should use -* Username: The username to use to connect to the ClickHouse database -* Password: The password to use to connect to the ClickHouse database -* Cluster (Optional): The name of the ClickHouse cluster if using an external Clickhouse cluster. When set, LangSmith will run migrations on the cluster and replicate data across instances. +* **Host**: The hostname or IP address of the ClickHouse database +* **HTTP Port**: The port that the ClickHouse database listens on for HTTP connections +* **Native Port**: The port that the ClickHouse database listens on for [native connections](https://clickhouse.com/docs/en/interfaces/tcp) +* **Database**: The name of the ClickHouse database that LangSmith should use +* **Username**: The username to use to connect to the ClickHouse database +* **Password**: The password to use to connect to the ClickHouse database +* **Cluster (Optional)**: The name of the ClickHouse cluster if using an external Clickhouse cluster. When set, LangSmith will run migrations on the cluster and replicate data across instances. Important considerations for clustered deployments: @@ -105,8 +105,8 @@ Important considerations for clustered deployments: * When using a clustered deployment, LangSmith will automatically: -* Run database migrations across all nodes in the cluster -* Configure tables for data replication across the cluster + * Run database migrations across all nodes in the cluster + * Configure tables for data replication across the cluster Note that while data is replicated across nodes, LangSmith does not configure distributed tables or handle query routing - queries will be directed to the specified host. You will need to handle any load balancing or query distribution at the infrastructure level if desired. @@ -146,3 +146,135 @@ CLICKHOUSE_CLUSTER=my_cluster_name # Optional: Set this if using an external Cli Once configured, you should be able to reinstall your LangSmith instance. If everything is configured correctly, your LangSmith instance should now be using your external ClickHouse database. + +## TLS with ClickHouse + +Use this section to configure TLS for ClickHouse connections. For mounting internal/public CAs so LangSmith trusts your ClickHouse server certificate, see [Configure custom TLS certificates](/langsmith/self-host-custom-tls-certificates#mount-internal-cas-for-tls). + +### Server TLS (one-way) + +To enable TLS for ClickHouse connections: + +- Set `tls: true` in your configuration (or use `tlsSecretKey` with an external secret). +- Use the appropriate TLS ports (typically `8443` for HTTP and `9440` for native TCP connections). +- Provide a CA bundle using `config.customCa.secretName` and `config.customCa.secretKey` if using an internal CA. + + +Mount a custom CA only when your ClickHouse server uses an internal or private CA. Publicly trusted CAs do not require this configuration. + + + + +```yaml Helm (server TLS) +config: + customCa: + secretName: "langsmith-custom-ca" # Secret containing your CA bundle + secretKey: "ca.crt" # Key in the Secret with the CA bundle +clickhouse: + external: + enabled: true + host: "your-clickhouse-host.example.com" + port: "8443" + nativePort: "9440" + user: "default" + password: "password" + database: "default" + tls: true +``` + +```yaml Kubernetes Secret (CA bundle) +apiVersion: v1 +kind: Secret +metadata: + name: langsmith-custom-ca +type: Opaque +stringData: + ca.crt: | + -----BEGIN CERTIFICATE----- + + -----END CERTIFICATE----- +``` + + + +### Mutual TLS with client auth (mTLS) + +As of LangSmith helm chart version **0.12.29**, we support mTLS for ClickHouse clients. For server-side authentication in mTLS, use the Server TLS steps above (custom CA) in addition to the client certificate configuration below. + +If your ClickHouse server requires client certificate authentication: + +- Provide a Secret with your client certificate and key. +- Reference it via `clickhouse.external.clientCert.secretName` and specify the keys with `certSecretKey` and `keySecretKey`. + + + +```yaml Helm (client auth) +clickhouse: + external: + enabled: true + host: "your-clickhouse-host.example.com" + port: "8443" + nativePort: "9440" + user: "default" + password: "password" + database: "default" + tls: true + clientCert: + secretName: "clickhouse-client-cert" + certSecretKey: "tls.crt" + keySecretKey: "tls.key" +``` + +```yaml Kubernetes Secret (client cert/key) +apiVersion: v1 +kind: Secret +metadata: + name: clickhouse-client-cert +type: Opaque +stringData: + tls.crt: | + -----BEGIN CERTIFICATE----- + + -----END CERTIFICATE----- + tls.key: | + -----BEGIN PRIVATE KEY----- + + -----END PRIVATE KEY----- +``` + + + +#### Non-TLS native port for migrations + + +When using mTLS with ClickHouse, you must **keep a non-TLS native (TCP) port** open for our migrations job, which runs on helm install and upgrade. The application itself will not communicate through this port, it is **only used by the migration job**. + + +By default, the migration job connects to port `9000` for migrations. If your ClickHouse instance uses a different non-TLS native port, you can configure it using the `CLICKHOUSE_MIGRATE_NATIVE_PORT` environment variable: + +```yaml +backend: + clickhouseMigrations: + extraEnv: + - name: CLICKHOUSE_MIGRATE_NATIVE_PORT + value: "9000" # Change to your non-TLS native port +``` + +#### Pod security context for certificate volumes + +The certificate volumes mounted for mTLS are protected by file access restrictions. To ensure all LangSmith pods can read the certificate files, you must set `fsGroup: 1000` in the pod security context. + +You can configure this in one of two ways: + +**Option 1: Use `commonPodSecurityContext`** + +Set the `fsGroup` at the top level to apply it to all pods: + +```yaml +commonPodSecurityContext: + fsGroup: 1000 +``` + +**Option 2: Add to individual pod security contexts** + +If you need more granular control, add the `fsGroup` to each pod's security context individually. See the [mTLS configuration example](https://github.com/langchain-ai/helm/blob/main/charts/langsmith/examples/mtls_config.yaml) for a complete reference. diff --git a/src/langsmith/self-host-external-postgres.mdx b/src/langsmith/self-host-external-postgres.mdx index 8222549cb9..7f489315e2 100644 --- a/src/langsmith/self-host-external-postgres.mdx +++ b/src/langsmith/self-host-external-postgres.mdx @@ -122,7 +122,7 @@ stringData: ### Mutual TLS with Client Auth (mTLS) -As of LangSmith helm chart version **0.12.28**, we support mTLS for PostgreSQL clients. For server-side authentication in mTLS, use the Server TLS steps above (custom CA) in addition to the client certificate configuration below. +As of LangSmith helm chart version **0.12.29**, we support mTLS for PostgreSQL clients. For server-side authentication in mTLS, use the Server TLS steps above (custom CA) in addition to the client certificate configuration below. If your PostgreSQL server requires client certificate authentication: diff --git a/src/langsmith/self-host-external-redis.mdx b/src/langsmith/self-host-external-redis.mdx index 7736cd6e17..8612f6d268 100644 --- a/src/langsmith/self-host-external-redis.mdx +++ b/src/langsmith/self-host-external-redis.mdx @@ -252,7 +252,7 @@ stringData: ### Mutual TLS with Client Auth (mTLS) -As of LangSmith helm chart version **0.12.28**, we support mTLS for Redis clients. For server-side authentication in mTLS, use the Server TLS steps above (custom CA) in addition to the client certificate configuration below. +As of LangSmith helm chart version **0.12.29**, we support mTLS for Redis clients. For server-side authentication in mTLS, use the Server TLS steps above (custom CA) in addition to the client certificate configuration below. If your Redis server requires client certificate authentication: From 7ca635e290fc728006dda45b42700a657f68f8b7 Mon Sep 17 00:00:00 2001 From: romain-priour-lc Date: Mon, 8 Dec 2025 08:53:37 -0800 Subject: [PATCH 4/4] Add server TLS steps link like in the Postgres docs --- src/langsmith/self-host-external-clickhouse.mdx | 2 +- src/langsmith/self-host-external-redis.mdx | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/src/langsmith/self-host-external-clickhouse.mdx b/src/langsmith/self-host-external-clickhouse.mdx index c6f67e1a4a..e348aa1faa 100644 --- a/src/langsmith/self-host-external-clickhouse.mdx +++ b/src/langsmith/self-host-external-clickhouse.mdx @@ -199,7 +199,7 @@ stringData: ### Mutual TLS with client auth (mTLS) -As of LangSmith helm chart version **0.12.29**, we support mTLS for ClickHouse clients. For server-side authentication in mTLS, use the Server TLS steps above (custom CA) in addition to the client certificate configuration below. +As of LangSmith helm chart version **0.12.29**, we support mTLS for ClickHouse clients. For server-side authentication in mTLS, use the [Server TLS steps](#server-tls-one-way) (custom CA) in addition to the following client certificate configuration. If your ClickHouse server requires client certificate authentication: diff --git a/src/langsmith/self-host-external-redis.mdx b/src/langsmith/self-host-external-redis.mdx index 8612f6d268..86bacc70eb 100644 --- a/src/langsmith/self-host-external-redis.mdx +++ b/src/langsmith/self-host-external-redis.mdx @@ -252,7 +252,7 @@ stringData: ### Mutual TLS with Client Auth (mTLS) -As of LangSmith helm chart version **0.12.29**, we support mTLS for Redis clients. For server-side authentication in mTLS, use the Server TLS steps above (custom CA) in addition to the client certificate configuration below. +As of LangSmith helm chart version **0.12.29**, we support mTLS for Redis clients. For server-side authentication in mTLS, use the [Server TLS steps](#server-tls-one-way) (custom CA) in addition to the following client certificate configuration. If your Redis server requires client certificate authentication: