Namespace Amazon.CDK.AWS.AppConfig

AWS AppConfig Construct Library

This module is part of the AWS Cloud Development Kit project.

For a high level overview of what AWS AppConfig is and how it works, please take a look here: What is AWS AppConfig?

Basic Hosted Configuration Use Case

The main way most AWS AppConfig users utilize the service is through hosted configuration, which involves storing
configuration data directly within AWS AppConfig.

An example use case:

var app = new Application(this, "MyApp");
var env = new Environment(this, "MyEnv", new EnvironmentProps {
    Application = app
});

new HostedConfiguration(this, "MyHostedConfig", new HostedConfigurationProps {
    Application = app,
    DeployTo = new [] { env },
    Content = ConfigurationContent.FromInlineText("This is my configuration content.")
});

This will create the application and environment for your configuration and then deploy your configuration to the specified environment.

For more information about what these resources are: Creating feature flags and free form configuration data in AWS AppConfig.

For more information about deploying configuration: Deploying feature flags and configuration data in AWS AppConfig

For an in-depth walkthrough of specific resources and how to use them, please take a look at the following sections.

Application

AWS AppConfig Application Documentation

In AWS AppConfig, an application is simply an organizational construct like a folder. Configurations and environments are associated with the application.

When creating an application through CDK, the name and description of an application are optional.

Create a simple application:

new Application(this, "MyApplication");

Environment

AWS AppConfig Environment Documentation

Basic environment with monitors:

Application application;
Alarm alarm;
CompositeAlarm compositeAlarm;


new Environment(this, "MyEnvironment", new EnvironmentProps {
    Application = application,
    Monitors = new [] { Monitor.FromCloudWatchAlarm(alarm), Monitor.FromCloudWatchAlarm(compositeAlarm) }
});

Environment monitors also support L1 CfnEnvironment.MonitorsProperty constructs through the fromCfnMonitorsProperty method. However, this is not the recommended approach for CloudWatch alarms because a role will not be auto-generated if not provided.

See About the AWS AppConfig data plane service for more information.

Permissions

You can grant read permission on the environment's configurations with the grantReadConfig method as follows:

using Amazon.CDK.AWS.IAM;


var app = new Application(this, "MyAppConfig");
var env = new Environment(this, "MyEnvironment", new EnvironmentProps {
    Application = app
});

var user = new User(this, "MyUser");
env.GrantReadConfig(user);

Deployment Strategy

AWS AppConfig Deployment Strategy Documentation

A deployment strategy defines how a configuration will roll out. The roll out is defined by four parameters: deployment type, growth factor, deployment duration, and final bake time.

Deployment strategy with predefined values:

new DeploymentStrategy(this, "MyDeploymentStrategy", new DeploymentStrategyProps {
    RolloutStrategy = RolloutStrategy.CANARY_10_PERCENT_20_MINUTES
});

Deployment strategy with custom values:

new DeploymentStrategy(this, "MyDeploymentStrategy", new DeploymentStrategyProps {
    RolloutStrategy = RolloutStrategy.Linear(new RolloutStrategyProps {
        GrowthFactor = 20,
        DeploymentDuration = Duration.Minutes(30),
        FinalBakeTime = Duration.Minutes(30)
    })
});

Referencing a deployment strategy by ID:

DeploymentStrategy.FromDeploymentStrategyId(this, "MyImportedDeploymentStrategy", DeploymentStrategyId.FromString("abc123"));

Referencing an AWS AppConfig predefined deployment strategy by ID:

DeploymentStrategy.FromDeploymentStrategyId(this, "MyImportedPredefinedDeploymentStrategy", DeploymentStrategyId.CANARY_10_PERCENT_20_MINUTES);

Configuration

A configuration is a higher-level construct that can either be a HostedConfiguration (stored internally through AWS AppConfig) or a SourcedConfiguration (stored in an Amazon S3 bucket, AWS Secrets Manager secrets, Systems Manager (SSM) Parameter Store parameters, SSM documents, or AWS CodePipeline). This construct manages deployments on creation.

HostedConfiguration

