Page updated Jan 16, 2024

Use CloudFormation to add custom AWS resources

The Amplify CLI provides the ability to add custom AWS resources with AWS CloudFormation. Running the amplify add custom command in your Amplify project provides CloudFormation starter templates along with mechanisms to reference other Amplify-generated resources.

To add custom AWS resources using AWS CloudFormation, run the following command:

amplify add custom
1amplify add custom
? How do you want to define this custom resource? … (Use arrow keys or type to filter) AWS CDK ❯ AWS CloudFormation
1? How do you want to define this custom resource? … (Use arrow keys or type to filter)
2 AWS CDK
3❯ AWS CloudFormation

A skeleton CloudFormation template is generated in the amplify/backend/custom/<resource-name> directory. The additional AWS resources can be defined in the <resource-name>-cloudformation-template.json CloudFormation template file.

{ "AWSTemplateFormatVersion": "2010-09-09", "Parameters": { "env": { "Type": "String" } }, "Resources": { "snstopic1234": { "Type": "AWS::SNS::Topic", "Properties": { "TopicName": { "Fn::Join": [ "", [ "sns-topic-1234-", { "Ref": "env" } ] ] } } }, "snstopicemailsub1234": { "Type": "AWS::SNS::Subscription", "Properties": { "Protocol": "email", "TopicArn": { "Ref": "snstopic1234" }, "Endpoint": "<your-email-address>" } } }, "Outputs": {} }
1{
2 "AWSTemplateFormatVersion": "2010-09-09",
3 "Parameters": {
4 "env": {
5 "Type": "String"
6 }
7 },
8 "Resources": {
9 "snstopic1234": {
10 "Type": "AWS::SNS::Topic",
11 "Properties": {
12 "TopicName": {
13 "Fn::Join": [ "", [ "sns-topic-1234-", { "Ref": "env" } ] ]
14 }
15 }
16 },
17 "snstopicemailsub1234": {
18 "Type": "AWS::SNS::Subscription",
19 "Properties": {
20 "Protocol": "email",
21 "TopicArn": {
22 "Ref": "snstopic1234"
23 },
24 "Endpoint": "<your-email-address>"
25 }
26 }
27 },
28 "Outputs": {}
29}

Note: Always append the Amplify environment name (env parameter) to a resource name to ensure correct behavior with Amplify's multi-environment workflows.

Reference Amplify backend name

Amplify CLI will automatically populate the env parameter in the top of your CloudFormation template.

... "Parameters": { "env": { "Type": "String" } }, ...
1...
2 "Parameters": {
3 "env": {
4 "Type": "String"
5 }
6 },
7...

To reference the parameter use the Ref intrinsic function:

... "Resources": { "snstopic1234": { "Type": "AWS::SNS::Topic", "Properties": { "TopicName": { "Fn::Join": [ "", [ "sns-topic-1234-", { "Ref": "env" } ] ] } } } } ...
1...
2 "Resources": {
3 "snstopic1234": {
4 "Type": "AWS::SNS::Topic",
5 "Properties": {
6 "TopicName": {
7 "Fn::Join": [ "", [ "sns-topic-1234-", { "Ref": "env" } ] ]
8 }
9 }
10 }
11 }
12...

Reference Amplify-generated resources

The CloudFormation template for custom AWS resources can reference Amplify-generated resources' CloudFormation outputs. To reference another resource's output, run:

amplify update custom
1amplify update custom
✔ Do you want to access Amplify generated resources in your custom CloudFormation file? (y/N) · yes ? Select the categories you want this custom resource to have access to: ❯ <category> ? Function has 2 resources in this project. Select the one you would like your custom resource to access ❯ ...
1✔ Do you want to access Amplify generated resources in your custom CloudFormation file? (y/N) · yes
2? Select the categories you want this custom resource to have access to:
3❯ <category>
4? Function has 2 resources in this project. Select the one you would like your custom resource to access
5❯ ...

Once the resources are selected, you can reference the resources' output listed as parameters on the top of your CloudFormation template. To reference the parameter use the Ref intrinsic function:

... "Parameters": { ..., "myFunctionArn": { "Type": "String" } }, "Resources": { ...: { "Type": ..., "Properties": { ...: { "Ref": "myFunctionArn"} } } } ...
1...
2 "Parameters": {
3 ...,
4 "myFunctionArn": {
5 "Type": "String"
6 }
7 },
8 "Resources": {
9 ...: {
10 "Type": ...,
11 "Properties": {
12 ...: { "Ref": "myFunctionArn"}
13 }
14 }
15 }
16...