fix: Update docs about environment in offline mode (#270)

* fix: Update docs about environment in offline mode fix: Fall back to default 'development' environment value if token does not contain an environment fixes: #266, #268 * docs: tls needs to be a file fixes: #162 * docs: Added which version of edge the reload interval for offline mode was released
Unleash · Sep 18, 2023 · 1cc30b7 · 1cc30b7
1 parent 62af705
commit 1cc30b7
Show file tree

Hide file tree

Showing 5 changed files with 100 additions and 25 deletions.
diff --git a/CLI.md b/CLI.md
@@ -8,6 +8,7 @@ This document contains the help content for the `unleash-edge` command-line prog
 * [`unleash-edge edge`↴](#unleash-edge-edge)
 * [`unleash-edge offline`↴](#unleash-edge-offline)
 * [`unleash-edge health`↴](#unleash-edge-health)
+* [`unleash-edge ready`↴](#unleash-edge-ready)
 
 ## `unleash-edge`
 
@@ -18,6 +19,7 @@ This document contains the help content for the `unleash-edge` command-line prog
 * `edge` — Run in edge mode
 * `offline` — Run in offline mode
 * `health` — Perform a health check against a running edge instance
+* `ready` — Perform a ready check against a running edge instance
 
 ###### **Options:**
 
@@ -32,18 +34,18 @@ This document contains the help content for the `unleash-edge` command-line prog
   Default value: ``
 * `-w`, `--workers <WORKERS>` — How many workers should be started to handle requests. Defaults to number of physical cpus
 
-  Default value: `16`
+  Default value: `8`
 * `--tls-enable` — Should we bind TLS
 
   Default value: `false`
-* `--tls-server-key <TLS_SERVER_KEY>` — Server key to use for TLS
-* `--tls-server-cert <TLS_SERVER_CERT>` — Server Cert to use for TLS
+* `--tls-server-key <TLS_SERVER_KEY>` — Server key to use for TLS - Needs to be a path to a file
+* `--tls-server-cert <TLS_SERVER_CERT>` — Server Cert to use for TLS - Needs to be a path to a file
 * `--tls-server-port <TLS_SERVER_PORT>` — Port to listen for https connection on (will use the interfaces already defined)
 
   Default value: `3043`
 * `--instance-id <INSTANCE_ID>` — Instance id. Used for metrics reporting
 
-  Default value: `01HA7584ARNZD9X399N0CEF3SE`
+  Default value: `01HAM0JMKDMZZP0HXNT8K1J6FW`
 * `-a`, `--app-name <APP_NAME>` — App name. Used for metrics reporting
 
   Default value: `unleash-edge`
@@ -143,6 +145,21 @@ Perform a health check against a running edge instance
 
 
 
+## `unleash-edge ready`
+
+Perform a ready check against a running edge instance
+
+**Usage:** `unleash-edge ready [OPTIONS]`
+
+###### **Options:**
+
+* `-e`, `--edge-url <EDGE_URL>` — Where the instance you want to health check is running
+
+  Default value: `http://localhost:3063`
+* `-c`, `--ca-certificate-file <CA_CERTIFICATE_FILE>` — If you're hosting Edge using a self-signed TLS certificate use this to tell the readychecker about your CA
+
+
+
 <hr/>
 
 <small><i>

diff --git a/README.md b/README.md
@@ -47,9 +47,9 @@ Options:
       --tls-enable
           Should we bind TLS [env: TLS_ENABLE=]
       --tls-server-key <TLS_SERVER_KEY>
-          Server key to use for TLS [env: TLS_SERVER_KEY=]
+          Server key to use for TLS [env: TLS_SERVER_KEY=] (Needs to be a path to a file)
       --tls-server-cert <TLS_SERVER_CERT>
-          Server Cert to use for TLS [env: TLS_SERVER_CERT=]
+          Server Cert to use for TLS [env: TLS_SERVER_CERT=] (Needs to be a path to a file)
       --tls-server-port <TLS_SERVER_PORT>
           Port to listen for https connection on (will use the interfaces already defined) [env: TLS_SERVER_PORT=] [default: 3043]
       --instance-id <INSTANCE_ID>
@@ -264,7 +264,7 @@ The simplified JSON format should be an object with a key for each feature. You
 
 When using offline mode you must specify one or more tokens at startup. These tokens will let your SDKs access Edge. Tokens following the Unleash API format `[project]:[environment].<somesecret>` allow Edge to recognize the project and environment 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.
 
-To make local development easier, you can specify a reload interval in seconds; this will cause Edge to reload the features file from disk every X seconds. This can be useful for local development.
+To make local development easier, you can specify a reload interval in seconds (Since Unleash-Edge 10.0.x); this will cause Edge to reload the features file from disk every X seconds. This can be useful for local development.
 
 Since offline mode does not connect to an upstream node, it does not support metrics or dynamic tokens.
 
@@ -281,6 +281,10 @@ Options:
 
 ```
 
+##### Environments in offline mode
+Currently, Edge does not support multiple environments in offline mode. All tokens added at startup will receive the same list of features passed in as the bootstrap argument. 
+However, tokens in <project>:<environment>.<secret> format will still filter by project.
+
 ## [Metrics](https://docs.getunleash.io/reference/api/unleash/metrics)
 
 **❗ Note:** For Unleash to correctly register SDK usage metrics sent from Edge instances, your Unleash instance must be v4.22 or newer.

diff --git a/server/README.md b/server/README.md
@@ -3,7 +3,7 @@
 [![crates.io](https://img.shields.io/crates/v/unleash-edge?label=latest)](https://crates.io/crates/unleash-edge)
 [![Documentation](https://docs.rs/unleash-edge/badge.svg?version=latest)](https://docs.rs/unleash-edge/latest)
 ![MIT licensed](https://img.shields.io/crates/l/unleash-edge.svg)
-[![Dependency Status](https://deps.rs/crate/unleash-edge/8.0.1/status.svg)](https://deps.rs/crate/unleash-edge/8.0.1)
+[![Dependency Status](https://deps.rs/crate/unleash-edge/11.0.1/status.svg)](https://deps.rs/crate/unleash-edge/11.0.1)
 [![CI](https://github.com/Unleash/unleash-edge/actions/workflows/test-with-coverage.yaml/badge.svg)](https://github.com/Unleash/unleash-edge/actions/workflows/test-with-coverage.yaml)
 [![Coverage Status](https://coveralls.io/repos/github/Unleash/unleash-edge/badge.svg?branch=main)](https://coveralls.io/github/Unleash/unleash-edge?branch=main)
 ![downloads](https://img.shields.io/crates/d/unleash-edge.svg)
@@ -47,9 +47,9 @@ Options:
       --tls-enable
           Should we bind TLS [env: TLS_ENABLE=]
       --tls-server-key <TLS_SERVER_KEY>
-          Server key to use for TLS [env: TLS_SERVER_KEY=]
+          Server key to use for TLS [env: TLS_SERVER_KEY=] (Needs to be a path to a file)
       --tls-server-cert <TLS_SERVER_CERT>
-          Server Cert to use for TLS [env: TLS_SERVER_CERT=]
+          Server Cert to use for TLS [env: TLS_SERVER_CERT=] (Needs to be a path to a file)
       --tls-server-port <TLS_SERVER_PORT>
           Port to listen for https connection on (will use the interfaces already defined) [env: TLS_SERVER_PORT=] [default: 3043]
       --instance-id <INSTANCE_ID>
@@ -71,6 +71,36 @@ will check an Edge process running on http://localhost:3063. If you're using bas
 
 If you're hosting Edge with a self-signed certificate using the tls cli arguments, you should use the `--ca-certificate-file <file_containing_your_ca_and_key_in_pem_format>` flag (or the CA_CERTIFICATE_FILE environment variable) to allow the health checker to trust the self signed certificate.
 
+### Built-in Ready check
+There is now (from 12.0.0) a subcommand named `ready` which will ping your ready endpoint and exit with status 0 provided the ready endpoint returns 200 OK and `{ status: "READY" }`. Otherwise it will return status 1 and an error message to signal that Edge is not ready (it has not spoken to upstream or recovered from a persisted backup).
+
+Examples:
+* Edge not running:
+```shell
+$ ./unleash-edge ready
+Error: Failed to connect to ready endpoint at http://localhost:3063/internal-backstage/ready. Failed with status None
+$ echo $?
+1
+```
+ 
+* Edge running but not populated its feature cache yet (not spoken to upstream or restored from backup)
+```shell
+$ ./unleash-edge ready
+Error: Ready check returned a different status than READY. It returned EdgeStatus { status: NotReady }
+$ echo $?
+1
+```
+* Edge running and synchronized. I.e. READY
+```shell
+$ ./unleash-edge ready
+OK
+$ echo $?
+0
+```
+
+If you're hosting Edge with a self-signed certificate using the tls cli arguments, you should use the `--ca-certificate-file <file_containing_your_ca_and_key_in_pem_format>` flag (or the CA_CERTIFICATE_FILE environment variable) to allow the health checker to trust the self signed certificate.
+
+
 ## Getting Unleash Edge
 
 Unleash Edge is distributed as a binary and as a docker image.
@@ -135,10 +165,10 @@ Edge mode also supports dynamic tokens, meaning that Edge doesn't need a token t
 Even though Edge supports dynamic tokens, you still have the option of providing a token through the command line argument or environment variable. This way, since Edge already knows about your token at start up, it will sync your features for that token and should be ready for your requests right away (_warm up / hot start_).
 
 ### Front-end tokens
-[Front-end tokens](https://docs.getunleash.io/reference/api-tokens-and-client-keys#front-end-tokens) can also be used with `/api/frontend` and `/api/proxy` endpoints, however they are not allowed to fetch features upstream. 
-In order to use these tokens correctly and make sure they return the correct information, it's important that the features they are allowed to access are already present in that Edge node's features cache. 
-The easiest way to ensure this is by passing in at least one client token as one of the command line arguments, 
-ensuring it has access to the same features as the front-end token you'll be using. 
+[Front-end tokens](https://docs.getunleash.io/reference/api-tokens-and-client-keys#front-end-tokens) can also be used with `/api/frontend` and `/api/proxy` endpoints, however they are not allowed to fetch features upstream.
+In order to use these tokens correctly and make sure they return the correct information, it's important that the features they are allowed to access are already present in that Edge node's features cache.
+The easiest way to ensure this is by passing in at least one client token as one of the command line arguments,
+ensuring it has access to the same features as the front-end token you'll be using.
 If you're using a frontend token that doesn't have data in the node's feature cache, you will receive an HTTP Status code: 511 Network Authentication Required along with a body of which project and environment you will need to add a client token for.
 
 #### Enterprise
@@ -210,15 +240,31 @@ graph LR
   B-->|Fetch toggles| C[Features dump]
 ```
 
-Offline mode should be used when you don't have a connection to an upstream node, such as your Unleash instance itself or another Edge instance. It can also be used when you need to have full control of both the data your clients will get and which tokens can be used to access it.
+Offline mode is useful when there is no connection to an upstream node, such as your Unleash instance or another Edge instance, or as a tool to make working with Unleash easier during development.
 
-Since this mode does not connect to an upstream node, it needs a downloaded JSON dump of a result from a query against an Unleash server on the [/api/client/features](https://docs.getunleash.io/reference/api/unleash/get-client-feature) endpoint as well as a comma-separated list of tokens that should be allowed to access the server.
+To use offline mode, you'll need a features file. The easiest way to get one is to download a JSON dump of a result from a query against an Unleash server on the [/api/client/features](https://docs.getunleash.io/reference/api/unleash/get-client-feature) endpoint. You can also use a hand rolled, human readable JSON version of the features file. Edge will automatically convert it to the API format when it starts up. Here's an example:
 
-If your token follows the Unleash API token format `[project]:[environment].<somesecret>`, Edge will filter the features dump to match the project contained in the token.
+``` json
+{
+  "featureOne": {
+    "enabled": true,
+    "variant": "variantOne"
+  },
+  "featureTwo": {
+    "enabled": false,
+    "variant": "variantTwo"
+  },
+  "featureThree": {
+    "enabled": true
+  }
+}
+```
+
+The simplified JSON format should be an object with a key for each feature. You can force the result of `is_enabled` in your SDK by setting the enabled property, likewise can also force the result of `get_variant` by specifying the name of the variant you want. This format is primarily for development.
 
-If you'd rather use a simple token like `secret-123`, any query against `/api/client/features` will receive the dump passed in on the command line.
+When using offline mode you must specify one or more tokens at startup. These tokens will let your SDKs access Edge. Tokens following the Unleash API format `[project]:[environment].<somesecret>` allow Edge to recognize the project and environment 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.
 
-When using offline mode, you can think of these tokens as [proxy client keys](https://docs.getunleash.io/reference/api-tokens-and-client-keys#proxy-client-keys).
+To make local development easier, you can specify a reload interval in seconds (Since Unleash-Edge 10.0.x); this will cause Edge to reload the features file from disk every X seconds. This can be useful for local development.
 
 Since offline mode does not connect to an upstream node, it does not support metrics or dynamic tokens.
 
@@ -229,10 +275,16 @@ $ ./unleash-edge offline --help
 Usage: unleash-edge offline [OPTIONS]
 
 Options:
-  -b, --bootstrap-file <BOOTSTRAP_FILE>  [env: BOOTSTRAP_FILE=]
-  -t, --tokens <TOKENS>                  [env: TOKENS=]
+  -b, --bootstrap-file <BOOTSTRAP_FILE>         [env: BOOTSTRAP_FILE=]
+  -t, --tokens <TOKENS>                         [env: TOKENS=]
+  -r, --reload-interval <RELOAD_INTERVAL>       [env: RELOAD_INTERVAL=]
+
 ```
 
+##### Environments in offline mode
+Currently, Edge does not support multiple environments in offline mode. All tokens added at startup will receive the same list of features passed in as the bootstrap argument. 
+However, tokens in <project>:<environment>.<secret> format will still filter by project.
+
 ## [Metrics](https://docs.getunleash.io/reference/api/unleash/metrics)
 
 **❗ Note:** For Unleash to correctly register SDK usage metrics sent from Edge instances, your Unleash instance must be v4.22 or newer.

diff --git a/server/src/cli.rs b/server/src/cli.rs
@@ -213,7 +213,7 @@ pub struct ReadyCheckArgs {
     #[clap(short, long, env, default_value = "http://localhost:3063")]
     pub edge_url: String,
 
-    /// If you're hosting Edge using a self-signed TLS certificate use this to tell healthcheck about your CA
+    /// If you're hosting Edge using a self-signed TLS certificate use this to tell the readychecker about your CA
     #[clap(short, long, env)]
     pub ca_certificate_file: Option<PathBuf>,
 }
@@ -255,11 +255,11 @@ pub struct TlsOptions {
     /// Should we bind TLS
     #[clap(env, long, default_value_t = false)]
     pub tls_enable: bool,
-    /// Server key to use for TLS
+    /// Server key to use for TLS - Needs to be a path to a file
     #[clap(env, long)]
     pub tls_server_key: Option<PathBuf>,
     #[clap(env, long)]
-    /// Server Cert to use for TLS
+    /// Server Cert to use for TLS - Needs to be a path to a file
     pub tls_server_cert: Option<PathBuf>,
     /// Port to listen for https connection on (will use the interfaces already defined)
     #[clap(env, long, default_value_t = 3043)]

diff --git a/server/src/metrics/client_metrics.rs b/server/src/metrics/client_metrics.rs
@@ -134,7 +134,9 @@ pub(crate) fn register_client_metrics(
     let metrics = unleash_types::client_metrics::from_bucket_app_name_and_env(
         metrics.bucket,
         metrics.app_name,
-        edge_token.environment.unwrap(),
+        edge_token
+            .environment
+            .unwrap_or_else(|| "development".into()),
     );
 
     metrics_cache.sink_metrics(&metrics);