IaC via SDK Best Practices

Q: What is the single most important habit in this list?

Never apply changes with a bare UpdateStack. Route every update through a change set so replacements are visible before ExecuteChangeSet runs.

Q: How do I stop a stack from being deleted by accident?

Set EnableTerminationProtection: true on the stack, and set DeletionPolicy: Retain or Snapshot on individual stateful resources so they survive even if the stack itself is deleted.

Q: Why does my CreateStack sometimes seem to create two stacks?

A retry after a timeout, without a ClientRequestToken, can be treated as a new request. Pass a stable token so retries of the same logical call are idempotent.

Q: Is it safe to delete a stack that exports a value?

Only if nothing imports it. Call ListImports first; CloudFormation blocks the deletion anyway if an import still exists, but checking first avoids a failed deploy step.

Every operation in this section - creating a stack, updating it, checking on it, deploying a CDK app - has a safe way to do it and a shortcut that works until the day it does not.

This page collects the habits worth having before you ship code that deploys or manages infrastructure through the CloudFormation SDK.

How to Use This List

Each item is a rule stated positively, with a one-line rationale.
Groups run roughly in order of impact: review discipline first, then safety nets, then operational hygiene.
Check the boxes against your own deploy code as a quick audit.
Revisit whenever a new stack, a new pipeline, or a new team starts deploying through this codebase.

A - Change-Set Discipline

Never call UpdateStack directly for anything beyond a disposable stack. It applies immediately with no preview; use CreateChangeSet + DescribeChangeSet + ExecuteChangeSet instead.
Always check the Replacement field, not just Action. An entry can say Modify and still replace the underlying resource - Replacement is the field that actually tells you.
Gate execution on an explicit review step. A human approval or an automated policy check on the change-set diff catches dangerous replacements before ExecuteChangeSet runs.
Delete unwanted change sets. DeleteChangeSet after a rejected review keeps stacks free of stale, confusing artifacts.

Review the diff before anything is applied.

# --- Python (boto3) ---
import boto3
 
cfn = boto3.client("cloudformation", region_name="us-east-1")
resp = cfn.describe_change_set(StackName="my-stack", ChangeSetName="release-142")
for change in resp["Changes"]:
    detail = change["ResourceChange"]
    if detail.get("Replacement") == "True":
        print("WARNING: replacement", detail["LogicalResourceId"])

// --- TypeScript (AWS SDK v3) ---
import { CloudFormationClient, DescribeChangeSetCommand } from "@aws-sdk/client-cloudformation";
 
const cfn = new CloudFormationClient({ region: "us-east-1" });
const resp = await cfn.send(new DescribeChangeSetCommand({ StackName: "my-stack", ChangeSetName: "release-142" }));
for (const change of resp.Changes ?? []) {
  const detail = change.ResourceChange;
  if (detail?.Replacement === "True") {
    console.log("WARNING: replacement", detail.LogicalResourceId);
  }
}

B - Protecting Stateful Resources

Enable termination protection on important stacks. EnableTerminationProtection: true on CreateStack (or UpdateTerminationProtection after the fact) blocks accidental DeleteStack calls.
Set DeletionPolicy: Retain or Snapshot on stateful resources. Databases, and anything else you cannot regenerate, should survive a stack deletion even when the rest of the stack is torn down.
Empty S3 buckets before relying on stack deletion. A non-empty bucket without a custom deletion policy fails DeleteStack - handle emptying explicitly rather than discovering this mid-teardown.
Treat Replacement: "True" on a stateful resource as a stop-the-line signal. Confirm it is intended before executing the change set.

# --- Python (boto3) ---
import boto3
 
cfn = boto3.client("cloudformation", region_name="us-east-1")
cfn.create_stack(
    StackName="my-stack",
    TemplateBody=template,
    EnableTerminationProtection=True,
)

// --- TypeScript (AWS SDK v3) ---
import { CloudFormationClient, CreateStackCommand } from "@aws-sdk/client-cloudformation";
 
const cfn = new CloudFormationClient({ region: "us-east-1" });
await cfn.send(new CreateStackCommand({
  StackName: "my-stack",
  TemplateBody: template,
  EnableTerminationProtection: true,
}));

C - Waiting and Idempotency

Wait on every asynchronous operation with a waiter. CreateStack, UpdateStack, DeleteStack, and change-set creation all return before the work finishes - poll with the matching waiter, not a fixed sleep.
Pass ClientRequestToken on CreateStack. It makes retries of the same logical request idempotent, so a network retry after a timeout does not attempt to create the stack twice.
Handle "No updates are to be performed" as a no-op, not an error. Both SDKs raise this when a template or change set has nothing new to apply.
Check StackStatus after a waiter succeeds, not just that it returned. A rollback state can still leave the stack in a status you need to react to.

D - Drift and Ongoing Hygiene

Scan for drift on a schedule, not only reactively. DetectStackDrift is a point-in-time check - without a recurring job, drift can go unnoticed for weeks.
Pair drift detection with a reconciliation process. Detection only reports differences; decide in advance whether manual changes get reverted (re-apply the template) or adopted (update the template).
Use ListImports before touching an exporting stack. Confirm nothing still depends on an export before attempting to remove or change it.
Keep nested-stack templates versioned in the same place as the parent. A parent stack referencing a TemplateURL that changed independently is a common source of confusing, hard-to-reproduce updates.

