• Home
  • Integrations
  • SDKs
  • Guides
  • API docs
No results for ""


Using the Relay Proxy

Read time: 5 minutes
Last edited: Dec 15, 2021


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 the Relay Proxy, read Deploying the Relay Proxy.

Configuring an SDK to use the Relay Proxy

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

The SDK uses these values to determine where to request flag updates. Change the values to point to the Relay Proxy URL instead of directly to LaunchDarkly's services.

You do not need to set all three properties to configure an SDK

Each SDK requires a different property or set of properties during configuration. Depending on which SDK you use and how you configure it, you may need to set different properties.

You do not need to set all the properties listed above to successfully configure an SDK. Precise implementation details to establish a connection vary depending on which SDK you use.

To learn more, read your SDK's documentation.

Configuring the Relay Proxy for Big Segments

This feature is not available on all versions of the Relay Proxy

If you want to use Big Segments with server-side SDKs, you must upgrade the Relay Proxy to version 6.4.0 or above.

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 stores Big Segment data in the persistent data store, which your SDK then uses for flag evaluation. 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, there's no additional setup required to use Big Segments. 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.

To learn more, read Persistent storage and Big Segments.

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.
Look for connection or environment-related errors

Error messages on initialization, including messages saying an environment was not found, may indicate that you configured the Relay Proxy incorrectly. These messages may appear when LaunchDarkly cannot validate an SDK key or when there is a connection issue to LaunchDarkly.

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

Alternatively, you can validate your Relay Proxy with curl. Note that you need to specify your Relay Proxy base URL, SDK key, and user details in the command:

curl -X REPORT localhost:8030/sdk/eval/user -H "Authorization: YOUR_SDK_KEY" -H "Content-Type: application/json" -d '{"key": "a00ceb", "email":"barnie@example.org"}'

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 should only use the Relay Proxy in proxy mode. Server-side SDKs can use it in either mode. In daemon mode, the SDK connects directly to the Relay Proxy's datastore. This is not a supported behavior for client-side SDKs.

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.

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:

SDKs configured to use the Relay Proxy while in proxy mode.
SDKs configured to use the Relay Proxy while 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 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 enable daemon mode:

  1. Configure your SDK to use a persistent data store. The SDK and the Relay Proxy must use the same data store.
  2. Configure your SDK to use run in 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.

Restoring your SDK to proxy mode

If you have set your SDK to daemon mode and wish to restore 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 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:

SDKs configured to use the Relay Proxy while in daemon mode.
SDKs configured to use the Relay Proxy while 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.

Set the HTTPS_PROXY environment variable on Mac/Linux systems:

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

Set the HTTPS_PROXY environment variable on Windows systems:

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