docs: add proxy deployment diagrams (#1743)

* docs: remove empty table row

* docs: add placeholder proxy hosting article

* docs: add images, describe first one

* docs: describe the customer-hosted proxy solution

* docs: describe the self-hosted single-region setup.

* docs: describe enterprise multi-region setup.

* docs: minor changes

* docs: update lists; restructure

* docs: more minor changes

* docs: add alt text to diagrams

* docs: update proxy hosting doc

* docs: some prettier formatting

* docs: add link to proxy hosting doc

* docs: format proxy config table

* docs: prettier formatting

website/docs/sdks/unleash-proxy.md

@@ -6,7 +6,9 @@ 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
@@ -26,23 +28,25 @@ _The Unleash Proxy uses the Unleash SDK and exposes a simple API_. The Proxy wil
 ## Configuration
 
 :::info
+
 You **must configure** these three variables for the proxy to start successfully:
+
 - `unleashUrl` / `UNLEASH_URL`
 
 - `unleashApiToken` / `UNLEASH_API_TOKEN`
 
 - `clientKeys` / `UNLEASH_PROXY_CLIENT_KEYS`
+
 :::
 
 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. |
-| `enableOAS`            | `ENABLE_OAS`                     | `false`         | no       | Set to `true` to expose the proxy's OpenAPI spec at `/docs/openapi.json` and an interactive Swagger interface at `/docs/openapi`. Read more in the [OpenAPI section](#openapi).|
+| `enableOAS` | `ENABLE_OAS` | `false` | no | Set to `true` to expose the proxy's OpenAPI spec at `/docs/openapi.json` and an interactive Swagger interface at `/docs/openapi`. Read more in the [OpenAPI section](#openapi). |
 | `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. |
@@ -60,6 +64,15 @@ The Proxy has a large number of configuration options that you can use to adjust
 | `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. |
 
+## Privacy and hosting options {#privacy-and-hosting}
+
+<div id="we-care-about-privacy"></div>
+
+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. 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.)
+
+For more information on the various hosting options and their tradeoffs, refer to the [proxy hosting strategies topic document](../topics/proxy-hosting.mdx).
 
 ## Health endpoint
 
@@ -81,12 +94,12 @@ 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.
 
@@ -98,7 +111,7 @@ Each strategy file must export a list of instantiated strategies. A file can exp
 
 Here's an example file that exports two custom strategies:
 
