• HOME
  • INTEGRATIONS
  • SDKS
  • GUIDES
  • API DOCS
No results for ""
EXPAND ALL
launchdarkly.com

EDIT ON GITHUB

Using the Relay Proxy

Read time: 4 minutes
Last edited: Jun 18, 2021

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

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, can indicate that the proxy is configured incorrectly. These messages can appear when an SDK key cannot be validated or when there is a connection issue to LaunchDarkly.
  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 see 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. Note that you need to specify your Relay Proxy base URL, SDK key, and user details in the command:

1curl -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.

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

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.

To learn more about setting up a persistent data store for use in daemon mode, read Using a persistent feature store without connecting to LaunchDarkly.

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.

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:

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

Set the HTTPS_PROXY environment variable on Windows systems:

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