Configuring SDKs for the Relay Proxy
Read time: 10 minutes
Last edited: Dec 28, 2023
This topic explains how to use the Relay Proxy. It also explains the Relay Proxy's two modes and gives detail on how to perform flag evaluations with the Relay Proxy.
To learn more about deploying and configuring the Relay Proxy, read Deploying the Relay Proxy.
After the Relay Proxy is up and running, you must set certain values in your SDK's configuration to connect to the Relay Proxy. Precise steps to set the configuration values depend on your particular SDK.
The values you may replace are:
- The base URI for the polling service. The default value is
https://clientsdk.launchdarkly.com, depending on which SDK you use.
- The base URI for the streaming service. The default value is
https://stream.launchdarkly.comfor server-side SDKs and
https://clientstream.launchdarkly.comfor client-side and mobile SDKs.
- The base URI for the events service. The default value is
https://mobile.launchdarkly.com, depending on which SDK you use. To learn more, read the Relay Proxy GitHub repository's Event forwarding.
Each SDK uses these values to determine where to request flag updates. Change the values to point to the Relay Proxy URI instead of directly to LaunchDarkly's services. In some SDKs, you must set the base URI of each service to the Relay Proxy's base URI, using a separate configuration property for each service but setting each one to the same value. In other SDKs, you can set the base URI for all services with a single configuration property.
If the Relay Proxy is unreachable for any reason, then LaunchDarkly is unreachable. LaunchDarkly SDKs do not fall back to the LaunchDarkly service URIs if the Relay Proxy is unavailable.
After you set up the Relay Proxy, you can configure your SDKs to run in either proxy mode or daemon mode.
Which mode you choose depends on the types of SDKs you are using:
- Client-side and mobile SDKs can only use the Relay Proxy in proxy mode. This is because in daemon mode, the SDK connects directly to the Relay Proxy's data store, which is not a supported behavior for client-side SDKs.
- Server-side SDKs can use it in either mode.
We generally recommend configuring your SDKs for proxy mode. Daemon mode is a workaround for environments where normal operation is not possible.
The two modes are not mutually exclusive. If you have configured multiple services to use Relay Proxy, some of these services can operate in proxy mode while others are in daemon mode. If this is your use case, we recommend configuring your SDKs to follow the best practices listed in each of the following subsections.
Expand Using proxy mode
Proxy mode is the most common use case for connecting to the Relay Proxy. LaunchDarkly SDKs are configured to run in proxy mode by default. Client-side SDKs must use proxy mode. To learn more about configuring the Relay Proxy for client-side SDKs, read the Relay Proxy GitHub repository's Client-side/mobile connections.
In proxy mode, several Relay Proxy instances should exist in a high-availability configuration behind a load balancer. Relay Proxy nodes do not need to communicate with each other. There is no master node or cluster.
You can scale the Relay Proxy horizontally by deploying more nodes behind the load balancer. Do not use a single node when your SDKs are in proxy mode.
Here is a diagram showing how the Relay Proxy works in proxy mode:
You should not use a persistent feature store between the Relay Proxy and your application in proxy mode.
Expand Using daemon mode
Daemon mode requires that you configure server-side LaunchDarkly SDKs to communicate directly with the Relay Proxy's persistent data store. We recommend this configuration when you're using LaunchDarkly with PHP or in a serverless environment.
There is no need to put a load balancer in front of the Relay Proxy when your SDKs are configured to run in daemon mode. You need only one instance of the Relay Proxy to keep the persistent store up to date. Multiple instances do not help the Relay Proxy to scale with the number of connected clients.
The persistent store will contain the flag and segment rules for your configured environments. The amount of data is typically quite small. The data will be the same information returned by the streaming and polling endpoints. To learn more about using daemon mode, read the Relay Proxy GitHub repository's Daemon mode.
Here is a diagram showing how the Relay Proxy works in daemon mode:
To use daemon mode:
- Configure your SDK to use a persistent data store. The SDK and the Relay Proxy must use the same data store.
- Configure your SDK to use daemon mode.
If you use LaunchDarkly in a serverless environment, we recommend using DynamoDB as a persistent feature store. In this scenario, the Relay Proxy’s purpose is to keep the feature store updated. To learn more about setting up a persistent feature store for use in daemon mode, read Using a persistent feature store without connecting to LaunchDarkly. For a tutorial that demonstrates a persistent store set up in a serverless environment, read Use a persistent feature store.
If you have set your SDK to daemon mode and wish to restore it to proxy mode, you can do that by removing the configuration that enabled daemon mode. By default, LaunchDarkly SDKs run in proxy mode, so removing the additional configuration returns the SDK to proxy mode. To learn more about customizing SDK configuration, read the documentation for your SDK.
We recommend that you use a monitoring service, such as Datadog, when your SDKs are configured to run in daemon mode. Because the Relay Proxy's data store communicates directly with the SDKs when the Relay Proxy is in daemon mode, an external monitoring service can provide information about problems that might otherwise be lost during an outage.
If you configure your SDKs for daemon mode, or if you are using synced segments or larger list-based segments with server-side SDKs, then you must use a persistent store with the Relay Proxy:
- If you are using daemon mode, then you can use DynamoDB, Redis, or Consul as a persistent store.
- If you are using synced segments or larger list-based segments, then you can only use DynamoDB or Redis. To learn more, read Configuring the Relay Proxy for segments.
We recommend setting an infinite time to live (TTL) on the cache for your persistent store so flags do not evaluate to their fallback values if the Relay Proxy loses its connection to the persistent store. To learn more, read Using a persistent feature store.
The Relay Proxy can only use one persistent store at a time. For example, if you enabled both Redis and DynamoDB it would result in an error.
LaunchDarkly SDKs have their own options for configuring persistent storage. If you configure your SDK to use the Relay Proxy in daemon mode, the SDK needs to be using the same storage configuration as the Relay Proxy. If you are not using daemon mode, the two configurations are completely independent. For example, you could have a relay using Redis, but a client using DynamoDB or not using persistent storage at all.
Here is a diagram showing how a persistent store works with the Relay Proxy in proxy mode:
If you are not using synced segments or larger list-based segments with server-side SDKs, and are not running any SDKs in daemon mode, we do not recommend using a persistent store. To learn more, read the Relay Proxy GitHub repository's Persistent storage.
Expand Using DynamoDB with the Relay Proxy
DynamoDB does not support storing values greater than 400KB, including the size of the column metadata. Using DynamoDB as a persistent feature store with the Relay Proxy will not work if the JSON representation of a segment exceeds that size. To learn more, read the AWS documentation on item size.
We generally recommend using DynamoDB for persistent storage with the Relay Proxy, because the Relay Proxy doesn't support Redis in cluster mode or other sharding. However, using DynamoDB can incur higher costs. The Relay Proxy and LaunchDarkly SDKs will continually write updates to DynamoDB while in proxy mode. To mitigate this, consider running multiple Relays in AWS without a persistent store.
Expand Using Redis with the Relay Proxy
If you use Redis with the Relay Proxy, each of your Redis hosts will need enough RAM to load the full set of segments and flag configurations, because the Relay Proxy doesn't support Redis in cluster mode or other sharding. The Relay Proxy will not realize that Redis is empty if it became empty after the Relay Proxy fully initialized. Redis’ default configuration empties the database on reboot, so you must put Redis in persistent storage mode.
If you want to use synced segments or larger list-based segments with server-side SDKs, you must use a persistent store. You can either the Relay Proxy with a persistent store, or a persistent store integration. You do not need to use both. To learn more, read Segment configuration for synced segments and larger list-based segments.
If you want to use synced segments or larger list-based segments with server-side SDKs, you must upgrade the Relay Proxy to version 6.4.0 or above.
LaunchDarkly uses different implementations for different types of segments so that all of your segments have good performance. Some segments require the Relay Proxy if you are using server-side SDKs.
Both larger list-based segments, defined as those with more than 15,000 entries, and segments synced from external tools are larger than LaunchDarkly can fit into its streaming and in-memory protocol. To use these segments with the Relay Proxy, you must configure the Relay Proxy to use either Redis or DynamoDB for persistent storage. The Relay Proxy populates and stores segment data in the persistent data store, which your SDK then uses for flag evaluation.
Here is a diagram showing how these "big segments" work with the Relay Proxy:
If your SDKs are already configured to use the Relay Proxy without a data store, you will need to reconfigure them to connect to the store in order to use these segments. To learn more, read Persistent data stores and the Relay Proxy GitHub repository's Persistent storage.
Here are the requirements for using synced segments or larger list-based segments with client-side and server-side SDKs and the Relay Proxy:
- If you use a client-side SDK, there's no additional setup required. However, if you use the Relay Proxy with a client-side SDK, the Relay Proxy must be configured to use persistent storage with Redis or DynamoDB.
- If you use a server-side SDK, you must use the Relay Proxy and configure your server-side SDKs to use the same persistent storage as the Relay Proxy for segments.
- The persistent store and feature store configurations for your SDK are separate. If you are using a feature store for your SDK, you can use either the same or a different persistent store for your segments. For example, if you configure your SDK to use Redis for a feature store, you can still configure it to use DynamoDB for the persistent store for segments.
In unusual cases, server-side SDKs may return incorrect evaluations if the required segments data is unavailable. If an SDK tries to evaluate a flag rule that depends on a big segment but the segment data is unavailable, it continues evaluating the rest of the rules and records this problem in the
EvaluationReason. In this case, the evaluation will return the result based on the remaining flag rules instead of the fallback value. To understand when and if this is happening, you can add code that examines the
You can secure traffic into the Relay Proxy with TLS connections, and also set an environment variable to convey Relay Proxy traffic through another proxy.
As a best practice, we recommend enabling TLS on all inbound connections to the Relay Proxy. This ensures that inbound traffic to the Relay Proxy is secure.
To enable TLS on inbound connections, position the Relay Proxy behind a secure load balancer.
In some cases, you may want to pass relay traffic through a proxy when it communicates with LaunchDarkly's services. Go's standard HTTP library provides a built-in HTTPS proxy.
If you include the
HTTPS_PROXY environment variable in your configuration, the SDK will proxy all network requests through the URL you provide. Configuration instructions for Mac, Linux, and Windows systems appear below.
To set the
HTTPS_PROXY environment variable: