Skip to content

Update feature flag docs #883

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
lorenyu merged 2 commits into from
Feb 25, 2025
Merged

Update feature flag docs #883

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
d89948d
Update feature flag docs
lorenyu Feb 25, 2025
6e050f8
Refine docs
lorenyu Feb 25, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
26 changes: 7 additions & 19 deletions docs/feature-flags.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,28 +4,16 @@ Feature flags are an important tool that enables [trunk-based development](https

## How it works

This project leverages [Amazon CloudWatch Evidently](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch-Evidently.html) to create and manage feature flags.
This project stores feature flags in AWS Parameter Store and injects them into the application as environment variables. See the [feature_flags module](/infra/modules/feature_flags/).

## Creating feature flags
## Create a feature flag

The list of feature flags for an application is defined in the `feature_flags` property in its app-config module (in `/infra/<APP_NAME>/app-config/feature-flags.tf`). To create a new feature flag, add a new string to that list. To remove a feature flag, remove the feature flag from the list. The set of feature flags will be updated on the next `terraform apply` of the service layer, or during the next deploy of the application.
Add a feature flag by updating the map of feature flags and their default values in the app-config module (in `/infra/<APP_NAME>/app-config/feature_flags.tf`). The set of feature flags will be updated on the next `terraform apply` of the service layer, or during the next deploy of the application.

## Querying feature flags in the application
## Set a feature flag value for an environment

To determine whether a particular feature should be enabled or disabled for a given user, the application code calls an "is feature enabled" function in the feature flags module. Under the hood, the module will call AWS Evidently's [EvaluateFeature](https://docs.aws.amazon.com/cloudwatchevidently/latest/APIReference/API_EvaluateFeature.html) API to determine whether a feature is enabled or disabled. For partial rollouts, it will remember which variation of the application a particular user saw and keep the user experience consistent for that user. For more information about the feature flags module, look in the application code and docs.
Set the value of a feature flag for an environment by setting the `feature_flag_overrides` variable to the env-config module for that environment. The value of the feature flag will be updated on the next `terraform apply` of the service layer, or during the next deploy of the application.

## Managing feature releases and partial rollouts via AWS Console
## Query a feature flag value in the application

The system is designed to allow the managing of feature releases and partial rollouts outside of Terraform, which empowers business owners and product managers to control enable and disable feature flags and adjust feature launch traffic percentages without needing to depend on the development team.

### To enable or disable a feature

1. Navigate to the Evidently service in AWS Console, select the appropriate Evidently feature flags project for the relevant application environment, and select the feature you want to manage.
2. In the actions menu, select "Edit feature".
3. Under "Feature variations", select either "FeatureOn" (to enable a feature) or "FeatureOff" (to disable a feature) to be the "Default" variation, then submit. **Warning: Do not modify the variation values. "FeatureOn" should always have a value of "True" and "FeatureOff" should always have a value of "False".**

### To manage a partial rollout

1. Navigate to the Evidently service in AWS Console, and select the appropriate Evidently feature flags project for the relevant application environment
2. Select "Create launch" to create a new partial rollout plan, or select an existing launch to manage an existing rollout
3. Under "Launch configuration", choose the traffic percentage you want to send to each variation, and choose whether you want the launch to begin immediately or on a schedule.
To determine whether a particular feature should be enabled or disabled for a given user, check for an environment variable `FF_<FEATURE_FLAG_NAME>`. If the feature flag is enabled the environment variable will be set to the string `"true"`, otherwise it will be set to the string `"false"`.