Connect to an external Redis database ↗

langchain guide advanced deployment workflows

Original Documentation

Documentation Index#
Fetch the complete documentation index at: https://docs.langchain.com/llms.txt Use this file to discover all available pages before exploring further.

LangSmith uses Redis to back our queuing/caching operations. By default, LangSmith Self-Hosted will use an internal Redis instance. However, you can configure LangSmith to use an external Redis instance. By configuring an external Redis instance, you can more easily manage backups, scaling, and other operational tasks for your Redis instance.

Each LangSmith installation must use its own dedicated Redis instance. Redis cannot be shared across separate LangSmith installations (for example, between an existing and new cluster during a migration). Sharing it across installations causes deployment tasks to be routed to the wrong cluster.

If you’re using a managed Redis service, we recommend:

For cloud-specific IAM/Workload Identity authentication, refer to the IAM authentication section.

Requirements#

A provisioned Redis instance that your LangSmith instance will have network access to. We recommend using a managed Redis service like:
Note: We only officially support Redis versions >= 5.
We support both Standalone and Redis Cluster. See the appropriate sections for deployment instructions.
We support no authentication, password, and IAM/Workload Identity authentication.
By default, we recommend an instance with at least 2 vCPUs and 8GB of memory. However, the actual requirements will depend on your tracing workload. We recommend monitoring your Redis instance and scaling up as needed.

Standalone Redis#

Connection string#

You will need to assemble the connection string for your Redis instance. This connection string should include the following information:

Host
Database
Port
URL params

This will take the form of:

"redis://host:port/db?<url_params>"

An example connection string might look like:

"redis://langsmith-redis:6379/0"

Note: If your Standalone Redis requires authentication or TLS, include these directly in the connection URL:

Use rediss:// when TLS is enabled on your Redis server.
Provide the password in the connection string.

For example:

rediss://langsmith-redis:6380/0?password=foo

For IAM authentication, use the identity as the username (no password):

rediss://<iam-identity>@host:6380

Configuration#

With your connection string in hand, you can configure your LangSmith instance to use an external Redis instance. You can do this by modifying the values file for your LangSmith Helm Chart installation or the .env file for your Docker installation.

redis:
  external:
    enabled: true
    connectionUrl: "Your connection url"

# In your .env file
REDIS_DATABASE_URI="Your connection url"

You can also store the connection URL in an existing Kubernetes Secret and reference it in your Helm values.

redis:
  external:
    enabled: true
    # Name of an existing Secret that contains the connection URL
    existingSecretName: "my-redis-secret"
    # Key in the Secret that stores the connection URL (default shown)
    connectionUrlSecretKey: "connection_url"

apiVersion: v1
kind: Secret
metadata:
  name: my-redis-secret
type: Opaque
stringData:
  # Full connection URL, e.g., using TLS with password
  connection_url: "rediss://langsmith-redis:6380/0?password=foo"

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

Redis cluster#

As of LangSmith helm version 0.12.25, we officially support Redis Cluster.

Host names#

When using Redis Cluster, provide a list of node hostnames and ports. Each node URI must be in the form:

redis://hostname:port

For example:

redis://redis-node-0:6379
redis://redis-node-1:6379
redis://redis-node-2:6379

Do not include a password in these URIs, and do not use rediss here. For Redis Cluster:

Provide the password separately via redis.external.cluster.password or through a Secret using passwordSecretKey.
Enable TLS separately with redis.external.cluster.tlsEnabled: true.

Configuration#

When connecting to an external Redis Cluster, configure the Helm values under redis.external.cluster. You can either:

Provide node URIs and (optionally) a password directly in values.yaml.

Or reference an existing Kubernetes Secret containing node URIs and password.

redis:
  external:
    enabled: true
    cluster:
      enabled: true
      # List of cluster node URIs. Format: redis://host:port
      nodeUris:
        - "redis://redis-node-0:6379"
        - "redis://redis-node-1:6379"
        - "redis://redis-node-2:6379"
      # Optional. If your cluster requires auth, set a password or use a Secret (recommended).
      password: "your_redis_password"
      # Enable if your cluster uses TLS.
      tlsEnabled: true

