Skip to main content

Migrate from Unleash Proxy

Unleash Edge is the successor of the now-deprecated Unleash Proxy. It functions as a lightweight read replica of your Unleash instance, designed to scale your feature flag infrastructure significantly.

While Edge maintains the same security and privacy guarantees as the Proxy, it offers fundamental improvements in performance and architecture. This guide details the differences between the two services and provides steps to migrate your existing setup.

Key differences​

FeatureUnleash ProxyUnleash Edge
PerformanceHandles hundreds of requests per second (RPS).Handles tens of thousands of RPS with lower memory usage.
EnvironmentsSupports a single environment per instance. Requires separate instances for Development and Production.Supports multiple environments in a single instance. Dynamically routes requests based on the API token.
Upstream URLRequires the /api suffix (https://unleash-instance.com/api).No /api suffix (https://unleash-instance.com).
Backend SDKsRequires experimental flags and specific configuration.Supported out of the box.
LanguageNode.jsRust (Single binary, no runtime dependencies).

Migration path: Hosted Edge​

If you are migrating to Enterprise Edge hosted, you do not need to deploy any infrastructure.

  1. Request Enterprise Edge: Contact your customer success representative to request Enterprise Edge.
  2. Get your Edge URL: Note the specific regional URL provided in the Admin UI (for example, https://<region>.unleash-edge.com).
  3. Update SDKs: Update your frontend and backend SDKs to point to this new Edge URL instead of your old Proxy URL.

Migration path: Self-hosted Edge​

For self-hosted setups, you must replace your Proxy container with the Edge container and update your configuration.

1. Update the upstream URL​

The most common configuration error during migration is the URL format used to connect Edge to Unleash.

- UNLEASH_URL=https://your-instance.com/api
+ UPSTREAM_URL=https://your-instance.com

2. Consolidate instances​

If you previously ran separate Proxy instances for development and production, you can now replace them with a single Edge instance. Edge determines the correct environmentfrom the API token provided by the SDK and serves responses from its local cache accordingly.

Deploy a single Edge container. Provide a startup token that has access to both environments (or use a wildcard token).

3. Configure tokens​

Edge handles tokens differently than the Proxy. Unlike the Proxy, where you could define arbitrary secrets, Edge requires valid Unleash tokens to fetch data. All tokens used by clients must be valid tokens generated in the Unleash Admin UI.

To serve any traffic (even for frontend clients), Edge must have the feature data in its cache. You must start Edge with at least one backend token that covers the projects and environments you intend to serve.

4. Deploy and update networking​

Deploy the Edge container (listening on port 3063 by default) in place of your Proxy container. Update your load balancer or ingress rules to direct traffic to the new service.

5. Verify SDK connections​

Ensure your frontend and backend SDKs are pointing to the Edge URL. No code changes are required in the SDKs themselves; they use the standard client and frontend APIs.

Advanced concepts​

Once migrated, you can leverage features that were difficult or not feasible with the Proxy.

Daisy chaining​

You can chain Edge instances to create complex topologies. For example, a central Edge node can sync with Unleash, while regional Edge nodes sync with the central node.

  • Configuration: Point the downstream Edge's UPSTREAM_URL to the upstream Edge instance.
  • Metrics: Metrics propagate up the chain from the SDK -> Regional Edge -> Central Edge -> Unleash.

For more information, see Daisy chaining.

Offline mode​

Edge supports a dedicated Offline mode for local development or air-gapped environments. This replaces the need to run a local Proxy with a mock config. See Offline mode configuration for details.

Unsupported features in Edge​

Edge is designed for scale and efficiency, which necessitates dropping support for some legacy features:

  • Custom strategies: Edge does not support custom activation strategies. You must migrate these to standard strategy constraints.
  • Context enrichers: The Proxy's experimental context enrichers are not supported in Edge.
  • Custom JS integration: Since Edge is written in Rust, you cannot wrap it in custom JavaScript code like the Node.js Proxy.