A hosted configuration represents configuration stored in the AWS AppConfig hosted configuration store. A hosted configuration takes in the configuration content and associated AWS AppConfig application. On construction of a hosted configuration, the configuration is deployed.

You can define hosted configuration content using any of the following ConfigurationContent methods:

Application application;


new HostedConfiguration(this, "MyHostedConfiguration", new HostedConfigurationProps {
    Application = application,
    Content = ConfigurationContent.FromFile("config.json")
});

Application application;


new HostedConfiguration(this, "MyHostedConfiguration", new HostedConfigurationProps {
    Application = application,
    Content = ConfigurationContent.FromInlineText("This is my configuration content.")
});

Application application;


new HostedConfiguration(this, "MyHostedConfiguration", new HostedConfigurationProps {
    Application = application,
    Content = ConfigurationContent.FromInlineJson("{}")
});

Application application;


new HostedConfiguration(this, "MyHostedConfiguration", new HostedConfigurationProps {
    Application = application,
    Content = ConfigurationContent.FromInlineYaml("MyConfig: This is my content.")
});

Application application;


new HostedConfiguration(this, "MyHostedConfiguration", new HostedConfigurationProps {
    Application = application,
    Content = ConfigurationContent.FromInline("This is my configuration content.")
});

AWS AppConfig supports the following types of configuration profiles.

A hosted configuration with type:

Application application;


new HostedConfiguration(this, "MyHostedConfiguration", new HostedConfigurationProps {
    Application = application,
    Content = ConfigurationContent.FromInlineText("This is my configuration content."),
    Type = ConfigurationType.FEATURE_FLAGS
});

When you create a configuration and configuration profile, you can specify up to two validators. A validator ensures that your configuration data is syntactically and semantically correct. You can create validators in either JSON Schema or as an AWS Lambda function. See About validators for more information.

When you import a JSON Schema validator from a file, you can pass in a relative path.

A hosted configuration with validators:

Application application;
Function fn;


new HostedConfiguration(this, "MyHostedConfiguration", new HostedConfigurationProps {
    Application = application,
    Content = ConfigurationContent.FromInlineText("This is my configuration content."),
    Validators = new [] { JsonSchemaValidator.FromFile("schema.json"), LambdaValidator.FromFunction(fn) }
});

You can attach a deployment strategy (as described in the previous section) to your configuration to specify how you want your configuration to roll out.

A hosted configuration with a deployment strategy:

Application application;


new HostedConfiguration(this, "MyHostedConfiguration", new HostedConfigurationProps {
    Application = application,
    Content = ConfigurationContent.FromInlineText("This is my configuration content."),
    DeploymentStrategy = new DeploymentStrategy(this, "MyDeploymentStrategy", new DeploymentStrategyProps {
        RolloutStrategy = RolloutStrategy.Linear(new RolloutStrategyProps {
            GrowthFactor = 15,
            DeploymentDuration = Duration.Minutes(30),
            FinalBakeTime = Duration.Minutes(15)
        })
    })
});

The deployTo parameter is used to specify which environments to deploy the configuration to.

A hosted configuration with deployTo:

Application application;
Environment env;


new HostedConfiguration(this, "MyHostedConfiguration", new HostedConfigurationProps {
    Application = application,
    Content = ConfigurationContent.FromInlineText("This is my configuration content."),
    DeployTo = new [] { env }
});

When more than one configuration is set to deploy to the same environment, the deployments will occur one at a time. This is done to satisfy AppConfig's constraint:

[!NOTE]
You can only deploy one configuration at a time to an environment.
However, you can deploy one configuration each to different environments at the same time.

The deployment order matches the order in which the configurations are declared.

var app = new Application(this, "MyApp");
var env = new Environment(this, "MyEnv", new EnvironmentProps {
    Application = app
});

new HostedConfiguration(this, "MyFirstHostedConfig", new HostedConfigurationProps {
    Application = app,
    DeployTo = new [] { env },
    Content = ConfigurationContent.FromInlineText("This is my first configuration content.")
});

new HostedConfiguration(this, "MySecondHostedConfig", new HostedConfigurationProps {
    Application = app,
    DeployTo = new [] { env },
    Content = ConfigurationContent.FromInlineText("This is my second configuration content.")
});

If an application would benefit from a deployment order that differs from the declared order, you can defer the decision by using IEnvironment.addDeployment rather than the deployTo property. In this example, firstConfig will be deployed before secondConfig.

var app = new Application(this, "MyApp");
var env = new Environment(this, "MyEnv", new EnvironmentProps {
    Application = app
});

var secondConfig = new HostedConfiguration(this, "MySecondHostedConfig", new HostedConfigurationProps {
    Application = app,
    Content = ConfigurationContent.FromInlineText("This is my second configuration content.")
});

var firstConfig = new HostedConfiguration(this, "MyFirstHostedConfig", new HostedConfigurationProps {
    Application = app,
    DeployTo = new [] { env },
    Content = ConfigurationContent.FromInlineText("This is my first configuration content.")
});

env.AddDeployment(secondConfig);

Alternatively, you can defer multiple deployments in favor of IEnvironment.addDeployments, which allows you to declare multiple configurations in the order they will be deployed. In this example the deployment order will be firstConfig, then secondConfig, and finally thirdConfig.

var app = new Application(this, "MyApp");
var env = new Environment(this, "MyEnv", new EnvironmentProps {
    Application = app
});

var secondConfig = new HostedConfiguration(this, "MySecondHostedConfig", new HostedConfigurationProps {
    Application = app,
    Content = ConfigurationContent.FromInlineText("This is my second configuration content.")
});

var thirdConfig = new HostedConfiguration(this, "MyThirdHostedConfig", new HostedConfigurationProps {
    Application = app,
    Content = ConfigurationContent.FromInlineText("This is my third configuration content.")
});

var firstConfig = new HostedConfiguration(this, "MyFirstHostedConfig", new HostedConfigurationProps {
    Application = app,
    Content = ConfigurationContent.FromInlineText("This is my first configuration content.")
});

env.AddDeployments(firstConfig, secondConfig, thirdConfig);

Any mix of deployTo, addDeployment, and addDeployments is permitted. The declaration order will be respected regardless of the approach used.

[!IMPORTANT]
If none of these options are utilized, there will not be any deployments.

SourcedConfiguration

A sourced configuration represents configuration stored in any of the following:

A sourced configuration takes in the location source construct and optionally a version number to deploy. On construction of a sourced configuration, the configuration is deployed only if a version number is specified.

S3

Use an Amazon S3 bucket to store a configuration.

Application application;


var bucket = new Bucket(this, "MyBucket", new BucketProps {
    Versioned = true
});

new SourcedConfiguration(this, "MySourcedConfiguration", new SourcedConfigurationProps {
    Application = application,
    Location = ConfigurationSource.FromBucket(bucket, "path/to/file.json")
});

Use an encrypted bucket:

Application application;


var bucket = new Bucket(this, "MyBucket", new BucketProps {
    Versioned = true,
    Encryption = BucketEncryption.KMS
});

new SourcedConfiguration(this, "MySourcedConfiguration", new SourcedConfigurationProps {
    Application = application,
    Location = ConfigurationSource.FromBucket(bucket, "path/to/file.json")
});

AWS Secrets Manager secret

Use a Secrets Manager secret to store a configuration.

Application application;
Secret secret;


new SourcedConfiguration(this, "MySourcedConfiguration", new SourcedConfigurationProps {
    Application = application,
    Location = ConfigurationSource.FromSecret(secret)
});

SSM Parameter Store parameter

Use an SSM parameter to store a configuration.

Application application;
StringParameter parameter;


new SourcedConfiguration(this, "MySourcedConfiguration", new SourcedConfigurationProps {
    Application = application,
    Location = ConfigurationSource.FromParameter(parameter),
    VersionNumber = "1"
});

SSM document

Use an SSM document to store a configuration.

Application application;
CfnDocument document;


new SourcedConfiguration(this, "MySourcedConfiguration", new SourcedConfigurationProps {
    Application = application,
    Location = ConfigurationSource.FromCfnDocument(document)
});

AWS CodePipeline

Use an AWS CodePipeline pipeline to store a configuration.

