From 6d5b89d88bbec34e687ac8a6b12d119c77304e45 Mon Sep 17 00:00:00 2001 From: Thomas Heartman Date: Thu, 17 Mar 2022 16:30:18 +0100 Subject: [PATCH 01/27] docs: add how-to for running proxy (duplicated content) --- .../how-to/how-to-run-the-unleash-proxy.mdx | 303 ++++++++++++++++++ 1 file changed, 303 insertions(+) create mode 100644 website/docs/how-to/how-to-run-the-unleash-proxy.mdx diff --git a/website/docs/how-to/how-to-run-the-unleash-proxy.mdx b/website/docs/how-to/how-to-run-the-unleash-proxy.mdx new file mode 100644 index 00000000000..20ed1105843 --- /dev/null +++ b/website/docs/how-to/how-to-run-the-unleash-proxy.mdx @@ -0,0 +1,303 @@ +--- +id: unleash-proxy +title: Unleash Proxy +--- + +> The unleash-proxy is compatible with all Unleash Enterprise versions and Unleash Open-Source v4. You should reach out to **support@getunleash.io** if you want the Unleash Team to host the Unleash Proxy for you. + +A lot of our users wanted to use feature toggles in their single-page and native applications. To solve this in a performant and privacy concerned way we built The Unleash Proxy + +The Unleash Proxy sits between the Unleash API and the application. It provides a simple and super-fast API, as it has all the data it needs available in memory. + +The proxy solves three important aspects: + +- **Performance** – The proxy will cache all toggles in memory, and will be running on the edge, close to your end-users. A single instance will be able to handle thousands of request/sec, and you can scale it easily by adding additional instances. +- **Security** – The proxy evaluates the feature flags for the user on the server-side, and exposes results for feature flags that are enabled for a specific user (flags not enabled for that specific user are _not_ exposed). +- **Privacy** – If you run the proxy yourself (we can host it as well though) we will not see your end users. This means that you still have full control of your end-users, the way it should be! + +![The Unleash Proxy](/img/The-unleash-proxy.png) + +_The Unleash Proxy uses the Unleash SDK and exposes a simple API_. The Proxy will synchronize with the Unleash API in the background and provide a simple HTTP API for clients. + +## How to Run the Unleash Proxy + +The Unleash Proxy is Open Source and [available on github](https://github.com/Unleash/unleash-proxy). You can either run it as a docker image or as part of a [node.js express application](https://github.com/Unleash/unleash-proxy#run-with-nodejs). + +### Configuration variables + +Regardless of how you choose to run the it, the proxy will need access to these three variables: + +- **`unleashUrl`** / **`UNLEASH_URL`** + + The URL of your Unleash instance's API. For instance, to connect to the [Unleash demo app](https://app.unleash-hosted.com/demo/), you would use `https://app.unleash-hosted.com/demo/api/` + +- **`unleashApiToken`** / **`UNLEASH_API_TOKEN`** + + The API token to connect to your Unleash project. For more information on how these work and how to create them, check out the [API token documentation](../user_guide/token.md). + +- **`clientKeys`** / **`UNLEASH_PROXY_CLIENT_KEYS`** + + A list of client keys that the proxy will accept. For the proxy to accept an incoming request, the client must use one of these keys for authorization. In client SDKs, this is usually known as a `clientKey` or a `clientSecret`. If you query the proxy directly via HTTP, this is the `authorization` header. + + When using an environment variable to set the proxy secrets, the value should be a comma-separated list of strings, such as `secret-one,secret-two`. + +There are many more configuration options available. You'll find all [available options on github](https://github.com/Unleash/unleash-proxy#available-options). + + +### Running the proxy via Docker + +The easiest way to run Unleash is via Docker. We have published a [docker image on docker hub](https://hub.docker.com/r/unleashorg/unleash-proxy). + +1. **Pull the Proxy image** + ```bash + docker pull unleashorg/unleash-proxy + ``` + +2. **Start the proxy** + + ```bash + docker run \ + -e UNLEASH_PROXY_CLIENT_KEYS=some-secret \ + -e UNLEASH_URL='https://app.unleash-hosted.com/demo/api/' \ + -e UNLEASH_API_TOKEN=56907a2fa53c1d16101d509a10b78e36190b0f918d9f122d \ + -p 3000:3000 \ + unleashorg/unleash-proxy + ``` + + You should see the following output: + + ```bash + Unleash-proxy is listening on port 3000! + ``` + +### Running the proxy using Node.js + +To run the Proxy via Node.js, you'll have to create your own Node.js project and use the Unleash Proxy as a dependency. Assuming you've already set up your project, here's the steps to take to start the proxy as part of your app: + +1. **Install the Unleash Proxy package** + ``` shell npm2yarn + npm install @unleash/proxy + ``` + +2. **Initialize and start the proxy in your code.** A fully working sample app that uses the proxy: + ``` js + const port = 3000; + + const { createApp } = require('@unleash/proxy'); + + const app = createApp({ + unleashUrl: 'https://app.unleash-hosted.com/demo/api/', + unleashApiToken: '56907a2fa53c1d16101d509a10b78e36190b0f918d9f122d', + clientKeys: ['some-secret', 'another-proxy-secret', 's1'], + refreshInterval: 1000, + }); + + app.listen(port, () => + console.log(`Unleash Proxy listening on http://localhost:${port}/proxy`), + ); + ``` + +### Verify that the proxy is working + +In order to verify the proxy you can use curl and see that you get a few evaluated feature toggles back. Assuming that the proxy is running on port 3000 and that your proxy client key is `some-secret`, you could run this command : + +```bash +curl http://localhost:3000/proxy -H "Authorization: some-secret" +``` + +The output is of the form described in the [payload section](#payload). + +### Health endpoint + +The proxy will try to synchronize with the Unleash API at startup, until it has successfully done that the proxy will return `HTTP 503 - Not Read?` for all request. You can use the health endpoint to validate that the proxy is ready to recieve requests: + +```bash +curl http://localhost:3000/proxy/health -I +``` + +```bash +HTTP/1.1 200 OK +Access-Control-Allow-Origin: * +Access-Control-Expose-Headers: ETag +Content-Type: text/html; charset=utf-8 +Content-Length: 2 +ETag: W/"2-eoX0dku9ba8cNUXvu/DyeabcC+s" +Date: Fri, 04 Jun 2021 10:38:27 GMT +Connection: keep-alive +Keep-Alive: timeout=5 +``` + + +## Custom activation strategies + +The Unleash Proxy can load [custom activation strategies](../advanced/custom-activation-strategy.md) for front-end client SDKs ([Android](../sdks/android-proxy.md), [JavaScript](../sdks/proxy-javascript.md), [React](../sdks/proxy-react.md), [iOS](../sdks/proxy-ios.md)). For a step-by-step guide, refer to the [_how to use custom strategies_ guide](../how-to/how-to-use-custom-strategies.md#step-3-b). + +To load custom strategies, use either of these two options: +- the **`customStrategies`** option: use this if you're running the Unleash Proxy via Node directly. +- the **`UNLEASH_CUSTOM_STRATEGIES_FILE`** environment variable: use this if you're running the proxy as a container. + +Both options take a list of file paths to JavaScript files that export custom strategy implementations. + +### Custom activation strategy files format + +Each strategy file must export a list of instantiated strategies. A file can export as many strategies as you'd like. + +Here's an example file that exports two custom strategies: + +``` js +const { Strategy } = require('unleash-client'); + +class MyCustomStrategy extends Strategy { + // ... strategy implementation +} + +class MyOtherCustomStrategy extends Strategy { + // ... strategy implementation +} + +// export strategies +module.exports = [ + new MyCustomStrategy(), + new MyOtherCustomStrategy() +]; +``` + +Refer the [custom activation strategy documentation](../advanced/custom-activation-strategy.md#implementation) for more details on how to implement a custom activation strategy. + +## Unleash Proxy API {#unleash-proxy-api} + +The Unleash Proxy has a very simple API. It takes the [Unleash Context](../user_guide/unleash_context) as input and will return the feature toggles relevant for that specific context. + +![The Unleash Proxy](/img/The-Unleash-Proxy-API.png) + +### Payload + +The `proxy` endpoint returns information about toggles enabled for the current user. The payload is a JSON object with a `toggles` property, which contains a list of toggles. + + +```json +{ + "toggles": [ + { + "name": "demo", + "enabled": true, + "variant": { + "name": "disabled", + "enabled": false + } + }, + { + "name": "demoApp.step1", + "enabled": true, + "variant": { + "name": "disabled", + "enabled": false + } + } + ] +} +``` + +#### Toggle data + +The data for a toggle without [variants](../advanced/feature-toggle-variants.md) looks like this: + +``` json +{ + "name": "basic-toggle", + "enabled": true, + "variant": { + "name": "disabled", + "enabled": false + } +} +``` + +- **`name`**: the name of the feature. +- **`enabled`**: whether the toggle is enabled or not. Will always be `true`. +- **`variant`**: describes whether the toggle has variants and, if it does, what variant is active for this user. If a toggle doesn't have any variants, it will always be `{"name": "disabled", "enabled": false}`. + +:::note +Unleash uses a fallback variant called "disabled" to indicate that a toggle has no variants. However, you are free to create a variant called "disabled" yourself. In that case you can tell them apart by checking the variant's `enabled` property: if the toggle has no variants, `enabled` will be `false`. If the toggle is the "disabled" variant that you created, it will have `enabled` set to `true`. +::: + + +If a toggle has variants, then the variant object can also contain an optional `payload` property. The `payload` will contain data about the variant's payload: what type it is, and what the content is. To learn more about variants and their payloads, check [the feature toggle variants documentation](../advanced/feature-toggle-variants.md). + +Variant toggles without payloads look will have their name listed and the `enabled` property set to `true`: + +``` json +{ + "name": "toggle-with-variants", + "enabled": true, + "variant": { + "name": "simple", + "enabled": true + } +} + +``` + +If the variant has a payload, the optional `payload` property will list the payload's type and it's content in a stringified form: + +``` json +{ + "name": "toggle-with-variants", + "enabled": true, + "variant": { + "name": "with-payload-string", + "payload": { + "type": "string", + "value": "this string is the variant's payload" + }, + "enabled": true + } +} +``` + +For the `variant` property: +- **`name`**: is the name of the variant, as shown in the Admin UI. +- **`enabled`**: indicates whether the variant is enabled or not. If the toggle has variants, this is always `true`. +- **`payload`** (optional): Only present if the variant has a payload. Describes the payload's type and content. + +If the variant has a payload, the `payload` object contains: +- **`type`**: the type of the variant's payload +- **`value`**: the value of the variant's payload + +The `value` will always be the payload's content as a string, escaped as necessary. For instance, a variant with a JSON payload would look like this: + +``` json +{ + "name": "toggle-with-variants", + "enabled": true, + "variant": { + "name": "with-payload-json", + "payload": { + "type": "json", + "value": "{\"description\": \"this is data delivered as a json string\"}" + }, + "enabled": true + } +} +``` + +## We care about Privacy! {#we-care-about-privacy} + +The Unleash Proxy is important because you should not expose your entire set of toggle configurations to your end users. Single page apps work in the context of a specific user. The proxy allows you to only provide data that relates to that one user: _The proxy will only return the evaluated toggles (with variants) that should be enabled for that specific user in that specific context._ + +Most of our customers prefer to run The Unleash Proxy themselves. PS! We actually prefer this as we don’t want to see your users. Running it is pretty simple, it is either a small Node.js process you start or a docker image you use. (We can of course host the proxy for you also.) + + + +## How to connect to the Proxy? {#how-to-connect-to-the-proxy} + +The Unleash Proxy takes the heavy lifting of evaluating toggles and only returns enabled toggles and their values to the client. This means that you would get away with a simple http-client in many common use-cases. + +However in some settings you would like a bit more logic around it to make it as fast as possible, and keep up to date with changes. + +- [JavaScript Proxy SDK](/sdks/proxy-javascript) +- [React Proxy SDK](/sdks/proxy-react) +- [Android Proxy SDK](/sdks/android_proxy_sdk) +- [iOS Proxy SDK](/sdks/proxy-ios) + +The proxy is also ideal fit for serverless functions such as AWS Lambda. In that scenario the proxy can run on a small container near the serverless function, preferably in the same VPC, giving the lambda extremely fast access to feature flags, at a predictable cost. From 4b0b08a2ea167b61a2789e5402d0bedf7906c09f Mon Sep 17 00:00:00 2001 From: Thomas Heartman Date: Thu, 17 Mar 2022 16:40:00 +0100 Subject: [PATCH 02/27] docs: start moving proxy details around --- .../how-to/how-to-run-the-unleash-proxy.mdx | 191 ------------------ website/docs/sdks/unleash-proxy.md | 109 ++-------- 2 files changed, 20 insertions(+), 280 deletions(-) diff --git a/website/docs/how-to/how-to-run-the-unleash-proxy.mdx b/website/docs/how-to/how-to-run-the-unleash-proxy.mdx index 20ed1105843..4fdf02306ef 100644 --- a/website/docs/how-to/how-to-run-the-unleash-proxy.mdx +++ b/website/docs/how-to/how-to-run-the-unleash-proxy.mdx @@ -3,22 +3,6 @@ id: unleash-proxy title: Unleash Proxy --- -> The unleash-proxy is compatible with all Unleash Enterprise versions and Unleash Open-Source v4. You should reach out to **support@getunleash.io** if you want the Unleash Team to host the Unleash Proxy for you. - -A lot of our users wanted to use feature toggles in their single-page and native applications. To solve this in a performant and privacy concerned way we built The Unleash Proxy - -The Unleash Proxy sits between the Unleash API and the application. It provides a simple and super-fast API, as it has all the data it needs available in memory. - -The proxy solves three important aspects: - -- **Performance** – The proxy will cache all toggles in memory, and will be running on the edge, close to your end-users. A single instance will be able to handle thousands of request/sec, and you can scale it easily by adding additional instances. -- **Security** – The proxy evaluates the feature flags for the user on the server-side, and exposes results for feature flags that are enabled for a specific user (flags not enabled for that specific user are _not_ exposed). -- **Privacy** – If you run the proxy yourself (we can host it as well though) we will not see your end users. This means that you still have full control of your end-users, the way it should be! - -![The Unleash Proxy](/img/The-unleash-proxy.png) - -_The Unleash Proxy uses the Unleash SDK and exposes a simple API_. The Proxy will synchronize with the Unleash API in the background and provide a simple HTTP API for clients. - ## How to Run the Unleash Proxy The Unleash Proxy is Open Source and [available on github](https://github.com/Unleash/unleash-proxy). You can either run it as a docker image or as part of a [node.js express application](https://github.com/Unleash/unleash-proxy#run-with-nodejs). @@ -126,178 +110,3 @@ Date: Fri, 04 Jun 2021 10:38:27 GMT Connection: keep-alive Keep-Alive: timeout=5 ``` - - -## Custom activation strategies - -The Unleash Proxy can load [custom activation strategies](../advanced/custom-activation-strategy.md) for front-end client SDKs ([Android](../sdks/android-proxy.md), [JavaScript](../sdks/proxy-javascript.md), [React](../sdks/proxy-react.md), [iOS](../sdks/proxy-ios.md)). For a step-by-step guide, refer to the [_how to use custom strategies_ guide](../how-to/how-to-use-custom-strategies.md#step-3-b). - -To load custom strategies, use either of these two options: -- the **`customStrategies`** option: use this if you're running the Unleash Proxy via Node directly. -- the **`UNLEASH_CUSTOM_STRATEGIES_FILE`** environment variable: use this if you're running the proxy as a container. - -Both options take a list of file paths to JavaScript files that export custom strategy implementations. - -### Custom activation strategy files format - -Each strategy file must export a list of instantiated strategies. A file can export as many strategies as you'd like. - -Here's an example file that exports two custom strategies: - -``` js -const { Strategy } = require('unleash-client'); - -class MyCustomStrategy extends Strategy { - // ... strategy implementation -} - -class MyOtherCustomStrategy extends Strategy { - // ... strategy implementation -} - -// export strategies -module.exports = [ - new MyCustomStrategy(), - new MyOtherCustomStrategy() -]; -``` - -Refer the [custom activation strategy documentation](../advanced/custom-activation-strategy.md#implementation) for more details on how to implement a custom activation strategy. - -## Unleash Proxy API {#unleash-proxy-api} - -The Unleash Proxy has a very simple API. It takes the [Unleash Context](../user_guide/unleash_context) as input and will return the feature toggles relevant for that specific context. - -![The Unleash Proxy](/img/The-Unleash-Proxy-API.png) - -### Payload - -The `proxy` endpoint returns information about toggles enabled for the current user. The payload is a JSON object with a `toggles` property, which contains a list of toggles. - - -```json -{ - "toggles": [ - { - "name": "demo", - "enabled": true, - "variant": { - "name": "disabled", - "enabled": false - } - }, - { - "name": "demoApp.step1", - "enabled": true, - "variant": { - "name": "disabled", - "enabled": false - } - } - ] -} -``` - -#### Toggle data - -The data for a toggle without [variants](../advanced/feature-toggle-variants.md) looks like this: - -``` json -{ - "name": "basic-toggle", - "enabled": true, - "variant": { - "name": "disabled", - "enabled": false - } -} -``` - -- **`name`**: the name of the feature. -- **`enabled`**: whether the toggle is enabled or not. Will always be `true`. -- **`variant`**: describes whether the toggle has variants and, if it does, what variant is active for this user. If a toggle doesn't have any variants, it will always be `{"name": "disabled", "enabled": false}`. - -:::note -Unleash uses a fallback variant called "disabled" to indicate that a toggle has no variants. However, you are free to create a variant called "disabled" yourself. In that case you can tell them apart by checking the variant's `enabled` property: if the toggle has no variants, `enabled` will be `false`. If the toggle is the "disabled" variant that you created, it will have `enabled` set to `true`. -::: - - -If a toggle has variants, then the variant object can also contain an optional `payload` property. The `payload` will contain data about the variant's payload: what type it is, and what the content is. To learn more about variants and their payloads, check [the feature toggle variants documentation](../advanced/feature-toggle-variants.md). - -Variant toggles without payloads look will have their name listed and the `enabled` property set to `true`: - -``` json -{ - "name": "toggle-with-variants", - "enabled": true, - "variant": { - "name": "simple", - "enabled": true - } -} - -``` - -If the variant has a payload, the optional `payload` property will list the payload's type and it's content in a stringified form: - -``` json -{ - "name": "toggle-with-variants", - "enabled": true, - "variant": { - "name": "with-payload-string", - "payload": { - "type": "string", - "value": "this string is the variant's payload" - }, - "enabled": true - } -} -``` - -For the `variant` property: -- **`name`**: is the name of the variant, as shown in the Admin UI. -- **`enabled`**: indicates whether the variant is enabled or not. If the toggle has variants, this is always `true`. -- **`payload`** (optional): Only present if the variant has a payload. Describes the payload's type and content. - -If the variant has a payload, the `payload` object contains: -- **`type`**: the type of the variant's payload -- **`value`**: the value of the variant's payload - -The `value` will always be the payload's content as a string, escaped as necessary. For instance, a variant with a JSON payload would look like this: - -``` json -{ - "name": "toggle-with-variants", - "enabled": true, - "variant": { - "name": "with-payload-json", - "payload": { - "type": "json", - "value": "{\"description\": \"this is data delivered as a json string\"}" - }, - "enabled": true - } -} -``` - -## We care about Privacy! {#we-care-about-privacy} - -The Unleash Proxy is important because you should not expose your entire set of toggle configurations to your end users. Single page apps work in the context of a specific user. The proxy allows you to only provide data that relates to that one user: _The proxy will only return the evaluated toggles (with variants) that should be enabled for that specific user in that specific context._ - -Most of our customers prefer to run The Unleash Proxy themselves. PS! We actually prefer this as we don’t want to see your users. Running it is pretty simple, it is either a small Node.js process you start or a docker image you use. (We can of course host the proxy for you also.) - - - -## How to connect to the Proxy? {#how-to-connect-to-the-proxy} - -The Unleash Proxy takes the heavy lifting of evaluating toggles and only returns enabled toggles and their values to the client. This means that you would get away with a simple http-client in many common use-cases. - -However in some settings you would like a bit more logic around it to make it as fast as possible, and keep up to date with changes. - -- [JavaScript Proxy SDK](/sdks/proxy-javascript) -- [React Proxy SDK](/sdks/proxy-react) -- [Android Proxy SDK](/sdks/android_proxy_sdk) -- [iOS Proxy SDK](/sdks/proxy-ios) - -The proxy is also ideal fit for serverless functions such as AWS Lambda. In that scenario the proxy can run on a small container near the serverless function, preferably in the same VPC, giving the lambda extremely fast access to feature flags, at a predictable cost. diff --git a/website/docs/sdks/unleash-proxy.md b/website/docs/sdks/unleash-proxy.md index 20ed1105843..502823fa954 100644 --- a/website/docs/sdks/unleash-proxy.md +++ b/website/docs/sdks/unleash-proxy.md @@ -18,95 +18,6 @@ The proxy solves three important aspects: ![The Unleash Proxy](/img/The-unleash-proxy.png) _The Unleash Proxy uses the Unleash SDK and exposes a simple API_. The Proxy will synchronize with the Unleash API in the background and provide a simple HTTP API for clients. - -## How to Run the Unleash Proxy - -The Unleash Proxy is Open Source and [available on github](https://github.com/Unleash/unleash-proxy). You can either run it as a docker image or as part of a [node.js express application](https://github.com/Unleash/unleash-proxy#run-with-nodejs). - -### Configuration variables - -Regardless of how you choose to run the it, the proxy will need access to these three variables: - -- **`unleashUrl`** / **`UNLEASH_URL`** - - The URL of your Unleash instance's API. For instance, to connect to the [Unleash demo app](https://app.unleash-hosted.com/demo/), you would use `https://app.unleash-hosted.com/demo/api/` - -- **`unleashApiToken`** / **`UNLEASH_API_TOKEN`** - - The API token to connect to your Unleash project. For more information on how these work and how to create them, check out the [API token documentation](../user_guide/token.md). - -- **`clientKeys`** / **`UNLEASH_PROXY_CLIENT_KEYS`** - - A list of client keys that the proxy will accept. For the proxy to accept an incoming request, the client must use one of these keys for authorization. In client SDKs, this is usually known as a `clientKey` or a `clientSecret`. If you query the proxy directly via HTTP, this is the `authorization` header. - - When using an environment variable to set the proxy secrets, the value should be a comma-separated list of strings, such as `secret-one,secret-two`. - -There are many more configuration options available. You'll find all [available options on github](https://github.com/Unleash/unleash-proxy#available-options). - - -### Running the proxy via Docker - -The easiest way to run Unleash is via Docker. We have published a [docker image on docker hub](https://hub.docker.com/r/unleashorg/unleash-proxy). - -1. **Pull the Proxy image** - ```bash - docker pull unleashorg/unleash-proxy - ``` - -2. **Start the proxy** - - ```bash - docker run \ - -e UNLEASH_PROXY_CLIENT_KEYS=some-secret \ - -e UNLEASH_URL='https://app.unleash-hosted.com/demo/api/' \ - -e UNLEASH_API_TOKEN=56907a2fa53c1d16101d509a10b78e36190b0f918d9f122d \ - -p 3000:3000 \ - unleashorg/unleash-proxy - ``` - - You should see the following output: - - ```bash - Unleash-proxy is listening on port 3000! - ``` - -### Running the proxy using Node.js - -To run the Proxy via Node.js, you'll have to create your own Node.js project and use the Unleash Proxy as a dependency. Assuming you've already set up your project, here's the steps to take to start the proxy as part of your app: - -1. **Install the Unleash Proxy package** - ``` shell npm2yarn - npm install @unleash/proxy - ``` - -2. **Initialize and start the proxy in your code.** A fully working sample app that uses the proxy: - ``` js - const port = 3000; - - const { createApp } = require('@unleash/proxy'); - - const app = createApp({ - unleashUrl: 'https://app.unleash-hosted.com/demo/api/', - unleashApiToken: '56907a2fa53c1d16101d509a10b78e36190b0f918d9f122d', - clientKeys: ['some-secret', 'another-proxy-secret', 's1'], - refreshInterval: 1000, - }); - - app.listen(port, () => - console.log(`Unleash Proxy listening on http://localhost:${port}/proxy`), - ); - ``` - -### Verify that the proxy is working - -In order to verify the proxy you can use curl and see that you get a few evaluated feature toggles back. Assuming that the proxy is running on port 3000 and that your proxy client key is `some-secret`, you could run this command : - -```bash -curl http://localhost:3000/proxy -H "Authorization: some-secret" -``` - -The output is of the form described in the [payload section](#payload). - ### Health endpoint The proxy will try to synchronize with the Unleash API at startup, until it has successfully done that the proxy will return `HTTP 503 - Not Read?` for all request. You can use the health endpoint to validate that the proxy is ready to recieve requests: @@ -301,3 +212,23 @@ However in some settings you would like a bit more logic around it to make it as - [iOS Proxy SDK](/sdks/proxy-ios) The proxy is also ideal fit for serverless functions such as AWS Lambda. In that scenario the proxy can run on a small container near the serverless function, preferably in the same VPC, giving the lambda extremely fast access to feature flags, at a predictable cost. + +## Configuration options + +Regardless of how you choose to run the it, the proxy will need access to these three variables: + +- **`unleashUrl`** / **`UNLEASH_URL`** + + The URL of your Unleash instance's API. For instance, to connect to the [Unleash demo app](https://app.unleash-hosted.com/demo/), you would use `https://app.unleash-hosted.com/demo/api/` + +- **`unleashApiToken`** / **`UNLEASH_API_TOKEN`** + + The API token to connect to your Unleash project. For more information on how these work and how to create them, check out the [API token documentation](../user_guide/token.md). + +- **`clientKeys`** / **`UNLEASH_PROXY_CLIENT_KEYS`** + + A list of client keys that the proxy will accept. For the proxy to accept an incoming request, the client must use one of these keys for authorization. In client SDKs, this is usually known as a `clientKey` or a `clientSecret`. If you query the proxy directly via HTTP, this is the `authorization` header. + + When using an environment variable to set the proxy secrets, the value should be a comma-separated list of strings, such as `secret-one,secret-two`. + +There are many more configuration options available. You'll find all [available options on github](https://github.com/Unleash/unleash-proxy#available-options). From 3c63adddab73767ad2b9cc1095231805fb78c0c6 Mon Sep 17 00:00:00 2001 From: Thomas Heartman Date: Fri, 18 Mar 2022 11:03:33 +0100 Subject: [PATCH 03/27] docs: add more scaffolding to proxy docs --- website/docs/sdks/unleash-proxy.md | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/website/docs/sdks/unleash-proxy.md b/website/docs/sdks/unleash-proxy.md index 502823fa954..260d593e281 100644 --- a/website/docs/sdks/unleash-proxy.md +++ b/website/docs/sdks/unleash-proxy.md @@ -232,3 +232,14 @@ Regardless of how you choose to run the it, the proxy will need access to these When using an environment variable to set the proxy secrets, the value should be a comma-separated list of strings, such as `secret-one,secret-two`. There are many more configuration options available. You'll find all [available options on github](https://github.com/Unleash/unleash-proxy#available-options). + +## Bootstrapping the Unleash Proxy {#bootstrap} + +## Scaling the Unleash Proxy + +## Hosting the Unleash Proxy + +## Proxy connection + +{ how to connect the proxy, what setups are possible etc. } +See #bootstrap From 29f77b8e278fbbb45f0a6917a66e12d3e9e7a428 Mon Sep 17 00:00:00 2001 From: Thomas Heartman Date: Tue, 22 Mar 2022 15:36:35 +0100 Subject: [PATCH 04/27] docs: add configuration options header. --- website/docs/sdks/unleash-proxy.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/website/docs/sdks/unleash-proxy.md b/website/docs/sdks/unleash-proxy.md index 260d593e281..e3529ddfdc1 100644 --- a/website/docs/sdks/unleash-proxy.md +++ b/website/docs/sdks/unleash-proxy.md @@ -243,3 +243,5 @@ There are many more configuration options available. You'll find all [available { how to connect the proxy, what setups are possible etc. } See #bootstrap + +## Configuration options From 48f5e45b4059802a10c080001aa8eeb8ce0236a2 Mon Sep 17 00:00:00 2001 From: Thomas Heartman Date: Mon, 28 Mar 2022 13:22:07 +0200 Subject: [PATCH 05/27] fix: remove wrong id --- website/docs/how-to/how-to-run-the-unleash-proxy.mdx | 1 - 1 file changed, 1 deletion(-) diff --git a/website/docs/how-to/how-to-run-the-unleash-proxy.mdx b/website/docs/how-to/how-to-run-the-unleash-proxy.mdx index 4fdf02306ef..9300648cbc6 100644 --- a/website/docs/how-to/how-to-run-the-unleash-proxy.mdx +++ b/website/docs/how-to/how-to-run-the-unleash-proxy.mdx @@ -1,5 +1,4 @@ --- -id: unleash-proxy title: Unleash Proxy --- From c7fe197fbda27c181800602b9a632321cfa4d3a7 Mon Sep 17 00:00:00 2001 From: Thomas Heartman Date: Mon, 28 Mar 2022 13:22:24 +0200 Subject: [PATCH 06/27] docs: add new how-to category: Unleash Proxy --- website/sidebars.js | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/website/sidebars.js b/website/sidebars.js index 1a0b97275cc..7bd76354b04 100644 --- a/website/sidebars.js +++ b/website/sidebars.js @@ -50,6 +50,17 @@ module.exports = { label: 'Using the APIs', items: ['user_guide/api-token', 'advanced/api_access'], }, + { + type: 'category', + link: { + type: 'generated-index', + title: 'How-to: The Unleash Proxy', + description: 'Learn how to work with the Unleash Proxy', + slug: '/how-to/proxy', + }, + label: 'Unleash Proxy guides', + items: ['how-to/how-to-run-the-unleash-proxy'], + }, { label: 'Feature toggles, strategies, context', items: [ @@ -58,6 +69,7 @@ module.exports = { 'user_guide/create_feature_toggle', 'how-to/how-to-define-custom-context-fields', 'how-to/how-to-use-custom-strategies', + 'how-to/how-to-capture-impression-data', 'how-to/how-to-schedule-feature-releases', ], type: 'category', From 8f3018d092046d34793a91cbb754c4ba7693fba6 Mon Sep 17 00:00:00 2001 From: Thomas Heartman Date: Tue, 12 Apr 2022 13:38:44 +0200 Subject: [PATCH 07/27] docs: ad configuration variables to proxy reference --- website/docs/sdks/unleash-proxy.md | 48 ++++++++++++++++++++++++++++++ 1 file changed, 48 insertions(+) diff --git a/website/docs/sdks/unleash-proxy.md b/website/docs/sdks/unleash-proxy.md index e3529ddfdc1..3cf286537e7 100644 --- a/website/docs/sdks/unleash-proxy.md +++ b/website/docs/sdks/unleash-proxy.md @@ -18,6 +18,54 @@ The proxy solves three important aspects: ![The Unleash Proxy](/img/The-unleash-proxy.png) _The Unleash Proxy uses the Unleash SDK and exposes a simple API_. The Proxy will synchronize with the Unleash API in the background and provide a simple HTTP API for clients. + +## Configuration + +### Required configuration variables + +Regardless of how you choose to run the it, the proxy will need access to these three variables: + +- **`unleashUrl`** / **`UNLEASH_URL`** + + The URL of your Unleash instance's API. For instance, to connect to the [Unleash demo app](https://app.unleash-hosted.com/demo/), you would use `https://app.unleash-hosted.com/demo/api/` + +- **`unleashApiToken`** / **`UNLEASH_API_TOKEN`** + + The API token to connect to your Unleash project. For more information on how these work and how to create them, check out the [API token documentation](../user_guide/token.md). + +- **`clientKeys`** / **`UNLEASH_PROXY_CLIENT_KEYS`** + + A list of client keys that the proxy will accept. For the proxy to accept an incoming request, the client must use one of these keys for authorization. In client SDKs, this is usually known as a `clientKey` or a `clientSecret`. If you query the proxy directly via HTTP, this is the `authorization` header. + + When using an environment variable to set the proxy secrets, the value should be a comma-separated list of strings, such as `secret-one,secret-two`. + +There are many more configuration options available. You'll find all [available options on github](https://github.com/Unleash/unleash-proxy#available-options). + +### All configuration options + +| Option | Environment Variable | Default value | Required | Description | | +|----------------------|----------------------------------|-----------------|:--------:|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---| +| clientKeys | `UNLEASH_PROXY_CLIENT_KEYS` | n/a | yes | List of client keys that the proxy should accept. When querying the proxy, Proxy SDKs must set the request's _client keys header_ to one of these values. The default client keys header is `Authorization`. | | +| clientKeysHeaderName | `CLIENT_KEY_HEADER_NAME` | "authorization" | no | The name of the HTTP header to use for client keys. Incoming requests must set the value of this header to one of the Proxy's `clientKeys` to be authorized successfully. | | +| customStrategies | `UNLEASH_CUSTOM_STRATEGIES_FILE` | [] | no | Use this option to inject implementation of custom activation strategies. If you are using `UNLEASH_CUSTOM_STRATEGIES_FILE` you need to provide a valid path to a javascript files which exports an array of custom activation strategies and the SDK will automatically load these | | +| environment | `UNLEASH_ENVIRONMENT` | `undefined` | no | If set this will be the `environment` used by the proxy in the Unleash Context. It will not be possible for proxy SDKs to override the environment if set. | | +| logLevel | `LOG_LEVEL ` | "warn" | no | Used to set logLevel. Supported options: "debug", "info", "warn", "error" and "fatal" | | +| logger | n/a | SimpleLogger | no | Register a custom logger. | | +| metricsInterval | `UNLEASH_METRICS_INTERVAL` | 30000 | no | How often the proxy should send usage metrics back to Unleash, defined in ms. | | +| namePrefix | `UNLEASH_NAME_PREFIX` | undefined | no | Used to filter features by using prefix when requesting backend values. | | +| projectName | `UNLEASH_PROJECT_NAME` | `undefined` | no | The projectName (id) to fetch feature toggles for. The proxy will only return know about feature toggles that belongs to the project, if specified. | | +| proxyBasePath | `PROXY_BASE_PATH` | "" | no | The base path to run the proxy from. "/proxy" will be added at the end. For instance, if `proxyBasePath` is `"base/path"`, the proxy will run at `/base/path/proxy`. | | +| proxyPort | `PORT` | 3000 | no | The port where the proxy should listen. | | +| proxySecrets | `UNLEASH_PROXY_SECRETS` | n/a | no | Deprecated alias for `clientKeys`. Please use `clientKeys` instead. | | +| refreshInterval | `UNLEASH_FETCH_INTERVAL` | 5000 | no | How often the proxy should query Unleash for updates, defined in ms. | | +| tags | `UNLEASH_TAGS` | undefined | no | Used to filter features by using tags set for features. Format should be `tagName:tagValue,tagName2:tagValue2` | | +| trustProxy | `TRUST_PROXY ` | `false` | no | By enabling the trustProxy option, Unleash Proxy will have knowledge that it's sitting behind a proxy and that the X-Forwarded-* header fields may be trusted, which otherwise may be easily spoofed. The proxy will automatically enrich the ip address in the Unleash Context. Can either be `true/false` (Trust all proxies), trust only given IP/CIDR (e.g. `'127.0.0.1'`) as a `string`. May be a list of comma separated values (e.g. `'127.0.0.1,192.168.1.1/24'` | | +| unleashApiToken | `UNLEASH_API_TOKEN` | n/a | yes | API token (client) needed to connect to Unleash API. | | +| unleashAppName | `UNLEASH_APP_NAME` | "unleash-proxy" | no | App name to used when registering with Unleash | | +| unleashInstanceId | `UNLEASH_INSTANCE_ID` | `generated` | no | Unleash instance id to used when registering with Unleash | | +| unleashUrl | `UNLEASH_URL` | n/a | yes | API Url to the Unleash instance to connect to | | + + ### Health endpoint The proxy will try to synchronize with the Unleash API at startup, until it has successfully done that the proxy will return `HTTP 503 - Not Read?` for all request. You can use the health endpoint to validate that the proxy is ready to recieve requests: From f1601392e12d19963a7f6f30a45c122a1a73946b Mon Sep 17 00:00:00 2001 From: Thomas Heartman Date: Tue, 12 Apr 2022 13:39:02 +0200 Subject: [PATCH 08/27] docs: change title, add content to how-to guide --- .../how-to/how-to-run-the-unleash-proxy.mdx | 38 +++++++------------ 1 file changed, 14 insertions(+), 24 deletions(-) diff --git a/website/docs/how-to/how-to-run-the-unleash-proxy.mdx b/website/docs/how-to/how-to-run-the-unleash-proxy.mdx index 9300648cbc6..0680aba9020 100644 --- a/website/docs/how-to/how-to-run-the-unleash-proxy.mdx +++ b/website/docs/how-to/how-to-run-the-unleash-proxy.mdx @@ -1,33 +1,23 @@ --- -title: Unleash Proxy +title: How to run the Unleash Proxy --- -## How to Run the Unleash Proxy +The [Unleash Proxy](../sdks/unleash-proxy.md) provides a way for you to consume feature toggles in front-end clients, such as the [JavaScript Proxy client](../sdks/proxy-javascript.md) and [React Proxy client](../sdks/proxy-react.md). -The Unleash Proxy is Open Source and [available on github](https://github.com/Unleash/unleash-proxy). You can either run it as a docker image or as part of a [node.js express application](https://github.com/Unleash/unleash-proxy#run-with-nodejs). +Depending on your setup, the Proxy is most easily run in one of two ways, depending on your situation: +- Run the proxy via Docker +- Run the proxy as a Node.js app -### Configuration variables +If you're using a hosted version of Unleash, we can also run the proxy for you if you'd rather not run it yourself. -Regardless of how you choose to run the it, the proxy will need access to these three variables: +## Prerequisites -- **`unleashUrl`** / **`UNLEASH_URL`** +This is what you need to do before you can run the proxy - The URL of your Unleash instance's API. For instance, to connect to the [Unleash demo app](https://app.unleash-hosted.com/demo/), you would use `https://app.unleash-hosted.com/demo/api/` +- an unleash server to connect to +- a client API token for the proxy to use -- **`unleashApiToken`** / **`UNLEASH_API_TOKEN`** - - The API token to connect to your Unleash project. For more information on how these work and how to create them, check out the [API token documentation](../user_guide/token.md). - -- **`clientKeys`** / **`UNLEASH_PROXY_CLIENT_KEYS`** - - A list of client keys that the proxy will accept. For the proxy to accept an incoming request, the client must use one of these keys for authorization. In client SDKs, this is usually known as a `clientKey` or a `clientSecret`. If you query the proxy directly via HTTP, this is the `authorization` header. - - When using an environment variable to set the proxy secrets, the value should be a comma-separated list of strings, such as `secret-one,secret-two`. - -There are many more configuration options available. You'll find all [available options on github](https://github.com/Unleash/unleash-proxy#available-options). - - -### Running the proxy via Docker +## How to run the Proxy via Docker The easiest way to run Unleash is via Docker. We have published a [docker image on docker hub](https://hub.docker.com/r/unleashorg/unleash-proxy). @@ -53,7 +43,7 @@ The easiest way to run Unleash is via Docker. We have published a [docker image Unleash-proxy is listening on port 3000! ``` -### Running the proxy using Node.js +## How to run the Proxy as a Node.js app To run the Proxy via Node.js, you'll have to create your own Node.js project and use the Unleash Proxy as a dependency. Assuming you've already set up your project, here's the steps to take to start the proxy as part of your app: @@ -80,7 +70,7 @@ To run the Proxy via Node.js, you'll have to create your own Node.js project and ); ``` -### Verify that the proxy is working +## Verify that the proxy is working In order to verify the proxy you can use curl and see that you get a few evaluated feature toggles back. Assuming that the proxy is running on port 3000 and that your proxy client key is `some-secret`, you could run this command : @@ -90,7 +80,7 @@ curl http://localhost:3000/proxy -H "Authorization: some-secret" The output is of the form described in the [payload section](#payload). -### Health endpoint +## Health endpoint The proxy will try to synchronize with the Unleash API at startup, until it has successfully done that the proxy will return `HTTP 503 - Not Read?` for all request. You can use the health endpoint to validate that the proxy is ready to recieve requests: From dc7e93b618f8055ef4612b67a49d8770341d0c13 Mon Sep 17 00:00:00 2001 From: Thomas Heartman Date: Tue, 12 Apr 2022 15:56:44 +0200 Subject: [PATCH 09/27] docs: start smoothing out proxy docs --- .../how-to/how-to-run-the-unleash-proxy.mdx | 45 +++++++------------ 1 file changed, 16 insertions(+), 29 deletions(-) diff --git a/website/docs/how-to/how-to-run-the-unleash-proxy.mdx b/website/docs/how-to/how-to-run-the-unleash-proxy.mdx index 0680aba9020..300bd16afbe 100644 --- a/website/docs/how-to/how-to-run-the-unleash-proxy.mdx +++ b/website/docs/how-to/how-to-run-the-unleash-proxy.mdx @@ -2,7 +2,7 @@ title: How to run the Unleash Proxy --- -The [Unleash Proxy](../sdks/unleash-proxy.md) provides a way for you to consume feature toggles in front-end clients, such as the [JavaScript Proxy client](../sdks/proxy-javascript.md) and [React Proxy client](../sdks/proxy-react.md). +The [Unleash Proxy](../sdks/unleash-proxy.md) provides a way for you to consume feature toggles in [front-end clients](../sdks/index.md#front-end-sdks), such as the [JavaScript Proxy client](../sdks/proxy-javascript.md) and [React Proxy client](../sdks/proxy-react.md). Depending on your setup, the Proxy is most easily run in one of two ways, depending on your situation: - Run the proxy via Docker @@ -14,19 +14,22 @@ If you're using a hosted version of Unleash, we can also run the proxy for you i This is what you need to do before you can run the proxy -- an unleash server to connect to -- a client API token for the proxy to use +- A running Unleash server to connect to +- A client API token for the proxy to use. +- if you're running the Proxy via Docker: [the `docker` command line tool](https://www.docker.com/) +- If you're running the Proxy as a Node.js app: [Node.js and its command line tools](https://nodejs.org/). ## How to run the Proxy via Docker The easiest way to run Unleash is via Docker. We have published a [docker image on docker hub](https://hub.docker.com/r/unleashorg/unleash-proxy). -1. **Pull the Proxy image** +### 1. Pull the Proxy image + ```bash docker pull unleashorg/unleash-proxy ``` -2. **Start the proxy** +### 2. Start the proxy ```bash docker run \ @@ -37,7 +40,7 @@ The easiest way to run Unleash is via Docker. We have published a [docker image unleashorg/unleash-proxy ``` - You should see the following output: +You should see the following output: ```bash Unleash-proxy is listening on port 3000! @@ -47,12 +50,16 @@ The easiest way to run Unleash is via Docker. We have published a [docker image To run the Proxy via Node.js, you'll have to create your own Node.js project and use the Unleash Proxy as a dependency. Assuming you've already set up your project, here's the steps to take to start the proxy as part of your app: -1. **Install the Unleash Proxy package** +### 1. Install the Unleash Proxy package + ``` shell npm2yarn npm install @unleash/proxy ``` -2. **Initialize and start the proxy in your code.** A fully working sample app that uses the proxy: +### 2. Initialize and start the proxy in your code. + +A fully working sample app that uses the proxy: + ``` js const port = 3000; @@ -78,24 +85,4 @@ In order to verify the proxy you can use curl and see that you get a few evaluat curl http://localhost:3000/proxy -H "Authorization: some-secret" ``` -The output is of the form described in the [payload section](#payload). - -## Health endpoint - -The proxy will try to synchronize with the Unleash API at startup, until it has successfully done that the proxy will return `HTTP 503 - Not Read?` for all request. You can use the health endpoint to validate that the proxy is ready to recieve requests: - -```bash -curl http://localhost:3000/proxy/health -I -``` - -```bash -HTTP/1.1 200 OK -Access-Control-Allow-Origin: * -Access-Control-Expose-Headers: ETag -Content-Type: text/html; charset=utf-8 -Content-Length: 2 -ETag: W/"2-eoX0dku9ba8cNUXvu/DyeabcC+s" -Date: Fri, 04 Jun 2021 10:38:27 GMT -Connection: keep-alive -Keep-Alive: timeout=5 -``` +Check the reference docs for API return values From 0a0ade18df71b9c80efd693787f3d0a121a1b022 Mon Sep 17 00:00:00 2001 From: Thomas Heartman Date: Tue, 12 Apr 2022 15:57:04 +0200 Subject: [PATCH 10/27] docs: add API tokens placeholder document --- website/docs/reference/api-tokens.mdx | 3 +++ 1 file changed, 3 insertions(+) create mode 100644 website/docs/reference/api-tokens.mdx diff --git a/website/docs/reference/api-tokens.mdx b/website/docs/reference/api-tokens.mdx new file mode 100644 index 00000000000..7e10a088a62 --- /dev/null +++ b/website/docs/reference/api-tokens.mdx @@ -0,0 +1,3 @@ +--- +title: API tokens +--- From bba6d6de945453704e6f9b1a8145e6183da20be3 Mon Sep 17 00:00:00 2001 From: Thomas Heartman Date: Tue, 12 Apr 2022 15:58:53 +0200 Subject: [PATCH 11/27] docs: add api tokens outline --- website/docs/reference/api-tokens.mdx | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/website/docs/reference/api-tokens.mdx b/website/docs/reference/api-tokens.mdx index 7e10a088a62..909aabac749 100644 --- a/website/docs/reference/api-tokens.mdx +++ b/website/docs/reference/api-tokens.mdx @@ -1,3 +1,13 @@ --- title: API tokens --- + +Unleash has a number of tokens/keys that all have slightly different use cases. Here's the list of all of them: + +## API tokens + +### Admin tokens + +### Client tokens + +## Proxy client keys (not actual tokens!) From 07de36f6c4b38caf8566ff1a6aee537b90b0d913 Mon Sep 17 00:00:00 2001 From: Thomas Heartman Date: Tue, 12 Apr 2022 16:02:16 +0200 Subject: [PATCH 12/27] docs: add api-tokens to sidebar --- website/sidebars.js | 1 + 1 file changed, 1 insertion(+) diff --git a/website/sidebars.js b/website/sidebars.js index 7bd76354b04..a8acced228f 100644 --- a/website/sidebars.js +++ b/website/sidebars.js @@ -259,6 +259,7 @@ module.exports = { label: 'Unleash concepts', items: [ 'user_guide/activation_strategy', + 'reference/api-tokens', 'advanced/archived_toggles', 'advanced/audit_log', 'advanced/impression-data', From f7081d5f3a1f618efef2817674ae9727a90cb3d0 Mon Sep 17 00:00:00 2001 From: Thomas Heartman Date: Wed, 13 Apr 2022 13:45:01 +0200 Subject: [PATCH 13/27] docs: First draft of API tokens and client keys doc --- website/docs/reference/api-tokens.mdx | 94 ++++++++++++++++++++++++++- 1 file changed, 92 insertions(+), 2 deletions(-) diff --git a/website/docs/reference/api-tokens.mdx b/website/docs/reference/api-tokens.mdx index 909aabac749..042caacd651 100644 --- a/website/docs/reference/api-tokens.mdx +++ b/website/docs/reference/api-tokens.mdx @@ -1,13 +1,103 @@ --- -title: API tokens +title: API tokens and client keys --- Unleash has a number of tokens/keys that all have slightly different use cases. Here's the list of all of them: ## API tokens +Use API tokens to connect to the Unleash server API. API tokens come in two distinct types: +- [Admin tokens](#admin-tokens) +- [Client tokens](#client-tokens) + +Both types have use [the same format](#format) but have different intended uses. API tokens are considered to be *secrets* and should _not_ be exposed to end users. + ### Admin tokens +**Admin tokens** grant *full read and write access* to all resources in the Unleash server API. Admin tokens have access to all projects, all environments, and all global resources (find out more about [resources in the RBAC document](../user_guide/rbac.md#core-principles)). + +Use admin tokens to: +- automate Unleash behavior such as creating feature toggles, projects, etc. +- write custom Unleash UIs to replace the default Unleash admin UI + +Do _not_ use admin tokens for: +- [Client SDKs](../sdks/index.md): You will _not_ be able to read toggle data from multiple environments. Use [client tokens](#client-tokens) instead. + +Support for scoped admin tokens with more fine-grained permissions is currently in the planning stage. + ### Client tokens -## Proxy client keys (not actual tokens!) +**Client tokens** are intended for use in [server-side client SDKs](../sdks/index.md#server-side-sdks) (including the Unleash Proxy) and grant the user permissions to: +- Read feature toggle information +- Register applications with the Unleash server +- Send usage metrics + +When creating a client token, you can choose which projects it should be able to read data from. You can give it access to a specific list of projects or to all projects (including projects that don't exist yet). + +Each client token is only **valid for a single environment**. + +Use client tokens: +- In [server-side client SDKs](../sdks/index.md#server-side-sdks) +- To connect [the Unleash Proxy](../sdks/unleash-proxy.md) to the Unleash API + +Do _not_ use client tokens: +- In [front-end SDKs](../sdks/index.md#front-end-sdks). You will _not_ be able to connect to the Unleash server due to CORS restrictions. Use [Proxy client keys](#proxy-client-keys) instead. + +### Format + +API tokens come in one of two formats. When we introduced [environments](../user_guide/environments.md) in Unleash 4.3, we updated the format of the tokens to provide more human-readable information to the user. Both formats are still valid (you don't need to update a working token of the old format) and are described below. + +#### Version 1 + +The first version of API tokens was a 64 character long hexadecimal string. Example: + +``` +be44368985f7fb3237c584ef86f3d6bdada42ddbd63a019d26955178 +``` + + +#### Version 2 + +API tokens consist of three parts: + +1. Project(s) +2. Environment +3. Hash + +The parts are separated by two different separators: A colon (`:`) between the project(s) and the environment, and a full stop (`.`) between the environment and the hash. + +The **project(s)** part is one of: +- The id of a specific project, for example: `default`. This indicates that the token is **only valid for this project**. +- A pair of opening and closing square brackets: `[]`. This indicates that the token is **valid for a discrete list of projects**. The list of projects is not shown in the token. +- An asterisk: `*`. This indicates that the token is **valid for all projects (current and future)**. + +The **environment** is the name of an environment on your Unleash server, such as `development`. + +The **hash** is 64 character long hexadecimal string. + +Some example client tokens are: +- A token with access to toggles in the "development" environment of a single project, "project-a": + ``` + project-a:development.be44368985f7fb3237c584ef86f3d6bdada42ddbd63a019d26955178 + ``` +- A token with access to toggles in the "production" environment multiple projects: + ``` + []:production.be44368985f7fb3237c584ef86f3d6bdada42ddbd63a019d26955178 + ``` +- A token with access to toggles in the "development" environment of all projects: + ``` + *:development.be44368985f7fb3237c584ef86f3d6bdada42ddbd63a019d26955178 + ``` + +## Proxy client keys {#proxy-client-keys} + +Use proxy client keys to connect [front-end client SDKs](../sdks/index.md#front-end-sdks) to the [Unleash Proxy](../sdks/unleash-proxy.md). As opposed to the [API tokens](#api-tokens), Proxy client keys are *not* considered secret and are safe to use on any clients (refer to the [the proxy documentation for more about privacy](../sdks/unleash-proxy.md#we-care-about-privacy)). They do _not_ let you connect to the Unleash server API. + +Proxy client keys are arbitrary strings that you *must* provide the Unleash proxy with on startup. Unleash does not generate proxy client keys for you. Because of this, they have no specific format. + +Use Proxy client keys to: +- Connect [Proxy client SDKs](../sdks/index.md#front-end-sdks) to the [Unleash Proxy](../sdks/unleash-proxy.md) +- Connect your own custom Proxy clients (or pure HTTP requests) to the Unleash Proxy + +Do *not* use Proxy client keys to: +- Connect to the Unleash API. It will not work. Use an appropriate [API token](#api-tokens) instead. From 88450a8946a77f6e8720e643d388cb93eef1d039 Mon Sep 17 00:00:00 2001 From: Thomas Heartman Date: Wed, 13 Apr 2022 13:46:12 +0200 Subject: [PATCH 14/27] docs: rename api token + client key doc --- .../{api-tokens.mdx => api-tokens-and-client-keys.mdx} | 0 website/sidebars.js | 2 +- 2 files changed, 1 insertion(+), 1 deletion(-) rename website/docs/reference/{api-tokens.mdx => api-tokens-and-client-keys.mdx} (100%) diff --git a/website/docs/reference/api-tokens.mdx b/website/docs/reference/api-tokens-and-client-keys.mdx similarity index 100% rename from website/docs/reference/api-tokens.mdx rename to website/docs/reference/api-tokens-and-client-keys.mdx diff --git a/website/sidebars.js b/website/sidebars.js index a8acced228f..63b6c4b2d20 100644 --- a/website/sidebars.js +++ b/website/sidebars.js @@ -259,7 +259,7 @@ module.exports = { label: 'Unleash concepts', items: [ 'user_guide/activation_strategy', - 'reference/api-tokens', + 'reference/api-tokens-and-client-keys', 'advanced/archived_toggles', 'advanced/audit_log', 'advanced/impression-data', From e0a87c68a0e70255ea46054de7dda056e9d0b4f5 Mon Sep 17 00:00:00 2001 From: Thomas Heartman Date: Wed, 13 Apr 2022 13:47:27 +0200 Subject: [PATCH 15/27] docs: minor tweaks for client keys --- website/docs/reference/api-tokens-and-client-keys.mdx | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/website/docs/reference/api-tokens-and-client-keys.mdx b/website/docs/reference/api-tokens-and-client-keys.mdx index 042caacd651..f4c80a48305 100644 --- a/website/docs/reference/api-tokens-and-client-keys.mdx +++ b/website/docs/reference/api-tokens-and-client-keys.mdx @@ -20,7 +20,7 @@ Use admin tokens to: - automate Unleash behavior such as creating feature toggles, projects, etc. - write custom Unleash UIs to replace the default Unleash admin UI -Do _not_ use admin tokens for: +Do **not** use admin tokens for: - [Client SDKs](../sdks/index.md): You will _not_ be able to read toggle data from multiple environments. Use [client tokens](#client-tokens) instead. Support for scoped admin tokens with more fine-grained permissions is currently in the planning stage. @@ -40,8 +40,8 @@ Use client tokens: - In [server-side client SDKs](../sdks/index.md#server-side-sdks) - To connect [the Unleash Proxy](../sdks/unleash-proxy.md) to the Unleash API -Do _not_ use client tokens: -- In [front-end SDKs](../sdks/index.md#front-end-sdks). You will _not_ be able to connect to the Unleash server due to CORS restrictions. Use [Proxy client keys](#proxy-client-keys) instead. +Do **not** use client tokens in: +- [Front-end SDKs](../sdks/index.md#front-end-sdks). You will _not_ be able to connect to the Unleash server due to CORS restrictions. Configure an [Unleash Proxy](../sdks/unleash-proxy.md) and use [Proxy client keys](#proxy-client-keys) instead. ### Format @@ -99,5 +99,5 @@ Use Proxy client keys to: - Connect [Proxy client SDKs](../sdks/index.md#front-end-sdks) to the [Unleash Proxy](../sdks/unleash-proxy.md) - Connect your own custom Proxy clients (or pure HTTP requests) to the Unleash Proxy -Do *not* use Proxy client keys to: +Do **not** use Proxy client keys to: - Connect to the Unleash API. It will not work. Use an appropriate [API token](#api-tokens) instead. From 0f9da03078fb94eee0e0bbf43ecc635c5daf7c2c Mon Sep 17 00:00:00 2001 From: Thomas Heartman Date: Wed, 13 Apr 2022 13:53:15 +0200 Subject: [PATCH 16/27] docs: link to the how-to guide for creating tokens --- website/docs/reference/api-tokens-and-client-keys.mdx | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/website/docs/reference/api-tokens-and-client-keys.mdx b/website/docs/reference/api-tokens-and-client-keys.mdx index f4c80a48305..9926eb06dd5 100644 --- a/website/docs/reference/api-tokens-and-client-keys.mdx +++ b/website/docs/reference/api-tokens-and-client-keys.mdx @@ -6,6 +6,10 @@ Unleash has a number of tokens/keys that all have slightly different use cases. ## API tokens +:::tip +This section describes what API tokens are. For information on how to create them, refer to the [how-to guide for creating API tokens](../user_guide/token.md). +::: + Use API tokens to connect to the Unleash server API. API tokens come in two distinct types: - [Admin tokens](#admin-tokens) - [Client tokens](#client-tokens) From 5e382e64dcd5742430e2771f48942c4dfc109d57 Mon Sep 17 00:00:00 2001 From: Thomas Heartman Date: Wed, 13 Apr 2022 15:06:42 +0200 Subject: [PATCH 17/27] docs: api request and placeholders to proxy how-to --- .../how-to/how-to-run-the-unleash-proxy.mdx | 122 ++++++++++-------- 1 file changed, 71 insertions(+), 51 deletions(-) diff --git a/website/docs/how-to/how-to-run-the-unleash-proxy.mdx b/website/docs/how-to/how-to-run-the-unleash-proxy.mdx index 300bd16afbe..642d7eb256f 100644 --- a/website/docs/how-to/how-to-run-the-unleash-proxy.mdx +++ b/website/docs/how-to/how-to-run-the-unleash-proxy.mdx @@ -1,88 +1,108 @@ --- title: How to run the Unleash Proxy --- +import ApiRequest from '@site/src/components/ApiRequest' + +:::info Placeholders +Placeholders in the code samples below are delimited by angle brackets (i.e. ``). You will need to replace them with the values that are correct in _your_ situation for the code samples to run properly. +::: + The [Unleash Proxy](../sdks/unleash-proxy.md) provides a way for you to consume feature toggles in [front-end clients](../sdks/index.md#front-end-sdks), such as the [JavaScript Proxy client](../sdks/proxy-javascript.md) and [React Proxy client](../sdks/proxy-react.md). Depending on your setup, the Proxy is most easily run in one of two ways, depending on your situation: -- Run the proxy via Docker -- Run the proxy as a Node.js app +- [Via Docker](#run-proxy-via-docker) +- [As a Node.js app](#run-proxy-as-node-app) -If you're using a hosted version of Unleash, we can also run the proxy for you if you'd rather not run it yourself. +If you're using a hosted version of Unleash, we can also run the proxy for you. ## Prerequisites -This is what you need to do before you can run the proxy +This is what you need before you can run the proxy: -- A running Unleash server to connect to -- A client API token for the proxy to use. -- if you're running the Proxy via Docker: [the `docker` command line tool](https://www.docker.com/) +- A running Unleash server to connect to. You'll need its API path (e.g. `https://app.unleash-hosted.com/demo/api`) to connect the proxy to it. +- A [client API token](../reference/api-tokens-and-client-keys#client-tokens) for the proxy to use. +- If you're running the Proxy via Docker: [the `docker` command line tool](https://www.docker.com/). - If you're running the Proxy as a Node.js app: [Node.js and its command line tools](https://nodejs.org/). +- A [Proxy client key](../reference/api-tokens-and-client-keys#proxy-client-keys). This can be any arbitrary string (for instance: `proxy-client-key`). Use this key when connecting a client SDK to the Proxy. -## How to run the Proxy via Docker +## How to run the Proxy via Docker {#run-proxy-via-docker} -The easiest way to run Unleash is via Docker. We have published a [docker image on docker hub](https://hub.docker.com/r/unleashorg/unleash-proxy). +We provide a [Docker image (available on on Docker Hub)](https://hub.docker.com/r/unleashorg/unleash-proxy) that you can use to run the proxy. ### 1. Pull the Proxy image - ```bash - docker pull unleashorg/unleash-proxy - ``` +Use the `docker` command to pull the Proxy image: -### 2. Start the proxy +```bash title="Pull the Unleash Proxy docker image" +docker pull unleashorg/unleash-proxy +``` - ```bash - docker run \ - -e UNLEASH_PROXY_CLIENT_KEYS=some-secret \ - -e UNLEASH_URL='https://app.unleash-hosted.com/demo/api/' \ - -e UNLEASH_API_TOKEN=56907a2fa53c1d16101d509a10b78e36190b0f918d9f122d \ - -p 3000:3000 \ - unleashorg/unleash-proxy - ``` +### 2. Start the Proxy -You should see the following output: +When running the Proxy, you'll need to provide it with at least the configuration options listed below. Check the reference docs for the [full list of configuration options](../sdks/unleash-proxy.md#configuration-options). - ```bash - Unleash-proxy is listening on port 3000! - ``` +```bash title="Run the Unleash Proxy via Docker" +docker run \ + -e UNLEASH_PROXY_CLIENT_KEYS= \ + -e UNLEASH_URL='' \ + -e UNLEASH_API_TOKEN= \ + -p 3000:3000 \ + unleashorg/unleash-proxy +``` -## How to run the Proxy as a Node.js app +If the proxy starts up successfully, you should see the following output: -To run the Proxy via Node.js, you'll have to create your own Node.js project and use the Unleash Proxy as a dependency. Assuming you've already set up your project, here's the steps to take to start the proxy as part of your app: +```bash +Unleash-proxy is listening on port 3000! +``` -### 1. Install the Unleash Proxy package +## How to run the Proxy as a Node.js app {#run-proxy-as-node-app} - ``` shell npm2yarn - npm install @unleash/proxy - ``` +To run the Proxy via Node.js, you'll have to create your own Node.js project and use the Unleash Proxy as a dependency. -### 2. Initialize and start the proxy in your code. +### 1. initialize the project -A fully working sample app that uses the proxy: +If you don't already have an existing Node.js project, create one: - ``` js - const port = 3000; +``` bash npm2yarn +npm init +``` - const { createApp } = require('@unleash/proxy'); +### 2. Install the Unleash Proxy package - const app = createApp({ - unleashUrl: 'https://app.unleash-hosted.com/demo/api/', - unleashApiToken: '56907a2fa53c1d16101d509a10b78e36190b0f918d9f122d', - clientKeys: ['some-secret', 'another-proxy-secret', 's1'], - refreshInterval: 1000, - }); +Install the Unleash Proxy as a dependency: - app.listen(port, () => - console.log(`Unleash Proxy listening on http://localhost:${port}/proxy`), - ); - ``` +``` shell npm2yarn +npm install @unleash/proxy +``` -## Verify that the proxy is working +### 3. Configure and start the proxy -In order to verify the proxy you can use curl and see that you get a few evaluated feature toggles back. Assuming that the proxy is running on port 3000 and that your proxy client key is `some-secret`, you could run this command : +Import the `createApp` function from `@unleash/proxy` and configure the proxy. You'll need to provide at least the configuration options highlighted below. Check the reference docs for the [full list of configuration options](../sdks/unleash-proxy.md#configuration-options). -```bash -curl http://localhost:3000/proxy -H "Authorization: some-secret" +Here is an example of what running the Proxy as a Node.js app might look like: + +``` js title="Sample app running the Unleash Proxy" +const port = 3000; + +const { createApp } = require('@unleash/proxy'); + +const app = createApp({ + // highlight-start + unleashUrl: '', + unleashApiToken: '', + clientKeys: [''], + // highlight-end +}); + +app.listen(port, () => + console.log(`Unleash Proxy listening on http://localhost:${port}/proxy`), +); ``` -Check the reference docs for API return values +## Verify that the proxy is working + +When the proxy process has started up correctly, you can start querying its `/proxy` endpoint. If it's running correctly, you'll get back a JSON object with a list of toggles. The list may be empty if you haven't added any toggles for the corresponding project/environment yet. + + From 93d2ef55b952ae397a09824bc0474aac5ef99f3d Mon Sep 17 00:00:00 2001 From: Thomas Heartman Date: Wed, 13 Apr 2022 15:07:11 +0200 Subject: [PATCH 18/27] chore: clarify proxy clients vs front-end clients --- website/docs/reference/api-tokens-and-client-keys.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/docs/reference/api-tokens-and-client-keys.mdx b/website/docs/reference/api-tokens-and-client-keys.mdx index 9926eb06dd5..eb9ff0032f6 100644 --- a/website/docs/reference/api-tokens-and-client-keys.mdx +++ b/website/docs/reference/api-tokens-and-client-keys.mdx @@ -95,7 +95,7 @@ Some example client tokens are: ## Proxy client keys {#proxy-client-keys} -Use proxy client keys to connect [front-end client SDKs](../sdks/index.md#front-end-sdks) to the [Unleash Proxy](../sdks/unleash-proxy.md). As opposed to the [API tokens](#api-tokens), Proxy client keys are *not* considered secret and are safe to use on any clients (refer to the [the proxy documentation for more about privacy](../sdks/unleash-proxy.md#we-care-about-privacy)). They do _not_ let you connect to the Unleash server API. +Use proxy client keys to connect [Proxy client SDKs (front-end SDKs)](../sdks/index.md#front-end-sdks) to the [Unleash Proxy](../sdks/unleash-proxy.md). As opposed to the [API tokens](#api-tokens), Proxy client keys are *not* considered secret and are safe to use on any clients (refer to the [the proxy documentation for more about privacy](../sdks/unleash-proxy.md#we-care-about-privacy)). They do _not_ let you connect to the Unleash server API. Proxy client keys are arbitrary strings that you *must* provide the Unleash proxy with on startup. Unleash does not generate proxy client keys for you. Because of this, they have no specific format. From ecbae418d48dfd5f4d9a9d17f6aea0e5d667e5ed Mon Sep 17 00:00:00 2001 From: Thomas Heartman Date: Wed, 13 Apr 2022 15:15:08 +0200 Subject: [PATCH 19/27] feat: allow ApiRequest component to create proxy requests --- .../ApiRequest/ApiRequest.stories.jsx | 8 ++ website/src/components/ApiRequest/index.tsx | 74 ++++++++++++------- 2 files changed, 55 insertions(+), 27 deletions(-) diff --git a/website/src/components/ApiRequest/ApiRequest.stories.jsx b/website/src/components/ApiRequest/ApiRequest.stories.jsx index 257fc77afc2..4c177e42d7c 100644 --- a/website/src/components/ApiRequest/ApiRequest.stories.jsx +++ b/website/src/components/ApiRequest/ApiRequest.stories.jsx @@ -53,3 +53,11 @@ DELETE.args = { url: 'api/admin/projects//features/', title: 'Create a feature toggle with impression data enabled.', }; + +export const GETProxy = Template.bind({}); +GETProxy.args = { + verb: 'get', + url: 'proxy', + title: 'Request toggles from the Unleash Proxy', + endpointType: 'Proxy API', +}; diff --git a/website/src/components/ApiRequest/index.tsx b/website/src/components/ApiRequest/index.tsx index de29343edb1..4727dd91fce 100644 --- a/website/src/components/ApiRequest/index.tsx +++ b/website/src/components/ApiRequest/index.tsx @@ -18,47 +18,67 @@ import CodeBlock from '@theme/CodeBlock'; const indentation = 2; type Props = { - verb: string, - payload?: any, - url: string, - title?: string -} + verb: string; + payload?: any; + url: string; + title?: string; + endpointType?: 'Proxy API' | 'Unleash server API'; +}; -const Component: React.FC = ({ verb, payload, url, title }) => { +const Component: React.FC = ({ + verb, + payload, + url, + title, + endpointType = 'Unleash server API', +}) => { const verbUpper = verb?.toUpperCase() || ''; const prettyPayload = JSON.stringify(payload, null, indentation); + const [baseUrl, authToken] = + endpointType === 'Unleash server API' + ? ['unleash-url', 'API-token'] + : ['proxy-url', 'proxy-client-key']; - const httpBlock = (payload ? ` -${verbUpper} /${url} -Authorization: + const httpBlock = ( + payload + ? ` +${verbUpper} <${baseUrl}>/${url} +Authorization: <${authToken}> content-type: application/json -${prettyPayload}` :` -${verbUpper} /${url} -Authorization: -content-type: application/json`).trim() +${prettyPayload}` + : ` +${verbUpper} <${baseUrl}>/${url} +Authorization: <${authToken}> +content-type: application/json` + ).trim(); - const curlBlock = (payload ? ` + const curlBlock = ( + payload + ? ` curl -H "Content-Type: application/json" \\ - -H "Authorization: " \\ + -H "Authorization: <${authToken}>" \\ -X ${verbUpper} \\ -d '${prettyPayload}' \\ - /${url}` : ` + <${baseUrl}>/${url}` + : ` curl -H "Content-Type: application/json" \\ - -H "Authorization: " \\ + -H "Authorization: <${authToken}>" \\ -X ${verbUpper} \\ - /${url}` ).trim() + <${baseUrl}>/${url}` + ).trim(); - const httpieBlock = (payload ? - `echo '${prettyPayload}' \\ + const httpieBlock = ( + payload + ? `echo '${prettyPayload}' \\ | http ${verbUpper} \\ - /${url} \\ - Authorization:` - : ` + <${baseUrl}>/${url} \\ + Authorization:<${authToken}>` + : ` http ${verbUpper} \\ - /${url} \\ - Authorization:`.trim() - ).trim() + <${baseUrl}>/${url} \\ + Authorization:<${authToken}>`.trim() + ).trim(); return ( @@ -69,7 +89,7 @@ http ${verbUpper} \\ - {curlBlock} + {curlBlock} From 6a71c27593324172663daa53a63b96a7d095add2 Mon Sep 17 00:00:00 2001 From: Thomas Heartman Date: Wed, 13 Apr 2022 15:15:27 +0200 Subject: [PATCH 20/27] docs: Update ApiRequest in how-to guide for proxy --- website/docs/how-to/how-to-run-the-unleash-proxy.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/docs/how-to/how-to-run-the-unleash-proxy.mdx b/website/docs/how-to/how-to-run-the-unleash-proxy.mdx index 642d7eb256f..96c0a5adb45 100644 --- a/website/docs/how-to/how-to-run-the-unleash-proxy.mdx +++ b/website/docs/how-to/how-to-run-the-unleash-proxy.mdx @@ -105,4 +105,4 @@ app.listen(port, () => When the proxy process has started up correctly, you can start querying its `/proxy` endpoint. If it's running correctly, you'll get back a JSON object with a list of toggles. The list may be empty if you haven't added any toggles for the corresponding project/environment yet. - + From ac9f800ba85e62017174b950188820e6f8a636c4 Mon Sep 17 00:00:00 2001 From: Thomas Heartman Date: Wed, 13 Apr 2022 15:37:04 +0200 Subject: [PATCH 21/27] docs: add details to the configuration option table --- website/docs/sdks/unleash-proxy.md | 76 +++++++++++++----------------- 1 file changed, 33 insertions(+), 43 deletions(-) diff --git a/website/docs/sdks/unleash-proxy.md b/website/docs/sdks/unleash-proxy.md index 3cf286537e7..86f391fa414 100644 --- a/website/docs/sdks/unleash-proxy.md +++ b/website/docs/sdks/unleash-proxy.md @@ -21,52 +21,42 @@ _The Unleash Proxy uses the Unleash SDK and exposes a simple API_. The Proxy wil ## Configuration -### Required configuration variables +:::info +You **must configure** these three variables for the proxy to start successfully: +- `unleashUrl` / `UNLEASH_URL` -Regardless of how you choose to run the it, the proxy will need access to these three variables: - -- **`unleashUrl`** / **`UNLEASH_URL`** - - The URL of your Unleash instance's API. For instance, to connect to the [Unleash demo app](https://app.unleash-hosted.com/demo/), you would use `https://app.unleash-hosted.com/demo/api/` - -- **`unleashApiToken`** / **`UNLEASH_API_TOKEN`** - - The API token to connect to your Unleash project. For more information on how these work and how to create them, check out the [API token documentation](../user_guide/token.md). +- `unleashApiToken` / `UNLEASH_API_TOKEN` -- **`clientKeys`** / **`UNLEASH_PROXY_CLIENT_KEYS`** - - A list of client keys that the proxy will accept. For the proxy to accept an incoming request, the client must use one of these keys for authorization. In client SDKs, this is usually known as a `clientKey` or a `clientSecret`. If you query the proxy directly via HTTP, this is the `authorization` header. - - When using an environment variable to set the proxy secrets, the value should be a comma-separated list of strings, such as `secret-one,secret-two`. - -There are many more configuration options available. You'll find all [available options on github](https://github.com/Unleash/unleash-proxy#available-options). +- `clientKeys` / `UNLEASH_PROXY_CLIENT_KEYS` +::: -### All configuration options - -| Option | Environment Variable | Default value | Required | Description | | -|----------------------|----------------------------------|-----------------|:--------:|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---| -| clientKeys | `UNLEASH_PROXY_CLIENT_KEYS` | n/a | yes | List of client keys that the proxy should accept. When querying the proxy, Proxy SDKs must set the request's _client keys header_ to one of these values. The default client keys header is `Authorization`. | | -| clientKeysHeaderName | `CLIENT_KEY_HEADER_NAME` | "authorization" | no | The name of the HTTP header to use for client keys. Incoming requests must set the value of this header to one of the Proxy's `clientKeys` to be authorized successfully. | | -| customStrategies | `UNLEASH_CUSTOM_STRATEGIES_FILE` | [] | no | Use this option to inject implementation of custom activation strategies. If you are using `UNLEASH_CUSTOM_STRATEGIES_FILE` you need to provide a valid path to a javascript files which exports an array of custom activation strategies and the SDK will automatically load these | | -| environment | `UNLEASH_ENVIRONMENT` | `undefined` | no | If set this will be the `environment` used by the proxy in the Unleash Context. It will not be possible for proxy SDKs to override the environment if set. | | -| logLevel | `LOG_LEVEL ` | "warn" | no | Used to set logLevel. Supported options: "debug", "info", "warn", "error" and "fatal" | | -| logger | n/a | SimpleLogger | no | Register a custom logger. | | -| metricsInterval | `UNLEASH_METRICS_INTERVAL` | 30000 | no | How often the proxy should send usage metrics back to Unleash, defined in ms. | | -| namePrefix | `UNLEASH_NAME_PREFIX` | undefined | no | Used to filter features by using prefix when requesting backend values. | | -| projectName | `UNLEASH_PROJECT_NAME` | `undefined` | no | The projectName (id) to fetch feature toggles for. The proxy will only return know about feature toggles that belongs to the project, if specified. | | -| proxyBasePath | `PROXY_BASE_PATH` | "" | no | The base path to run the proxy from. "/proxy" will be added at the end. For instance, if `proxyBasePath` is `"base/path"`, the proxy will run at `/base/path/proxy`. | | -| proxyPort | `PORT` | 3000 | no | The port where the proxy should listen. | | -| proxySecrets | `UNLEASH_PROXY_SECRETS` | n/a | no | Deprecated alias for `clientKeys`. Please use `clientKeys` instead. | | -| refreshInterval | `UNLEASH_FETCH_INTERVAL` | 5000 | no | How often the proxy should query Unleash for updates, defined in ms. | | -| tags | `UNLEASH_TAGS` | undefined | no | Used to filter features by using tags set for features. Format should be `tagName:tagValue,tagName2:tagValue2` | | -| trustProxy | `TRUST_PROXY ` | `false` | no | By enabling the trustProxy option, Unleash Proxy will have knowledge that it's sitting behind a proxy and that the X-Forwarded-* header fields may be trusted, which otherwise may be easily spoofed. The proxy will automatically enrich the ip address in the Unleash Context. Can either be `true/false` (Trust all proxies), trust only given IP/CIDR (e.g. `'127.0.0.1'`) as a `string`. May be a list of comma separated values (e.g. `'127.0.0.1,192.168.1.1/24'` | | -| unleashApiToken | `UNLEASH_API_TOKEN` | n/a | yes | API token (client) needed to connect to Unleash API. | | -| unleashAppName | `UNLEASH_APP_NAME` | "unleash-proxy" | no | App name to used when registering with Unleash | | -| unleashInstanceId | `UNLEASH_INSTANCE_ID` | `generated` | no | Unleash instance id to used when registering with Unleash | | -| unleashUrl | `UNLEASH_URL` | n/a | yes | API Url to the Unleash instance to connect to | | - - -### Health endpoint +The Proxy has a large number of configuration options that you can use to adjust it to your specific use case. The table below lists all the available options. + +| Option | Environment Variable | Default value | Required | Description | +|------------------------|----------------------------------|--------------------|:--------:|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `clientKeys` | `UNLEASH_PROXY_CLIENT_KEYS` | n/a | yes | List of [client keys](../reference/api-tokens-and-client-keys.mdx#proxy-client-keys) that the proxy should accept. When querying the proxy, Proxy SDKs must set the request's _client keys header_ to one of these values. The default client keys header is `Authorization`. When using an environment variable to set the proxy secrets, the value should be a comma-separated list of strings, such as `secret-one,secret-two`. | +| | | | | | +| `clientKeysHeaderName` | `CLIENT_KEY_HEADER_NAME` | `"authorization"` | no | The name of the HTTP header to use for client keys. Incoming requests must set the value of this header to one of the Proxy's `clientKeys` to be authorized successfully. | +| `customStrategies` | `UNLEASH_CUSTOM_STRATEGIES_FILE` | `[]` | no | Use this option to inject implementation of custom activation strategies. If you are using `UNLEASH_CUSTOM_STRATEGIES_FILE`: provide a valid path to a JavaScript file which exports an array of custom activation strategies. | +| `environment` | `UNLEASH_ENVIRONMENT` | `undefined` | no | If set this will be the `environment` used by the proxy in the Unleash Context. It will not be possible for proxy SDKs to override the environment if set. | +| `logLevel` | `LOG_LEVEL ` | `"warn"` | no | Used to set `logLevel`. Supported options: `"debug"`, `"info"`, `"warn"`, `"error"` and `"fatal"` | +| `logger` | n/a | `SimpleLogger` | no | Register a custom logger. | +| `metricsInterval` | `UNLEASH_METRICS_INTERVAL` | `30000` | no | How often the proxy should send usage metrics back to Unleash, defined in ms. | +| `namePrefix` | `UNLEASH_NAME_PREFIX` | `undefined` | no | If set, the Proxy will only fetch toggles whose name start with the provided prefix. | +| `projectName` | `UNLEASH_PROJECT_NAME` | `undefined` | no | If set, the Proxy will only fetch toggles belonging to the project with this ID. | +| `proxyBasePath` | `PROXY_BASE_PATH` | `""` | no | The base path to run the proxy from. "/proxy" will be added at the end. For instance, if `proxyBasePath` is `"base/path"`, the proxy will run at `/base/path/proxy`. | +| `proxyPort` | `PORT` | `3000` | no | The port to run the proxy on. | +| `proxySecrets` | `UNLEASH_PROXY_SECRETS` | n/a | no | Deprecated alias for `clientKeys`. Please use `clientKeys` instead. | +| `refreshInterval` | `UNLEASH_FETCH_INTERVAL` | `5000` | no | How often the proxy should query Unleash for updates, defined in ms. | +| `tags` | `UNLEASH_TAGS` | `undefined` | no | If set, the proxy will only fetch feature toggles with these [tags](../advanced/tags.md). The format should be `tagName:tagValue,tagName2:tagValue2` | +| `trustProxy` | `TRUST_PROXY ` | `false` | no | If enabled, the Unleash Proxy will know that it is itself sitting behind a proxy and that the `X-Forwarded-*` header fields (which otherwise may be easily spoofed) can be trusted. The proxy will automatically enrich the IP address in the Unleash Context. Can be `true/false` (trust all proxies) or a string (trust only given IP/CIDR (e.g. `'127.0.0.1'`)). If it is a string, it can also be a list of comma separated values (e.g. `'127.0.0.1,192.168.1.1/24'` | +| `unleashApiToken` | `UNLEASH_API_TOKEN` | n/a | yes | The [client API token](../reference/api-tokens-and-client-keys.mdx#client-tokens) for connecting to Unleash API. | +| `unleashAppName` | `UNLEASH_APP_NAME` | `"unleash-proxy" ` | no | The application name to use when registering with Unleash | +| `unleashInstanceId` | `UNLEASH_INSTANCE_ID` | auto-generated | no | A unique(-ish) identifier for your instance. Typically a hostname, pod id or something similar. Unleash uses this to separate metrics from the client SDKs with the same `unleashAppName`. | +| `unleashUrl` | `UNLEASH_URL` | n/a | yes | The API URL of the Unleash instance you want to connect to. | + + +## Health endpoint The proxy will try to synchronize with the Unleash API at startup, until it has successfully done that the proxy will return `HTTP 503 - Not Read?` for all request. You can use the health endpoint to validate that the proxy is ready to recieve requests: From b43d9b05db5c6ffc74e89868de22f03edfd53719 Mon Sep 17 00:00:00 2001 From: Thomas Heartman Date: Wed, 13 Apr 2022 15:39:04 +0200 Subject: [PATCH 22/27] docs: link to the how-to guide from the proxy reference docs --- website/docs/sdks/unleash-proxy.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/website/docs/sdks/unleash-proxy.md b/website/docs/sdks/unleash-proxy.md index 86f391fa414..0af9b0b195d 100644 --- a/website/docs/sdks/unleash-proxy.md +++ b/website/docs/sdks/unleash-proxy.md @@ -5,6 +5,10 @@ title: Unleash Proxy > The unleash-proxy is compatible with all Unleash Enterprise versions and Unleash Open-Source v4. You should reach out to **support@getunleash.io** if you want the Unleash Team to host the Unleash Proxy for you. +:::tip +Looking for how to run the Unleash proxy? Check out the [_How to run the Unleash Proxy_ guide](../how-to/how-to-run-the-unleash-proxy.mdx)! +::: + A lot of our users wanted to use feature toggles in their single-page and native applications. To solve this in a performant and privacy concerned way we built The Unleash Proxy The Unleash Proxy sits between the Unleash API and the application. It provides a simple and super-fast API, as it has all the data it needs available in memory. From f1a4347534bc179d5ba23f999452165a76aee035 Mon Sep 17 00:00:00 2001 From: Thomas Heartman Date: Wed, 13 Apr 2022 15:39:50 +0200 Subject: [PATCH 23/27] chore: delete duplicate configuration section --- website/docs/sdks/unleash-proxy.md | 22 ---------------------- 1 file changed, 22 deletions(-) diff --git a/website/docs/sdks/unleash-proxy.md b/website/docs/sdks/unleash-proxy.md index 0af9b0b195d..b60329a6fa4 100644 --- a/website/docs/sdks/unleash-proxy.md +++ b/website/docs/sdks/unleash-proxy.md @@ -255,26 +255,6 @@ However in some settings you would like a bit more logic around it to make it as The proxy is also ideal fit for serverless functions such as AWS Lambda. In that scenario the proxy can run on a small container near the serverless function, preferably in the same VPC, giving the lambda extremely fast access to feature flags, at a predictable cost. -## Configuration options - -Regardless of how you choose to run the it, the proxy will need access to these three variables: - -- **`unleashUrl`** / **`UNLEASH_URL`** - - The URL of your Unleash instance's API. For instance, to connect to the [Unleash demo app](https://app.unleash-hosted.com/demo/), you would use `https://app.unleash-hosted.com/demo/api/` - -- **`unleashApiToken`** / **`UNLEASH_API_TOKEN`** - - The API token to connect to your Unleash project. For more information on how these work and how to create them, check out the [API token documentation](../user_guide/token.md). - -- **`clientKeys`** / **`UNLEASH_PROXY_CLIENT_KEYS`** - - A list of client keys that the proxy will accept. For the proxy to accept an incoming request, the client must use one of these keys for authorization. In client SDKs, this is usually known as a `clientKey` or a `clientSecret`. If you query the proxy directly via HTTP, this is the `authorization` header. - - When using an environment variable to set the proxy secrets, the value should be a comma-separated list of strings, such as `secret-one,secret-two`. - -There are many more configuration options available. You'll find all [available options on github](https://github.com/Unleash/unleash-proxy#available-options). - ## Bootstrapping the Unleash Proxy {#bootstrap} ## Scaling the Unleash Proxy @@ -285,5 +265,3 @@ There are many more configuration options available. You'll find all [available { how to connect the proxy, what setups are possible etc. } See #bootstrap - -## Configuration options From 9db36013b1e9a535fd6d7e5700f98076f9d6e146 Mon Sep 17 00:00:00 2001 From: Thomas Heartman Date: Wed, 13 Apr 2022 15:41:02 +0200 Subject: [PATCH 24/27] chore: delete reference doc scaffolding --- website/docs/sdks/unleash-proxy.md | 11 ----------- 1 file changed, 11 deletions(-) diff --git a/website/docs/sdks/unleash-proxy.md b/website/docs/sdks/unleash-proxy.md index b60329a6fa4..018a0b56249 100644 --- a/website/docs/sdks/unleash-proxy.md +++ b/website/docs/sdks/unleash-proxy.md @@ -254,14 +254,3 @@ However in some settings you would like a bit more logic around it to make it as - [iOS Proxy SDK](/sdks/proxy-ios) The proxy is also ideal fit for serverless functions such as AWS Lambda. In that scenario the proxy can run on a small container near the serverless function, preferably in the same VPC, giving the lambda extremely fast access to feature flags, at a predictable cost. - -## Bootstrapping the Unleash Proxy {#bootstrap} - -## Scaling the Unleash Proxy - -## Hosting the Unleash Proxy - -## Proxy connection - -{ how to connect the proxy, what setups are possible etc. } -See #bootstrap From 4b8c3c3949fc9e2f71cde96dc50e791cc1020d61 Mon Sep 17 00:00:00 2001 From: Thomas Heartman Date: Tue, 19 Apr 2022 09:43:09 +0200 Subject: [PATCH 25/27] Apply suggestions from code review Co-authored-by: sighphyre --- website/docs/reference/api-tokens-and-client-keys.mdx | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/website/docs/reference/api-tokens-and-client-keys.mdx b/website/docs/reference/api-tokens-and-client-keys.mdx index eb9ff0032f6..0ef5a377bb4 100644 --- a/website/docs/reference/api-tokens-and-client-keys.mdx +++ b/website/docs/reference/api-tokens-and-client-keys.mdx @@ -14,15 +14,15 @@ Use API tokens to connect to the Unleash server API. API tokens come in two dist - [Admin tokens](#admin-tokens) - [Client tokens](#client-tokens) -Both types have use [the same format](#format) but have different intended uses. API tokens are considered to be *secrets* and should _not_ be exposed to end users. +Both types use [the same format](#format) but have different intended uses. API tokens are considered to be *secrets* and should _not_ be exposed to end users. ### Admin tokens **Admin tokens** grant *full read and write access* to all resources in the Unleash server API. Admin tokens have access to all projects, all environments, and all global resources (find out more about [resources in the RBAC document](../user_guide/rbac.md#core-principles)). Use admin tokens to: -- automate Unleash behavior such as creating feature toggles, projects, etc. -- write custom Unleash UIs to replace the default Unleash admin UI +- Automate Unleash behavior such as creating feature toggles, projects, etc. +- Write custom Unleash UIs to replace the default Unleash admin UI. Do **not** use admin tokens for: - [Client SDKs](../sdks/index.md): You will _not_ be able to read toggle data from multiple environments. Use [client tokens](#client-tokens) instead. @@ -72,7 +72,7 @@ The parts are separated by two different separators: A colon (`:`) between the p The **project(s)** part is one of: - The id of a specific project, for example: `default`. This indicates that the token is **only valid for this project**. -- A pair of opening and closing square brackets: `[]`. This indicates that the token is **valid for a discrete list of projects**. The list of projects is not shown in the token. +- A pair of opening and closing square brackets: `[]`. This indicates that the token is **valid for a discrete list of projects**. The list of projects is not shown in the token. - An asterisk: `*`. This indicates that the token is **valid for all projects (current and future)**. The **environment** is the name of an environment on your Unleash server, such as `development`. From 54bfe7323d54bd95a7f646df5861571a32c897cb Mon Sep 17 00:00:00 2001 From: Thomas Heartman Date: Tue, 19 Apr 2022 09:57:10 +0200 Subject: [PATCH 26/27] docs: update introduction --- website/docs/reference/api-tokens-and-client-keys.mdx | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/website/docs/reference/api-tokens-and-client-keys.mdx b/website/docs/reference/api-tokens-and-client-keys.mdx index 0ef5a377bb4..bca2042eded 100644 --- a/website/docs/reference/api-tokens-and-client-keys.mdx +++ b/website/docs/reference/api-tokens-and-client-keys.mdx @@ -2,7 +2,13 @@ title: API tokens and client keys --- -Unleash has a number of tokens/keys that all have slightly different use cases. Here's the list of all of them: +For Unleash to be of any use, it requires at least a server and a [consuming client](../sdks/index.md). +More advanced use cases may call for multiple clients, automated feature toggle updates, the [Unleash proxy](../sdks/unleash-proxy.md) and [Unleash proxy clients](../sdks/index.md#front-end-sdks), and more. To facilitate communication between all these moving parts, Unleash uses a system of API tokens and client keys, all with a specific purpose in mind. + +This document details the three kinds of tokens and keys that you will need to fully connect any Unleash system: +- [Admin tokens](#admin-tokens) for updating resources in Unleash +- [Client tokens](#client-tokens) for connecting server-side client SDKs and the Unleash proxy to the Unleash server +- [Proxy client keys](#proxy-client-keys) for connecting proxy client SDKs to the Unleash proxy. ## API tokens From 9d2ef0c47fca0d663257cbf6d8147d504a65bcb6 Mon Sep 17 00:00:00 2001 From: Thomas Heartman Date: Tue, 19 Apr 2022 11:08:02 +0200 Subject: [PATCH 27/27] docs: add note about client tokens changing with v 4.10 --- website/docs/reference/api-tokens-and-client-keys.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/docs/reference/api-tokens-and-client-keys.mdx b/website/docs/reference/api-tokens-and-client-keys.mdx index bca2042eded..7da7559cd1f 100644 --- a/website/docs/reference/api-tokens-and-client-keys.mdx +++ b/website/docs/reference/api-tokens-and-client-keys.mdx @@ -42,7 +42,7 @@ Support for scoped admin tokens with more fine-grained permissions is currently - Register applications with the Unleash server - Send usage metrics -When creating a client token, you can choose which projects it should be able to read data from. You can give it access to a specific list of projects or to all projects (including projects that don't exist yet). +When creating a client token, you can choose which projects it should be able to read data from. You can give it access to a specific list of projects or to all projects (including projects that don't exist yet). Prior to Unleash 4.10, a token could be valid only for a *single project* or *all projects*. Each client token is only **valid for a single environment**.