Proxy Mode
Overview
This topic explains proxy mode configuration for the Relay Proxy.
This table shows recommended configuration options:
| Configuration | Recommendation | Notes |
|---|---|---|
| Automatic configuration | Enable if not using a persistent store for restart or scale resiliency | Automatic configuration allows you to avoid re-deploys when adding new projects or environments or rotating SDK keys. LD Relay cannot start if the automatic configuration endpoint is down even when a persistent store is used. If the ability to restart or add LD Relay nodes while LaunchDarkly is unavailable is critical, do not use automatic configuration |
| Event forwarding | Enable | Allow SDKs to forward events to LD Relay to reduce outbound connections and offload compression |
| Metrics | Enable | Enable at least one of the supported metrics integrations such as Prometheus |
| Persistent Stores | Optional. | Persistent stores can be used to allow the deployment of additional LD Relay instances while LaunchDarkly is unavailable. You may opt instead to provision LD Relay so it can handle at least 1.5x-2x of your production traffic in order to avoid the need to scale LD Relay during short outages. |
| Disconnected Status Time | Optional. | Time to wait before marking an environment as disconnected. The default is 1m and is sufficient for instances with reliable networks. If you are using LD Relay in an unreliable network environment, consider increasing this value |
Here is an example:
[Main]
; Time to wait before marking a client as disconnected.
; Impacts the status page
; disconnectedStatusTime=1m
;; For automatic configuration
[AutoConfig]
key=rel-abc-123
;; Event forwarding when setting the event uri to LD Relay in your SDK
[Events]
enable=true
;; Metrics integration for monitoring and alerting
[Prometheus]
enabled=true
Persistent Stores
Persistent stores can be used to improve reboot and restart resilience for LD Relay in the event of a network partition between your application and LaunchDarkly.
This table shows persistent store configuration options:
| Configuration | Recommendation | Notes |
|---|---|---|
| Cache TTL | Infinite with a negative number, localTTL=-1s | An infinite cache TTL means LD Relay maintains its in-memory cache of all flags, mitigating the risk of persistent store downtime. If the persistent store goes down with a non-infinite cache TTL, you may see partial or invalid evaluations due to missing flags or segments. |
| Prefix or Table name | Use the client-side id | The prefix or table name must be unique per environment. When using autoconfig, the placeholder $CID can be used. This is replaced with the client-side id of the environment. Using the same scheme when statically configuring environments allows for consistency if you switch between these options |
| Ignore Connection Errors | ignoreConnectionErrors=true when AutoConfig is disabled | By default, LD Relay shuts down if it cannot reach LaunchDarkly after the initialization timeout is exceeded. To have LD Relay begin serving requests from the persistent store after the timeout, you must set ignore connection errors to true |
| Initialization Timeout | Tune to your needs, default is 10s | This setting controls how long LD Relay attempts to initialize its environments. Until initialization succeeds, LD Relay serves 503 errors to any SDKs that attempt to connect. What happens when the timeout is exceeded depends on the setting of ignore connection errors. When ignore connection errors is false, which is the default, LD Relay shuts down after the timeout is exceeded. Otherwise, LD Relay begins servicing SDK requests using the data in the persistent store. |
Here is an example:
[Main]
;; You must set ignoreConnectionErrors=true in order for LD Relay to start without a connection to LaunchDarkly. You should set this when using a persistent store for flag availability.
ignoreConnectionErrors=true
;; How long will LD Relay wait for connection to LaunchDarkly before serving requests.
;; If ignoreConnectionErrors is false, LD Relay will exit with an error if it cannot connect to LaunchDarkly within the timeout.
initTimeout=10s;; Default is 10 seconds
;; NOTE: If you are using Automatic Configuration, LD Relay can not start without a connection to LaunchDarkly.
[AutoConfig]
key=rel-abc-123
; When using Automatic Configuration with a persistent store, you must set the prefix using the $CID placeholder.
envDatastorePrefix="ld-$CID"
; if using DynamoDB with a table per environment
;envDatastoreTableName="ld-$CID"
; When not using automatic configuration, set the prefix and/or table name for each environment.
; see https://github.com/launchdarkly/ld-relay/blob/v8/docs/configuration.md#file-section-environment-name
[Redis]
enabled=true
url=redis://host:port
; Always use an infinite cache TTL for persistent stores
localTtl=-1s
[DynamoDB]
enabled=true
tableName=ld
; Always use an infinite cache TTL for persistent stores
localTtl=-1s
SDK Configuration
Configure the endpoints you want to handle using LD Relay. Events must be enabled if you set the events URI. To learn more about configuring endpoints, read Proxy mode.
Infrastructure
-
Minimum 3 instances in at least two availability zones per region.
- On-prem: Consider failure domains in your deployment such as separate racks and power
- Cloud: Follow the guidelines of your hosting provider to qualify for SLAs
-
Highly available load balancer with support for SSE connections
You should target 99.99 percent availability, which matches LaunchDarkly's SLA for flag delivery.
Scaling and performance
In addition to the base scaling and performance guidelines, Proxy Mode has the following considerations:
Server-side SDKs
1 incoming long-lived HTTPS SSE connection per connected server-side SDK instance
Client-side SDKs
- 1 outgoing long-lived HTTPS SSE connection per connected client-side SDK instance with streaming enabled
- 1 incoming HTTPS request per connected client-side SDK every time a flag or segment is updated
LD Relay does not scale well with streaming client-side connections and should be avoided. It can handle polling requests to the base URI without issue. For browser SDKs, you can use LD Relay for initialization and the SaaS for streaming.
Do not point the stream URI of client-side mobile SDKs to LD Relay without careful consideration.