Get started with cross-stack references in AWS CloudFormation

Cross-stack references in AWS CloudFormation allow you to share information between stacks. It enables you to reference resources from one stack in another stack, providing a way to create dependencies and establish communication between stacks.

Cross-stack references are useful in scenarios where you have multiple stacks that need to interact with each other. For example, you might have a stack for a VPC (Virtual Private Cloud) and another stack for an application that needs to use that VPC. By using cross-stack references, you can pass the VPC information from the VPC stack to the application stack, allowing the application to be deployed within the specified VPC.

To establish a cross-stack reference, you need to perform the following steps:

Export values from the source stack: In the stack that contains the resource you want to reference, you define an export value for that resource. This export value can be an output from the stack or a resource attribute.
Import values in the target stack: In the stack where you want to reference the resource, you use the Fn::ImportValue function to import the exported value from the source stack. This function allows you to access the exported value within the target stack.

Here's an example that demonstrates cross-stack references in CloudFormation using YAML syntax:

Source stack (VPC stack):

Resources:
  MyVPC:
    Type: AWS::EC2::VPC
    Properties:
      ...

Outputs:
  VPCId:
    Value: !Ref MyVPC
    Export:
      Name: MyVPC-VPCId

Target stack (Application stack):

Resources:
  MyEC2Instance:
    Type: AWS::EC2::Instance
    Properties:
      ...
      SubnetId: !ImportValue MyVPC-VPCId

In this example, the VPC stack exports the VPC ID with the name "MyVPC-VPCId". The application stack then imports the VPC ID using the !ImportValue function and uses it as the SubnetId for the EC2 instance resource.

By using cross-stack references, you can create more modular and reusable CloudFormation templates. It allows you to manage resources in separate stacks while maintaining the necessary dependencies and connections between them.

What is Reference function in the CloudFormation template

In AWS CloudFormation templates, the Reference function is used to retrieve the value of a resource or parameter defined in the same template. It allows you to dynamically reference the properties of other resources or parameters within your template.

The syntax for the Reference function is as follows:

{"Ref" : "logicalName"}

Here, "logicalName" represents the logical name of the resource or parameter you want to reference. The logical name is a unique identifier that you assign to each resource or parameter in your template.

When the CloudFormation stack is created or updated, the Reference function is evaluated, and the value of the specified resource or parameter is returned.

The Reference function can be used in various contexts within a CloudFormation template, such as:

Properties of other resources: You can reference the properties of one resource within another resource's properties. For example, if you have an Amazon EC2 instance and want to specify its security group, you can use the Reference function to retrieve the security group ID.
Outputs: You can use the Reference function to define outputs that provide values from resources in your stack. These outputs can be used to pass information to other systems or to provide information to users.
Conditions: The Reference function can be used within conditions to evaluate the state of a resource or parameter. It allows you to conditionally create or update resources based on their current state.
Metadata: The Reference function can also be used in the Metadata section of a resource. This allows you to include dynamic values or retrieve information about other resources during stack creation or update.

It's important to note that the Reference function can only be used to reference resources or parameters within the same CloudFormation template. If you need to reference resources or parameters from other templates or stacks, you can use the AWS CloudFormation Export/Import mechanism to achieve that.

Hands-on lab prerequisites

To create a cross-stack reference, use the Export output field to flag the value of a resource output for export. Then, use the Fn::ImportValue intrinsic function to import the value. For more information, see Outputs and Fn::ImportValue.

Before you begin this walkthrough, check that you have AWS Identity and Access Management (IAM) permissions to use all of the following services: Amazon VPC, Amazon EC2, and AWS CloudFormation.

AWS CloudFormation is a free service. However, you are charged for the AWS resources that you include in your stacks at the current rate for each one. For more information about AWS pricing, see the detail page for each product.

The following restrictions apply to cross-stack references:

For each AWS account, Export names must be unique within a region.
You can't create cross-stack references across regions. You can use the intrinsic function Fn::ImportValue to import only values that have been exported within the same region.
For outputs, the value of the Name property of an Export can't use Ref or GetAtt functions that depend on a resource.

