Skip to main content

Edge and Proxy hosting strategies

This document describes the main ways of hosting Unleash Edge (or alternatively Unleash Proxy) alongside the Unleash API and the tradeoffs between self-hosting compared to using the Frontend API that Unleash hosts for you. Whether you're hosting Unleash yourself or have a managed solution will be a key consideration.

Warning

Edge is the next-gen replacement of the Unleash proxy and is recommended to be used over the proxy in most cases, with the exception of the scenario where custom strategies are being used as Edge does not support these.

Unleash-hosted Frontend API vs self-hosted Edge/Proxy​

Which way is right for you will depend on your setup and your needs.

In general, we recommend you use Edge over the Frontend API, but we do recognize that self-hosting requires some extra work on your part and that not all our customers need it.

If you want Unleash to host the Frontend API for you, you should be aware of the following limitations:

  • This is only available to Pro and Enterprise customers who have signed up for a managed Unleash instance.
  • We allow short spikes in traffic and our adaptive infrastructure will automatically scale to your needs.
  • Please check the Fair Use Policy to see the limits of the Unleash-hosted Frontend API.
  • There's no guarantee that it'll be geographically close to your end users, this means your end users might be getting slower response times on feature flag evaluations.
  • When we host the frontend API, we will also receive whatever end-user data you put in the Unleash context. This may or may not be an issue depending on your business requirements.

Hosting Edge requires a little more setup than the Unleash-hosted Frontend API does, but it offers a number of benefits over both the frontend API and Proxy:

  • You can scale Edge instances horizontally and automatically.
  • There's no request cap or extra charges.
  • Edge can handle multiple sets of API tokens and sync these automatically. Compared to the legacy proxy, it is not necessary to set up single instances per token.
  • A key benefit of Edge is its ability to dynamically update new tokens while running. This greatly simplifies scaling up additional application workloads that leverage new tokens without the need to restart the instance or make large changes to infra, as was the prior requirement with the proxy.
  • You can arrange for Edge to be close to your applications, minimizing response times.
  • You have full control of all your user data. None of the data that Edge receives is ever sent to the Unleash API. This keeps your data in your hands.
  • You can easily add more Edge instances in different regions, as described in the multi-region section.

Unleash hosts everything​

Availability

This setup is only available to Pro and Enterprise customers.

Unleash no longer hosts instances of the proxy, but makes the Frontend API available to all Pro and Enterprise customers. The API is backed by an Amazon RDS database. Your applications can connect to the frontend API from your own cloud or from other hosting solutions.

In order to access the frontend API you'll need:

  • A Frontend API key for the environment you'd like to use.
  • The Frontend API URL. This will be your Unleash instance's URL followed by /api/frontend.

This is the simplest, but also most limited (by far) way to use Unleash client SDKs. In this setup, Unleash hosts both the Unleash API and the Unleash frontend API. With Unleash hosting, you'll only need to worry about the Frontend API keys and the URL to access the endpoint.

While this is easy to get started with, it comes with the limitations described in the section on tradeoffs between self-hosted and Unleash-hosted setups.

Unleash hosts the API, you host Edge​

Availability

This setup is only available to Pro and Enterprise customers.

An architecture diagram of using Edge in a setup where Unleash hosts the API and you host the proxy.

You host Edge yourself. It runs in a standalone container alongside your other applications in your cloud or hosting setup. Unleash manages the Unleash API, the admin UI, and the backing database in our AWS setup; the API and the UI run together in a Kubernetes deployment and connect to an Amazon RDS database.

You'll need to configure Edge and the SDKs.

On Unleash​

  • Create one or more client API tokens scoped to the projects/environments you wish to use the Edge instance for. Refer to how to create API tokens for the steps to create one.
  • Create frontend tokens for the frontend apps that will retrieve feature flags from Edge.

On Edge​

Edge will fetch feature flags from the specified upstream Unleash instance for every client API key it has been made aware of, either during startup (recommended) or separate endpoint requests. It will then periodically sync features with upstream.

It will then accept frontend or backend tokens from application SDKs.

Warning

Make sure to use the correct token type for your use case:

  • Frontend API: Use for frontend-facing apps; Edge returns application-specific context.
  • Client API: Use for backend SDKs; Edge returns the entire flag payload for the scope of the token (project/environment).

Start Edge and populate flag cache​

This initial command will populate the flag cache on startup using the client token specified in the environment variable:

docker run -p 3063:3063 -e TOKENS='CLIENT_API_TOKEN' -e UPSTREAM_URL='UPSTREAM_URL' unleashorg/unleash-edge:v8.1 edge

The following can be used to pass new tokens to Edge for different project/environment scopes:

curl --location --request GET 'http://0.0.0.0:3063/api/client/features' \ --header 'Content-Type: application/json' \ --header 'Authorization: NEW_TOKEN' \ --data-raw ''

On SDKs​

  • Point frontend/client SDKs to Edge endpoints:
    • Backend SDKs: /api/client.
    • Frontend SDKs: /api/frontend, /api/proxy.

You host everything​

Availability

This setup is only available open-source and Enterprise customers.

An architecture diagram of using the proxy in a single-region, self-hosted setup.

You host everything yourself. Everything runs where and how you configure it to.

To configure Edge and the SDKs, follow steps in the previous section on Unleash hosts the API, you host Edge

As you might expect, doing everything yourself gives you the most flexibility, but also requires the most effort. However, if you're already hosting Unleash yourself, this shouldn't be any more difficult than the previous section.

As described in the section on tradeoffs between self-hosted and Unleash-hosted setups, running Edge yourself gives you a number of benefits.

Multi-region​

An architecture diagram of using the proxy in a multi-region, self-hosted setup.

You can also use Edge for a multi-region setup. You can run Edge in a different region to the API and still connect to the API. Because Edge runs closer to your applications it still provides you benefits in terms of quicker response times. Everything should be configured as described in the you host everything section or the Unleash hosts the API, you host Edge section. You can add as many Edge instances in as many extra regions as you want.

Legacy: Unleash hosts the API, you host the Proxy​

Recommendation

This approach is no longer recommended. You should use Unleash Edge instead of the Unleash proxy. If you are an existing Proxy user, see our Edge migration guide for a guide on how to migrate. Please take note of the section covering features Edge does not currently support in the same linked document before planning a migration.

Availability

This setup is only available to Pro and Enterprise customers.

An architecture diagram of using the proxy in a setup where Unleash hosts the API and you host the proxy.

You host the proxy yourself. It runs in a standalone container alongside your other applications in your cloud or hosting setup. Unleash manages the Unleash API, the admin UI, and the backing database in our AWS setup: the API and the UI run together in a Kubernetes deployment and connect to an Amazon RDS database.

You'll need to configure the proxy and the proxy client SDKs.

For the proxy, configure:

For the proxy client SDK, configure:

  • One of the proxy client keys that you configured for the proxy.
  • The proxy's endpoint. This will depend on where and how you're hosting the proxy, but will typically end in /proxy.

This setup requires a little more setup on your part than the Unleash-hosted proxy does, but it offers all the benefits described in the section on tradeoffs between self-hosted and Unleash-hosted setups.