redis:
  external:
    enabled: true
    # Name of an existing Secret that contains cluster connection details
    existingSecretName: "my-redis-cluster-secret"
    cluster:
      enabled: true
      # Keys in the Secret. Defaults shown here; override if your Secret uses different keys.
      nodeUrisSecretKey: "redis_cluster_node_uris"
      passwordSecretKey: "redis_cluster_password"
      tlsEnabled: true

If using an existing Secret, it should contain:

apiVersion: v1
kind: Secret
metadata:
  name: my-redis-cluster-secret
type: Opaque
stringData:
  # JSON array of node URIs (as a string)
  redis_cluster_node_uris: '["redis://redis-node-0:6379","redis://redis-node-1:6379","redis://redis-node-2:6379"]'
  # Optional if your cluster requires a password
  redis_cluster_password: "your_redis_password"

TLS with Redis#

Use this section to configure TLS for Redis connections. For mounting internal/public CAs so LangSmith trusts your Redis server certificate, see Configure custom TLS certificates.

Server TLS (one-way)#

To validate the Redis server certificate:

Provide a CA bundle using config.customCa.secretName and config.customCa.secretKey.
For Standalone Redis, use rediss:// in the connection URL.
For Redis Cluster, set redis.external.cluster.tlsEnabled: true.

Mount a custom CA only when your Redis server uses an internal or private CA. Publicly trusted CAs do not require this configuration.

config:
  customCa:
    secretName: "langsmith-custom-ca"  # Secret containing your CA bundle
    secretKey: "ca.crt"    # Key in the Secret with the CA bundle
redis:
  external:
    enabled: true
    # Use rediss:// and include password if required by your server
    connectionUrl: "rediss://host:6380/0?password=<PASSWORD>"

config:
  customCa:
    secretName: "langsmith-custom-ca"  # Secret containing your CA bundle
    secretKey: "ca.crt"    # Key in the Secret with the CA bundle
redis:
  external:
    enabled: true
    cluster:
      enabled: true
      tlsEnabled: true
      nodeUris:
        - "redis://redis-node-0:6379"
        - "redis://redis-node-1:6379"
        - "redis://redis-node-2:6379"
      password: "<PASSWORD>"

apiVersion: v1
kind: Secret
metadata:
  name: langsmith-custom-ca
type: Opaque
stringData:
  ca.crt: |
    -----BEGIN CERTIFICATE-----
    <ROOT_OR_INTERMEDIATE_CA_CERT_CHAIN>
    -----END CERTIFICATE-----

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 (custom CA) in addition to the following client certificate configuration.

If your Redis server requires client certificate authentication:

Provide a Secret with your client certificate and key.
Reference it via redis.external.clientCert.secretName and specify the keys with certSecretKey and keySecretKey.
For Standalone Redis, keep using rediss:// in the connection URL.

For Redis Cluster, set redis.external.cluster.tlsEnabled: true.

redis:
  external:
    enabled: true
    clientCert:
      secretName: "redis-mtls-secret"
      certSecretKey: "tls.crt"
      keySecretKey: "tls.key"
    # Standalone example:
    # connectionUrl: "rediss://host:6380/0?password=<PASSWORD>"
    # Or, for Cluster:
    cluster:
      enabled: true
      tlsEnabled: true
      nodeUris:
        - "redis://redis-node-0:6379"
        - "redis://redis-node-1:6379"
        - "redis://redis-node-2:6379"
      password: "<PASSWORD>"

apiVersion: v1
kind: Secret
metadata:
  name: redis-mtls-secret
type: Opaque
stringData:
  tls.crt: |
    -----BEGIN CERTIFICATE-----
    <CLIENT_CERT>
    -----END CERTIFICATE-----
  tls.key: |
    -----BEGIN PRIVATE KEY-----
    <CLIENT_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:

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 for a complete reference.

IAM authentication#

As of LangSmith helm chart version 0.12.34, we support IAM authentication for Redis. This allows you to use cloud provider workload identity instead of static passwords.

IAM authentication is supported for both standalone Redis and Redis Cluster configurations. However, not all cloud providers support IAM authentication for all Redis offerings. Check your cloud provider’s documentation to verify IAM support for your specific Redis setup (e.g., GCP only supports IAM for Memorystore Cluster, not standalone Memorystore).

ElastiCache for Redis IAM authentication#