Application application;
Pipeline pipeline;


new SourcedConfiguration(this, "MySourcedConfiguration", new SourcedConfigurationProps {
    Application = application,
    Location = ConfigurationSource.FromPipeline(pipeline)
});

Similar to a hosted configuration, a sourced configuration can optionally take in a type, validators, a deployTo parameter, and a deployment strategy.

A sourced configuration with type:

Application application;
Bucket bucket;


new SourcedConfiguration(this, "MySourcedConfiguration", new SourcedConfigurationProps {
    Application = application,
    Location = ConfigurationSource.FromBucket(bucket, "path/to/file.json"),
    Type = ConfigurationType.FEATURE_FLAGS,
    Name = "MyConfig",
    Description = "This is my sourced configuration from CDK."
});

A sourced configuration with validators:

Application application;
Bucket bucket;
Function fn;


new SourcedConfiguration(this, "MySourcedConfiguration", new SourcedConfigurationProps {
    Application = application,
    Location = ConfigurationSource.FromBucket(bucket, "path/to/file.json"),
    Validators = new [] { JsonSchemaValidator.FromFile("schema.json"), LambdaValidator.FromFunction(fn) }
});

A sourced configuration with a deployment strategy:

Application application;
Bucket bucket;


new SourcedConfiguration(this, "MySourcedConfiguration", new SourcedConfigurationProps {
    Application = application,
    Location = ConfigurationSource.FromBucket(bucket, "path/to/file.json"),
    DeploymentStrategy = new DeploymentStrategy(this, "MyDeploymentStrategy", new DeploymentStrategyProps {
        RolloutStrategy = RolloutStrategy.Linear(new RolloutStrategyProps {
            GrowthFactor = 15,
            DeploymentDuration = Duration.Minutes(30),
            FinalBakeTime = Duration.Minutes(15)
        })
    })
});

Extension

An extension augments your ability to inject logic or behavior at different points during the AWS AppConfig workflow of creating or deploying a configuration. See: https://docs.aws.amazon.com/appconfig/latest/userguide/working-with-appconfig-extensions.html

AWS Lambda destination

Use an AWS Lambda as the event destination for an extension.

Function fn;


new Extension(this, "MyExtension", new ExtensionProps {
    Actions = new [] {
        new Action(new ActionProps {
            ActionPoints = new [] { ActionPoint.ON_DEPLOYMENT_START },
            EventDestination = new LambdaDestination(fn)
        }) }
});

Lambda extension with parameters:

Function fn;


new Extension(this, "MyExtension", new ExtensionProps {
    Actions = new [] {
        new Action(new ActionProps {
            ActionPoints = new [] { ActionPoint.ON_DEPLOYMENT_START },
            EventDestination = new LambdaDestination(fn)
        }) },
    Parameters = new [] { Parameter.Required("testParam", "true"), Parameter.NotRequired("testNotRequiredParam") }
});

Amazon Simple Queue Service (SQS) destination

Use a queue as the event destination for an extension.

Queue queue;


new Extension(this, "MyExtension", new ExtensionProps {
    Actions = new [] {
        new Action(new ActionProps {
            ActionPoints = new [] { ActionPoint.ON_DEPLOYMENT_START },
            EventDestination = new SqsDestination(queue)
        }) }
});

Amazon Simple Notification Service (SNS) destination

Use an SNS topic as the event destination for an extension.

Topic topic;


new Extension(this, "MyExtension", new ExtensionProps {
    Actions = new [] {
        new Action(new ActionProps {
            ActionPoints = new [] { ActionPoint.ON_DEPLOYMENT_START },
            EventDestination = new SnsDestination(topic)
        }) }
});

Amazon EventBridge destination

Use the default event bus as the event destination for an extension.

var bus = EventBus.FromEventBusName(this, "MyEventBus", "default");

new Extension(this, "MyExtension", new ExtensionProps {
    Actions = new [] {
        new Action(new ActionProps {
            ActionPoints = new [] { ActionPoint.ON_DEPLOYMENT_START },
            EventDestination = new EventBridgeDestination(bus)
        }) }
});

