# Creating a free form configuration profile in AWS AppConfig Creating a free form configuration profile *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 AWS 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 AWS AppConfig hosted configuration store or any of the following AWS services and Systems Manager tools: **** | Location | Supported file types | | --- | --- | | AWS AppConfig hosted configuration store | YAML, JSON, and text if added using the AWS Management Console. Any file type if added using the AWS AppConfig [CreateHostedConfigurationVersion](https://docs.aws.amazon.com/appconfig/2019-10-09/APIReference/API_CreateHostedConfigurationVersion.html) API action. | | [Amazon Simple Storage Service (Amazon S3)](https://docs.aws.amazon.com/AmazonS3/latest/userguide/Welcome.html) | Any | | [AWS CodePipeline](https://docs.aws.amazon.com/codepipeline/latest/userguide/welcome.html) | Pipeline (as defined by the service) | | [AWS Secrets Manager](https://docs.aws.amazon.com/secretsmanager/latest/userguide/intro.html) | Secret (as defined by the service) | | [AWS Systems Manager Parameter Store](https://docs.aws.amazon.com/systems-manager/latest/userguide/systems-manager-parameter-store.html) | Standard and secure string parameters (as defined by Parameter Store) | | [AWS Systems Manager document store (SSM documents)](https://docs.aws.amazon.com/systems-manager/latest/userguide/documents.html) | YAML, JSON, text | A configuration profile can also include optional validators to ensure your configuration data is syntactically and semantically correct. AWS 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 AWS AppConfig hosted configuration store as it offers the most features and enhancements. For freeform configurations stored in the AWS 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. **Topics** + [ # Understanding validators ](appconfig-creating-configuration-and-profile-validators.md) + [ # Understanding configuration store quotas and limitations ](appconfig-creating-configuration-and-profile-quotas.md) + [ # Understanding the AWS AppConfig hosted configuration store ](appconfig-creating-configuration-and-profile-about-hosted-store.md) + [ # Understanding configurations stored in Amazon S3 ](appconfig-creating-configuration-and-profile-S3-source.md) + [ # Creating an AWS AppConfig freeform configuration profile (console) ](appconfig-creating-free-form-configuration-and-profile-create-console.md) + [ # Creating an AWS AppConfig freeform configuration profile (command line) ](appconfig-creating-free-form-configuration-and-profile-create-commandline.md) # 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. AWS AppConfig supports the following types of validators: + **AWS Lambda functions**: Supported for feature flags and free form configurations. + **JSON Schema**: Supported for free form configurations. (AWS AppConfig automatically validates feature flags against a JSON Schema.) **Topics** + [ ## AWS Lambda function validators ](#appconfig-creating-configuration-and-profile-validators-lambda) + [ ## JSON Schema validators ](#appconfig-creating-configuration-and-profile-validators-json-schema) ## AWS Lambda function validators Lambda function validators must be configured with the following event schema. AWS 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" } ``` AWS 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 AWS Lambda](https://docs.aws.amazon.com/lambda/latest/dg/retries-on-errors.html) in the *AWS 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"; } } ``` AWS 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 AWS Services](https://docs.aws.amazon.com/lambda/latest/dg/access-control-resource-based.html#permissions-resource-serviceinvoke). AWS 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, AWS 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 AWS Lambda. A configuration in an SSM document uses the `ApplicationConfiguration` document type. The corresponding JSON Schema, uses the `ApplicationConfigurationSchema` document type. AWS 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. # Understanding configuration store quotas and limitations Configuration stores supported by AWS AppConfig have the following quotas and limitations. **** | | AWS AppConfig hosted configuration store | Amazon S3 | Systems Manager Parameter Store | AWS Secrets Manager | Systems Manager Document store | AWS CodePipeline | | --- | --- | --- | --- | --- | --- | --- | | **Configuration size limit** | 2 MB default, 4 MB maximum | 2 MB Enforced by AWS AppConfig, not S3 | 4 KB (free tier) / 8 KB (advanced parameters) | 64 KB | 64 KB | 2 MBEnforced by AWS AppConfig, not CodePipeline | | **Resource storage limit** | 1 GB | Unlimited | 10,000 parameters (free tier) / 100,000 parameters (advanced parameters) | 500,000 | 500 documents | Limited by the number of configuration profiles per application (100 profiles per application) | | **Server-side encryption** | Yes | [SSE-S3](https://docs.aws.amazon.com/AmazonS3/latest/userguide/serv-side-encryption.html), [SSE-KMS](https://docs.aws.amazon.com/AmazonS3/latest/userguide/UsingKMSEncryption.html) | Yes | Yes | No | Yes | | **CloudFormation support** | Yes | Not for creating or updating data | Yes | Yes | No | Yes | | **Pricing** | Free | See [Amazon S3 pricing](https://aws.amazon.com//s3/pricing/) | See [AWS Systems Manager pricing](https://aws.amazon.com//systems-manager/pricing/) | See [AWS Secrets Manager pricing](https://aws.amazon.com//secrets-manager/pricing/) | Free | See [AWS CodePipeline pricing](https://aws.amazon.com//codepipeline/pricing/) | # Understanding the AWS AppConfig hosted configuration store AWS AppConfig includes an internal or hosted configuration store. Configurations must be 2 MB or smaller. The AWS AppConfig hosted configuration store provides the following benefits over other configuration store options. + You don't need to set up and configure other services such as Amazon Simple Storage Service (Amazon S3) or Parameter Store. + You don't need to configure AWS Identity and Access Management (IAM) permissions to use the configuration store. + You can store configurations in YAML, JSON, or as text documents. + There is no cost to use the store. + You can create a configuration and add it to the store when you create a configuration profile. # 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 AWS Identity and Access Management (IAM) role that gives AWS AppConfig permission to get the object. Before you create a configuration profile for an Amazon S3 object, be aware of the following restrictions. **** | Restriction | Details | | --- | --- | | Size | Configurations stored as S3 objects can be a maximum of 1 MB in size. | | Object encryption | A configuration profile can target SSE-S3 and SSE-KMS encrypted objects. | | Storage classes | AWS AppConfig supports the following S3 storage classes: `STANDARD`, `INTELLIGENT_TIERING`, `REDUCED_REDUNDANCY`, `STANDARD_IA`, and `ONEZONE_IA`. The following classes are not supported: All S3 Glacier classes (`GLACIER` and `DEEP_ARCHIVE`). | | Versioning | AWS AppConfig requires that the S3 object use versioning. | ## 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 AWS AppConfig permission to get the object. The role must include the following permissions. Permissions to access the S3 object + s3:GetObject + s3:GetObjectVersion Permissions to list S3 buckets s3:ListAllMyBuckets Permissions to access the S3 bucket where the object is stored + s3:GetBucketLocation + s3:GetBucketVersioning + s3:ListBucket + s3:ListBucketVersions Complete the following procedure to create a role that enables AWS 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 AWS AppConfig to get a configuration stored in an S3 object. **To create an IAM policy for accessing an S3 object** 1. Open the IAM console at [https://console.aws.amazon.com/iam/](https://console.aws.amazon.com/iam/). 1. In the navigation pane, choose **Policies**, and then choose **Create policy**. 1. On the **Create policy** page, choose the **JSON** tab. 1. Update the following sample policy with information about your S3 bucket and configuration object. Then paste the policy into the text field on the **JSON** tab. Replace the *placeholder values* with your own information. ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "s3:GetObject", "s3:GetObjectVersion" ], "Resource": "arn:aws:s3:::amzn-s3-demo-bucket/my-configurations/my-configuration.json" }, { "Effect": "Allow", "Action": [ "s3:GetBucketLocation", "s3:GetBucketVersioning", "s3:ListBucketVersions", "s3:ListBucket" ], "Resource": [ "arn:aws:s3:::amzn-s3-demo-bucket" ] }, { "Effect": "Allow", "Action": "s3:ListAllMyBuckets", "Resource": "*" } ] } ``` ------ 1. Choose **Review policy**. 1. On the **Review policy** page, type a name in the **Name** box, and then type a description. 1. Choose **Create policy**. The system returns you to the **Roles** page. **Creating the IAM Role for Accessing an S3 Object** Use the following procedure to create an IAM role that enables AWS AppConfig to get a configuration stored in an S3 object. **To create an IAM role for accessing an Amazon S3 object** 1. Open the IAM console at [https://console.aws.amazon.com/iam/](https://console.aws.amazon.com/iam/). 1. In the navigation pane, choose **Roles**, and then choose **Create role**. 1. On the **Select type of trusted entity** section, choose **AWS service**. 1. In the **Choose a use case** section, under **Common use cases**, choose **EC2**, and then choose **Next: Permissions**. 1. On the **Attach permissions policy** page, in the search box, enter the name of the policy you created in the previous procedure. 1. Choose the policy and then choose **Next: Tags**. 1. On the **Add tags (optional)** page, enter a key and an optional value, and then choose **Next: Review**. 1. On the **Review** page, type a name in the **Role name** field, and then type a description. 1. Choose **Create role**. The system returns you to the **Roles** page. 1. On the **Roles** page, choose the role you just created to open the **Summary** page. Note the **Role Name** and **Role ARN**. You will specify the role ARN when you create the configuration profile later in this topic. **Creating a Trust Relationship** Use the following procedure to configure the role you just created to trust AWS AppConfig. **To add a trust relationship** 1. In the **Summary** page for the role you just created, choose the **Trust Relationships** tab, and then choose **Edit Trust Relationship**. 1. Delete `"ec2.amazonaws.com"` and add `"appconfig.amazonaws.com"`, as shown in the following example. ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": { "Service": "appconfig.amazonaws.com" }, "Action": "sts:AssumeRole" } ] } ``` ------ 1. Choose **Update Trust Policy**. # Creating an AWS AppConfig freeform configuration profile (console) Use the following procedure to create an AWS AppConfig freeform configuration profile and (optionally) a freeform-configuration by using the AWS Systems Manager console. **To create a freeform configuration profile** 1. Open the AWS Systems Manager console at [https://console.aws.amazon.com/systems-manager/appconfig/](https://console.aws.amazon.com/systems-manager/appconfig/). 1. In the navigation pane, choose **Applications**, and then choose an application you created in [Creating a namespace for your application in AWS AppConfig](appconfig-creating-namespace.md). 1. Choose the **Configuration profiles and feature flags** tab, and then choose **Create configuration**. 1. In the **Configuration options** section, choose **Freeform configuration**. 1. For **Configuration profile name**, enter a name for the configuration profile. 1. (Optional) Expand **Description** and enter a description. 1. (Optional) Expand **Additional options** and complete the following, as necessary. 1. In the **Associate extensions** section, choose an extension from the list. 1. In the **Tags** section, choose **Add new tag**, and then specify a key and optional value. 1. Choose **Next**. 1. On the **Specify configuration data** page, in the **Configuration definition** section, choose an option. 1. Complete the fields for the option you selected, as described in the following table. **** [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/appconfig/latest/userguide/appconfig-creating-free-form-configuration-and-profile-create-console.html) 1. In the **Service role** section, choose **New service role** to have AWS AppConfig create the IAM role that provides access to the configuration data. AWS AppConfig automatically populates the **Role name** field based on the name you entered earlier. Or, choose **Existing service role**. Choose the role by using the **Role ARN** list. 1. Optionally, on the **Add validators** page, choose either **JSON Schema** or **AWS Lambda**. If you choose **JSON Schema**, enter the JSON Schema in the field. If you choose **AWS Lambda**, choose the function Amazon Resource Name (ARN) and the version from the list. **Important** 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 AWS Lambda. 1. Choose **Next**. 1. On the **Review and save** page, choose **Save and continue to deploy**. **Important** If you created a configuration profile for AWS CodePipeline, then you must create a pipeline in CodePipeline that specifies AWS AppConfig as the *deploy provider*. You don't need to perform [Deploying feature flags and configuration data in AWS AppConfig](deploying-feature-flags.md). However, you must configure a client to receive application configuration updates as described in [Retrieving configuration data without AWS AppConfig Agent](about-data-plane.md). For information about creating a pipeline that specifies AWS AppConfig as the deploy provider, see [Tutorial: Create a Pipeline that Uses AWS AppConfig as a Deployment Provider](https://docs.aws.amazon.com/codepipeline/latest/userguide/tutorials-AppConfig.html) in the *AWS CodePipeline User Guide*. Proceed to [Deploying feature flags and configuration data in AWS AppConfig](deploying-feature-flags.md). # Creating an AWS AppConfig freeform configuration profile (command line) The following procedure describes how to use the AWS CLI (on Linux or Windows) or AWS Tools for PowerShell to create an AWS AppConfig freeform configuration profile. If you prefer, you can use AWS CloudShell to run the commands listed below. For more information, see [What is AWS CloudShell?](https://docs.aws.amazon.com//cloudshell/latest/userguide/welcome.html) in the *AWS CloudShell User Guide*. **Note** For freeform configurations hosted in the AWS AppConfig hosted configuration store, you specify `hosted` for the location URI. **To create a configuration profile by using the AWS CLI** 1. Open the AWS CLI. 1. Run the following command to create a freeform configuration profile. ------ #### [ Linux ] ``` aws appconfig create-configuration-profile \ --application-id APPLICATION_ID \ --name NAME \ --description CONFIGURATION_PROFILE_DESCRIPTION \ --location-uri CONFIGURATION_URI or hosted \ --retrieval-role-arn IAM_ROLE_ARN \ --tags TAGS \ --validators "Content=SCHEMA_CONTENT or LAMBDA_FUNCTION_ARN,Type=JSON_SCHEMA or LAMBDA" ``` ------ #### [ Windows ] ``` aws appconfig create-configuration-profile ^ --application-id APPLICATION_ID ^ --name NAME ^ --description CONFIGURATION_PROFILE_DESCRIPTION ^ --location-uri CONFIGURATION_URI or hosted ^ --retrieval-role-arn IAM_ROLE_ARN ^ --tags TAGS ^ --validators "Content=SCHEMA_CONTENT or LAMBDA_FUNCTION_ARN,Type=JSON_SCHEMA or LAMBDA" ``` ------ #### [ PowerShell ] ``` New-APPCConfigurationProfile ` -Name NAME ` -ApplicationId APPLICATION_ID ` -Description CONFIGURATION_PROFILE_DESCRIPTION ` -LocationUri CONFIGURATION_URI or hosted ` -RetrievalRoleArn IAM_ROLE_ARN ` -Tag TAGS ` -Validators "Content=SCHEMA_CONTENT or LAMBDA_FUNCTION_ARN,Type=JSON_SCHEMA or LAMBDA" ``` ------ **Important** Note the following important information. If you created a configuration profile for AWS CodePipeline, then you must create a pipeline in CodePipeline that specifies AWS AppConfig as the *deploy provider*. You don't need to perform [Deploying feature flags and configuration data in AWS AppConfig](deploying-feature-flags.md). However, you must configure a client to receive application configuration updates as described in [Retrieving configuration data without AWS AppConfig Agent](about-data-plane.md). For information about creating a pipeline that specifies AWS AppConfig as the deploy provider, see [Tutorial: Create a Pipeline that Uses AWS AppConfig as a Deployment Provider](https://docs.aws.amazon.com/codepipeline/latest/userguide/tutorials-AppConfig.html) in the *AWS CodePipeline User Guide*. If you created a configuration in the AWS AppConfig hosted configuration store, you can create new versions of the configuration by using the [CreateHostedConfigurationVersion](https://docs.aws.amazon.com//appconfig/2019-10-09/APIReference/API_CreateHostedConfigurationVersion.html) API operations. To view AWS CLI details and sample commands for this API operation, see [create-hosted-configuration-version](https://docs.aws.amazon.com/cli/latest/reference/appconfig/create-hosted-configuration-version.html) in the *AWS CLI Command Reference*. Proceed to [Deploying feature flags and configuration data in AWS AppConfig](deploying-feature-flags.md).