ElastiCache for Redis supports IAM authentication, which allows you to authenticate using AWS IAM credentials instead of Redis AUTH passwords.

Prerequisites#

Configure workload identity in your Kubernetes cluster using AWS IRSA or EKS Pod Identity
Enable IAM authentication on your ElastiCache instance and grant access to your workload identity

Configuration#

Standalone Redis:

    redis:
      external:
        enabled: true
        existingSecretName: "redis-secret"
        iamAuthProvider: "aws"
    ```

```yaml
    apiVersion: v1
    kind: Secret
    metadata:
      name: redis-secret
    type: Opaque
    stringData:
      # IAM connection URL - identity as username, no password
      connection_url: "rediss://<iam-identity>@<elasticache-host>:6380"
    ```

**Redis Cluster:**

```yaml
    redis:
      external:
        enabled: true
        existingSecretName: "redis-cluster-secret"
        iamAuthProvider: "aws"
        cluster:
          enabled: true
          nodeUrisSecretKey: "redis_cluster_node_uris"
          tlsEnabled: true
    ```

#### Required annotations

You must apply the ServiceAccount annotations required by AWS IRSA to all LangSmith components that connect to Redis:

**Deployments:** `backend`, `queue`, `platformBackend`, `hostBackend`, `ingestQueue`

Example configuration:

```yaml
    backend:
      serviceAccount:
        annotations:
          eks.amazonaws.com/role-arn: "arn:aws:iam::<account-id>:role/<role-name>"

    queue:
      serviceAccount:
        annotations:
          eks.amazonaws.com/role-arn: "arn:aws:iam::<account-id>:role/<role-name>"

    platformBackend:
      serviceAccount:
        annotations:
          eks.amazonaws.com/role-arn: "arn:aws:iam::<account-id>:role/<role-name>"

    hostBackend:
      serviceAccount:
        annotations:
          eks.amazonaws.com/role-arn: "arn:aws:iam::<account-id>:role/<role-name>"

    ingestQueue:
      serviceAccount:
        annotations:
          eks.amazonaws.com/role-arn: "arn:aws:iam::<account-id>:role/<role-name>"
    ```

See the [Helm values reference](https://github.com/langchain-ai/helm/blob/main/charts/langsmith/values.yaml) for the full list of configurable services.
  <span class="tab-end"></span>

  <span class="tab-start" data-tab-title="GCP"></span>
### Memorystore for Redis IAM authentication

Memorystore for Redis supports [IAM authentication](https://docs.cloud.google.com/memorystore/docs/cluster/about-iam-auth) for **Cluster instances only** (not standalone Memorystore). This allows you to authenticate using GCP service accounts.

<span class="callout-start" data-callout-type="note"></span>
  IAM authentication is only available for Memorystore Cluster, not standalone Memorystore instances.
<span class="callout-end"></span>

#### Prerequisites

1. **Configure workload identity** in your Kubernetes cluster using [GCP Workload Identity](https://cloud.google.com/kubernetes-engine/docs/how-to/workload-identity)
2. **Enable IAM authentication** on your Memorystore Cluster and grant access to your workload identity

#### Configuration

**Memorystore Cluster with IAM:**

```yaml
    redis:
      external:
        enabled: true
        existingSecretName: "redis-cluster-secret"
        iamAuthProvider: "gcp"
        cluster:
          enabled: true
          nodeUrisSecretKey: "redis_cluster_node_uris"
          tlsEnabled: true
    ```

```yaml
    apiVersion: v1
    kind: Secret
    metadata:
      name: redis-cluster-secret
    type: Opaque
    stringData:
      redis_cluster_node_uris: '["redis://node-0:6379","redis://node-1:6379","redis://node-2:6379"]'
    ```

#### Required annotations

You must apply the ServiceAccount annotations required by GCP Workload Identity to all LangSmith components that connect to Redis:

**Deployments:** `backend`, `queue`, `platformBackend`, `hostBackend`, `ingestQueue`

Example configuration:

```yaml
    backend:
      serviceAccount:
        annotations:
          iam.gke.io/gcp-service-account: "<service-account>@<project>.iam.gserviceaccount.com"

    queue:
      serviceAccount:
        annotations:
          iam.gke.io/gcp-service-account: "<service-account>@<project>.iam.gserviceaccount.com"

    platformBackend:
      serviceAccount:
        annotations:
          iam.gke.io/gcp-service-account: "<service-account>@<project>.iam.gserviceaccount.com"

    hostBackend:
      serviceAccount:
        annotations:
          iam.gke.io/gcp-service-account: "<service-account>@<project>.iam.gserviceaccount.com"

    ingestQueue:
      serviceAccount:
        annotations:
          iam.gke.io/gcp-service-account: "<service-account>@<project>.iam.gserviceaccount.com"
    ```

See the [Helm values reference](https://github.com/langchain-ai/helm/blob/main/charts/langsmith/values.yaml) for the full list of configurable services.
  <span class="tab-end"></span>

  <span class="tab-start" data-tab-title="Azure"></span>
### Azure Cache for Redis with Microsoft Entra authentication

Azure Cache for Redis supports [Microsoft Entra authentication](https://learn.microsoft.com/en-us/azure/azure-cache-for-redis/cache-azure-active-directory-for-authentication), which allows you to authenticate using Azure managed identities.

#### Prerequisites

1. **Configure workload identity** in your Kubernetes cluster using [Azure Workload Identity](https://learn.microsoft.com/en-us/azure/aks/workload-identity-overview)
2. **Enable Microsoft Entra authentication** on your Azure Cache for Redis and grant access to your workload identity

#### Configuration

**Standalone Redis:**

```yaml
    redis:
      external:
        enabled: true
        existingSecretName: "redis-secret"
        iamAuthProvider: "azure"
    ```

```yaml
    apiVersion: v1
    kind: Secret
    metadata:
      name: redis-secret
    type: Opaque
    stringData:
      # IAM connection URL - managed identity as username, no password
      connection_url: "rediss://<managed-identity>@<azure-redis-host>:6380"
    ```

**Redis Cluster:**

```yaml
    redis:
      external:
        enabled: true
        existingSecretName: "redis-cluster-secret"
        iamAuthProvider: "azure"
        cluster:
          enabled: true
          nodeUrisSecretKey: "redis_cluster_node_uris"
          tlsEnabled: true
    ```

#### Required annotations

You must apply the ServiceAccount annotations and pod labels required by Azure Workload Identity to all LangSmith components that connect to Redis:

**Deployments:** `backend`, `queue`, `platformBackend`, `hostBackend`, `ingestQueue`

Example configuration:

```yaml
    backend:
      serviceAccount:
        annotations:
          azure.workload.identity/client-id: "<managed-identity-client-id>"
      deployment:
        labels:
          azure.workload.identity/use: "true"

    queue:
      serviceAccount:
        annotations:
          azure.workload.identity/client-id: "<managed-identity-client-id>"
      deployment:
        labels:
          azure.workload.identity/use: "true"

    platformBackend:
      serviceAccount:
        annotations:
          azure.workload.identity/client-id: "<managed-identity-client-id>"
      deployment:
        labels:
          azure.workload.identity/use: "true"

    hostBackend:
      serviceAccount:
        annotations:
          azure.workload.identity/client-id: "<managed-identity-client-id>"
      deployment:
        labels:
          azure.workload.identity/use: "true"

    ingestQueue:
      serviceAccount:
        annotations:
          azure.workload.identity/client-id: "<managed-identity-client-id>"
      deployment:
        labels:
          azure.workload.identity/use: "true"
    ```

See the [Helm values reference](https://github.com/langchain-ai/helm/blob/main/charts/langsmith/values.yaml) for the full list of configurable services.
  <span class="tab-end"></span>
<span class="tab-group-end"></span>

***


  <span class="callout-start" data-callout-type="note"></span>
[Edit this page on GitHub](https://github.com/langchain-ai/docs/edit/main/src/langsmith/self-host-external-redis.mdx) or [file an issue](https://github.com/langchain-ai/docs/issues/new/choose).
  <span class="callout-end"></span>

  <span class="callout-start" data-callout-type="note"></span>
[Connect these docs](/use-these-docs) to Claude, VSCode, and more via MCP for real-time answers.
  <span class="callout-end"></span>

Link last verified June 7, 2026. View original ↗

Source: LangChain Docs

Link last verified: 2026-03-04