You can also add extensions and their associations directly by calling onDeploymentComplete() or any other action point method on the AWS AppConfig application, configuration, or environment resource. To add an association to an existing extension, you can call addExtension() on the resource.

Adding an association to an AWS AppConfig application:

Application application;
Extension extension;
LambdaDestination lambdaDestination;


application.AddExtension(extension);
application.OnDeploymentComplete(lambdaDestination);

Classes

Action	Defines an action for an extension.
ActionPoint	Defines Extension action points.
ActionProps	Properties for the Action construct.
Application	An AWS AppConfig application.
ApplicationProps	Properties for the Application construct.
CfnApplication	The `AWS::AppConfig::Application` resource creates an application.
CfnApplicationProps	Properties for defining a `CfnApplication`.
CfnConfigurationProfile	The `AWS::AppConfig::ConfigurationProfile` resource creates a configuration profile that enables AWS AppConfig to access the configuration source.
CfnConfigurationProfile.ValidatorsProperty	A validator provides a syntactic or semantic check to ensure the configuration that you want to deploy functions as intended.
CfnConfigurationProfileProps	Properties for defining a `CfnConfigurationProfile`.
CfnDeployment	The `AWS::AppConfig::Deployment` resource starts a deployment.
CfnDeployment.DynamicExtensionParametersProperty	A map of dynamic extension parameter names to values to pass to associated extensions with `PRE_START_DEPLOYMENT` actions.
CfnDeploymentProps	Properties for defining a `CfnDeployment`.
CfnDeploymentStrategy	The `AWS::AppConfig::DeploymentStrategy` resource creates an AWS AppConfig deployment strategy.
CfnDeploymentStrategyProps	Properties for defining a `CfnDeploymentStrategy`.
CfnEnvironment	The `AWS::AppConfig::Environment` resource creates an environment, which is a logical deployment group of AWS AppConfig targets, such as applications in a `Beta` or `Production` environment.
CfnEnvironment.MonitorProperty	Amazon CloudWatch alarms to monitor during the deployment process.
CfnEnvironment.MonitorsProperty
CfnEnvironmentProps	Properties for defining a `CfnEnvironment`.
CfnExtension	Creates an AWS AppConfig extension.
CfnExtension.ActionProperty	The actions defined in the extension.
CfnExtension.ParameterProperty	A value such as an Amazon Resource Name (ARN) or an Amazon Simple Notification Service topic entered in an extension when invoked.
CfnExtensionAssociation	When you create an extension or configure an AWS authored extension, you associate the extension with an AWS AppConfig application, environment, or configuration profile.
CfnExtensionAssociationProps	Properties for defining a `CfnExtensionAssociation`.
CfnExtensionProps	Properties for defining a `CfnExtension`.
CfnHostedConfigurationVersion	Create a new configuration in the AWS AppConfig hosted configuration store.
CfnHostedConfigurationVersionProps	Properties for defining a `CfnHostedConfigurationVersion`.
ConfigurationContent	Defines the hosted configuration content.
ConfigurationOptions	Options for the Configuration construct.
ConfigurationProps	Properties for the Configuration construct.
ConfigurationSource	Defines the integrated configuration sources.
ConfigurationSourceType	The configuration source type.
ConfigurationType	The configuration type.
DeploymentStrategy	An AWS AppConfig deployment strategy.
DeploymentStrategyId	Defines the deployment strategy ID's of AWS AppConfig deployment strategies.
DeploymentStrategyProps	Properties for DeploymentStrategy.
Environment	An AWS AppConfig environment.
EnvironmentAttributes	Attributes of an existing AWS AppConfig environment to import it.
EnvironmentOptions	Options for the Environment construct.
EnvironmentProps	Properties for the Environment construct.
EventBridgeDestination	Use an Amazon EventBridge event bus as an event destination.
ExtensibleBase	This class is meant to be used by AWS AppConfig resources (application, configuration profile, environment) directly.
Extension	An AWS AppConfig extension.
ExtensionAttributes	Attributes of an existing AWS AppConfig extension to import.
ExtensionOptions	Options for the Extension construct.
ExtensionProps	Properties for the Extension construct.
GrowthType	Defines the growth type of the deployment strategy.
HostedConfiguration	A hosted configuration represents configuration stored in the AWS AppConfig hosted configuration store.
HostedConfigurationOptions	Options for HostedConfiguration.
HostedConfigurationProps	Properties for HostedConfiguration.
JsonSchemaValidator	Defines a JSON Schema validator.
LambdaDestination	Use an AWS Lambda function as an event destination.
LambdaValidator	Defines an AWS Lambda validator.
Monitor	Defines monitors that will be associated with an AWS AppConfig environment.
MonitorType	The type of Monitor.
Parameter	Defines a parameter for an extension.
Platform	Defines the platform for the AWS AppConfig Lambda extension.
RolloutStrategy	Defines the rollout strategy for a deployment strategy and includes the growth factor, deployment duration, growth type, and optionally final bake time.
RolloutStrategyProps	Properties for the Rollout Strategy.
SnsDestination	Use an Amazon SNS topic as an event destination.
SourcedConfiguration	A sourced configuration represents configuration stored in an Amazon S3 bucket, AWS Secrets Manager secret, Systems Manager (SSM) Parameter Store parameter, SSM document, or AWS CodePipeline.
SourcedConfigurationOptions	Options for SourcedConfiguration.
SourcedConfigurationProps	Properties for SourcedConfiguration.
SourceType	Defines the source type for event destinations.
SqsDestination	Use an Amazon SQS queue as an event destination.
ValidatorType	The validator type.

