Note: The AWS Adapter is a technical preview and not ready for production usage. Its API is not stable and things might break unexpectedly.
The AwsTerraformAdapter is included in the @cdktf/aws-cdk package and allows you to use Amazon Web Services Cloud Development Kit (AWS CDK) constructs in your CDK for Terraform (CDKTF) projects.
You need to manually map resources that the AWS Cloud Control API does not yet support to specific Terraform resources because attribute names and resource types differ between CloudFormation and Terraform. Some manual mappings are included in the adapter, and we are happy to accept PRs that add manual mappings for currently unsupported resources!
The AwsTerraformAdapter adds an Aspect to MyStack that is invoked when the stack is synthesized. That Aspect then iterates over all AWS CDK constructs that have been added to the adapter, converts them to CDK for Terraform constructs, and adds them to the stack. It does not add the AWS CDK constructs themselves.
While some mappings are already included, you need to manually map most resources that the AWS Cloud Control API does not yet support (supported resources).
The following example shows how to write and register a mapping for an AWS::DynamoDB::Table CloudFormation resource.
The adapter will throw an error explaining that there is currently no mapping in place for a DynamoDB table resource.
Error: Unsupported resource Type AWS::DynamoDB::Table. There is no custom mapping registered for AWS::DynamoDB::Table and the AWS CloudControl API does not seem to support it yet. If you think this is an error or you need support for this resource, file an issue at: https://github.com/hashicorp/cdktf-aws-cdk/issues/new?title=Unsupported%20Resource%20Type%20%60AWS::DynamoDB::Table%60 and mention the AWS CDK constructs you want to use
Error: Unsupported resource Type AWS::DynamoDB::Table. There is no custom mapping registered for AWS::DynamoDB::Table and the AWS CloudControl API does not seem to support it yet. If you think this is an error or you need support for this resource, file an issue at: https://github.com/hashicorp/cdktf-aws-cdk/issues/new?title=Unsupported%20Resource%20Type%20%60AWS::DynamoDB::Table%60 and mention the AWS CDK constructs you want to use
To write a custom mapping, add the following code right below the imports and above the stack MyStack.
The example code imports the registerMapping function and invokes it with arguments for registering an AWS::DynamoDB::Table resource. The second argument to the function is an object with two parts: resource and attributes. The resource is a function that is called for each instance of the registered CloudFormation type. The example logs the props and returns null, so AWS doesn't create any resources.
Write code that maps all attributes to a format that matches the Terraform resource for an AWS DynamoDBTable. For the target schema, you can either look at the docs on the Terraform Registry or at the code of the DynamoDB.DynamodbTableConfig you will supply to the resource upon creation.
The logged props show that you need to support at least setting these attributes and that you need to make sure they appear in the resulting CDKTF resources.
Synthesizing the code with this initial mapping function fails with an error listing properties that may not be properly mapped. CDKTF checks whether there are any object properties left on the props object (that are not undefined) after the mapping function returned. This is a safeguard of the mapping implementation to block mappings that do not support all properties at the time they were written.
The following example adds mapping for missing values in the error message. First, it maps the AttributeDefinitions array to make sure it fits the schema of the Terraform resource. It also looks up the hashKey in the KeySchema array. Finally, it deletes the properties that have been handled and returns a new DynamodbTable resource.
Synthesizing again using this mapping still produces an error.
Error: cannot map some properties of AWS::DynamoDB::Table: {
"ProvisionedThroughput": {
"ReadCapacityUnits": 5,
"WriteCapacityUnits": 5
}
}
Error: cannot map some properties of AWS::DynamoDB::Table: {
"ProvisionedThroughput": {
"ReadCapacityUnits": 5,
"WriteCapacityUnits": 5
}
}
The error indicates that the ProvisionedThroughput property has not yet been mapped or deleted. The following example shows a complete mapping for the DynamoDB table.
This code synthesizes without error and produces the following aws_dynamodb_table resource in the cdk.tf.json output file (available in ./cdktf.out/stacks/<stack>).
You should also map the attributes argument. When AWS CDK constructs reference each other's properties, they do so via the CloudFormation property name of the resource.
The follwing example maps the Arn CloudFormation property to the .arn of the Terraform resource. While this example might look like something that could be handled automatically, there are cases where this cannot map directly. For example, there are some resources that do not have a direct representation in Terraform but do in CloudFormation (and vice versa).
The adapter is an early preview of interoperability with AWS CDK constructs, and it has the following limitations:
Limited interoperability between CDKTF and AWS CDK tokens. For example, passing Terraform functions as arguments into AWS CDK constructs might unexpectedly fail.
AWS CDK App, Stack, and nested Stack constructs are not supported.
These CloudFormation features are not yet supported: Transforms, Parameters, Mappings, and Includes.
These AWS CDK features are not yet supported: Assets, Aspects, and Annotations.