Creating a feature flag configuration profile in Amazon AppConfig - Amazon AppConfig
Creating a feature flag configuration profile (console)Creating a feature flag and a feature flag configuration profile (command line) Type reference for AWS.AppConfig.FeatureFlags
Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

Creating a feature flag configuration profile in Amazon 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. Amazon AppConfig stores feature flag configurations in the Amazon 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 Amazon AppConfig hosted configuration store, see About the Amazon AppConfig hosted configuration store section.

Before you begin

In the following procedure, in the optional Encryption section, you can choose an Amazon Key Management Service (Amazon KMS) key. This customer managed key enables you to encrypt new configuration data versions in the Amazon AppConfig hosted configuration store. For more information about this key, see Amazon AppConfig supports customer manager keys in Security in Amazon 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 Amazon AppConfig workflow of creating or deploying a configuration. For more information, see About Amazon 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. Amazon 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 Amazon AppConfig feature flag configuration profile by using the Amazon AppConfig console.

To create a configuration profile

  1. Open the Amazon Systems Manager console at https://console.amazonaws.cn/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 Amazon 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 Amazon Key Management Service (Amazon 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 Amazon 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 Amazon 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 Amazon AppConfig.

Creating a feature flag and a feature flag configuration profile (command line)

The following procedure describes how to use the Amazon Command Line Interface (on Linux or Windows) or Tools for Windows PowerShell to create an Amazon AppConfig feature flag configuration profile. If you prefer, you can use Amazon CloudShell to run the commands listed below. For more information, see What is Amazon CloudShell? in the Amazon CloudShell User Guide.

To create a feature flags configuration step by step

  1. Open the Amazon 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 Amazon 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 Amazon AppConfig generated metadata.

    Note

    When you create the hosted configuration version, Amazon AppConfig verifies that your data conforms to the AWS.AppConfig.FeatureFlags JSON schema. Amazon 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 Amazon 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
    }
  }
}