Metadata-Version: 2.1
Name: aws-cdk.cloudformation-include
Version: 1.50.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: Typing :: Typed
Classifier: Development Status :: 4 - Beta
Classifier: License :: OSI Approved
Requires-Python: >=3.6
Description-Content-Type: text/markdown
Requires-Dist: jsii (<2.0.0,>=1.8.0)
Requires-Dist: publication (>=0.0.3)
Requires-Dist: aws-cdk.alexa-ask (==1.50.0)
Requires-Dist: aws-cdk.aws-accessanalyzer (==1.50.0)
Requires-Dist: aws-cdk.aws-acmpca (==1.50.0)
Requires-Dist: aws-cdk.aws-amazonmq (==1.50.0)
Requires-Dist: aws-cdk.aws-amplify (==1.50.0)
Requires-Dist: aws-cdk.aws-apigateway (==1.50.0)
Requires-Dist: aws-cdk.aws-apigatewayv2 (==1.50.0)
Requires-Dist: aws-cdk.aws-appconfig (==1.50.0)
Requires-Dist: aws-cdk.aws-applicationautoscaling (==1.50.0)
Requires-Dist: aws-cdk.aws-appmesh (==1.50.0)
Requires-Dist: aws-cdk.aws-appstream (==1.50.0)
Requires-Dist: aws-cdk.aws-appsync (==1.50.0)
Requires-Dist: aws-cdk.aws-athena (==1.50.0)
Requires-Dist: aws-cdk.aws-autoscaling (==1.50.0)
Requires-Dist: aws-cdk.aws-autoscalingplans (==1.50.0)
Requires-Dist: aws-cdk.aws-backup (==1.50.0)
Requires-Dist: aws-cdk.aws-batch (==1.50.0)
Requires-Dist: aws-cdk.aws-budgets (==1.50.0)
Requires-Dist: aws-cdk.aws-cassandra (==1.50.0)
Requires-Dist: aws-cdk.aws-ce (==1.50.0)
Requires-Dist: aws-cdk.aws-certificatemanager (==1.50.0)
Requires-Dist: aws-cdk.aws-chatbot (==1.50.0)
Requires-Dist: aws-cdk.aws-cloud9 (==1.50.0)
Requires-Dist: aws-cdk.aws-cloudfront (==1.50.0)
Requires-Dist: aws-cdk.aws-cloudtrail (==1.50.0)
Requires-Dist: aws-cdk.aws-cloudwatch (==1.50.0)
Requires-Dist: aws-cdk.aws-codebuild (==1.50.0)
Requires-Dist: aws-cdk.aws-codecommit (==1.50.0)
Requires-Dist: aws-cdk.aws-codedeploy (==1.50.0)
Requires-Dist: aws-cdk.aws-codeguruprofiler (==1.50.0)
Requires-Dist: aws-cdk.aws-codepipeline (==1.50.0)
Requires-Dist: aws-cdk.aws-codestar (==1.50.0)
Requires-Dist: aws-cdk.aws-codestarconnections (==1.50.0)
Requires-Dist: aws-cdk.aws-codestarnotifications (==1.50.0)
Requires-Dist: aws-cdk.aws-cognito (==1.50.0)
Requires-Dist: aws-cdk.aws-config (==1.50.0)
Requires-Dist: aws-cdk.aws-datapipeline (==1.50.0)
Requires-Dist: aws-cdk.aws-dax (==1.50.0)
Requires-Dist: aws-cdk.aws-detective (==1.50.0)
Requires-Dist: aws-cdk.aws-directoryservice (==1.50.0)
Requires-Dist: aws-cdk.aws-dlm (==1.50.0)
Requires-Dist: aws-cdk.aws-dms (==1.50.0)
Requires-Dist: aws-cdk.aws-docdb (==1.50.0)
Requires-Dist: aws-cdk.aws-dynamodb (==1.50.0)
Requires-Dist: aws-cdk.aws-ec2 (==1.50.0)
Requires-Dist: aws-cdk.aws-ecr (==1.50.0)
Requires-Dist: aws-cdk.aws-ecs (==1.50.0)
Requires-Dist: aws-cdk.aws-efs (==1.50.0)
Requires-Dist: aws-cdk.aws-eks (==1.50.0)
Requires-Dist: aws-cdk.aws-elasticache (==1.50.0)
Requires-Dist: aws-cdk.aws-elasticbeanstalk (==1.50.0)
Requires-Dist: aws-cdk.aws-elasticloadbalancing (==1.50.0)
Requires-Dist: aws-cdk.aws-elasticloadbalancingv2 (==1.50.0)
Requires-Dist: aws-cdk.aws-elasticsearch (==1.50.0)
Requires-Dist: aws-cdk.aws-emr (==1.50.0)
Requires-Dist: aws-cdk.aws-events (==1.50.0)
Requires-Dist: aws-cdk.aws-eventschemas (==1.50.0)
Requires-Dist: aws-cdk.aws-fms (==1.50.0)
Requires-Dist: aws-cdk.aws-fsx (==1.50.0)
Requires-Dist: aws-cdk.aws-gamelift (==1.50.0)
Requires-Dist: aws-cdk.aws-globalaccelerator (==1.50.0)
Requires-Dist: aws-cdk.aws-glue (==1.50.0)
Requires-Dist: aws-cdk.aws-greengrass (==1.50.0)
Requires-Dist: aws-cdk.aws-guardduty (==1.50.0)
Requires-Dist: aws-cdk.aws-iam (==1.50.0)
Requires-Dist: aws-cdk.aws-imagebuilder (==1.50.0)
Requires-Dist: aws-cdk.aws-inspector (==1.50.0)
Requires-Dist: aws-cdk.aws-iot (==1.50.0)
Requires-Dist: aws-cdk.aws-iot1click (==1.50.0)
Requires-Dist: aws-cdk.aws-iotanalytics (==1.50.0)
Requires-Dist: aws-cdk.aws-iotevents (==1.50.0)
Requires-Dist: aws-cdk.aws-iotthingsgraph (==1.50.0)
Requires-Dist: aws-cdk.aws-kinesis (==1.50.0)
Requires-Dist: aws-cdk.aws-kinesisanalytics (==1.50.0)
Requires-Dist: aws-cdk.aws-kinesisfirehose (==1.50.0)
Requires-Dist: aws-cdk.aws-kms (==1.50.0)
Requires-Dist: aws-cdk.aws-lakeformation (==1.50.0)
Requires-Dist: aws-cdk.aws-lambda (==1.50.0)
Requires-Dist: aws-cdk.aws-logs (==1.50.0)
Requires-Dist: aws-cdk.aws-macie (==1.50.0)
Requires-Dist: aws-cdk.aws-managedblockchain (==1.50.0)
Requires-Dist: aws-cdk.aws-mediaconvert (==1.50.0)
Requires-Dist: aws-cdk.aws-medialive (==1.50.0)
Requires-Dist: aws-cdk.aws-mediastore (==1.50.0)
Requires-Dist: aws-cdk.aws-msk (==1.50.0)
Requires-Dist: aws-cdk.aws-neptune (==1.50.0)
Requires-Dist: aws-cdk.aws-networkmanager (==1.50.0)
Requires-Dist: aws-cdk.aws-opsworks (==1.50.0)
Requires-Dist: aws-cdk.aws-opsworkscm (==1.50.0)
Requires-Dist: aws-cdk.aws-pinpoint (==1.50.0)
Requires-Dist: aws-cdk.aws-pinpointemail (==1.50.0)
Requires-Dist: aws-cdk.aws-qldb (==1.50.0)
Requires-Dist: aws-cdk.aws-ram (==1.50.0)
Requires-Dist: aws-cdk.aws-rds (==1.50.0)
Requires-Dist: aws-cdk.aws-redshift (==1.50.0)
Requires-Dist: aws-cdk.aws-resourcegroups (==1.50.0)
Requires-Dist: aws-cdk.aws-robomaker (==1.50.0)
Requires-Dist: aws-cdk.aws-route53 (==1.50.0)
Requires-Dist: aws-cdk.aws-route53resolver (==1.50.0)
Requires-Dist: aws-cdk.aws-s3 (==1.50.0)
Requires-Dist: aws-cdk.aws-sagemaker (==1.50.0)
Requires-Dist: aws-cdk.aws-sam (==1.50.0)
Requires-Dist: aws-cdk.aws-sdb (==1.50.0)
Requires-Dist: aws-cdk.aws-secretsmanager (==1.50.0)
Requires-Dist: aws-cdk.aws-securityhub (==1.50.0)
Requires-Dist: aws-cdk.aws-servicecatalog (==1.50.0)
Requires-Dist: aws-cdk.aws-servicediscovery (==1.50.0)
Requires-Dist: aws-cdk.aws-ses (==1.50.0)
Requires-Dist: aws-cdk.aws-sns (==1.50.0)
Requires-Dist: aws-cdk.aws-sqs (==1.50.0)
Requires-Dist: aws-cdk.aws-ssm (==1.50.0)
Requires-Dist: aws-cdk.aws-stepfunctions (==1.50.0)
Requires-Dist: aws-cdk.aws-synthetics (==1.50.0)
Requires-Dist: aws-cdk.aws-transfer (==1.50.0)
Requires-Dist: aws-cdk.aws-waf (==1.50.0)
Requires-Dist: aws-cdk.aws-wafregional (==1.50.0)
Requires-Dist: aws-cdk.aws-wafv2 (==1.50.0)
Requires-Dist: aws-cdk.aws-workspaces (==1.50.0)
Requires-Dist: aws-cdk.core (==1.50.0)
Requires-Dist: constructs (<4.0.0,>=3.0.2)

