Metadata-Version: 2.1
Name: aws-cdk.cloudformation-include
Version: 1.107.0
Summary: A package that facilitates working with existing CloudFormation templates in the CDK
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
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
Requires-Dist: aws-cdk.alexa-ask (==1.107.0)
Requires-Dist: aws-cdk.aws-accessanalyzer (==1.107.0)
Requires-Dist: aws-cdk.aws-acmpca (==1.107.0)
Requires-Dist: aws-cdk.aws-amazonmq (==1.107.0)
Requires-Dist: aws-cdk.aws-amplify (==1.107.0)
Requires-Dist: aws-cdk.aws-apigateway (==1.107.0)
Requires-Dist: aws-cdk.aws-apigatewayv2 (==1.107.0)
Requires-Dist: aws-cdk.aws-appconfig (==1.107.0)
Requires-Dist: aws-cdk.aws-appflow (==1.107.0)
Requires-Dist: aws-cdk.aws-appintegrations (==1.107.0)
Requires-Dist: aws-cdk.aws-applicationautoscaling (==1.107.0)
Requires-Dist: aws-cdk.aws-applicationinsights (==1.107.0)
Requires-Dist: aws-cdk.aws-appmesh (==1.107.0)
Requires-Dist: aws-cdk.aws-apprunner (==1.107.0)
Requires-Dist: aws-cdk.aws-appstream (==1.107.0)
Requires-Dist: aws-cdk.aws-appsync (==1.107.0)
Requires-Dist: aws-cdk.aws-athena (==1.107.0)
Requires-Dist: aws-cdk.aws-auditmanager (==1.107.0)
Requires-Dist: aws-cdk.aws-autoscaling (==1.107.0)
Requires-Dist: aws-cdk.aws-autoscalingplans (==1.107.0)
Requires-Dist: aws-cdk.aws-backup (==1.107.0)
Requires-Dist: aws-cdk.aws-batch (==1.107.0)
Requires-Dist: aws-cdk.aws-budgets (==1.107.0)
Requires-Dist: aws-cdk.aws-cassandra (==1.107.0)
Requires-Dist: aws-cdk.aws-ce (==1.107.0)
Requires-Dist: aws-cdk.aws-certificatemanager (==1.107.0)
Requires-Dist: aws-cdk.aws-chatbot (==1.107.0)
Requires-Dist: aws-cdk.aws-cloud9 (==1.107.0)
Requires-Dist: aws-cdk.aws-cloudfront (==1.107.0)
Requires-Dist: aws-cdk.aws-cloudtrail (==1.107.0)
Requires-Dist: aws-cdk.aws-cloudwatch (==1.107.0)
Requires-Dist: aws-cdk.aws-codeartifact (==1.107.0)
Requires-Dist: aws-cdk.aws-codebuild (==1.107.0)
Requires-Dist: aws-cdk.aws-codecommit (==1.107.0)
Requires-Dist: aws-cdk.aws-codedeploy (==1.107.0)
Requires-Dist: aws-cdk.aws-codeguruprofiler (==1.107.0)
Requires-Dist: aws-cdk.aws-codegurureviewer (==1.107.0)
Requires-Dist: aws-cdk.aws-codepipeline (==1.107.0)
Requires-Dist: aws-cdk.aws-codestar (==1.107.0)
Requires-Dist: aws-cdk.aws-codestarconnections (==1.107.0)
Requires-Dist: aws-cdk.aws-codestarnotifications (==1.107.0)
Requires-Dist: aws-cdk.aws-cognito (==1.107.0)
Requires-Dist: aws-cdk.aws-config (==1.107.0)
Requires-Dist: aws-cdk.aws-customerprofiles (==1.107.0)
Requires-Dist: aws-cdk.aws-databrew (==1.107.0)
Requires-Dist: aws-cdk.aws-datapipeline (==1.107.0)
Requires-Dist: aws-cdk.aws-datasync (==1.107.0)
Requires-Dist: aws-cdk.aws-dax (==1.107.0)
Requires-Dist: aws-cdk.aws-detective (==1.107.0)
Requires-Dist: aws-cdk.aws-devopsguru (==1.107.0)
Requires-Dist: aws-cdk.aws-directoryservice (==1.107.0)
Requires-Dist: aws-cdk.aws-dlm (==1.107.0)
Requires-Dist: aws-cdk.aws-dms (==1.107.0)
Requires-Dist: aws-cdk.aws-docdb (==1.107.0)
Requires-Dist: aws-cdk.aws-dynamodb (==1.107.0)
Requires-Dist: aws-cdk.aws-ec2 (==1.107.0)
Requires-Dist: aws-cdk.aws-ecr (==1.107.0)
Requires-Dist: aws-cdk.aws-ecs (==1.107.0)
Requires-Dist: aws-cdk.aws-efs (==1.107.0)
Requires-Dist: aws-cdk.aws-eks (==1.107.0)
Requires-Dist: aws-cdk.aws-elasticache (==1.107.0)
Requires-Dist: aws-cdk.aws-elasticbeanstalk (==1.107.0)
Requires-Dist: aws-cdk.aws-elasticloadbalancing (==1.107.0)
Requires-Dist: aws-cdk.aws-elasticloadbalancingv2 (==1.107.0)
Requires-Dist: aws-cdk.aws-elasticsearch (==1.107.0)
Requires-Dist: aws-cdk.aws-emr (==1.107.0)
Requires-Dist: aws-cdk.aws-emrcontainers (==1.107.0)
Requires-Dist: aws-cdk.aws-events (==1.107.0)
Requires-Dist: aws-cdk.aws-eventschemas (==1.107.0)
Requires-Dist: aws-cdk.aws-finspace (==1.107.0)
Requires-Dist: aws-cdk.aws-fis (==1.107.0)
Requires-Dist: aws-cdk.aws-fms (==1.107.0)
Requires-Dist: aws-cdk.aws-frauddetector (==1.107.0)
Requires-Dist: aws-cdk.aws-fsx (==1.107.0)
Requires-Dist: aws-cdk.aws-gamelift (==1.107.0)
Requires-Dist: aws-cdk.aws-globalaccelerator (==1.107.0)
Requires-Dist: aws-cdk.aws-glue (==1.107.0)
Requires-Dist: aws-cdk.aws-greengrass (==1.107.0)
Requires-Dist: aws-cdk.aws-greengrassv2 (==1.107.0)
Requires-Dist: aws-cdk.aws-groundstation (==1.107.0)
Requires-Dist: aws-cdk.aws-guardduty (==1.107.0)
Requires-Dist: aws-cdk.aws-iam (==1.107.0)
Requires-Dist: aws-cdk.aws-imagebuilder (==1.107.0)
Requires-Dist: aws-cdk.aws-inspector (==1.107.0)
Requires-Dist: aws-cdk.aws-iot1click (==1.107.0)
Requires-Dist: aws-cdk.aws-iot (==1.107.0)
Requires-Dist: aws-cdk.aws-iotanalytics (==1.107.0)
Requires-Dist: aws-cdk.aws-iotcoredeviceadvisor (==1.107.0)
Requires-Dist: aws-cdk.aws-iotevents (==1.107.0)
Requires-Dist: aws-cdk.aws-iotfleethub (==1.107.0)
Requires-Dist: aws-cdk.aws-iotsitewise (==1.107.0)
Requires-Dist: aws-cdk.aws-iotthingsgraph (==1.107.0)
Requires-Dist: aws-cdk.aws-iotwireless (==1.107.0)
Requires-Dist: aws-cdk.aws-ivs (==1.107.0)
Requires-Dist: aws-cdk.aws-kendra (==1.107.0)
Requires-Dist: aws-cdk.aws-kinesis (==1.107.0)
Requires-Dist: aws-cdk.aws-kinesisanalytics (==1.107.0)
Requires-Dist: aws-cdk.aws-kinesisfirehose (==1.107.0)
Requires-Dist: aws-cdk.aws-kms (==1.107.0)
Requires-Dist: aws-cdk.aws-lakeformation (==1.107.0)
Requires-Dist: aws-cdk.aws-lambda (==1.107.0)
Requires-Dist: aws-cdk.aws-licensemanager (==1.107.0)
Requires-Dist: aws-cdk.aws-logs (==1.107.0)
Requires-Dist: aws-cdk.aws-lookoutmetrics (==1.107.0)
Requires-Dist: aws-cdk.aws-lookoutvision (==1.107.0)
Requires-Dist: aws-cdk.aws-macie (==1.107.0)
Requires-Dist: aws-cdk.aws-managedblockchain (==1.107.0)
Requires-Dist: aws-cdk.aws-mediaconnect (==1.107.0)
Requires-Dist: aws-cdk.aws-mediaconvert (==1.107.0)
Requires-Dist: aws-cdk.aws-medialive (==1.107.0)
Requires-Dist: aws-cdk.aws-mediapackage (==1.107.0)
Requires-Dist: aws-cdk.aws-mediastore (==1.107.0)
Requires-Dist: aws-cdk.aws-msk (==1.107.0)
Requires-Dist: aws-cdk.aws-mwaa (==1.107.0)
Requires-Dist: aws-cdk.aws-neptune (==1.107.0)
Requires-Dist: aws-cdk.aws-networkfirewall (==1.107.0)
Requires-Dist: aws-cdk.aws-networkmanager (==1.107.0)
Requires-Dist: aws-cdk.aws-nimblestudio (==1.107.0)
Requires-Dist: aws-cdk.aws-opsworks (==1.107.0)
Requires-Dist: aws-cdk.aws-opsworkscm (==1.107.0)
Requires-Dist: aws-cdk.aws-pinpoint (==1.107.0)
Requires-Dist: aws-cdk.aws-pinpointemail (==1.107.0)
Requires-Dist: aws-cdk.aws-qldb (==1.107.0)
Requires-Dist: aws-cdk.aws-quicksight (==1.107.0)
Requires-Dist: aws-cdk.aws-ram (==1.107.0)
Requires-Dist: aws-cdk.aws-rds (==1.107.0)
Requires-Dist: aws-cdk.aws-redshift (==1.107.0)
Requires-Dist: aws-cdk.aws-resourcegroups (==1.107.0)
Requires-Dist: aws-cdk.aws-robomaker (==1.107.0)
Requires-Dist: aws-cdk.aws-route53 (==1.107.0)
Requires-Dist: aws-cdk.aws-route53resolver (==1.107.0)
Requires-Dist: aws-cdk.aws-s3 (==1.107.0)
Requires-Dist: aws-cdk.aws-s3objectlambda (==1.107.0)
Requires-Dist: aws-cdk.aws-s3outposts (==1.107.0)
Requires-Dist: aws-cdk.aws-sagemaker (==1.107.0)
Requires-Dist: aws-cdk.aws-sam (==1.107.0)
Requires-Dist: aws-cdk.aws-sdb (==1.107.0)
Requires-Dist: aws-cdk.aws-secretsmanager (==1.107.0)
Requires-Dist: aws-cdk.aws-securityhub (==1.107.0)
Requires-Dist: aws-cdk.aws-servicecatalog (==1.107.0)
Requires-Dist: aws-cdk.aws-servicecatalogappregistry (==1.107.0)
Requires-Dist: aws-cdk.aws-servicediscovery (==1.107.0)
Requires-Dist: aws-cdk.aws-ses (==1.107.0)
Requires-Dist: aws-cdk.aws-signer (==1.107.0)
Requires-Dist: aws-cdk.aws-sns (==1.107.0)
Requires-Dist: aws-cdk.aws-sqs (==1.107.0)
Requires-Dist: aws-cdk.aws-ssm (==1.107.0)
Requires-Dist: aws-cdk.aws-ssmcontacts (==1.107.0)
Requires-Dist: aws-cdk.aws-ssmincidents (==1.107.0)
Requires-Dist: aws-cdk.aws-sso (==1.107.0)
Requires-Dist: aws-cdk.aws-stepfunctions (==1.107.0)
Requires-Dist: aws-cdk.aws-synthetics (==1.107.0)
Requires-Dist: aws-cdk.aws-timestream (==1.107.0)
Requires-Dist: aws-cdk.aws-transfer (==1.107.0)
Requires-Dist: aws-cdk.aws-waf (==1.107.0)
Requires-Dist: aws-cdk.aws-wafregional (==1.107.0)
Requires-Dist: aws-cdk.aws-wafv2 (==1.107.0)
Requires-Dist: aws-cdk.aws-workspaces (==1.107.0)
Requires-Dist: aws-cdk.aws-xray (==1.107.0)
Requires-Dist: aws-cdk.core (==1.107.0)
Requires-Dist: constructs (<4.0.0,>=3.3.69)
Requires-Dist: jsii (<2.0.0,>=1.29.0)
Requires-Dist: publication (>=0.0.3)