-``` js
+```js
 const { Strategy } = require('unleash-client');
 
 class MyCustomStrategy extends Strategy {
@@ -110,10 +123,7 @@ class MyOtherCustomStrategy extends Strategy {
 }
 
 // export strategies
-module.exports = [
-    new MyCustomStrategy(),
-    new MyOtherCustomStrategy()
-];
+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.
@@ -126,8 +136,10 @@ The Unleash Proxy has a very simple API. It takes the [Unleash Context](../user_
 
 ### OpenAPI integration and API documentation {#openapi}
 
-:::info Availability
-The OpenAPI integration is available in versions 0.9 and later of the Unleash proxy.
+:::info
+
+Availability The OpenAPI integration is available in versions 0.9 and later of the Unleash proxy.
+
 :::
 
 The proxy can optionally expose a runtime-generated OpenAPI JSON spec and a corresponding OpenAPI UI for its API. The OpenAPI UI page is an interactive page where you can discover and test the API endpoints the proxy exposes. The JSON spec can be used to generate an OpenAPI client with OpenAPI tooling such as the [OpenAPI generator](https://openapi-generator.tech/).
@@ -140,7 +152,6 @@ The spec and UI can then be found at `<base url>/docs/openapi.json` and `<base u
 
 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": [
@@ -168,7 +179,7 @@ The `proxy` endpoint returns information about toggles enabled for the current u
 
 The data for a toggle without [variants](../advanced/feature-toggle-variants.md) looks like this:
 
-``` json
+```json
 {
   "name": "basic-toggle",
   "enabled": true,
@@ -183,16 +194,17 @@ The data for a toggle without [variants](../advanced/feature-toggle-variants.md)
 - **`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`.
-:::
+:::note The "disabled" variant
 
+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
+```json
 {
   "name": "toggle-with-variants",
   "enabled": true,
@@ -201,12 +213,11 @@ Variant toggles without payloads look will have their name listed and the `enabl
     "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
+```json
 {
   "name": "toggle-with-variants",
   "enabled": true,
@@ -222,17 +233,19 @@ If the variant has a payload, the optional `payload` property will list the payl
 ```
 
 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
+```json
 {
   "name": "toggle-with-variants",
   "enabled": true,
@@ -247,14 +260,6 @@ The `value` will always be the payload's content as a string, escaped as necessa
 }
 ```
 
-## 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.

website/docs/topics/proxy-hosting.mdx

@@ -0,0 +1,110 @@
+---
+title: Proxy hosting strategies
+---
+
+Because the [Unleash proxy](../sdks/unleash-proxy.md) is a separate piece of the Unleash architecture and because it should sit close to your application, there are numerous ways of hosting it. Another important distinction is whether you're hosting Unleash yourself or you have a managed solution.
+
+This document describes the three main ways of hosting the proxy alongside the Unleash API and the tradeoffs between hosting the proxy yourself and having Unleash host it for you.
+
+## Unleash-hosted proxy vs self-hosted proxy {#unleash-hosted-or-self-hosted}
+
+Which way is right for you will depend on your setup and your needs. In general, we recommend that you host the proxy yourself, but we do recognize that self-hosting requires some extra work on your part and that not all our customers need it.
+
+If you want Unleash to host the proxy for you, you should be aware of the following limitations:
+
+-   This is only available to Pro and Enterprise customers who have signed up for a managed Unleash instance.
+-   You'll get a total of two (2) proxies: One for the "development" environment and one for the "production" environment.
+-   The proxies _will not_ scale, regardless of how many requests you're getting.
+-   If you go above an average of 10 requests per second, then you'll be charged extra. (Is this pricing available anywhere?)
+-   There's no guarantee that it'll be close to your applications. This means you'll get higher response times.
+-   When we host the proxy, we will also receive whatever end user data you put in the [Unleash context](../user_guide/unleash-context.md). This may or may not be an issue depending on your business requirements.
+
+Hosting the proxy yourself requires a little more setup on your part than the Unleash-hosted proxy does, but it offers a number of benefits:
+
+-   You can scale the proxy horizontally and automatically.
+-   There's no request cap or extra charges.
+-   You can host as many proxies as you want for as many different environments as you want.
+-   You can arrange for the proxy to be close to your applications, minimizing response times.
+-   You have full control of all your user data. None of the data that the proxy receives is ever sent to the Unleash API. This keeps _your_ data in _your_ hands.
+-   You can easily add more proxies in different regions, as described in the [multi-region](#multi-region) section.
+
+## Unleash hosts everything
+
+:::info Availability
+
+This setup is only available to Pro and Enterprise customers.
+
+:::
+
+![An architecture diagram of using the proxy in a setup where Unleash hosts both the API and the proxy.](/img/proxy-hosting-all-unleash.svg)
+
+When Unleash hosts the proxy, it'll run alongside the Unleash API and the admin UI within Unleash's Kubernetes setup in AWS. The API is backed by an Amazon RDS database. Your applications can connect to the proxy from your own cloud or other hosting solution. You'll need to configure your proxy SDKs with the following details:
+
+-   One of the [proxy's client keys](../reference/api-tokens-and-client-keys.mdx#proxy-client-keys). Unleash will provide you with the actual keys.
+-   The proxy's endpoint. This will be the your Unleash instance's URL followed by "/api/proxy/development" or "/api/proxy/production" (depending on which environment you want to use).
+
+This is the simplest, but also most limited (by far) way to host the proxy. In this setup, Unleash hosts both the Unleash API and the Unleash proxy. With Unleash hosting the proxy, you'll only need to worry about the client keys and the URL the proxy is hosted at.
+
+While this is easy to get started with, it comes with the limitations described in the [section on tradeoffs between self-hosted and Unleash-hosted setups](#unleash-hosted-or-self-hosted).
+
+## Unleash hosts the API, you host the proxy
+
+:::info Availability
+
+This setup is only available to Pro and Enterprise customers.
+
+:::
+
+![An architecture diagram of using the proxy in a setup where Unleash hosts the API and you host the proxy.](/img/proxy-hosting-unleash-api-customer-proxy.svg)
+
+You host the proxy yourself. It runs in a standalone container alongside your other applications in your cloud or hosting setup. Unleash manages the Unleash API, the admin UI, and the backing database in our AWS setup: the API and the UI run together in a Kubernetes deployment and connect to an Amazon RDS database.
+
+You'll need to configure the proxy and the proxy client SDKs.
+
+For the proxy, configure:
+
+-   The Unleash API url. This is your Unleash instance URL followed by "/api".
+-   A [client API token](../reference/api-tokens-and-client-keys.mdx#client-tokens). (Refer to [how to create API tokens](../user_guide/token.md) for the steps to create one.)
+-   One or more [proxy client keys](../reference/api-tokens-and-client-keys.mdx#proxy-client-keys). Refer to the [configuration section of the proxy document](../sdks/unleash-proxy#configuration) for more details.
+
+For the proxy client SDK, configure:
+
+-   One of the proxy client keys that you configured for the proxy.
+-   The proxy's endpoint. This will depend on where and how you're hosting the proxy, but will typically end in "/proxy"
+
+This setup requires a little more setup on your part than the Unleash-hosted proxy does, but it offers all the benefits described in the [section on tradeoffs between self-hosted and Unleash-hosted setups](#unleash-hosted-or-self-hosted).
+
+## You host everything
+
+:::info Availability
+
+This setup is only available open-source and Enterprise customers.
+
+:::
+
+![An architecture diagram of using the proxy in a single-region, self-hosted setup.](/img/proxy-hosting-customer-single.svg)
+
+You host everything yourself. Everything runs where and how you configure it to.
+
+You'll need to configure the proxy and the proxy client SDKs.
+
+For the proxy, configure:
+
+-   The Unleash API url. This is your Unleash instance URL followed by "/api".
+-   A [client API token](../reference/api-tokens-and-client-keys.mdx#client-tokens). (Refer to [how to create API tokens](../user_guide/token.md) for the steps to create one.)
+-   One or more [proxy client keys](../reference/api-tokens-and-client-keys.mdx#proxy-client-keys). Refer to the [configuration section of the proxy document](../sdks/unleash-proxy#configuration) for more details.
+
+For the proxy client SDK, configure:
+
+-   One of the proxy client keys that you configured for the proxy.
+-   The proxy's endpoint. This will depend on where and how you're hosting the proxy, but will typically end in "/proxy"
+
+As you might expect, doing everything yourself _is_ going to give you the most flexibility, but it's also going to be the most work. If you're already hosting Unleash yourself, though, this shouldn't be any more difficult than the previous section.
+
+As described in the [section on tradeoffs between self-hosted and Unleash-hosted setups](#unleash-hosted-or-self-hosted), running the proxy yourself gives you a number of benefits.
+
+## Multi-region
+
+![An architecture diagram of using the proxy in a multi-region, self-hosted setup.](/img/proxy-hosting-customer-multi.svg)
+
+You can also use the proxy for a multi-region setup. You can run a proxy in a different region to the API and still connect to the API. Because the proxy runs closer to your applications it still provides you benefits in terms of quicker response times. Everything should be configured as described in the [you host everything section](#you-host-everything) or the [Unleash hosts the API, you host the proxy section](#unleash-hosts-the-api-you-host-the-proxy). You can add as many extra proxies in as many extra regions as you want.

website/sidebars.js

@@ -294,7 +294,7 @@ module.exports = {
                     'Discussions, explanations, and explorations regarding topics related to Unleash.',
                 slug: '/topics',
             },
-            items: ['topics/a-b-testing'],
+            items: ['topics/a-b-testing', 'topics/proxy-hosting'],
         },
     ],
 };