Similarly, the ImportValue function can't include Ref or GetAtt functions that depend on a resource.
You can't delete a stack if another stack references one of its outputs.
You can't modify or remove an output value that is referenced by another stack.

Step 1: Use a sample template to create a network stack

The network stack contains the VPC, security group, and subnet that you will use in the web application stack. In addition to these resources, the network stack creates an Internet gateway and routing tables to enable public access.

You must create this stack before you create the web application stack. If you create the web application stack first, it won't have a security group or subnet.

To create the network stack

Open the AWS CloudFormation console and choose Create stack.
Choose Template is ready, and in the Specify template section choose Amazon S3 URL. Copy and paste the following URL into the text box: https://s3.amazonaws.com/cloudformation-examples/user-guide/cross-stack/SampleNetworkCrossStack.template

The link provides the location of the network stack template. To see the resources that the stack will create, choose the link, which opens the template. In the outputs section, you can see the networking resources that the sample template exports. The names of the exported resources are prefixed with the stack's name in case you export networking resources from other stacks. When users import networking resources, they can specify from which stack the resources are imported.
After reviewing the template, choose Next.
For Stack name, type SampleNetworkCrossStack, and then choose Next.

Record the name of this stack. You'll need the stack name when you launch the web application stack.
Choose Next. For this walkthrough, you don't need to add tags or specify advanced settings.
Ensure that the stack name and template URL are correct, and then choose Create stack.

It might take several minutes for AWS CloudFormation to create your stack. Wait until all resources have been successfully created before proceeding to create the web application stack.
To monitor progress, view the stack events. For more information, see Viewing AWS CloudFormation stack data and resources on the AWS Management Console.

Step 2: Use a sample template to create a web application stack

The web application stack creates an EC2 instance that uses the security group and subnet from the network stack.

You must create this stack in the same region as the network stack.

To create the web application stack

Open the AWS CloudFormation console, and choose Create stack.
Choose Template is ready, and in the Specify template section choose Amazon S3 URL. Copy and paste the following URL into the text box: https://s3.amazonaws.com/cloudformation-examples/user-guide/cross-stack/SampleWebAppCrossStack.template

The link provides the location of the web application template. To see the resources that the stack will create, choose the link, which will open the template. In the resources section, view the EC2 instance's properties. You can see how the networking resources are imported from another stack by using the Fn::ImportValue function.

Exported values:

After reviewing the template, choose Next.
For Stack name, type SampleWebAppCrossStack. In the Parameters section, use the default value for the NetworkStackName parameter, and then choose Next.

The sample template uses the parameter value to specify from which stack to import values.
Choose Next. For this walkthrough, you don't need to add tags or specify advanced settings.
Ensure that the stack name and template URL are correct, and then choose Create stack.

It might take several minutes for AWS CloudFormation to create your stack.
After the stack has been created, view its resources and note the instance ID. For more information on viewing stack resources, see Viewing AWS CloudFormation stack data and resources on the AWS Management Console.

To verify the instance's security group and subnet, view the instance's properties in the Amazon EC2 console. If the instance uses the security group and subnet from the SampleNetworkCrossStack stack, you have successfully created a cross-stack reference.

Use the console to view the stack outputs and the example website URL to verify that the web application is running. For more information, see Viewing AWS CloudFormation stack data and resources on the AWS Management Console.

Step 3: Clean up your resources

To ensure that you are not charged for unwanted services, delete the stacks.

To delete the stacks

In the AWS CloudFormation console, choose the SampleWebAppCrossStack stack.
Choose Actions, and then choose Delete stack.
In the confirmation message, choose Delete.
After the stack has been deleted, repeat the same steps for the SampleNetworkCrossStack stack.

Wait until AWS CloudFormation completely deletes the SampleWebAppCrossStack stack. If the EC2 instance is still running in the VPC, AWS CloudFormation won't delete the VPC in the SampleNetworkCrossStack stack.

All of the resources that you have previously created are deleted.

Use the sample templates from this walkthrough to build your own cross-referenced stacks.