diff --git a/website/docs/how-to/how-to-add-strategy-constraints.md b/website/docs/how-to/how-to-add-strategy-constraints.md index 4ed2cf5150..3a50a0172a 100644 --- a/website/docs/how-to/how-to-add-strategy-constraints.md +++ b/website/docs/how-to/how-to-add-strategy-constraints.md @@ -8,7 +8,7 @@ Before Unleash 4.16, strategy constraints were only available to Unleash Pro and ::: -This guide shows you how to add [strategy constraints](../reference/strategy-constraints.md) to your feature flags via the admin UI. For information on how to interact with strategy constraints from an [Unleash client SDK](../reference/sdks/index.md), visit the specific SDKs documentation or see [the relevant section in the strategy constraints documentation](../reference/strategy-constraints.md#sdks 'strategy constraints documentation, section on interacting with constraints from client SDKs'). +This guide shows you how to add [strategy constraints](../reference/strategy-constraints.md) to your feature flags using the Admin UI. For information on how to interact with strategy constraints from an [Unleash client SDK](../reference/sdks/index.md), visit the specific SDK's documentation or see [the relevant section in the strategy constraints documentation](../reference/strategy-constraints.md#sdks 'strategy constraints documentation, section on interacting with constraints from client SDKs'). ## Prerequisites diff --git a/website/docs/how-to/how-to-create-api-tokens.mdx b/website/docs/how-to/how-to-create-api-tokens.mdx index a31699bcbb..fc44549f49 100644 --- a/website/docs/how-to/how-to-create-api-tokens.mdx +++ b/website/docs/how-to/how-to-create-api-tokens.mdx @@ -12,7 +12,7 @@ All users can see tokens with `CLIENT` level access, but only instance admins ca ::: -Unleash SDKs use API tokens to authenticate to the Unleash API. Unleash supports different types of API tokens, each with different levels of access and privileges. Refer to the [API tokens and client keys](../reference/api-tokens-and-client-keys.mdx) article for complete overview of the different token types. +Unleash SDKs use API tokens to authenticate to the Unleash API. Unleash supports different types of API tokens, each with different levels of access and privileges. Refer to the [API tokens and client keys documentation](../reference/api-tokens-and-client-keys.mdx) for a complete overview of the different token types. ## Step 1: Navigate to the API token creation form {#step-1} diff --git a/website/docs/how-to/how-to-create-project-api-tokens.mdx b/website/docs/how-to/how-to-create-project-api-tokens.mdx index 84acd5a24c..11f16f7fb5 100644 --- a/website/docs/how-to/how-to-create-project-api-tokens.mdx +++ b/website/docs/how-to/how-to-create-project-api-tokens.mdx @@ -8,7 +8,7 @@ Creating Project API tokens requires you to have the `CREATE_PROJECT_API_TOKEN` ::: -Unleash SDKs use API tokens to authenticate to the Unleash API. Unleash supports different types of API tokens, each with different levels of access and privileges. Refer to the [API tokens and client keys](../reference/api-tokens-and-client-keys.mdx) article for complete overview of the different token types. +Unleash SDKs use API tokens to authenticate to the Unleash API. Unleash supports different types of API tokens, each with different levels of access and privileges. Refer to the [API tokens and client keys documentation](../reference/api-tokens-and-client-keys.mdx) for a complete overview of the different token types. ## Step 1: Navigate to the API token creation form {#step-1} diff --git a/website/docs/how-to/how-to-create-service-accounts.mdx b/website/docs/how-to/how-to-create-service-accounts.mdx index 303678366c..c8a2dbedea 100644 --- a/website/docs/how-to/how-to-create-service-accounts.mdx +++ b/website/docs/how-to/how-to-create-service-accounts.mdx @@ -8,7 +8,7 @@ Service accounts is an enterprise feature available from Unleash 4.21 onwards. ::: -[Service accounts](../reference/service-accounts.md) enable Unleash admins to create accounts that act as users and respect the same set of permissions, however they do not have a password and cannot log in to the Unleash UI. Instead, they are intended to be used to access the Unleash API programatically. +[Service accounts](../reference/service-accounts.md) enable Unleash admins to create accounts that act as users and adhere to the same set of permissions. However, these accounts do not have a password and cannot log in to the Unleash Admin UI. Instead, they are intended to be used to access the Unleash API programmatically. ## Step 1: Navigate to the service accounts page {#step-1} @@ -30,7 +30,7 @@ Select a [root role](https://docs.getunleash.io/reference/rbac#predefined-roles) ![The service account form filled with some example data, and the "add service account" button highlighted at the bottom.](/img/service-account-3.png) -You can optionally generate a token for the new service account right away. Give your token a description and optionally set an expiry date. By default the expiry date is set to 30 days. The token will be generated when you submit the form. +You can optionally generate a token for the new service account right away. Give your token a description and optionally set an expiry date. By default, the expiry date is set to 30 days. The token will be generated when you submit the form. ![The service account form with the token section highlighted and the "generate a token now" option selected](/img/service-account-4.png) diff --git a/website/docs/how-to/how-to-enable-openapi.mdx b/website/docs/how-to/how-to-enable-openapi.mdx index 7a6851aab8..45fd8d0136 100644 --- a/website/docs/how-to/how-to-enable-openapi.mdx +++ b/website/docs/how-to/how-to-enable-openapi.mdx @@ -13,7 +13,7 @@ Since v5.2.0 Unleash has OpenAPI enabled by default. ::: -Both Unleash and the Unleash proxy have included OpenAPI schemas and Swagger UIs for their APIs. The schemas can be used to get an overview over all API operations and to generate API clients using OpenAPI client generators. The Swagger UI lets you see and try out all the available API operations directly in your browser. +Both Unleash and the Unleash proxy have included OpenAPI schemas and Swagger UIs for their APIs. The schemas can be used to get an overview of all API operations and to generate API clients using OpenAPI client generators. The Swagger UI lets you see and try out all the available API operations directly in your browser. To enable the OpenAPI documentation and the Swagger UI, you must start Unleash or the proxy with the correct configuration option. The following section shows you how. The methods are the same for both Unleash and the Unleash proxy, so the steps described in the next section will work for either. @@ -79,7 +79,7 @@ docker run \ The configuration option for enabling OpenAPI and the swagger UI is `enableOAS`. Set this option to `true`. -The following examples have been shortened to show the only the relevant configuration options. For more detailed instructions on how to run Unleash or the proxy, refer to [how to run the Unleash proxy](how-to-run-the-unleash-proxy.mdx) or the [section on running Unleash via Node.js from the deployment section](/using-unleash/deploy/getting-started.md#option-three---from-nodejs) of the documentation. +The following examples have been shortened to show only the relevant configuration options. For more detailed instructions on how to run Unleash or the proxy, refer to [how to run the Unleash proxy](how-to-run-the-unleash-proxy.mdx) or the [section on running Unleash via Node.js from the deployment section](/using-unleash/deploy/getting-started.md#option-three---from-nodejs) of the documentation. @@ -90,7 +90,7 @@ const unleash = require('unleash-server'); unleash .start({ - // ... Other options elided for brevity + // ... Other options emitted for brevity // highlight-next-line enableOAS: true, }) diff --git a/website/docs/how-to/how-to-use-the-admin-api.md b/website/docs/how-to/how-to-use-the-admin-api.md index 6302e149e6..41da452914 100644 --- a/website/docs/how-to/how-to-use-the-admin-api.md +++ b/website/docs/how-to/how-to-use-the-admin-api.md @@ -2,7 +2,7 @@ title: How to use the Admin API --- -It is possible to integrate directly with the Admin API. In this guide we will explain all the steps to set it up. +This guide explains the steps required to getting access to and using the Admin API. ## Step 1: Create API token {#step-1-create-api-token} diff --git a/website/docs/quickstart.md b/website/docs/quickstart.md index 75657a9458..206c15a59c 100644 --- a/website/docs/quickstart.md +++ b/website/docs/quickstart.md @@ -6,7 +6,7 @@ There are lots of options to get started with Unleash. If you're comfortable wit ## 1. Set up Unleash with Docker {#setup-unleash-docker} -The easiest way to run unleash locally is using git and [docker](https://www.docker.com/). +The easiest way to run Unleash locally is using Git and [Docker](https://www.docker.com/). ```sh git clone git@github.com:Unleash/unleash.git @@ -87,7 +87,7 @@ unleash.on("synchronized", () => { ### Unleash Demo Instance {#unleash-demo-instance} -For testing purposes we have set up a demo instance that you can use in order to test out different use-cases before setting up your own instance. You can find the demo instance here: https://app.unleash-hosted.com/demo/ +For testing purposes, we have set up a demo instance that you can use to test out different use cases before setting up your own instance. You can find the demo instance here: https://app.unleash-hosted.com/demo/ NOTE: This is a demo instance set up with the Pro version. [More information on our different versions](https://www.getunleash.io/pricing). diff --git a/website/docs/reference/api-tokens-and-client-keys.mdx b/website/docs/reference/api-tokens-and-client-keys.mdx index e9fc5a4940..3b438c2a92 100644 --- a/website/docs/reference/api-tokens-and-client-keys.mdx +++ b/website/docs/reference/api-tokens-and-client-keys.mdx @@ -128,7 +128,7 @@ Do **not** use client tokens in: **Front-end tokens** are used with [front-end SDKs](../reference/sdks/index.md#front-end-sdks) when used with the [Unleash front-end API](./front-end-api.md). They grant the user permission to: -- Read the enabled flagd for a given context +- Read the enabled flags for a given context - Register applications with the Unleash server - Send usage metrics diff --git a/website/docs/reference/sdks/index.md b/website/docs/reference/sdks/index.md index f66e8f821a..47ae1522fc 100644 --- a/website/docs/reference/sdks/index.md +++ b/website/docs/reference/sdks/index.md @@ -4,9 +4,9 @@ title: SDK overview import VideoContent from '@site/src/components/VideoContent.jsx' -In order to connect your application to Unleash you will need a client SDK (software developer kit) for your programming language and an [API token](../how-to/how-to-create-api-tokens). The SDK will handle connecting to the Unleash server instance and retrieving feature flags based on your configuration. All versions of Unleash (OSS, Pro, and Enterprise) use the same client SDKs. +To connect your application to Unleash you need a [client SDK](#official-sdks) for your programming language and an [API token](../how-to/how-to-create-api-tokens). The SDK handles connecting to the Unleash server instance and retrieving feature flags based on your configuration. All versions of Unleash (OSS, Pro, and Enterprise) use the same client SDKs. -Unleash provides official client SDKs for a number of programming language. Additionally, our community have developed and contributed SDKs for other languages. So if you can't find your favorite language in the list of official SDKs, check out the [list of clients written by our fantastic community](#community-sdks). +Unleash provides official client SDKs for a number of programming languages. Additionally, our community has developed and contributed SDKs for other languages. So if you can't find your favorite language in the list of official SDKs, check out the [list of clients written by our fantastic community](#community-sdks). ## Official SDKs @@ -32,7 +32,8 @@ Client-side SDKs can connect to [Unleash Edge](/reference/unleash-edge) or to th - [Android SDK](/docs/generated/sdks/client-side/android-proxy.md) - [Flutter Proxy SDK](/docs/generated/sdks/client-side/flutter.md) - [iOS Proxy SDK](/docs/generated/sdks/client-side/ios-proxy.md) -- [Javascript SDK](/docs/generated/sdks/client-side/javascript-browser.md) +- [JavaScript SDK](/docs/generated/sdks/client-side/javascript-browser.md) +- [Next.js](/docs/generated/sdks/client-side/next-js.md) - [React Proxy SDK](/docs/generated/sdks/client-side/react.md) - [Svelte Proxy SDK](/docs/generated/sdks/client-side/svelte.md) - [Vue Proxy SDK](/docs/generated/sdks/client-side/vue.md) @@ -83,7 +84,7 @@ If you see an item marked with a ❌ that you would find useful, feel free to re | Basic support | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | | **Category: [Strategy constraints](../strategy-constraints.md)** | | | | | | | | | | Basic support (`IN`, `NOT_IN` operators) | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | -| Advanced support (Semver, date, numeric and extended string operators) (introduced in) | ✅ (5.1) | ✅ (3.12) | ✅ (3.3) | ✅ (5.1) | ✅ (4.2) | ✅ (2.1) | ✅ (1.3.1) | ⭕ | +| Advanced support (Semver, date, numeric, and extended string operators) (introduced in) | ✅ (5.1) | ✅ (3.12) | ✅ (3.3) | ✅ (5.1) | ✅ (4.2) | ✅ (2.1) | ✅ (1.3.1) | ⭕ | | **Category: [Unleash Context](../reference/unleash-context)** | | | | | | | | | | Static fields (`environment`, `appName`) | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | | Defined fields | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | @@ -99,7 +100,7 @@ If you see an item marked with a ❌ that you would find useful, feel free to re | [Custom stickiness](../stickiness.md#custom-stickiness-beta) | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ⭕ | | [Strategy Variants](./strategy-variants)| ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ⭕ | | **Category: Local backup** | | | | | | | | | -| File based backup | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ⭕ | +| File-based backup | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ⭕ | | **Category: Usage metrics** | | | | | | | | | | Can disable metrics | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | | Client registration | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | @@ -134,7 +135,7 @@ Here's some of the fantastic work our community has done to make Unleash work in ### Implement your own SDK {#implement-your-own-sdk} -If you can't find an SDK that fits your need, you can also develop your own SDK. To make implementation easier, check out these resources: +If you can't find an SDK that fits your requirements, you can also develop your own SDK. To make implementation easier, check out these resources: - [Unleash Client Specifications](https://github.com/Unleash/client-specification) - Used by all official SDKs to make sure they behave correctly across different language implementations. This lets us verify that a gradual rollout to 10% of the users would affect the same users regardless of which SDK you're using. - [Client SDK overview](../client-specification) - A brief, overall guide of the _Unleash Architecture_ and important aspects of the SDK role in it all. @@ -143,7 +144,7 @@ If you can't find an SDK that fits your need, you can also develop your own SDK. The following section details the behavior of frontend / client-side SDKs when initializing and fetching flags with respect to network connectivity. -When the SDK is initialized in the application, an in memory repository is setup and synchronized against the frontend API using the configured token and context. Note that the frontend API is hosted by either the Unleash Proxy/Edge or the upstream Unleash instance directly. +When the SDK is initialized in the application, an in-memory repository is set up and synchronized against the frontend API using the configured token and context. Note that the frontend API is hosted by either the Unleash Proxy/Edge or the upstream Unleash instance directly. 1. All feature flag evaluation is performed by the Proxy/Edge or Unleash instance. A payload of all enabled flags and their variants (if applicable) is returned as a single request. Disabled flags are not included. @@ -165,7 +166,7 @@ By default, all SDKs reach out to the Unleash Server at startup to fetch their f Bootstrapping is also supported by the following front-end client SDKs: - [Android SDK](/docs/generated/sdks/client-side/android-proxy.md) -- [Javascript SDK](/docs/generated/sdks/client-side/javascript-browser.md) +- [JavaScript SDK](/docs/generated/sdks/client-side/javascript-browser.md) - [React Proxy SDK](/docs/generated/sdks/client-side/react.md) - [Svelte Proxy SDK](/docs/generated/sdks/client-side/svelte.md) - [Vue Proxy SDK](/docs/generated/sdks/client-side/vue.md) diff --git a/website/docs/understanding-unleash/data-collection.md b/website/docs/understanding-unleash/data-collection.md index 1b432f2abd..0efef58ea3 100644 --- a/website/docs/understanding-unleash/data-collection.md +++ b/website/docs/understanding-unleash/data-collection.md @@ -1,13 +1,9 @@ --- title: Data collection --- -:::info - At Unleash, we prioritize the privacy and security of our users' data. This document provides an overview of the data collected when running Unleash. We explain the purpose of data collection and provide instructions on managing data collection settings. -::: - -## What data is collected {#what-data-is-collected} +## What data is collected When running Unleash, we collect the following data: **Version and Instance ID**: A unique identifier and version for your Unleash instance. This ID allows us to track usage statistics and measure the adoption of Unleash across different installations and helps us ensure that you're using the latest version with the most up-to-date features and security enhancements. @@ -26,16 +22,20 @@ This includes the following data points: - The number of custom strategies defined and in use - The number of feature exports/imports made -Please note that all collected data is anonymous, and we only collect usage counts. This data helps us understand how features are used in Unleash, enabling us to prioritize important features and make informed decisions about deprecating features that are no longer relevant to our users. +All collected data is anonymous, and we only collect usage counts. This data helps us understand how features are used in Unleash, enabling us to prioritize important features and make informed decisions about deprecating features that are no longer relevant to our users. -Please note that we do not collect personally identifiable information (PII) through Unleash. +:::info -## Managing data collection settings {#managing-data-collection-settings} +Unleash does not collect personally identifiable information (PII). + +::: + +## Managing data collection settings We understand that privacy preferences may vary among our users. While the data collected by Unleash is limited and anonymous, we provide options to manage data collection settings: -**Disabling All Telemetry**: If you have previously disabled the version telemetry by setting the environment variable `CHECK_VERSION` to anything other than "true", "t" or "1" both the version telemetry and the feature telemetry will be disabled. This respects your choice to opt out of all telemetry data if you had previously disabled it. +**Disabling All Telemetry**: If you have previously disabled the version telemetry by setting the environment variable `CHECK_VERSION` to anything other than `true`, `t`, or `1`, then both the version telemetry and the feature telemetry will be disabled. This respects your choice to opt out of all telemetry data if you had previously disabled it. -**Turning Off Feature Telemetry**: To disable the collection of the new telemetry data while still allowing the version telemetry, set the environment variable `SEND_TELEMETRY` to anything other than "true", "t" or "1" before starting Unleash. This will ensure that the new telemetry data is not sent, but the version information is still sent. +**Turning Off Feature Telemetry**: To disable the collection of the new telemetry data while still allowing the version telemetry, set the environment variable `SEND_TELEMETRY` to anything other than `true`, `t`, or `1` before starting Unleash. This will ensure that the new telemetry data is not sent, but the version information is still sent. We respect your privacy choices, and we will continue to honor your decision regarding telemetry. If you have any questions or concerns about managing data collection settings or privacy, please reach out to our support team for assistance. diff --git a/website/docs/understanding-unleash/managing-constraints.mdx b/website/docs/understanding-unleash/managing-constraints.mdx index 6cb91578bb..f1a97a2dd4 100644 --- a/website/docs/understanding-unleash/managing-constraints.mdx +++ b/website/docs/understanding-unleash/managing-constraints.mdx @@ -8,7 +8,7 @@ In this explanatory guide, we will discuss how best to deal with large and compl ::: -Unleash offers several ways to limit feature exposure to a specified audience, such as the [User IDs strategy](../reference/activation-strategies.md#userids), [strategy constraints](../reference/strategy-constraints.md), and [segments](../reference/segments.mdx). Each of these options make it easy to add some sort of user identifier to the list of users who should get access to a feature. +Unleash offers several ways to limit feature exposure to a specified audience, such as the [User IDs strategy](../reference/activation-strategies.md#userids), [strategy constraints](../reference/strategy-constraints.md), and [segments](../reference/segments.mdx). Each of these options makes it easy to add some sort of user identifier to the list of users who should get access to a feature. Because of their availability and ease of use with smaller lists, it can be tempting to just keep adding identifiers to those lists. However, once you start approaching a hundred elements, we recommend that you find another way to manage these IDs. In fact, it's probably better to stop well before you get that far. @@ -22,9 +22,9 @@ First, let's talk a bit about Unleash's architecture: **Your Unleash instance** For the SDKs (Edge/proxy included) to evaluate a feature, it needs to know everything about that feature in a specific environment. This includes all strategies and their constraints. This means that the Unleash instance must transmit all information about this feature (and all other features) as a response to an API call. -As the number of elements in a constraint list (such as number of unique user IDs) grows, so does the size of the HTTP response from the Unleash instance. More data to transmit, means more bandwidth used and longer response times. More data to parse (on the SDK side) means more time spent processing and more data to store and look up on the client. +As the number of elements in a constraint list (such as the number of unique user IDs) grows, so does the size of the HTTP response from the Unleash instance. More data to transmit means more bandwidth used and longer response times. More data to parse (on the SDK side) means more time spent processing and more data to store and look up on the client. -To fetch feature configuration, Unleash SDKs run a polling loop in the background. With normal-sized configurations this isn't an issue, but as you add more and more complex constraints, this can eventually overload your network and slow down your SDK. And the more SDKs that connect to your Unleash instance, the worse the problem gets. +To fetch feature configuration, Unleash SDKs run a polling loop in the background. While this works well with normal-sized configurations, as you add more complex constraints, it can eventually overload your network and slow down your SDK. Additionally, as the number of SDKs connecting to your Unleash instance increases, the problem can become more pronounced, potentially impacting performance. In other words: it's not good. @@ -32,7 +32,7 @@ In other words: it's not good. Okay, so putting all these IDs in Unleash isn't good. But how **do** you manage features for these 124 special cases you have? -The first thing to think about would be whether you can group these special cases in some way. Maybe you already have an [Unleash context](../reference/unleash-context.md) field that covers the same amount of users. In that case, you can constrain on that instead. If you don't have a context field that matches these users, then you might need to create one. +The first thing to think about would be whether you can group these special cases in some way. Maybe you already have an [Unleash context](../reference/unleash-context.md) field that covers the same amount of users. In that case, you can constrain that instead. If you don't have a context field that matches these users, then you might need to create one. Further, if you have a lot of special cases and require complex constraint logic to model it correctly, this probably reflects some logic that is specific to your domain. It's also likely that this same logic is used elsewhere in your system external to Unleash. Modeling this logic in multiple places can quickly lead to breakage, and we recommend having a single source of truth for cases like this. diff --git a/website/docs/understanding-unleash/proxy-hosting.mdx b/website/docs/understanding-unleash/proxy-hosting.mdx index d7a71c850e..6dc29c008f 100644 --- a/website/docs/understanding-unleash/proxy-hosting.mdx +++ b/website/docs/understanding-unleash/proxy-hosting.mdx @@ -1,5 +1,5 @@ --- -title: Edge & Proxy hosting strategies +title: Edge and Proxy hosting strategies --- import VideoContent from '@site/src/components/VideoContent.jsx' @@ -27,13 +27,13 @@ If you want Unleash to host the Frontend API for you, you should be aware of the - We allow short spikes in traffic and our adaptive infrastructure will automatically scale to your needs. - Please check the [Fair Use Policy](https://www.getunleash.io/fair-use-policy) to see the limits of the Unleash-hosted Frontend API. - There's no guarantee that it'll be geographically close to your end users, this means your end users might be getting slower response times on feature flag evaluations. -- When we host the frontend API, we will also receive whatever end user data you put in the [Unleash context](../reference/unleash-context.md). This may or may not be an issue depending on your business requirements. +- When we host the frontend API, we will also receive whatever end-user data you put in the [Unleash context](../reference/unleash-context.md). This may or may not be an issue depending on your business requirements. -Hosting Edge requires a little more setup the Unleash-hosted Frontend API does, but it offers a number of benefits over both the frontend API and Proxy: +Hosting Edge requires a little more setup than the Unleash-hosted Frontend API does, but it offers a number of benefits over both the frontend API and Proxy: - You can scale Edge instances horizontally and automatically. - There's no request cap or extra charges. -- Edge can handle multiple sets of API tokens and sync these automatically. Compared to the legacy proxy, it is not necessary to setup single instances per token. +- Edge can handle multiple sets of API tokens and sync these automatically. Compared to the legacy proxy, it is not necessary to set up single instances per token. - A key benefit of Edge is its ability to dynamically update new tokens while running. This greatly simplifies scaling up additional application workloads that leverage new tokens without the need to restart the instance or make large changes to infra, as was the prior requirement with the proxy. - You can arrange for Edge to be close to your applications, minimizing response times. - You have full control of all your user data. None of the data that Edge receives is ever sent to the Unleash API. This keeps _your_ data in _your_ hands. @@ -52,9 +52,9 @@ This setup is only available to Pro and Enterprise customers. Unleash no longer hosts instances of the proxy, but makes the [Frontend API](../reference/front-end-api) available to all Pro and Enterprise customers. The API is backed by an Amazon RDS database. Your applications can connect to the frontend API from your own cloud or from other hosting solutions. -In order to access the frontend API you'll need -- to create a [Frontend API key](../reference/api-tokens-and-client-keys#front-end-tokens) for the environment you'd like to use. -- The Frontend API URL. This will be the your Unleash instance's URL followed by "/api/frontend". +In order to access the frontend API you'll need: +- A [Frontend API key](../reference/api-tokens-and-client-keys#front-end-tokens) for the environment you'd like to use. +- The Frontend API URL. This will be your Unleash instance's URL followed by `/api/frontend`. This is the simplest, but also most limited (by far) way to use Unleash client SDKs. In this setup, Unleash hosts both the Unleash API and the Unleash frontend API. With Unleash hosting, you'll only need to worry about the Frontend API keys and the URL to access the endpoint. @@ -74,30 +74,33 @@ This setup is only available to Pro and Enterprise customers. -You host Edge 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 host Edge 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 Edge and the SDKs. ### On Unleash -- Create one or multiple [client API tokens](https://docs.getunleash.io/reference/api-tokens-and-client-keys#client-tokens) scoped to the projects/environments you wish to leverage the Edge instance for. (Refer to [how to create API tokens](https://docs.getunleash.io/how-to/how-to-create-api-tokens) for the steps to create one) -- Create frontend tokens for the frontend apps that will retrieve feature flags from Edge +- Create one or more [client API tokens](https://docs.getunleash.io/reference/api-tokens-and-client-keys#client-tokens) scoped to the projects/environments you wish to use the Edge instance for. Refer to [how to create API tokens](https://docs.getunleash.io/how-to/how-to-create-api-tokens) for the steps to create one. +- Create frontend tokens for the frontend apps that will retrieve feature flags from Edge. ### On Edge Edge will fetch feature flags from the specified upstream Unleash instance for every client API key it has been made aware of, either during startup (recommended) or separate endpoint requests. It will then periodically sync features with upstream. -It will then accept frontend / backend tokens from application SDKs. +It will then accept frontend or backend tokens from application SDKs. :::info Warning -Make sure to use the correct token type for the use case: -Frontend API: Frontend facing apps only, Edge returns app specific context -Client API: For backend SDKs, Edge returns entire flag payload for scope of token (project/environment) +Make sure to use the correct token type for your use case: + +- Frontend API: Use for frontend-facing apps; Edge returns application-specific context. +- Client API: Use for backend SDKs; Edge returns the entire flag payload for the scope of the token (project/environment). ::: -**Start Edge & populate flag cache** -- This initial command will populate flag cache on startup using the client token specified in the environment variable: + +#### Start Edge and populate flag cache + +This initial command will populate the flag cache on startup using the client token specified in the environment variable: ```docker run -p 3063:3063 -e TOKENS='CLIENT_API_TOKEN' -e UPSTREAM_URL='UPSTREAM_URL' unleashorg/unleash-edge:v8.1 edge``` @@ -107,9 +110,9 @@ The following can be used to pass new tokens to Edge for different project/envir ### On SDKs -- Point frontend/client SDKs to Edge endpoints - - **Backend SDKs:** /api/client - - **Frontend SDKs:** /api/frontend, /api/proxy +- Point frontend/client SDKs to Edge endpoints: + - **Backend SDKs**: `/api/client`. + - **Frontend SDKs**: `/api/frontend`, `/api/proxy`. ## You host everything @@ -126,7 +129,7 @@ You host everything yourself. Everything runs where and how you configure it to. **To configure Edge and the SDKs, follow steps in the [previous section on Unleash hosts the API, you host Edge](#unleash-hosts-the-api-you-host-edge)** -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 you might expect, doing everything yourself gives you the most flexibility, but also requires the most effort. However, if you're already hosting Unleash yourself, 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 Edge yourself gives you a number of benefits. @@ -162,13 +165,13 @@ 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](../how-to/how-to-create-api-tokens.mdx) for the steps to create one.) +- 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](../how-to/how-to-create-api-tokens.mdx) 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](../reference/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" +- 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). diff --git a/website/docs/understanding-unleash/the-anatomy-of-unleash.mdx b/website/docs/understanding-unleash/the-anatomy-of-unleash.mdx index 6557fd59a5..37ad6e4405 100644 --- a/website/docs/understanding-unleash/the-anatomy-of-unleash.mdx +++ b/website/docs/understanding-unleash/the-anatomy-of-unleash.mdx @@ -3,7 +3,7 @@ title: The Anatomy of Unleash --- import Figure from '@site/src/components/Figure/Figure.tsx' -This guide's purpose is to give you a conceptual overview of how Unleash works. It covers the various components that exist within an Unleash system and how they interact with each other and with external applications. The diagrams are intended to help you understand the fundamental building blocks, such as [projects](../reference/projects.md), [environments](../reference/environments.md), [variants](../reference/feature-toggle-variants.md) and, of course, [feature flags](../reference/feature-toggles.mdx). +This guide's purpose is to give you a conceptual overview of how Unleash works. It covers the various components that exist within our system and how they interact with each other and with external applications. The diagrams help you understand the fundamental building blocks, such as [projects](../reference/projects.md), [environments](../reference/environments.md), [variants](../reference/feature-toggle-variants.md) and of course, [feature flags](../reference/feature-toggles.mdx). The end of this guide presents a [short use case, explaining how you might configure Unleash](#use-case) to start working with feature flags. @@ -18,7 +18,7 @@ Some things in Unleash are configured and defined on the root level. These optio - [Strategy types](../reference/activation-strategies.md) (including [custom activation strategy types](../reference/custom-activation-strategies.md)) - [Tag types](../reference/tags.md) - [Unleash context](../reference/unleash-context.md) fields (including [custom context fields](../reference/unleash-context.md#custom-context-fields)) -- Users, [user groups](../reference/rbac.md#user-groups) and [roles](../reference/rbac.md) +- Users, [user groups](../reference/rbac.md#user-groups), and [roles](../reference/rbac.md) ## Projects @@ -33,7 +33,7 @@ Pro and Enterprise customers can create, rename, and delete projects as they wis ## Environments and project environments -
+
[**Environments**](../reference/environments.md) in Unleash let you change how a feature flag works in your application’s different environments. For instance, while you are developing a feature, it’s likely that you’ll want it to be available in your development environment, but not in your production environment: environments let you do that. You might also want to enable a feature for only some users in your development environment, but no users in your production environment: environments let you do that. @@ -70,11 +70,11 @@ When creating a feature flag, you must assign a unique (across your Unleash inst When you check a [feature flag](../reference/feature-toggles.mdx) in an application, the following decides the result: 1. Is the flag active in the current environment? If not, it will be disabled. -2. If the flag **is** active in the current environment, the flag’s strategies decide the result. As long as **at least one** of a flag’s strategies resolve to true for the current context (user or application), then the flag will be considered enabled. In other words, if you have a hundred strategies and ninety-nine of them resolve to false, but one of them resolves to true, then the flag is enabled. +2. If the flag **is** active in the current environment, the flag’s strategies decide the result. As long as **at least one** of a flag’s strategies resolves to `true` for the current context (user or application), then the flag will be considered enabled. In other words, if you have a hundred strategies and ninety-nine of them resolve to false, but one of them resolves to true, then the flag is enabled. -Activation strategies tie feature flags and [environments](../reference/environments.md) together. When you assign an activation strategy to a feature flag, you do so in one environment at a time. You can assign the same strategy to the same flag in different environments, but they will be different instances of the same strategy, and do not stay in sync. Unleash also lets you copy strategies from one environment to another. +Activation strategies tie feature flags and [environments](../reference/environments.md) together. When you assign an activation strategy to a feature flag, you do so in one environment at a time. You can assign the same strategy to the same flag in different environments, but they will be different instances of the same strategy and do not stay in sync. Unleash also lets you copy strategies from one environment to another. -Unleash comes with a number of strategies built in (refer the [activation strategies documentation](../reference/activation-strategies.md) for more information on those). You can also create your own [custom activation strategies](../reference/custom-activation-strategies.md) if you need them. All strategies can be further augmented by [**strategy constraints**](../reference/strategy-constraints.md). +Unleash comes with a number of [built-in strategies](../reference/activation-strategies.md). You can also create your own [custom activation strategies](../reference/custom-activation-strategies.md). All strategies can be further augmented by [**strategy constraints**](../reference/strategy-constraints.md).
@@ -93,7 +93,7 @@ An activation strategy can have as many constraints as you want. When an activat :::tip Strategies and constraints -Feature flag strategies are **permissive**: As long as **one** strategy resolves to true, the feature is considered enabled. On the other hand, constrains are **restrictive**: for a given strategy, **all** constraints must be met for it to resolve to true. +Feature flag strategies are **permissive**: As long as **one** strategy resolves to true, the feature is considered enabled. On the other hand, constraints are **restrictive**: for a given strategy, **all** constraints must be met for it to resolve to true. We can exemplify this difference with the logical operators AND and OR: - For a feature flag, if Strategy1 OR Strategy2 OR .. OR StrategyN is true, **then the feature is enabled**. @@ -140,7 +140,7 @@ Prior to 4.21, variants were independent of [environments](../reference/environm
-As of version 4.21, a feature can have different variants in different environments. For instance, a development environment might have no variants, while a production environment has 2 variants. Payloads, weightings and anything else can also differ between environments. +As of version 4.21, a feature can have different variants in different environments. For instance, a development environment might have no variants, while a production environment has 2 variants. Payloads, weightings, and anything else can also differ between environments.
@@ -169,9 +169,9 @@ In pseudocode (loosely based on the [Node.js SDK](/docs/generated/sdks/server-si ```js if (unleash.isEnabled(“new-color-scheme”)) { - // load stylesheet with new color scheme + // load stylesheet with the new color scheme } else { - // load stylesheet with old color scheme + // load stylesheet with the old color scheme } ``` @@ -180,7 +180,7 @@ And with that, the new color scheme is now live in your development environment. ### Rolling out the feature to users -When you’re happy with the new color scheme, you decide to start rolling it out to users. But you want it to go out to only a small number of users at first, so that you can get some feedback while rolling out. +When you’re happy with the new color scheme, you decide to start rolling it out to users. But you want it to go out to only a small number of users at first so that you can get some feedback while rolling out. You decide to add a _gradual rollout_ strategy to the new-color-scheme feature in the production environment. Because you want to start small, you set the rollout percentage to 5%. diff --git a/website/docs/understanding-unleash/unleash-overview.md b/website/docs/understanding-unleash/unleash-overview.md index 23cf27d2e8..a73234e2e8 100644 --- a/website/docs/understanding-unleash/unleash-overview.md +++ b/website/docs/understanding-unleash/unleash-overview.md @@ -2,7 +2,7 @@ title: Unleash introductory overview --- -One of the most important aspects of the architecture to understand is that feature flags are evaluated in client SDKs which runs as part of your application. This makes flag evaluations super-fast (_we're talking nano-seconds_), scalable and resilient against network disturbances. In order to achieve this Unleash incurs a small update-delay when you change your flag configurations until it is fully propagated to your application (in terms of seconds and is configurable). +One of the most important aspects of the Unleash architecture is that feature flags are evaluated directly in the client SDKs that run as part of your application. This makes flag evaluations incredibly fast (we're talking nano-seconds), scalable, and resilient against network disturbances. To achieve this, Unleash incurs a small update-delay when you change your flag configurations until it is fully propagated to your application. This delay is typically a few seconds and is configurable. If you want more details you can read about [our unique architecture](https://www.getunleash.io/blog/our-unique-architecture). @@ -22,9 +22,9 @@ Before you can connect your application to Unleash you need a Unleash server. Yo ![A visual overview of an Unleash system as described in the following paragraph.](/img/unleash-architecture-edge.png 'System Overview') -- [**The Unleash API**](/reference/api/unleash) - The Unleash instance. This is where you create feature flags, configure activation strategies, and parameters, etc. The service holding all feature flags and their configurations. Configurations declare which activation strategies to use and which parameters they should get. -- **The Unleash admin UI** - The bundled web interface for interacting with the Unleash instance. Manage flags, define strategies, look at metrics, and much more. Use the UI to [create feature flags](how-to/how-to-create-feature-toggles.md), [manage project access roles](../how-to/how-to-create-and-assign-custom-project-roles.md), [create API tokens](how-to/how-to-create-api-tokens.mdx), and more. +- [**Unleash API**](/reference/api/unleash) - The Unleash instance. This is where you create feature flags, configure activation strategies, and parameters, etc. The service that contains all feature flags and their configurations. Configurations declare which activation strategies to use and which parameters they should get. +- **Unleash Admin UI** - The bundled web interface for interacting with the Unleash instance. Manage flags, define strategies, look at metrics, and much more. Use the UI to [create feature flags](how-to/how-to-create-feature-toggles.md), [manage project access roles](../how-to/how-to-create-and-assign-custom-project-roles.md), [create API tokens](how-to/how-to-create-api-tokens.mdx), and more. - [**Unleash SDKs**](../reference/sdks/index.md) - Unleash SDKs integrate into your applications and get feature configurations from the Unleash API. Use them to check whether features are enabled or disabled and to send metrics to the Unleash API. [See all our SDKs](../reference/sdks/index.md) -- [**The Unleash Edge**](../generated/unleash-edge.md) - The Unleash Edge sits between front-end and native applications and the Unleash API, it can also sit between server-side SDKs and the Unleash API as well. You can scale it independently of the Unleash API to handle large request rates without causing issues for the Unleash API. Edge has all endpoints for the client API, frontend API, and proxy API. +- [**Unleash Edge**](../generated/unleash-edge.md) - The Unleash Edge sits between front-end and native applications on one side and the Unleash API on the other. It can also sit between server-side SDKs and the Unleash API as well. You can scale it independently of the Unleash API to handle large request rates without causing issues for the Unleash API. Edge has all endpoints for the client API, frontend API, and proxy API. To be super fast (_we're talking nano-seconds_), the [client SDK](../reference/sdks/index.md) caches all feature flags and their current configuration in memory. The activation strategies are also implemented in the SDK. This makes it really fast to check if a flag is on or off because it is just a simple function operating on local state, without the need to poll data from the database.