Upgrading the Relay Proxy

This topic explains how to upgrade the Relay Proxy, roll back to a previous version if needed, validate your deployment after an upgrade, and plan ahead for end-of-life (EOL) versions.

Before upgrading, review the release notes for any breaking changes, new configuration options, or deprecations. We recommend testing upgrades in a non-production environment first.

Upgrade procedures

The upgrade procedure depends on how you deployed the Relay Proxy.

Upgrade with Docker

1. Pull the new image version. To float the minor and patch versions within a major version, use a pattern like v8-:

   Float minor and patch versionsPin to a specific version

   $
   docker pull launchdarkly/ld-relay:v8-static-debian12-nonroot

2. Stop the running container and start a new one using the updated image with the same configuration you used originally.

3. Validate the deployment.

Upgrade with Helm

1. Update the Helm chart repository:

   Update chart repository

   $
   helm repo update launchdarkly-ld-relay

2. Review available chart versions:

   List available chart versions

   $
   helm search repo launchdarkly-ld-relay/ld-relay --versions

3. Run helm upgrade:

   Upgrade to latest chart versionUpgrade to a specific chart version

   $
   helm upgrade relay launchdarkly-ld-relay/ld-relay --values ./values.yaml

4. Monitor the rollout:

   Monitor rollout status

   $
   kubectl rollout status deployment/relay

5. Validate the deployment.

Upgrade a standalone binary

To upgrade a standalone binary:

1. Download the new release binary from the Relay Proxy GitHub releases page.
2. Stop the running Relay Proxy process.
3. Replace the binary with the downloaded version.
4. Restart the Relay Proxy using your existing configuration file or environment variables.
5. Validate the deployment.

Rolling back to a previous version

The rollback procedure depends on how you deployed the Relay Proxy.

Roll back with Docker

Stop the container and start a new one using the image tag for the previous version. You can find all available image tags on Docker Hub.

Roll back with Helm

Use helm rollback to revert to a previous release:

$
helm history relay

$
helm rollback relay <REVISION_NUMBER>

Roll back a standalone binary

Stop the process, replace the binary with the previous version, and restart using your existing configuration.

Validate a deployment

After upgrading or rolling back, confirm that the Relay Proxy is healthy and serving traffic correctly.

Check the status endpoint

Make a GET request to the /status endpoint. No authentication is required:

$
curl -X GET localhost:8030/status

A healthy response shows each configured environment as connected. If any environment shows as disconnected, check your SDK keys and network connectivity. To learn more about the status endpoint and its response format, read Monitoring the Relay Proxy.

Validate flag evaluation

After confirming the status endpoint, verify that flag evaluations are working as expected by starting an SDK and confirming it connects successfully. You can also change a flag value in the LaunchDarkly UI and verify the updated value appears in your application.

Review metrics after upgrade

Watch for unexpected changes in connection counts, error rates, or latency after the upgrade. To learn more, read Monitoring the Relay Proxy.

Plan for EOL versions

We recommend the following strategies to Plan for EOL versions.

Support windows

LaunchDarkly supports each Relay Proxy minor version for approximately one year after releasing a newer minor version. After a version reaches its EOL date, LaunchDarkly no longer provides security patches, bug fixes, or support for that version. To see current EOL dates for each version, read Versioning policy.

Recommended upgrade timeline

When your running version is within 90 days of its EOL date:

1. Review the release notes for all versions between your current version and the latest release. Pay particular attention to breaking changes and required configuration updates.
2. Test the upgrade in a non-production environment and validate behavior using the steps in Validating a deployment.
3. Schedule the production upgrade to complete before the EOL date.

Version compatibility

The Relay Proxy uses semantic versioning:

• Patch upgrades, for example, 8.18.0 to 8.18.1: Safe to apply without configuration changes.
• Minor upgrades, for example, 8.17.x to 8.18.x: May include new features or deprecations. Review the release notes before upgrading.
• Major upgrades, for example, 7.x to 8.x: May include breaking changes and require configuration updates. Review the migration guide in the GitHub repository before upgrading.

The Relay Proxy is backward compatible with LaunchDarkly SDKs. You do not need to upgrade your SDKs in lockstep with the Relay Proxy.