Welcome
Amazon AppConfig
Amazon AppConfig feature flags and dynamic configurations help software builders quickly and securely adjust application behavior in production environments without full code deployments. Amazon AppConfig speeds up software release frequency, improves application resiliency, and helps you address emergent issues more quickly. With feature flags, you can gradually release new capabilities to users and measure the impact of those changes before fully deploying the new capabilities to all users. With operational flags and dynamic configurations, you can update block lists, allow lists, throttling limits, logging verbosity, and perform other operational tuning to quickly respond to issues in production environments.
Note
Amazon AppConfig is a capability of Amazon Systems Manager.
Despite the fact that application configuration content can vary greatly from application to application, Amazon AppConfig supports the following use cases, which cover a broad spectrum of customer needs:
-
Feature flags and toggles - Safely release new capabilities to your customers in a controlled environment. Instantly roll back changes if you experience a problem.
-
Application tuning - Carefully introduce application changes while testing the impact of those changes with users in production environments.
-
Allow list or block list - Control access to premium features or instantly block specific users without deploying new code.
-
Centralized configuration storage - Keep your configuration data organized and consistent across all of your workloads. You can use Amazon AppConfig to deploy configuration data stored in the Amazon AppConfig hosted configuration store, Amazon Secrets Manager, Systems Manager, Parameter Store, or Amazon S3.
How Amazon AppConfig works
This section provides a high-level description of how Amazon AppConfig works and how you get started.
- 1. Identify configuration values in code you want to manage in the cloud
-
Before you start creating Amazon AppConfig artifacts, we recommend you identify configuration data in your code that you want to dynamically manage using Amazon AppConfig. Good examples include feature flags or toggles, allow and block lists, logging verbosity, service limits, and throttling rules, to name a few.
If your configuration data already exists in the cloud, you can take advantage of Amazon AppConfig validation, deployment, and extension features to further streamline configuration data management.
- 2. Create an application namespace
-
To create a namespace, you create an Amazon AppConfig artifact called an application. An application is simply an organizational construct like a folder.
- 3. Create environments
-
For each Amazon AppConfig application, you define one or more environments. An environment is a logical grouping of targets, such as applications in a
Beta
orProduction
environment, Lambda functions, or containers. You can also define environments for application subcomponents, such as theWeb
,Mobile
, andBack-end
.You can configure Amazon CloudWatch alarms for each environment. The system monitors alarms during a configuration deployment. If an alarm is triggered, the system rolls back the configuration.
- 4. Create a configuration profile
-
A configuration profile includes, among other things, a URI that enables Amazon AppConfig to locate your configuration data in its stored location and a profile type. Amazon AppConfig supports two configuration profile types: feature flags and freeform configurations. Feature flag configuration profiles store their data in the Amazon AppConfig hosted configuration store and the URI is simply
hosted
. For freeform configuration profiles, you can store your data in the Amazon AppConfig hosted configuration store or any Amazon service that integrates with Amazon AppConfig, as described in Creating a free form configuration profilein the the Amazon AppConfig User Guide. A configuration profile can also include optional validators to ensure your configuration data is syntactically and semantically correct. Amazon AppConfig performs a check using the validators when you start a deployment. If any errors are detected, the deployment rolls back to the previous configuration data.
- 5. Deploy configuration data
-
When you create a new deployment, you specify the following:
-
An application ID
-
A configuration profile ID
-
A configuration version
-
An environment ID where you want to deploy the configuration data
-
A deployment strategy ID that defines how fast you want the changes to take effect
When you call the StartDeployment API action, Amazon AppConfig performs the following tasks:
-
Retrieves the configuration data from the underlying data store by using the location URI in the configuration profile.
-
Verifies the configuration data is syntactically and semantically correct by using the validators you specified when you created your configuration profile.
-
Caches a copy of the data so it is ready to be retrieved by your application. This cached copy is called the deployed data.
-
- 6. Retrieve the configuration
-
You can configure Amazon AppConfig Agent as a local host and have the agent poll Amazon AppConfig for configuration updates. The agent calls the StartConfigurationSession and GetLatestConfiguration API actions and caches your configuration data locally. To retrieve the data, your application makes an HTTP call to the localhost server. Amazon AppConfig Agent supports several use cases, as described in Simplified retrieval methods
in the the Amazon AppConfig User Guide. If Amazon AppConfig Agent isn't supported for your use case, you can configure your application to poll Amazon AppConfig for configuration updates by directly calling the StartConfigurationSession and GetLatestConfiguration API actions.
This reference is intended to be used with the Amazon AppConfig User
Guide
Amazon AppConfig Data
Amazon AppConfig Data provides the data plane APIs your application uses to retrieve configuration data. Here's how it works:
Your application retrieves configuration data by first establishing a configuration session using the Amazon AppConfig Data StartConfigurationSession API action. Your session's client then makes periodic calls 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 Amazon AppConfig application, environment, and configuration profile that the session tracks.
-
(Optional) The minimum amount of time the session's client must wait between calls to
GetLatestConfiguration
.
In response, Amazon AppConfig provides an InitialConfigurationToken
to be given to
the session's client and used the first time it calls GetLatestConfiguration
for that session.
Important
This 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 recent
ConfigurationToken
value it has and receives in response:
-
NextPollConfigurationToken
: theConfigurationToken
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 be used instead of the value sent on theStartConfigurationSession
call. -
The configuration: the latest data intended for the session. This may be empty if the client already has the latest version of the configuration.
Important
The InitialConfigurationToken
and
NextPollConfigurationToken
should only be used once. To support long
poll use cases, the tokens are valid for up to 24 hours. If a
GetLatestConfiguration
call uses an expired token, the system returns
BadRequestException
.
For more information and to view example Amazon CLI commands that show how to retrieve a
configuration using the Amazon AppConfig Data
StartConfigurationSession
and
GetLatestConfiguration
API actions, see Retrieving feature flags and
configuration data in Amazon AppConfig in the
Amazon AppConfig User Guide.