E - Scope and Permissions

Request the narrowest Capabilities the template actually needs. Prefer CAPABILITY_IAM over CAPABILITY_NAMED_IAM unless the template genuinely assigns explicit IAM resource names.
Scope the IAM role deploying stacks, not just the resources inside them. A deploy role with cloudformation:* and broad downstream service permissions can create anything its templates ask for - review both layers.
Prefer the synthesized-template SDK path over shelling out to cdk deploy only when your pipeline needs it. For most teams cdk deploy remains simpler and better supported.
Log ResponseMetadata.RequestId (boto3) or $metadata.requestId (SDK v3) on failure. It is what AWS support needs to look into a failed stack operation.

FAQs

What is the single most important habit in this list?

Never apply changes with a bare UpdateStack. Route every update through a change set so replacements are visible before ExecuteChangeSet runs.

How do I stop a stack from being deleted by accident?

Set EnableTerminationProtection: true on the stack, and set DeletionPolicy: Retain or Snapshot on individual stateful resources so they survive even if the stack itself is deleted.

Why does my CreateStack sometimes seem to create two stacks?

A retry after a timeout, without a ClientRequestToken, can be treated as a new request. Pass a stable token so retries of the same logical call are idempotent.

What should I do when I see "No updates are to be performed"?

Treat it as a no-op. Both SDKs raise this when the template or change set introduces no actual differences from the current stack state.

How often should drift detection run?

On a recurring schedule - nightly is common - rather than only when you suspect a problem, since it is a point-in-time scan and drift accumulates silently between runs.

Is it safe to delete a stack that exports a value?

Only if nothing imports it. Call ListImports first; CloudFormation blocks the deletion anyway if an import still exists, but checking first avoids a failed deploy step.

Should I always bypass cdk deploy for CI?

No. Bypass it only when your pipeline has its own change-set review or rollback conventions that don't compose with the CDK CLI. Otherwise cdk deploy is simpler and better supported.

What's the risk of requesting CAPABILITY_NAMED_IAM when CAPABILITY_IAM would do?

It is a broader acknowledgment than the template needs. Request the narrowest capability the template actually requires so a deploy role's scope stays easy to reason about.

Stack Creation, Updates & Change Sets - the change-set workflow group A formalizes.
Drift Detection via SDK - the scanning and reconciliation habits in group D.
Nested Stacks & Cross-Stack References - the export-safety check in group D.
CDK App Synthesis & Programmatic Deploy - when the bypass-cdk-deploy guidance in group E applies.

Stack versions: This page was written for boto3 1.43.x (Python 3.10+) and the AWS SDK for JavaScript v3 (Node.js 18+).

IaC via SDK Best Practices

Every operation in this section - creating a stack, updating it, checking on it, deploying a CDK app - has a safe way to do it and a shortcut that works until the day it does not.

This page collects the habits worth having before you ship code that deploys or manages infrastructure through the CloudFormation SDK.

How to Use This List

Each item is a rule stated positively, with a one-line rationale.
Groups run roughly in order of impact: review discipline first, then safety nets, then operational hygiene.
Check the boxes against your own deploy code as a quick audit.
Revisit whenever a new stack, a new pipeline, or a new team starts deploying through this codebase.

A - Change-Set Discipline

Never call UpdateStack directly for anything beyond a disposable stack. It applies immediately with no preview; use CreateChangeSet + DescribeChangeSet + ExecuteChangeSet instead.
Always check the Replacement field, not just Action. An entry can say Modify and still replace the underlying resource - Replacement is the field that actually tells you.
Gate execution on an explicit review step. A human approval or an automated policy check on the change-set diff catches dangerous replacements before ExecuteChangeSet runs.
Delete unwanted change sets. DeleteChangeSet after a rejected review keeps stacks free of stale, confusing artifacts.

Review the diff before anything is applied.

# --- Python (boto3) ---
import boto3
 
cfn = boto3.client("cloudformation", region_name="us-east-1")
resp = cfn.describe_change_set(StackName="my-stack", ChangeSetName="release-142")
for change in resp["Changes"]:
    detail = change["ResourceChange"]
    if detail.get("Replacement") == "True":
        print("WARNING: replacement", detail["LogicalResourceId"])

// --- TypeScript (AWS SDK v3) ---
import { CloudFormationClient, DescribeChangeSetCommand } from "@aws-sdk/client-cloudformation";
 
const cfn = new CloudFormationClient({ region: "us-east-1" });
const resp = await cfn.send(new DescribeChangeSetCommand({ StackName: "my-stack", ChangeSetName: "release-142" }));
for (const change of resp.Changes ?? []) {
  const detail = change.ResourceChange;
  if (detail?.Replacement === "True") {
    console.log("WARNING: replacement", detail.LogicalResourceId);
  }
}

B - Protecting Stateful Resources

