diff --git a/CLI.md b/CLI.md index 0451c5d4..407b0d75 100644 --- a/CLI.md +++ b/CLI.md @@ -32,7 +32,8 @@ This document contains the help content for the `unleash-edge` command-line prog * `-b`, `--base-path ` — Which base path should this server listen for HTTP traffic on Default value: `` -* `-w`, `--workers ` — How many workers should be started to handle requests. Defaults to number of physical cpus +* `-w`, `--workers ` — How many workers should be started to handle requests. Defaults to number of physical + cpus Default value: `16` * `--tls-enable` — Should we bind TLS @@ -43,12 +44,13 @@ This document contains the help content for the `unleash-edge` command-line prog * `--tls-server-key ` — Server key to use for TLS - Needs to be a path to a file * `--tls-server-cert ` — Server Cert to use for TLS - Needs to be a path to a file -* `--tls-server-port ` — Port to listen for https connection on (will use the interfaces already defined) +* `--tls-server-port ` — Port to listen for https connection on (will use the interfaces already + defined) Default value: `3043` * `--instance-id ` — Instance id. Used for metrics reporting - Default value: `01HX9QXY3MNKKAMP7XRS6RG2Q4` + Default value: `` * `-a`, `--app-name ` — App name. Used for metrics reporting Default value: `unleash-edge` @@ -56,12 +58,19 @@ This document contains the help content for the `unleash-edge` command-line prog Possible values: `true`, `false` -* `--trust-proxy` — By enabling the trust proxy option. Unleash Edge will have knowledge that it's sitting behind a proxy and that the X-Forward-\* header fields may be trusted, which otherwise may be easily spoofed. Edge will use this to populate its context's remoteAddress field If you need to only trust specific ips or CIDR, enable this flag and then set `--proxy-trusted-servers` +* `--trust-proxy` — By enabling the trust proxy option. Unleash Edge will have knowledge that it's sitting behind a + proxy and that the X-Forward-\* header fields may be trusted, which otherwise may be easily spoofed. Edge will use + this to populate its context's remoteAddress field If you need to only trust specific ips or CIDR, enable this flag + and then set `--proxy-trusted-servers` Possible values: `true`, `false` -* `--proxy-trusted-servers ` — Tells Unleash Edge which servers to trust the X-Forwarded-For. Accepts explicit Ip addresses or Cidrs (127.0.0.1/16). Accepts a comma separated list or multiple instances of the flag. E.g `--proxy-trusted-servers "127.0.0.1,192.168.0.1"` and `--proxy-trusted-servers 127.0.0.1 --proxy-trusted-servers 192.168.0.1` are equivalent -* `--disable-all-endpoint` — Set this flag to true if you want to disable /api/proxy/all and /api/frontend/all Because returning all toggles regardless of their state is a potential security vulnerability, these endpoints can be disabled +* `--proxy-trusted-servers ` — Tells Unleash Edge which servers to trust the X-Forwarded-For. + Accepts explicit Ip addresses or Cidrs (127.0.0.1/16). Accepts a comma separated list or multiple instances of the + flag. E.g `--proxy-trusted-servers "127.0.0.1,192.168.0.1"` + and `--proxy-trusted-servers 127.0.0.1 --proxy-trusted-servers 192.168.0.1` are equivalent +* `--disable-all-endpoint` — Set this flag to true if you want to disable /api/proxy/all and /api/frontend/all Because + returning all toggles regardless of their state is a potential security vulnerability, these endpoints can be disabled Default value: `false` @@ -80,8 +89,6 @@ This document contains the help content for the `unleash-edge` command-line prog Default value: `Authorization` - - ## `unleash-edge edge` Run in edge mode @@ -90,30 +97,42 @@ Run in edge mode ###### **Options:** -* `-u`, `--upstream-url ` — Where is your upstream URL. Remember, this is the URL to your instance, without any trailing /api suffix -* `-b`, `--backup-folder ` — A path to a local folder. Edge will write feature and token data to disk in this folder and read this back after restart. Mutually exclusive with the --redis-url option +* `-u`, `--upstream-url ` — Where is your upstream URL. Remember, this is the URL to your instance, + without any trailing /api suffix +* `-b`, `--backup-folder ` — A path to a local folder. Edge will write feature and token data to disk in + this folder and read this back after restart. Mutually exclusive with the --redis-url option * `-m`, `--metrics-interval-seconds ` — How often should we post metrics upstream? Default value: `60` -* `-f`, `--features-refresh-interval-seconds ` — How long between each refresh for a token +* `-f`, `--features-refresh-interval-seconds ` — How long between each refresh for a + token Default value: `10` -* `--token-revalidation-interval-seconds ` — How long between each revalidation of a token +* `--token-revalidation-interval-seconds ` — How long between each revalidation of + a token Default value: `3600` -* `-t`, `--tokens ` — Get data for these client tokens at startup. Accepts comma-separated list of tokens. Hot starts your feature cache -* `-H`, `--custom-client-headers ` — Expects curl header format (-H : ) for instance `-H X-Api-Key: mysecretapikey` -* `-s`, `--skip-ssl-verification` — If set to true, we will skip SSL verification when connecting to the upstream Unleash server +* `-t`, `--tokens ` — Get data for these client tokens at startup. Accepts comma-separated list of tokens. Hot + starts your feature cache +* `-H`, `--custom-client-headers ` — Expects curl header format (-H : ) + for instance `-H X-Api-Key: mysecretapikey` +* `-s`, `--skip-ssl-verification` — If set to true, we will skip SSL verification when connecting to the upstream + Unleash server Default value: `false` Possible values: `true`, `false` -* `--pkcs8-client-certificate-file ` — Client certificate chain in PEM encoded X509 format with the leaf certificate first. The certificate chain should contain any intermediate certificates that should be sent to clients to allow them to build a chain to a trusted root -* `--pkcs8-client-key-file ` — Client key is a PEM encoded PKCS#8 formatted private key for the leaf certificate -* `--pkcs12-identity-file ` — Identity file in pkcs12 format. Typically this file has a pfx extension +* `--pkcs8-client-certificate-file ` — Client certificate chain in PEM encoded X509 + format with the leaf certificate first. The certificate chain should contain any intermediate certificates that should + be sent to clients to allow them to build a chain to a trusted root +* `--pkcs8-client-key-file ` — Client key is a PEM encoded PKCS#8 formatted private key for the + leaf certificate +* `--pkcs12-identity-file ` — Identity file in pkcs12 format. Typically this file has a pfx + extension * `--pkcs12-passphrase ` — Passphrase used to unlock the pkcs12 file -* `--upstream-certificate-file ` — Extra certificate passed to the client for building its trust chain. Needs to be in PEM format (crt or pem extensions usually are) +* `--upstream-certificate-file ` — Extra certificate passed to the client for building its + trust chain. Needs to be in PEM format (crt or pem extensions usually are) * `--upstream-request-timeout ` — Timeout for requests to the upstream server Default value: `5` @@ -143,11 +162,23 @@ Run in edge mode Possible values: `tcp`, `tls`, `redis`, `rediss`, `redis-unix`, `unix` -* `--token-header ` — Token header to use for both edge authorization and communication with the upstream server +* `--token-header ` — Token header to use for both edge authorization and communication with the upstream + server Default value: `Authorization` +* `--strict` — If set to true, Edge starts with strict behavior. Strict behavior means that Edge will refuse tokens + outside of the scope of the startup tokens + + Default value: `false` + Possible values: `true`, `false` + +* `--dynamic` — If set to true, Edge starts with dynamic behavior. Dynamic behavior means that Edge will accept tokens + outside of the scope of the startup tokens + Default value: `false` + + Possible values: `true`, `false` ## `unleash-edge offline` @@ -158,13 +189,13 @@ Run in offline mode ###### **Options:** * `-b`, `--bootstrap-file ` — The file to load our features from. This data will be loaded at startup -* `-t`, `--tokens ` — Tokens that should be allowed to connect to Edge. Supports a comma separated list or multiple instances of the `--tokens` argument -* `-r`, `--reload-interval ` — The interval in seconds between reloading the bootstrap file. Disabled if unset or 0 +* `-t`, `--tokens ` — Tokens that should be allowed to connect to Edge. Supports a comma separated list or + multiple instances of the `--tokens` argument +* `-r`, `--reload-interval ` — The interval in seconds between reloading the bootstrap file. Disabled + if unset or 0 Default value: `0` - - ## `unleash-edge health` Perform a health check against a running edge instance @@ -176,9 +207,8 @@ Perform a health check against a running edge instance * `-e`, `--edge-url ` — Where the instance you want to health check is running Default value: `http://localhost:3063` -* `-c`, `--ca-certificate-file ` — If you're hosting Edge using a self-signed TLS certificate use this to tell healthcheck about your CA - - +* `-c`, `--ca-certificate-file ` — If you're hosting Edge using a self-signed TLS certificate use + this to tell healthcheck about your CA ## `unleash-edge ready` @@ -191,14 +221,13 @@ Perform a ready check against a running edge instance * `-e`, `--edge-url ` — Where the instance you want to health check is running Default value: `http://localhost:3063` -* `-c`, `--ca-certificate-file ` — If you're hosting Edge using a self-signed TLS certificate use this to tell the readychecker about your CA - - +* `-c`, `--ca-certificate-file ` — If you're hosting Edge using a self-signed TLS certificate use + this to tell the readychecker about your CA
- This document was generated automatically by - clap-markdown. +This document was generated automatically by +clap-markdown. diff --git a/README.md b/README.md index 3595b9a0..5d361383 100644 --- a/README.md +++ b/README.md @@ -43,6 +43,40 @@ Running Edge in Docker with our recommended setup: docker run -it -p 3063:3063 -e STRICT=true -e UPSTREAM_URL= unleashorg/unleash-edge: edge ``` +## Edge behaviors + +As of version 19.2.0, Unleash Edge now supports two behaviors when running in edge mode: **strict** and **dynamic**. We +recommend adopting the new **strict** behavior, while **dynamic** remains as a legacy option that will be deprecated and +removed in a future release. + +For legacy reasons, **dynamic** behavior is still the default. However, a warning will be logged at startup to indicate +its deprecation. + +Please note that these behaviors are mutually exclusive. + +### Strict behavior + +If started with the `--strict` flag or the `STRICT` environment variable, Edge now starts with strict behavior and must +be given tokens at startup. + +Edge will refuse requests from SDKs that have a wider or different access scope than the initial tokens. Specifically, +this means incoming requests must have a token that exactly matches the environment and is bound to a project or +projects specified in that token. + +E.g. If you start with one wildcard token with access to the development +environment `*:development.` and your clients use various tokens with access to specific projects +in the development environment, Edge will filter features to only grant access to the narrower scope. + +### Dynamic behavior + +With dynamic behavior, Edge behaves as it has since v1.0.0. Any new client tokens are validated against upstream and if +found to be valid, a refresh job will be configured with the minimum set of tokens that are able to fetch all projects +and environments Edge has seen. Set with `--dynamic` or the `DYNAMIC` environment variable. (19.2.0 / July 4th 2024): +We're looking to deprecate this behavior. If you need this behavior, reach out to us on Slack, the final +decision has not been made yet. In 19.2.0 this behavior is still the default, but Edge will log that you should make a +choice between dynamic or strict behavior. +When dynamic behavior is selected (by default or by choice), Edge will print a warning about the planned deprecation. + ## Deploying See our page on [Deploying Edge](./docs/deploying.md) @@ -121,7 +155,8 @@ See more about available logging and log levels at https://docs.rs/env_logger/la - Old Edge version. In order to guarantee metrics on newer Unleash versions, you will need to be using Edge v17.0.0 or newer -- Old SDK clients. We've noticed that some clients, particularly early Python (1.x branch) as well as earlier .NET SDKs (we +- Old SDK clients. We've noticed that some clients, particularly early Python (1.x branch) as well as earlier .NET + SDKs (we recommend you use 4.1.5 or newer) struggle to post metrics with the strict headers Edge requires. ## Development diff --git a/server/src/builder.rs b/server/src/builder.rs index dd591358..64cb316a 100644 --- a/server/src/builder.rs +++ b/server/src/builder.rs @@ -100,7 +100,9 @@ pub(crate) fn build_offline_mode( fn build_offline(offline_args: OfflineArgs) -> EdgeResult { if offline_args.tokens.is_empty() { - return Err(EdgeError::NoTokens("No tokens provided. Tokens must be specified when running in offline mode".into())); + return Err(EdgeError::NoTokens( + "No tokens provided. Tokens must be specified when running in offline mode".into(), + )); } if let Some(bootstrap) = offline_args.bootstrap_file { @@ -163,7 +165,9 @@ async fn build_edge(args: &EdgeArgs) -> EdgeResult { } if args.strict && args.tokens.is_empty() { - return Err(EdgeError::NoTokens("No tokens provided. Tokens must be specified when running with strict behavior".into())); + return Err(EdgeError::NoTokens( + "No tokens provided. Tokens must be specified when running with strict behavior".into(), + )); } let (token_cache, feature_cache, engine_cache) = build_caches(); @@ -242,22 +246,25 @@ pub async fn build_caches_and_refreshers(args: CliArgs) -> EdgeResult #[cfg(test)] mod tests { - use crate::{builder::{build_edge, build_offline}, cli::{EdgeArgs, OfflineArgs, TokenHeader}}; + use crate::{ + builder::{build_edge, build_offline}, + cli::{EdgeArgs, OfflineArgs, TokenHeader}, + }; #[test] fn should_fail_with_empty_tokens_when_offline_mode() { let args = OfflineArgs { bootstrap_file: None, tokens: vec![], - reload_interval: Default::default() + reload_interval: Default::default(), }; let result = build_offline(args); assert!(result.is_err()); - assert_eq!(result - .err() - .unwrap() - .to_string(), "No tokens provided. Tokens must be specified when running in offline mode"); + assert_eq!( + result.err().unwrap().to_string(), + "No tokens provided. Tokens must be specified when running in offline mode" + ); } #[tokio::test] @@ -276,16 +283,18 @@ mod tests { upstream_request_timeout: Default::default(), upstream_socket_timeout: Default::default(), custom_client_headers: Default::default(), - token_header: TokenHeader { token_header: "Authorization".into() }, + token_header: TokenHeader { + token_header: "Authorization".into(), + }, upstream_certificate_file: Default::default(), token_revalidation_interval_seconds: Default::default(), }; let result = build_edge(&args).await; assert!(result.is_err()); - assert_eq!(result - .err() - .unwrap() - .to_string(), "No tokens provided. Tokens must be specified when running with strict behavior"); + assert_eq!( + result.err().unwrap().to_string(), + "No tokens provided. Tokens must be specified when running with strict behavior" + ); } - } \ No newline at end of file +} diff --git a/server/src/cli.rs b/server/src/cli.rs index e053f7d2..25511660 100644 --- a/server/src/cli.rs +++ b/server/src/cli.rs @@ -175,11 +175,11 @@ pub struct EdgeArgs { #[clap(long, env, global = true, default_value = "Authorization")] pub token_header: TokenHeader, - /// If set to true, Edge starts with strict behavior. Strict behavior means that Edge will refuse tokens outside of the scope of the startup tokens + /// If set to true, Edge starts with strict behavior. Strict behavior means that Edge will refuse tokens outside the scope of the startup tokens #[clap(long, env, default_value_t = false)] pub strict: bool, - /// If set to true, Edge starts with dynamic behavior. Dynamic behavior means that Edge will accept tokens outside of the scope of the startup tokens + /// If set to true, Edge starts with dynamic behavior. Dynamic behavior means that Edge will accept tokens outside the scope of the startup tokens #[clap(long, env, default_value_t = false, conflicts_with = "strict")] pub dynamic: bool, } diff --git a/server/src/client_api.rs b/server/src/client_api.rs index 747c9946..d4a6dd90 100644 --- a/server/src/client_api.rs +++ b/server/src/client_api.rs @@ -1101,7 +1101,8 @@ mod tests { assert_eq!(result.status(), StatusCode::NOT_FOUND); } #[tokio::test] - pub async fn still_subsumes_tokens_after_moving_registration_to_initial_hydration_when_dynamic() { + pub async fn still_subsumes_tokens_after_moving_registration_to_initial_hydration_when_dynamic() + { let upstream_features_cache: Arc> = Arc::new(DashMap::default()); let upstream_token_cache: Arc> = Arc::new(DashMap::default()); diff --git a/server/src/http/feature_refresher.rs b/server/src/http/feature_refresher.rs index f1a98a89..fa339161 100644 --- a/server/src/http/feature_refresher.rs +++ b/server/src/http/feature_refresher.rs @@ -228,19 +228,21 @@ impl FeatureRefresher { match self.get_features_by_filter(&token, filters) { Some(features) if self.token_is_subsumed(&token) => Ok(features), _ => { - if self.strict { - debug!("Strict behavior: Token is not subsumed by any registered tokens. Returning error"); - Err(EdgeError::InvalidTokenWithStrictBehavior) - } else { - debug!("Dynamic behavior: Had never seen this environment. Configuring fetcher"); - self.register_and_hydrate_token(&token).await; - self.get_features_by_filter(&token, filters).ok_or_else(|| { + if self.strict { + debug!("Strict behavior: Token is not subsumed by any registered tokens. Returning error"); + Err(EdgeError::InvalidTokenWithStrictBehavior) + } else { + debug!( + "Dynamic behavior: Had never seen this environment. Configuring fetcher" + ); + self.register_and_hydrate_token(&token).await; + self.get_features_by_filter(&token, filters).ok_or_else(|| { EdgeError::ClientHydrationFailed( "Failed to get features by filter after registering and hydrating token (This is very likely an error in Edge. Please report this!)" .into(), ) }) - } + } } } } @@ -1046,7 +1048,8 @@ mod tests { } #[tokio::test] - pub async fn fetching_two_projects_from_same_environment_should_get_features_for_both_when_dynamic() { + pub async fn fetching_two_projects_from_same_environment_should_get_features_for_both_when_dynamic( + ) { let upstream_features_cache: Arc> = Arc::new(DashMap::default()); let upstream_engine_cache: Arc> = Arc::new(DashMap::default()); diff --git a/server/src/internal_backstage.rs b/server/src/internal_backstage.rs index f87bf2e1..19b30f71 100644 --- a/server/src/internal_backstage.rs +++ b/server/src/internal_backstage.rs @@ -394,7 +394,7 @@ mod tests { #[actix_web::test] async fn returns_validated_tokens_when_strict() { - let upstream_features_cache: Arc> = + let upstream_features_cache: Arc> = Arc::new(DashMap::default()); let upstream_token_cache: Arc> = Arc::new(DashMap::default()); let upstream_engine_cache: Arc> = Arc::new(DashMap::default()); diff --git a/server/src/types.rs b/server/src/types.rs index f5d4c299..e68c5fda 100644 --- a/server/src/types.rs +++ b/server/src/types.rs @@ -1,13 +1,13 @@ -use std::{ - collections::HashMap, - hash::{Hash, Hasher}, - str::FromStr, -}; use std::cmp::min; use std::fmt; use std::fmt::{Debug, Display, Formatter}; use std::net::IpAddr; use std::sync::Arc; +use std::{ + collections::HashMap, + hash::{Hash, Hasher}, + str::FromStr, +}; use actix_web::{http::header::EntityTag, web::Json}; use async_trait::async_trait;