Feature flags provide a way for Spring Boot applications to turn features on or off dynamically. Developers can use feature flags in simple use cases like conditional statement to more advanced scenarios like conditionally adding routes. Feature Flags are not dependent of any spring-cloud-azure dependencies, but may be used in conjunction with spring-cloud-azure-appconfiguration-config.
Here are some of the benefits of using this library:
- A common convention for feature management
- Low barrier-to-entry
- Supports application.yml file feature flag setup
- Feature Flag lifetime management
- Configuration values can change in real-time, feature flags can be consistent across the entire request
Feature flags are composed of two parts, a name and a list of feature-filters that are used to turn the feature on.
Feature filters define a scenario for when a feature should be enabled. When a feature is evaluated for whether it is on or off, its list of feature-filters are traversed until one of the filters decides the feature should be enabled. At this point the feature is considered enabled and traversal through the feature filters stops. If no feature filter indicates that the feature should be enabled, then it will be considered disabled.
As an example, a Microsoft Edge browser feature filter could be designed. This feature filter would activate any features it is attached to as long as an HTTP request is coming from Microsoft Edge.
The Spring Configuration system is used to determine the state of feature flags. Any system can be used to have them read in, such as application.yml, spring-cloud-azure-appconfiguration-config and more.
The feature management library supports application.yml or bootstrap.yml as a feature flag source. Below we have an example of the format used to set up feature flags in a application.yml file.
feature-management:
feature-set:
features:
feature-t: false
feature-u:
enabled-for:
-
name: Random
feature-v:
enabled-for:
-
name: TimeWindowFilter
parameters:
time-window-filter-setting-start: "Wed, 01 May 2019 13:59:59 GMT",
time-window-filter-setting-end: "Mon, 01 July 2019 00:00:00 GMT"
The feature-management
section of the YAML document is used by convention to load feature flags. In the section above, we see that we have provided three different features. Features define their filters using the enabled-for
property. We can see that feature feature-t
is set to false with no filters set. feature-t
will always return false, this can also be done for true. feature-u
which has only one feature filter Random
which does not require any configuration so it only has the name property. feature-v
it specifies a feature filter named TimeWindow
. This is an example of a configurable feature filter. We can see in the example that the filter has a parameter's property. This is used to configure the filter. In this case, the start and end times for the feature to be active are configured.
Name | Description | Required | Default |
---|---|---|---|
spring.cloud.azure.feature.management.fail-fast | Whether throw RuntimeException or not when exception occurs | No | true |
The simplest use case for feature flags is to do a conditional check for whether a feature is enabled to take different paths in code. The use cases grow when additional using spring-cloud-azure-feature-flag-web to manage web based features.
The basic form of feature management is checking if a feature is enabled and then performing actions based on the result. This is done through the autowiring FeatureManager
and calling it's isEnabledAsync
method.
@Autowired
FeatureManager featureManager;
if(featureManager.isEnabledAsync("feature-t").block()) {
// Do Something
}
FeatureManager
can also be accessed by @Component
classes.
When using the Feature Management Web library you can require that a given feature is enabled in order to execute. This can be done by using the @FeatureOn
annotation.
@GetMapping("/featureT")
@FeatureGate(feature = "feature-t")
@ResponseBody
public String featureT() {
...
}
The featureT
endpoint can only be accessed if "feature-t" is enabled.
When a controller is blocked because the feature it specifies is disabled, IDisabledFeaturesHandler
will be invoked. By default, a HTTP 404 is returned. This can be overridden using implementing IDisabledFeaturesHandler
.
@Component
public class DisabledFeaturesHandler implements IDisabledFeaturesHandler{
@Override
public HttpServletResponse handleDisabledFeatures(HttpServletRequest request, HttpServletResponse response) {
...
return response;
}
}
Certain routes may expose application capabilites that are gated by features. These routes can redirected if a feature is disabled to another endpoint.
@GetMapping("/featureT")
@FeatureGate(feature = "feature-t" fallback= "/oldEndpoint")
@ResponseBody
public String featureT() {
...
}
@GetMapping("/oldEndpoint")
@ResponseBody
public String oldEndpoint() {
...
}
Creating a feature filter provides a way to enable features based on criteria that you define. To implement a feature filter, the FeatureFilter
interface must be implemented. FeatureFilter
has a single method evaluate
. When a feature specifies that it can be enabled with a feature filter, the evaluate
method is called. If evaluate
returns true
it means the feature should be enabled. If false
it will continue evaluating the Feature's filters until one returns true. If all return false
then the feature is off.
Feature filters are found by being defined as @Component
where there name matches the expected filter defined in the configuration.
@Component("Random")
public class Random implements FeatureFilter {
@Override
public boolean evaluate(FeatureFilterEvaluationContext context) {
double chance = Double.valueOf((String) context.getParameters().get("chance"));
return Math.random() > chance/100;
}
}
Some feature filters require parameters to decide whether a feature should be turned on or not. For example a browser feature filter may turn on a feature for a certain set of browsers. It may be desired that Edge and Chrome browsers enable a feature, while FireFox does not. To do this a feature filter can be designed to expect parameters. These parameters would be specified in the feature configuration, and in code would be accessible via the FeatureFilterEvaluationContext
parameter of evaluate
. FeatureFilterEvaluationContext
has a property parameters
which is a HashMap<String, Object>
.
There are scenarios which require the state of a feature to remain consistent during the lifetime of a request. The values returned from the standard FeatureManager
may change if the configuration source which it is pulling from is updated during the request. This can be prevented by using FeatureManagerSnapshot
and @FeatureOn( snapshot = true )
. FeatureManagerSnapshot
can be retrieved in the same manner as FeatureManager
. FeatureManagerSnapshot
calls FeatureManager
, but it caches the first evaluated state of a feature during a request and will return the same state of a feature during its lifetime.
There are a few feature filters that come with the spring-cloud-azure-feature-management
package. These feature filters are not added automatically, but can be referenced and registered as soon as the package is registered.
Each of the built-in feature filters have their own parameters. Here is the list of feature filters along with examples.
This filter provides the capability to enable a feature based on a set percentage.
feature-management:
feature-set:
features:
feature-v:
enabled-for:
-
name: PercentageFilter
parameters:
percentage-filter-setting: 50
This filter provides the capability to enable a feature based on a time window. If only time-window-filter-setting-end
is specified, the feature will be considered on until that time. If only start is specified, the feature will be considered on at all points after that time. If both are specified the feature will be considered valid between the two times.
feature-management:
feature-set:
features:
feature-v:
enabled-for:
-
name: TimeWindowFilter
parameters:
time-window-filter-setting-start: "Wed, 01 May 2019 13:59:59 GMT",
time-window-filter-setting-end: "Mon, 01 July 2019 00:00:00 GMT"
This filter provides the capability to enable a feature for a target audience. An in-depth explanation of targeting is explained in the targeting section below. The filter parameters include an audience object which describes users, groups, and a default percentage of the user base that should have access to the feature. Each group object that is listed in the target audience must also specify what percentage of the group's members should have access. If a user is specified in the users section directly, or if the user is in the included percentage of any of the group rollouts, or if the user falls into the default rollout percentage then that user will have the feature enabled.
feature-management:
target:
enabled-for:
-
name: targetingFilter
parameters:
users:
- Jeff
- Alicia
groups:
-
name: Ring0
rolloutPercentage: 100
-
name: Ring1
rolloutPercentage: 100
defaultRolloutPercentage: 50
Targeting is a feature management strategy that enables developers to progressively roll out new features to their user base. The strategy is built on the concept of targeting a set of users known as the target audience. An audience is made up of specific users, groups, and a designated percentage of the entire user base. The groups that are included in the audience can be broken down further into percentages of their total members.
The following steps demonstrate an example of a progressive rollout for a new 'Beta' feature:
- Individual users Jeff and Alicia are granted access to the Beta
- Another user, Mark, asks to opt-in and is included.
- Twenty percent of a group known as "Ring1" users are included in the Beta.
- The number of "Ring1" users included in the beta is bumped up to 100 percent.
- Five percent of the user base is included in the beta.
- The rollout percentage is bumped up to 100 percent and the feature is completely rolled out.
- This strategy for rolling out a feature is built in to the library through the included TargetingFilter feature filter.
An example web application that uses the targeting feature filter is available in the FeatureFlagDemo example project.
To begin using the TargetingFilter
in an application it must be added as a @Bean
like any other Feature Filter. TargetingFilter
relies on another @Bean
to be added to the application, ITargetingContextAccessor
. The ITargetingContextAccessor
allows for defining the current TargetingContext
to be used for defining the current user id and groups. An example of this is:
public class TargetingContextAccessor implements ITargetingContextAccessor {
@Override
public Mono<TargetingContext> getContextAsync() {
TargetingContext context = new TargetingContext();
context.setUserId("Jeff");
ArrayList<String> groups = new ArrayList<String>();
groups.add("Ring0");
context.setGroups(groups);
return Mono.just(context);
}
}
Options are available to customize how targeting evaluation is performed across a given TargetingFilter
. An optional parameter TargetingEvaluationOptions
can be set during TargetingFilter
creation.
@Bean
public TargetingFilter targetingFilter(ITargetingContextAccessor contextAccessor) {
return new TargetingFilter(contextAccessor, new TargetingEvaluationOptions().setIgnoreCase(true));
}