Enable termination protection on important stacks. EnableTerminationProtection: true on CreateStack (or UpdateTerminationProtection after the fact) blocks accidental DeleteStack calls.
Set DeletionPolicy: Retain or Snapshot on stateful resources. Databases, and anything else you cannot regenerate, should survive a stack deletion even when the rest of the stack is torn down.
Empty S3 buckets before relying on stack deletion. A non-empty bucket without a custom deletion policy fails DeleteStack - handle emptying explicitly rather than discovering this mid-teardown.
Treat Replacement: "True" on a stateful resource as a stop-the-line signal. Confirm it is intended before executing the change set.

# --- Python (boto3) ---
import boto3
 
cfn = boto3.client("cloudformation", region_name="us-east-1")
cfn.create_stack(
    StackName="my-stack",
    TemplateBody=template,
    EnableTerminationProtection=True,
)

// --- TypeScript (AWS SDK v3) ---
import { CloudFormationClient, CreateStackCommand } from "@aws-sdk/client-cloudformation";
 
const cfn = new CloudFormationClient({ region: "us-east-1" });
await cfn.send(new CreateStackCommand({
  StackName: "my-stack",
  TemplateBody: template,
  EnableTerminationProtection: true,
}));

C - Waiting and Idempotency

Wait on every asynchronous operation with a waiter. CreateStack, UpdateStack, DeleteStack, and change-set creation all return before the work finishes - poll with the matching waiter, not a fixed sleep.
Pass ClientRequestToken on CreateStack. It makes retries of the same logical request idempotent, so a network retry after a timeout does not attempt to create the stack twice.
Handle "No updates are to be performed" as a no-op, not an error. Both SDKs raise this when a template or change set has nothing new to apply.
Check StackStatus after a waiter succeeds, not just that it returned. A rollback state can still leave the stack in a status you need to react to.

D - Drift and Ongoing Hygiene

Scan for drift on a schedule, not only reactively. DetectStackDrift is a point-in-time check - without a recurring job, drift can go unnoticed for weeks.
Pair drift detection with a reconciliation process. Detection only reports differences; decide in advance whether manual changes get reverted (re-apply the template) or adopted (update the template).
Use ListImports before touching an exporting stack. Confirm nothing still depends on an export before attempting to remove or change it.
Keep nested-stack templates versioned in the same place as the parent. A parent stack referencing a TemplateURL that changed independently is a common source of confusing, hard-to-reproduce updates.

E - Scope and Permissions

Request the narrowest Capabilities the template actually needs. Prefer CAPABILITY_IAM over CAPABILITY_NAMED_IAM unless the template genuinely assigns explicit IAM resource names.
Scope the IAM role deploying stacks, not just the resources inside them. A deploy role with cloudformation:* and broad downstream service permissions can create anything its templates ask for - review both layers.
Prefer the synthesized-template SDK path over shelling out to cdk deploy only when your pipeline needs it. For most teams cdk deploy remains simpler and better supported.
Log ResponseMetadata.RequestId (boto3) or $metadata.requestId (SDK v3) on failure. It is what AWS support needs to look into a failed stack operation.

FAQs

What is the single most important habit in this list?

Never apply changes with a bare UpdateStack. Route every update through a change set so replacements are visible before ExecuteChangeSet runs.

How do I stop a stack from being deleted by accident?

Set EnableTerminationProtection: true on the stack, and set DeletionPolicy: Retain or Snapshot on individual stateful resources so they survive even if the stack itself is deleted.

Why does my CreateStack sometimes seem to create two stacks?

A retry after a timeout, without a ClientRequestToken, can be treated as a new request. Pass a stable token so retries of the same logical call are idempotent.

What should I do when I see "No updates are to be performed"?

Treat it as a no-op. Both SDKs raise this when the template or change set introduces no actual differences from the current stack state.

How often should drift detection run?

On a recurring schedule - nightly is common - rather than only when you suspect a problem, since it is a point-in-time scan and drift accumulates silently between runs.

Is it safe to delete a stack that exports a value?

Only if nothing imports it. Call ListImports first; CloudFormation blocks the deletion anyway if an import still exists, but checking first avoids a failed deploy step.

Should I always bypass cdk deploy for CI?

No. Bypass it only when your pipeline has its own change-set review or rollback conventions that don't compose with the CDK CLI. Otherwise cdk deploy is simpler and better supported.

What's the risk of requesting CAPABILITY_NAMED_IAM when CAPABILITY_IAM would do?

It is a broader acknowledgment than the template needs. Request the narrowest capability the template actually requires so a deploy role's scope stays easy to reason about.

Stack Creation, Updates & Change Sets - the change-set workflow group A formalizes.
Drift Detection via SDK - the scanning and reconciliation habits in group D.
Nested Stacks & Cross-Stack References - the export-safety check in group D.
CDK App Synthesis & Programmatic Deploy - when the bypass-cdk-deploy guidance in group E applies.

Stack versions: This page was written for boto3 1.43.x (Python 3.10+) and the AWS SDK for JavaScript v3 (Node.js 18+).

IaC via SDK Best Practices

Buscar en la documentación

IaC via SDK Best Practices