Interfaces

CfnConfigurationProfile.IValidatorsProperty	A validator provides a syntactic or semantic check to ensure the configuration that you want to deploy functions as intended.
CfnDeployment.IDynamicExtensionParametersProperty	A map of dynamic extension parameter names to values to pass to associated extensions with `PRE_START_DEPLOYMENT` actions.
CfnEnvironment.IMonitorProperty	Amazon CloudWatch alarms to monitor during the deployment process.
CfnEnvironment.IMonitorsProperty
CfnExtension.IActionProperty	The actions defined in the extension.
CfnExtension.IParameterProperty	A value such as an Amazon Resource Name (ARN) or an Amazon Simple Notification Service topic entered in an extension when invoked.
IActionProps	Properties for the Action construct.
IApplication
IApplicationProps	Properties for the Application construct.
ICfnApplicationProps	Properties for defining a `CfnApplication`.
ICfnConfigurationProfileProps	Properties for defining a `CfnConfigurationProfile`.
ICfnDeploymentProps	Properties for defining a `CfnDeployment`.
ICfnDeploymentStrategyProps	Properties for defining a `CfnDeploymentStrategy`.
ICfnEnvironmentProps	Properties for defining a `CfnEnvironment`.
ICfnExtensionAssociationProps	Properties for defining a `CfnExtensionAssociation`.
ICfnExtensionProps	Properties for defining a `CfnExtension`.
ICfnHostedConfigurationVersionProps	Properties for defining a `CfnHostedConfigurationVersion`.
IConfiguration
IConfigurationOptions	Options for the Configuration construct.
IConfigurationProps	Properties for the Configuration construct.
IDeploymentStrategy
IDeploymentStrategyProps	Properties for DeploymentStrategy.
IEnvironment
IEnvironmentAttributes	Attributes of an existing AWS AppConfig environment to import it.
IEnvironmentOptions	Options for the Environment construct.
IEnvironmentProps	Properties for the Environment construct.
IEventDestination	Implemented by allowed extension event destinations.
IExtensible	Defines the extensible base implementation for extension association resources.
IExtension
IExtensionAttributes	Attributes of an existing AWS AppConfig extension to import.
IExtensionOptions	Options for the Extension construct.
IExtensionProps	Properties for the Extension construct.
IHostedConfigurationOptions	Options for HostedConfiguration.
IHostedConfigurationProps	Properties for HostedConfiguration.
IRolloutStrategyProps	Properties for the Rollout Strategy.
ISourcedConfigurationOptions	Options for SourcedConfiguration.
ISourcedConfigurationProps	Properties for SourcedConfiguration.
IValidator