AppConfigClient

AppConfig feature flags and dynamic configurations help software builders quickly and securely adjust application behavior in production environments without full code deployments. 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.

AppConfig is a capability of Amazon Web Services Systems Manager.

Despite the fact that application configuration content can vary greatly from application to application, 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 AppConfig to deploy configuration data stored in the AppConfig hosted configuration store, Secrets Manager, Systems Manager, Parameter Store, or Amazon S3.

How AppConfig works

This section provides a high-level description of how AppConfig works and how you get started.

1. Identify configuration values in code you want to manage in the cloud

Before you start creating AppConfig artifacts, we recommend you identify configuration data in your code that you want to dynamically manage using 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 AppConfig validation, deployment, and extension features to further streamline configuration data management.

2. Create an application namespace

To create a namespace, you create an AppConfig artifact called an application. An application is simply an organizational construct like a folder.

3. Create environments

For each AppConfig application, you define one or more environments. An environment is a logical grouping of targets, such as applications in a Beta or Production environment, Lambda functions, or containers. You can also define environments for application subcomponents, such as the Web, Mobile, and Back-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 AppConfig to locate your configuration data in its stored location and a profile type. AppConfig supports two configuration profile types: feature flags and freeform configurations. Feature flag configuration profiles store their data in the AppConfig hosted configuration store and the URI is simply hosted. For freeform configuration profiles, you can store your data in the AppConfig hosted configuration store or any Amazon Web Services service that integrates with AppConfig, as described in Creating a free form configuration profile  in the the AppConfig User Guide.

A configuration profile can also include optional validators to ensure your configuration data is syntactically and semantically correct. 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, AppConfig performs the following tasks:

  1. Retrieves the configuration data from the underlying data store by using the location URI in the configuration profile.

  2. Verifies the configuration data is syntactically and semantically correct by using the validators you specified when you created your configuration profile.

  3. 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 AppConfig Agent as a local host and have the agent poll 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. AppConfig Agent supports several use cases, as described in Simplified retrieval methods  in the the AppConfig User Guide.

If AppConfig Agent isn't supported for your use case, you can configure your application to poll AppConfig for configuration updates by directly calling the StartConfigurationSession  and GetLatestConfiguration  API actions.

This reference is intended to be used with the AppConfig User Guide .

Installation

NPM
npm install @aws-sdk/client-appconfig
Yarn
yarn add @aws-sdk/client-appconfig
pnpm
pnpm add @aws-sdk/client-appconfig

AppConfigClient Operations

Command
Summary
CreateApplicationCommand

Creates an application. In AppConfig, an application is simply an organizational construct like a folder. This organizational construct has a relationship with some unit of executable code. For example, you could create an application called MyMobileApp to organize and manage configuration data for a mobile application installed by your users.

CreateConfigurationProfileCommand

Creates a configuration profile, which is information that enables AppConfig to access the configuration source. Valid configuration sources include the following:

  • Configuration data in YAML, JSON, and other formats stored in the AppConfig hosted configuration store

  • Configuration data stored as objects in an Amazon Simple Storage Service (Amazon S3) bucket

  • Pipelines stored in CodePipeline

  • Secrets stored in Secrets Manager

  • Standard and secure string parameters stored in Amazon Web Services Systems Manager Parameter Store

  • Configuration data in SSM documents stored in the Systems Manager document store

A configuration profile includes the following information:

  • The URI location of the configuration data.

  • The Identity and Access Management (IAM) role that provides access to the configuration data.

  • A validator for the configuration data. Available validators include either a JSON Schema or an Amazon Web Services Lambda function.

For more information, see Create a Configuration and a Configuration Profile  in the AppConfig User Guide.

CreateDeploymentStrategyCommand

Creates a deployment strategy that defines important criteria for rolling out your configuration to the designated targets. A deployment strategy includes the overall duration required, a percentage of targets to receive the deployment during each interval, an algorithm that defines how percentage grows, and bake time.

CreateEnvironmentCommand

