mirror of
https://github.com/Unleash/unleash.git
synced 2026-01-05 20:06:22 +01:00
docs: enterprise edge (#11083)
This commit is contained in:
Melinda Fekete
GitHub
parent
a96e41a3ef
commit
232a8634cd
@ -35,30 +35,46 @@ This fully-managed solution is designed for high availability, featuring the fol
|
||||
|
||||
### Unleash Enterprise Edge Cloud
|
||||
|
||||
[Unleash Enterprise Edge](https://www.getunleash.io/unleash-enterprise-edge), our cloud-hosted Edge offering, provides enterprise-grade security, full observability, and multi-region redundancy. Here are the key aspects of the offering:
|
||||
[Unleash Enterprise Edge](https://www.getunleash.io/unleash-enterprise-edge), our cloud-hosted Edge offering, provides enterprise-grade security, full observability, streaming, and multi-region redundancy. Here are the key aspects of the offering:
|
||||
|
||||
- **Multi-AZ deployments:** Edge instances run across at least two AZs within each region.
|
||||
- **Multi-region deployment:** Edge is available in multiple global regions. SDKs automatically connect to the nearest available region. Traffic fails over to other regions if one region becomes unavailable.
|
||||
- **Resilience:** Edge caches flag configurations locally. SDKs connected to Edge can continue evaluating flags even if the connection to the primary Unleash API server is temporarily lost.
|
||||
- **Scalability and performance:** Edge acts as a read-only cache, handling numerous SDK connections. Instead of relying on periodic polling, Edge and the Unleash server use a high-speed streaming protocol to sync flag changes in milliseconds.
|
||||
|
||||
[Enterprise Edge](https://www.getunleash.io/unleash-enterprise-edge) is available in the following 11 global data centers across North America, Europe, and Asia, allowing you to achieve low latency, high resilience, and optimal performance:
|
||||
- US East (Ohio): `us-east-2`
|
||||
- US East (N. Virginia): `us-east-1`
|
||||
- US West (Oregon): `us-west-2`
|
||||
- Asia Pacific (Mumbai): `ap-south-1`
|
||||
- Asia Pacific (Singapore): `ap-southeast-1`
|
||||
- Asia Pacific (Sydney): `ap-southeast-2`
|
||||
- Asia Pacific (Tokyo): `ap-northeast-1`
|
||||
- Europe (Frankfurt): `eu-central-1`
|
||||
- Europe (Ireland): `eu-west-1`
|
||||
- Europe (London): `eu-west-2`
|
||||
- Europe (Paris): `eu-west-3`
|
||||
[Enterprise Edge](https://www.getunleash.io/unleash-enterprise-edge) is available in the following 17 global data centers across North and South America, Europe, and Asia, allowing you to achieve low latency, high resilience, and optimal performance:
|
||||
|
||||
**US:**
|
||||
- us-east-1 (Virginia)
|
||||
- us-east-2 (Ohio)
|
||||
- us-west-1 (N. California)
|
||||
- us-west-2 (Oregon)
|
||||
|
||||
**Europe:**
|
||||
- eu-central-1 (Frankfurt)
|
||||
- eu-west-1 (Ireland)
|
||||
- eu-west-2 (London)
|
||||
- eu-west-3 (Paris)
|
||||
- eu-north-1 (Stockholm)
|
||||
|
||||
**Asia:**
|
||||
- ap-south-1 (Mumbai)
|
||||
- ap-northeast-3 (Osaka)
|
||||
- ap-northeast-2 (Seoul)
|
||||
- ap-northeast-1 (Tokyo)
|
||||
- ap-southeast-1 (Singapore)
|
||||
- ap-southeast-2 (Sydney)
|
||||
|
||||
**Canada:**
|
||||
- ca-central-1 (Central)
|
||||
|
||||
**South America:**
|
||||
- sa-east-1 (São Paulo)
|
||||
|
||||
|
||||
## Hybrid
|
||||
|
||||
In this hybrid model, Unleash hosts the API server and Admin UI, while you host Unleash Edge instances yourself. You run Edge as a container within your own infrastructure, close to your applications. This gives you control over Edge's location and its network environment. 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.
|
||||
In this hybrid model, Unleash hosts the API server and Admin UI, while you host Unleash Enterprise Edge instances yourself. You run Edge as a container within your own infrastructure, close to your applications. This gives you control over Edge's location and its network environment. 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.
|
||||
|
||||
|
||||
|
||||
@ -90,7 +106,7 @@ Point your SDKs to your self-hosted Edge instance's URL.
|
||||
|
||||
## Self-hosted
|
||||
|
||||
In this model, you host and manage all components: the Unleash API server, the database, the Admin UI, and Unleash Edge instances.
|
||||
In this model, you host and manage all components: the Unleash API server, the database, the Admin UI, and Unleash Enterprise Edge instances.
|
||||
|
||||
|
||||
|
||||
@ -101,24 +117,22 @@ In addition to [configuring Edge](#configure-edge), you must also set up the Unl
|
||||
|
||||
## Unleash Edge options
|
||||
|
||||
### Unleash Enterprise Edge vs Unleash Edge Open-Source
|
||||
### Unleash Enterprise Edge: Hosted vs. Self-Hosted
|
||||
|
||||
The following table compares the key differences between using the Unleash Enterprise Edge Cloud and Unleash Edge Open-Source.
|
||||
The following table compares the operational differences between using Unleash Enterprise Edge Hosted and Unleash Enterprise Edge Self-hosted.
|
||||
|
||||
| Feature | Unleash Enterprise Edge Cloud | Unleash Edge: Open-Source |
|
||||
| :---------------------- | :------------------------------------------------------------------------------------------- | :---------------------------------------------------------------------------------------------------------- |
|
||||
| **Infrastructure**| Managed entirely by Unleash | Managed entirely by you |
|
||||
| **Operational effort** | Minimal setup and no ongoing maintenance required from you | Requires setup, deployment, scaling, monitoring, and maintenance effort from you |
|
||||
| **Infrastructure cost** | Included in Unleash Enterprise Edge fee | Pay for the compute, network, storage, and operational overhead on your infrastructure |
|
||||
| **Setup and configuration**| Point your SDKs to the provided Unleash Edge URL | Pull Docker image, configure upstream URL and API tokens via environment variables, deploy and manage the containers |
|
||||
| **Scalability** | Handled automatically by Unleash | Monitor load and scale Edge instances manually or via automation |
|
||||
| **High availability** | Managed by Unleash with multi-AZ and multi-region redundancy and failover | Requires you to design and implement high availability (e.g., multiple instances, load balancers, potentially across AZs) |
|
||||
| **Security and updates** | Handled automatically by Unleash | You manage host and container security, network rules, and apply Edge updates |
|
||||
| **Observability** | Monitor health, replica count, memory usage, CPU, latency, and more directly from Unleash | You need to set up and manage your own monitoring and logging solutions for Edge |
|
||||
| **Deployment** | Available in [11 global regions](#unleash-enterprise-edge-cloud) | Deploy within your own infrastructure, VPC, or on-premises, wherever you can run containers |
|
||||
| **Latency**| Configuration changes are pushed instantly to Enterprise Edge, ensuring it's always up to date; no polling required—changes propagate in real time | Relies on polling at a configured interval to check for updates; this introduces a delay between when changes are made and when they take effect |
|
||||
| **Client-side context** | Processed on Unleash-managed Edge infrastructure, but does not reach the central Unleash server or database | Processed entirely within your infrastructure |
|
||||
| **Support** | Enterprise-grade support with SLAs and uptime guarantees | No formal SLA |
|
||||
| Feature | Enterprise Edge Hosted | Enterprise Edge Self-hosted |
|
||||
| ----- | ----- | ----- |
|
||||
| **Infrastructure** | Managed entirely by Unleash | Managed entirely by you |
|
||||
| **Operational effort** | Minimal setup and no ongoing maintenance required from you | Requires setup, deployment, scaling, monitoring, and maintenance effort from you |
|
||||
| **Infrastructure cost** | Included in Unleash Enterprise Edge fee | You pay for the compute, network, storage, and operational overhead on your infrastructure |
|
||||
| **Setup and configuration** | Point your SDKs to the provided Unleash Edge URL | Pull Docker image, configure upstream URL and API tokens via environment variables, deploy and manage the containers |
|
||||
| **Scalability** | Handled automatically by Unleash | Monitor load and scale Edge instances manually or via automation |
|
||||
| **High availability** | Managed by Unleash with multi-AZ and multi-region redundancy and failover | Requires you to design and implement high availability (e.g., multiple instances, load balancers, potentially across AZs) |
|
||||
| **Security and updates** | Handled automatically by Unleash | You manage host and container security, network rules, and apply Edge updates |
|
||||
| **Observability** | Full platform monitoring included | Edge application metrics reported to Unleash UI; Infrastructure monitoring managed by you |
|
||||
| **Deployment** | Available in 17 global regions | Deploy within your own infrastructure, VPC, or on-premises, wherever you can run containers |
|
||||
| **Client-side context** | Processed on Unleash-managed Edge infrastructure, but does not reach the central Unleash server or database | Processed entirely within your infrastructure (maximum privacy) |
|
||||
|
||||
### Using Unleash without Edge
|
||||
|
||||
@ -126,13 +140,3 @@ Using Unleash Edge is optional. You can also access the Unleash API directly usi
|
||||
- **Fair Use Policy:** Sending requests to the Unleash API is subject to limits outlined in the [Fair Use Policy](https://www.getunleash.io/fair-use-policy). While short traffic spikes are accommodated, sustained high traffic might require using Unleash Edge.
|
||||
- **Latency:** Although the Unleash architecture is designed for incredibly fast flag evaluations thanks to caching in the SDKs, the central Unleash API server might not be geographically close to all your end users, potentially increasing flag evaluation latency.
|
||||
- **Data privacy:** When using the Frontend API to talk to Unleash, any end-user data included in the [Unleash Context](/concepts/unleash-context) is sent directly to the Unleash server. Evaluate if this meets your privacy requirements. Using Edge avoids sending this context data directly to the central Unleash API server.
|
||||
|
||||
## Self-hosted Unleash Proxy
|
||||
|
||||
:::note
|
||||
|
||||
Unleash Proxy has been deprecated, use [Unleash Edge](/unleash-edge) instead.
|
||||
:::
|
||||
|
||||
|
||||
If you are currently self-hosting Proxy, see our [Edge migration guide](https://github.com/Unleash/unleash-edge/blob/main/docs/migration-guide) for a guide on how to migrate.
|
||||
|
||||
@ -15,7 +15,7 @@ Unleash is designed for privacy, speed, and resilience, enabling feature flag ev
|
||||
|
||||
The Unleash system consists of several key components.
|
||||
|
||||
|
||||
|
||||
|
||||
### The Unleash API server
|
||||
|
||||
|
||||
@ -218,7 +218,7 @@ With Unleash Enterprise Edge Cloud, this complexity is handled for you—you sim
|
||||
- Use initialization tokens: Configure Edge to start with initialization tokens, as this enables Edge to immediately pre-fetch flag configurations upon startup. This ensures low-latency responses to initial SDK requests, particularly when multiple Edge instances are load-balanced and serving frontend API traffic.
|
||||
- Implement health and readiness checks: Integrate the built-in `/health` and `/ready` endpoints with your load balancer and orchestration platform. This ensures that traffic is only directed to healthy Edge instances that have completed their initial configuration loading.
|
||||
|
||||
For more information,refer to the Unleash Edge [deployment guide](/unleash-edge/deploying).
|
||||
For more information,refer to the Unleash Edge [deployment guide](/unleash-edge/deploy).
|
||||
</details>
|
||||
|
||||
### Lower scale or single-region scenarios
|
||||
|
||||
@ -206,7 +206,7 @@ Deployed within your own infrastructure, Edge ensures that PII and sensitive con
|
||||
|
||||
With Edge, you can keep your core Unleash service hidden from the internet while evaluating feature flags at the edge for better performance and scalability. Unleash Enterprise Edge cannot access the [Unleash Admin API](/get-started/unleash-overview#admin-api), minimizing the impact of compromised clients or credentials. In our cloud-hosted offering, you can also define an [IP allow list](#set-up-ip-allow-lists-for-enhanced-security) for the Unleash instance and Hosted Edge to further reduce the attack surface.
|
||||
|
||||
For regulated environments that require continuous availability, you can configure persistent storage—such as Redis or local backup files—to keep feature flag evaluations running, even if the main Unleash server is temporarily unreachable. Learn more about Edge architecture and setup in our [Edge Concepts](/unleash-edge/concepts).
|
||||
For regulated environments that require continuous availability, you can configure persistent storage—such as Redis or local backup files—to keep feature flag evaluations running, even if the main Unleash server is temporarily unreachable. Learn more about Edge architecture and setup in our [Edge overview](/unleash-edge).
|
||||
|
||||
The guide so far has focused on how you can use the features of Unleash to improve your application's security posture, making sure that feature flags are not the weak link. But what about Unleash itself, as a company and SaaS service? You might be asking…
|
||||
|
||||
|
||||
@ -78,7 +78,7 @@ First, make sure your Unleash instance is running (locally or remotely) and gene
|
||||
</TabItem>
|
||||
|
||||
<TabItem value="rust" label="Rust toolchain">
|
||||
If you're comfortable with the Rust toolchain, install the CLI with [cargo binstall](https://github.com/cargo-bins/cargo-binstall?tab=readme-ov-file#installation) (or [from source](/unleash-edge/development-guide)):
|
||||
If you're comfortable with the Rust toolchain, install the CLI with [cargo binstall](https://github.com/cargo-bins/cargo-binstall?tab=readme-ov-file#installation) (or [from source](https://github.com/Unleash/unleash-edge#building-from-source)):
|
||||
|
||||
```shell
|
||||
cargo binstall unleash-edge
|
||||
@ -525,8 +525,8 @@ Congratulations, you've successfully set up Unleash Edge locally!
|
||||
|
||||
Unleash Edge offers a lot of flexibility and advanced configuration options worth exploring:
|
||||
|
||||
1. [Offline mode](/unleash-edge/concepts#offline) - Learn how to configure Unleash Edge to work without an Unleash instance, using a local features file.
|
||||
2. [Pretrusted tokens](/unleash-edge#pretrusted-tokens) - Learn how to explicitly authorize known frontend tokens without upstream validation.
|
||||
3. [Security considerations in production](/unleash-edge/deploying) - Learn how to run Unleash Edge in production with best practices for CORS, health checks, and sensitive endpoints.
|
||||
4. [Persistent cache storage](/unleash-edge/cli#unleash-edge-edge) - Learn how to enable persistent cache storage with options such as `--backup-folder` and `--redis-url`.
|
||||
5. [Advanced CLI configuration](/unleash-edge/cli) - Learn how to customize the CLI behavior with options such as `--base-path`, `--workers`, `--allow-list`, `--edge-request-timeout`, and `--edge-auth-header`.
|
||||
1. [Offline mode](/unleash-edge/deploy#modes-of-operation) - Learn how to configure Unleash Edge to work without an Unleash instance, using a local features file.
|
||||
2. [Pretrusted tokens](/unleash-edge/deploy#pre-trusted-tokens) - Learn how to explicitly authorize known frontend tokens without upstream validation.
|
||||
3. [Security considerations in production](/unleash-edge/configure#security) - Learn how to run Unleash Edge in production with best practices for CORS, health checks, and sensitive endpoints.
|
||||
4. [Persistent cache storage](/unleash-edge/deploy#reliability-and-persistence) - Learn how to enable persistent cache storage with options such as `--backup-folder` and `--redis-url`.
|
||||
5. [Advanced CLI configuration](/unleash-edge/configure) - Learn how to customize the CLI behavior with options such as `--base-path`, `--workers`, `--allow-list`, `--edge-request-timeout`, and `--edge-auth-header`.
|
||||
|
||||
@ -18,6 +18,11 @@ This is an example of a feature that is only available to Enterprise customers w
|
||||
- [Enterprise](https://www.getunleash.io/pricing) - Available as pay-as-you-go or as an annual contract, either as cloud-hosted or self-hosted.
|
||||
- Pro - Currently not offered.
|
||||
|
||||
# Unleash Edge
|
||||
|
||||
- Open Source - Deprecated in favor of the Enterprise edition. Long-term support starts December 10, 2025. End-of-life is December 31, 2026.
|
||||
- Enterprise - Available as cloud-hosted or self-hosted. Requires Unleash Enterprise v7.3+.
|
||||
|
||||
## Beta features
|
||||
|
||||
Some new Unleash features are tagged as `BETA` in the documentation. This means that the feature may be subject to change or discontinuation. Unleash may decide to enable such features for a select number of customers only. If you're interested in trying out a beta feature, please reach out to Customer Success at beta@getunleash.io.
|
||||
|
||||
223
website/docs/unleash-edge/configure.mdx
Normal file
223
website/docs/unleash-edge/configure.mdx
Normal file
@ -0,0 +1,223 @@
|
||||
---
|
||||
title: Configure Unleash Edge
|
||||
---
|
||||
|
||||
If you are using [Unleash Enterprise Edge hosted](/unleash-edge#enterprise-edge-hosted), these configurations are managed for you automatically. You do not need to set environment variables or manage tokens via CLI.
|
||||
|
||||
This reference covers all configuration options for Enterprise Edge self-hosted.
|
||||
|
||||
## Configure the operating mode
|
||||
|
||||
Edge supports two modes: [Edge mode](#edge-mode) (default) and [Offline mode](#offline-mode).
|
||||
|
||||
### Edge mode
|
||||
|
||||
Connects to Unleash and synchronizes feature flags. Use for production deployments.
|
||||
|
||||
```shell
|
||||
unleash-edge edge --upstream-url https://your-unleash.com --tokens your-token
|
||||
```
|
||||
|
||||
### Offline mode
|
||||
|
||||
Serves flags from a local file without upstream connection. Use for development, testing, or air-gapped environments. See [Offline mode configuration](#offline-mode-configuration) for all available options.
|
||||
|
||||
```shell
|
||||
unleash-edge offline \
|
||||
--bootstrap-file /path/to/features.json \
|
||||
--client-tokens your-token
|
||||
```
|
||||
|
||||
In offline mode, Edge validates requests against tokens you provide at startup rather than validating with Unleash. Use `--client-tokens` for [backend SDK](/sdks#backend-sdks) access and `--frontend-tokens` for [frontend SDK](/sdks#frontend-sdks) access.
|
||||
These tokens don't need to exist in Unleash—they serve as shared secrets between your SDKs and Edge.
|
||||
|
||||
To use offline mode, you also need to provide a local file that contains your feature flag configurations.
|
||||
You can create one by exporting your feature flags from Unleash:
|
||||
|
||||
```shell
|
||||
curl -H "Authorization: your-token" \
|
||||
https://your-unleash.com/api/client/features > features.json
|
||||
```
|
||||
|
||||
Alternatively, use a simplified JSON for development:
|
||||
|
||||
```json
|
||||
{
|
||||
"my-feature": { "enabled": true },
|
||||
"another-feature": { "enabled": false, "variant": "control" }
|
||||
}
|
||||
```
|
||||
|
||||
When using offline mode you must specify one or more tokens at startup. These tokens let your SDKs access Edge.
|
||||
Tokens following the Unleash API format `[project]:[environment].<somesecret>` allow Edge to recognize the [project](/concepts/projects) and [environment](/concepts/environments) specified in the token, returning only the relevant features to the calling SDK.
|
||||
On the other hand, for tokens not adhering to this format, Edge will return all features if there is an exact match with any of the startup tokens.
|
||||
Edge does not support multiple [environments](/concepts/environments) in offline mode. All tokens added at startup will receive the same list of features passed in as the bootstrap argument.
|
||||
|
||||
## Configuration reference
|
||||
|
||||
## Global configuration
|
||||
|
||||
These settings apply to the Unleash Edge process regardless of whether it is running in Edge or Offline mode.
|
||||
|
||||
### Server and network
|
||||
|
||||
| Feature | Environment variable | CLI flag | Default | Description |
|
||||
| :---- | :---- | :---- | :---- | :---- |
|
||||
| **Port** | `PORT` | `-p, --port` | 3063 | HTTP port to listen on. |
|
||||
| **Interface** | `INTERFACE` | `-i, --interface` | 0.0.0.0 | Interface to bind to. |
|
||||
| **Base path** | `BASE_PATH` | `--base-path` | "" | Base path for all routes. |
|
||||
| **App name** | `APP_NAME` | `-a, --app-name` | unleash-edge | App name for metrics. |
|
||||
| **Instance ID** | `INSTANCE_ID` | `--instance-id` | ULID | Unique ID for this instance. |
|
||||
| **Req timeout** | `EDGE_REQUEST_TIMEOUT` | `--edge-request-timeout` | 5 | Timeout for incoming requests (seconds). |
|
||||
| **Keepalive** | `EDGE_KEEPALIVE_TIMEOUT` | `--edge-keepalive-timeout` | 5 | Keepalive timeout (seconds). |
|
||||
| **Workers** | `WORKERS` | `-w, --workers` | CPUs | **Deprecated** in 20.0.0. |
|
||||
|
||||
### Security
|
||||
|
||||
| Feature | Environment variable | CLI flag | Default | Description |
|
||||
| :---- | :---- | :---- | :---- | :---- |
|
||||
| **Enable TLS** | `TLS_ENABLE` | `--tls-enable` | false | Bind HTTPS. |
|
||||
| **Server key** | `TLS_SERVER_KEY` | `--tls-server-key` | - | Path to private key. |
|
||||
| **Server cert** | `TLS_SERVER_CERT` | `--tls-server-cert` | - | Path to certificate. |
|
||||
| **TLS port** | `TLS_SERVER_PORT` | `--tls-server-port` | 3043 | Port for HTTPS. |
|
||||
| **Force HTTPS** | - | `--redirect-http-to-https` | false | Redirect HTTP to HTTPS. |
|
||||
| **CORS origin** | `CORS_ORIGIN` | `--cors-origin` | - | Allowed origins (comma-separated). |
|
||||
| **CORS headers** | `CORS_ALLOWED_HEADERS` | `--cors-allowed-headers` | - | Allowed headers. |
|
||||
| **CORS max age** | `CORS_MAX_AGE` | `--cors-max-age` | 172800 | Pre-flight cache duration. |
|
||||
| **CORS exposed** | `CORS_EXPOSED_HEADERS` | `--cors-exposed-headers` | - | Exposed headers. |
|
||||
| **CORS methods** | `CORS_METHODS` | `--cors-methods` | - | Allowed methods. |
|
||||
|
||||
### Access control and proxy
|
||||
|
||||
| Feature | Environment variable | CLI flag | Description |
|
||||
| :---- | :---- | :---- | :---- |
|
||||
| **Allow list** | `ALLOW_LIST` | `--allow-list` | CIDRs allowed to connect (Default `0.0.0.0/0`). |
|
||||
| **Deny list** | `DENY_LIST` | `--deny-list` | CIDRs denied connection. |
|
||||
| **Trust proxy** | `TRUST_PROXY` | `--trust-proxy` | Enabled `Trust X-Forwarded-*` headers. Required if running behind a load balancer to correctly identify client IPs. |
|
||||
| **Trusted servers** | - | `--proxy-trusted-servers` | Comma-separated list of specific IPs/CIDRs to trust. Requires `TRUST_PROXY` to be enabled. |
|
||||
| **Auth header** | `EDGE_AUTH_HEADER` | `--edge-auth-header` | Custom header to use for Edge authorization checks. |
|
||||
| **Token header** | `TOKEN_HEADER` | `--token-header` | Custom header to extract tokens from (Default: `Authorization`). |
|
||||
|
||||
### Logging and debugging
|
||||
|
||||
| Feature | Environment variable | CLI flag | Description |
|
||||
| :---- | :---- | :---- | :---- |
|
||||
| **Log format** | `LOG_FORMAT` | `-l, --log-format` | plain, json, or pretty. |
|
||||
| **Disable all** | - | `--disable-all-endpoint` | Disables /api/proxy/all (Security hardening). |
|
||||
| **Disable metrics batch** | `DISABLE_METRICS_BATCH_ENDPOINT` | `--disable-metrics-batch-endpoint` | Disables `/internal-backstage/metricsbatch`. |
|
||||
| **Disable metrics** | `DISABLE_METRICS_ENDPOINT` | `--disable-metrics-endpoint` | Disables `/internal-backstage/metrics`. |
|
||||
| **Disable features** | `DISABLE_FEATURES_ENDPOINT` | `--disable-features-endpoint` | Disables `/internal-backstage/features`. |
|
||||
| **Disable tokens** | `DISABLE_TOKENS_ENDPOINT` | `--disable-tokens-endpoint` | Disables `/internal-backstage/tokens`. |
|
||||
| **Disable info** | `DISABLE_INSTANCE_DATA_ENDPOINT` | `--disable-instance-data-endpoint` | Disables `/internal-backstage/instancedata`. |
|
||||
|
||||
## Edge mode configuration
|
||||
|
||||
These settings apply when running Unleash Edge in Edge mode.
|
||||
|
||||
### Upstream connection
|
||||
|
||||
| Feature | Environment variable | CLI flag | Default | Description |
|
||||
| :---- | :---- | :---- | :---- | :---- |
|
||||
| **URL** | `UPSTREAM_URL` | `-u, --upstream-url` | - | **Required**. URL to Unleash (no /api). |
|
||||
| **Startup tokens** | `TOKENS` | `-t, --tokens` | - | [Backend tokens](/concepts/api-tokens-and-client-keys#backend-tokens) to bootstrap cache and set scope. |
|
||||
| **Skip SSL** | `SKIP_SSL_VERIFICATION` | `-s, --skip-ssl-verification` | false | **Insecure**. Skips upstream TLS verification. |
|
||||
| **Headers** | `CUSTOM_CLIENT_HEADERS` | `-H, --custom-client-headers` | - | Custom headers to send upstream. |
|
||||
| **Req timeout** | `UPSTREAM_REQUEST_TIMEOUT` | `--upstream-request-timeout` | 5 | Upstream request timeout (seconds). |
|
||||
| **Sock timeout** | `UPSTREAM_SOCKET_TIMEOUT` | `--upstream-socket-timeout` | 5 | Upstream socket timeout (seconds). |
|
||||
| **Keepalive** | `CLIENT_KEEPALIVE_TIMEOUT` | `--client-keepalive-timeout` | 15 | Keepalive duration. |
|
||||
| **Auth header** | `UPSTREAM_AUTH_HEADER` | `--upstream-auth-header` | - | Header for upstream authorization. |
|
||||
|
||||
### Synchronization and polling
|
||||
|
||||
| Feature | Environment variable | CLI flag | Default | Description |
|
||||
| :---- | :---- | :---- | :---- | :---- |
|
||||
| **Metrics interval** | `METRICS_INTERVAL_SECONDS` | `-m, --metrics-interval-seconds` | 60 | How often to push metrics upstream. |
|
||||
| **Refresh interval** | `FEATURES_REFRESH_INTERVAL_SECONDS` | `-f, --features-refresh-interval-seconds` | 15 | How often to poll for feature updates. |
|
||||
| **Token revalidation** | `TOKEN_REVALIDATION_INTERVAL_SECONDS` | `--token-revalidation-interval-seconds` | 3600 | How often to re-validate tokens. |
|
||||
| **Streaming** | `STREAMING` | `--streaming` | false | Enables real-time updates. |
|
||||
|
||||
### Persistence
|
||||
|
||||
| Feature | Environment variable | CLI flag | Default | Description |
|
||||
| :---- | :---- | :---- | :---- | :---- |
|
||||
| **Backup folder** | `BACKUP_FOLDER` | `-b, --backup-folder` | - | Local folder for backups (mutually exclusive with Redis). |
|
||||
| **S3 bucket** | `S3_BUCKET_NAME` | `--s3-bucket-name` | - | S3 bucket for snapshots. |
|
||||
| **Redis URL** | `REDIS_URL` | `--redis-url` | - | Redis connection string. |
|
||||
| **Redis mode** | `REDIS_MODE` | `--redis-mode` | single | Single or cluster mode. |
|
||||
| **Redis host** | `REDIS_HOST` | `--redis-host` | - | Redis hostname (alternative to `REDIS_URL`). |
|
||||
| **Redis port** | `REDIS_PORT` | `--redis-port` | - | Redis port (alternative to `REDIS_URL`). |
|
||||
| **Redis user** | `REDIS_USERNAME` | `--redis-username` | - | Redis username. |
|
||||
| **Redis pass** | `REDIS_PASSWORD` | `--redis-password` | - | Redis password. |
|
||||
| **Redis TLS** | `REDIS_SECURE` | `--redis-secure` | false | Enable TLS. |
|
||||
| **Redis scheme** | `REDIS_SCHEME` | `--redis-scheme` | redis | tcp, tls, redis, rediss, unix. |
|
||||
| **Read timeout** | `REDIS_READ_CONNECTION_TIMEOUT_MILLISECONDS` | `--redis-read-connection-timeout-milliseconds` | 2000 | Timeout for restoring from Redis. |
|
||||
| **Write timeout** | `REDIS_WRITE_CONNECTION_TIMEOUT_MILLISECONDS` | `--redis-write-connection-timeout-milliseconds` | 2000 | Timeout for persisting to Redis. |
|
||||
|
||||
### Observability
|
||||
|
||||
| Feature | Environment variable | CLI flag | Description |
|
||||
| :---- | :---- | :---- | :---- |
|
||||
| **Prometheus URL** | `PROMETHEUS_REMOTE_WRITE_URL` | `--prometheus-remote-write-url` | URL for remote metric write. |
|
||||
| **Push interval** | `PROMETHEUS_PUSH_INTERVAL` | `--prometheus-push-interval` | Interval for pushing metrics (Default 60). |
|
||||
| **Prometheus user** | `PROMETHEUS_USERNAME` | `--prometheus-username` | Auth username. |
|
||||
| **Prometheus pass** | `PROMETHEUS_PASSWORD` | `--prometheus-password` | Auth password. |
|
||||
| **Prometheus ID** | `PROMETHEUS_USER_ID` | `--prometheus-user-id` | User ID. |
|
||||
| **Datadog** | `DATADOG_URL` | `--datadog-url` | Datadog agent URL. |
|
||||
| **OpenTelemetry** | `OTEL_COLLECTOR_URL` | `--otel-collector-url` | OTel collector endpoint. |
|
||||
| **Sentry DSN** | `SENTRY_DSN` | `--sentry-dsn` | Sentry DSN. |
|
||||
| **Sentry rate** | `SENTRY_TRACING_RATE` | `--sentry-tracing-rate` | Tracing rate (Default `0.1`). |
|
||||
| **Sentry debug** | `SENTRY_DEBUG` | `--sentry-debug` | Enable Sentry debugging. |
|
||||
| **Sentry logs** | `SENTRY_ENABLE_LOGS` | `--sentry-enable-logs` | Enable sending application logs to Sentry |
|
||||
|
||||
### Upstream mTLS
|
||||
|
||||
| Environment variable | CLI flag | Description |
|
||||
| :---- | :---- | :---- |
|
||||
| `PKCS8_CLIENT_CERTIFICATE_FILE` | `--pkcs8-client-certificate-file` | Client cert chain (PEM). |
|
||||
| `PKCS8_CLIENT_KEY_FILE` | `--pkcs8-client-key-file` | Client private key (PKCS#8). |
|
||||
| `PKCS12_IDENTITY_FILE` | `--pkcs12-identity-file` | Identity file (.pfx / pkcs12). |
|
||||
| `PKCS12_PASSPHRASE` | `--pkcs12-passphrase` | Passphrase for pkcs12 file. |
|
||||
| `PEM_CERT_FILE` | `--pem-cert-file` | PEM cert file. |
|
||||
| `UPSTREAM_CERTIFICATE_FILE` | `--upstream-certificate-file` | Extra CA certs for trust chain. |
|
||||
|
||||
## Offline mode configuration
|
||||
|
||||
These settings apply when running Unleash Edge in Offline mode.
|
||||
|
||||
| Feature | Environment variable | CLI flag | Default | Description |
|
||||
| :---- | :---- | :---- | :---- | :---- |
|
||||
| **Bootstrap file** | `BOOTSTRAP_FILE` | `-b, --bootstrap-file` | - | Path to features.json file. |
|
||||
| **Reload interval** | `RELOAD_INTERVAL` | `-r, --reload-interval` | 0 | Seconds between reloading the file. |
|
||||
| **Backend tokens** | `CLIENT_TOKENS` | `-c, --client-tokens` | - | Tokens for [backend SDK](/sdks#backend-sdks) access. |
|
||||
| **Frontend tokens** | `FRONTEND_TOKENS` | `-f, --frontend-tokens` | - | Tokens for [frontend SDK](/sdks#frontend-sdks) access. |
|
||||
|
||||
## Debugging
|
||||
|
||||
### View internal state
|
||||
|
||||
| Endpoint | Shows |
|
||||
|----------|-------|
|
||||
| `/internal-backstage/tokens` | Known tokens |
|
||||
| `/internal-backstage/features` | Cached features |
|
||||
| `/internal-backstage/metrics` | Prometheus metrics |
|
||||
|
||||
|
||||
### Health check
|
||||
|
||||
```
|
||||
unleash-edge health [OPTIONS]
|
||||
|
||||
Options:
|
||||
-e, --edge-url <URL> Edge URL [default: http://localhost:3063]
|
||||
-c, --ca-certificate-file <FILE> CA cert for self-signed TLS
|
||||
```
|
||||
|
||||
### Ready check
|
||||
|
||||
```
|
||||
unleash-edge ready [OPTIONS]
|
||||
|
||||
Options:
|
||||
-e, --edge-url <URL> Edge URL [default: http://localhost:3063]
|
||||
-c, --ca-certificate-file <FILE> CA cert for self-signed TLS
|
||||
```
|
||||
275
website/docs/unleash-edge/deploy.mdx
Normal file
275
website/docs/unleash-edge/deploy.mdx
Normal file
@ -0,0 +1,275 @@
|
||||
---
|
||||
title: Deploy Unleash Edge
|
||||
toc_max_heading_level: 2
|
||||
pagination_next: unleash-edge/configure
|
||||
---
|
||||
|
||||
:::note Availability
|
||||
|
||||
**Plan**: [Enterprise](https://www.getunleash.io/pricing) | **Unleash version**: `7.3+`
|
||||
|
||||
:::
|
||||
|
||||
[Enterprise Edge Self-hosted](/unleash-edge#enterprise-edge-self-hosted) gives you full control over the infrastructure, networking, and data persistence of your Edge nodes. It allows you to keep flag data in specific geographic regions, operate in air-gapped environments, and meet specific infrastructure requirements.
|
||||
|
||||
This guide covers deploying Enterprise Edge self-hosted on your infrastructure.
|
||||
|
||||
## License
|
||||
|
||||
To self-host Enterprise Edge, you need an Unleash Enterprise instance and a license key that includes Enterprise Edge. Contact your customer success representative to obtain or upgrade your license.
|
||||
|
||||
## Quickstart with Docker
|
||||
|
||||
Unleash Edge is distributed as a Docker image.
|
||||
|
||||
To pull the image from Docker Hub, run:
|
||||
|
||||
```shell
|
||||
docker pull unleashorg/unleash-edge-enterprise:latest
|
||||
```
|
||||
|
||||
To run Edge in a container, provide your upstream URL and a backend token for bootstrapping.
|
||||
|
||||
```
|
||||
docker run -it -p 3063:3063 \
|
||||
-e UPSTREAM_URL=https://<your-unleash-instance>.com \
|
||||
-e TOKENS=<your_client_token> \
|
||||
unleashorg/unleash-edge-enterprise:<version> edge
|
||||
```
|
||||
|
||||
Once Edge is running, connect your SDKs by pointing them to `http://localhost:3063/api`:
|
||||
|
||||
```javascript
|
||||
const unleash = initialize({
|
||||
url: 'http://localhost:3063/api',
|
||||
appName: 'my-app',
|
||||
customHeaders: { Authorization: '<your_client_token>' },
|
||||
});
|
||||
```
|
||||
|
||||
For a more hands-on guide on setting up Edge locally and connecting an SDK, follow our [Unleash Edge](/guides/unleash-edge-quickstart) quickstart guide.
|
||||
|
||||
## Infrastructure requirements
|
||||
|
||||
Edge runs as a single binary or container. Minimum requirements per instance:
|
||||
|
||||
| Resource | Minimum | Recommended |
|
||||
|----------|---------|-------------|
|
||||
| CPU | 0.1 cores | 1 core |
|
||||
| Memory | 64 MB | 128 MB |
|
||||
| Disk | 100 MB | 500 MB (with persistence) |
|
||||
|
||||
## Modes of operation
|
||||
|
||||
Unleash Edge supports two distinct modes of operation:
|
||||
|
||||
- **Edge mode**: Connects to an upstream node (Unleash instance or another Edge). It synchronizes feature flags and streams metrics back to the upstream server. This is the standard operating mode.
|
||||
- **Offline mode**: Runs without a connection to an upstream Unleash instance. It loads feature flags from a local file (bootstrap file). This is primarily used for local development or strictly air-gapped testing.
|
||||
|
||||
See [Configure the operating mode](/unleash-edge/configure#configure-the-operating-mode) for configuration options.
|
||||
|
||||
```mermaid
|
||||
graph LR
|
||||
A(Client 1) -->|Fetch toggles| C((Edge 1))
|
||||
B(Client 2) -->|Fetch toggles| D((Edge 2))
|
||||
C-->|Fetch toggles| E((Edge 3))
|
||||
D-->|Fetch toggles| E
|
||||
E-->|Fetch toggles| F((Unleash))
|
||||
```
|
||||
|
||||
## Daisy chaining
|
||||
|
||||
Daisy chaining allows you to connect an Edge instance to another upstream Edge instance rather than directly to the Unleash API. This architecture is useful for multi-cloud deployments or extreme scale scenarios where a central Edge node bridges the gap between regional nodes and the main Unleash instance.
|
||||
|
||||
```mermaid
|
||||
graph LR
|
||||
A(Client 1) -->|Fetch toggles| C((Edge 1))
|
||||
B(Client 2) -->|Fetch toggles| D((Edge 2))
|
||||
C-->|Fetch toggles| E((Edge 3))
|
||||
D-->|Fetch toggles| E
|
||||
E-->|Fetch toggles| F((Unleash))
|
||||
```
|
||||
|
||||
To configure daisy chaining, point the downstream Edge's `UPSTREAM_URL` to the upstream Edge instance instead of Unleash. Metrics propagate upstream through the chain automatically.
|
||||
|
||||
## Production deployment
|
||||
|
||||
For production setups, we recommend deploying a minimum of two Edge instances behind a load balancer. This ensures high availability during updates or unexpected failures.
|
||||
|
||||
Unleash Edge runs evaluations from memory for speed, but it requires a persistence layer to survive restarts when the upstream is unavailable. To guarantee the resilience benefits of Edge, you must configure a persistence layer.
|
||||
|
||||
If an Edge node restarts and cannot contact the upstream Unleash server, it will fail to start unless it can load valid data from a persistence layer.
|
||||
|
||||
When running multiple Edge replicas, you must configure a shared persistence layer, such as Redis, so all instances share the same cold-start data.
|
||||
|
||||
#### Persistence options
|
||||
|
||||
| Option | Env var / CLI flag | Use case |
|
||||
| ----- | ----- | ----- |
|
||||
| **Redis** | `REDIS_URL --redis-url` | Recommended for production. Persists snapshots to a shared Redis cluster. Ideal for multi-replica setups. |
|
||||
| **Amazon S3** | `S3_BUCKET_NAME --s3-bucket-name` | Edge writes periodic snapshot files to S3. Suitable when a Redis service is not available but durable storage is required. |
|
||||
| **Local file** | `BACKUP_FOLDER --backup-folder` | Intended for **development only**. Not recommended for production or multi-replica environments. |
|
||||
|
||||
#### Deployment example
|
||||
|
||||
```shell
|
||||
docker run -d \
|
||||
--name unleash-edge \
|
||||
-p 3063:3063 \
|
||||
-e UPSTREAM_URL=https://your-unleash-instance.com \
|
||||
-e TOKENS=your-client-token \
|
||||
-e REDIS_URL=redis://your-redis:6379 \
|
||||
--memory=128m \
|
||||
--cpus=1 \
|
||||
unleashorg/unleash-edge-enterprise:latest edge
|
||||
```
|
||||
|
||||
### Kubernetes
|
||||
|
||||
For Kubernetes deployments, we recommend using the official [Helm charts](https://github.com/Unleash/helm-charts). Ensure you update the `image.repository` in your `values.yaml` to point to the Enterprise image tag.
|
||||
|
||||
## Configuration
|
||||
|
||||
Unleash Edge is configured primarily via environment variables. See [Configure self-hosted Edge](/unleash-edge/configure) for the complete reference.
|
||||
|
||||
### Essential configuration
|
||||
|
||||
| Environment Variable | CLI Argument | Description |
|
||||
| ----- | ----- | ----- |
|
||||
| `UPSTREAM_URL` | `--upstream-url` | The URL of your Unleash instance. Note: Do not include the `/api` suffix. |
|
||||
| `TOKENS` | `--tokens` | Comma-separated list of backend tokens used to bootstrap the cache. |
|
||||
| `STREAMING` | `--streaming` | Set to `true` to enable real-time updates. |
|
||||
| `PORT` | `--port` | The HTTP port Edge listens on (Default: `3063`). |
|
||||
| `RUST_LOG` | N/A | Log level configuration (e.g., `warn,unleash_edge=debug`). |
|
||||
|
||||
For the complete list of environment variables including TLS, CORS, and observability options, see [Configure](/unleash-edge/configure).
|
||||
|
||||
## Performance and sizing
|
||||
|
||||
Unleash Edge is designed to scale linearly with CPU resources. The throughput depends heavily on the size of your feature toggle dataset (number of feature flags and strategies).
|
||||
|
||||
### Capacity guidelines
|
||||
|
||||
Based on internal benchmarks, you can estimate capacity requirements using the following tiers. These figures assume a standard dataset size (approx. 100kB).
|
||||
|
||||
| CPU Allocation | Est. RPS (Requests Per Second) | Memory Footprint (Approx) |
|
||||
| ----- | ----- | ----- |
|
||||
| 0.1 vCPU | ~600 RPS | ~7 MiB |
|
||||
| 1.0 vCPU | ~6,900 RPS | ~7 MiB |
|
||||
| 4.0 vCPU | ~25,000 RPS | ~10 MiB |
|
||||
| 8.0 vCPU | ~40,000 RPS | ~15 MiB |
|
||||
|
||||
**Note**: Actual performance varies based on hardware generation and network conditions. We recommend allocating 1 vCPU per 5,000 expected RPS as a conservative baseline for production planning.
|
||||
|
||||
## Tokens
|
||||
|
||||
Edge relies on Unleash API tokens to validate access and sync configuration. The specific token configuration depends on your operating mode.
|
||||
|
||||
### Edge mode
|
||||
|
||||
When running in [Edge mode](#modes-of-operation), you must provide at least one valid [backend token](/concepts/api-tokens-and-client-keys#backend-tokens) at startup using the `TOKENS` variable. This token serves two critical functions:
|
||||
|
||||
- **Authentication**: Validates the Edge instance against the upstream Unleash server or the persistence layer.
|
||||
- **Scope definition**: Defines the maximum set of data the Edge instance can access.
|
||||
|
||||
Edge enforces strict scoping based on this token. It will only sync flags for the [projects](/concepts/projects) and [environments](/concepts/environments) included in the startup token.
|
||||
|
||||
For example:
|
||||
- **Broader access startup token**: If a client connects with a token that is a subset of the startup token (for example, the startup token has `*:development`, and the client has `project-a:development`), the request is accepted. Edge filters the response to show only `project-a`.
|
||||
- **Narrower or different access startup token**: If a client requests data outside the startup token's scope (for example, requesting production data when Edge only has development, or requesting `*` when Edge only has `project-a`), the request is rejected with `403 Forbidden` or `511 Network Authentication Required`.
|
||||
|
||||
:::tip Recommendation
|
||||
Bootstrap Edge with a wildcard token for the specific environment (for example, `*:development.some-secret`). This ensures the Edge instance has all data for that environment, allowing it to serve any client request for that environment instantly.
|
||||
:::
|
||||
|
||||
- Environment variable: `TOKENS`
|
||||
- CLI flag: `--tokens`
|
||||
|
||||
### Offline mode
|
||||
|
||||
When running in [Offline mode](#modes-of-operation), there is no upstream instance to validate tokens. You must explicitly configure which tokens are valid:
|
||||
|
||||
- **[Backend SDKs](/sdks#backend-sdks)**: Use `CLIENT_TOKENS` (or `--client-tokens`). Grants access to `/api/client/features`.
|
||||
- **[Frontend SDKs](/sdks#frontend-sdks)**: Use `FRONTEND_TOKENS` (or `--frontend-tokens`). Grants access to `/api/frontend` and `/api/proxy`.
|
||||
|
||||
### Pre-trusted tokens
|
||||
|
||||
:::note Availability
|
||||
Edge version: `19.10+`
|
||||
:::
|
||||
|
||||
If migrating from the legacy Unleash Proxy, you can use `PRETRUSTED_TOKENS` to support legacy secrets (for example, `secret-123@development`) without updating your frontend clients.
|
||||
|
||||
Note: You must still provide a standard backend token via `TOKENS` that covers the same environment. This ensures Edge can fetch the feature data required by the legacy token.
|
||||
|
||||
## Health and readiness
|
||||
|
||||
Edge exposes internal endpoints to verify the state of the application. These are useful for load balancer health checks and Kubernetes probes.
|
||||
|
||||
- **Health check**: `GET /internal-backstage/health`
|
||||
- Returns `200 OK` if the process is running.
|
||||
- **Ready check**: `GET /internal-backstage/ready`
|
||||
- Returns `200 OK` only when Edge has successfully synced with the upstream and the cache is populated.
|
||||
|
||||
## Metrics
|
||||
|
||||
:::note Availability
|
||||
|
||||
**Edge version**: `19+` | Unleash version `5.9+`
|
||||
|
||||
:::
|
||||
|
||||
Edge batches metrics from connected SDKs and pushes them upstream to Unleash. It also exposes its own application metrics compatible with Prometheus.
|
||||
|
||||
- **Endpoint**: `GET /internal-backstage/metrics`
|
||||
|
||||
## Security
|
||||
|
||||
### Protect internal endpoints
|
||||
|
||||
Endpoints under `/internal-backstage/` expose operational data and must not be publicly accessible.
|
||||
|
||||
**Option 1: Reverse proxy**
|
||||
|
||||
```nginx
|
||||
location /internal-backstage/ {
|
||||
deny all;
|
||||
return 403;
|
||||
}
|
||||
```
|
||||
|
||||
**Option 2: Disable at startup**
|
||||
|
||||
```shell
|
||||
-e DISABLE_METRICS_ENDPOINT=true \
|
||||
-e DISABLE_TOKENS_ENDPOINT=true \
|
||||
-e DISABLE_FEATURES_ENDPOINT=true
|
||||
```
|
||||
|
||||
### Network access control
|
||||
|
||||
```shell
|
||||
# Allow specific CIDRs
|
||||
--allow-list="10.0.0.0/8,192.168.0.0/16"
|
||||
|
||||
# Block specific CIDRs
|
||||
--deny-list="203.0.113.0/24"
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
**Edge returns 511 for frontend requests**
|
||||
|
||||
Frontend token doesn't have cached data. Ensure a backend token is configured that covers the same project and environment.
|
||||
|
||||
**Edge won't start**
|
||||
|
||||
Check that `UPSTREAM_URL` doesn't include `/api` suffix. Correct: `https://unleash.example.com`. Incorrect: `https://unleash.example.com/api`.
|
||||
|
||||
**Tokens rejected**
|
||||
|
||||
Ensure tokens match the expected format and have appropriate permissions in Unleash. Token scope must match or be narrower than startup tokens.
|
||||
|
||||
## Development guide
|
||||
|
||||
You can find a complete [development guide](https://github.com/Unleash/unleash-edge/blob/main/docs/development-guide.md) for Unleash Edge on GitHub.
|
||||
84
website/docs/unleash-edge/migrate-from-proxy.mdx
Normal file
84
website/docs/unleash-edge/migrate-from-proxy.mdx
Normal file
@ -0,0 +1,84 @@
|
||||
---
|
||||
title: 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
|
||||
|
||||
| Feature | Unleash Proxy | Unleash Edge |
|
||||
| :---- | :---- | :---- |
|
||||
| **Performance** | Handles hundreds of requests per second (RPS). | Handles tens of thousands of RPS with lower memory usage. |
|
||||
| **Environments** | Supports a single [environment](/concepts/environments) per instance. Requires separate instances for Development and Production. | Supports multiple [environments](/concepts/environments) in a single instance. Dynamically routes requests based on the API token. |
|
||||
| **Upstream URL** | Requires the /api suffix (https://unleash-instance.com/api). | No `/api` suffix (https://unleash-instance.com). |
|
||||
| **[Backend SDKs](/sdks#backend-sdks)** | Requires experimental flags and specific configuration. | Supported out of the box. |
|
||||
| **Language** | Node.js | Rust (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.
|
||||
|
||||
```diff
|
||||
- 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 [environment](/concepts/environments)from 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](/concepts/api-tokens-and-client-keys#backend-tokens) that covers the [projects](/concepts/projects) and [environments](/concepts/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](/sdks#frontend-sdks) and [backend SDKs](/sdks#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](/api).
|
||||
|
||||
## 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](/unleash-edge/deploy#daisy-chaining).
|
||||
|
||||
### Offline mode
|
||||
|
||||
Edge supports a dedicated [Offline mode](/unleash-edge/configure#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](/unleash-edge/configure#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](/concepts/custom-activation-strategies). You must migrate these to standard [strategy constraints](/concepts/activation-strategies#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.
|
||||
145
website/docs/unleash-edge/unleash-edge-overview.mdx
Normal file
145
website/docs/unleash-edge/unleash-edge-overview.mdx
Normal file
@ -0,0 +1,145 @@
|
||||
---
|
||||
title: Unleash Edge
|
||||
slug: /unleash-edge
|
||||
---
|
||||
|
||||
:::note Availability
|
||||
|
||||
**Plan**: [Enterprise](https://www.getunleash.io/pricing)
|
||||
|
||||
:::
|
||||
|
||||
Unleash Edge is a lightweight caching layer designed to improve scalability, performance, and resilience. It sits between your [application SDKs](/sdks) and the [Unleash API](/api), functioning as a read replica that can handle thousands of connected SDKs without increasing the read load on your primary Unleash instance.
|
||||
|
||||
Beyond scalability, Unleash Edge offers significant privacy and security benefits. It evaluates feature flags for [frontend SDKs](/sdks#frontend-sdks) directly on the Edge node, ensuring that sensitive user data required for evaluation is never sent upstream to Unleash.
|
||||
|
||||
Unleash Edge supports streaming, a persistent connection between Edge and Unleash where configuration changes in Unleash are pushed to Edge nodes immediately, ensuring your feature flags are always up to date without the network overhead of frequent polling.
|
||||
|
||||
Edge supports both [frontend SDKs](/sdks#frontend-sdks) and [backend SDKs](/sdks#backend-sdks) and has multi-environment and project awareness. You can [daisy-chain](/unleash-edge/deploy#daisy-chaining) Edge instances to support more complex setups, such as multi-cloud deployments.
|
||||
|
||||
Key features:
|
||||
- **Performance**: Edge uses in-memory caching and can run close to your end-users. A single instance can handle tens to hundreds of thousands of requests per second. Feature flag configuration updates are propagated to Edge instances instantly through streaming.
|
||||
- **Resilience**: Edge is designed to survive restarts and maintain functionality even if you lose connection to your Unleash server.
|
||||
- **Security**: Edge supports frontend applications without exposing sensitive data to end-users or to Unleash.
|
||||
|
||||
Unleash Edge Enterprise is available as [hosted](#enterprise-edge-hosted) or [self-hosted](#enterprise-edge-self-hosted), see [Hosting options](/deploy/hosting-options#unleash-edge-options) for a detailed comparison.
|
||||
|
||||
## How Edge works
|
||||
|
||||
Edge sits between your SDKs and Unleash, serving flag data from an in-memory cache with sub-millisecond latency. The cache stays synchronized with Unleash either through periodic polling or real-time [streaming](#real-time-updates-with-streaming).
|
||||
|
||||
Edge evaluates feature flags locally. This means user data (PII) used for targeting rules (like user IDs, emails, or IPs) is processed within the Edge node and never sent to the Unleash Cloud or your upstream instance.
|
||||
|
||||
Edge also aggregates usage metrics from connected SDKs and sends them upstream to Unleash.
|
||||
|
||||
|
||||
|
||||
### Backend SDKs
|
||||
|
||||
[Backend SDKs](/sdks#backend-sdks) fetch the full feature flag configuration from Edge and evaluate flags locally using [activation strategies](/concepts/activation-strategies).
|
||||
|
||||
### Frontend SDKs
|
||||
|
||||
[Frontend SDKs](/sdks#frontend-sdks) send evaluation requests to Edge, which evaluates flags server-side and returns only the results.
|
||||
|
||||
### Real-time updates with streaming
|
||||
|
||||
Enterprise Edge supports streaming mode, which pushes configuration changes from Unleash to Edge with millisecond latency. Enable streaming for near-instant flag updates across your infrastructure.
|
||||
|
||||
## Enterprise Edge hosted
|
||||
|
||||
Enterprise Edge hosted is a fully managed service operated by Unleash. It is ideal for teams requiring globally low latency and high resilience without the added operational overhead.
|
||||
|
||||
Enterprise Edge hosted is available in the following data centers:
|
||||
|
||||
**US:**
|
||||
- us-east-1 (Virginia)
|
||||
- us-east-2 (Ohio)
|
||||
- us-west-1 (N. California)
|
||||
- us-west-2 (Oregon)
|
||||
|
||||
**Europe:**
|
||||
- eu-central-1 (Frankfurt)
|
||||
- eu-west-1 (Ireland)
|
||||
- eu-west-2 (London)
|
||||
- eu-west-3 (Paris)
|
||||
- eu-north-1 (Stockholm)
|
||||
|
||||
**Asia:**
|
||||
- ap-south-1 (Mumbai)
|
||||
- ap-northeast-3 (Osaka)
|
||||
- ap-northeast-2 (Seoul)
|
||||
- ap-northeast-1 (Tokyo)
|
||||
- ap-southeast-1 (Singapore)
|
||||
- ap-southeast-2 (Sydney)
|
||||
|
||||
**Canada:**
|
||||
- ca-central-1 (Central)
|
||||
|
||||
**South America:**
|
||||
- sa-east-1 (São Paulo)
|
||||
|
||||
|
||||
## Enterprise Edge self-hosted
|
||||
|
||||
:::note Availability
|
||||
|
||||
**Unleash version**: `7.3+`
|
||||
|
||||
:::
|
||||
|
||||
Enterprise Edge self-hosted is hosted and operated by you within your own infrastructure. It is designed for environments requiring strict control, such as air-gapped networks or privacy-sensitive setups.
|
||||
|
||||
For more information on how to configure and deploy self-hosted Unleash Edge, go to [Deploy Unleash Edge](/unleash-edge/deploy).
|
||||
|
||||
## How to get Enterprise Edge
|
||||
|
||||
To use Enterprise Edge hosted, contact your customer success representative to enable Enterprise Edge in your account. Once Unleash configures Edge in your account, you can update your SDK configuration to use the Edge URL provided.
|
||||
|
||||
To use Enterprise Edge self-hosted, you must request a license key from your customer success representative.
|
||||
Self-hosted Edge requires deployment and configuration on your infrastructure.
|
||||
|
||||
See:
|
||||
- [Deploy self-hosted Edge](/unleash-edge/deploy) for deployment guides.
|
||||
- [Configure self-hosted Edge](/unleash-edge/configure) for configuration reference.
|
||||
|
||||
## Observability
|
||||
|
||||
:::note Availability
|
||||
|
||||
**Plan**: [Enterprise](https://www.getunleash.io/pricing) | **Version**: `7.4+`
|
||||
|
||||
:::
|
||||
|
||||
Unleash provides deep visibility into the health and performance of your Unleash Edge nodes directly within the Admin UI.
|
||||
|
||||
|
||||
|
||||
Go to **Admin settings > Enterprise Edge** to visualize your Edge topology. This view allows you to monitor the real-time state of every connected Edge instance.
|
||||
|
||||
The dashboard reports the following metrics for each Edge node:
|
||||
|
||||
**Instance details**: Region, instance ID, upstream server, and hosting type (hosted or self-hosted).
|
||||
|
||||
**Instance health:**
|
||||
- **Hosting type**: Hosted or self-hosted.
|
||||
- **Status**: Current connection state (such as `Connected`).
|
||||
- **Version**: The running version of the Edge binary.
|
||||
- **Resources**: Real-time CPU and Memory usage.
|
||||
|
||||
**Traffic and performance:**
|
||||
- **Stream clients**: Number of SDKs currently maintaining a streaming connection.
|
||||
- **Upstream latency**: Time taken to fetch updates from the upstream Unleash server (broken down by Client Features, Metrics, and Edge sync).
|
||||
- **Downstream latency**: Time taken to serve requests to connected SDKs (broken down by frontend and backend evaluations).
|
||||
|
||||
These metrics help you identify bottlenecks, verify regional deployments, and ensure your Edge nodes are properly synced.
|
||||
|
||||
|
||||
## Unleash Edge OSS
|
||||
|
||||
We are streamlining our Edge offering to focus on Enterprise capabilities.
|
||||
|
||||
- **Long-Term Support (LTS)**: The OSS version of Edge enters LTS on **December 10, 2025**.
|
||||
- **End-of-life (EOL)**: The OSS version will reach EOL on **December 31, 2026**.
|
||||
|
||||
We recommend all users [migrate to an Enterprise plan](https://www.getunleash.io/pricing) to access Unleash Edge Enterprise.
|
||||
@ -7,37 +7,6 @@ import {
|
||||
} from './shared';
|
||||
|
||||
const DOCS = mapObject(enrich)({
|
||||
'unleash-edge': {
|
||||
sidebarName: 'Unleash Edge',
|
||||
searchPriority: 'high',
|
||||
slugName: 'unleash-edge',
|
||||
subPages: {
|
||||
'docs/concepts.md': {
|
||||
sidebarName: 'Concepts',
|
||||
slugName: 'concepts',
|
||||
},
|
||||
'docs/deploying.md': {
|
||||
sidebarName: 'Deploying',
|
||||
slugName: 'deploying',
|
||||
},
|
||||
'docs/benchmarking.md': {
|
||||
sidebarName: 'Benchmarking',
|
||||
slugName: 'benchmarking',
|
||||
},
|
||||
'docs/CLI.md': {
|
||||
sidebarName: 'CLI',
|
||||
slugName: 'cli',
|
||||
},
|
||||
'docs/development-guide.md': {
|
||||
sidebarName: 'Development guide',
|
||||
slugName: 'development-guide',
|
||||
},
|
||||
'docs/migration-guide.md': {
|
||||
sidebarName: 'Migration guide',
|
||||
slugName: 'migration-guide',
|
||||
},
|
||||
},
|
||||
},
|
||||
'unleash-mcp': {
|
||||
sidebarName: 'MCP',
|
||||
slugName: 'integrate/mcp',
|
||||
|
||||
@ -562,15 +562,22 @@ const sidebars: SidebarsConfig = {
|
||||
collapsed: true,
|
||||
link: {
|
||||
type: 'doc',
|
||||
id: 'generated/unleash-edge',
|
||||
id: 'unleash-edge/unleash-edge-overview',
|
||||
},
|
||||
items: [
|
||||
'generated/unleash-edge/concepts',
|
||||
'generated/unleash-edge/deploying',
|
||||
'generated/unleash-edge/benchmarking',
|
||||
'generated/unleash-edge/cli',
|
||||
'generated/unleash-edge/development-guide',
|
||||
'generated/unleash-edge/migration-guide',
|
||||
{
|
||||
type: 'category',
|
||||
label: 'Self-host Unleash Edge',
|
||||
link: {
|
||||
type: 'doc',
|
||||
id: 'unleash-edge/deploy',
|
||||
},
|
||||
items: [
|
||||
'unleash-edge/deploy',
|
||||
'unleash-edge/configure',
|
||||
'unleash-edge/migrate-from-proxy',
|
||||
],
|
||||
},
|
||||
],
|
||||
},
|
||||
{
|
||||
|
||||
BIN
website/static/img/edge-observability.png
Normal file
BIN
website/static/img/edge-observability.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 275 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 412 KiB |
BIN
website/static/img/unleash-architecture.png
Normal file
BIN
website/static/img/unleash-architecture.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 415 KiB |
BIN
website/static/img/unleash-enterprise-edge.png
Normal file
BIN
website/static/img/unleash-enterprise-edge.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 198 KiB |
@ -752,6 +752,11 @@
|
||||
"destination": "/guides",
|
||||
"permanent": true
|
||||
},
|
||||
{
|
||||
"source": "/use-cases/user-management-access-controls-auditing",
|
||||
"destination": "/guides/user-management-access-controls",
|
||||
"permanent": true
|
||||
},
|
||||
{
|
||||
"source": "/use-cases",
|
||||
"destination": "/guides",
|
||||
@ -1032,6 +1037,36 @@
|
||||
"destination": "/unleash-edge",
|
||||
"permanent": true
|
||||
},
|
||||
{
|
||||
"source": "/unleash-edge/concepts",
|
||||
"destination": "/unleash-edge",
|
||||
"permanent": true
|
||||
},
|
||||
{
|
||||
"source": "/unleash-edge/benchmarking",
|
||||
"destination": "/unleash-edge/deploy",
|
||||
"permanent": true
|
||||
},
|
||||
{
|
||||
"source": "/unleash-edge/cli",
|
||||
"destination": "/unleash-edge/configure",
|
||||
"permanent": true
|
||||
},
|
||||
{
|
||||
"source": "/unleash-edge/deploying",
|
||||
"destination": "/unleash-edge/deploy",
|
||||
"permanent": true
|
||||
},
|
||||
{
|
||||
"source": "/unleash-edge/migration-guide",
|
||||
"destination": "/unleash-edge/migrate-from-proxy",
|
||||
"permanent": true
|
||||
},
|
||||
{
|
||||
"source": "/unleash-edge/development-guide",
|
||||
"destination": "/unleash-edge",
|
||||
"permanent": true
|
||||
},
|
||||
{
|
||||
"source": "/reference/sdks/android-proxy",
|
||||
"destination": "/sdks/android",
|
||||
|
||||
Loading…
Reference in New Issue
Block a user