Package software.amazon.awscdk.services.appconfig


package software.amazon.awscdk.services.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:

 Application app = new Application(this, "MyApp");
 Environment env = Environment.Builder.create(this, "MyEnv")
         .application(app)
         .build();
 
 HostedConfiguration.Builder.create(this, "MyHostedConfig")
         .application(app)
         .deployTo(List.of(env))
         .content(ConfigurationContent.fromInlineText("This is my configuration content."))
         .build();
 

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;
 
 
 Environment.Builder.create(this, "MyEnvironment")
         .application(application)
         .monitors(List.of(Monitor.fromCloudWatchAlarm(alarm), Monitor.fromCloudWatchAlarm(compositeAlarm)))
         .build();
 

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.

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:

 DeploymentStrategy.Builder.create(this, "MyDeploymentStrategy")
         .rolloutStrategy(RolloutStrategy.CANARY_10_PERCENT_20_MINUTES)
         .build();
 

Deployment strategy with custom values:

 DeploymentStrategy.Builder.create(this, "MyDeploymentStrategy")
         .rolloutStrategy(RolloutStrategy.linear(RolloutStrategyProps.builder()
                 .growthFactor(20)
                 .deploymentDuration(Duration.minutes(30))
                 .finalBakeTime(Duration.minutes(30))
                 .build()))
         .build();
 

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:

  • fromFile - Defines the hosted configuration content from a file (you can specify a relative path). The content type will be determined by the file extension unless specified.

 Application application;
 
 
 HostedConfiguration.Builder.create(this, "MyHostedConfiguration")
         .application(application)
         .content(ConfigurationContent.fromFile("config.json"))
         .build();
 

  • fromInlineText - Defines the hosted configuration from inline text. The content type will be set as text/plain.

 Application application;
 
 
 HostedConfiguration.Builder.create(this, "MyHostedConfiguration")
         .application(application)
         .content(ConfigurationContent.fromInlineText("This is my configuration content."))
         .build();
 

  • fromInlineJson - Defines the hosted configuration from inline JSON. The content type will be set as application/json unless specified.

 Application application;
 
 
 HostedConfiguration.Builder.create(this, "MyHostedConfiguration")
         .application(application)
         .content(ConfigurationContent.fromInlineJson("{}"))
         .build();
 

  • fromInlineYaml - Defines the hosted configuration from inline YAML. The content type will be set as application/x-yaml.

 Application application;
 
 
 HostedConfiguration.Builder.create(this, "MyHostedConfiguration")
         .application(application)
         .content(ConfigurationContent.fromInlineYaml("MyConfig: This is my content."))
         .build();
 

  • fromInline - Defines the hosted configuration from user-specified content types. The content type will be set as application/octet-stream unless specified.

 Application application;
 
 
 HostedConfiguration.Builder.create(this, "MyHostedConfiguration")
         .application(application)
         .content(ConfigurationContent.fromInline("This is my configuration content."))
         .build();
 

AWS AppConfig supports the following types of configuration profiles.

  • Feature flag: Use a feature flag configuration to turn on new features that require a timely deployment, such as a product launch or announcement.
  • Freeform: Use a freeform configuration to carefully introduce changes to your application.

A hosted configuration with type:

 Application application;
 
 
 HostedConfiguration.Builder.create(this, "MyHostedConfiguration")
         .application(application)
         .content(ConfigurationContent.fromInlineText("This is my configuration content."))
         .type(ConfigurationType.FEATURE_FLAGS)
         .build();
 

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;
 
 
 HostedConfiguration.Builder.create(this, "MyHostedConfiguration")
         .application(application)
         .content(ConfigurationContent.fromInlineText("This is my configuration content."))
         .validators(List.of(JsonSchemaValidator.fromFile("schema.json"), LambdaValidator.fromFunction(fn)))
         .build();
 

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;
 
 
 HostedConfiguration.Builder.create(this, "MyHostedConfiguration")
         .application(application)
         .content(ConfigurationContent.fromInlineText("This is my configuration content."))
         .deploymentStrategy(DeploymentStrategy.Builder.create(this, "MyDeploymentStrategy")
                 .rolloutStrategy(RolloutStrategy.linear(RolloutStrategyProps.builder()
                         .growthFactor(15)
                         .deploymentDuration(Duration.minutes(30))
                         .finalBakeTime(Duration.minutes(15))
                         .build()))
                 .build())
         .build();
 

The deployTo parameter is used to specify which environments to deploy the configuration to. If this parameter is not specified, there will not be a deployment.

A hosted configuration with deployTo:

 Application application;
 Environment env;
 
 
 HostedConfiguration.Builder.create(this, "MyHostedConfiguration")
         .application(application)
         .content(ConfigurationContent.fromInlineText("This is my configuration content."))
         .deployTo(List.of(env))
         .build();
 

SourcedConfiguration

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

  • Amazon S3 bucket
  • AWS Secrets Manager secret
  • Systems Manager
  • (SSM) Parameter Store parameter
  • SSM document
  • AWS CodePipeline.

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;
 
 
 Bucket bucket = Bucket.Builder.create(this, "MyBucket")
         .versioned(true)
         .build();
 
 SourcedConfiguration.Builder.create(this, "MySourcedConfiguration")
         .application(application)
         .location(ConfigurationSource.fromBucket(bucket, "path/to/file.json"))
         .build();
 

