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: