Creating a feature flag configuration profile in AWS AppConfig - AWS AppConfig

Creating a feature flag configuration profile in AWS AppConfig

You can use feature flags to enable or disable features within your applications or to configure different characteristics of your application features using flag attributes. AWS AppConfig stores feature flag configurations in the AWS AppConfig hosted configuration store in a feature flag format that contains data and metadata about your flags and the flag attributes. For more information about the AWS AppConfig hosted configuration store, see About the AWS AppConfig hosted configuration store section.

Before you begin

In the following procedure, in the optional Encryption section, you can choose an AWS Key Management Service (AWS KMS) key. This customer managed key enables you to encrypt new configuration data versions in the AWS AppConfig hosted configuration store. For more information about this key, see AWS AppConfig supports customer manager keys in Security in AWS AppConfig.

The following procedure also gives you the option to associate an extension with a feature flag configuration profile. An extension augments your ability to inject logic or behavior at different points during the AWS AppConfig workflow of creating or deploying a configuration. For more information, see About AWS AppConfig extensions.

Lastly, in the Feature flag attributes section, when you enter the attribute details of a new feature flag, you can specify constraints. Constraints ensure that any unexpected attribute values are not deployed to your application. AWS AppConfig supports the following types of flag attributes and their corresponding constraints.

Type Constraint Description
String Regular Expression

Regex pattern for the string

Enum

List of acceptable values for the string

Number Minimum

Minimum numeric value for the attribute

Maximum

Maximum numeric value for the attribute

Boolean None None
String array Regular Expression Regex pattern for the elements of the array
Enum List of acceptable values for the elements of the array
Number array Minimum Minimum numeric value for the elements of the array
Maximum Maximum numeric value for the elements of the array

Creating a feature flag configuration profile (console)

Use the following procedure to create an AWS AppConfig feature flag configuration profile by using the AWS AppConfig console.

To create a configuration profile
  1. Open the AWS Systems Manager console at https://console.aws.amazon.com/systems-manager/appconfig/.

  2. In the navigation pane, choose Applications, and then choose an application you created in Creating a namespace for your application in AWS AppConfig.

  3. Choose the Configuration profiles and feature flags tab, and then choose Create configuration.

  4. In the Configuration options section, choose Feature flag.

  5. Scroll down. In the Configuration profile section, for Configuration profile name, enter a name.

  6. (Optional) Expand Description and enter a description.

  7. (Optional) Expand Additional options and complete the following, as necessary.

    1. In the Encryption list, choose an AWS Key Management Service (AWS KMS) key from the list.

    2. In the Associate extensions section, choose an extension from the list.

    3. In the Tags section, choose Add new tag, and then specify a key and optional value.

  8. Choose Next.

  9. In the Feature flag definition section, for Flag name, enter a name.

  10. 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.

  11. (Optional) Expand Description and enter information about this flag.

  12. Select This is a short-term flag and optionally choose a date for when the flag should be disabled or deleted. Note that AWS AppConfig does not disable the flag.

  13. In the Flag attributes section, choose Define attribute. Attributes enable you to provide additional values within your flag.

  14. For Key, specify a flag key and choose its type from the Type list. You can optionally validate attribute values against specified constraints. The following image shows an example.

    Example of flag attributes for an AWS AppConfig feature flag

    Choose Define attribute to add additional attributes.

    Note

    Note the following information.

    • For attribute names, the word "enabled" is reserved. You can't create a feature flag attribute called "enabled". There are no other reserved words.

    • The attributes of a feature flag are only included in the GetLatestConfiguration response if that flag is enabled.

    • Flag attribute keys for a given flag must be unique.

    • Select Required value to specify whether an attribute value is required.

  15. In the Feature flag value section, choose Enabled to enable the flag. Use this same toggle to disable a flag when it reaches a specified deprecration date, if applicable.

  16. Choose Next.

  17. On the Review and save page, verify the details of the flag and then Save and continue to deploy.

Proceed to Deploying feature flags and configuration data in AWS AppConfig.

Creating a feature flag and a feature flag configuration profile (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 an AWS AppConfig feature flag configuration profile. If you prefer, you can use AWS CloudShell to run the commands listed below. For more information, see What is AWS CloudShell? in the AWS CloudShell User Guide.

To create a feature flags configuration step by step
  1. Open the AWS CLI.

  2. Create a feature flag configuration profile specifying its Type as AWS.AppConfig.FeatureFlags. The configuration profile must use hosted for the location URI.

    Linux
    aws appconfig create-configuration-profile \ --application-id The_application_ID \ --name A_name_for_the_configuration_profile \ --location-uri hosted \ --type AWS.AppConfig.FeatureFlags
    Windows
    aws appconfig create-configuration-profile ^ --application-id The_application_ID ^ --name A_name_for_the_configuration_profile ^ --location-uri hosted ^ --type AWS.AppConfig.FeatureFlags
    PowerShell
    New-APPCConfigurationProfile ` -Name A_name_for_the_configuration_profile ` -ApplicationId The_application_ID ` -LocationUri hosted ` -Type AWS.AppConfig.FeatureFlags
  3. Create your feature flag configuration data. Your data must be in a JSON format and conform to the AWS.AppConfig.FeatureFlags JSON schema. For more information about the schema, see Type reference for AWS.AppConfig.FeatureFlags.

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

    Linux
    aws appconfig create-hosted-configuration-version \ --application-id The_application_ID \ --configuration-profile-id The_configuration_profile_id \ --content-type "application/json" \ --content file://path/to/feature_flag_configuration_data \ file_name_for_system_to_store_configuration_data
    Windows
    aws appconfig create-hosted-configuration-version ^ --application-id The_application_ID ^ --configuration-profile-id The_configuration_profile_id ^ --content-type "application/json" ^ --content file://path/to/feature_flag_configuration_data ^ file_name_for_system_to_store_configuration_data
    PowerShell
    New-APPCHostedConfigurationVersion ` -ApplicationId The_application_ID ` -ConfigurationProfileId The_configuration_profile_id ` -ContentType "application/json" ` -Content file://path/to/feature_flag_configuration_data ` file_name_for_system_to_store_configuration_data

    Here's a Linux sample command.

    aws appconfig create-hosted-configuration-version \ --application-id 1a2b3cTestApp \ --configuration-profile-id 4d5e6fTestConfigProfile \ --content-type "application/json" \ --content Base64Content

    The content parameter uses the following base64 encoded data.

    { "flags": { "flagkey": { "name": "WinterSpecialBanner" } }, "values": { "flagkey": { "enabled": true } }, "version": "1" }

    The system returns information like the following.

    Linux
    {
       "ApplicationId"          : "1a2b3cTestApp",
       "ConfigurationProfileId" : "4d5e6fTestConfigProfile",
       "VersionNumber"          : "1",
       "ContentType"            : "application/json"
    }
    Windows
    {
       "ApplicationId"          : "1a2b3cTestApp",
       "ConfigurationProfileId" : "4d5e6fTestConfigProfile",
       "VersionNumber"          : "1",
       "ContentType"            : "application/json"
    }
    PowerShell
    ApplicationId          : 1a2b3cTestApp
    ConfigurationProfileId : 4d5e6fTestConfigProfile
    VersionNumber          : 1
    ContentType            : application/json

    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.

Type reference for AWS.AppConfig.FeatureFlags

Use the AWS.AppConfig.FeatureFlags JSON schema as a reference to create your feature flag configuration data.

{ "$schema": "http://json-schema.org/draft-07/schema#", "definitions": { "flagSetDefinition": { "type": "object", "properties": { "version": { "$ref": "#/definitions/flagSchemaVersions" }, "flags": { "$ref": "#/definitions/flagDefinitions" }, "values": { "$ref": "#/definitions/flagValues" } }, "required": ["version", "flags"], "additionalProperties": false }, "flagDefinitions": { "type": "object", "patternProperties": { "^[a-z][a-zA-Z\\d-]{0,63}$": { "$ref": "#/definitions/flagDefinition" } }, "maxProperties": 100, "additionalProperties": false }, "flagDefinition": { "type": "object", "properties": { "name": { "$ref": "#/definitions/customerDefinedName" }, "description": { "$ref": "#/definitions/customerDefinedDescription" }, "_createdAt": { "type": "string" }, "_updatedAt": { "type": "string" }, "_deprecation": { "type": "object", "properties": { "status": { "type": "string", "enum": ["planned"] } }, "additionalProperties": false }, "attributes": { "$ref": "#/definitions/attributeDefinitions" } }, "additionalProperties": false }, "attributeDefinitions": { "type": "object", "patternProperties": { "^[a-z][a-zA-Z\\d-_]{0,63}$": { "$ref": "#/definitions/attributeDefinition" } }, "maxProperties": 25, "additionalProperties": false }, "attributeDefinition": { "type": "object", "properties": { "description": { "$ref": "#/definitions/customerDefinedDescription" }, "constraints": { "oneOf": [ { "$ref": "#/definitions/numberConstraints" }, { "$ref": "#/definitions/stringConstraints" }, { "$ref": "#/definitions/arrayConstraints" }, { "$ref": "#/definitions/boolConstraints" } ] } }, "additionalProperties": false }, "flagValues": { "type": "object", "patternProperties": { "^[a-z][a-zA-Z\\d-_]{0,63}$": { "$ref": "#/definitions/flagValue" } }, "maxProperties": 100, "additionalProperties": false }, "flagValue": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "_createdAt": { "type": "string" }, "_updatedAt": { "type": "string" } }, "patternProperties": { "^[a-z][a-zA-Z\\d-_]{0,63}$": { "$ref": "#/definitions/attributeValue", "maxProperties": 25 } }, "required": ["enabled"], "additionalProperties": false }, "attributeValue": { "oneOf": [ { "type": "string", "maxLength": 1024 }, { "type": "number" }, { "type": "boolean" }, { "type": "array", "oneOf": [ { "items": { "type": "string", "maxLength": 1024 } }, { "items": { "type": "number" } } ] } ], "additionalProperties": false }, "stringConstraints": { "type": "object", "properties": { "type": { "type": "string", "enum": ["string"] }, "required": { "type": "boolean" }, "pattern": { "type": "string", "maxLength": 1024 }, "enum": { "type": "array", "maxLength": 100, "items": { "oneOf": [ { "type": "string", "maxLength": 1024 }, { "type": "integer" } ] } } }, "required": ["type"], "not": { "required": ["pattern", "enum"] }, "additionalProperties": false }, "numberConstraints": { "type": "object", "properties": { "type": { "type": "string", "enum": ["number"] }, "required": { "type": "boolean" }, "minimum": { "type": "integer" }, "maximum": { "type": "integer" } }, "required": ["type"], "additionalProperties": false }, "arrayConstraints": { "type": "object", "properties": { "type": { "type": "string", "enum": ["array"] }, "required": { "type": "boolean" }, "elements": { "$ref": "#/definitions/elementConstraints" } }, "required": ["type"], "additionalProperties": false }, "boolConstraints": { "type": "object", "properties": { "type": { "type": "string", "enum": ["boolean"] }, "required": { "type": "boolean" } }, "required": ["type"], "additionalProperties": false }, "elementConstraints": { "oneOf": [ { "$ref": "#/definitions/numberConstraints" }, { "$ref": "#/definitions/stringConstraints" } ] }, "customerDefinedName": { "type": "string", "pattern": "^[^\\n]{1,64}$" }, "customerDefinedDescription": { "type": "string", "maxLength": 1024 }, "flagSchemaVersions": { "type": "string", "enum": ["1"] } }, "type": "object", "$ref": "#/definitions/flagSetDefinition", "additionalProperties": false }
Important

To retrieve feature flag configuration data, your application must call the GetLatestConfiguration API. You can't retrieve feature flag configuration data by calling GetConfiguration, which is deprecated. For more information, see GetLatestConfiguration in the AWS AppConfig API Reference.

When your application calls GetLatestConfiguration and receives a newly deployed configuration, the information that defines your feature flags and attributes is removed. The simplified JSON contains a map of keys that match each of the flag keys you specified. The simplified JSON also contains mapped values of true or false for the enabled attribute. If a flag sets enabled to true, any attributes of the flag will be present as well. The following JSON schema describes the format of the JSON output.

{ "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "patternProperties": { "^[a-z][a-zA-Z\\d-_]{0,63}$": { "$ref": "#/definitions/attributeValuesMap" } }, "maxProperties": 100, "additionalProperties": false, "definitions": { "attributeValuesMap": { "type": "object", "properties": { "enabled": { "type": "boolean" } }, "required": ["enabled"], "patternProperties": { "^[a-z][a-zA-Z\\d-_]{0,63}$": { "$ref": "#/definitions/attributeValue" } }, "maxProperties": 25, "additionalProperties": false }, "attributeValue": { "oneOf": [ { "type": "string","maxLength": 1024 }, { "type": "number" }, { "type": "boolean" }, { "type": "array", "oneOf": [ { "items": { "oneOf": [ { "type": "string", "maxLength": 1024 } ] } }, { "items": { "oneOf": [ { "type": "number" } ] } } ] } ], "additionalProperties": false } } }