Creating a configuration profile in Amazon AppConfig - Amazon AppConfig
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 configuration profile in Amazon AppConfig

A configuration profile includes, among other things, a URI that enables Amazon AppConfig to locate your configuration data in its stored location and a profile type. Amazon AppConfig supports two configuration profile types: feature flags and freeform configurations. Feature flag configuration profiles store their data in the Amazon AppConfig hosted configuration store and the URI is simply hosted. For freeform configuration profiles, you can store your data in the Amazon AppConfig hosted configuration store or another Systems Manager capability or Amazon service that integrates with Amazon AppConfig, as described in Creating a free form configuration profile in Amazon AppConfig.

A configuration profile can also include optional validators to ensure your configuration data is syntactically and semantically correct. Amazon AppConfig performs a check using the validators when you start a deployment. If any errors are detected, the deployment stops before making any changes to the targets of the configuration.

Note

If possible, we recommend hosting your configuration data in the Amazon AppConfig hosted configuration store as it offers the most features and enhancements.

About validators

When you create a configuration profile, you have the option to specify up to two validators. A validator ensures that your configuration data is syntactically and semantically correct. If you plan to use a validator, you must create it before you create the configuration profile. Amazon AppConfig supports the following types of validators:

  • Amazon Lambda functions: Supported for feature flags and free form configurations.

  • JSON Schema: Supported for free form configurations. (Amazon AppConfig automatically validates feature flags against a JSON Schema.)

Amazon Lambda function validators

Lambda function validators must be configured with the following event schema. Amazon AppConfig uses this schema to invoke the Lambda function. The content is a base64-encoded string, and the URI is a string.

{ "applicationId": "The application ID of the configuration profile being validated", "configurationProfileId": "The ID of the configuration profile being validated", "configurationVersion": "The version of the configuration profile being validated", "content": "Base64EncodedByteString", "uri": "The configuration uri" }

Amazon AppConfig verifies that the Lambda X-Amz-Function-Error header is set in the response. Lambda sets this header if the function throws an exception. For more information about X-Amz-Function-Error, see Error Handling and Automatic Retries in Amazon Lambda in the Amazon Lambda Developer Guide.

Here is a simple example of a Lambda response code for a successful validation.

import json def handler(event, context): #Add your validation logic here print("We passed!")

Here is a simple example of a Lambda response code for an unsuccessful validation.

def handler(event, context): #Add your validation logic here raise Exception("Failure!")

Here is another example that validates only if the configuration parameter is a prime number.

function isPrime(value) { if (value < 2) { return false; } for (i = 2; i < value; i++) { if (value % i === 0) { return false; } } return true; } exports.handler = async function(event, context) { console.log('EVENT: ' + JSON.stringify(event, null, 2)); const input = parseInt(Buffer.from(event.content, 'base64').toString('ascii')); const prime = isPrime(input); console.log('RESULT: ' + input + (prime ? ' is' : ' is not') + ' prime'); if (!prime) { throw input + "is not prime"; } }

Amazon AppConfig calls your validation Lambda when calling the StartDeployment and ValidateConfigurationActivity API operations. You must provide appconfig.amazonaws.com permissions to invoke your Lambda. For more information, see Granting Function Access to Amazon Services. Amazon AppConfig limits the validation Lambda run time to 15 seconds, including start-up latency.

JSON Schema validators

If you create a configuration in an SSM document, then you must specify or create a JSON Schema for that configuration. A JSON Schema defines the allowable properties for each application configuration setting. The JSON Schema functions like a set of rules to ensure that new or updated configuration settings conform to the best practices required by your application. Here is an example.

{ "$schema": "http://json-schema.org/draft-04/schema#", "title": "$id$", "description": "BasicFeatureToggle-1", "type": "object", "additionalProperties": false, "patternProperties": { "[^\\s]+$": { "type": "boolean" } }, "minProperties": 1 }

When you create a configuration from an SSM document, the system automatically verifies that the configuration conforms to the schema requirements. If it doesn't, Amazon AppConfig returns a validation error.

Important

Note the following important information about JSON Schema validators:

  • Configuration data stored in SSM documents must validate against an associated JSON Schema before you can add the configuration to the system. SSM parameters do not require a validation method, but we recommend that you create a validation check for new or updated SSM parameter configurations by using Amazon Lambda.

  • A configuration in an SSM document uses the ApplicationConfiguration document type. The corresponding JSON Schema, uses the ApplicationConfigurationSchema document type.

  • Amazon AppConfig supports JSON Schema version 4.X for inline schema. If your application configuration requires a different version of JSON Schema, then you must create a Lambda validator.