AWS AppConfig - User Guide

AWS AppConfigUser Guide

AWS AppConfig User Guide

AWS AppConfig: User GuideCopyright © Amazon Web Services, Inc. and/or its affiliates. All rights reserved.

Amazon's trademarks and trade dress may not be used in connection with any product or service that is notAmazon's, in any manner that is likely to cause confusion among customers, or in any manner that disparages ordiscredits Amazon. All other trademarks not owned by Amazon are the property of their respective owners, who mayor may not be affiliated with, connected to, or sponsored by Amazon.


Table of ContentsWhat Is AWS AppConfig? .... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1

Simplify tasks with AWS AppConfig .... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1AWS AppConfig use cases .... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1Benefits of using AWS AppConfig .... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1Get started with AWS AppConfig . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2How AWS AppConfig works .... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2

Configure AWS AppConfig to work with your application .... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3Enable your application code to check for and retrieve configuration data .... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4Deploy a new or updated configuration .... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4

Pricing for AWS AppConfig .... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5AWS AppConfig quotas .... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

Getting started .... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6Install or upgrade AWS command line tools ... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6Configuring permissions for AWS AppConfig .... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7(Optional) Configuring permissions for rollback based on CloudWatch alarms .... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

Step 1: Create the permission policy for rollback based on CloudWatch alarms .... . . . . . . . . . . . . . . . . . . . . . . . 9Step 2: Create the IAM role for rollback based on CloudWatch alarms .... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10Step 3: Add a trust relationship .... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10

Working with AWS AppConfig .... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11Step 1: Creating an AWS AppConfig application .... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

Creating an AWS AppConfig application (console) ... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11Creating an AWS AppConfig application (commandline) ... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12

Step 2: Creating an environment .... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13Creating an AWS AppConfig environment (console) ... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13Creating an AWS AppConfig environment (commandline) ... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14

Step 3: Creating configuration profiles and feature flags .... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15Example configurations .... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16About the configuration profile IAM role .... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18About configurations stored in Amazon S3 .... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19About validators ... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21Creating a feature flag configuration profile .... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23Creating a freeform configuration profile .... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32

Step 4: Creating a deployment strategy .... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38Predefined deployment strategies .... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39Create a deployment strategy .... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40

Step 5: Deploying a configuration .... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43Deploy a configuration (console) ... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43Deploy a configuration (commandline) ... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44

Step 6: Retrieving the configuration .... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46Retrieving a configuration example .... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47

Services that integrate with AWS AppConfig .... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49AWS Lambda extensions .... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49

How it works .... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49Before you begin .... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51Supported runtimes .... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51Adding the AWS AppConfig Lambda extension .... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51Configuring the AWS AppConfig Lambda extension .... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52Retrieving one or more flags .... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54Available versions of the AWS AppConfig Lambda extension .... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55Using a container image to add the AWS AppConfig Lambda extension .... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63Integrating with OpenAPI ... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65

Atlassian Jira ... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67Configuring permissions .... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67Configuring integration .... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69

iii


Deleting integration .... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70AWS CodePipeline .... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70

How integration works .... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71Security ... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72Monitoring .... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73Document History .... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74AWS glossary .... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77

iv

AWS AppConfig User GuideSimplify tasks with AWS AppConfig

What Is AWS AppConfig?Use AWS AppConfig, a capability of AWS Systems Manager, to create, manage, and quickly deployapplication configurations. A configuration is a collection of settings that influence the behavior ofyour application. You can use AWS AppConfig with applications hosted on Amazon Elastic ComputeCloud (Amazon EC2) instances, AWS Lambda, containers, mobile applications, or IoT devices. To viewexamples of the types of configurations you can manage by using AWS AppConfig, see Exampleconfigurations (p. 16).

Simplify tasks with AWS AppConfigAWS AppConfig helps simplify the following tasks:

• Configure

Source your configurations from Amazon Simple Storage Service (Amazon S3), AWS AppConfig hostedconfigurations, Parameter Store, Systems Manager Document Store. Use AWS CodePipeline integrationto source your configurations from Bitbucket Pipelines, GitHub, and AWS CodeCommit.

• Validate

While deploying application configurations, a simple typo could cause an unexpected outage. Preventerrors in production systems using AWS AppConfig validators. AWS AppConfig validators provide asyntactic check using a JSON schema or a semantic check using an AWS Lambda function to ensurethat your configurations deploy as intended. Configuration deployments only proceed when theconfiguration data is valid.

• Deploy and monitor

Define deployment criteria and rate controls to determine how your targets retrieve the newconfiguration. Use AWS AppConfig deployment strategies to set deployment velocity, deploymenttime, and bake time. Monitor each deployment to proactively catch any errors using AWS AppConfigintegration with Amazon CloudWatch. If AWS AppConfig encounters an error, the system rolls back thedeployment to minimize impact on your application users.

AWS AppConfig use casesAWS AppConfig can help you in the following use cases:

• Application tuning – Introduce changes carefully to your application that can be tested withproduction traffic.

• Feature toggle – Turn on new features that require a timely deployment, such as a product launch orannouncement.

• Allow list – Allow premium subscribers to access paid content.• Operational issues – Reduce stress on your application when a dependency or other external factor

impacts the system.

Benefits of using AWS AppConfigAWS AppConfig offers the following benefits for your organization:

1

http://aws.amazon.com/systems-manager/features/appconfig/

AWS AppConfig User GuideGet started with AWS AppConfig

• Reduce errors in configuration changes

AWS AppConfig reduces application downtime by enabling you to create rules to validate yourconfiguration. Configurations that aren't valid can't be deployed. AWS AppConfig provides thefollowing two options for validating configurations:

• For syntactic validation, you can use a JSON schema. AWS AppConfig validates your configurationby using the JSON schema to ensure that configuration changes adhere to the applicationrequirements.

• For semantic validation, you can call an AWS Lambda function that runs your configuration beforeyou deploy it.

• Deploy changes across a set of targets quickly

AWS AppConfig simplifies the administration of applications at scale by deploying configurationchanges from a central location. AWS AppConfig supports configurations stored in Systems ManagerParameter Store, Systems Manager (SSM) documents, and Amazon S3. You can use AWS AppConfigwith applications hosted on EC2 instances, AWS Lambda, containers, mobile applications, or IoTdevices.

Targets don't need to be configured with the Systems Manager SSM Agent or the AWS Identity andAccess Management (IAM) instance profile required by other Systems Manager capabilities. This meansthat AWS AppConfig works with unmanaged instances.

• Update applications without interruptions

AWS AppConfig deploys configuration changes to your targets at runtime without a heavy-weightbuild process or taking your targets out of service.

• Control deployment of changes across your application

When deploying configuration changes to your targets, AWS AppConfig enables you to minimize riskby using a deployment strategy. You can use the rate controls of a deployment strategy to determinehow fast you want your application targets to retrieve a configuration change.

Get started with AWS AppConfigThe following resources can help you work directly with AWS AppConfig.

AWS AppConfig Overview (Video)

View more AWS videos on the Amazon Web Services YouTube Channel.

The following blogs can help you learn more about AWS AppConfig and its capabilities:

• Introduction to AWS AppConfig deployment – Learn about safe deployment of applicationconfiguration settings with AWS AppConfig.

• Automating feature release using AWS AppConfig deployment – Learn how to automate featurerelease using AWS AppConfig integration with AWS CodePipeline.

• Deploying application configuration to serverless workloads – Learn how to use an AWS AppConfigLambda extension to deploy application configuration to serverless workloads.

How AWS AppConfig worksAt a high level, there are three processes for working with AWS AppConfig:

2

http://youtu.be/ztIxMY3IIu0

https://www.youtube.com/user/AmazonWebServices

http://aws.amazon.com/blogs/aws/safe-deployment-of-application-configuration-settings-with-aws-appconfig/

http://aws.amazon.com/blogs/mt/automating-feature-release-using-aws-appconfig-integration-with-aws-codepipeline/

http://aws.amazon.com/blogs/aws/safe-deployment-of-application-configuration-settings-with-aws-appconfig/

AWS AppConfig User GuideConfigure AWS AppConfig to work with your application

1. Configure (p. 3) AWS AppConfig to work with your application.2. Enable (p. 4) your application code to periodically check for and retrieve configuration data from

AWS AppConfig.3. Deploy (p. 4) a new or updated configuration.

The following sections describe each step.

Configure AWS AppConfig to work with yourapplicationTo configure AWS AppConfig to work with your application, you set up three types of resources, whichare described in the following table.

Resource Details

Application In AWS AppConfig, an application is simplyan organizational construct like a folder. Thisorganizational construct has a relationship withsome unit of executable code. For example, youcould create an application called MyMobileAppto organize and manage configuration data for amobile application installed by your users.

Environment For each application, you define one ormore environments. An environment is alogical deployment group of AWS AppConfigapplications, such as applications in a Beta orProduction environment. You can also defineenvironments for application subcomponentssuch as the Web, Mobile, and Back-endcomponents for your application. You canconfigure Amazon CloudWatch alarms for eachenvironment. The system monitors alarmsduring a configuration deployment. If an alarm istriggered, the system rolls back the configuration.

Configuration profile A configuration profile enables AWS AppConfig toaccess your configuration in its stored location.You can store configurations in the followingformats and locations:

• YAML, JSON, or text documents in the AWSAppConfig hosted configuration store

• Objects in an Amazon S3 bucket• Documents in the Systems Manager document

store• Parameters in Parameter Store

A configuration profile can also include optionalvalidators to ensure your configuration datais syntactically and semantically correct. AWSAppConfig performs a check using the validatorswhen you start a deployment. If any errors are

3

AWS AppConfig User GuideEnable your application code to check

for and retrieve configuration data

Resource Details

detected, the deployment stops before makingany changes to the targets of the configuration.

Enable your application code to check for andretrieve configuration dataYour application retrieves configuration data by first establishing a configuration session using the AWSAppConfig Data StartConfigurationSession API action. Your session's client then makes periodiccalls to GetLatestConfiguration to check for and retrieve the latest data available.

When calling StartConfigurationSession, your code sends the following information:

• Identifiers (ID or name) of an AWS AppConfig application, environment, and configuration profile thatthe session tracks.

• (Optional) The minimum amount of time the session's client must wait between calls toGetLatestConfiguration.

In response, AWS AppConfig provides an InitialConfigurationToken to be given to the session'sclient and used the first time it calls GetLatestConfiguration for that session.

When calling GetLatestConfiguration, your client code sends the most recentConfigurationToken value it has and receives in response:

• NextPollConfigurationToken: the ConfigurationToken value to use on the next call toGetLatestConfiguration.

• NextPollIntervalInSeconds: the duration the client should wait before making its next call toGetLatestConfiguration. This duration may vary over the course of the session, so it should beused instead of the value sent on the StartConfigurationSession call.

• The configuration: the latest data intended for the session. This may be empty if the client already hasthe latest version of the configuration.

For more information and to view example AWS CLI commands that show how to retrievea configuration using the AWS AppConfig Data StartConfigurationSession andGetLatestConfiguration API actions, see Receiving the configuration.

Deploy a new or updated configurationAWS AppConfig enables you to deploy configurations in the manner that best suits the use case of yourapplications. You can deploy changes in seconds, or you can roll them out slowly to assess the impactof the changes. The AWS AppConfig resource that helps you control deployments is called a deploymentstrategy. A deployment strategy includes the following information:

• Total amount of time for a deployment to last. (DeploymentDurationInMinutes).• The percentage of targets to retrieve a deployed configuration during each interval. (GrowthFactor).• The amount of time AWS AppConfig monitors for alarms before considering the deployment to be

complete and no longer eligible for automatic rollback. (FinalBakeTimeInMinutes).

You can use built-in deployment strategies that cover common scenarios, or you can create your own.After you create or choose a deployment strategy, you start the deployment. Starting the deploymentcalls the StartDeployment API action. The call includes the IDs of an application, environment,

4

https://docs.aws.amazon.com/appconfig/latest/userguide/appconfig-retrieving-the-configuration.html

https://docs.aws.amazon.com/appconfig/2019-10-09/APIReference/API_DeploymentStrategy.html



https://docs.aws.amazon.com/appconfig/2019-10-09/APIReference/API_StartDeployment.html

AWS AppConfig User GuidePricing for AWS AppConfig

configuration profile, and (optionally) the configuration data version to deploy. The call also includes theID of the deployment strategy to use, which determines how the configuration data rolls out.

NoteFor information about AWS AppConfig language-specific SDKs, see AWS AppConfig SDKs.

Pricing for AWS AppConfigThere is a charge to use AWS AppConfig. For more information, see AWS Systems Manager Pricing.

AWS AppConfig quotasInformation about AWS AppConfig endpoints and service quotas along with other Systems Managerquotas is in the Amazon Web Services General Reference.

NoteFor information about quotas for services that store AWS AppConfig configurations, see Aboutconfiguration store quotas and limitations (p. 33).

5

https://docs.aws.amazon.com/appconfig/2019-10-09/APIReference/API_CreateApplication.html#API_CreateApplication_SeeAlso

https://aws.amazon.com/systems-manager/pricing/

https://docs.aws.amazon.com/general/latest/gr/appconfig.html

AWS AppConfig User GuideInstall or upgrade AWS command line tools

Getting Started with AWS AppConfigThe following topics describe important tasks for getting started with AWS AppConfig.

Topics• Install or upgrade AWS command line tools (p. 6)• Configuring permissions for AWS AppConfig (p. 7)• (Optional) Configuring permissions for rollback based on CloudWatch alarms (p. 9)

Install or upgrade AWS command line toolsThis topic is for users who have programmatic access to use AWS AppConfig (or any other AWS service),and who want to run AWS CLI or AWS Tools for Windows PowerShell commands from their localmachines.

NoteProgrammatic access and console access are different permissions that can be granted to a useraccount by an AWS account administrator. A user can be granted one or both access types. Forinformation, see Create non-Admin IAM users and groups for Systems Manager in the AWSSystems Manager User Guide.

For information about the AWS CLI, see the AWS Command Line Interface User Guide. For informationabout the AWS Tools for Windows PowerShell, see the AWS Tools for Windows PowerShell User Guide.

For information about all AWS AppConfig commands you can run using the AWS CLI, see the AWSAppConfig section of the AWS CLI Command Reference. For information about all AWS AppConfigcommands you can run using the AWS Tools for PowerShell, see the AWS AppConfig section of the AWSTools for PowerShell Cmdlet Reference.

AWS CLI

To install or upgrade and then configure the AWS CLI

1. Follow the instructions in Installing the AWS Command Line Interface in the AWS Command LineInterface User Guide to install or upgrade the AWS CLI on your local machine.

TipThe AWS CLI is frequently updated with new functionality. Upgrade (reinstall) the CLIperiodically to ensure that you have access to all the latest functionality.

2. To configure the AWS CLI, see Configuring the AWS Command Line Interface in the AWSCommand Line Interface User Guide.

In this step, you specify credentials that an AWS administrator in your organization has givenyou, in the following format:

AWS Access Key ID: AKIAIOSFODNN7EXAMPLEAWS Secret Access Key: wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY

ImportantWhen you configure the AWS CLI, you are prompted to specify an AWS Region.Choose one of the supported Regions listed for Systems Manager in the AWS GeneralReference. If necessary, first verify with an administrator for your AWS account whichRegion you should choose.

