Namespace Amazon.CDK

AWS Cloud Development Kit Core Library

---

---

This library includes the basic building blocks of the AWS Cloud Development Kit (AWS CDK). It defines the core classes that are used in the rest of the AWS Construct Library.

See the AWS CDK Developer Guide for information of most of the capabilities of this library. The rest of this README will only cover topics not already covered in the Developer Guide.

Stacks and Stages

A Stack is the smallest physical unit of deployment, and maps directly onto a CloudFormation Stack. You define a Stack by defining a subclass of Stack -- let's call it MyStack -- and instantiating the constructs that make up your application in MyStack's constructor. You then instantiate this stack one or more times to define different instances of your application. For example, you can instantiate it once using few and cheap EC2 instances for testing, and once again using more and bigger EC2 instances for production.

When your application grows, you may decide that it makes more sense to split it out across multiple Stack classes. This can happen for a number of reasons:

As soon as your conceptual application starts to encompass multiple stacks, it is convenient to wrap them in another construct that represents your logical application. You can then treat that new unit the same way you used to be able to treat a single stack: by instantiating it multiple times for different instances of your application.

You can define a custom subclass of Stage, holding one or more Stacks, to represent a single logical instance of your application.

As a final note: Stacks are not a unit of reuse. They describe physical deployment layouts, and as such are best left to application builders to organize their deployments with. If you want to vend a reusable construct, define it as a subclasses of Construct: the consumers of your construct will decide where to place it in their own stacks.

Nested Stacks

Nested stacks are stacks created as part of other stacks. You create a nested stack within another stack by using the NestedStack construct.

As your infrastructure grows, common patterns can emerge in which you declare the same components in multiple templates. You can separate out these common components and create dedicated templates for them. Then use the resource in your template to reference other templates, creating nested stacks.

For example, assume that you have a load balancer configuration that you use for most of your stacks. Instead of copying and pasting the same configurations into your templates, you can create a dedicated template for the load balancer. Then, you just use the resource to reference that template from within other templates.

The following example will define a single top-level stack that contains two nested stacks: each one with a single Amazon S3 bucket:

class MyNestedStack : NestedStack
{
    public MyNestedStack(Construct scope, string id, NestedStackProps? props=null) : base(scope, id, props)
    {

        new Bucket(this, "NestedBucket");
    }
}

class MyParentStack : Stack
{
    public MyParentStack(Construct scope, string id, StackProps? props=null) : base(scope, id, props)
    {

        new MyNestedStack(this, "Nested1");
        new MyNestedStack(this, "Nested2");
    }
}

Resources references across nested/parent boundaries (even with multiple levels of nesting) will be wired by the AWS CDK through CloudFormation parameters and outputs. When a resource from a parent stack is referenced by a nested stack, a CloudFormation parameter will automatically be added to the nested stack and assigned from the parent; when a resource from a nested stack is referenced by a parent stack, a CloudFormation output will be automatically be added to the nested stack and referenced using Fn::GetAtt "Outputs.Xxx" from the parent.

Nested stacks also support the use of Docker image and file assets.

Accessing resources in a different stack

You can access resources in a different stack, as long as they are in the same account and AWS Region. The following example defines the stack stack1, which defines an Amazon S3 bucket. Then it defines a second stack, stack2, which takes the bucket from stack1 as a constructor property.

IDictionary<string, string> prod = new Dictionary<string, string> { { "account", "123456789012" }, { "region", "us-east-1" } };

StackThatProvidesABucket stack1 = new StackThatProvidesABucket(app, "Stack1", new StackProps { Env = prod });

// stack2 will take a property { bucket: IBucket }
StackThatExpectsABucket stack2 = new StackThatExpectsABucket(app, "Stack2", new StackThatExpectsABucketProps {
    Bucket = stack1.Bucket,
    Env = prod
});

If the AWS CDK determines that the resource is in the same account and Region, but in a different stack, it automatically synthesizes AWS CloudFormation Exports in the producing stack and an Fn::ImportValue in the consuming stack to transfer that information from one stack to the other.

Removing automatic cross-stack references

The automatic references created by CDK when you use resources across stacks are convenient, but may block your deployments if you want to remove the resources that are referenced in this way. You will see an error like:

Export Stack1:ExportsOutputFnGetAtt-****** cannot be deleted as it is in use by Stack1

Let's say there is a Bucket in the stack1, and the stack2 references its bucket.bucketName. You now want to remove the bucket and run into the error above.

It's not safe to remove stack1.bucket while stack2 is still using it, so unblocking yourself from this is a two-step process. This is how it works:

DEPLOYMENT 1: break the relationship

DEPLOYMENT 2: remove the resource

Durations

To make specifications of time intervals unambiguous, a single class called Duration is used throughout the AWS Construct Library by all constructs that that take a time interval as a parameter (be it for a timeout, a rate, or something else).

An instance of Duration is constructed by using one of the static factory methods on it:

Duration.Seconds(300); // 5 minutes
Duration.Minutes(5); // 5 minutes
Duration.Hours(1); // 1 hour
Duration.Days(7); // 7 days
Duration.Parse("PT5M");

Durations can be added or subtracted together:

Duration.Minutes(1).Plus(Duration.Seconds(60)); // 2 minutes
Duration.Minutes(5).Minus(Duration.Seconds(10));

Size (Digital Information Quantity)

To make specification of digital storage quantities unambiguous, a class called Size is available.

An instance of Size is initialized through one of its static factory methods:

Size.Kibibytes(200); // 200 KiB
Size.Mebibytes(5); // 5 MiB
Size.Gibibytes(40); // 40 GiB
Size.Tebibytes(200); // 200 TiB
Size.Pebibytes(3);

Instances of Size created with one of the units can be converted into others. By default, conversion to a higher unit will fail if the conversion does not produce a whole number. This can be overridden by unsetting integral property.

Size.Mebibytes(2).ToKibibytes(); // yields 2048
Size.Kibibytes(2050).ToMebibytes(new SizeConversionOptions { Rounding = SizeRoundingBehavior.FLOOR });

Secrets

To help avoid accidental storage of secrets as plain text, we use the SecretValue type to represent secrets. Any construct that takes a value that should be a secret (such as a password or an access key) will take a parameter of type SecretValue.

The best practice is to store secrets in AWS Secrets Manager and reference them using SecretValue.secretsManager:

