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 free form 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. With freeform configuration profiles, you can store your data in the Amazon AppConfig hosted configuration store or any of the following Amazon services and Systems Manager capabilities:

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.

For freeform configurations stored in the Amazon AppConfig hosted configuration store or SSM documents, you can create the freeform configuration by using the Systems Manager console at the time you create a configuration profile. The process is described later in this topic.

For freeform configurations stored in Parameter Store, Secrets Manager, or Amazon S3, you must create the parameter, secret, or object first and store it in the relevant configuration store. After you store the configuration data, use the procedure in this topic to create the configuration profile.

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

Understanding configuration store quotas and limitations

Configuration stores supported by Amazon AppConfig have the following quotas and limitations.

Understanding the Amazon AppConfig hosted configuration store

Amazon AppConfig includes an internal or hosted configuration store. Configurations must be 2 MB or smaller. The Amazon AppConfig hosted configuration store provides the following benefits over other configuration store options.

Understanding configurations stored in Amazon S3

You can store configurations in an Amazon Simple Storage Service (Amazon S3) bucket. When you create the configuration profile, you specify the URI to a single S3 object in a bucket. You also specify the Amazon Resource Name (ARN) of an Amazon Identity and Access Management (IAM) role that gives Amazon AppConfig permission to get the object. Before you create a configuration profile for an Amazon S3 object, be aware of the following restrictions.

Configuring permissions for a configuration stored as an Amazon S3 object

When you create a configuration profile for a configuration stored as an S3 object, you must specify an ARN for an IAM role that gives Amazon AppConfig permission to get the object. The role must include the following permissions.

Permissions to access the S3 object

Permissions to list S3 buckets

s3:ListAllMyBuckets

Permissions to access the S3 bucket where the object is stored

Complete the following procedure to create a role that enables Amazon AppConfig to get a configuration stored in an S3 object.

Creating the IAM Policy for Accessing an S3 Object

Use the following procedure to create an IAM policy that enables Amazon AppConfig to get a configuration stored in an S3 object.

Creating the IAM Role for Accessing an S3 Object

Use the following procedure to create an IAM role that enables Amazon AppConfig to get a configuration stored in an S3 object.

Creating a Trust Relationship

Use the following procedure to configure the role you just created to trust Amazon AppConfig.