6

https://docs.aws.amazon.com/systems-manager/latest/userguide/setup-create-iam-user.html

https://docs.aws.amazon.com/cli/latest/userguide/

https://docs.aws.amazon.com/powershell/latest/userguide/

https://docs.aws.amazon.com/cli/latest/reference/appconfig/index.html

https://docs.aws.amazon.com/cli/latest/reference/appconfig/index.html

https://docs.aws.amazon.com/powershell/latest/reference/items/AWS_AppConfig_cmdlets.html

https://docs.aws.amazon.com/powershell/latest/reference/items/AWS_AppConfig_cmdlets.html

https://docs.aws.amazon.com/cli/latest/userguide/installing.html

https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-getting-started.html

https://docs.aws.amazon.com/general/latest/gr/rande.html


AWS AppConfig User GuideConfiguring permissions for AWS AppConfig

For more information about access keys, see Managing Access Keys for IAM Users in the IAMUser Guide

3. To verify the installation or upgrade, run the following command from the AWS CLI:

aws appconfig help

If successful, this command displays a list of available AWS AppConfig commands.

AWS Tools for PowerShell

To install or upgrade and then configure the AWS Tools for Windows PowerShell

1. Follow the instructions in Setting up the AWS Tools for Windows PowerShell or AWS Tools forPowerShell Core in the AWS Tools for Windows PowerShell User Guide to install or upgrade AWSTools for PowerShell on your local machine.

TipAWS Tools for PowerShell is frequently updated with new functionality. Upgrade(reinstall) the AWS Tools for PowerShell periodically to ensure that you have access toall the latest functionality.

2. To configure AWS Tools for PowerShell, see Using AWS Credentials in the AWS Tools for WindowsPowerShell User Guide.

In this step, you specify credentials that an AWS administrator in your organization has givenyou, using the following command.

Set-AWSCredential `-AccessKey AKIAIOSFODNN7EXAMPLE `-SecretKey wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY `-StoreAs MyProfileName

ImportantWhen you configure AWS Tools for PowerShell, you can run Set-DefaultAWSRegionto specify an AWS Region. Choose one of the supported Regions listed for AWSAppConfig in the AWS General Reference. If necessary, first verify with an administratorfor your AWS account which Region you should choose.

For more information about access keys, see Managing Access Keys for IAM Users in the IAMUser Guide.

3. To verify the installation or upgrade, run the following command from AWS Tools forPowerShell.

Get-AWSCmdletName -Service AppConfig

If successful, this command displays a list of available AWS AppConfig cmdlets.

Configuring permissions for AWS AppConfigBy default, only AWS account adminstrators have access to AWS AppConfig. You can grant AWS Identityand Access Management (IAM) users, groups, and roles access to AWS AppConfig by specifying resources,actions, and condition context keys in an IAM permission policy that you assign to the user, group, orrole. For more information, see Actions, resources, and condition keys for AWS AppConfig in the ServiceAuthorization Reference.

7

https://docs.aws.amazon.com/IAM/latest/UserGuide/ManagingCredentials.html

https://docs.aws.amazon.com/powershell/latest/userguide/pstools-getting-set-up.html

https://docs.aws.amazon.com/powershell/latest/userguide/pstools-getting-set-up.html

https://docs.aws.amazon.com/powershell/latest/userguide/specifying-your-aws-credentials.html


https://docs.aws.amazon.com/IAM/latest/UserGuide/ManagingCredentials.html

https://docs.aws.amazon.com/service-authorization/latest/reference/list_awsappconfig.html#awsappconfig-policy-keys

AWS AppConfig User GuideConfiguring permissions for AWS AppConfig

ImportantSecurity is a shared responsibility between AWS and you. The shared responsibility modeldescribes this as security of the cloud and security in the cloud. To understand how to applythe shared responsibility model when using AWS AppConfig, see to Security in AWS SystemsManager in the AWS Systems Manager User Guide. AWS AppConfig is a capability of AWSSystems Manager.

We recommend that you create restrictive IAM permissions policies that grant users, groups, and rolesthe least privileges necessary to perform a desired action in AWS AppConfig.

For example, you can create a read-only IAM permissions policy that includes only the Get and List APIactions used by AWS AppConfig, like the following.

{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "ssm:GetDocument", "ssm:ListDocuments", "appconfig:GetLatestConfiguration", "appconfig:StartConfigurationSession", "appconfig:ListApplications", "appconfig:GetApplication", "appconfig:ListEnvironments", "appconfig:GetEnvironment", "appconfig:ListConfigurationProfiles", "appconfig:GetConfigurationProfile", "appconfig:ListDeploymentStrategies", "appconfig:GetDeploymentStrategy", "appconfig:GetConfiguration", "appconfig:ListDeployments", "appconfig:GetDeployment" ], "Resource": "*" } ]}

ImportantRestrict access to the StartDeployment and StopDeployment API actions to trusted users whounderstand the responsibilities and consequences of deploying a new configuration to yourtargets.

For more information about creating and editing IAM policies, see Creating IAM Policies in the IAM UserGuide. For information about how to assign this policy to an IAM group, see Attaching a Policy to an IAMGroup.

To configure an IAM user account with permission to use AWS AppConfig

1. Sign in to the AWS Management Console and open the IAM console at https://console.aws.amazon.com/iam/.

2. In the navigation pane, choose Users.3. In the list, choose a name.4. Choose the Permissions tab.5. On the right side of the page, under Permission policies, choose Add inline policy.6. Choose the JSON tab.

8

http://aws.amazon.com/compliance/shared-responsibility-model/

https://docs.aws.amazon.com/systems-manager/latest/userguide/security.html



https://docs.aws.amazon.com/appconfig/2019-10-09/APIReference/API_StopDeployment.html

https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_create.html

https://docs.aws.amazon.com/IAM/latest/UserGuide/id_groups_manage_attach-policy.html

https://docs.aws.amazon.com/IAM/latest/UserGuide/id_groups_manage_attach-policy.html

https://console.aws.amazon.com/iam/


AWS AppConfig User Guide(Optional) Configuring permissions forrollback based on CloudWatch alarms

7. Replace the default content with your custom permissions policy.8. Choose Review policy.9. On the Review policy page, for Name, enter a name for the inline policy. For example:

AWSAppConfig-<action>-Access.10. Choose Create policy.

(Optional) Configuring permissions for rollbackbased on CloudWatch alarms

You can configure AWS AppConfig to roll back to a previous version of a configuration in response toone or more Amazon CloudWatch alarms. When you configure a deployment to respond to CloudWatchalarms, you specify an AWS Identity and Access Management (IAM) role. AWS AppConfig requires thisrole so that it can monitor CloudWatch alarms.

NoteThe IAM role must belong to the current account. By default, AWS AppConfig can only monitoralarms owned by the current account. If you want to configure AWS AppConfig to roll backdeployments in response to metrics from a different account, you must configure cross accountalarms. For more information, see Cross-account cross-Region CloudWatch console in theAmazon CloudWatch User Guide.

Use the following procedures to create an IAM role that enables AWS AppConfig to rollback based onCloudWatch alarms. This section includes the following procedures.

1. Step 1: Create the permission policy for rollback based on CloudWatch alarms (p. 9)2. Step 2: Create the IAM role for rollback based on CloudWatch alarms (p. 10)3. Step 3: Add a trust relationship (p. 10)

Step 1: Create the permission policy for rollbackbased on CloudWatch alarmsUse the following procedure to create an IAM policy that gives AWS AppConfig permission to call theDescribeAlarms API action.

To create an IAM permission policy for rollback based on CloudWatch alarms

1. Open the IAM console at https://console.aws.amazon.com/iam/.2. In the navigation pane, choose Policies, and then choose Create policy.3. On the Create policy page, choose the JSON tab.4. Replace the default content on the JSON tab with the following permission policy, and then choose

Next: Tags.

{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "cloudwatch:DescribeAlarms" ], "Resource": "*"

9

https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/Cross-Account-Cross-Region.html


AWS AppConfig User GuideStep 2: Create the IAM role for

rollback based on CloudWatch alarms

} ] }

5. Enter tags for this role, and then choose Next: Review.6. On the Review page, enter SSMCloudWatchAlarmDiscoveryPolicy in the Name field.7. Choose Create policy. The system returns you to the Policies page.

Step 2: Create the IAM role for rollback based onCloudWatch alarmsUse the following procedure to create an IAM role and assign the policy you created in the previousprocedure to it.

To create an IAM role for rollback based on CloudWatch alarms

1. Open the IAM console at https://console.aws.amazon.com/iam/.2. In the navigation pane, choose Roles, and then choose Create role.3. Under Select type of trusted entity, choose AWS service.4. Immediately under Choose the service that will use this role, choose EC2: Allows EC2 instances to

call AWS services on your behalf, and then choose Next: Permissions.5. On the Attached permissions policy page, search for SSMCloudWatchAlarmDiscoveryPolicy.6. Choose this policy and then choose Next: Tags.7. Enter tags for this role, and then choose Next: Review.8. On the Create role page, enter SSMCloudWatchAlarmDiscoveryRole in the Role name field, and

then choose Create role.9. On the Roles page, choose the role you just created. The Summary page opens.

Step 3: Add a trust relationshipUse the following procedure to configure the role you just created to trust AWS AppConfig.

To add a trust relationship for AWS AppConfig

1. In the Summary page for the role you just created, choose the Trust Relationships tab, and thenchoose Edit Trust Relationship.

2. Edit the policy to include only "appconfig.amazonaws.com", as shown in the following example:

{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": { "Service": "appconfig.amazonaws.com" }, "Action": "sts:AssumeRole" } ]}

3. Choose Update Trust Policy.

10


AWS AppConfig User GuideStep 1: Creating an AWS AppConfig application

Working with AWS AppConfigThis section includes topics that describe how to use AWS AppConfig features to create and deploy aconfiguration to your hosts or targets. You can use AWS CloudFormation to create many of the AWSAppConfig artifacts described in this section. For more information, see AWS AppConfig resource typereference in the AWS CloudFormation User Guide.

Topics

• Step 1: Creating an AWS AppConfig application (p. 11)

• Step 2: Creating an environment (p. 13)

• Step 3: Creating configuration profiles and feature flags (p. 15)

• Step 4: Creating a deployment strategy (p. 38)

• Step 5: Deploying a configuration (p. 43)

• Step 6: Retrieving the configuration (p. 46)

Step 1: Creating an AWS AppConfig applicationIn AWS AppConfig, an application is simply an organizational construct like a folder. This organizationalconstruct has a relationship with some unit of executable code. For example, you could create anapplication called MyMobileApp to organize and manage configuration data for a mobile applicationinstalled by your users.

NoteYou can use AWS CloudFormation to create AWS AppConfig artifacts, including applications,environments, configuration profiles, deployments, deployment strategies, and hostedconfiguration versions. For more information, see AWS AppConfig resource type reference in theAWS CloudFormation User Guide.

Creating an AWS AppConfig application (console)Use the following procedure to create an AWS AppConfig application by using the AWS Systems Managerconsole.

To create an application

1. Open the AWS Systems Manager console at https://console.aws.amazon.com/systems-manager/appconfig/.

2. In the navigation pane choose AWS AppConfig.

3. On the Applications tab, choose Create application.

4. For Name, enter a name for the application.

5. For Description, enter information about the application.

6. In the Tags section, enter a key and an optional value. You can specify a maximum of 50 tags for aresource.

7. Choose Create application.

11

https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/AWS_AppConfig.html



https://console.aws.amazon.com/systems-manager/appconfig/


AWS AppConfig User GuideCreating an AWS AppConfig application (commandline)

AWS AppConfig creates the application and then displays the Environments tab. Proceed to Step 2:Creating an environment (p. 13). You can begin the procedure where it states, "On the Environmentstab..."

Creating an AWS AppConfig application(commandline)The following procedure describes how to use the AWS CLI (on Linux or Windows) or AWS Tools forPowerShell to create an AWS AppConfig application.

To create an application step by step

1. Install and configure the AWS CLI or the AWS Tools for PowerShell, if you have not already.

For information, see Install or upgrade AWS command line tools (p. 6).2. Run the following command to create an application.

Linux

aws appconfig create-application \ --name A_name_for_the_application \ --description A_description_of_the_application \ --tags User_defined_key_value_pair_metadata_for_the_application

Windows

aws appconfig create-application ^ --name A_name_for_the_application ^ --description A_description_of_the_application ^ --tags User_defined_key_value_pair_metadata_for_the_application

PowerShell

New-APPCApplication ` -Name Name_for_the_application ` -Description Description_of_the_application ` -Tag Hashtable_type_user_defined_key_value_pair_metadata_for_the_application

The system returns information like the following.

Linux

{ "Id": "Application ID", "Name": "Application name", "Description": "Description of the application"}

Windows

{ "Id": "Application ID", "Name": "Application name", "Description": "Description of the application"}

12

AWS AppConfig User GuideStep 2: Creating an environment

PowerShell

ContentLength : Runtime of the commandDescription : Description of the applicationHttpStatusCode : HTTP Status of the runtimeId : Application IDName : Application nameResponseMetadata : Runtime Metadata

Step 2: Creating an environmentFor each AWS AppConfig application, you define one or more environments. An environment is a logicaldeployment group of AppConfig targets, such as applications in a Beta or Production environment.You can also define environments for application subcomponents such as the Web, Mobile, andBack-end components for your application. You can configure Amazon CloudWatch alarms for eachenvironment. The system monitors alarms during a configuration deployment. If an alarm is triggered,the system rolls back the configuration.

Before You Begin

If you want to enable AWS AppConfig to roll back a configuration in response to a CloudWatch alarm,then you must configure an AWS Identity and Access Management (IAM) role with permissions to enableAWS AppConfig to respond to CloudWatch alarms. You choose this role in the following procedure.For more information, see (Optional) Configuring permissions for rollback based on CloudWatchalarms (p. 9).

Creating an AWS AppConfig environment (console)Use the following procedure to create an AWS AppConfig environment by using the AWS SystemsManager console.

To create an environment


2. In the navigation pane choose AWS AppConfig.3. On the Applications tab, choose the application you created in Step 1: Creating an AWS AppConfig

application (p. 11) and then choose View details.4. On the Environments tab, choose Create environment.5. For Name, enter a name for the environment.6. For Description, enter information about the environment.7. In the IAM role list, choose the IAM role with permission to roll back a configuration when an alarm

is triggered.8. In the CloudWatch alarms list, choose one or more alarms to monitor. AWS AppConfig rolls back

your configuration deployment if one of these alarms goes into an alarm state.9. In the Tags section, enter a key and an optional value. You can specify a maximum of 50 tags for a

resource.10. Choose Create environment.

AWS AppConfig creates the environment and then displays the Environment details page. Proceed toStep 3: Creating configuration profiles and feature flags (p. 15).

13



AWS AppConfig User GuideCreating an AWS AppConfig environment (commandline)

Creating an AWS AppConfig environment(commandline)The following procedure describes how to use the AWS CLI (on Linux or Windows) or AWS Tools forPowerShell to create an AWS AppConfig environment.

To create an environment step by step


