Metadata-Version: 2.1
Name: aws-cdk.core
Version: 1.104.0
Summary: AWS Cloud Development Kit Core Library
Home-page: https://github.com/aws/aws-cdk
Author: Amazon Web Services
License: Apache-2.0
Project-URL: Source, https://github.com/aws/aws-cdk.git
Description: # AWS Cloud Development Kit Core Library
        
        <!--BEGIN STABILITY BANNER-->---
        
        
        ![cfn-resources: Stable](https://img.shields.io/badge/cfn--resources-stable-success.svg?style=for-the-badge)
        
        ![cdk-constructs: Stable](https://img.shields.io/badge/cdk--constructs-stable-success.svg?style=for-the-badge)
        
        ---
        <!--END STABILITY BANNER-->
        
        This library includes the basic building blocks of the [AWS Cloud Development Kit](https://github.com/aws/aws-cdk) (AWS CDK). It defines the core classes that are used in the rest of the
        AWS Construct Library.
        
        See the [AWS CDK Developer
        Guide](https://docs.aws.amazon.com/cdk/latest/guide/home.html) 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.
        
        <!--BEGIN CORE DOCUMENTATION-->
        
        ## 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:
        
        * You could be starting to reach the maximum number of resources allowed in a single
          stack (this is currently 500).
        * You could decide you want to separate out stateful resources and stateless resources
          into separate stacks, so that it becomes easy to tear down and recreate the stacks
          that don't have stateful resources.
        * There could be a single stack with resources (like a VPC) that are shared
          between multiple instances of other stacks containing your applications.
        
        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 `Construct`, holding one or more
        `Stack`s, to represent a single logical instance of your application.
        
        As a final note: `Stack`s 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](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/using-cfn-nested-stacks.html) 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:
        
        ```python
        # Example automatically generated. See https://github.com/aws/jsii/issues/826
        class MyNestedStack(cfn.NestedStack):
            def __init__(self, scope, id, *, parameters=None, timeout=None, notifications=None):
                super().__init__(scope, id, parameters=parameters, timeout=timeout, notifications=notifications)
        
                s3.Bucket(self, "NestedBucket")
        
        class MyParentStack(Stack):
            def __init__(self, scope, id, *, description=None, env=None, stackName=None, tags=None, synthesizer=None, terminationProtection=None, analyticsReporting=None):
                super().__init__(scope, id, description=description, env=env, stackName=stackName, tags=tags, synthesizer=synthesizer, terminationProtection=terminationProtection, analyticsReporting=analyticsReporting)
        
                MyNestedStack(self, "Nested1")
                MyNestedStack(self, "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.
        
        ```python
        # Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
        prod = {"account": "123456789012", "region": "us-east-1"}
        
        stack1 = StackThatProvidesABucket(app, "Stack1", env=prod)
        
        # stack2 will take a property { bucket: IBucket }
        stack2 = StackThatExpectsABucket(app, "Stack2",
            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](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/using-cfn-stack-exports.html)
        in the producing stack and an
        [Fn::ImportValue](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/intrinsic-function-reference-importvalue.html)
        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:
        
        ```text
        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
        
        * Make sure `stack2` no longer references `bucket.bucketName` (maybe the consumer
          stack now uses its own bucket, or it writes to an AWS DynamoDB table, or maybe you just
          remove the Lambda Function altogether).
        * In the `stack1` class, call `this.exportValue(this.bucket.bucketName)`. This
          will make sure the CloudFormation Export continues to exist while the relationship
          between the two stacks is being broken.
        * Deploy (this will effectively only change the `stack2`, but it's safe to deploy both).
        
        DEPLOYMENT 2: remove the resource
        
        * You are now free to remove the `bucket` resource from `stack1`.
        * Don't forget to remove the `exportValue()` call as well.
        * Deploy again (this time only the `stack1` will be changed -- the bucket will be deleted).
        
        ## 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:
        
        ```python
        # Example automatically generated. See https://github.com/aws/jsii/issues/826
        Duration.seconds(300)# 5 minutes
        Duration.minutes(5)# 5 minutes
        Duration.hours(1)# 1 hour
        Duration.days(7)# 7 days
        Duration.parse("PT5M")
        ```
        
        ## 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:
        
        ```python
        # Example automatically generated. See https://github.com/aws/jsii/issues/826
        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.
        
        ```python
        # Example automatically generated. See https://github.com/aws/jsii/issues/826
        Size.mebibytes(2).to_kibibytes()# yields 2048
        Size.kibibytes(2050).to_mebibytes(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`:
        
        ```python
        # Example automatically generated. See https://github.com/aws/jsii/issues/826
        secret = SecretValue.secrets_manager("secretId",
            json_field="password", # optional: key of a JSON field to retrieve (defaults to all content),
            version_id="id", # optional: id of the version (default AWSCURRENT)
            version_stage="stage"
        )
        ```
        
        Using AWS Secrets Manager is the recommended way to reference secrets in a CDK app.
        `SecretValue` also supports the following secret sources:
        
        * `SecretValue.plainText(secret)`: stores the secret as plain text in your app and the resulting template (not recommended).
        * `SecretValue.ssmSecure(param, version)`: refers to a secret stored as a SecureString in the SSM Parameter Store.
        * `SecretValue.cfnParameter(param)`: refers to a secret passed through a CloudFormation parameter (must have `NoEcho: true`).
        * `SecretValue.cfnDynamicReference(dynref)`: refers to a secret described by a CloudFormation dynamic reference (used by `ssmSecure` and `secretsManager`).
        
        ## 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:
        
        ```python
        # Example automatically generated. See https://github.com/aws/jsii/issues/826
        # Builds "arn:<PARTITION>:lambda:<REGION>:<ACCOUNT>:function:MyFunction"
        stack.format_arn(
            service="lambda",
            resource="function",
            sep=":",
            resource_name="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.
        
        ```python
        # Example automatically generated. See https://github.com/aws/jsii/issues/826
        # Extracts the function name out of an AWS Lambda Function ARN
        arn_components = stack.parse_arn(arn, ":")
        function_name = arn_components.resource_name
        ```
        
        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](https://docs.aws.amazon.com/general/latest/gr/aws-arns-and-namespaces.html)
        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`:
        
        ```python
        # Example automatically generated. See https://github.com/aws/jsii/issues/826
        # Declare the dependable object
        b_and_c = ConcreteDependable()
        b_and_c.add(construct_b)
        b_and_c.add(construct_c)
        
        # Take the dependency
        construct_a.node.add_dependency(b_and_c)
        ```
        
        ### 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:
        
        * Cyclic dependencies are not allowed, so if `stackA` is using resources from
          `stackB`, the reverse is not possible anymore.
        * Stacks with dependencies between them are treated specially by the CDK
          toolkit:
        
          * If `stackA` depends on `stackB`, running `cdk deploy stackA` will also
            automatically deploy `stackB`.
          * `stackB`'s deployment will be performed *before* `stackA`'s deployment.
        
        ## 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:
        
        ```python
        # Example automatically generated. See https://github.com/aws/jsii/issues/826
        CustomResource(self, "MyMagicalResource",
            resource_type="Custom::MyCustomResource", # must start with 'Custom::'
        
            # the resource properties
            properties={
                "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
            service_token="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](#amazon-sns-topic)                                       | Self-managed | Manual         | Manual                   | Unlimited       | Any      | Depends   |
        | [lambda.Function](#aws-lambda-function)                              | AWS Lambda   | Manual         | Manual                   | 15min           | Any      | Small     |
        | [core.CustomResourceProvider](#the-corecustomresourceprovider-class) | Lambda       | Auto           | Auto                     | 15min           | Node.js  | Small     |
        | [custom-resources.Provider](#the-custom-resource-provider-framework) | Lambda       | Auto           | Auto                     | Unlimited Async | Any      | Large     |
        
        Legend:
        
        * **Compute type**: which type of compute can is used to execute the handler.
        * **Error Handling**: whether errors thrown by handler code are automatically
          trapped and a FAILED response is submitted to CloudFormation. If this is
          "Manual", developers must take care of trapping errors. Otherwise, events
          could cause stacks to hang.
        * **Submit to CloudFormation**: whether the framework takes care of submitting
          SUCCESS/FAILED responses to CloudFormation through the event's response URL.
        * **Max Timeout**: maximum allows/possible timeout.
        * **Language**: which programming languages can be used to implement handlers.
        * **Footprint**: how many resources are used by the provider framework itself.
        
        **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:
        
        ```python
        # Example automatically generated. See https://github.com/aws/jsii/issues/826
        def get_or_create(self, scope):
            stack = Stack.of(scope)
            uniqueid = "GloballyUniqueIdForSingleton"return stack.node.try_find_child(uniqueid) ?? sns.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:
        
        ```python
        # Example automatically generated. See https://github.com/aws/jsii/issues/826
        topic = sns.Topic(self, "MyProvider")
        
        CustomResource(self, "MyResource",
            service_token=topic.topic_arn
        )
        ```
        
        #### 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:
        
        ```python
        # Example automatically generated. See https://github.com/aws/jsii/issues/826
        fn = lambda_.Function(self, "MyProvider", function_props)
        
        CustomResource(self, "MyResource",
            service_token=fn.function_arn
        )
        ```
        
        #### The `core.CustomResourceProvider` class
        
        The class [`@aws-cdk/core.CustomResourceProvider`](https://docs.aws.amazon.com/cdk/api/latest/docs/@aws-cdk_core.CustomResourceProvider.html) 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:
        
        ```python
        # Example automatically generated. See https://github.com/aws/jsii/issues/826
        service_token = CustomResourceProvider.get_or_create(self, "Custom::MyCustomResourceType",
            code_directory=f"{__dirname}/my-handler",
            runtime=CustomResourceProviderRuntime.NODEJS_12_X,
            description="Lambda function created by the custom resource provider"
        )
        
        CustomResource(self, "MyResource",
            resource_type="Custom::MyCustomResourceType",
            service_token=service_token
        )
        ```
        
        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:
        
        ```js
        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`:
        
        ```js
        exports.handler = async (e) => {
          return {
            Data: {
              Result: e.ResourceProperties.lhs + e.ResourceProperties.rhs,
            },
          };
        };
        ```
        
        `sum.ts`:
        
        ```python
        # Example automatically generated. See https://github.com/aws/jsii/issues/826
        from aws_cdk.core import Construct, CustomResource, CustomResourceProvider, CustomResourceProviderRuntime, Token
        
        class Sum(Construct):
        
            def __init__(self, scope, id, *, lhs, rhs):
                super().__init__(scope, id)
        
                resource_type = "Custom::Sum"
                service_token = CustomResourceProvider.get_or_create(self, resource_type,
                    code_directory=f"{__dirname}/sum-handler",
                    runtime=CustomResourceProviderRuntime.NODEJS_12_X
                )
        
                resource = CustomResource(self, "Resource",
                    resource_type=resource_type,
                    service_token=service_token,
                    properties={
                        "lhs": lhs,
                        "rhs": rhs
                    }
                )
        
                self.result = Token.as_number(resource.get_att("Result"))
        ```
        
        Usage will look like this:
        
        ```python
        # Example automatically generated. See https://github.com/aws/jsii/issues/826
        sum = Sum(self, "MySum", lhs=40, rhs=2)
        CfnOutput(self, "Result", value=Token.as_string(sum.result))
        ```
        
        To access the ARN of the provider's AWS Lambda function role, use the `getOrCreateProvider()`
        built-in singleton method:
        
        ```python
        # Example automatically generated. See https://github.com/aws/jsii/issues/826
        provider = CustomResourceProvider.get_or_create_provider(self, "Custom::MyCustomResourceType",
            code_directory=f"{__dirname}/my-handler",
            runtime=CustomResourceProviderRuntime.NODEJS_12_X
        )
        
        role_arn = provider.role_arn
        ```
        
        This role ARN can then be used in resource-based IAM policies.
        
        #### The Custom Resource Provider Framework
        
        The [`@aws-cdk/custom-resources`](https://docs.aws.amazon.com/cdk/api/latest/docs/custom-resources-readme.html) 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:
        
        ```python
        # Example automatically generated. See https://github.com/aws/jsii/issues/826
        provider = customresources.Provider(self, "MyProvider",
            on_event_handler=on_event_handler,
            is_complete_handler=is_complete_handler
        )
        
        CustomResource(self, "MyResource",
            service_token=provider.service_token
        )
        ```
        
        See the [documentation](https://docs.aws.amazon.com/cdk/api/latest/docs/custom-resources-readme.html) 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](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/outputs-section-structure.html) and exports are created using
        the `CfnOutput` class:
        
        ```python
        # Example automatically generated. See https://github.com/aws/jsii/issues/826
        CfnOutput(self, "OutputName",
            value=my_bucket.bucket_name,
            description="The name of an S3 bucket", # Optional
            export_name="TheAwesomeBucket"
        )
        ```
        
        ### Parameters
        
        CloudFormation templates support the use of [Parameters](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/parameters-section-structure.html) 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:
        
        ```python
        # Example automatically generated. See https://github.com/aws/jsii/issues/826
        CfnParameter(self, "MyParameter",
            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):
        
        ```python
        # Example automatically generated. See https://github.com/aws/jsii/issues/826
        param = CfnParameter(self, "ParameterName")
        
        # If the parameter is a String
        param.value_as_string
        
        # If the parameter is a Number
        param.value_as_number
        
        # If the parameter is a List
        param.value_as_list
        ```
        
        ### Pseudo Parameters
        
        CloudFormation supports a number of [pseudo parameters](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/pseudo-parameter-reference.html),
        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:
        
        ```python
        # Example automatically generated. See https://github.com/aws/jsii/issues/826
        # "this" is the current construct
        stack = Stack.of(self)
        
        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](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-product-attribute-reference.html). The `CfnResource` class allows
        accessing those through the `cfnOptions` property:
        
        ```python
        # Example automatically generated. See https://github.com/aws/jsii/issues/826
        raw_bucket = s3.CfnBucket(self, "Bucket")
        # -or-
        raw_bucket_alt = my_bucket.node.default_child
        
        # then
        raw_bucket.cfn_options.condition = CfnCondition(self, "EnableBucket")
        raw_bucket.cfn_options.metadata = {
            "metadata_key": "MetadataValue"
        }
        ```
        
        Resource dependencies (the `DependsOn` attribute) is modified using the
        `cfnResource.addDependsOn` method:
        
        ```python
        # Example automatically generated. See https://github.com/aws/jsii/issues/826
        resource_a = CfnResource(self, "ResourceA", resource_props)
        resource_b = CfnResource(self, "ResourceB", resource_props)
        
        resource_b.add_depends_on(resource_a)
        ```
        
        ### Intrinsic Functions and Condition Expressions
        
        CloudFormation supports [intrinsic functions](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/intrinsic-function-reference.html). These functions
        can be accessed from the `Fn` class, which provides type-safe methods for each
        intrinsic function as well as condition expressions:
        
        ```python
        # Example automatically generated. See https://github.com/aws/jsii/issues/826
        # To use Fn::Base64
        Fn.base64("SGVsbG8gQ0RLIQo=")
        
        # To compose condition expressions:
        environment_parameter = CfnParameter(self, "Environment")
        Fn.condition_and(
            # The "Environment" CloudFormation template parameter evaluates to "Production"
            Fn.condition_equals("Production", environment_parameter),
            # The AWS::Region pseudo-parameter value is NOT equal to "us-east-1"
            Fn.condition_not(Fn.condition_equals("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:
        
        ```python
        # Example automatically generated. See https://github.com/aws/jsii/issues/826
        environment_parameter = CfnParameter(self, "Environment")
        is_prod = CfnCondition(self, "IsProduction",
            expression=Fn.condition_equals("Production", environment_parameter)
        )
        
        # Configuration value that is a different string based on IsProduction
        stage = Fn.condition_if(is_prod.logical_id, "Beta", "Prod").to_string()
        
        # Make Bucket creation condition to IsProduction by accessing
        # and overriding the CloudFormation resource
        bucket = s3.Bucket(self, "Bucket")
        cfn_bucket = my_bucket.node.default_child
        cfn_bucket.cfn_options.condition = is_prod
        ```
        
        ### Mappings
        
        CloudFormation [mappings](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/mappings-section-structure.html) are created and queried using the
        `CfnMappings` class:
        
        ```python
        # Example automatically generated. See https://github.com/aws/jsii/issues/826
        region_table = CfnMapping(self, "RegionTable",
            mapping={
                "region_name": {
                    "us-east-1": "US East (N. Virginia)",
                    "us-east-2": "US East (Ohio)"
                }
            }
        )
        
        region_table.find_in_map("regionName", Aws.REGION)
        ```
        
        This will yield the following template:
        
        ```yaml
        Mappings:
          RegionTable:
            regionName:
              us-east-1: US East (N. Virginia)
              us-east-2: US East (Ohio)
        ```
        
        ### Dynamic References
        
        CloudFormation supports [dynamically resolving](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/dynamic-references.html) values
        for SSM parameters (including secure strings) and Secrets Manager. Encoding such
        references is done using the `CfnDynamicReference` class:
        
        ```python
        # Example automatically generated. See https://github.com/aws/jsii/issues/826
        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](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/transform-section-structure.html) to use when deploying the stack. Those can be
        configured using the `stack.templateOptions` property:
        
        ```python
        # Example automatically generated. See https://github.com/aws/jsii/issues/826
        stack = Stack(app, "StackName")
        
        stack.template_options.description = "This will appear in the AWS console"
        stack.template_options.transforms = ["AWS::Serverless-2016-10-31"]
        stack.template_options.metadata = {
            "metadata_key": "MetadataValue"
        }
        ```
        
        ### Emitting Raw Resources
        
        The `CfnResource` class allows emitting arbitrary entries in the
        [Resources](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/resources-section-structure.html) section of the CloudFormation template.
        
        ```python
        # Example automatically generated. See https://github.com/aws/jsii/issues/826
        CfnResource(self, "ResourceId",
            type="AWS::S3::Bucket",
            properties={
                "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.
        
        ```python
        # Example automatically generated. See https://github.com/aws/jsii/issues/826
        CfnInclude(self, "ID",
            template={
                "Resources": {
                    "Bucket": {
                        "Type": "AWS::S3::Bucket",
                        "Properties": {
                            "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`.
        
        ```python
        # Example automatically generated. See https://github.com/aws/jsii/issues/826
        stack = Stack(app, "StackName",
            termination_protection=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.
        
        ```python
        # Example automatically generated. See https://github.com/aws/jsii/issues/826
        tag_param = CfnParameter(self, "TagName")
        
        string_equals = CfnJson(self, "ConditionJson",
            value={
                f"aws:PrincipalTag/{tagParam.valueAsString}": True
            }
        )
        
        principal = iam.AccountRootPrincipal().with_conditions({
            "StringEquals": string_equals
        })
        
        iam.Role(self, "MyRole", assumed_by=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`](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_condition-keys.html#condition-keys-principaltag)
        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](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/cloudformation-limits.html) 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.
        
        <!--END CORE DOCUMENTATION-->
        
Platform: UNKNOWN
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: JavaScript
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Typing :: Typed
Classifier: Development Status :: 5 - Production/Stable
Classifier: License :: OSI Approved
Classifier: Framework :: AWS CDK
Classifier: Framework :: AWS CDK :: 1
Requires-Python: >=3.6
Description-Content-Type: text/markdown