# Include CloudFormation templates in the CDK

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


![cdk-constructs: Experimental](https://img.shields.io/badge/cdk--constructs-experimental-important.svg?style=for-the-badge)

> The APIs of higher level constructs in this module are experimental and under active development. They are subject to non-backward compatible changes or removal in any future version. These are not subject to the [Semantic Versioning](https://semver.org/) model and breaking changes will be announced in the release notes. This means that while you may use them, you may need to update your source code when upgrading to a newer version of this package.

---
<!--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](../@aws-cdk/core/lib/cfn-include.ts).

## 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 our template is YAML, we can use

```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"
)
```

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

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")
```

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 by its name:

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

## Conditions

If your template uses [CloudFormation Conditions](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/conditions-section-structure.html),
you can retrieve them from your template:

```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")
```

The `CfnCondition` object is mutable,
and any changes you make to it will be reflected in the resulting template:

```python
# Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
condition.expression = core.Fn.condition_equals(1, 2)
```

## Outputs

If your template uses [CloudFormation Outputs](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/outputs-section-structure.html),
you can retrieve them from your template:

```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")
```

The `CfnOutput` object is mutable,
and any changes you make to it will be reflected in the resulting template:

```python
# Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
output.value = cfn_bucket.attr_arn
```

## Known limitations

This module is still in its early, experimental stage,
and so does not implement all features of CloudFormation templates.
All items unchecked below are currently not supported.

### Ability to retrieve CloudFormation objects from the template:

* [x] Resources
* [x] Parameters
* [x] Conditions
* [x] Outputs

### [Resource attributes](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-product-attribute-reference.html):

* [x] Properties
* [x] Condition
* [x] DependsOn
* [x] CreationPolicy
* [x] UpdatePolicy
* [x] UpdateReplacePolicy
* [x] DeletionPolicy
* [x] Metadata

### [CloudFormation functions](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/intrinsic-function-reference.html):

* [x] Ref
* [x] Fn::GetAtt
* [x] Fn::Join
* [x] Fn::If
* [x] Fn::And
* [x] Fn::Equals
* [x] Fn::Not
* [x] Fn::Or
* [x] Fn::Base64
* [x] Fn::Cidr
* [x] Fn::FindInMap
* [x] Fn::GetAZs
* [x] Fn::ImportValue
* [x] Fn::Select
* [x] Fn::Split
* [ ] Fn::Sub
* [x] Fn::Transform


