mirror of
https://github.com/Unleash/unleash.git
synced 2025-09-05 17:53:12 +02:00
docs: add inter-doc links, some reformatting
This commit is contained in:
Thomas Heartman
parent
05803dab03
commit
226c5feefd
@ -2,17 +2,26 @@
|
||||
title: Anatomy of Unleash
|
||||
---
|
||||
|
||||
Welcome to Unleash! Whether you’ve got a brand new instance or a pre-existing one, this guide is here to give you a conceptual overview over how Unleash works. We’ll walk through 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, environments, variants and, of course, feature toggles.
|
||||
Unleash has many different components on different levels. This guide is here to give you a conceptual overview over 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](../user_guide/projects.md), [environments](../user_guide/environments.md), [variants](../advanced/feature-toggle-variants.md) and, of course, [feature toggles](../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 toggles.
|
||||
|
||||
|
||||
## The global level
|
||||
|
||||
Unleash is a hierarchical system where some things are defined at the global level. Most things at the global level are configuration options and not something we will look deeper into in this guide.
|
||||
Some things in Unleash are configured and defined on the global level. These options apply across the entire Unleash instance. The most important global configuration options for day-to-day operations are:
|
||||
|
||||
- [API access tokens](../reference/api-tokens-and-client-keys.mdx)
|
||||
- [Segments](../reference/segments.mdx)
|
||||
- [Strategy types](../user_guide/activation-strategies.md) (including [custom activation strategy types](../advanced/custom-activation-strategy.md))
|
||||
- [Tag types](../advanced/tags.md)
|
||||
- [Unleash context](../user_guide/unleash-context.md) fields (including [custom context fields](../user_guide/unleash-context.md#custom-context-fields))
|
||||
- Users, [user groups](../user_guide/rbac.md#user-groups) and [global roles](../user_guide/rbac.md)
|
||||
|
||||
|
||||
## Projects
|
||||
|
||||
Projects are the most basic component above the global level in Unleash. Projects contain feature toggles and their configurations, and a set of active environments, all of which we’ll go through later in this article.
|
||||
[**Projects**](../user_guide/projects.md) are the most basic component above the global level in Unleash. Projects contain feature toggles and their configurations, and a set of active environments, all of which we’ll go through later in this article.
|
||||
|
||||
All Unleash instances must have at least one project at any given time. New instances get a project called “Default”.
|
||||
|
||||
@ -22,190 +31,114 @@ Pro and Enterprise customers can create, rename, and delete projects as they wis
|
||||
|
||||
## Environments and project environments
|
||||
|
||||
Environments in Unleash let you change how a feature toggle 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 the development environment, but not in the production environment: environments let you do that. You might also want to enable a feature for only some users in a production environment, but for no users in a development environment: environments let you do that.
|
||||
[**Environments**](../user_guide/environments.md) in Unleash let you change how a feature toggle 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 the development environment, but not in the production environment: environments let you do that. You might also want to enable a feature for only some users in a production environment, but for no users in a development environment: environments let you do that.
|
||||
|
||||
Environments exist on two different levels within Unleash. The set of _all available environments_ is defined **on the global level**. Additionally, _each project_ can choose which of these global environments should be available **on the project level**. The set of environments available to any given project is _always a subset_ of the set of globally available environments.
|
||||
Environments exist on two different levels within Unleash. The set of **all available environments is defined on the global level**. Additionally, **each project** can choose which of these global environments should be **available on the project level**. The set of environments available to any given project is **always a subset** of the set of globally available environments.
|
||||
|
||||
Each project must always have _at least one_ active environment.
|
||||
Each project must always have **at least one** active environment.
|
||||
|
||||
Enterprise users can create and remove environments. Open-source and Pro customers get access to two environments: _development_ and _production._
|
||||
Enterprise users can create and remove environments. Open-source and Pro customers get access to two environments: **development** and **production.**
|
||||
|
||||
Environments are adjacent to feature toggles in Unleash: neither one contains the other, but they come together to let you define activation strategies.
|
||||
Environments are adjacent to [feature toggles](../reference/feature-toggles.mdx) in Unleash: neither one contains the other, but they come together to let you define activation strategies.
|
||||
|
||||
|
||||
## Features (feature toggles)
|
||||
|
||||
Feature toggles are at the heart of Unleash’s functionality. Feature toggles belong to projects and live next to project environments. In and of itself, a feature toggle doesn’t do anything. You must assign _activation strategies_ to it for it to start taking effect.
|
||||
|
||||
When creating a feature toggle, you must assign a unique (across your Unleash instance) name, a feature toggle type, a project it belongs to, and an optional description. Everything except for the name can be changed later.
|
||||
|
||||
|
||||
|
||||
[**Feature toggles**](../reference/feature-toggles.mdx) are at the heart of Unleash’s functionality. Feature toggles belong to projects and live next to project environments. In and of itself, a feature toggle doesn’t do anything. You must assign [**activation strategies**](../user_guide/activation-strategies.md) to it for it to start taking effect.
|
||||
|
||||
When creating a feature toggle, you must assign a unique (across your Unleash instance) name, a [feature toggle type](../advanced/feature-toggle-types.md), a [project](../user_guide/projects.md) it belongs to, and an optional description. Everything except for the name can be changed later.
|
||||
|
||||
|
||||
|
||||
|
||||
**Step 2**
|
||||
|
||||
_You can then create a feature toggle within the project. This feature toggle will need a unique name, feature toggle type, what project it lives in, and an optional description. You can also choose to enable impression data at this point. Everything but the name can be edited later. _
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
## Activation strategies
|
||||
|
||||
Activation strategies (or just _strategies_ for short) are the part of feature toggles that tell Unleash _who should get a feature_. An activation strategy is assigned to _one _feature toggle in _one _environment.
|
||||
|
||||
When you check a feature toggle in an application, the toggle’s strategies decide the result. As long as **at least one** of a toggle’s strategies resolve to true for the current context (user or application), then the toggle 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 toggle is enabled.
|
||||
|
||||
Activation strategies tie feature toggles and environments together. When you assign an activation strategy to a feature toggle, you do so in one environment at a time. You can assign the same strategy to the same toggle 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](https://docs.getunleash.io/user_guide/activation_strategy) for more information on those). You can also create your own [custom activation strategies](https://docs.getunleash.io/advanced/custom_activation_strategy) if you need them. All strategies can be further augmented by _strategy constraints_.
|
||||
|
||||
[**Activation strategies**](../user**guide/activation-strategies.md) (or just **strategies** for short) are the part of feature toggles that tell Unleash **who should get a feature**. An activation strategy is assigned to **one **feature toggle in **one **environment.
|
||||
|
||||
When you check a [feature toggle](../reference/feature-toggles.mdx) in an application, the toggle’s strategies decide the result. As long as **at least one** of a toggle’s strategies resolve to true for the current context (user or application), then the toggle 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 toggle is enabled.
|
||||
|
||||
Activation strategies tie feature toggles and [environments](../user_guide/environments.md) together. When you assign an activation strategy to a feature toggle, you do so in one environment at a time. You can assign the same strategy to the same toggle 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](../user**guide/activation-strategies.md) for more information on those). You can also create your own [custom activation strategies](../advanced/custom-activation-strategy.md) if you need them. All strategies can be further augmented by [**strategy constraints**](../advanced/strategy-constraints.md).
|
||||
|
||||
|
||||
|
||||
|
||||
**Step 4 **
|
||||
|
||||
|
||||
## Strategy constraints
|
||||
|
||||
[Strategy constraints](https://docs.getunleash.io/advanced/strategy_constraints) (or just _constraints_) help you fine-tune your strategies. They are an extra layer of prerequisites that help you narrow the audience of a strategy down.
|
||||
[**Strategy constraints**](../advanced/strategy-constraints.md) (or just **constraints**) help you fine-tune your strategies. They are an extra layer of prerequisites that help you narrow the audience of a strategy down. Strategy constraints are applied to [**activation strategies**](../user_guide/activation-strategies.md)
|
||||
|
||||
For example, if you wanted to roll a feature out to 50% of users with _a specific email domain _(such as “@mycompany.com”), then strategy constraints would let you target only users with that email domain.
|
||||
For example, if you wanted to roll a feature out to 50% of users with **a specific email domain **(such as “@mycompany.com”), then strategy constraints would let you target only users with that email domain.
|
||||
|
||||
Constraints can also be used for more general purposes, such as timing feature releases or releasing features in specific regions.
|
||||
|
||||
An activation strategy can have as many constraints as you want. When an activation strategy has multiple constraints, then **every constraint **must be satisfied for the strategy to be evaluated. So if you have two constraints: one that says users must have an “@mycompany.com” email address and one that says users must have signed up for a beta program, then the strategy would only be evaluated for users with @mycompany.com emails that have signed up for the program.
|
||||
An activation strategy can have as many constraints as you want. When an activation strategy has multiple constraints, then **every constraint **must be satisfied for the strategy to be evaluated. So if you have two constraints: one that says users must have an “@mycompany.com” email address and one that says users must have signed up for a beta program, then the strategy would **only be evaluated for users with @mycompany.com emails that have signed up for the program**.
|
||||
|
||||
You can define constraints on whatever properties you want in your [Unleash context](https://docs.getunleash.io/advanced/strategy_constraints).
|
||||
You can define constraints on whatever properties you want in your [Unleash context](../user_guide/unleash-context.md).
|
||||
|
||||
Constraints are applied to individual strategies and do not stay in sync with each other. When you need to have the same constraints applied to multiple strategies and need those constraints to stay in sync, use _segments_.
|
||||
Constraints are applied to individual strategies and do not stay in sync with each other. When you need to have the same constraints applied to multiple strategies and need those constraints to stay in sync, use [**segments**](../reference/segments.mdx).
|
||||
|
||||
|
||||
## Segments
|
||||
|
||||
[Segments](https://docs.getunleash.io/advanced/strategy_constraints) add extra functionality on top of strategy constraints. A segment is a reusable collection of strategy constraints with a name and an optional description. When you apply a segment to a strategy, the strategy will be evaluated as if all of the segment's constraints were applied to it.
|
||||
[**Segments**](../reference/segments.mdx) add extra functionality on top of [**strategy constraints**](../advanced/strategy-constraints.md). A segment is a reusable collection of strategy constraints with a name and an optional description. When you apply a segment to a [strategy](../user_guide/activation-strategies.md), the strategy will be evaluated as if all of the segment's constraints were applied to it.
|
||||
|
||||
Segments let you apply a set of constraints to multiple strategies _and_ keep the constraints in sync between those strategies. Whenever you apply a segment to a strategy, you essentially create a_ reference_ to that segment. This means that whenever you change the segment by adding, removing, or changing constraints, this change propagates to all the strategies that reference this segment.
|
||||
Segments let you apply a set of constraints to multiple strategies **and** keep the constraints in sync between those strategies. Whenever you apply a segment to a strategy, you essentially create a **reference** to that segment. This means that whenever you change the segment by adding, removing, or changing constraints, this change propagates to all the strategies that reference this segment.
|
||||
|
||||
You can apply multiple segments to a strategy. Much like with constraints, _every segment_ needs _every constraint_ to be satisfied for the strategy to be evaluated. If you also have other constraints on the strategy, then those must also be satisfied.
|
||||
You can apply multiple segments to a strategy. Much like with constraints, **every segment** needs **every constraint** to be satisfied for the strategy to be evaluated. If you also have other constraints on the strategy, then those must also be satisfied.
|
||||
|
||||
Segments are only available to Pro and Enterprise users.
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
**Step 5 **
|
||||
|
||||
|
||||
## Variants and feature toggle payloads
|
||||
|
||||
By default, a feature toggle in Unleash only tells you whether a feature is enabled or disabled, but you can also add more information to your toggles by using [feature toggle variants](https://docs.getunleash.io/advanced/strategy_constraints). Variants also allow you to run A/B testing experiments.
|
||||
By default, a [feature toggle](../reference/feature-toggles.mdx) in Unleash only tells you whether a feature is enabled or disabled, but you can also add more information to your toggles by using [**feature toggle variants**](../advanced/feature-toggle-variants.md). Variants also allow you to run [A/B testing experiments](a-b-testing.md).
|
||||
|
||||
Feature toggles are designed to let you decide which users get access to a feature. Variants are designed to let you decide _which version_ of the feature a user gets access to. For instance, if user A is part of your beta testing program and gets access to a new beta feature, then you can use variants to decide whether they should get the red version or the green version of the feature.
|
||||
Feature toggles are designed to let you decide which users get access to a feature. Variants are designed to let you decide **which version** of the feature a user gets access to. For instance, if user A is part of your beta testing program and gets access to a new beta feature, then you can use variants to decide whether they should get the red version or the green version of the feature.
|
||||
|
||||
When you create new variants for a feature, they must be given a name and a _weighting_ indicating how many users should see this particular variant of the feature. They can also be given a _payload_.
|
||||
When you create new variants for a feature, they must be given a name and a **weighting** indicating how many users should see this particular variant of the feature. They can also be given a **payload**.
|
||||
|
||||
You can use the variant payload to attach arbitrary data to a variant. Variants can have different kinds of payloads.
|
||||
|
||||
A feature toggle can have as many variants as you want. And importantly, variants are independent of environments. In other words: you’ll always have the exact same variants with the exact same weightings and the exact same payloads in all environments.
|
||||
|
||||
|
||||
|
||||
|
||||
A feature toggle can have as many variants as you want. Importantly, variants are independent of [environments](../user_guide/environments.md). In other words: you’ll always have the exact same variants with the exact same weightings and the exact same payloads in all environments.
|
||||
|
||||
|
||||
|
||||
|
||||
**Step 6 **
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
**Step 7 **
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
**Step 8**
|
||||
|
||||
_You are also able to create variants which return an additional payload when the feature toggle is enabled. The variants returned are the same across environments. _
|
||||
|
||||
_For example, you can return different colors, values, or other pieces of information that could be used in your client application. _
|
||||
|
||||
_For example, when experimenting between button colors, you can turn on the toggles for users that are receiving the experiment, then also the color the button should be (red, green, blue, yellow). _
|
||||
|
||||
_Link to: https://docs.getunleash.io/advanced/toggle_variants_
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
**Example 1: **Customers above a certain tier get additional features
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
**Example 2: **New feature rollout for improved checkout process
|
||||
|
||||
|
||||
|
||||
* Links to info about features, strategies, etc. ← the essential Unleash instance
|
||||
* What do we do about the proxy? ← mention it as part of the overview, but is company specific
|
||||
* Connecting an SDK ← Or you might not have to, depending on whether the project has one set up already
|
||||
|
||||
|
||||
## Use case: changing website colors
|
||||
## Use case: changing website colors {#use-case}
|
||||
|
||||
Using the concepts we have looked at in the previous sections, let’s create a hypothetical case and see how Unleash would solve it.
|
||||
|
||||
**Problem statement:** You have an existing website with a _red_ color scheme, but you’re feeling a bit adventurous and would like to try and see if changing it to a blue color scheme would be better.
|
||||
**Problem statement:** You have an existing website with a **red** color scheme, but you’re feeling a bit adventurous and would like to try and see if changing it to a blue color scheme would be better.
|
||||
|
||||
**Current state:** You have an existing website that gets server-side rendered and you have a newly created instance of Unleash.
|
||||
|
||||
|
||||
### Configuring Unleash for development
|
||||
|
||||
As this is a brand new Unleash instance, you already have the “Default” project and the “Development” and “Production” environments available. That’s going to be all you need for now.
|
||||
Assuming you have a brand new Unleash instance, you already have the “Default” project and the “Development” and “Production” environments available. That’s going to be all you need for now.
|
||||
|
||||
First things first, in the Default project, you create a new feature toggle, called “new-color-scheme” (toggle names have to be URL-friendly, so no spaces allowed!).
|
||||
|
||||
Because you’d like to see the new color scheme while you’re developing it, you assign a “standard” strategy to the new-color-scheme_ _toggle in the development environment and turn it on.
|
||||
|
||||
Because you’d like to see the new color scheme while you’re developing it, you assign a “standard” strategy to the new-color-scheme toggle in the development environment and turn it on.
|
||||
|
||||
### In your application
|
||||
|
||||
You configure an [Unleash SDK for your server](https://docs.getunleash.io/sdks) to communicate with Unleash. When rendering the page, you check the state of the new-color-scheme feature and render a different stylesheet based on the results.
|
||||
You configure an [Unleash SDK for your server](../sdks/index.md) to communicate with Unleash. When rendering the page, you check the state of the new-color-scheme feature and render a different stylesheet based on the results.
|
||||
|
||||
In pseudocode that might look like this:
|
||||
|
||||
|
||||
Loading…
Reference in New Issue
Block a user