Search across all documentation pages
A single flat template does not scale past a certain size or a certain number of teams touching it. CloudFormation gives you two ways to split a large deployment into smaller pieces: nested stacks, where one stack embeds others as resources, and cross-stack references, where independent stacks share values through exported outputs.
They solve similar-sounding problems but compose differently, and knowing which one fits is the point of this page.
A nested stack is declared like any other resource, using the type AWS::CloudFormation::Stack, with TemplateURL pointing at the child template's location in S3.
# --- Parent template (network.yaml) ---
Resources:
VpcStack:
Type: AWS::CloudFormation::Stack
Properties:
TemplateURL: https://my-templates-bucket.s3.amazonaws.com/vpc-child.yaml
Parameters:
CidrBlock: 10.0.0.0/16From the SDK, deploying the parent is an ordinary CreateStack call - CloudFormation resolves and creates the nested stack automatically as part of it.
# --- Python (boto3) ---
import boto3
with open("network.yaml") as f:
template = f.read()
cfn = boto3.client("cloudformation", region_name="us-east-1")
cfn.create_stack(
StackName="network-parent",
TemplateBody=template,
Capabilities=["CAPABILITY_IAM"],
)// --- TypeScript (AWS SDK v3) ---
import { readFileSync } from "fs";
import { CloudFormationClient, CreateStackCommand } from "@aws-sdk/client-cloudformation";
const template = readFileSync("network.yaml", "utf-8");
const cfn = new CloudFormationClient({ region: "us-east-1" });
await cfn.send(new CreateStackCommand({
StackName: "network-parent",
TemplateBody: template,
Capabilities: ["CAPABILITY_IAM"],
}));Note the child template must already exist at that TemplateURL in S3 before the parent stack is created - the parent references it by location, it does not embed the file inline.
Cross-stack references work differently: two stacks that are not parent and child at all, connected only through an Outputs{Export} in one and Fn::ImportValue in the other.
# --- Exporting stack (vpc-stack.yaml) ---
Outputs:
VpcId:
Value: !Ref MyVpc
Export:
Name: shared-vpc-id# --- Importing stack (app-stack.yaml) ---
Resources:
AppInstance:
Type: AWS::EC2::Instance
Properties:
SubnetId: !ImportValue shared-vpc-idDeploying each stack from the SDK is unremarkable - they are just two independent CreateStack calls, in dependency order:
# --- Python (boto3) ---
import boto3
cfn = boto3.client("cloudformation", region_name="us-east-1")
with open("vpc-stack.yaml") as f:
cfn.create_stack(StackName="vpc-stack", TemplateBody=f.read())
cfn.get_waiter("stack_create_complete").wait(StackName="vpc-stack")
with open("app-stack.yaml") as f:
cfn.create_stack(StackName="app-stack", TemplateBody=f.read())
cfn.get_waiter("stack_create_complete").wait(StackName="app-stack")// --- TypeScript (AWS SDK v3) ---
import { readFileSync } from "fs";
import { CloudFormationClient, CreateStackCommand, waitUntilStackCreateComplete } from "@aws-sdk/client-cloudformation";
const cfn = new CloudFormationClient({ region: "us-east-1" });
await cfn.send(new CreateStackCommand({ StackName: "vpc-stack", TemplateBody: readFileSync("vpc-stack.yaml", "utf-8") }));
await waitUntilStackCreateComplete({ client: cfn, maxWaitTime: 600 }, { StackName: "vpc-stack" });
await cfn.send(new CreateStackCommand({ StackName: "app-stack", TemplateBody: readFileSync("app-stack.yaml", "utf-8") }));
await waitUntilStackCreateComplete({ client: cfn, maxWaitTime: 600 }, { StackName: "app-stack" });The exporting stack must exist and finish creating before the importing stack is deployed, since Fn::ImportValue resolves at deploy time and fails if the export does not exist yet.
Even though a nested stack is declared as a resource inside its parent, it is internally a real, independent stack with its own StackId, its own StackStatus, and its own entry in DescribeStacks. Drift detection, described earlier in this section, runs per-stack, so a nested stack can drift independently of its parent, and you may need to call DetectStackDrift on it directly (or use DetectStackDrift's nested-stack support, which CloudFormation extends to child stacks automatically for direct parents).
Deleting or updating the parent cascades to its nested stacks - deleting the parent deletes the children, and updating the parent's template can update, replace, or remove children in the same operation.
An export cannot be removed or changed while another stack still imports it. If you try to update or delete the exporting stack in a way that would break the export, UpdateStack or DeleteStack fails outright, listing the importing stacks as the reason.
# --- Python (boto3) ---
import boto3
cfn = boto3.client("cloudformation", region_name="us-east-1")
resp = cfn.list_imports(ExportName="shared-vpc-id")
print(resp["Imports"]) # stack names currently importing this value// --- TypeScript (AWS SDK v3) ---
import { CloudFormationClient, ListImportsCommand } from "@aws-sdk/client-cloudformation";
const cfn = new CloudFormationClient({ region: "us-east-1" });
const resp = await cfn.send(new ListImportsCommand({ ExportName: "shared-vpc-id" }));
console.log(resp.Imports); // stack names currently importing this valueListImports is the way to check this before attempting a risky change - it tells you exactly which stacks depend on an export, so you can update or migrate them off it first.
Nested stacks fit reusable sub-templates that only make sense within one larger deployment - a standard VPC layout embedded in several application stacks, for instance - where the parent owns the child's full lifecycle. Cross-stack references fit genuine boundaries between independently owned stacks, such as a platform team's networking stack exporting a VPC ID that several separate application teams' stacks import.
TemplateURL is resolved at parent creation time - upload the child template before creating the parent.DeleteStack (and any update that removes the export) fails until every importing stack stops relying on it - check with ListImports first.exportValue / automatic parameter passing) when the same composition is being authored in code rather than raw templates - the CDK generates the export/import wiring for you at synthesis time.Fn::ImportValue for sharing values across stacks that should not be hard-linked by CloudFormation's export-lock behavior.Reach for nested stacks and cross-stack exports when composition genuinely reduces duplication; a flat template is simpler and often good enough below a certain size.
A stack declared as a resource (AWS::CloudFormation::Stack) inside a parent stack's template, with its own template referenced by TemplateURL. It is internally a separate stack, but its lifecycle is tied to the parent.
Cross-stack references connect two independent stacks via Outputs{Export} and Fn::ImportValue - neither owns the other's lifecycle. Nested stacks are owned and cascaded by their parent.
Another stack is still importing that export via Fn::ImportValue. Use ListImports to find which stacks, then update them to stop importing it before deleting or changing the export.
Yes. Nested stacks are cascaded with the parent - deleting or updating the parent can delete, replace, or update its nested stacks in the same operation.
Yes, CloudFormation generally extends drift detection to direct nested stacks along with the parent, but confirm per resource type rather than assuming full recursive coverage on deeply nested trees.
When the child template is a reusable piece that only makes sense within one larger deployment and should share the parent's lifecycle - not for sharing values across independently owned stacks.
No, not simultaneously - that is a circular dependency and neither stack can deploy first. Restructure so the dependency flows one direction.
SSM Parameter Store, read at deploy time, avoids CloudFormation's export-lock behavior at the cost of losing the safety check that prevents deleting a value still in use.
Stack versions: This page was written for boto3 1.43.x (Python 3.10+) and the AWS SDK for JavaScript v3 (Node.js 18+).
Reviewed by Chris St. John·Last updated Jul 25, 2026