For information, see Install or upgrade AWS command line tools (p. 6).2. Run the following command to create an environment.

Linux

aws appconfig create-environment \ --application-id The_application_ID \ --name A_name_for_the_environment \ --description A_description_of_the_environment \ --monitors "AlarmArn=ARN_of_the_Amazon_CloudWatch_alarm,AlarmArnRole=ARN_of_the_IAM role_for_AWS AppConfig_to_monitor_AlarmArn" \ --tags User_defined_key_value_pair_metadata_of_the_environment

Windows

aws appconfig create-environment ^ --application-id The_application_ID ^ --name A_name_for_the_environment ^ --description A_description_of_the_environment ^ --monitors "AlarmArn=ARN_of_the_Amazon_CloudWatch_alarm,AlarmArnRole=ARN_of_the_IAM role_for_AWS AppConfig_to_monitor_AlarmArn" ^ --tags User_defined_key_value_pair_metadata_of_the_environment

PowerShell

New-APPCEnvironment ` -Name Name_for_the_environment ` -ApplicationId The_application_ID -Description Description_of_the_environment ` -Monitors @{"AlarmArn=ARN_of_the_Amazon_CloudWatch_alarm,AlarmArnRole=ARN_of_the_IAM role_for_AWS AppConfig_to_monitor_AlarmArn"} ` -Tag Hashtable_type_user_defined_key_value_pair_metadata_of_the_environment


Linux

{ "ApplicationId": "The application ID", "Id": "The_environment ID", "Name": "Name of the environment", "State": "The state of the environment", "Description": "Description of the environment",

14

AWS AppConfig User GuideStep 3: Creating configuration profiles and feature flags

"Monitors": [ { "AlarmArn": "ARN of the Amazon CloudWatch alarm", "AlarmRoleArn": "ARN of the IAM role for AppConfig to monitor AlarmArn" } ] }

Windows

{ "ApplicationId": "The application ID", "Id": "The environment ID", "Name": "Name of the environment", "State": "The state of the environment" "Description": "Description of the environment", "Monitors": [ { "AlarmArn": "ARN of the Amazon CloudWatch alarm", "AlarmRoleArn": "ARN of the IAM role for AppConfig to monitor AlarmArn" } ] }

PowerShell

ApplicationId : The application IDContentLength : Runtime of the commandDescription : Description of the environmentHttpStatusCode : HTTP Status of the runtimeId : The environment IDMonitors : {ARN of the Amazon CloudWatch alarm, ARN of the IAM role for AppConfig to monitor AlarmArn}Name : Name of the environmentResponse Metadata : Runtime MetadataState : State of the environment

Step 3: Creating configuration profiles and featureflags

A configuration is a collection of settings that influence the behavior of your application. A configurationprofile enables AWS AppConfig to access your configuration. Configuration profiles include the followinginformation.

• The URI location where the configuration is stored.• The AWS Identity and Access Management (IAM) role that provides access to the configuration.• A validator for the configuration data. You can use either a JSON Schema or an AWS Lambda function

to validate your configuration profile. A configuration profile can have a maximum of two validators.

AWS AppConfig supports the following types of configuration profiles.

• Feature flag: Use a feature flag configuration to turn on new features that require a timelydeployment, such as a product launch or announcement.

• Freeform: Use a freeform configuration to carefully introduce changes to your application.

15

AWS AppConfig User GuideExample configurations

Contents

• Example configurations (p. 16)

• About the configuration profile IAM role (p. 18)

• About configurations stored in Amazon S3 (p. 19)

• About validators (p. 21)

• Creating a feature flag configuration profile (p. 23)

• Creating a freeform configuration profile (p. 32)

Example configurationsUse AWS AppConfig, a capability of AWS Systems Manager, to create, manage, and quickly deployapplication configurations. A configuration is a collection of settings that influence the behavior of yourapplication. Here are some examples.

Feature flag configuration

The following feature flag configuration enables or disables mobile payments and defaut payments on aper-region basis.

JSON

{ "allow_mobile_payments": { "enabled": false }, "default_payments_per_region": { "enabled": true }}

YAML

---allow_mobile_payments: enabled: falsedefault_payments_per_region: enabled: true

Operational configuration

The following operational configuration enforces limits on how an application processes requests.

JSON

{ "throttle-limits": { "enabled": "true", "throttles": [ { "simultaneous_connections": 12 }, { "tps_maximum": 5000 }

16

http://aws.amazon.com/systems-manager/features/appconfig/

AWS AppConfig User GuideExample configurations

], "limit-background-tasks": [ true ] }}

YAML

---throttle-limits: enabled: 'true' throttles: - simultaneous_connections: 12 - tps_maximum: 5000 limit-background-tasks: - true

Access control list configuration

The following access control list configuration specifies which users or groups can access an application.

JSON

{ "allow-list": { "enabled": "true", "cohorts": [ { "internal_employees": true }, { "beta_group": false }, { "recent_new_customers": false }, { "user_name": "Jane_Doe" }, { "user_name": "John_Doe" } ] }}

YAML

---allow-list: enabled: 'true' cohorts: - internal_employees: true - beta_group: false - recent_new_customers: false - user_name: Jane_Doe - user_name: Ashok_Kumar

17

AWS AppConfig User GuideAbout the configuration profile IAM role

About the configuration profile IAM roleYou can create the IAM role that provides access to the configuration data by using AWS AppConfig,as described in the following procedure. Or you can create the IAM role yourself and choose it from alist. If you create the role by using AWS AppConfig, the system creates the role and specifies one of thefollowing permissions policies, depending on which type of configuration source you choose.

Configuration source is an SSM document

{

"Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "ssm:GetDocument" ], "Resource": [ "arn:aws:ssm:AWS-Region:account-number:document/document-name" ] } ]}

Configuration source is a Parameter Store parameter

{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "ssm:GetParameter" ], "Resource": [ "Arn:aws:ssm:AWS-Region:account-number:parameter/parameter-name" ] } ] }

If you create the role by using AWS AppConfig, the system also creates the following trust relationshipfor the role.

{

"Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": { "Service": "appconfig.amazonaws.com" }, "Action": "sts:AssumeRole" } ]}

18

AWS AppConfig User GuideAbout configurations stored in Amazon S3

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

Restriction Details

Size Configurations stored as S3 objects can be amaximum of 1 MB in size.

Object encryption A configuration profile can only target an SSE-S3encrypted object.

Storage classes AWS AppConfig supports the following S3 storageclasses: STANDARD, INTELLIGENT_TIERING,REDUCED_REDUNDANCY, STANDARD_IA, andONEZONE_IA. The following classes are notsupported: All S3 Glacier classes (GLACIER andDEEP_ARCHIVE).

Versioning AWS AppConfig requires that the S3 object useversioning.

Configuring permissions for a configuration stored as anAmazon S3 objectWhen you create a configuration profile for a configuration stored as an S3 object, you must specify anARN for an IAM role that gives AWS AppConfig permission to get the object. The role must include thefollowing 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 configurationstored in an S3 object.

Creating the IAM Policy for Accessing an S3 Object

19

AWS AppConfig User GuideAbout configurations stored in Amazon S3

Use the following procedure to create an IAM policy that enables AWS AppConfig to get a configurationstored 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/.

2. In the navigation pane, choose Policies, and then choose Create policy.

3. On the Create policy page, choose the JSON tab.

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

{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "s3:GetObject", "s3:GetObjectVersion" ], "Resource": "arn:aws:s3:::my-bucket/my-configurations/my-configuration.json" }, { "Effect": "Allow", "Action": [ "s3:GetBucketLocation", "s3:GetBucketVersioning", "s3:ListBucketVersions", "s3:ListBucket" ], "Resource": [ "arn:aws:s3:::my-bucket" ] }, { "Effect": "Allow", "Action": "s3:ListAllMyBuckets", "Resource": "*" } ]}

5. Choose Review policy.

6. On the Review policy page, type a name in the Name box, and then type a description.

7. 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 configurationstored in an S3 object.

To create an IAM role for accessing an Amazon S3 object


2. In the navigation pane, choose Roles, and then choose Create role.

3. On the Select type of trusted entity section, choose AWS service.

4. In the Choose a use case section, under Common use cases, choose EC2, and then choose Next:Permissions.

20



AWS AppConfig User GuideAbout validators

5. On the Attach permissions policy page, in the search box, enter the name of the policy you createdin the previous procedure.

6. Choose the policy and then choose Next: Tags.7. On the Add tags (optional) page, enter a key and an optional value, and then choose Next:Review.8. On the Review page, type a name in the Role name field, and then type a description.9. Choose Create role. The system returns you to the Roles page.10. 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 inthis 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 thenchoose Edit Trust Relationship.

2. Delete "ec2.amazonaws.com" and add "appconfig.amazonaws.com", as shown in thefollowing example.