SecretValue secret = SecretValue.SecretsManager("secretId", new SecretsManagerSecretOptions {
    JsonField = "password",  // optional: key of a JSON field to retrieve (defaults to all content),
    VersionId = "id",  // optional: id of the version (default AWSCURRENT)
    VersionStage = "stage"
});

Using AWS Secrets Manager is the recommended way to reference secrets in a CDK app. SecretValue also supports the following secret sources:

ARN manipulation

Sometimes you will need to put together or pick apart Amazon Resource Names (ARNs). The functions stack.formatArn() and stack.parseArn() exist for this purpose.

formatArn() can be used to build an ARN from components. It will automatically use the region and account of the stack you're calling it on:

Stack stack;


// Builds "arn:<PARTITION>:lambda:<REGION>:<ACCOUNT>:function:MyFunction"
stack.FormatArn(new ArnComponents {
    Service = "lambda",
    Resource = "function",
    Sep = ":",
    ResourceName = "MyFunction"
});

parseArn() can be used to get a single component from an ARN. parseArn() will correctly deal with both literal ARNs and deploy-time values (tokens), but in case of a deploy-time value be aware that the result will be another deploy-time value which cannot be inspected in the CDK application.

Stack stack;


// Extracts the function name out of an AWS Lambda Function ARN
ArnComponents arnComponents = stack.ParseArn(arn, ":");
string? functionName = arnComponents.ResourceName;

Note that depending on the service, the resource separator can be either : or /, and the resource name can be either the 6th or 7th component in the ARN. When using these functions, you will need to know the format of the ARN you are dealing with.

For an exhaustive list of ARN formats used in AWS, see AWS ARNs and Namespaces in the AWS General Reference.

Dependencies

Construct Dependencies

Sometimes AWS resources depend on other resources, and the creation of one resource must be completed before the next one can be started.

In general, CloudFormation will correctly infer the dependency relationship between resources based on the property values that are used. In the cases where it doesn't, the AWS Construct Library will add the dependency relationship for you.

If you need to add an ordering dependency that is not automatically inferred, you do so by adding a dependency relationship using constructA.node.addDependency(constructB). This will add a dependency relationship between all resources in the scope of constructA and all resources in the scope of constructB.

If you want a single object to represent a set of constructs that are not necessarily in the same scope, you can use a ConcreteDependable. The following creates a single object that represents a dependency on two constructs, constructB and constructC:

// Declare the dependable object
ConcreteDependable bAndC = new ConcreteDependable();
bAndC.Add(constructB);
bAndC.Add(constructC);

// Take the dependency
constructA.Node.AddDependency(bAndC);

Stack Dependencies

Two different stack instances can have a dependency on one another. This happens when an resource from one stack is referenced in another stack. In that case, CDK records the cross-stack referencing of resources, automatically produces the right CloudFormation primitives, and adds a dependency between the two stacks. You can also manually add a dependency between two stacks by using the stackA.addDependency(stackB) method.

A stack dependency has the following implications:

Custom Resources

Custom Resources are CloudFormation resources that are implemented by arbitrary user code. They can do arbitrary lookups or modifications during a CloudFormation deployment.

To define a custom resource, use the CustomResource construct:

new CustomResource(this, "MyMagicalResource", new CustomResourceProps {
    ResourceType = "Custom::MyCustomResource",  // must start with 'Custom::'

    // the resource properties
    Properties = new Dictionary<string, object> {
        { "Property1", "foo" },
        { "Property2", "bar" }
    },

    // the ARN of the provider (SNS/Lambda) which handles
    // CREATE, UPDATE or DELETE events for this resource type
    // see next section for details
    ServiceToken = "ARN"
});

Custom Resource Providers

Custom resources are backed by a custom resource provider which can be implemented in one of the following ways. The following table compares the various provider types (ordered from low-level to high-level):

Provider	Compute Type	Error Handling	Submit to CloudFormation	Max Timeout	Language	Footprint
sns.Topic	Self-managed	Manual	Manual	Unlimited	Any	Depends
lambda.Function	AWS Lambda	Manual	Manual	15min	Any	Small
core.CustomResourceProvider	Lambda	Auto	Auto	15min	Node.js	Small
custom-resources.Provider	Lambda	Auto	Auto	Unlimited Async	Any	Large

Legend:

A NOTE ABOUT SINGLETONS

When defining resources for a custom resource provider, you will likely want to define them as a stack singleton so that only a single instance of the provider is created in your stack and which is used by all custom resources of that type.

Here is a basic pattern for defining stack singletons in the CDK. The following examples ensures that only a single SNS topic is defined:

public Topic GetOrCreate(Construct scope)
{
    Stack stack = Stack.Of(scope);
    string uniqueid = "GloballyUniqueIdForSingleton"; // For example, a UUID from `uuidgen`
    IConstruct? existing = stack.Node.TryFindChild(uniqueid);
    if (existing)
    {
        return (Topic)existing;
    }
    return new Topic(stack, uniqueid);
}

Amazon SNS Topic

Every time a resource event occurs (CREATE/UPDATE/DELETE), an SNS notification is sent to the SNS topic. Users must process these notifications (e.g. through a fleet of worker hosts) and submit success/failure responses to the CloudFormation service.

Set serviceToken to topic.topicArn in order to use this provider:

Topic topic = new Topic(this, "MyProvider");

new CustomResource(this, "MyResource", new CustomResourceProps {
    ServiceToken = topic.TopicArn
});

AWS Lambda Function

An AWS lambda function is called directly by CloudFormation for all resource events. The handler must take care of explicitly submitting a success/failure response to the CloudFormation service and handle various error cases.

Set serviceToken to lambda.functionArn to use this provider:

Function fn = new Function(this, "MyProvider", functionProps);

new CustomResource(this, "MyResource", new CustomResourceProps {
    ServiceToken = fn.FunctionArn
});

The core.CustomResourceProvider class

The class @aws-cdk/core.CustomResourceProvider offers a basic low-level framework designed to implement simple and slim custom resource providers. It currently only supports Node.js-based user handlers, and it does not have support for asynchronous waiting (handler cannot exceed the 15min lambda timeout).

The provider has a built-in singleton method which uses the resource type as a stack-unique identifier and returns the service token:

string serviceToken = CustomResourceProvider.GetOrCreate(this, "Custom::MyCustomResourceType", new CustomResourceProviderProps {
    CodeDirectory = $"{__dirname}/my-handler",
    Runtime = CustomResourceProviderRuntime.NODEJS_12_X,
    Description = "Lambda function created by the custom resource provider"
});

new CustomResource(this, "MyResource", new CustomResourceProps {
    ResourceType = "Custom::MyCustomResourceType",
    ServiceToken = serviceToken
});

The directory (my-handler in the above example) must include an index.js file. It cannot import external dependencies or files outside this directory. It must export an async function named handler. This function accepts the CloudFormation resource event object and returns an object with the following structure:

exports.handler = async function(event) {
  const id = event.PhysicalResourceId; // only for "Update" and "Delete"
  const props = event.ResourceProperties;
  const oldProps = event.OldResourceProperties; // only for "Update"s

  switch (event.RequestType) {
    case "Create":
      // ...

    case "Update":
      // ...

      // if an error is thrown, a FAILED response will be submitted to CFN
      throw new Error('Failed!');

    case "Delete":
      // ...
  }

  return {
    // (optional) the value resolved from `resource.ref`
    // defaults to "event.PhysicalResourceId" or "event.RequestId"
    PhysicalResourceId: "REF",

    // (optional) calling `resource.getAtt("Att1")` on the custom resource in the CDK app
    // will return the value "BAR".
    Data: {
      Att1: "BAR",
      Att2: "BAZ"
    },

    // (optional) user-visible message
    Reason: "User-visible message",

    // (optional) hides values from the console
    NoEcho: true
  };
}

Here is an complete example of a custom resource that summarizes two numbers:

sum-handler/index.js:

exports.handler = async (e) => {
  return {
    Data: {
      Result: e.ResourceProperties.lhs + e.ResourceProperties.rhs,
    },
  };
};

sum.ts:

using Amazon.CDK;

class SumProps
{
    public int Lhs { get; set; }
    public int Rhs { get; set; }
}

class Sum : Construct
{
    public int Result { get; }

    public Sum(Construct scope, string id, SumProps props) : base(scope, id)
    {

        string resourceType = "Custom::Sum";
        string serviceToken = CustomResourceProvider.GetOrCreate(this, resourceType, new CustomResourceProviderProps {
            CodeDirectory = $"{__dirname}/sum-handler",
            Runtime = CustomResourceProviderRuntime.NODEJS_12_X
        });

        CustomResource resource = new CustomResource(this, "Resource", new CustomResourceProps {
            ResourceType = resourceType,
            ServiceToken = serviceToken,
            Properties = new Dictionary<string, object> {
                { "lhs", props.Lhs },
                { "rhs", props.Rhs }
            }
        });

        Result = Token.AsNumber(resource.GetAtt("Result"));
    }
}

Usage will look like this:

Sum sum = new Sum(this, "MySum", new SumProps { Lhs = 40, Rhs = 2 });
new CfnOutput(this, "Result", new CfnOutputProps { Value = Token.AsString(sum.Result) });

To access the ARN of the provider's AWS Lambda function role, use the getOrCreateProvider() built-in singleton method:

CustomResourceProvider provider = CustomResourceProvider.GetOrCreateProvider(this, "Custom::MyCustomResourceType", new CustomResourceProviderProps {
    CodeDirectory = $"{__dirname}/my-handler",
    Runtime = CustomResourceProviderRuntime.NODEJS_12_X
});

string roleArn = provider.RoleArn;

This role ARN can then be used in resource-based IAM policies.

The Custom Resource Provider Framework

The @aws-cdk/custom-resources module includes an advanced framework for implementing custom resource providers.

Handlers are implemented as AWS Lambda functions, which means that they can be implemented in any Lambda-supported runtime. Furthermore, this provider has an asynchronous mode, which means that users can provide an isComplete lambda function which is called periodically until the operation is complete. This allows implementing providers that can take up to two hours to stabilize.

Set serviceToken to provider.serviceToken to use this type of provider:

Provider provider = new Provider(this, "MyProvider", new ProviderProps {
    OnEventHandler = onEventHandler,
    IsCompleteHandler = isCompleteHandler
});

new CustomResource(this, "MyResource", new CustomResourceProps {
    ServiceToken = provider.ServiceToken
});

See the documentation for more details.

AWS CloudFormation features

A CDK stack synthesizes to an AWS CloudFormation Template. This section explains how this module allows users to access low-level CloudFormation features when needed.

Stack Outputs

CloudFormation stack outputs and exports are created using the CfnOutput class:

new CfnOutput(this, "OutputName", new CfnOutputProps {
    Value = myBucket.BucketName,
    Description = "The name of an S3 bucket",  // Optional
    ExportName = "TheAwesomeBucket"
});

Parameters

CloudFormation templates support the use of Parameters to customize a template. They enable CloudFormation users to input custom values to a template each time a stack is created or updated. While the CDK design philosophy favors using build-time parameterization, users may need to use CloudFormation in a number of cases (for example, when migrating an existing stack to the AWS CDK).

Template parameters can be added to a stack by using the CfnParameter class:

new CfnParameter(this, "MyParameter", new CfnParameterProps {
    Type = "Number",
    Default = 1337
});

The value of parameters can then be obtained using one of the value methods. As parameters are only resolved at deployment time, the values obtained are placeholder tokens for the real value (Token.isUnresolved() would return true for those):

CfnParameter param = new CfnParameter(this, "ParameterName", new CfnParameterProps { });

// If the parameter is a String
param.ValueAsString;

// If the parameter is a Number
param.ValueAsNumber;

// If the parameter is a List
param.ValueAsList;

Pseudo Parameters

CloudFormation supports a number of pseudo parameters, which resolve to useful values at deployment time. CloudFormation pseudo parameters can be obtained from static members of the Aws class.

It is generally recommended to access pseudo parameters from the scope's stack instead, which guarantees the values produced are qualifying the designated stack, which is essential in cases where resources are shared cross-stack:

// "this" is the current construct
Stack stack = Stack.Of(this);

stack.Account; // Returns the AWS::AccountId for this stack (or the literal value if known)
stack.Region; // Returns the AWS::Region for this stack (or the literal value if known)
stack.Partition;

Resource Options

CloudFormation resources can also specify resource attributes. The CfnResource class allows accessing those through the cfnOptions property:

CfnBucket rawBucket = new CfnBucket(this, "Bucket", new CfnBucketProps { });
// -or-
CfnBucket rawBucketAlt = (CfnBucket)myBucket.Node.DefaultChild;

// then
rawBucket.CfnOptions.Condition = new CfnCondition(this, "EnableBucket", new CfnConditionProps { });
rawBucket.CfnOptions.Metadata = new Dictionary<string, object> {
    { "metadataKey", "MetadataValue" }
};

Resource dependencies (the DependsOn attribute) is modified using the cfnResource.addDependsOn method:

CfnResource resourceA = new CfnResource(this, "ResourceA", resourceProps);
CfnResource resourceB = new CfnResource(this, "ResourceB", resourceProps);

resourceB.AddDependsOn(resourceA);

Intrinsic Functions and Condition Expressions

CloudFormation supports intrinsic functions. These functions can be accessed from the Fn class, which provides type-safe methods for each intrinsic function as well as condition expressions:

// To use Fn::Base64
Fn.Base64("SGVsbG8gQ0RLIQo=");

// To compose condition expressions:
CfnParameter environmentParameter = new CfnParameter(this, "Environment");
Fn.ConditionAnd(Fn.ConditionEquals("Production", environmentParameter), Fn.ConditionNot(Fn.ConditionEquals("us-east-1", Aws.REGION)));

When working with deploy-time values (those for which Token.isUnresolved returns true), idiomatic conditionals from the programming language cannot be used (the value will not be known until deployment time). When conditional logic needs to be expressed with un-resolved values, it is necessary to use CloudFormation conditions by means of the CfnCondition class:

CfnParameter environmentParameter = new CfnParameter(this, "Environment");
CfnCondition isProd = new CfnCondition(this, "IsProduction", new CfnConditionProps {
    Expression = Fn.ConditionEquals("Production", environmentParameter)
});

// Configuration value that is a different string based on IsProduction
string stage = Fn.ConditionIf(isProd.LogicalId, "Beta", "Prod").ToString();

// Make Bucket creation condition to IsProduction by accessing
// and overriding the CloudFormation resource
Bucket bucket = new Bucket(this, "Bucket");
CfnBucket cfnBucket = (CfnBucket)myBucket.Node.DefaultChild;
cfnBucket.CfnOptions.Condition = isProd;

Mappings

CloudFormation mappings are created and queried using the CfnMappings class:

CfnMapping regionTable = new CfnMapping(this, "RegionTable", new CfnMappingProps {
    Mapping = new Dictionary<string, IDictionary<string, object>> {
        { "us-east-1", new Dictionary<string, object> {
            { "regionName", "US East (N. Virginia)" }
        } },
        { "us-east-2", new Dictionary<string, object> {
            { "regionName", "US East (Ohio)" }
        } }
    }
});

regionTable.FindInMap(Aws.REGION, "regionName");

This will yield the following template:

Mappings:
  RegionTable:
    us-east-1:
      regionName: US East (N. Virginia)
    us-east-2:
      regionName: US East (Ohio)

Mappings can also be synthesized "lazily"; lazy mappings will only render a "Mappings" section in the synthesized CloudFormation template if some findInMap call is unable to immediately return a concrete value due to one or both of the keys being unresolved tokens (some value only available at deploy-time).

For example, the following code will not produce anything in the "Mappings" section. The call to findInMap will be able to resolve the value during synthesis and simply return 'US East (Ohio)'.

CfnMapping regionTable = new CfnMapping(this, "RegionTable", new CfnMappingProps {
    Mapping = new Dictionary<string, IDictionary<string, object>> {
        { "us-east-1", new Dictionary<string, object> {
            { "regionName", "US East (N. Virginia)" }
        } },
        { "us-east-2", new Dictionary<string, object> {
            { "regionName", "US East (Ohio)" }
        } }
    },
    Lazy = true
});

regionTable.FindInMap("us-east-2", "regionName");

On the other hand, the following code will produce the "Mappings" section shown above, since the top-level key is an unresolved token. The call to findInMap will return a token that resolves to { "Fn::FindInMap": [ "RegionTable", { "Ref": "AWS::Region" }, "regionName" ] }.

CfnMapping regionTable;


regionTable.FindInMap(Aws.REGION, "regionName");

Dynamic References

CloudFormation supports dynamically resolving values for SSM parameters (including secure strings) and Secrets Manager. Encoding such references is done using the CfnDynamicReference class:

new CfnDynamicReference(CfnDynamicReferenceService.SECRETS_MANAGER, "secret-id:secret-string:json-key:version-stage:version-id");

Template Options & Transform

CloudFormation templates support a number of options, including which Macros or Transforms to use when deploying the stack. Those can be configured using the stack.templateOptions property:

Stack stack = new Stack(app, "StackName");

stack.TemplateOptions.Description = "This will appear in the AWS console";
stack.TemplateOptions.Transforms = new [] { "AWS::Serverless-2016-10-31" };
stack.TemplateOptions.Metadata = new Dictionary<string, object> {
    { "metadataKey", "MetadataValue" }
};

Emitting Raw Resources

The CfnResource class allows emitting arbitrary entries in the Resources section of the CloudFormation template.

new CfnResource(this, "ResourceId", new CfnResourceProps {
    Type = "AWS::S3::Bucket",
    Properties = new Dictionary<string, object> {
        { "BucketName", "bucket-name" }
    }
});

As for any other resource, the logical ID in the CloudFormation template will be generated by the AWS CDK, but the type and properties will be copied verbatim in the synthesized template.

Including raw CloudFormation template fragments

When migrating a CloudFormation stack to the AWS CDK, it can be useful to include fragments of an existing template verbatim in the synthesized template. This can be achieved using the CfnInclude class.

new CfnInclude(this, "ID", new CfnIncludeProps {
    Template = new Dictionary<string, IDictionary<string, IDictionary<string, object>>> {
        { "Resources", new Struct {
            Bucket = new Struct {
                Type = "AWS::S3::Bucket",
                Properties = new Struct {
                    BucketName = "my-shiny-bucket"
                }
            }
        } }
    }
});

Termination Protection

You can prevent a stack from being accidentally deleted by enabling termination protection on the stack. If a user attempts to delete a stack with termination protection enabled, the deletion fails and the stack--including its status--remains unchanged. Enabling or disabling termination protection on a stack sets it for any nested stacks belonging to that stack as well. You can enable termination protection on a stack by setting the terminationProtection prop to true.

