Using the Relay Proxy

Overview

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.

Configuring an SDK to use 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://app.launchdarkly.com, https://sdk.launchdarkly.com, or https://clientsdk.launchdarkly.com, depending on which SDK you use.
• The base URI for the streaming service. The default value is https://stream.launchdarkly.com for server-side SDKs and https://clientstream.launchdarkly.com for client-side and mobile SDKs.
• The base URI for the events service. The default value is https://events.launchdarkly.com or https://mobile.launchdarkly.com, depending on which SDK you use.

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.

To learn more, read Relay Proxy configuration.

Configuring the Relay Proxy for Big Segments

Big Segments are larger than LaunchDarkly can fit into its streaming and in-memory protocol. To use Big 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 Big Segment data in the persistent data store, which your SDK then uses for flag evaluation.

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 Big Segments. To learn more, read Persistent data stores.

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. To learn how to configure server-side SDKs for Big Segments, read Big Segments.

If you use a client-side SDK, you do not need to use the Relay Proxy to use Big Segments. However, if you do use the Relay Proxy with a client-side SDK, the Relay Proxy must be configured to use persistent storage with Redis or DynamoDB.

Using DynamoDB with the Relay Proxy

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.

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.

To learn more, read Persistent storage and Big Segments.

Server-side flag evaluation using Big Segments and the Relay Proxy

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

Validating your Relay Proxy configuration

After you have configured it, follow the procedure below to validate your Relay Proxy configuration:

1. Start your SDK. If the SDK connects successfully, the Relay Proxy is working.

2. To confirm the Relay Proxy is configured correctly, test it by evaluating a feature flag.
3. In the LaunchDarkly UI, change the value of a feature flag so you will receive a different variation in production.
4. Verify in your application that the flag value has changed.

Alternatively, you can validate your Relay Proxy with curl. You must specify your Relay Proxy base URI, SDK key, and evaluation context in the command.

curl -X REPORT localhost:8030/sdk/evalx/context \
  -H "Authorization: sdk-key-123abc" \
  -H "Content-Type: application/json" \
  -d '{"key": "context-key-123abc", "email":"sandy@example.com"}'
COPY

Using the Relay Proxy in different modes

After you set up the Relay Proxy, you can configure your SDKs to run in either proxy mode or daemon mode.

Client-side and mobile SDKs can only use the Relay Proxy in proxy mode. In daemon mode, the SDK connects directly to the Relay Proxy's datastore, which is not a supported behavior for client-side SDKs. Server-side SDKs can use it in either mode.

The Relay Proxy's 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 Relay Proxy to follow the best practices listed in each of the following subsections.

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.

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 SDKs can be configured to use the Relay Proxy in proxy mode:

You should not use a persistent feature store between the Relay Proxy and your application in proxy mode.

Using daemon mode

Optionally, you can configure server-side LaunchDarkly SDKs to communicate directly with 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.

To use daemon mode:

1. Configure your SDK to use a persistent data store. The SDK and the Relay Proxy must use the same data store. To learn how, read Storing data.
2. Configure your SDK to use daemon mode. To learn how, read Using 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.

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.

Here is a diagram showing how SDKs can be configured to use the Relay Proxy in daemon mode:

Securing connections to and from the Relay Proxy

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.

Securing inbound connections to the Relay 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.

Passing Relay Proxy traffic through a proxy

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:

export HTTPS_PROXY=https://web-proxy.domain.com:8080
COPY