Creates an environment. For each application, you define one or more environments. An environment is a deployment 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 and Back-end components for your application. 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.

CreateExtensionAssociationCommand

When you create an extension or configure an Amazon Web Services authored extension, you associate the extension with an AppConfig application, environment, or configuration profile. For example, you can choose to run the AppConfig deployment events to Amazon SNS Amazon Web Services authored extension and receive notifications on an Amazon SNS topic anytime a configuration deployment is started for a specific application. Defining which extension to associate with an AppConfig resource is called an extension association. An extension association is a specified relationship between an extension and an AppConfig resource, such as an application or a configuration profile. For more information about extensions and associations, see Extending workflows  in the AppConfig User Guide.

CreateExtensionCommand

Creates an AppConfig extension. An extension augments your ability to inject logic or behavior at different points during the AppConfig workflow of creating or deploying a configuration.

You can create your own extensions or use the Amazon Web Services authored extensions provided by AppConfig. For an AppConfig extension that uses Lambda, you must create a Lambda function to perform any computation and processing defined in the extension. If you plan to create custom versions of the Amazon Web Services authored notification extensions, you only need to specify an Amazon Resource Name (ARN) in the Uri field for the new extension version.

  • For a custom EventBridge notification extension, enter the ARN of the EventBridge default events in the Uri field.

  • For a custom Amazon SNS notification extension, enter the ARN of an Amazon SNS topic in the Uri field.

  • For a custom Amazon SQS notification extension, enter the ARN of an Amazon SQS message queue in the Uri field.

For more information about extensions, see Extending workflows  in the AppConfig User Guide.

CreateHostedConfigurationVersionCommand

Creates a new configuration in the AppConfig hosted configuration store. If you're creating a feature flag, we recommend you familiarize yourself with the JSON schema for feature flag data. For more information, see Type reference for AWS.AppConfig.FeatureFlags  in the AppConfig User Guide.

DeleteApplicationCommand

Deletes an application.

DeleteConfigurationProfileCommand

Deletes a configuration profile.

To prevent users from unintentionally deleting actively-used configuration profiles, enable deletion protection .

DeleteDeploymentStrategyCommand

Deletes a deployment strategy.

DeleteEnvironmentCommand

Deletes an environment.

To prevent users from unintentionally deleting actively-used environments, enable deletion protection .

DeleteExtensionAssociationCommand

Deletes an extension association. This action doesn't delete extensions defined in the association.

DeleteExtensionCommand

Deletes an AppConfig extension. You must delete all associations to an extension before you delete the extension.

DeleteHostedConfigurationVersionCommand

Deletes a version of a configuration from the AppConfig hosted configuration store.

GetAccountSettingsCommand

Returns information about the status of the DeletionProtection parameter.

GetApplicationCommand

Retrieves information about an application.

GetConfigurationCommand

(Deprecated) Retrieves the latest deployed configuration.

Note the following important information.

GetConfigurationProfileCommand

Retrieves information about a configuration profile.

GetDeploymentCommand

Retrieves information about a configuration deployment.

GetDeploymentStrategyCommand

Retrieves information about a deployment strategy. A deployment strategy defines important criteria for rolling out your configuration to the designated targets. A deployment strategy includes the overall duration required, a percentage of targets to receive the deployment during each interval, an algorithm that defines how percentage grows, and bake time.

GetEnvironmentCommand

Retrieves information about an environment. An environment is a deployment group of AppConfig applications, such as applications in a Production environment or in an EU_Region environment. Each configuration deployment targets an environment. You can enable one or more Amazon CloudWatch alarms for an environment. If an alarm is triggered during a deployment, AppConfig roles back the configuration.

GetExtensionAssociationCommand

Returns information about an AppConfig extension association. For more information about extensions and associations, see Extending workflows  in the AppConfig User Guide.

GetExtensionCommand

Returns information about an AppConfig extension.

GetHostedConfigurationVersionCommand

Retrieves information about a specific configuration version.