Stack stack = new Stack(app, "StackName", new StackProps {
    TerminationProtection = true
});

By default, termination protection is disabled.

CfnJson

CfnJson allows you to postpone the resolution of a JSON blob from deployment-time. This is useful in cases where the CloudFormation JSON template cannot express a certain value.

A common example is to use CfnJson in order to render a JSON map which needs to use intrinsic functions in keys. Since JSON map keys must be strings, it is impossible to use intrinsics in keys and CfnJson can help.

The following example defines an IAM role which can only be assumed by principals that are tagged with a specific tag.

CfnParameter tagParam = new CfnParameter(this, "TagName");

CfnJson stringEquals = new CfnJson(this, "ConditionJson", new CfnJsonProps {
    Value = new Dictionary<string, boolean> {
        { $"aws:PrincipalTag/{tagParam.valueAsString}", true }
    }
});

PrincipalBase principal = new AccountRootPrincipal().WithConditions(new Dictionary<string, object> {
    { "StringEquals", stringEquals }
});

new Role(this, "MyRole", new RoleProps { AssumedBy = principal });

Explanation: since in this example we pass the tag name through a parameter, it can only be resolved during deployment. The resolved value can be represented in the template through a { "Ref": "TagName" }. However, since we want to use this value inside a aws:PrincipalTag/TAG-NAME IAM operator, we need it in the key of a StringEquals condition. JSON keys must be strings, so to circumvent this limitation, we use CfnJson to "delay" the rendition of this template section to deploy-time. This means that the value of StringEquals in the template will be { "Fn::GetAtt": [ "ConditionJson", "Value" ] }, and will only "expand" to the operator we synthesized during deployment.

Stack Resource Limit

When deploying to AWS CloudFormation, it needs to keep in check the amount of resources being added inside a Stack. Currently it's possible to check the limits in the AWS CloudFormation quotas page.

It's possible to synthesize the project with more Resources than the allowed (or even reduce the number of Resources).

Set the context key @aws-cdk/core:stackResourceLimit with the proper value, being 0 for disable the limit of resources.

Classes

