/aws-cloudformation

Template Safety Guidance

• Cross-Stack Reference Safety
• Conditional Resource Coupling
• Security Group Blast Radius
• DeletionPolicy Preservation for Stateful Resources
• Parameter Propagation for New Resources
• Template Size Limits

Cross-Stack Reference Safety

Never rename or remove an exported Output without checking for Fn::ImportValue consumers.

When a template has Outputs with Export.Name, other stacks may depend on that export via Fn::ImportValue. Renaming or removing the export will cause immediate deployment failures in all consuming stacks.

Before modifying any exported output:

1. Check Metadata."com.aws.cloudformation.Context" for documented consumers
2. If no context exists, warn the user that downstream stacks may break
3. If proceeding with a rename, update the com.aws.cloudformation.Context context to reflect the new export name
4. Recommend coordinating the rename with all importing stacks (deploy consumers first with the new name, then rename the export)

Key principle: Exported outputs are a public API contract. Treat renames as breaking changes.

Conditional Resource Coupling

Resources sharing a Condition form an atomic feature toggle group.

When multiple resources use the same Condition, they are intentionally coupled — they must all be created or none created. Removing the Condition from one resource in the group breaks the atomicity.

Before modifying or removing a Condition from a resource:

1. Check Metadata."com.aws.cloudformation.Context" for feature toggle group documentation
2. Identify all other resources that share the same Condition
3. Warn the user that breaking the coupling may cause deployment failures (e.g., a resource created without its required subnet group or security group)
4. If the user intends to break the coupling, recommend removing the Condition from ALL resources in the group, or explain why selective removal is safe

Security Group Blast Radius

Assess the blast radius before modifying shared security groups.

A single security group may be referenced by EC2 instances, RDS databases, Lambda VPC configs, and other resources. Adding an ingress rule affects ALL resources using that group.

Before modifying a security group:

1. Check Metadata."com.aws.cloudformation.Context" for documented references and blast radius
2. Enumerate which resources use the security group
3. Warn the user about the full impact (e.g., "opening port 443 from 0.0.0.0/0 will also expose the RDS instance, not just the web server")
4. Recommend creating a separate, scoped security group if the ingress rule should only apply to a subset of resources

Key principle: Public ingress (0.0.0.0/0) on a shared security group is almost always wrong — it exposes databases and internal services, not just the intended target.

DeletionPolicy Preservation for Stateful Resources

Never remove or downgrade a DeletionPolicy on stateful resources without explicit user confirmation.

Resources with DeletionPolicy: Retain (DynamoDB tables, RDS instances, S3 buckets) contain data that cannot be recreated. When asked to remove such a resource:

1. Check Metadata."com.aws.cloudformation.Context" for data criticality documentation
2. Warn about data loss risk — even with Retain, removing from the template orphans the resource from CloudFormation management
3. Confirm the user understands: the physical resource survives (Retain), but it is no longer managed by the stack
4. If removing, update the template Description and remaining resources' com.aws.cloudformation.Context context to document the orphaned resource
5. Never change DeletionPolicy from Retain to Delete without explicit user confirmation and documented backup verification

Key principle: DeletionPolicy: Retain exists for a reason. Respect it, document it, and warn loudly before any operation that could result in data loss.

Parameter Propagation for New Resources

When adding resources to a template with naming conventions, propagate existing parameters.

Many templates use Parameters (e.g., Environment, Project, Team) to drive resource naming for multi-environment deployment. New resources must follow the same convention.

When adding a resource to a template with parameterized names:

1. Check Metadata."com.aws.cloudformation.Context" for naming convention documentation
2. Examine existing resources for naming patterns (e.g., !Sub "${Environment}-...")
3. Apply the same pattern to the new resource's name
4. Add Metadata."com.aws.cloudformation.Context" to the new resource, documenting its purpose and constraints
5. If the template has a documented convention (e.g., "all resources must use Environment prefix"), follow it even if not explicitly requested

Key principle: Consistency in naming enables multi-environment deployment. A resource that breaks the naming convention becomes an obstacle to promotion across environments.

Template Size Limits

Check the template body size before adding resources to an already-large template. CloudFormation enforces hard limits: a template body passed inline (TemplateBody) is capped at 51,200 bytes, a template uploaded via S3 (TemplateURL) at 1,048,576 bytes (1 MB), and any single template at 500 resources. A template that already carries many resources or rich Metadata."com.aws.cloudformation.Context" may be close to these limits, so the addition you are about to make may not fit.

Service Quotas reports the current values for two of these — Template Size (1 MB) and Template Resources (500), both non-adjustable — and also Template Description Length (1,024 bytes), which the persist procedure relies on. The 51,200-byte inline TemplateBody cap is not published as a service quota; take it from the CloudFormation quotas documentation. When the margin matters, confirm with:

aws service-quotas list-service-quotas --service-code cloudformation \
  --query "Quotas[?starts_with(QuotaName, 'Template')].[QuotaName,Value,Unit]"

When adding or modifying resources — especially in a large template:

1. Measure the current template body size in bytes (e.g., wc -c <template> on Unix/macOS or Git Bash, or (Get-Item <template>).Length in PowerShell) and compare it against the 1,048,576-byte limit; note the remaining headroom and the resource count against the 500 cap.
2. Estimate the size of what you are about to add, INCLUDING the Metadata."com.aws.cloudformation.Context" you are required to attach. If the addition would push the template over the limit, do NOT blindly append.
3. When headroom is tight, intelligently adjust context to fit rather than dropping it:
   • Condense and consolidate verbose existing Metadata."com.aws.cloudformation.Context" (collapse long why/rationale prose into terse caveman shorthand; keep must constraints intact).
   • Prioritize the highest-value context and write concise context for the new resources.
4. If condensing is not enough, split the stack: move a cohesive group of resources into a nested stack (AWS::CloudFormation::Stack) or a CloudFormation module, or relocate bulky static content (e.g., large inline code) to S3. Preserve Metadata."com.aws.cloudformation.Context" on the extracted resources.
5. Never silently drop required context or exceed the limit — a template over the limit fails at CreateStack/UpdateStack (e.g., "Template body is too long" / "Template format error: number of resources exceeds maximum").

Key principle: Context is mandatory, but so is staying under the size limit. When both cannot fit, intelligently adjust existing and new context (condense, prioritize, or relocate) — never choose between blindly adding and dropping context.