Use an encrypted bucket:

 Application application;
 
 
 Bucket bucket = Bucket.Builder.create(this, "MyBucket")
         .versioned(true)
         .encryption(BucketEncryption.KMS)
         .build();
 
 SourcedConfiguration.Builder.create(this, "MySourcedConfiguration")
         .application(application)
         .location(ConfigurationSource.fromBucket(bucket, "path/to/file.json"))
         .build();
 

AWS Secrets Manager secret

Use a Secrets Manager secret to store a configuration.

 Application application;
 Secret secret;
 
 
 SourcedConfiguration.Builder.create(this, "MySourcedConfiguration")
         .application(application)
         .location(ConfigurationSource.fromSecret(secret))
         .build();
 

SSM Parameter Store parameter

Use an SSM parameter to store a configuration.

 Application application;
 StringParameter parameter;
 
 
 SourcedConfiguration.Builder.create(this, "MySourcedConfiguration")
         .application(application)
         .location(ConfigurationSource.fromParameter(parameter))
         .versionNumber("1")
         .build();
 

SSM document

Use an SSM document to store a configuration.

 Application application;
 CfnDocument document;
 
 
 SourcedConfiguration.Builder.create(this, "MySourcedConfiguration")
         .application(application)
         .location(ConfigurationSource.fromCfnDocument(document))
         .build();
 

AWS CodePipeline

Use an AWS CodePipeline pipeline to store a configuration.

 Application application;
 Pipeline pipeline;
 
 
 SourcedConfiguration.Builder.create(this, "MySourcedConfiguration")
         .application(application)
         .location(ConfigurationSource.fromPipeline(pipeline))
         .build();
 

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;
 
 
 SourcedConfiguration.Builder.create(this, "MySourcedConfiguration")
         .application(application)
         .location(ConfigurationSource.fromBucket(bucket, "path/to/file.json"))
         .type(ConfigurationType.FEATURE_FLAGS)
         .name("MyConfig")
         .description("This is my sourced configuration from CDK.")
         .build();
 

A sourced configuration with validators:

 Application application;
 Bucket bucket;
 Function fn;
 
 
 SourcedConfiguration.Builder.create(this, "MySourcedConfiguration")
         .application(application)
         .location(ConfigurationSource.fromBucket(bucket, "path/to/file.json"))
         .validators(List.of(JsonSchemaValidator.fromFile("schema.json"), LambdaValidator.fromFunction(fn)))
         .build();
 

A sourced configuration with a deployment strategy:

 Application application;
 Bucket bucket;
 
 
 SourcedConfiguration.Builder.create(this, "MySourcedConfiguration")
         .application(application)
         .location(ConfigurationSource.fromBucket(bucket, "path/to/file.json"))
         .deploymentStrategy(DeploymentStrategy.Builder.create(this, "MyDeploymentStrategy")
                 .rolloutStrategy(RolloutStrategy.linear(RolloutStrategyProps.builder()
                         .growthFactor(15)
                         .deploymentDuration(Duration.minutes(30))
                         .finalBakeTime(Duration.minutes(15))
                         .build()))
                 .build())
         .build();
 

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;
 
 
 Extension.Builder.create(this, "MyExtension")
         .actions(List.of(
             Action.Builder.create()
                     .actionPoints(List.of(ActionPoint.ON_DEPLOYMENT_START))
                     .eventDestination(new LambdaDestination(fn))
                     .build()))
         .build();
 

Lambda extension with parameters:

 Function fn;
 
 
 Extension.Builder.create(this, "MyExtension")
         .actions(List.of(
             Action.Builder.create()
                     .actionPoints(List.of(ActionPoint.ON_DEPLOYMENT_START))
                     .eventDestination(new LambdaDestination(fn))
                     .build()))
         .parameters(List.of(Parameter.required("testParam", "true"), Parameter.notRequired("testNotRequiredParam")))
         .build();
 

Amazon Simple Queue Service (SQS) destination

Use a queue as the event destination for an extension.

 Queue queue;
 
 
 Extension.Builder.create(this, "MyExtension")
         .actions(List.of(
             Action.Builder.create()
                     .actionPoints(List.of(ActionPoint.ON_DEPLOYMENT_START))
                     .eventDestination(new SqsDestination(queue))
                     .build()))
         .build();
 

Amazon Simple Notification Service (SNS) destination

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

 Topic topic;
 
 
 Extension.Builder.create(this, "MyExtension")
         .actions(List.of(
             Action.Builder.create()
                     .actionPoints(List.of(ActionPoint.ON_DEPLOYMENT_START))
                     .eventDestination(new SnsDestination(topic))
                     .build()))
         .build();
 

Amazon EventBridge destination

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

 IEventBus bus = EventBus.fromEventBusName(this, "MyEventBus", "default");
 
 Extension.Builder.create(this, "MyExtension")
         .actions(List.of(
             Action.Builder.create()
                     .actionPoints(List.of(ActionPoint.ON_DEPLOYMENT_START))
                     .eventDestination(new EventBridgeDestination(bus))
                     .build()))
         .build();
 

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);