Annotations	Includes API for attaching annotations such as warning messages to constructs.
App	A construct which represents an entire CDK app. This construct is normally the root of the construct tree.
AppProps	Initialization props for apps.
Arn
ArnComponents
ArnFormat	An enum representing the various ARN formats that different services use.
Aspects_	Aspects can be applied to CDK tree scopes and can operate on the tree before synthesis.
AssetHashType	The type of asset hash.
AssetOptions	Asset hash options.
AssetStaging	Stages a file or directory from a location on the file system into a staging directory.
AssetStagingProps	Initialization properties for AssetStaging.
Aws	Accessor for pseudo parameters.
BootstraplessSynthesizer	A special synthesizer that behaves similarly to DefaultStackSynthesizer, but doesn't require bootstrapping the environment it operates in.
BootstraplessSynthesizerProps	Construction properties of {@link BootstraplessSynthesizer}.
BundlingDockerImage	(deprecated) A Docker image used for asset bundling.
BundlingOptions	Bundling options.
BundlingOutput	The type of output that a bundling operation is producing.
CfnAutoScalingReplacingUpdate	Specifies whether an Auto Scaling group and the instances it contains are replaced during an update.
CfnAutoScalingRollingUpdate	To specify how AWS CloudFormation handles rolling updates for an Auto Scaling group, use the AutoScalingRollingUpdate policy.
CfnAutoScalingScheduledAction	With scheduled actions, the group size properties of an Auto Scaling group can change at any time.
CfnCapabilities	Capabilities that affect whether CloudFormation is allowed to change IAM resources.
CfnCodeDeployBlueGreenAdditionalOptions	Additional options for the blue/green deployment.
CfnCodeDeployBlueGreenApplication	The application actually being deployed.
CfnCodeDeployBlueGreenApplicationTarget	Type of the {@link CfnCodeDeployBlueGreenApplication.target} property.
CfnCodeDeployBlueGreenEcsAttributes	The attributes of the ECS Service being deployed.
CfnCodeDeployBlueGreenHook	A CloudFormation Hook for CodeDeploy blue-green ECS deployments.
CfnCodeDeployBlueGreenHookProps	Construction properties of {@link CfnCodeDeployBlueGreenHook}.
CfnCodeDeployBlueGreenLifecycleEventHooks	Lifecycle events for blue-green deployments.
CfnCodeDeployLambdaAliasUpdate	To perform an AWS CodeDeploy deployment when the version changes on an AWS::Lambda::Alias resource, use the CodeDeployLambdaAliasUpdate update policy.
CfnCondition	Represents a CloudFormation condition, for resources which must be conditionally created and the determination must be made at deploy time.
CfnConditionProps
CfnCreationPolicy	Associate the CreationPolicy attribute with a resource to prevent its status from reaching create complete until AWS CloudFormation receives a specified number of success signals or the timeout period is exceeded.
CfnCustomResource	A CloudFormation AWS::CloudFormation::CustomResource.
CfnCustomResourceProps	Properties for defining a CfnCustomResource.
CfnDeletionPolicy	With the DeletionPolicy attribute you can preserve or (in some cases) backup a resource when its stack is deleted.
CfnDynamicReference	References a dynamically retrieved value.
CfnDynamicReferenceProps	Properties for a Dynamic Reference.
CfnDynamicReferenceService	The service to retrieve the dynamic reference from.
CfnElement	An element of a CloudFormation stack.
CfnHook	Represents a CloudFormation resource.
CfnHookProps	Construction properties of {@link CfnHook}.
CfnInclude	(deprecated) Includes a CloudFormation template into a stack.
CfnIncludeProps	(deprecated) Construction properties for {@link CfnInclude}.
CfnJson	Captures a synthesis-time JSON object a CloudFormation reference which resolves during deployment to the resolved values of the JSON object.
CfnJsonProps
CfnMacro	A CloudFormation AWS::CloudFormation::Macro.
CfnMacroProps	Properties for defining a CfnMacro.
CfnMapping	Represents a CloudFormation mapping.
CfnMappingProps
CfnModuleDefaultVersion	A CloudFormation AWS::CloudFormation::ModuleDefaultVersion.
CfnModuleDefaultVersionProps	Properties for defining a CfnModuleDefaultVersion.
CfnModuleVersion	A CloudFormation AWS::CloudFormation::ModuleVersion.
CfnModuleVersionProps	Properties for defining a CfnModuleVersion.
CfnOutput
CfnOutputProps
CfnParameter	A CloudFormation parameter.
CfnParameterProps
CfnPublicTypeVersion	A CloudFormation AWS::CloudFormation::PublicTypeVersion.
CfnPublicTypeVersionProps	Properties for defining a CfnPublicTypeVersion.
CfnPublisher	A CloudFormation AWS::CloudFormation::Publisher.
CfnPublisherProps	Properties for defining a CfnPublisher.
CfnRefElement	Base class for referenceable CloudFormation constructs which are not Resources.
CfnResource	Represents a CloudFormation resource.
CfnResourceAutoScalingCreationPolicy	For an Auto Scaling group replacement update, specifies how many instances must signal success for the update to succeed.
CfnResourceDefaultVersion	A CloudFormation AWS::CloudFormation::ResourceDefaultVersion.
CfnResourceDefaultVersionProps	Properties for defining a CfnResourceDefaultVersion.
CfnResourceProps
CfnResourceSignal	When AWS CloudFormation creates the associated resource, configures the number of required success signals and the length of time that AWS CloudFormation waits for those signals.
CfnResourceVersion	A CloudFormation AWS::CloudFormation::ResourceVersion.
CfnResourceVersion.LoggingConfigProperty	Logging configuration information for a resource.
CfnResourceVersionProps	Properties for defining a CfnResourceVersion.
CfnRule	The Rules that define template constraints in an AWS Service Catalog portfolio describe when end users can use the template and which values they can specify for parameters that are declared in the AWS CloudFormation template used to create the product they are attempting to use.
CfnRuleAssertion	A rule assertion.
CfnRuleProps	A rule can include a RuleCondition property and must include an Assertions property.
CfnStack	A CloudFormation AWS::CloudFormation::Stack.
CfnStackProps	Properties for defining a CfnStack.
CfnStackSet	A CloudFormation AWS::CloudFormation::StackSet.
CfnStackSet.AutoDeploymentProperty	[ Service-managed permissions] Describes whether StackSets automatically deploys to AWS Organizations accounts that are added to a target organizational unit (OU).
CfnStackSet.DeploymentTargetsProperty	The AWS OrganizationalUnitIds or Accounts for which to create stack instances in the specified Regions.
CfnStackSet.OperationPreferencesProperty	The user-specified preferences for how AWS CloudFormation performs a stack set operation.
CfnStackSet.ParameterProperty	The Parameter data type.
CfnStackSet.StackInstancesProperty	Stack instances in some specific accounts and Regions.
CfnStackSetProps	Properties for defining a CfnStackSet.
CfnTag
CfnTrafficRoute	A traffic route, representing where the traffic is being directed to.
CfnTrafficRouting	Type of the {@link CfnCodeDeployBlueGreenEcsAttributes.trafficRouting} property.
CfnTrafficRoutingConfig	Traffic routing configuration settings.
CfnTrafficRoutingTimeBasedCanary	The traffic routing configuration if {@link CfnTrafficRoutingConfig.type} is {@link CfnTrafficRoutingType.TIME_BASED_CANARY}.
CfnTrafficRoutingTimeBasedLinear	The traffic routing configuration if {@link CfnTrafficRoutingConfig.type} is {@link CfnTrafficRoutingType.TIME_BASED_LINEAR}.
CfnTrafficRoutingType	The possible types of traffic shifting for the blue-green deployment configuration.
CfnTypeActivation	A CloudFormation AWS::CloudFormation::TypeActivation.
CfnTypeActivation.LoggingConfigProperty	Contains logging configuration information for an extension.
CfnTypeActivationProps	Properties for defining a CfnTypeActivation.
CfnUpdatePolicy	Use the UpdatePolicy attribute to specify how AWS CloudFormation handles updates to the AWS::AutoScaling::AutoScalingGroup resource.
CfnWaitCondition	A CloudFormation AWS::CloudFormation::WaitCondition.
CfnWaitConditionHandle	A CloudFormation AWS::CloudFormation::WaitConditionHandle.
CfnWaitConditionProps	Properties for defining a CfnWaitCondition.
ConcreteDependable	A set of constructs to be used as a dependable.
Construct	Represents the building block of the construct graph.
ConstructNode	Represents the construct node in the scope tree.
ConstructOrder	In what order to return constructs.
ContextProvider	Base class for the model side of context providers.
CopyOptions	Options applied when copying directories.
CustomResource	Instantiation of a custom resource, whose implementation is provided a Provider.
CustomResourceProps	Properties to provide a Lambda-backed custom resource.
CustomResourceProvider	An AWS-Lambda backed custom resource provider, for CDK Construct Library constructs.
CustomResourceProviderProps	Initialization properties for CustomResourceProvider.
CustomResourceProviderRuntime	The lambda runtime to use for the resource provider.
DefaultStackSynthesizer	Uses conventionally named roles and reify asset storage locations.
DefaultStackSynthesizerProps	Configuration properties for DefaultStackSynthesizer.
DefaultTokenResolver	Default resolver implementation.
DependableTrait	Trait for IDependable.
Dependency	A single dependency.
DockerBuildOptions	Docker build options.
DockerIgnoreStrategy	Ignores file paths based on the .dockerignore specification.
DockerImage	A Docker image.
DockerImageAssetLocation	The location of the published docker image.
DockerImageAssetSource
DockerRunOptions	Docker run options.
DockerVolume	A Docker volume.
DockerVolumeConsistency	Supported Docker volume consistency types.
Duration	Represents a length of time.
EncodingOptions	Properties to string encodings.
Environment	The deployment environment for a stack.
Expiration	Represents a date of expiration.
ExportValueOptions	Options for the stack.exportValue() method.
FeatureFlags	Features that are implemented behind a flag in order to preserve backwards compatibility for existing apps.
FileAssetLocation	The location of the published file asset.
FileAssetPackaging	Packaging modes for file assets.
FileAssetSource	Represents the source for a file asset.
FileCopyOptions	Options applied when copying directories into the staging location.
FileFingerprintOptions	Options related to calculating source hash.
FileSystem	File system utilities.
FingerprintOptions	Options related to calculating source hash.
Fn	CloudFormation intrinsic functions.
GetContextKeyOptions
GetContextKeyResult
GetContextValueOptions
GetContextValueResult
GitIgnoreStrategy	Ignores file paths based on the .gitignore specification.
GlobIgnoreStrategy	Ignores file paths based on simple glob patterns.
IgnoreMode	Determines the ignore behavior to use.
IgnoreStrategy	Represents file path ignoring behavior.
Intrinsic	Token subclass that represents values intrinsic to the target document language.
IntrinsicProps	Customization properties for an Intrinsic token.
Lazy	Lazily produce a value.
LazyAnyValueOptions	Options for creating lazy untyped tokens.
LazyListValueOptions	Options for creating a lazy list token.
LazyStringValueOptions	Options for creating a lazy string token.
LegacyStackSynthesizer	Use the original deployment environment.
Names	Functions for devising unique names for constructs.
NestedStack	A CloudFormation nested stack.
NestedStackProps	Initialization props for the NestedStack construct.
NestedStackSynthesizer	Deployment environment for a nested stack.
PhysicalName	Includes special markers for automatic generation of physical names.
Reference	An intrinsic Token that represents a reference to a construct.
RemovalPolicy	Possible values for a resource's Removal Policy.
RemovalPolicyOptions
RemoveTag	The RemoveTag Aspect will handle removing tags from this node and children.
ResolveChangeContextOptions	Options that can be changed while doing a recursive resolve.
ResolveOptions	Options to the resolve() operation.
Resource	A construct which represents an AWS resource.
ResourceEnvironment	Represents the environment a given resource lives in.
ResourceProps	Construction properties for {@link Resource}.
ReverseOptions	Options for the 'reverse()' operation.
ScopedAws	Accessor for scoped pseudo parameters.
SecretsManagerSecretOptions	Options for referencing a secret value from Secrets Manager.
SecretValue	Work with secret values in the CDK.
Size	Represents the amount of digital storage.
SizeConversionOptions	Options for how to convert time to a different unit.
SizeRoundingBehavior	Rounding behaviour when converting between units of Size.
Stack	A root construct which represents a single CloudFormation stack.
StackProps
StackSynthesizer	Base class for implementing an IStackSynthesizer.
Stage	An abstract application modeling unit consisting of Stacks that should be deployed together.
StageProps	Initialization props for a stage.
StageSynthesisOptions	Options for assembly synthesis.
StringConcat	Converts all fragments to strings and concats those.
SymlinkFollowMode	Determines how symlinks are followed.
SynthesisOptions	(deprecated) Options for synthesis.
SynthesizeStackArtifactOptions	Stack artifact options.
Tag	The Tag Aspect will handle adding a tag to this node and cascading tags to children.
TagManager	TagManager facilitates a common implementation of tagging for Constructs.
TagManagerOptions	Options to configure TagManager behavior.
TagProps	Properties for a tag.
Tags	Manages AWS tags for all resources within a construct scope.
TagType
TimeConversionOptions	Options for how to convert time to a different unit.
Token	Represents a special or lazily-evaluated value.
TokenComparison	An enum-like class that represents the result of comparing two Tokens.
Tokenization	Less oft-needed functions to manipulate Tokens.
TokenizedStringFragments	Fragments of a concatenated string containing stringified Tokens.
TreeInspector	Inspector that maintains an attribute bag.
ValidationError	An error returned during the validation phase.
ValidationResult	Representation of validation results.
ValidationResults	A collection of validation results.

