Understanding multi-variant feature flag concepts and common use cases Understanding multi-variant feature flag rules Creating a multi-variant feature flag

Creating multi-variant feature flags

Feature flag variants enable you to define a set of possible flag values to return for a request. You can also configure different statuses (enabled or disabled) for multi-variant flags. When requesting a flag configured with variants, your application provides context that AWS AppConfig evaluates against a set of user-defined rules. Depending on the context specified in the request and the rules defined for the variant, AWS AppConfig returns different flag values to the application.

The following screenshot shows an example of a feature flag with three user-defined variants and the required Default variant.

An example screenshot of a feature flag with variants.

Understanding multi-variant feature flag concepts and common use cases

To help you better understand feature flag variants, this section explains flag variant concepts and common use cases.

Concepts

Feature flag: An AWS AppConfig configuration type used to control the behavior of a feature in an application. A flag has a status (enabled or disabled) and an optional set of attributes containing arbitrary string, numeric, boolean, or array values.
Feature flag variant: A specific combination of status and attribute values belonging to a feature flag. A feature flag may have multiple variants.
Variant rule: A user-defined expression used to select a feature flag variant. Each variant has its own rule that AWS AppConfig evaluates to determine whether to return it or not.
Default variant: A special variant that is returned when no other variant is selected. A default variant doesn’t have a rule. All multi-variant feature flags have a default variant.
Context: User-defined keys and values passed to AWS AppConfig at configuration retrieval time. Context values are used during rule evaluation to select the feature flag variant to return.

Note

For more information about AWS AppConfig Agent, see How to use AWS AppConfig Agent to retrieve configuration data.

Common use cases

This section describes two common use cases for feature flag variants.

User segmentation

User segmentation is the process of dividing users based on certain attributes. As an example, you could use flag variants to expose a feature to some users but not others based on their user ID, geographic location, device type, or purchase frequency.

Using the example of purchase frequency, suppose your commerce application supports a feature to increase customer loyalty. You can use flag variants to configure different incentive types to be shown to a user based on when they last purchased something. A new user might be offered a small discount to encourage them to become a customer, whereas a repeat customer might be given a larger discount if they purchase something from a new category.

Traffic splitting

Traffic splitting is the process of selecting a random, but consistent, flag variant based on a context value you define. For example, you may want to perform an experiment where a small percentage of your users (identified by their user ID) sees a particular variant. Or, you may want to execute a gradual feature rollout where a feature is first exposed to 5% of your users, then 15%, then 40%, then 100%, while maintaining a consistent user experience throughout the rollout.

Using the experimentation example, you could use flag variants to test a new button style for the primary action on your application homepage to see if it drives more clicks. For your experiment, you could create a flag variant with a traffic splitting rule that selects 5% of users to see the new style, while the default variant indicates the users that should continue to see the existing style. If the experiment is successful, you can increase the percentage value, or even turn that variant into the default.

Understanding multi-variant feature flag rules

When you create a feature flag variant, you specify a rule for it. Rules are expressions that take context values as input and produce a boolean result as output. For example, you could define a rule to select a flag variant for beta users, identified by their account ID, testing a user interface refresh. For this scenario, you do the following:

Create a new feature flag configuration profile called UI Refresh.
Create a new feature flag called ui_refresh.
Edit the feature flag after you create it to add variants.
Create and enable a new variant called BetaUsers.
Define a rule for BetaUsers that selects the variant if the account ID from the request context is in a list of account IDs approved to view the new beta experience.
Confirm that the default variant’s status is set to disabled.

Note

Variants are evaluated as an ordered list based on the order they are defined in the console. The variant at the top of the list is evaluated first. If no rules match the supplied context, AWS AppConfig returns the Default variant.

When AWS AppConfig processes the feature flag request, it compares the supplied context, which includes the AccountID (for this example) to the BetaUsers variant first. If the context matches the rule for BetaUsers, AWS AppConfig returns the configuration data for the beta experience. If the context doesn’t include an account ID or if the account ID ends in anything other than 123, AWS AppConfig returns configuration data for the Default rule, which means the user views the current experience in production.

Defining rules

A variant rule is an expression comprised of one or more operands and an operator. An operand is a specific value used during the evaluation of a rule. Operand values can be either static, such as a literal number or string, or variable, such as the value found in a context or the result of another expression. An operator, such as "greater than", is a test or action applied to its operands that produces a value. A variant rule expression must produce either a "true" or "false" to be valid.

Operands

Type	Description	Example
String	A sequence of UTF-8 characters, enclosed in double-quotes.	`"apple", "Ḽơᶉëᶆ ȋṕšᶙṁ"`
Integer	A 64-bit integer value.	`-7, 42`
Float	A 64-bit IEEE-754 floating-point value.	`3.14, 1.234e-5`
Timestamp	A specific moment in time as described by the W3C note on date and time formats.	`2012-03-04T05:06:07-08:00, 2024-01`
Boolean	A true or false value.	`true, false`
Context value	A parameterized value in the form of $`key` that is retrieved from the context during rule evaluation.	`$country, $userId`

Comparison operators

Operator	Description	Example
eq	Determines whether a context value is equal to a given value.	`(eq $state "Virginia")`
gt	Determines whether a context value is greater than a given value.	`(gt $age 65)`
gte	Determines whether a context value is greater than or equal to a given value.	`(gte $age 65)`
lt	Determines whether a context value is less than a given value.	`(lt $age 65)`
lte	Determines whether a context value is less than or equal to a given value.	`(lte $age 65)`

Logical operators

Operator	Description	Example
and	Determines if both operands are true.	`(and (eq $state "Virginia") (gt $age 65) )`
or	Determines if at least one of the operands is true.	`(or (eq $state "Virginia") (gt $age 65) )`
not	Reverses the value of an expression.	`(not (eq $state "Virginia"))`

Custom operators

Operator	Description	Example
begins_with	Determines whether a context value begins with a given prefix.	`(begins_with $state "A")`
ends_with	Determines whether a context value ends with a given prefix.	`(ends_with $email "amazon.com")`
contains	Determines whether a context value contains a given substring.	`(contains $promoCode "WIN")`
in	Determines whether a context value is contained within a list of constants.	`(in $userId ["123", "456"])`
matches	Determines whether a context value matches a given regex pattern.	`(matches in::$greeting pattern::"h.*y")`
exists	Determines whether any value was provided for a context key.	`(exists key:"country")`
split	Evaluates to true for a given percentage of traffic based on a consistent hash of the provided context value(s).	`(split pct::10 by::$userId seed::"abc")`

Creating a multi-variant feature flag

Use the procedures in this section to create variants of a feature flag.

Before you begin

Note the following important information.

You can create variants of existing feature flags by editing them. You can't create variants of a new feature flag when you create a new configuration profile. You must complete the workflow of creating the new configuration profile first. After you create the configuration profile, you can add variants to any flag within the configuration profile. For information about how to create a new configuration profile, see Creating a feature flag configuration profile in AWS AppConfig.
To retrieve feature flag variant data for Amazon EC2, Amazon ECS, and Amazon EKS compute platforms, you must use AWS AppConfig Agent version 2.0.4416 or later.
For performance reasons, AWS CLI and SDK calls to AWS AppConfig don't retrieve variant data. For more information about AWS AppConfig Agent, see How to use AWS AppConfig Agent to retrieve configuration data.
When you create a feature flag variant, you specify a rule for it. Rules are expressions that take request context as input and produce a boolean result as output. Before you create variants, review the supported operands and operators for flag variant rules. You can create rules before you create variants. For more information, see Understanding multi-variant feature flag rules.

Topics

Creating a multi-variant feature flag (console)
Creating a multi-variant feature flag (command line)

Creating a multi-variant feature flag (console)

The following procedure describes how to create a multi-variant feature flag for an existing configuration profile by using the AWS AppConfig console. You can also edit existing feature flags to create variants.

To create a multi-variant feature flag

Open the AWS Systems Manager console at https://console.aws.amazon.com/systems-manager/appconfig/.
In the navigation pane, choose Applications, and then choose an application.
On the Configuration profiles and feature flags tab, choose an existing feature flag configuration profile.
In the Flags section, choose Add new flag.
In the Feature flag definition section, for Flag name, enter a name.
For Flag key enter a flag identifier to distinguish flags within the same configuration profile. Flags within the same configuration profile can't have the same key. After the flag is created, you can edit the flag name, but not the flag key.
(Optional) In the Description field, enter information about this flag.
In the Variants section, choose Multi-variant flag.
(Optional) In the Feature flag attributes section, choose Define attribute. Attributes enable you to provide additional values within your flag. For more information about attributes and constraints, see Understanding feature flag attributes.
1. For Key, specify a flag key and choose its type from the Type list. For information about the supported options for the Value and Constraints fields, see the previously referenced section about attributes.
2. Select Required value to specify whether an attribute value is required.
3. Choose Define attribute to add additional attributes.
4. Choose Apply to save attribute changes.
In the Feature flag variants section, choose Create variant.
1. For Variant name, enter a name.
2. Use the Enabled value toggle to enable the variant.
3. In the Rule text box, enter a rule.
4. Use the Create variant > Create variant above or Create variant below options to create additional variants for this flag.
5. In the Default variant section, use the Enabled value toggle to enable the default variant. Optionally, provide values for attributes defined in step 10.
6. Choose Apply.
Verify the details of the flag and its variants and choose Create flag.

For information about deploying your new feature flag with variants, see Deploying feature flags and configuration data in AWS AppConfig.

Creating a multi-variant feature flag (command line)

The following procedure describes how to use the AWS Command Line Interface (on Linux or Windows) or Tools for Windows PowerShell to create a multi-variant feature flag for an existing configuration profile. You can also edit existing feature flags to create variants.

Before you begin

Complete the following tasks before you create a multi-variant feature flag by using the AWS CLI.

Create a feature flag configuration profile. For more information, see Creating a feature flag configuration profile in AWS AppConfig.
Update to the latest version of the AWS CLI. For more information, see Install or update to the latest version of the AWS CLI in the AWS Command Line Interface User Guide.

To create a multi-variant feature flag

Create a configuration file on your local machine that specifies the details of the multi-variant flag you want to create. Save the file with a .json file extension. The file must adhere to the AWS.AppConfig.FeatureFlags JSON schema. The schema contents of your configuration file will be similar to the following.


{
  "flags": {
    "FLAG_NAME": {
      "attributes": {
          "ATTRIBUTE_NAME": {
          "constraints": {
            "type": "CONSTRAINT_TYPE"
          }
        }
      },
      "description": "FLAG_DESCRIPTION",
      "name": "VARIANT_NAME"
    }
  },
  "values": {
    "VARIANT_VALUE_NAME": {
      "_variants": [
        {
          "attributeValues": {
            "ATTRIBUTE_NAME": BOOLEAN
          },
          "enabled": BOOLEAN,
          "name": "VARIANT_NAME",
          "rule": "VARIANT_RULE"
        },
        {
          "attributeValues": {
            "ATTRIBUTE_NAME": BOOLEAN
          },
          "enabled": BOOLEAN,
          "name": "VARIANT_NAME",
          "rule": "VARIANT_RULE"
        },
        {
          "attributeValues": {
            "ATTRIBUTE_NAME": BOOLEAN
          },
          "enabled": BOOLEAN,
          "name": "VARIANT_NAME",
          "rule": "VARIANT_RULE"
        },
        {
          "attributeValues": {
            "ATTRIBUTE_NAME": BOOLEAN
          },
          "enabled": BOOLEAN,
          "name": "VARIANT_NAME",
          "rule": "VARIANT_RULE"
        }
      ]
    }
  },
  "version": "VERSION_NUMBER"
}

Here is an example with three variants and the default variant.


{
  "flags": {
    "ui_refresh": {
      "attributes": {
        "dark_mode_support": {
          "constraints": {
            "type": "boolean"
          }
        }
      },
      "description": "A release flag used to release a new UI",
      "name": "UI Refresh"
    }
  },
  "values": {
    "ui_refresh": {
      "_variants": [
        {
          "attributeValues": {
            "dark_mode_support": true
          },
          "enabled": true,
          "name": "QA",
          "rule": "(ends_with $email \"qa-testers.mycompany.com\")"
        },
        {
          "attributeValues": {
            "dark_mode_support": true
          },
          "enabled": true,
          "name": "Beta Testers",
          "rule": "(exists $opted_in_to_beta)"
        },
        {
          "attributeValues": {
            "dark_mode_support": false
          },
          "enabled": true,
          "name": "Sample Population",
          "rule": "(split pct::10 by::$email)"
        },
        {
          "attributeValues": {
            "dark_mode_support": false
          },
          "enabled": false,
          "name": "Default Variant"
        }
      ]
    }
  },
  "version": "1"
}

Use the CreateHostedConfigurationVersion API to save your feature flag configuration data to AWS AppConfig.

The service_returned_content_file contains your configuration data that includes some AWS AppConfig generated metadata.

Note

When you create the hosted configuration version, AWS AppConfig verifies that your data conforms to the AWS.AppConfig.FeatureFlags JSON schema. AWS AppConfig additionally validates that each feature flag attribute in your data satisfies the constraints you defined for those attributes.

Warning Javascript is disabled or is unavailable in your browser.

To use the Amazon Web Services Documentation, Javascript must be enabled. Please refer to your browser's Help pages for instructions.

Document Conventions

Creating a feature flag configuration profile (command line)

Type reference for AWS.AppConfig.FeatureFlags