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

Configuration data is a collection of settings that influence the behavior of your application. A configuration profile includes, among other things, a URI that enables Amazon AppConfig to locate your configuration data in its stored location and a configure type. Amazon AppConfig supports two types of configuration profiles: feature flags and freeform configurations. A feature flag configuration stores data in the Amazon AppConfig hosted configuration store and the URI is simply hosted. A freeform configuration can store data in the Amazon AppConfig hosted configuration store, various Systems Manager capabilities, or an Amazon service that integrates with Amazon AppConfig. For more information, see 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.

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