Interfaces

CfnResourceVersion.ILoggingConfigProperty	Logging configuration information for a resource.
CfnStackSet.IAutoDeploymentProperty	[ Service-managed permissions] Describes whether StackSets automatically deploys to AWS Organizations accounts that are added to a target organizational unit (OU).
CfnStackSet.IDeploymentTargetsProperty	The AWS OrganizationalUnitIds or Accounts for which to create stack instances in the specified Regions.
CfnStackSet.IOperationPreferencesProperty	The user-specified preferences for how AWS CloudFormation performs a stack set operation.
CfnStackSet.IParameterProperty	The Parameter data type.
CfnStackSet.IStackInstancesProperty	Stack instances in some specific accounts and Regions.
CfnTypeActivation.ILoggingConfigProperty	Contains logging configuration information for an extension.
IAnyProducer	Interface for lazy untyped value producers.
IAppProps	Initialization props for apps.
IArnComponents
IAspect	Represents an Aspect.
IAsset	Common interface for all assets.
IAssetOptions	Asset hash options.
IAssetStagingProps	Initialization properties for AssetStaging.
IBootstraplessSynthesizerProps	Construction properties of {@link BootstraplessSynthesizer}.
IBundlingOptions	Bundling options.
ICfnAutoScalingReplacingUpdate	Specifies whether an Auto Scaling group and the instances it contains are replaced during an update.
ICfnAutoScalingRollingUpdate	To specify how AWS CloudFormation handles rolling updates for an Auto Scaling group, use the AutoScalingRollingUpdate policy.
ICfnAutoScalingScheduledAction	With scheduled actions, the group size properties of an Auto Scaling group can change at any time.
ICfnCodeDeployBlueGreenAdditionalOptions	Additional options for the blue/green deployment.
ICfnCodeDeployBlueGreenApplication	The application actually being deployed.
ICfnCodeDeployBlueGreenApplicationTarget	Type of the {@link CfnCodeDeployBlueGreenApplication.target} property.
ICfnCodeDeployBlueGreenEcsAttributes	The attributes of the ECS Service being deployed.
ICfnCodeDeployBlueGreenHookProps	Construction properties of {@link CfnCodeDeployBlueGreenHook}.
ICfnCodeDeployBlueGreenLifecycleEventHooks	Lifecycle events for blue-green deployments.
ICfnCodeDeployLambdaAliasUpdate	To perform an AWS CodeDeploy deployment when the version changes on an AWS::Lambda::Alias resource, use the CodeDeployLambdaAliasUpdate update policy.
ICfnConditionExpression	Represents a CloudFormation element that can be used within a Condition.
ICfnConditionProps
ICfnCreationPolicy	Associate the CreationPolicy attribute with a resource to prevent its status from reaching create complete until AWS CloudFormation receives a specified number of success signals or the timeout period is exceeded.
ICfnCustomResourceProps	Properties for defining a CfnCustomResource.
ICfnDynamicReferenceProps	Properties for a Dynamic Reference.
ICfnHookProps	Construction properties of {@link CfnHook}.
ICfnIncludeProps	(deprecated) Construction properties for {@link CfnInclude}.
ICfnJsonProps
ICfnMacroProps	Properties for defining a CfnMacro.
ICfnMappingProps
ICfnModuleDefaultVersionProps	Properties for defining a CfnModuleDefaultVersion.
ICfnModuleVersionProps	Properties for defining a CfnModuleVersion.
ICfnOutputProps
ICfnParameterProps
ICfnPublicTypeVersionProps	Properties for defining a CfnPublicTypeVersion.
ICfnPublisherProps	Properties for defining a CfnPublisher.
ICfnResourceAutoScalingCreationPolicy	For an Auto Scaling group replacement update, specifies how many instances must signal success for the update to succeed.
ICfnResourceDefaultVersionProps	Properties for defining a CfnResourceDefaultVersion.
ICfnResourceOptions
ICfnResourceProps
ICfnResourceSignal	When AWS CloudFormation creates the associated resource, configures the number of required success signals and the length of time that AWS CloudFormation waits for those signals.
ICfnResourceVersionProps	Properties for defining a CfnResourceVersion.
ICfnRuleAssertion	A rule assertion.
ICfnRuleConditionExpression	Interface to specify certain functions as Service Catalog rule-specifc.
ICfnRuleProps	A rule can include a RuleCondition property and must include an Assertions property.
ICfnStackProps	Properties for defining a CfnStack.
ICfnStackSetProps	Properties for defining a CfnStackSet.
ICfnTag
ICfnTrafficRoute	A traffic route, representing where the traffic is being directed to.
ICfnTrafficRouting	Type of the {@link CfnCodeDeployBlueGreenEcsAttributes.trafficRouting} property.
ICfnTrafficRoutingConfig	Traffic routing configuration settings.
ICfnTrafficRoutingTimeBasedCanary	The traffic routing configuration if {@link CfnTrafficRoutingConfig.type} is {@link CfnTrafficRoutingType.TIME_BASED_CANARY}.
ICfnTrafficRoutingTimeBasedLinear	The traffic routing configuration if {@link CfnTrafficRoutingConfig.type} is {@link CfnTrafficRoutingType.TIME_BASED_LINEAR}.
ICfnTypeActivationProps	Properties for defining a CfnTypeActivation.
ICfnUpdatePolicy	Use the UpdatePolicy attribute to specify how AWS CloudFormation handles updates to the AWS::AutoScaling::AutoScalingGroup resource.
ICfnWaitConditionProps	Properties for defining a CfnWaitCondition.
IConstruct	Represents a construct.
ICopyOptions	Options applied when copying directories.
ICustomResourceProps	Properties to provide a Lambda-backed custom resource.
ICustomResourceProviderProps	Initialization properties for CustomResourceProvider.
IDefaultStackSynthesizerProps	Configuration properties for DefaultStackSynthesizer.
IDependable	Trait marker for classes that can be depended upon.
IDependency	A single dependency.
IDockerBuildOptions	Docker build options.
IDockerImageAssetLocation	The location of the published docker image.
IDockerImageAssetSource
IDockerRunOptions	Docker run options.
IDockerVolume	A Docker volume.
IEncodingOptions	Properties to string encodings.
IEnvironment	The deployment environment for a stack.
IExportValueOptions	Options for the stack.exportValue() method.
IFileAssetLocation	The location of the published file asset.
IFileAssetSource	Represents the source for a file asset.
IFileCopyOptions	Options applied when copying directories into the staging location.
IFileFingerprintOptions	Options related to calculating source hash.
IFingerprintOptions	Options related to calculating source hash.
IFragmentConcatenator	Function used to concatenate symbols in the target document language.
IGetContextKeyOptions
IGetContextKeyResult
IGetContextValueOptions
IGetContextValueResult
IInspectable	Interface for examining a construct and exposing metadata.
IIntrinsicProps	Customization properties for an Intrinsic token.
ILazyAnyValueOptions	Options for creating lazy untyped tokens.
ILazyListValueOptions	Options for creating a lazy list token.
ILazyStringValueOptions	Options for creating a lazy string token.
IListProducer	Interface for lazy list producers.
ILocalBundling	Local bundling.
INestedStackProps	Initialization props for the NestedStack construct.
INumberProducer	Interface for lazy number producers.
IPostProcessor	A Token that can post-process the complete resolved value, after resolve() has recursed over it.
IRemovalPolicyOptions
IResolvable	Interface for values that can be resolvable later.
IResolveChangeContextOptions	Options that can be changed while doing a recursive resolve.
IResolveContext	Current resolution context for tokens.
IResolveOptions	Options to the resolve() operation.
IResource	Interface for the Resource construct.
IResourceEnvironment	Represents the environment a given resource lives in.
IResourceProps	Construction properties for {@link Resource}.
IReverseOptions	Options for the 'reverse()' operation.
ISecretsManagerSecretOptions	Options for referencing a secret value from Secrets Manager.
ISizeConversionOptions	Options for how to convert time to a different unit.
IStableAnyProducer	Interface for (stable) lazy untyped value producers.
IStableListProducer	Interface for (stable) lazy list producers.
IStableNumberProducer	Interface for (stable) lazy number producers.
IStableStringProducer	Interface for (stable) lazy string producers.
IStackProps
IStackSynthesizer	Encodes information how a certain Stack should be deployed.
IStageProps	Initialization props for a stage.
IStageSynthesisOptions	Options for assembly synthesis.
IStringProducer	Interface for lazy string producers.
ISynthesisOptions	(deprecated) Options for synthesis.
ISynthesisSession	Represents a single session of synthesis.
ISynthesizeStackArtifactOptions	Stack artifact options.
ITaggable	Interface to implement tags.
ITagManagerOptions	Options to configure TagManager behavior.
ITagProps	Properties for a tag.
ITemplateOptions	CloudFormation template options for a stack.
ITimeConversionOptions	Options for how to convert time to a different unit.
ITokenMapper	Interface to apply operation to tokens in a string.
ITokenResolver	How to resolve tokens.
IValidationError	An error returned during the validation phase.