diff --git a/website/docs/user_guide/environments.md b/website/docs/user_guide/environments.md index 1bf28fefdf..f7ee615bf7 100644 --- a/website/docs/user_guide/environments.md +++ b/website/docs/user_guide/environments.md @@ -4,7 +4,7 @@ title: Environments ---
@@ -13,13 +13,15 @@ title: Environments -Environments is a new way to organize activation strategy configurations for feature toggles into separate environments. In Unleash a feature lives across all your environments, after all, the goal is to get the new feature released as soon as possible. But it makes sense to configure the activation differently per environment. You might want the feature enabled for everyone in development, while only enable it for yourself in production. +Environments is a new way to organize activation strategy configurations for feature toggles into separate environments. In Unleash, a feature lives across all your environments — after all, the goal is to get the new feature released as soon as possible — but it makes sense to configure the activation differently per environment. You might want the feature enabled for everyone in development, but only for yourself in production, for instance. -Unleash Enterprise users have been able to leverage strategy constraints to control the roll-out per environment. This will not be needed after the release as a "full group" of activation strategy will belong to an environment. +Previously, Unleash Enterprise could use [strategy constraints](https://docs.getunleash.io/advanced/strategy_constraints) to control the rollout across environments. With the new environments feature, this is no longer necessary. Now all activation strategies belong to an explicit environment instead. -Connected applications will also use environment scoped API keys, to make sure they only download feature toggle configurations for the environment they are running in. +Further, connected applications will use environment-scoped API keys to make sure they only download feature toggle configurations for the environment they are running in. -Metrics has also been upgraded to record the environment, so that Unleash now can display the usage metrics per environment. +Finally, metrics have also been upgraded to record the environment. This, in turn, means that Unleash can display usage metrics per environment. + +Despite this being a shift in how Unleash works, everything will continue to work exactly how it did for existing users. For backwards compatibility, we have created an environment named "default" that will contain all of the existing toggles and API keys. Read more about that in [the migration section](#migration). @@ -28,11 +30,13 @@ Metrics has also been upgraded to record the environment, so that Unleash now ca ## How to start using environments -In order to start using environments you need to be on Unleash v4.2. You also need to have the environment feature enabled (if you are using Unleash Hosted, please reach out on [contact@getunleash.io](mailto:contact@getunleash.io) if you want to start using environments. +In order to start using environments you need to be on Unleash v4.2 or higher. You also need to have the environment feature enabled (if you are using Unleash Hosted, please reach out on [contact@getunleash.io](mailto:contact@getunleash.io) if you want to start using environments. + +Note that in order to enable an environment for a feature toggle, you must first add activation strategies for that environment. You cannot enable an environment without activation strategies. ### Step 1: Enable new environments for your Project -Navigate to the project and choose the “environments” tab. +Navigate to the project and choose the “environments” tab. @@ -42,7 +46,7 @@ Navigate to the project and choose the “environments” tab. ### Step 2: Configure activation strategies for the new environment -From the “feature toggle view” you will now be able to configure activation strategies per environment. +From the “feature toggle view” you will now be able to configure activation strategies per environment. You can also enable and disable environments here. Remember that an environment must have activation strategies before you can enable it. @@ -51,7 +55,7 @@ From the “feature toggle view” you will now be able to configure activation ### Step 3: Create environment specific API keys -In order for the SDK to download the feature toggle configuration for the correct environment you will need to create an API token for a defined environment. +In order for the SDK to download the feature toggle configuration for the correct environment you will need to create an API token for a defined environment. @@ -61,9 +65,10 @@ In order for the SDK to download the feature toggle configuration for the correc ## Migration -To ease migration we have created a special environment called “default”. All existing activation strategies have been added to this environment. All existing Client API keys has also been scoped to work against the default environment, to ensure zero disruption as part of the upgrade. +To ease migration we have created a special environment called “default”. All existing activation strategies have been added to this environment. All existing Client API keys have also been scoped to work against the default environment to ensure zero disruption as part of the upgrade. + +If you're currently using strategy constraints together with the “environment” field on the Unleash Context, you should be aware that the new environment support works slightly differently. With environments, the SDK API will use the client's API key to determine which environment the client is configured for. The API then sends _only_ strategies belonging to the client's environment. This means that you might not need the "environment" property of the Unleash Context anymore. -If you today are using strategy constraints together with the “environment” field on the Unleash Context you should be aware that the new environment support works slightly differently. Now the SDK will only download the activation strategies configured for a configured environment. The Unleash SDK API will know which environment to deliver to the SDK because the API token used by the SDK is scoped to a single environment. Because of this you will probably stop using “environment” on the Unleash Context. @@ -73,31 +78,33 @@ If you today are using strategy constraints together with the “environment” ### Addons -We have slightly changed the events related to working with feature toggles. This means that you would need to change your addon configuration to also subscribe for the new events to not miss updates: +We have made some slight changes to events related to feature toggles: there's one deprecation and several new event types. Most of the new events contain _project_ and _environment_ data. + +To avoid missing important updates, you will also need to update your addon configuration to subscribe to the new events. **Deprecated events:** * **FEATURE_UPDATE** - _not used after switching to environments_ **New Events** -* **FEATURE-METADATA-UPDATED** - The feature toggle metadata was updated (across all environments). +* **FEATURE-METADATA-UPDATED** - The feature toggle metadata was updated (across all environments). * **FEATURE-STRATEGY-ADD**¹ - An activation strategy was added to a feature toggle in an environment. The _data_ will contain the updated strategy configuration. * **FEATURE-STRATEGY-UPDATE**¹ - An activation strategy was updated for a feature toggle. The _data_ will contain the updated strategy configuration. -* **FEATURE-STRATEGY-REMOVE**¹ - An activation strategy was removed for a feature toggle. -* **FEATURE-ENVIRONMENT-ENABLED**¹ - Signals that a feature toggle has been _enabled_ in a defined environment. -* **FEATURE-ENVIRONMENT-DISABLED**¹ - Signals that a feature toggle has been _disabled_ in a defined environment. -* **FEATURE-PROJECT-CHANGE**¹ - The feature toggle was moved to a new project. +* **FEATURE-STRATEGY-REMOVE**¹ - An activation strategy was removed for a feature toggle. +* **FEATURE-ENVIRONMENT-ENABLED**¹ - Signals that a feature toggle has been _enabled_ in a defined environment. +* **FEATURE-ENVIRONMENT-DISABLED**¹ - Signals that a feature toggle has been _disabled_ in a defined environment. +* **FEATURE-PROJECT-CHANGE**¹ - The feature toggle was moved to a new project. -> 1) These feature events will contain _project_ and _environment_ as part of the even metadata. +> 1) These feature events will contain _project_ and _environment_ as part of the event metadata. -### API +### API -In order to support configuration per environment we had to rebuild our feature toggle admin API to account for environments as well. This means +In order to support configuration per environment we had to rebuild our feature toggle admin API to account for environments as well. This means that we're making the following changes to the API: * **/api/admin/features** - _deprecated (scheduled for removal in Unleash v5.0). The [old feature toggles admin API](https://docs.getunleash.io/api/admin/features) still works, but strategy configuration will be assumed to target the “default” environment._ -* **/api/admin/projects/:projectId/features** - New feature API to be used for feature toggles which also adds support for environments. See [the documentation](https://docs.getunleash.io/api/admin/feature-toggles-v2) to learn more. +* **/api/admin/projects/:projectId/features** - New feature API to be used for feature toggles which also adds support for environments. See [the documentation](https://docs.getunleash.io/api/admin/feature-toggles-v2) to learn more. ## Plan Differences @@ -107,23 +114,23 @@ In order to support configuration per environment we had to rebuild our feature -* Will get access to two pre-configured environments: “development” and “production”. Existing users of Unleash will also get an additional “default” environment to simplify adoption of environments. -* Will be possible to turn environments on/off for all projects. +* Will get access to two preconfigured environments: “development” and “production”. Existing users of Unleash will also get an additional “default” environment to simplify the adoption of environments. +* Will be possible to turn environments on/off for all projects. ### Pro (commercial) -* Will get access to two pre-configured environments: “development” and “production”. Existing users of Unleash will also get an additional “default” environment to simplify the adoption of environments. -* Will be possible to turn environments on/off for the default project. +* Will get access to two preconfigured environments: “development” and “production”. Existing users of Unleash will also get an additional “default” environment to simplify the adoption of environments. +* Will be possible to turn environments on/off for the default project. ### Enterprise (commercial) -* Will get access to two pre-configured environments: “development” and “production”. Existing users of Unleash will also get an additional “default” environment to simplify the adoption of environments. +* Will get access to two preconfigured environments: “development” and “production”. Existing users of Unleash will also get an additional “default” environment to simplify the adoption of environments. * Will be possible to turn environments on/off for all projects * Will be allowed to update and remove environments. * Will be allowed to create new environments. @@ -133,8 +140,8 @@ In order to support configuration per environment we had to rebuild our feature -* **Unleash v4.2** will provide _early access_ to environment support. This means that it can be enabled per customer via a feature flag. -* **Unleash v4.3** plans to provide general access to the environment support for all users of Unleash (Open-Source, Pro, Enterprise). +* **Unleash v4.2** will provide _early access_ to environment support. This means that it can be enabled per customer via a feature flag. +* **Unleash v4.3** plans to provide general access to the environment support for all users of Unleash (Open-Source, Pro, Enterprise). ### Future enhancements @@ -143,5 +150,5 @@ With improved environment capabilities we have also done the groundwork to be ab -* Improve **Usage Metrics **to be able to show usage and evaluation results per hour for multiple days with dimensions such as environment, application and time (per hour). -* Improve **RBAC** with the ability to limit who can change configuration for a specific environment (planned as an enterprise feature). \ No newline at end of file +* Improve **Usage Metrics** to be able to show usage and evaluation results per hour for multiple days with dimensions such as environment, application and time (per hour). +* Improve **RBAC** with the ability to limit who can change configuration for a specific environment (planned as an enterprise feature).