{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": { "Service": "appconfig.amazonaws.com" }, "Action": "sts:AssumeRole" } ]}

3. Choose Update Trust Policy.

About validatorsWhen you create a configuration and configuration profile, you can specify up to two validators. Avalidator ensures that your configuration data is syntactically and semantically correct. You can createvalidators in either JSON Schema or as an AWS Lambda function.

ImportantConfiguration data stored in SSM documents must validate against an associated JSON Schemabefore you can add the configuration to the system. SSM parameters do not require a validationmethod, but we recommend that you create a validation check for new or updated SSMparameter configurations by using AWS Lambda.

JSON Schema Validators

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

{ "$schema": "http://json-schema.org/draft-04/schema#",

21

AWS AppConfig User GuideAbout validators

"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 theconfiguration conforms to the schema requirements. If it doesn't, AWS AppConfig returns a validationerror.

NoteNote the following information about JSON Schema validators:

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

• AWS AppConfig supports JSON Schema version 4.X for inline schema. If your applicationconfiguration requires a different version of JSON Schema, then you must create a Lambdavalidator.

AWS Lambda Validators

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

{ "ApplicationId": "The application Id of the configuration profile being validated", "ConfigurationProfileId": "The configuration profile Id of the configuration profile being validated", "ConfigurationVersion": "The configuration version of the configuration profile being validated", "Content": "Base64EncodedByteString", "Uri": "The uri of the configuration" }

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 in the AWS LambdaDeveloper 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

22

https://docs.aws.amazon.com/lambda/latest/dg/retries-on-errors.html

AWS AppConfig User GuideCreating a feature flag configuration profile

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 andValidateConfigurationActivity API actions. You must provide appconfig.amazonaws.compermissions to invoke your Lambda. For more information, see Granting Function Access to AWSServices. AWS AppConfig limits the validation Lambda run time to 15 seconds, including start-up latency.

Creating a feature flag configuration profileYou can use feature flags to enable or disable features within your applications or to configure differentcharacteristics of your application features using flag attributes. AWS AppConfig stores featureflag configurations in the AWS AppConfig hosted configuration store in a feature flag format thatcontains data and metadata about your flags and the flag attributes. For more information aboutthe AWS AppConfig hosted configuration store, see About the AWS AppConfig hosted configurationstore (p. 34) section.

ImportantTo retrieve feature flag configuration data, your application must call theGetLatestConfiguration API. You can't retrieve feature flag configuration data by callingGetConfiguration. For more information, see GetLatestConfiguration in the AWS AppConfigAPI Reference.

Topics• Creating a feature flag and a feature flag configuration profile (console) (p. 23)• Creating a feature flag and a feature flag configuration profile (commandline) (p. 25)• Type reference for AWS.AppConfig.FeatureFlags (p. 27)

Creating a feature flag and a feature flag configuration profile(console)Use the following procedure to create an AWS AppConfig feature flag configuration profile and a featureflag configuration by using the AWS AppConfig console.

23

https://docs.aws.amazon.com/lambda/latest/dg/access-control-resource-based.html#permissions-resource-serviceinvoke

https://docs.aws.amazon.com/lambda/latest/dg/access-control-resource-based.html#permissions-resource-serviceinvoke

https://docs.aws.amazon.com/appconfig/2019-10-09/APIReference/API_appconfigdata_GetLatestConfiguration.html


To create a configuration profile


2. On the Applications tab, choose the application you created in Create an AWS AppConfigconfiguration (p. 11) and then choose the Configuration profiles and feature flags tab.

3. Choose Create.

4. Choose Feature flag.

To create a feature flag

1. On the configuration you created, choose Add new flag.

2. Provide a Flag name and (optional) Description. The Flag key auto populates by replacing spaceswith underscores in the name you provided. You can edit the flag key if you want a different value orformat. After the flag is created, you can edit the flag name, but not the flag key.

3. Specify whether the feature flag is Enabled or Disabled using the toggle button.

24




4. (Optional) Add Attributes and attribute Constraints to the feature flag. Attributes enable you toprovide additional values within your flag. You can optionally validate attribute values againstspecified constraints. Constraints ensure that any unexpected values are not deployed to yourapplication.

AWS AppConfig feature flags supports the following types of attributes and their correspondingconstraints.

Type Constraint Description

Regular Expression Regex pattern for the stringString

Enum List of acceptable values forthe string

Minimum Minimum numeric value for theattribute

Number

Maximum Maximum numeric value forthe attribute

Boolean None None

Regular Expression Regex pattern for the elementsof the array

String array

Enum List of acceptable values forthe elements of the array

Minimum Minimum numeric value for theelements of the array

Number array

Maximum Maximum numeric value forthe elements of the array

NoteSelect Required value to specify whether the attribute value is required.

5. Choose Save new version.

Proceed to Step 4: Creating a deployment strategy.

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

To create a feature flags configuration step by step


For information, see Install or upgrade AWS command line tools (p. 6).2. Create a feature flag configuration profile specifying its Type as AWS.AppConfig.FeatureFlags.

The configuration profile must use hosted for the location URI.

25

https://docs.aws.amazon.com/cloudshell/latest/userguide/welcome.html



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 theAWS.AppConfig.FeatureFlags JSON schema. For more information about the schema, see Typereference for AWS.AppConfig.FeatureFlags (p. 27).

4. Use the CreateHostedConfigurationVersion API to save your feature flag configuration datato AWS 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 `

26


file_name_for_system_to_store_configuration_data


Linux

{ "ApplicationId" : "The application ID", "ConfigurationProfileId" : "The configuration profile ID", "VersionNumber" : "The configuration version number", "ContentType" : "application/json"}

Windows

{ "ApplicationId" : "The application ID", "ConfigurationProfileId" : "The configuration profile ID", "VersionNumber" : "The configuration version number", "ContentType" : "application/json"}

PowerShell

ApplicationId : The application IDConfigurationProfileId : The configuration profile IDVersionNumber : The configuration version numberContentType : application/json

The service_returned_content_file contains your configuration data that includes some AWSAppConfig generated metadata.

NoteWhen you create the hosted configuration version, AWS AppConfig verifies that yourdata conforms to the AWS.AppConfig.FeatureFlags JSON schema. AWS AppConfigadditionally validates that each feature flag attribute in your data satisfies the constraintsyou defined for those attributes.

Type reference for AWS.AppConfig.FeatureFlags

Use the AWS.AppConfig.FeatureFlags JSON schema as a reference to create your feature flagconfiguration data.

{ "$schema": "http://json-schema.org/draft-07/schema#", "definitions": { "flagSetDefinition": { "type": "object", "properties": { "version": { "$ref": "#/definitions/flagSchemaVersions" }, "flags": { "$ref": "#/definitions/flagDefinitions" }, "values": {

27


"$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" },

28


{ "$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",

29


"properties": { "type": { "type": "string", "enum": ["string"] }, "required": { "type": "boolean" }, "pattern": { "type": "string", "maxLength": 1024 }, "enum": { "type": "array", "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": {

30


"$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 }

ImportantTo retrieve feature flag configuration data, your application must call theGetLatestConfiguration API. You can't retrieve feature flag configuration data by callingGetConfiguration. For more information, see GetLatestConfiguration in the AWS AppConfigAPI Reference.

When your application calls GetLatestConfiguration and receives a newly deployed configuration, theinformation that defines your feature flags and attributes is removed. The simplified JSON contains amap of keys that match each of the flag keys you specified. The simplified JSON also contains mappedvalues of true or false for the enabled attribute. If a flag sets enabled to true, any attributes of theflag 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" }

31

https://docs.aws.amazon.com/appconfig/2019-10-09/APIReference/API_GetLatestConfiguration.html

https://docs.aws.amazon.com/appconfig/2019-10-09/APIReference/API_GetLatestConfiguration.html

AWS AppConfig User GuideCreating a freeform configuration profile

}, "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 } }}

Creating a freeform configuration profileA freeform configuration profile enables AWS AppConfig to access your configuration from a specifiedsource location. You can store freeform configurations in the following formats and locations.

• YAML, JSON, or text documents in the AWS AppConfig hosted configuration store.• Objects in an Amazon Simple Storage Service (Amazon S3) bucket.• Documents in the Systems Manager document store.

32


• Any integration source action supported by AWS CodePipeline.

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 createa configuration profile. The process is described later in this topic.

For freeform configurations stored in SSM parameters or in S3, you must create the parameter or objectfirst and then add it to Parameter Store or S3. After you create the parameter or object, you can use theprocedure in this topic to create the configuration profile. For information about creating a parameter inParameter Store, see Creating Systems Manager parameters in the AWS Systems Manager User Guide.

Topics

• About configuration store quotas and limitations (p. 33)

• About the AWS AppConfig hosted configuration store (p. 34)

• Creating a freeform configuration and configuration profile (p. 34)

About configuration store quotas and limitations

AWS AppConfig-supported configuration store have the following quotas and limitations.

AWSAppConfighostedconfigurationstore

S3 ParameterStore

Documentstore

AWSCodePipeline

Configurationsize limit

1 MB 1 MB

Enforcedby AWSAppConfig, notS3

4 KB (freetier) / 8 KB(advancedparameters)

64 KB 1 MB

Enforcedby AWSAppConfig, notCodePipeline

Resourcestorage limit

1 GB Unlimited 10,000parameters(free tier) /100,000parameters(advancedparameters)

500documents

Limited bythe number ofconfigurationprofiles perapplication(100profiles perapplication)

Server-sideencryption

Yes SSE-S3 No No Yes

AWSCloudFormationsupport

Yes Not forcreating orupdating data

Yes No Yes

Validatecreate orupdate APIactions

Not supported Not supported Regexsupported

JSON Schemarequired for allput and updateAPI actions

Not supported

33

https://docs.aws.amazon.com/systems-manager/latest/userguide/sysman-paramstore-su-create.html

https://docs.aws.amazon.com/AmazonS3/latest/dev/serv-side-encryption.html


AWSAppConfighostedconfigurationstore

S3 ParameterStore

Documentstore

AWSCodePipeline

Pricing Free See Amazon S3pricing

See AWSSystemsManagerpricing

Free See AWSCodePipelinepricing

About the AWS AppConfig hosted configuration store

AWS AppConfig includes an internal or hosted configuration store. Configurations must be 1 MB orsmaller. The AWS AppConfig hosted configuration store provides the following benefits over otherconfiguration store options.

• You don't need to set up and configure other services such as Amazon Simple Storage Service (AmazonS3) or Parameter Store.

• You don't need to configure AWS Identity and Access Management (IAM) permissions to use theconfiguration 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.

Creating a freeform configuration and configuration profile

This section describes how to create a freeform configuration and configuration profile. Before youbegin, note the following information.

• The following procedure requires you to specify an IAM service role so that AWS AppConfig can accessyour configuration data in the configuration store you choose. This role is not required if you usethe AWS AppConfig hosted configuration store. If you choose S3, Parameter Store, or the SystemsManager document store, then you must either choose an existing IAM role or choose the option tohave the system automatically create the role for you. For more information, about this role, see Aboutthe configuration profile IAM role (p. 18).

• If you want to create a configuration profile for configurations stored in S3, you must configurepermissions. For more information about permissions and other requirements for using S3 as aconfiguration store, see About configurations stored in Amazon S3 (p. 19).

• If you want to use validators, review the details and requirements for using them. For moreinformation, see About validators (p. 21).

Topics

• Creating an AWS AppConfig freeform configuration profile (console) (p. 34)

• Creating an AWS AppConfig freeform configuration profile (commandline) (p. 37)

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.

34

https://aws.amazon.com//s3/pricing/

https://aws.amazon.com//s3/pricing/

https://aws.amazon.com//systems-manager/pricing/




https://aws.amazon.com//codepipeline/pricing/




To create a configuration profile


2. On the Applications tab, choose the application you created in Create an AWS AppConfigconfiguration (p. 11) and then choose the Configuration profiles and feature flags tab.

3. Choose Create freeform configuration profile.

4. For Name, enter a name for the configuration profile.

5. For Description, enter information about the configuration profile.

6. On the Select configuration source page, choose an option.

7. • If you selected AWS AppConfig hosted configuration, then choose either YAML, JSON, or Text,and enter your configuration in the field. Choose Next and go to Step 10 in this procedure.

• If you selected Amazon S3 object, then enter the object URI. Choose Next.

• If you selected AWS Systems Manager parameter, then choose the name of the parameter fromthe list. Choose Next.

• If you selected AWS CodePipeline, then choose Next and go to Step 10 in this procedure.

• If you selected AWS Systems Manager document, then complete the following steps.

a. In the Document source section, choose either Saved document or New document.

b. If you choose Saved document, then choose the SSM document from the list. If you chooseNew document, the Details and Content sections appear.

c. In the Details section, enter a name for the new application configuration.

d. For the Application configuration schema section, either choose the JSON schema using thelist or choose Create schema. If you choose Create schema, Systems Manager opens the Createschema page. Enter the schema details in the Content section, and then choose Create schema.

35




e. For Application configuration schema version either choose the version from the list or chooseUpdate schema to edit the schema and create a new version.

f. In the Content section, choose either YAML or JSON and then enter the configuration data inthe field.

g. Choose Next.

8. In the Service role section, choose New service role to have AWS AppConfig create the IAM role thatprovides access to the configuration data. AWS AppConfig automatically populates the Role namefield based on the name you entered earlier. Or, to choose a role that already exists in IAM, chooseExisting service role. Choose the role by using the Role ARN list.

9. On the Add validators page, choose either JSON Schema or AWS Lambda. If you choose JSONSchema, enter the JSON Schema in the field. If you choose AWS Lambda, choose the functionAmazon Resource Name (ARN) and the version from the list.

ImportantConfiguration data stored in SSM documents must validate against an associated JSONSchema before you can add the configuration to the system. SSM parameters do not require

36


a validation method, but we recommend that you create a validation check for new orupdated SSM parameter configurations by using AWS Lambda.


11. Choose Create configuration profile.

ImportantIf you created a configuration profile for AWS CodePipeline, then after you create a deploymentstrategy, as described in the next section, you must create a pipeline in CodePipeline thatspecifies AWS AppConfig as the deploy provider. For information about creating a pipeline thatspecifies AWS AppConfig as the deploy provider, see Tutorial: Create a Pipeline That Uses AWSAppConfig as a Deployment Provider in the AWS CodePipeline User Guide.

Proceed to Step 4: Creating a deployment strategy (p. 38).

Creating an AWS AppConfig freeform configuration profile (commandline)

The following procedure describes how to use the AWS CLI (on Linux or Windows) or AWS Tools forPowerShell to create a AWS AppConfig freeform configuration profile. If you prefer, you can use AWSCloudShell to run the commands listed below. For more information, see What is AWS CloudShell? in theAWS CloudShell User Guide.

To create a configuration profile step by step


For information, see Install or upgrade AWS command line tools (p. 6).

2. Run the following command to create a freeform configuration profile.

Linux

aws appconfig create-configuration-profile \ --application-id The_application_ID \ --name A_name_for_the_configuration_profile \ --description A_description_of_the_configuration_profile \ --location-uri A_URI_to_locate_the_configuration or hosted \ --retrieval-role-arn The_ARN_of_the_IAM_role_with_permission_to_access_the_configuration_at_the_specified_LocationUri \ --tags User_defined_key_value_pair_metadata_of_the_configuration_profile \ --validators "Content=JSON_Schema_content_or_the_ARN_of_an_AWS Lambda_function,Type=JSON_SCHEMA or LAMBDA"

Windows

aws appconfig create-configuration-profile ^ --application-id The_application_ID ^ --name A_name_for_the_configuration_profile ^ --description A_description_of_the_configuration_profile ^ --location-uri A_URI_to_locate_the_configuration or hosted ^ --retrieval-role-arn The_ARN_of_the_IAM_role_with_permission_to_access_the_configuration_at_the_specified_LocationUri ^ --tags User_defined_key_value_pair_metadata_of_the_configuration_profile ^ --validators "Content=JSON_Schema_content_or_the_ARN_of_an_AWS Lambda_function,Type=JSON_SCHEMA or LAMBDA"

37

https://docs.aws.amazon.com/codepipeline/latest/userguide/tutorials-AppConfig.html



AWS AppConfig User GuideStep 4: Creating a deployment strategy

PowerShell

New-APPCConfigurationProfile ` -Name A_name_for_the_configuration_profile ` -ApplicationId The_application_ID ` -Description Description_of_the_configuration_profile ` -LocationUri A_URI_to_locate_the_configuration or hosted ` -RetrievalRoleArn The_ARN_of_the_IAM_role_with_permission_to_access_the_configuration_at_the_specified_LocationUri ` -Tag Hashtable_type_user_defined_key_value_pair_metadata_of_the_configuration_profile ` -Validators "Content=JSON_Schema_content_or_the_ARN_of_an_AWS Lambda_function,Type=JSON_SCHEMA or LAMBDA"

NoteIf you created a configuration in the AWS AppConfig hosted configuration store, you cancreate new versions of the configuration by using the CreateHostedConfigurationVersion APIaction. To view AWS CLI details and sample commands for this API action, see create-hosted-configuration-version in the AWS CLI Command Reference.

Step 4: Creating a deployment strategyAn AWS AppConfig deployment strategy defines the following important aspects of a configurationdeployment.

Setting Description

Deployment type Deployment type defines how the configurationdeploys or rolls out. AWS AppConfig supportsLinear and Exponential deployment types.

• Linear: For this type, AWS AppConfig processesthe deployment by increments of the growthfactor evenly distributed over the deployment.For example, a linear deployment that usesa step percentage of 20 initially makes theconfiguration available to 20 percent of thetargets. After 1/5th of the deployment timehas passed, the system updates the percentageto 40 percent. This continues until 100% ofthe targets are set to receive the deployedconfiguration.

• Exponential: For this type, AWS AppConfigprocesses the deployment exponentiallyusing the following formula: G*(2^N). In thisformula, G is the step percentage specified bythe user and N is the number of steps until theconfiguration is deployed to all targets. Forexample, if you specify a growth factor of 2,then the system rolls out the configuration asfollows:

38

https://docs.aws.amazon.com/appconfig/2019-10-09/APIReference/API_CreateHostedConfigurationVersion.html

https://docs.aws.amazon.com/cli/latest/reference/appconfig/create-hosted-configuration-version.html

https://docs.aws.amazon.com/cli/latest/reference/appconfig/create-hosted-configuration-version.html

AWS AppConfig User GuidePredefined deployment strategies

Setting Description

2*(2^0)2*(2^1)2*(2^2)

Expressed numerically, the deployment rollsout as follows: 2% of the targets, 4% of thetargets, 8% of the targets, and continues untilthe configuration has been deployed to alltargets.

Step percentage (growth factor) This setting specifies the percentage of callers totarget during each step of the deployment.

NoteIn the SDK and the AWS AppConfig APIReference, step percentage is calledgrowth factor.

Deployment time This setting specifies an amount of time duringwhich AWS AppConfig deploys to hosts. This isnot a timeout value. It is a window of time duringwhich the deployment is processed in intervals.

Bake time This setting specifies the amount of time AWSAppConfig monitors for Amazon CloudWatchalarms before proceeding to the next step of adeployment or before considering the deploymentto be complete. If an alarm is triggered during thistime, AWS AppConfig rolls back the deployment.You must configure permissions for AWSAppConfig to roll back based on CloudWatchalarms. For more information, see (Optional)Configuring permissions for rollback based onCloudWatch alarms (p. 9).

Predefined deployment strategiesAWS AppConfig includes predefined deployment strategies to help you quickly deploy a configuration.Instead of creating your own strategies, you can choose one of the following when you deploy aconfiguration.

Deployment strategy Description

AppConfig.AllAtOnce Quick:

This strategy deploys the configuration to alltargets immediately. The system monitors forAmazon CloudWatch alarms for 10 minutes. If noalarms are received in this time, the deployment iscomplete. If an alarm is triggered during this time,AppConfig rolls back the deployment.

AppConfig.Linear50PercentEvery30Seconds Testing/Demonstration:

39

https://docs.aws.amazon.com/appconfig/2019-10-09/APIReference/API_CreateDeploymentStrategy.html

https://docs.aws.amazon.com/appconfig/2019-10-09/APIReference/API_CreateDeploymentStrategy.html

AWS AppConfig User GuideCreate a deployment strategy

Deployment strategy Description

This strategy deploys the configuration to halfof all targets every 30 seconds for a one-minutedeployment. The system monitors for AmazonCloudWatch alarms for 1 minute. If no alarmsare received in this time, the deployment iscomplete. If an alarm is triggered during this time,AppConfig rolls back the deployment.

We recommend using this strategy only fortesting or demonstration purposes because it hasa short duration and bake time.

AppConfig.Canary10Percent20Minutes AWS Recommended:

This strategy processes the deploymentexponentially using a 10% growth factor over20 minutes. The system monitors for AmazonCloudWatch alarms for 10 minutes. If no alarmsare received in this time, the deployment iscomplete. If an alarm is triggered during this time,AppConfig rolls back the deployment.

We recommend using this strategy for productiondeployments because it aligns with AWS bestpractices for configuration deployments.

Create a deployment strategyYou can create a maximum of 20 deployment strategies. When you deploy a configuration, you canchoose the deployment strategy that works best for the application and the environment.

Creating an AWS AppConfig deployment strategy (console)Use the following procedure to create a AWS AppConfig deployment strategy by using the AWS SystemsManager console.

To create a deployment strategy


2. In the navigation pane, choose AWS AppConfig.3. Choose the Deployment Strategies tab, and then choose Create deployment strategy.4. For Name, enter a name for the deployment strategy.5. For Description, enter information about the deployment strategy.6. For Deployment type, choose a type.7. For Step percentage, choose the percentage of callers to target during each step of the deployment.8. For Deployment time, enter the total duration for the deployment in minutes or hours.9. For Bake time, enter the total time, in minutes or hours, to monitor for Amazon CloudWatch alarms

before proceeding to the next step of a deployment or before considering the deployment to becomplete.


40




11. Choose Create deployment strategy.

ImportantIf you created a configuration profile for AWS CodePipeline, then you must create a pipeline inCodePipeline that specifies AWS AppConfig as the deploy provider. You don't need to performStep 5: Deploying a configuration (p. 43). However, you must configure a client to receiveapplication configuration updates as described in Step 6: Retrieving the configuration (p. 46).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 in the AWSCodePipeline User Guide.

Proceed to Step 5: Deploying a configuration (p. 43).

Creating an AWS AppConfig deployment strategy(commandline)The following procedure describes how to use the AWS CLI (on Linux or Windows) or AWS Tools forPowerShell to create a AWS AppConfig deployment strategy.

To create a deployment strategy step by step


For information, see Install or upgrade AWS command line tools (p. 6).2. Run the following command to create a deployment strategy.

Linux

aws appconfig create-deployment-strategy \ --name A_name_for_the_deployment_strategy \ --description A_description_of_the_deployment_strategy \ --deployment-duration-in-minutes Total_amount_of_time_for_a_deployment_to_last \ --final-bake-time-in-minutes Amount_of_time_AWS AppConfig_monitors_for_alarms_before_considering_the_deployment_to_be_complete \ --growth-factor The_percentage_of_targets_to_receive_a_deployed_configuration_during_each_interval \ --growth-type The_linear_or_exponential_algorithm_used_to_define_how_percentage_grows_over_time \ --replicate-to To_save_the_deployment_strategy_to_a_Systems_Manager_(SSM)_document \ --tags User_defined_key_value_pair_metadata_of_the_deployment_strategy

Windows

aws appconfig create-deployment-strategy ^ --name A_name_for_the_deployment_strategy ^ --description A_description_of_the_deployment_strategy ^ --deployment-duration-in-minutes Total_amount_of_time_for_a_deployment_to_last ^ --final-bake-time-in-minutes Amount_of_time_AWS AppConfig_monitors_for_alarms_before_considering_the_deployment_to_be_complete ^ --growth-factor The_percentage_of_targets_to_receive_a_deployed_configuration_during_each_interval ^ --growth-type The_linear_or_exponential_algorithm_used_to_define_how_percentage_grows_over_time ^ --name A_name_for_the_deployment_strategy ^

41



--replicate-to To_save_the_deployment_strategy_to_a_Systems_Manager_(SSM)_document ^ --tags User_defined_key_value_pair_metadata_of_the_deployment_strategy

PowerShell

New-APPCDeploymentStrategy ` --Name A_name_for_the_deployment_strategy ` --Description A_description_of_the_deployment_strategy ` --DeploymentDurationInMinutes Total_amount_of_time_for_a_deployment_to_last ` --FinalBakeTimeInMinutes Amount_of_time_AWS AppConfig_monitors_for_alarms_before_considering_the_deployment_to_be_complete ` --GrowthFactor The_percentage_of_targets_to_receive_a_deployed_configuration_during_each_interval ` --GrowthType The_linear_or_exponential_algorithm_used_to_define_how_percentage_grows_over_time ` --ReplicateTo To_save_the_deployment_strategy_to_a_Systems_Manager_(SSM)_document ` --Tag Hashtable_type_User_defined_key_value_pair_metadata_of_the_deployment_strategy


Linux

{ "Id": "Id of the deployment strategy", "Name": "Name of the deployment strategy", "Description": "Description of the deployment strategy", "DeploymentDurationInMinutes": "Total amount of time the deployment lasted", "GrowthType": "The linear or exponential algorithm used to define how percentage grew over time", "GrowthFactor": "The percentage of targets that received a deployed configuration during each interval", "FinalBakeTimeInMinutes": "The amount of time AWS AppConfig monitored for alarms before considering the deployment to be complete", "ReplicateTo": "The Systems Manager (SSM) document where the deployment strategy is saved"}

Windows

{ "Id": "Id of the deployment strategy", "Name": "Name of the deployment strategy", "Description": "Description of the deployment strategy", "DeploymentDurationInMinutes": "Total amount of time the deployment lasted", "GrowthType": "The linear or exponential algorithm used to define how percentage grew over time", "GrowthFactor": "The percentage of targets that received a deployed configuration during each interval", "FinalBakeTimeInMinutes": "The amount of time AWS AppConfig monitored for alarms before considering the deployment to be complete", "ReplicateTo": "The Systems Manager (SSM) document where the deployment strategy is saved"}

42

AWS AppConfig User GuideStep 5: Deploying a configuration

PowerShell

ContentLength : Runtime of the commandDeploymentDurationInMinutes : Total amount of time the deployment lastedDescription : Description of the deployment strategyFinalBakeTimeInMinutes : The amount of time AWS AppConfig monitored for alarms before considering the deployment to be completeGrowthFactor : The percentage of targets that received a deployed configuration during each intervalGrowthType : The linear or exponential algorithm used to define how percentage grew over timeHttpStatusCode : HTTP Status of the runtimeId : The deployment strategy IDName : Name of the deployment strategyReplicateTo : The Systems Manager (SSM) document where the deployment strategy is savedResponseMetadata : Runtime Metadata

Step 5: Deploying a configurationStarting a deployment in AWS AppConfig calls the StartDeployment API action. This call includes theIDs of the AWS AppConfig application, the environment, the configuration profile, and (optionally) theconfiguration data version to deploy. The call also includes the ID of the deployment strategy to use,which determines how the configuration data is deployed.

AWS AppConfig monitors the distribution to all hosts and reports status. If a distribution fails, then AWSAppConfig rolls back the configuration.

NoteYou can only deploy one configuration at a time to an Environment. However, you can deployone configuration each to different Environments at the same time.

Deploy a configuration (console)Use the following procedure to deploy an AWS AppConfig configuration by using the AWS SystemsManager console.

To deploy a configuration by using the console


2. In the navigation pane, choose AWS AppConfig.

3. On the Applications tab, choose an application, and then choose View details.

4. On the Environments tab, choose an environment, and then choose View details.

5. Choose Start deployment.

6. For Configuration, choose a configuration from the list.

7. Depending on the source of your configuration, use the Document version or Parameter version listto choose the version you want to deploy.

8. For Deployment strategy, choose a strategy from the list.

9. For Deployment description, enter a description.


43




AWS AppConfig User GuideDeploy a configuration (commandline)

11. Choose Start deployment.

Deploy a configuration (commandline)The following procedure describes how to use the AWS CLI (on Linux or Windows) or AWS Tools forPowerShell to deploy a AWS AppConfig configuration.

To deploy a configuration step by step


For information, see Install or upgrade AWS command line tools (p. 6).2. Run the following command to deploy a configuration.

Linux

aws appconfig start-deployment \ --application-id The_application_ID \ --environment-id The_environment_ID \ --deployment-strategy-id The_deployment_strategy_ID \ --configuration-profile-id The_configuration_profile_ID \ --configuration-version The_configuration_version_to_deploy \ --description A_description_of_the_deployment \ --tags User_defined_key_value_pair_metadata_of_the_deployment

Windows

aws appconfig start-deployment ^ --application-id The_application_ID ^ --environment-id The_environment_ID ^ --deployment-strategy-id The_deployment_strategy_ID ^ --configuration-profile-id The_configuration_profile_ID ^ --configuration-version The_configuration_version_to_deploy ^ --description A_description_of_the_deployment ^ --tags User_defined_key_value_pair_metadata_of_the_deployment

PowerShell

Start-APPCDeployment ` -ApplicationId The_application_ID ` -ConfigurationProfileId The_configuration_profile_ID ` -ConfigurationVersion The_configuration_version_to_deploy ` -DeploymentStrategyId The_deployment_strategy_ID ` -Description A_description_of_the_deployment ` -EnvironmentId The_environment_ID ` -Tag Hashtable_type_user_defined_key_value_pair_metadata_of_the_deployment


Linux

{ "ApplicationId": "The ID of the application that was deployed", "EnvironmentId" : "The ID of the environment", "DeploymentStrategyId": "The ID of the deployment strategy that was deployed", "ConfigurationProfileId": "The ID of the configuration profile that was deployed",

44

AWS AppConfig User GuideDeploy a configuration (commandline)

"DeploymentNumber": The sequence number of the deployment, "ConfigurationName": "The name of the configuration", "ConfigurationLocationUri": "Information about the source location of the configuration", "ConfigurationVersion": "The configuration version that was deployed", "Description": "The description of the deployment", "DeploymentDurationInMinutes": Total amount of time the deployment lasted, "GrowthType": "The linear or exponential algorithm used to define how percentage grew over time", "GrowthFactor": The percentage of targets to receive a deployed configuration during each interval, "FinalBakeTimeInMinutes": Time AWS AppConfig monitored for alarms before considering the deployment to be complete, "State": "The state of the deployment",

"EventLog": [ { "Description": "A description of the deployment event", "EventType": "The type of deployment event", "OccurredAt": The date and time the event occurred, "TriggeredBy": "The entity that triggered the deployment event" } ],

"PercentageComplete": The percentage of targets for which the deployment is available, "StartedAt": The time the deployment started, "CompletedAt": The time the deployment completed }

Windows

{ "ApplicationId": "The ID of the application that was deployed", "EnvironmentId" : "The ID of the environment", "DeploymentStrategyId": "The ID of the deployment strategy that was deployed", "ConfigurationProfileId": "The ID of the configuration profile that was deployed", "DeploymentNumber": The sequence number of the deployment, "ConfigurationName": "The name of the configuration", "ConfigurationLocationUri": "Information about the source location of the configuration", "ConfigurationVersion": "The configuration version that was deployed", "Description": "The description of the deployment", "DeploymentDurationInMinutes": Total amount of time the deployment lasted, "GrowthType": "The linear or exponential algorithm used to define how percentage grew over time", "GrowthFactor": The percentage of targets to receive a deployed configuration during each interval, "FinalBakeTimeInMinutes": Time AWS AppConfig monitored for alarms before considering the deployment to be complete, "State": "The state of the deployment",

"EventLog": [ { "Description": "A description of the deployment event", "EventType": "The type of deployment event", "OccurredAt": The date and time the event occurred, "TriggeredBy": "The entity that triggered the deployment event" } ],

"PercentageComplete": The percentage of targets for which the deployment is available,

45

AWS AppConfig User GuideStep 6: Retrieving the configuration

"StartedAt": The time the deployment started, "CompletedAt": The time the deployment completed }

PowerShell

ApplicationId : The ID of the application that was deployedCompletedAt : The time the deployment completedConfigurationLocationUri : Information about the source location of the configurationConfigurationName : The name of the configurationConfigurationProfileId : The ID of the configuration profile that was deployedConfigurationVersion : The configuration version that was deployedContentLength : Runtime of the deployment DeploymentDurationInMinutes : Total amount of time the deployment lastedDeploymentNumber : The sequence number of the deploymentDeploymentStrategyId : The ID of the deployment strategy that was deployedDescription : The description of the deploymentEnvironmentId : The ID of the environment that was deployedEventLog : {Description : A description of the deployment event, EventType : The type of deployment event, OccurredAt : The date and time the event occurred, TriggeredBy : The entity that triggered the deployment event}FinalBakeTimeInMinutes : Time AWS AppConfig monitored for alarms before considering the deployment to be completeGrowthFactor : The percentage of targets to receive a deployed configuration during each intervalGrowthType : The linear or exponential algorithm used to define how percentage grew over timeHttpStatusCode : HTTP Status of the runtimePercentageComplete : The percentage of targets for which the deployment is availableResponseMetadata : Runtime MetadataStartedAt : The time the deployment startedState : The state of the deployment

Step 6: Retrieving the configurationYour application retrieves configuration data by first establishing a configuration session usingthe StartConfigurationSession API action. Your session's client then makes periodic calls toGetLatestConfiguration to check for and retrieve the latest data available.

When calling StartConfigurationSession, your code sends the following information:

• Identifiers (ID or name) of an AWS AppConfig application, environment, and configuration profile thatthe session tracks.

• (Optional) The minimum amount of time the session's client must wait between calls toGetLatestConfiguration.

In response, AWS AppConfig provides an InitialConfigurationToken to be given to the session'sclient and used the first time it calls GetLatestConfiguration for that session.

ImportantThis token should only be used once in your first call to GetLatestConfiguration.You must use the new token in the GetLatestConfiguration response(NextPollConfigurationToken) in each subsequent call to GetLatestConfiguration.

When calling GetLatestConfiguration, your client code sends the most recentConfigurationToken value it has and receives in response:

46

https://docs.aws.amazon.com/appconfig/2019-10-09/APIReference/API_appconfigdata_StartConfigurationSession.html


AWS AppConfig User GuideRetrieving a configuration example

• NextPollConfigurationToken: the ConfigurationToken value to use on the next call toGetLatestConfiguration.

• NextPollIntervalInSeconds: the duration the client should wait before making its next call toGetLatestConfiguration. This duration may vary over the course of the session, so it should beused instead of the value sent on the StartConfigurationSession call.

• The configuration: the latest data intended for the session. This may be empty if the client already hasthe latest version of the configuration.

ImportantNote the following important information.

• The StartConfigurationSession API should only be called once per application, environment,configuration profile, and client to establish a session with the service. This is typically done inthe startup of your application or immediately prior to the first retrieval of a configuration.

• The InitialConfigurationToken and NextPollConfigurationToken expire after24 hours. If a GetLatestConfiguration call uses an expired token, the system returnsBadRequestException.

Retrieving a configuration exampleThe following AWS CLI example demonstrates how to retrieve configuration data by using theAWS AppConfig Data StartConfigurationSession and GetLatestConfiguration APIactions. The first command starts a configuration session. This call includes the IDs (or names) ofthe AWS AppConfig application, the environment, and the configuration profile. The API returns anInitialConfigurationToken used to fetch your configuration data.

aws appconfigdata start-configuration-session \ --application-identifier application_name_or_ID \ --environment-identifier environment_name_or_ID \ --configuration-profile-identifier configuration_profile_name_or_ID

The system responds with information in the following format.

{ "InitialConfigurationToken": initial configuration token}

After starting a session, use InitialConfigurationToken to call GetLatestConfiguration to fetch yourconfiguration data. The configuration data is saved to the mydata.json file.

aws appconfigdata get-latest-configuration \ --configuration-token initial configuration token mydata.json

The first call to GetLatestConfiguration uses the ConfigurationToken obtained fromStartConfigurationSession. The following information is returned.

{ "NextPollConfigurationToken" : next configuration token, "ContentType" : content type of configuration, "NextPollIntervalInSeconds" : 60}

Subsequent calls to GetLatestConfiguration must provide NextPollConfigurationToken fromthe previous response.

47


https://docs.aws.amazon.com/appconfig/2019-10-09/APIReference/API_appconfigdata_StartConfigurationSession.html#API_appconfigdata_StartConfigurationSession_ResponseSyntax


AWS AppConfig User GuideRetrieving a configuration example

aws appconfigdata get-latest-configuration \ --configuration-token next configuration token mydata.json

ImportantNote the following important details about the GetLatestConfiguration API action:

• The GetLatestConfiguration response includes a Configuration section that showsthe configuration data. The Configuration section only appears if the system finds new orupdated configuration data. If the system doesn't find new or updated configuration data,then the Configuration data is empty.

• You receive a new ConfigurationToken in every response fromGetLatestConfiguration.

• We recommend tuning the polling frequency of your GetLatestConfiguration API callsbased on your budget, the expected frequency of your configuration deployments, and thenumber of targets for a configuration.

48

AWS AppConfig User GuideAWS Lambda extensions

Services that integrate with AWSAppConfig

AWS AppConfig integrates with other AWS services to help you manage your application configurationsquickly and securely. The following information can help you configure AWS AppConfig to integrate withthe products and services you use.

Contents

• AWS AppConfig integration with Lambda extensions (p. 49)

• AWS AppConfig integration with Atlassian Jira (p. 67)

• AWS AppConfig integration with CodePipeline (p. 70)

AWS AppConfig integration with Lambdaextensions

An AWS Lambda extension is a companion process that augments the capabilities of a Lambda function.An extension can start before a function is invoked, run in parallel with a function, and continue torun after a function invocation is processed. In essence, a Lambda extension is like a client that runs inparallel to a Lambda invocation. This parallel client can interface with your function at any point duringits lifecycle.

If you use AWS AppConfig feature flags or other dynamic configuration data in a Lambda function,then we recommend that you add the AWS AppConfig Lambda extension as a layer to your Lambdafunction. This makes calling feature flags simpler, and the extension itself includes best practices thatsimplify using AWS AppConfig while reducing costs. Reduced costs result from fewer API calls to the AWSAppConfig service and shorter Lambda function processing times. For more information about Lambdaextensions, see Lambda extensions in the AWS Lambda Developer Guide.

NoteAWS AppConfig pricing is based on the number of times a configuration is called and received.You costs increase if your Lambda performs multiple cold starts and retrieves new configurationdata frequently.

This topic includes information about the AWS AppConfig Lambda extension and the procedure for howto configure the extension to work with your Lambda function.

How it worksIf you use AWS AppConfig to manage configurations for a Lambda function without Lambda extensions,then you must configure your Lambda function to receive configuration updates by integrating with theStartConfigurationSession and GetLatestConfiguration API actions.

Integrating the AWS AppConfig Lambda extension with your Lambda function simplifies this process.The extension takes care of calling the AWS AppConfig service, managing a local cache of retrieved

49

https://docs.aws.amazon.com/lambda/latest/dg/runtimes-extensions-api.html

https://aws.amazon.com/systems-manager/pricing/



AWS AppConfig User GuideHow it works

data, tracking the configuration tokens needed for the next service calls, and periodically checking forconfiguration updates in the background. The following diagram shows how it works.

1. You configure the AWS AppConfig Lambda extension as a layer of your Lambda function.

2. To access its configuration data, your function calls the AWS AppConfig extension at an HTTPendpoint running on localhost:2772.

3. The extension maintains a local cache of the configuration data. If the data isn't in the cache, theextension calls AWS AppConfig to get the configuration data.

4. Upon receiving the configuration from the service, the extension stores it in the local cache and passesit to the Lambda function.

5. AWS AppConfig Lambda extension periodically checks for updates to your configuration data inthe background. Each time your Lambda function is invoked, the extension checks the elapsed timesince it retrieved a configuration. If the elapsed time is greater than the configured poll interval, theextension calls AWS AppConfig to check for newly deployed data, updates the local cache if there hasbeen a change, and resets the elapsed time.

Note

• Lambda instantiates separate instances corresponding to the concurrency level that yourfunction requires. Each instance is isolated and maintains its own local cache of yourconfiguration data. For more information about Lambda instances and concurrency, seeManaging concurrency for a Lambda function.

• The amount of time it takes for a configuration change to appear in a Lambda function, afteryou deploy an updated configuration from AWS AppConfig, depends on the deployment

50

https://docs.aws.amazon.com/lambda/latest/dg/configuration-concurrency.html

AWS AppConfig User GuideBefore you begin

strategy you used for the deployment and the polling interval you configured for theextension.

Before you beginBefore you enable the AWS AppConfig Lambda extension, do the following:

• Organize the configurations in your Lambda function so that you can externalize them into AWSAppConfig.

• Configure AWS AppConfig to manage your configuration updates. For more information, see Workingwith AWS AppConfig (p. 11).

• Add appconfig:StartConfigurationSession and appconfig:GetLatestConfiguration tothe AWS Identity and Access Management (IAM) policy used by the Lambda function execution role.For more information, see AWS Lambda execution role in the AWS Lambda Developer Guide. For moreinformation about AWS AppConfig permissions, see Actions, resources, and condition keys for AWSAppConfig in the Service Authorization Reference.

Supported runtimesThe AWS AppConfig Lambda extension supports the following runtimes:

• Python 3.7, 3.8, 3.9

• Node.js 12.x, 14.x

• Ruby 2.7

• Java 8, 11 (Amazon Corretto)

• .NET Core 3.1

• Custom runtimes (Amazon Linux and Amazon Linux 2)

For more information about these runtimes, including the corresponding SDKs, operating systems, andarchitectures, see Lambda runtimes in the AWS Lambda Developer Guide.

Adding the AWS AppConfig Lambda extensionTo use the AWS AppConfig Lambda extension, you need to add the extension to your Lambda. This canbe done by adding the AWS AppConfig Lambda extension to your Lambda function as a layer or byenabling the extension on a Lambda function as a container image.

Adding the AWS AppConfig Lambda extension by using a layerand an ARN

To use the AWS AppConfig Lambda extension, you add the extension to your Lambda function as alayer. For information about how to add a layer to your function, see Configuring extensions in the AWSLambda Developer Guide. The name of the extension in the AWS Lambda console is AWS-AppConfig-Extension. Also note that when you add the extension as a layer to your Lambda, you must specify anAmazon Resource Name (ARN). Choose an ARN from one of the following lists that corresponds with theplatform and AWS Region where you created the Lambda.

• x86-64 platform (p. 55)

• ARM64 platform (p. 57)

51

https://docs.aws.amazon.com/lambda/latest/dg/lambda-intro-execution-role.html

https://docs.aws.amazon.com/service-authorization/latest/reference/list_awsappconfig.html

https://docs.aws.amazon.com/service-authorization/latest/reference/list_awsappconfig.html

https://docs.aws.amazon.com/lambda/latest/dg/lambda-runtimes.html

https://docs.aws.amazon.com/lambda/latest/dg/using-extensions.html#using-extensions-config

AWS AppConfig User GuideConfiguring the AWS AppConfig Lambda extension

If you want to test the extension before you add it to your function, you can verify that it works by usingthe following code example.

import urllib.request

def lambda_handler(event, context): url = f'http://localhost:2772/applications/application_name/environments/environment_name/configurations/configuration_name' config = urllib.request.urlopen(url).read() return config

To test it, create a new Lambda function for Python, add the extension, and then run the Lambdafunction. After you run the Lambda function, the AWS AppConfig Lambda function returns theconfiguration you specified for the http://localhost:2772 path. For information about creating a Lambdafunction, see Create a Lambda function with the console in the AWS Lambda Developer Guide.

To add the AWS AppConfig Lambda extension as a container image, see Using a container image to addthe AWS AppConfig Lambda extension (p. 63).

Configuring the AWS AppConfig Lambda extensionYou can configure the extension by changing the following AWS Lambda environment variables. Formore information, see Using AWS Lambda environment variables in the AWS Lambda Developer Guide.

Prefetching configuration data

The environment variable AWS_APPCONFIG_EXTENSION_PREFETCH_LIST can improve the start-uptime of your function. When the AWS AppConfig Lambda extension is initialized, it retrieves the specifiedconfiguration from AWS AppConfig before Lambda starts to initialize your function and invoke yourhandler. In some cases, the configuration data is already available in the local cache before your functionrequests it.

To use the prefetch capability, set the value of the environment variable to the path correspondingto your configuration data. For example, if your configuration corresponds to an application,environment, and configuration profile respectively named "my_application", "my_environment", and"my_configuration_data", the path would be /applications/my_application/environments/my_environment/configurations/my_configuration_data. You can specify multipleconfiguration items by listing them as a comma-separated list (If you have a resource name that includesa comma, use the resource’s ID value instead of its name).

Accessing configuration data from another account

The AWS AppConfig Lambda extension can retrieve configuration data from another account byspecifying an IAM role that grants permissions to the data. To set this up, follow these steps:

1. In the account where AWS AppConfig is used to manage the configuration data, create arole with a trust policy that grants the account running the Lambda function access to theappconfig:StartConfigurationSession and appconfig:GetLatestConfigurationactions, along with the partial or complete ARNs corresponding to the AWS AppConfig configurationresources.

2. In the account running the Lambda function, add the AWS_APPCONFIG_EXTENSION_ROLE_ARNenvironment variable to the Lambda function with the ARN of the role created in step 1.

3. (Optional) If needed, an external ID can be specified using theAWS_APPCONFIG_EXTENSION_ROLE_EXTERNAL_ID environment variable. Similarly, a session namecan be configured using the AWS_APPCONFIG_EXTENSION_ROLE_SESSION_NAME environmentvariable.

52

https://docs.aws.amazon.com/lambda/latest/dg/getting-started-create-function.html

https://docs.aws.amazon.com/lambda/latest/dg/configuration-envvars.html

https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_use_permissions-to-switch.html

https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create_for-user_externalid.html

AWS AppConfig User GuideConfiguring the AWS AppConfig Lambda extension

NoteNote the following information.

• The AWS AppConfig Lambda extension can only retrieve data from one account. If you specifyan IAM role, the extension will not be able to retrieve configuration data from the account inwhich the Lambda function is running.

• AWS Lambda logs information about the AWS AppConfig Lambda extension and the Lambdafunction by using Amazon CloudWatch Logs.

Environment variable Details Default value

AWS_APPCONFIG_EXTENSION_POLL_INTERVAL_SECONDSThis environment variablecontrols how often theextension polls AWS AppConfigfor an updated configuration inseconds.

45

AWS_APPCONFIG_EXTENSION_POLL_TIMEOUT_MILLISThis environment variablecontrols the maximum amountof time, in milliseconds, theextension waits for a responsefrom AWS AppConfig whenrefreshing data in the cache.If AWS AppConfig does notrespond in the specified amountof time, the extension skips thispoll interval and returns thepreviously updated cached data.

3000

AWS_APPCONFIG_EXTENSION_HTTP_PORTThis environment variablespecifies the port on which thelocal HTTP server that hosts theextension runs.

2772

AWS_APPCONFIG_EXTENSION_PREFETCH_LISTThis environment variablespecifies the configuration datathat the extension starts toretrieve before the functioninitializes and the handler runs.It can reduce the function's coldstart time significantly.

None

AWS_APPCONFIG_EXTENSION_MAX_CONNECTIONSThis environment variableconfigures the maximumnumber of connections theextension uses to retrieveconfigurations from AWSAppConfig.

3

AWS_APPCONFIG_EXTENSION_LOG_LEVELThis environment variablespecifies which AWS AppConfigextension-specific logs aresent to Amazon CloudWatchLogs for a function. Valid,case-insensitive values are:debug, info, warn, error,and none. Debug includes

info

53

AWS AppConfig User GuideRetrieving one or more flags

Environment variable Details Default value

detailed information, includingtiming information, about theextension.

AWS_APPCONFIG_EXTENSION_ROLE_ARNThis environment variablespecifies the IAM role ARNcorresponding to a role thatshould be assumed by the AWSAppConfig extension to retrieveconfiguration.

None

AWS_APPCONFIG_EXTENSION_ROLE_EXTERNAL_IDThis environment variablespecifies the external id to usein conjunction with the assumedrole ARN.

None

AWS_APPCONFIG_EXTENSION_ROLE_SESSION_NAMEThis environment variablespecifies the session name to beassociated with the credentialsfor the assumed IAM role.

None

AWS_APPCONFIG_EXTENSION_SERVICE_REGIONThis environment variablespecifies an alternative regionthe extension should use to callthe AWS AppConfig service.When undefined, the extensionuses the endpoint in the currentregion.

None

Retrieving one or more flags from a feature flagconfigurationFor feature flag configurations (configurations of type AWS.AppConfig.FeatureFlags), the Lambdaextension enables you to retrieve a single flag or a subset of flags in a configuration. Retrieving oneor two flags is useful if your Lambda only needs to use a few flags from the configuration profile. Thefollowing examples use Python.

NoteThe ability to call a single feature flag or a subset of flags in a configuration is only available inthe AWS AppConfig Lambda extension version 2.0.45 and higher.

You can retrieve AWS AppConfig configuration data from a local HTTP endpoint. To access a specificflag or a list of flags, use the ?flag=flag_name query parameter for an AWS AppConfig configurationprofile.

To access a single flag and its attributes


def lambda_handler(event, context): url = f'http://localhost:2772/applications/application_name/environments/environment_name/configurations/configuration_name?flag=flag_name' config = urllib.request.urlopen(url).read() return config

54

AWS AppConfig User GuideAvailable versions of the AWSAppConfig Lambda extension

To access a multiple flags and their attributes


def lambda_handler(event, context): url = f'http://localhost:2772/applications/application_name/environments/environment_name/configurations/configuration_name?flag=flag_name_one&flag=flag_name_two' config = urllib.request.urlopen(url).read() return config

Available versions of the AWS AppConfig LambdaextensionThis topic lists AWS AppConfig Lambda extension versions according to processor. The AWS AppConfigLambda extension supports Lambda functions developed for the x86-64 and ARM64 (Graviton2)platforms. Each table includes the Amazon Resource Name (ARN) to use in each AWS Region.

Topics• x86-64 platform (p. 55)• ARM64 platform (p. 57)• Older extension versions (p. 58)

x86-64 platformWhen you add the extension as a layer to your Lambda, you must specify an ARN. Choose an ARN fromthe following table that corresponds with the AWS Region where you created the Lambda. These ARNsare for Lambda functions developed for the x86-64 platform.

Version 2.0.58

Region ARN

US East (N. Virginia) arn:aws:lambda:us-east-1:027255383542:layer:AWS-AppConfig-Extension:69

US East (Ohio) arn:aws:lambda:us-east-2:728743619870:layer:AWS-AppConfig-Extension:50

US West (N. California) arn:aws:lambda:us-west-1:958113053741:layer:AWS-AppConfig-Extension:78

US West (Oregon) arn:aws:lambda:us-west-2:359756378197:layer:AWS-AppConfig-Extension:101

Canada (Central) arn:aws:lambda:ca-central-1:039592058896:layer:AWS-AppConfig-Extension:50

Europe (Frankfurt) arn:aws:lambda:eu-central-1:066940009817:layer:AWS-AppConfig-Extension:59

55


Region ARN

Europe (Ireland) arn:aws:lambda:eu-west-1:434848589818:layer:AWS-AppConfig-Extension:69

Europe (London) arn:aws:lambda:eu-west-2:282860088358:layer:AWS-AppConfig-Extension:50

Europe (Paris) arn:aws:lambda:eu-west-3:493207061005:layer:AWS-AppConfig-Extension:51

Europe (Stockholm) arn:aws:lambda:eu-north-1:646970417810:layer:AWS-AppConfig-Extension:98

Europe (Milan) arn:aws:lambda:eu-south-1:203683718741:layer:AWS-AppConfig-Extension:47

China (Bejing) arn:aws-cn:lambda:cn-north-1:615057806174:layer:AWS-AppConfig-Extension:46

China (Ningxia) arn:aws-cn:lambda:cn-northwest-1:615084187847:layer:AWS-AppConfig-Extension:46

Asia Pacific (Hong Kong) arn:aws:lambda:ap-east-1:630222743974:layer:AWS-AppConfig-Extension:47

Asia Pacific (Tokyo) arn:aws:lambda:ap-northeast-1:980059726660:layer:AWS-AppConfig-Extension:49

Asia Pacific (Seoul) arn:aws:lambda:ap-northeast-2:826293736237:layer:AWS-AppConfig-Extension:59

Asia Pacific (Osaka) arn:aws:lambda:ap-northeast-3:706869817123:layer:AWS-AppConfig-Extension:46

Asia Pacific (Singapore) arn:aws:lambda:ap-southeast-1:421114256042:layer:AWS-AppConfig-Extension:51

Asia Pacific (Sydney) arn:aws:lambda:ap-southeast-2:080788657173:layer:AWS-AppConfig-Extension:59

Asia Pacific (Jakarta) arn:aws:lambda:ap-southeast-3:418787028745:layer:AWS-AppConfig-Extension:24

56


Region ARN

Asia Pacific (Mumbai) arn:aws:lambda:ap-south-1:554480029851:layer:AWS-AppConfig-Extension:60

South America (São Paulo) arn:aws:lambda:sa-east-1:000010852771:layer:AWS-AppConfig-Extension:69

Africa (Cape Town) arn:aws:lambda:af-south-1:574348263942:layer:AWS-AppConfig-Extension:47

Middle East (Bahrain) arn:aws:lambda:me-south-1:559955524753:layer:AWS-AppConfig-Extension:47

AWS GovCloud (US-East) arn:aws-us-gov:lambda:us-gov-east-1:946561847325:layer:AWS-AppConfig-Extension:23

AWS GovCloud (US-West) arn:aws-us-gov:lambda:us-gov-west-1:946746059096:layer:AWS-AppConfig-Extension:23

ARM64 platform

When you add the extension as a layer to your Lambda, you must specify an ARN. Choose an ARN fromthe following table that corresponds with the AWS Region where you created the Lambda. These ARNsare for Lambda functions developed for the ARM64 platform.

Version 2.0.58

Region ARN

US East (N. Virginia) arn:aws:lambda:us-east-1:027255383542:layer:AWS-AppConfig-Extension-Arm64:2

US East (Ohio) arn:aws:lambda:us-east-2:728743619870:layer:AWS-AppConfig-Extension-Arm64:2

US West (Oregon) arn:aws:lambda:us-west-2:359756378197:layer:AWS-AppConfig-Extension-Arm64:3

Europe (Frankfurt) arn:aws:lambda:eu-central-1:066940009817:layer:AWS-AppConfig-Extension-Arm64:2

Europe (Ireland) arn:aws:lambda:eu-west-1:434848589818:layer:AWS-AppConfig-Extension-Arm64:7

57


Region ARN

Europe (London) arn:aws:lambda:eu-west-2:282860088358:layer:AWS-AppConfig-Extension-Arm64:2

Asia Pacific (Tokyo) arn:aws:lambda:ap-northeast-1:980059726660:layer:AWS-AppConfig-Extension-Arm64:2

Asia Pacific (Singapore) arn:aws:lambda:ap-southeast-1:421114256042:layer:AWS-AppConfig-Extension-Arm64:3

Asia Pacific (Sydney) arn:aws:lambda:ap-southeast-2:080788657173:layer:AWS-AppConfig-Extension-Arm64:2

Asia Pacific (Mumbai) arn:aws:lambda:ap-south-1:554480029851:layer:AWS-AppConfig-Extension-Arm64:2

Older extension versionsThis section lists the ARNs and AWS Regions for older versions of the AWS AppConfig Lambda extension.This list doesn't contain information for all previous versions of the AWS AppConfig Lambda extension,but it will be updated when new versions are released.

Older extension versions (x86-64 platform)

The following tables list ARNs and the AWS Regions for older versions of the AWS AppConfig Lambdaextension developed for the x86-64 platform.

Date replaced by newer extension: 04/21/2022

Version 2.0.45

Region ARN






58


Region ARN















59


Region ARN









Version 2.0.30

Region ARN







60


Region ARN















61


Region ARN







Older extension versions (ARM64 platform)

The following tables list ARNs and the AWS Regions for older versions of the AWS AppConfig Lambdaextension developed for the ARM64 platform.


Version 2.0.45

Region ARN

US East (N. Virginia) arn:aws:lambda:us-east-1:027255383542:layer:AWS-AppConfig-Extension-Arm64:1

US East (Ohio) arn:aws:lambda:us-east-2:728743619870:layer:AWS-AppConfig-Extension-Arm64:1

US West (Oregon) arn:aws:lambda:us-west-2:359756378197:layer:AWS-AppConfig-Extension-Arm64:2

Europe (Frankfurt) arn:aws:lambda:eu-central-1:066940009817:layer:AWS-AppConfig-Extension-Arm64:1

Europe (Ireland) arn:aws:lambda:eu-west-1:434848589818:layer:AWS-AppConfig-Extension-Arm64:6

62

AWS AppConfig User GuideUsing a container image to add theAWS AppConfig Lambda extension

Region ARN

Europe (London) arn:aws:lambda:eu-west-2:282860088358:layer:AWS-AppConfig-Extension-Arm64:1

Asia Pacific (Tokyo) arn:aws:lambda:ap-northeast-1:980059726660:layer:AWS-AppConfig-Extension-Arm64:1

Asia Pacific (Singapore) arn:aws:lambda:ap-southeast-1:421114256042:layer:AWS-AppConfig-Extension-Arm64:2

Asia Pacific (Sydney) arn:aws:lambda:ap-southeast-2:080788657173:layer:AWS-AppConfig-Extension-Arm64:1

Asia Pacific (Mumbai) arn:aws:lambda:ap-south-1:554480029851:layer:AWS-AppConfig-Extension-Arm64:1

Using a container image to add the AWS AppConfigLambda extensionYou can package your AWS AppConfig Lambda extension as a container image to upload it to yourcontainer registry hosted on Amazon Elastic Container Registry (Amazon ECR).

To add the AWS AppConfig Lambda extension as a Lambda container image

1. Enter the AWS Region and the Amazon Resource Name (ARN) in the AWS Command Line Interface(AWS CLI) as shown below. Replace the Region and ARN value with your Region and the matchingARN to retrieve a copy of the Lambda layer.

aws lambda get-layer-version-by-arn \ --region us-east-1 \ --arn arn:aws:lambda::layer:AWS-AppConfig-Extension:00

Following is the response.

{ "LayerVersionArn": "arn:aws:lambda::layer:AWS-AppConfig-Extension:00", "Description": "AWS AppConfig extension: Use dynamic configurations deployed via AWS AppConfig for your AWS Lambda functions", "CreatedDate": "2021-04-01T02:37:55.339+0000", "LayerArn": "arn:aws:lambda::layer:AWS-AppConfig-Extension",

"Content": { "CodeSize": 5228073, "CodeSha256": "8otOgbLQbexpUm3rKlMhvcE6Q5TvwcLCKrc4Oe+vmMY=", "Location" : "S3-Bucket-Location-URL" },

"Version": 30, "CompatibleRuntimes": [ "python3.8", "python3.7",

63

AWS AppConfig User GuideUsing a container image to add theAWS AppConfig Lambda extension

"nodejs12.x", "ruby2.7" ],}

2. In the above response, the value returned for Location is the URL of the Amazon Simple StorageService (Amazon S3) bucket that contains the Lambda extension. Paste the URL into your webbrowser to download the Lambda extension .zip file.

NoteThe Amazon S3 bucket URL is available for only 10 minutes.

(Optional) Alternatively, you can also use the following curl command to download the Lambdaextension.

curl -o extension.zip "S3-Bucket-Location-URL"

(Optional) Alternatively, you can combine Step 1 and Step 2 to retrieve the ARN and downloadthe .zip extension file all at once.

aws lambda get-layer-version-by-arn \ --arn arn:aws:lambda::layer:AWS-AppConfig-Extension:00 \ | jq -r '.Content.Location' \ | xargs curl -o extension.zip

3. Add the following lines in your Dockerfile to add the extension to your container image.

COPY extension.zip extension.zipRUN yum install -y unzip \ && unzip extension.zip /opt \ && rm -f extension.zip

4. Ensure that the Lambda function execution role has the appconfig:GetConfiguration permission set.

Example

This section includes an example for enabling the AWS AppConfig Lambda extension on a containerimage-based Python Lambda function.

1. Create a Dockerfile that is similar to the following.

FROM public.ecr.aws/lambda/python:3.8 AS builderCOPY extension.zip extension.zipRUN yum install -y unzip \ && unzip extension.zip -d /opt \ && rm -f extension.zip

FROM public.ecr.aws/lambda/python:3.8COPY --from=builder /opt /optCOPY index.py ${LAMBDA_TASK_ROOT}CMD [ "index.handler" ]

2. Download the extension layer to the same directory as the Dockerfile.

aws lambda get-layer-version-by-arn \ --arn arn:aws:lambda::layer:AWS-AppConfig-Extension:00 \ | jq -r '.Content.Location' \ | xargs curl -o extension.zip

64

https://docs.aws.amazon.com/appconfig/2019-10-09/APIReference/API_GetConfiguration.html

AWS AppConfig User GuideIntegrating with OpenAPI

3. Create a Python file named index.py in the same directory as the Dockerfile.


def handler(event, context): return { # replace parameters here with your application, environment, and configuration names 'configuration': get_configuration('myApp', 'myEnv', 'myConfig'), }

def get_configuration(app, env, config): url = f'http://localhost:2772/applications/{app}/environments/{env}/configurations/{config}' return urllib.request.urlopen(url).read()

4. Run the following steps to build the docker image and upload it to Amazon ECR.

// set environment variablesexport ACCOUNT_ID = <YOUR_ACCOUNT_ID>export REGION = <AWS_REGION>

// create an ECR repositoryaws ecr create-repository --repository-name test-repository

// build the docker imagedocker build -t test-image .

// sign in to AWSaws ecr get-login-password \ | docker login \ --username AWS \ --password-stdin "$ACCOUNT_ID.dkr.ecr.$REGION.amazonaws.com"

// tag the image docker tag test-image:latest "$ACCOUNT_ID.dkr.ecr.$REGION.amazonaws.com/test-repository:latest"

// push the image to ECR docker push "$ACCOUNT_ID.dkr.ecr.$REGION.amazonaws.com/test-repository:latest"

5. Use the Amazon ECR image that you created above to create the Lambda function. For moreinformation about a Lambda function as a container, see Create a Lambda function defined as acontainer image.

6. Ensure that the Lambda function execution role has the appconfig:GetConfiguration permission set.

Integrating with OpenAPIYou can use the following YAML specification for OpenAPI to create an SDK using a tool like OpenAPIGenerator. You can update this specification to include hard-coded values for Application, Environment,or Configuration. You can also add additional paths (if you have multiple configuration types) andinclude configuration schemas to generate configuration-specific typed models for your SDK clients. Formore information about OpenAPI (which is also known as Swagger), see the OpenAPI specification.

openapi: 3.0.0info: version: 1.0.0 title: AppConfig Lambda extension API description: An API model for AppConfig Lambda extension.

65

https://docs.aws.amazon.com/lambda/latest/dg/getting-started-create-function.html#gettingstarted-images-function

https://docs.aws.amazon.com/lambda/latest/dg/getting-started-create-function.html#gettingstarted-images-function

https://docs.aws.amazon.com/appconfig/2019-10-09/APIReference/API_GetConfiguration.html

https://github.com/OpenAPITools/openapi-generator

https://github.com/OpenAPITools/openapi-generator

https://swagger.io/specification/

AWS AppConfig User GuideIntegrating with OpenAPI

servers: - url: https://localhost:{port}/ variables: port: default: '2772'paths: /applications/{Application}/environments/{Environment}/configurations/{Configuration}: get: operationId: getConfiguration tags: - configuration parameters: - in: path name: Application description: The application for the configuration to get. Specify either the application name or the application ID. required: true schema: type: string - in: path name: Environment description: The environment for the configuration to get. Specify either the environment name or the environment ID. required: true schema: type: string - in: path name: Configuration description: The configuration to get. Specify either the configuration name or the configuration ID. required: true schema: type: string responses: 200: headers: ConfigurationVersion: schema: type: string content: application/octet-stream: schema: type: string format: binary description: successful config retrieval 400: description: BadRequestException content: application/text: schema: $ref: '#/components/schemas/Error' 404: description: ResourceNotFoundException content: application/text: schema: $ref: '#/components/schemas/Error' 500: description: InternalServerException content: application/text: schema: $ref: '#/components/schemas/Error' 502: description: BadGatewayException

66

AWS AppConfig User GuideAtlassian Jira

content: application/text: schema: $ref: '#/components/schemas/Error' 504: description: GatewayTimeoutException content: application/text: schema: $ref: '#/components/schemas/Error'

components: schemas: Error: type: string description: The response error

AWS AppConfig integration with Atlassian JiraIntegrating with Atlassian Jira allows AWS AppConfig to create and update issues in the Atlassian consolewhenever you make changes to a feature flag in your AWS account for the specified AWS Region. EachJira issue includes the flag name, application ID, configuration profile ID, and flag values. After youupdate, save, and deploy your flag changes, Jira updates the existing issues with the details of thechange.

NoteJira updates issues whenever you create or update a feature flag. Jira also updates issues whenyou delete a child-level flag attribute from a parent-level flag. Jira does not record informationwhen you delete a parent-level flag.

To configure integration, you must do the following:

• Configure permissions

• Configure integration

Configuring permissions for AWS AppConfig JiraintegrationWhen you configure AWS AppConfig integration with Jira, you specify credentials for an AWS Identityand Access Management (IAM) user. Specifically, you enter the user's access key ID and secret key in theAWS AppConfig for Jira application. This user gives Jira permission to communicate with AWS AppConfig.AWS AppConfig uses these credentials one time to establish an association between AWS AppConfig andJira. The credentials are not stored. You can remove the association by uninstalling the AWS AppConfigfor Jira application.

The IAM user account requires a permissions policy that includes the following actions:

• appconfig:AssociateExtension

• appconfig:GetConfigurationProfile

• appconfig:ListApplications

• appconfig:ListConfigurationProfiles

• appconfig:UpdateConfigurationProfile

67

https://docs.aws.amazon.com/appconfig/latest/userguide/appconfig-creating-configuration-and-profile.html#appconfig-creating-configuration-and-profile-feature-flags

https://docs.aws.amazon.com/appconfig/latest/userguide/appconfig-integration-jira-permissions.html

https://docs.aws.amazon.com/appconfig/latest/userguide/appconfig-integration-jira-configure.html

AWS AppConfig User GuideConfiguring permissions

• sts:GetCallerIdentity

Complete the following tasks to create an IAM permissions policy and an IAM user for AWS AppConfigand Jira integration:

Tasks

• Task 1: Create an IAM permissions policy for AWS AppConfig and Jira integration (p. 68)

• Task 2: Create an IAM user for AWS AppConfig and Jira integration (p. 69)

Task 1: Create an IAM permissions policy for AWS AppConfigand Jira integrationUse the following procedure to create an IAM permissions policy that allows Atlassian Jira tocommunicate with AWS AppConfig. We recommend that you create a new policy and attach this policyto a new IAM role. Adding the required permissions to an existing IAM policy and role goes against theprinciple of least privilege and is not recommended.

To create an IAM policy for AWS AppConfig and Jira integration


2. In the navigation pane, choose Policies, and then choose Create policy.

3. On the Create policy page, choose the JSON tab and replace the default content with thefollowing policy. In the following policy, replace Region, account_ID, application_ID,and configuration_profile_ID with information from your AWS AppConfig feature flagenvironment.

{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "appconfig:AssociateExtension", "appconfig:GetConfigurationProfile", "appconfig:UpdateConfigurationProfile" ], "Resource": [ "arn:aws:appconfig:Region:account_ID:application/application_ID", "arn:aws:appconfig:Region:account_ID:application/application_ID/configurationprofile/configuration_profile_ID" ] }, { "Effect": "Allow", "Action": [ "appconfig:ListApplications" ], "Resource": [ "arn:aws:appconfig:Region:account_ID:*" ] }, { "Effect": "Allow", "Action": [

68


AWS AppConfig User GuideConfiguring integration

"appconfig:ListConfigurationProfiles" ], "Resource": [ "arn:aws:appconfig:Region:account_ID:application/application_ID" ] }, { "Effect": "Allow", "Action": "sts:GetCallerIdentity", "Resource": "*" } ]}

4. Choose Next: Tags.5. (Optional) Add one or more tag-key value pairs to organize, track, or control access for this policy,

and then choose Next: Review.6. On the Review policy page, enter a name in the Name box, such as AppConfigJiraPolicy, and

then enter an optional description.7. Choose Create policy.

Task 2: Create an IAM user for AWS AppConfig and JiraintegrationUse the following procedure to create an IAM user for AWS AppConfig and Atlassian Jira integration.After you create the user, you can copy the access key ID and secret key, which you will specify when youcomplete the integration.

To create an IAM user for AWS AppConfig and Jira integration

1. Open the IAM console at https://console.aws.amazon.com/iam/.2. In the navigation pane, choose Users, and then choose Add users.3. In the User name field, enter a name, such as AppConfigJiraUser.4. For Select AWS credential type, choose Access key - Programmatic access.5. Choose Next: Permissions.6. Under Set permissions page, choose Attach existing policies directly. Search for and select the

check box for the policy that you created in Task 1: Create an IAM permissions policy for AWSAppConfig and Jira integration (p. 68), and then choose Next: Tags.

7. On the Add tags (optional) page, add one or more tag-key value pairs to organize, track, or controlaccess for this user. Choose Next: Review.

8. On the Review page, verify the user details.9. Choose Create user. The system displays the user's access key ID and secret key. Either download

the .csv file or copy these credentials to a separate location. You will specify these credentials whenyou configure integration.

Configuring the AWS AppConfig Jira integrationapplicationUse the following procedure to configure required options in the AWS AppConfig for Jira application.After you complete this procedure, Jira creates a new issue for each feature flag in your AWS accountfor the specified AWS Region. If you make changes to a feature flag in AWS AppConfig, Jira records thedetails in the existing issues.

69


AWS AppConfig User GuideDeleting integration

NoteAn AWS AppConfig feature flag can include multiple child-level flag attributes. Jira creates oneissue for each parent-level feature flag. If you change a child-level flag attribute, you can viewthe details of that change in the Jira issue for the parent-level flag.

To configure integration

1. Log in to the Atlassian Marketplace.

2. Type AWS AppConfig in the search field and press Enter.

3. Install the application on your Jira instance.

4. In the Atlassian console, choose Manage apps, and then choose AWS AppConfig for Jira.

5. Choose Configure.

6. Under Configuration details, choose Jira project and then choose the project that you want toassociate with your AWS AppConfig feature flag.

7. Choose AWS Region, and then choose the Region where your AWS AppConfig feature flag is located.

8. In the Application ID field, enter the name of the AWS AppConfig application that contains yourfeature flag.

9. In the Configuration profile ID field, enter the name of the AWS AppConfig configuration profile foryour feature flag.

10. In the Access key ID and Secret key fields, enter the credentials you copied in Task 2: Create an IAMuser for AWS AppConfig and Jira integration (p. 69). Optionally, you can also specify a sessiontoken.

11. Choose Submit.

12. In the Atlassian console, choose Projects, and then choose the project you selected for AWSAppConfig integration. The Issues page displays an issue for each feature flag in the specified AWSaccount and AWS Region.

Deleting the AWS AppConfig for Jira application anddataIf you no longer want to use Jira integration with AWS AppConfig feature flags, you can delete the AWSAppConfig for Jira application in the Atlassian console. Deleting the integration application does thefollowing:

• Deletes the association between your Jira instance and AWS AppConfig.

• Deletes your Jira instance details from AWS AppConfig.

To delete the AWS AppConfig for Jira application

1. In the Atlassian console, choose Manage apps.

2. Choose AWS AppConfig for Jira.

3. Choose Uninstall.

AWS AppConfig integration with CodePipelineAWS AppConfig is an integrated deploy action for AWS CodePipeline (CodePipeline). CodePipeline isa fully managed continuous delivery service that helps you automate your release pipelines for fastand reliable application and infrastructure updates. CodePipeline automates the build, test, and deploy

70

https://marketplace.atlassian.com/

AWS AppConfig User GuideHow integration works

phases of your release process every time there is a code change, based on the release model you define.For more information, see What is AWS CodePipeline?

The integration of AWS AppConfig with CodePipeline offers the following benefits:

• Customers who use CodePipeline to manage orchestration now have a lightweight means of deployingconfiguration changes to their applications without having to deploy their entire code base.

• Customers who want to use AWS AppConfig to manage configuration deployments but are limitedbecause AWS AppConfig does not support their current code or configuration store, now haveadditional options. CodePipeline supports AWS CodeCommit, GitHub, and BitBucket (to name a few).

NoteAWS AppConfig integration with CodePipeline is only supported in AWS Regions whereCodePipeline is available.

How integration worksYou start by setting up and configuring CodePipeline. This includes adding your configuration to aCodePipeline-supported code store. Next, you set up your AWS AppConfig environment by performingthe following tasks:

• Create an application• Create an environment• Create an AWS CodePipeline configuration profile• Choose a predefined deployment strategy or create your own

After you complete these tasks, you create a pipeline in CodePipeline that specifies AWS AppConfigas the deploy provider. You can then make a change to your configuration and upload it to yourCodePipeline code store. Uploading the new configuration automatically starts a new deployment inCodePipeline. After the deployment completes, you can verify your changes. For information aboutcreating a pipeline that specifies AWS AppConfig as the deploy provider, see Tutorial: Create a PipelineThat Uses AWS AppConfig as a Deployment Provider in the AWS CodePipeline User Guide.

71

https://docs.aws.amazon.com/codepipeline/latest/userguide/welcome.html

https://aws.amazon.com/about-aws/global-infrastructure/regional-product-services/

https://docs.aws.amazon.com/systems-manager/latest/userguide/appconfig-creating-application.html

https://docs.aws.amazon.com/systems-manager/latest/userguide/appconfig-creating-environment.html

https://docs.aws.amazon.com/systems-manager/latest/userguide/appconfig-creating-configuration-and-profile.html

https://docs.aws.amazon.com/systems-manager/latest/userguide/appconfig-creating-deployment-strategy.html




Security in AWS AppConfigCloud security at AWS is the highest priority. As an AWS customer, you benefit from a data centerand network architecture that are built to meet the requirements of the most security-sensitiveorganizations.

Security is a shared responsibility between AWS and you. The shared responsibility model describes thisas security of the cloud and security in the cloud:

• Security of the cloud – AWS is responsible for protecting the infrastructure that runs AWS services inthe AWS Cloud. AWS also provides you with services that you can use securely. Third-party auditorsregularly test and verify the effectiveness of our security as part of the AWS Compliance Programs. Tolearn about the compliance programs that apply to AWS Systems Manager, see AWS Services in Scopeby Compliance Program.

• Security in the cloud – Your responsibility is determined by the AWS service that you use. You are alsoresponsible for other factors including the sensitivity of your data, your company’s requirements, andapplicable laws and regulations.

AWS AppConfig is a capability of AWS Systems Manager. To understand how to apply the sharedresponsibility model when using AWS AppConfig, refer to Security in AWS Systems Manager. It explainshow to configure Systems Manager to meet the security and compliance objectives for AWS AppConfig.

72

http://aws.amazon.com/compliance/shared-responsibility-model/

http://aws.amazon.com/compliance/programs/

http://aws.amazon.com/compliance/services-in-scope/

http://aws.amazon.com/compliance/services-in-scope/



Monitoring AWS AppConfigMonitoring is an important part of maintaining the reliability, availability, and performance of your AWSsolutions. AWS AppConfig is a capability of AWS Systems Manager. For information about monitoringSystems Manager capabilities, see Monitoring AWS Systems Manager in the AWS Systems Manager UserGuide.

73

https://docs.aws.amazon.com/systems-manager/latest/userguide/monitoring.html


AWS AppConfig User GuideDocument History

The following table describes the important changes to the documentation since the last release of AWSAppConfig.

Current API version: 2019-10-09

update-history-change update-history-description update-history-date

New version of the AWSAppConfig LambdaExtension (p. 74)

Version 2.0.58 of the AWSAppConfig Lambda Extensionis now available. The newextension uses different AmazonResource Names (ARNs). Formore information, see Availableversions of the AWS AppConfigLambda extension.

May 3, 2022

AWS AppConfig integration withAtlassian Jira (p. 74)

Integrating with AtlassianJira allows AWS AppConfig tocreate and update issues in theAtlassian console whenever youmake changes to a feature flagin your AWS account for thespecified AWS Region. Each Jiraissue includes the flag name,application ID, configurationprofile ID, and flag values. Afteryou update, save, and deployyour flag changes, Jira updatesthe existing issues with thedetails of the change. For moreinformation, see AWS AppConfigintegration with Atlassian Jira.

April 7, 2022

General availability of featureflags and Lambda extensionsupport for ARM64 (Graviton2)processors (p. 74)

With AWS AppConfig featureflags, you can develop anew feature and deploy it toproduction while hiding thefeature from users. You startby adding the flag to AWSAppConfig as configuration data.Once the feature is ready to bereleased, you can update theflag configuration data withoutdeploying any code. This featureimproves the safety of yourdev-ops environment becauseyou don't need to deploy newcode to release the feature. Formore information, see Creating

March 15, 2022

74

https://docs.aws.amazon.com/appconfig/latest/userguide/appconfig-integration-lambda-extensions-versions.html




https://docs.aws.amazon.com/appconfig/latest/userguide/appconfig-integration-jira.html

https://docs.aws.amazon.com/appconfig/latest/userguide/appconfig-integration-jira.html



a feature flag configurationprofile.

General availability of featureflags in AWS AppConfig includesthe following enhancements:

• The console includes an optionto designate a flag as a shortterm flag. You can filter andsort the list of flags on short-term flags.

• For customers using featureflags in AWS Lambda, the newLambda extension allows youto call individual feature flagsby using an HTTP endpoint.For more information, seesee Retrieving one or moreflags from a feature flagconfiguration.

This update also providessupport for AWS Lambdaextensions developed for ARM64(Graviton2) processors. For moreinformation, see see Availableversions of the AWS AppConfigLambda extension.

The GetConfiguration API actionis deprecated (p. 74)

The GetConfigurationAPI action is deprecated.Calls to receive configurationdata should use theStartConfigurationSessionandGetLatestConfigurationAPIs instead. For moreinformation about these APIsand how to use them, seeRetrieving the configuration.

January 28, 2022

New region ARN forAWS AppConfig Lambdaextension (p. 74)

AWS AppConfig Lambdaextension is available in the newAsia Pacific (Osaka) region. TheAmazon Resource Name (ARN) isrequired to create a Lambda inthe region. For more informationabout the Asia Pacific (Osaka)region ARN, see Adding the AWSAppConfig Lambda extension.

March 4, 2021

75



https://docs.aws.amazon.com/appconfig/latest/userguide/appconfig-integration-lambda-extensions-retrieving-flags.html






https://docs.aws.amazon.com/appconfig/latest/userguide/appconfig-retrieving-the-configuration.html

https://docs.aws.amazon.com/appconfig/latest/userguide/appconfig-integration-lambda-extensions.html#appconfig-integration-lambda-extensions-enabling

https://docs.aws.amazon.com/appconfig/latest/userguide/appconfig-integration-lambda-extensions.html#appconfig-integration-lambda-extensions-enabling


AWS AppConfig Lambdaextension (p. 74)

If you use AWS AppConfigto manage configurationsfor a Lambda function, thenwe recommend that you addthe AWS AppConfig Lambdaextension. This extensionincludes best practices thatsimplify using AWS AppConfigwhile reducing costs. Reducedcosts result from fewer APIcalls to the AWS AppConfigservice and, separately, reducedcosts from shorter Lambdafunction processing times. Formore information, see AWSAppConfig integration withLambda extensions.

October 8, 2020

New section (p. 74) Added a new section thatprovides instructions for settingup AWS AppConfig. For moreinformation, see Setting up AWSAppConfig.

September 30, 2020

Added commandlineprocedures (p. 74)

Procedures in this user guidenow include commandline stepsfor the AWS Command LineInterface (AWS CLI) and Tools forWindows PowerShell. For moreinformation, see Working withAWS AppConfig.

September 30, 2020

Launch of AWS AppConfig userguide (p. 74)

Use AWS AppConfig, a capabilityof AWS Systems Manager,to create, manage, andquickly deploy applicationconfigurations. AWSAppConfig supports controlleddeployments to applicationsof any size and includes built-in validation checks andmonitoring. You can use AWSAppConfig with applicationshosted on EC2 instances, AWSLambda, containers, mobileapplications, or IoT devices.

July 31, 2020

76

https://docs.aws.amazon.com/appconfig/latest/userguide/appconfig-integration-lambda-extensions.html



https://docs.aws.amazon.com/appconfig/latest/userguide/setting-up-appconfig.html

https://docs.aws.amazon.com/appconfig/latest/userguide/setting-up-appconfig.html

https://docs.aws.amazon.com/appconfig/latest/userguide/appconfig-creating-application.html

https://docs.aws.amazon.com/appconfig/latest/userguide/appconfig-creating-application.html


AWS glossaryFor the latest AWS terminology, see the AWS glossary in the AWS General Reference.

77

https://docs.aws.amazon.com/general/latest/gr/glos-chap.html

AWS AppConfig - User Guide

Documents

Transcript of AWS AppConfig - User Guide