# Include CloudFormation templates in the CDK

<!--BEGIN STABILITY BANNER-->---


![cdk-constructs: Stable](https://img.shields.io/badge/cdk--constructs-stable-success.svg?style=for-the-badge)

---
<!--END STABILITY BANNER-->

This module contains a set of classes whose goal is to facilitate working
with existing CloudFormation templates in the CDK.
It can be thought of as an extension of the capabilities of the
[`CfnInclude` class](https://docs.aws.amazon.com/cdk/api/latest/docs/@aws-cdk_core.CfnInclude.html).

## Basic usage

Assume we have a file with an existing template.
It could be in JSON format, in a file `my-template.json`:

```json
{
  "Resources": {
    "Bucket": {
      "Type": "AWS::S3::Bucket",
      "Properties": {
        "BucketName": "some-bucket-name"
      }
    }
  }
}
```

Or it could by in YAML format, in a file `my-template.yaml`:

```yaml
Resources:
  Bucket:
    Type: AWS::S3::Bucket
    Properties:
      BucketName: some-bucket-name
```

It can be included in a CDK application with the following code:

```python
# Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
import aws_cdk.cloudformation_include as cfn_inc

cfn_template = cfn_inc.CfnInclude(self, "Template",
    template_file="my-template.json"
)
```

Or, if your template uses YAML:

```python
# Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
cfn_template = cfn_inc.CfnInclude(self, "Template",
    template_file="my-template.yaml"
)
```

**Note**: different YAML parsers sometimes don't agree on what exactly constitutes valid YAML.
If you get a YAML exception when including your template,
try converting it to JSON, and including that file instead.
If you're downloading your template from the CloudFormation AWS Console,
you can easily get it in JSON format by clicking the 'View in Designer'
button on the 'Template' tab -
once in Designer, select JSON in the "Choose template language"
radio buttons on the bottom pane.

This will add all resources from `my-template.json` / `my-template.yaml` into the CDK application,
preserving their original logical IDs from the template file.

Note that this including process will *not* execute any
[CloudFormation transforms](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/template-macros.html) -
including the [Serverless transform](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/transform-aws-serverless.html).

Any resource from the included template can be retrieved by referring to it by its logical ID from the template.
If you know the class of the CDK object that corresponds to that resource,
you can cast the returned object to the correct type:

```python
# Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
import aws_cdk.aws_s3 as s3

cfn_bucket = cfn_template.get_resource("Bucket")
```

Note that any resources not present in the latest version of the CloudFormation schema
at the time of publishing the version of this module that you depend on,
including [Custom Resources](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-cfn-customresource.html),
will be returned as instances of the class `CfnResource`,
and so cannot be cast to a different resource type.

Any modifications made to that resource will be reflected in the resulting CDK template;
for example, the name of the bucket can be changed:

```python
# Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
cfn_bucket.bucket_name = "my-bucket-name"
```

You can also refer to the resource when defining other constructs,
including the higher-level ones
(those whose name does not start with `Cfn`),
for example:

```python
# Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
import aws_cdk.aws_iam as iam

role = iam.Role(self, "Role",
    assumed_by=iam.AnyPrincipal()
)
role.add_to_policy(iam.PolicyStatement(
    actions=["s3:*"],
    resources=[cfn_bucket.attr_arn]
))
```

If you need, you can also convert the CloudFormation resource to a higher-level
resource by importing it:

```python
# Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
bucket = s3.Bucket.from_bucket_name(self, "L2Bucket", cfn_bucket.ref)
```

## Non-resource template elements

In addition to resources,
you can also retrieve and mutate all other template elements:

* [Parameters](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/parameters-section-structure.html):

  ```python
  # Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
  import aws_cdk.core as core

  param = cfn_template.get_parameter("MyParameter")

  # mutating the parameter
  param.default = "MyDefault"
  ```
* [Conditions](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/conditions-section-structure.html):

  ```python
  # Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
  import aws_cdk.core as core

  condition = cfn_template.get_condition("MyCondition")

  # mutating the condition
  condition.expression = core.Fn.condition_equals(1, 2)
  ```
* [Mappings](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/mappings-section-structure.html):

  ```python
  # Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
  import aws_cdk.core as core

  mapping = cfn_template.get_mapping("MyMapping")

  # mutating the mapping
  mapping.set_value("my-region", "AMI", "ami-04681a1dbd79675a5")
  ```
* [Service Catalog template Rules](https://docs.aws.amazon.com/servicecatalog/latest/adminguide/reference-template_constraint_rules.html):

  ```python
  # Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
  import aws_cdk.core as core

  rule = cfn_template.get_rule("MyRule")

  # mutating the rule
  rule.add_assertion(core.Fn.condition_contains(["m1.small"], my_parameter.value), "MyParameter has to be m1.small")
  ```
* [Outputs](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/outputs-section-structure.html):

  ```python
  # Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
  import aws_cdk.core as core

  output = cfn_template.get_output("MyOutput")

  # mutating the output
  output.value = cfn_bucket.attr_arn
  ```
* [Hooks for blue-green deployments](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/blue-green.html):

  ```python
  # Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
  import aws_cdk.core as core

  hook = cfn_template.get_hook("MyOutput")

  # mutating the hook
  code_deploy_hook = hook
  code_deploy_hook.service_role = my_role.role_arn
  ```

## Parameter replacement

If your existing template uses CloudFormation Parameters,
you may want to remove them in favor of build-time values.
You can do that using the `parameters` property:

```python
# Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
inc.CfnInclude(self, "includeTemplate",
    template_file="path/to/my/template",
    parameters={
        "MyParam": "my-value"
    }
)
```

This will replace all references to `MyParam` with the string `'my-value'`,
and `MyParam` will be removed from the 'Parameters' section of the template.

## Nested Stacks

This module also supports templates that use [nested stacks](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/using-cfn-nested-stacks.html).

For example, if you have the following parent template:

```json
{
  "Resources": {
    "ChildStack": {
      "Type": "AWS::CloudFormation::Stack",
      "Properties": {
        "TemplateURL": "https://my-s3-template-source.s3.amazonaws.com/child-stack.json"
      }
    }
  }
}
```

where the child template pointed to by `https://my-s3-template-source.s3.amazonaws.com/child-stack.json` is:

```json
{
  "Resources": {
    "MyBucket": {
      "Type": "AWS::S3::Bucket"
    }
  }
}
```

You can include both the parent stack,
and the nested stack in your CDK application as follows:

```python
# Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
parent_template = inc.CfnInclude(self, "ParentStack",
    template_file="path/to/my-parent-template.json",
    load_nested_stacks={
        "ChildStack": {
            "template_file": "path/to/my-nested-template.json"
        }
    }
)
```

Here, `path/to/my-nested-template.json`
represents the path on disk to the downloaded template file from the original template URL of the nested stack
(`https://my-s3-template-source.s3.amazonaws.com/child-stack.json`).
In the CDK application,
this file will be turned into an [Asset](https://docs.aws.amazon.com/cdk/latest/guide/assets.html),
and the `TemplateURL` property of the nested stack resource
will be modified to point to that asset.

The included nested stack can be accessed with the `getNestedStack` method:

```python
# Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
included_child_stack = parent_template.get_nested_stack("ChildStack")
child_stack = included_child_stack.stack
child_template = included_child_stack.included_template
```

Now you can reference resources from `ChildStack`,
and modify them like any other included template:

```python
# Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
cfn_bucket = child_template.get_resource("MyBucket")
cfn_bucket.bucket_name = "my-new-bucket-name"

role = iam.Role(child_stack, "MyRole",
    assumed_by=iam.AccountRootPrincipal()
)

role.add_to_policy(iam.PolicyStatement(
    actions=["s3:GetObject*", "s3:GetBucket*", "s3:List*"
    ],
    resources=[cfn_bucket.attr_arn]
))
```

You can also include the nested stack after the `CfnInclude` object was created,
instead of doing it on construction:

```python
# Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
included_child_stack = parent_template.load_nested_stack("ChildTemplate",
    template_file="path/to/my-nested-template.json"
)
```

## Vending CloudFormation templates as Constructs

In many cases, there are existing CloudFormation templates that are not entire applications,
but more like specialized fragments, implementing a particular pattern or best practice.
If you have templates like that,
you can use the `CfnInclude` class to vend them as CDK Constructs:

```python
# Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
import path as path


class MyConstruct(Construct):
    def __init__(self, scope, id):
        super().__init__(scope, id)

        # include a template inside the Construct
        cfn_inc.CfnInclude(self, "MyConstruct",
            template_file=path.join(__dirname, "my-template.json"),
            preserve_logical_ids=False
        )
```

Notice the `preserveLogicalIds` parameter -
it makes sure the logical IDs of all the included template elements are re-named using CDK's algorithm,
guaranteeing they are unique within your application.
Without that parameter passed,
instantiating `MyConstruct` twice in the same Stack would result in duplicated logical IDs.