ListApplicationsCommand

Lists all applications in your Amazon Web Services account.

ListConfigurationProfilesCommand

Lists the configuration profiles for an application.

ListDeploymentStrategiesCommand

Lists deployment strategies.

ListDeploymentsCommand

Lists the deployments for an environment in descending deployment number order.

ListEnvironmentsCommand

Lists the environments for an application.

ListExtensionAssociationsCommand

Lists all AppConfig extension associations in the account. For more information about extensions and associations, see Extending workflows  in the AppConfig User Guide.

ListExtensionsCommand

Lists all custom and Amazon Web Services authored AppConfig extensions in the account. For more information about extensions, see Extending workflows  in the AppConfig User Guide.

ListHostedConfigurationVersionsCommand

Lists configurations stored in the AppConfig hosted configuration store by version.

ListTagsForResourceCommand

Retrieves the list of key-value tags assigned to the resource.

StartDeploymentCommand

Starts a deployment.

StopDeploymentCommand

Stops a deployment. This API action works only on deployments that have a status of DEPLOYING, unless an AllowRevert parameter is supplied. If the AllowRevert parameter is supplied, the status of an in-progress deployment will be ROLLED_BACK. The status of a completed deployment will be REVERTED. AppConfig only allows a revert within 72 hours of deployment completion.

TagResourceCommand

Assigns metadata to an AppConfig resource. Tags help organize and categorize your AppConfig resources. Each tag consists of a key and an optional value, both of which you define. You can specify a maximum of 50 tags for a resource.

UntagResourceCommand

Deletes a tag key and value from an AppConfig resource.

UpdateAccountSettingsCommand

Updates the value of the DeletionProtection parameter.

UpdateApplicationCommand

Updates an application.

UpdateConfigurationProfileCommand

Updates a configuration profile.

UpdateDeploymentStrategyCommand

Updates a deployment strategy.

UpdateEnvironmentCommand

Updates an environment.

UpdateExtensionAssociationCommand

Updates an association. For more information about extensions and associations, see Extending workflows  in the AppConfig User Guide.

UpdateExtensionCommand

Updates an AppConfig extension. For more information about extensions, see Extending workflows  in the AppConfig User Guide.

ValidateConfigurationCommand

Uses the validators in a configuration profile to validate a configuration.

AppConfigClient Configuration

Parameter
Type
Description
defaultsMode
Optional
DefaultsMode | Provider<DefaultsMode>
The @smithy/smithy-client#DefaultsMode that will be used to determine how certain default configuration options are resolved in the SDK.
disableHostPrefix
Optional
boolean
Disable dynamically changing the endpoint of the client based on the hostPrefix trait of an operation.
extensions
Optional
RuntimeExtension[]
Optional extensions
logger
Optional
Logger
Optional logger for logging debug/info/warn/error.
maxAttempts
Optional
number | Provider<number>
Value for how many times a request will be made at most in case of retry.
profile
Optional
string
Setting a client profile is similar to setting a value for the AWS_PROFILE environment variable. Setting a profile on a client in code only affects the single client instance, unlike AWS_PROFILE.When set, and only for environments where an AWS configuration file exists, fields configurable by this file will be retrieved from the specified profile within that file. Conflicting code configuration and environment variables will still have higher priority.For client credential resolution that involves checking the AWS configuration file, the client's profile (this value) will be used unless a different profile is set in the credential provider options.
region
Optional
string | Provider<string>
The AWS region to which this client will send requests
requestHandler
Optional
__HttpHandlerUserInput
The HTTP handler to use or its constructor options. Fetch in browser and Https in Nodejs.
retryMode
Optional
string | Provider<string>
Specifies which retry algorithm to use.
useDualstackEndpoint
Optional
boolean | Provider<boolean>
Enables IPv6/IPv4 dualstack endpoint.
useFipsEndpoint
Optional
boolean | Provider<boolean>
Enables FIPS compatible endpoints.
Additional config fields are described in the full configuration type: AppConfigClientConfig