Change Sets

/**
 * Creates a list of changes that will be applied to a stack for review
 * Change set can be created for updating existing stack or creating new stack
 */
class CreateChangeSetCommand {
  constructor(input: CreateChangeSetCommandInput);
}

interface CreateChangeSetCommandInput {
  /** Name or ARN of the stack for the change set */
  StackName: string;
  
  /** Name of the change set (unique within stack) */
  ChangeSetName: string;
  
  /** CloudFormation template for changes */
  TemplateBody?: string;
  
  /** S3 URL containing the template */
  TemplateURL?: string;
  
  /** Use previous template for parameter-only changes */
  UsePreviousTemplate?: boolean;
  
  /** Parameter values for the change set */
  Parameters?: Parameter[];
  
  /** IAM capabilities required by changes */
  Capabilities?: Capability[];
  
  /** Resource types that can be modified */
  ResourceTypes?: string[];
  
  /** IAM service role for change set operations */
  RoleARN?: string;
  
  /** Rollback configuration */
  RollbackConfiguration?: RollbackConfiguration;
  
  /** SNS topic ARNs for notifications */
  NotificationARNs?: string[];
  
  /** Resource tags */
  Tags?: Tag[];
  
  /** Change set type: UPDATE (default) or CREATE */
  ChangeSetType?: ChangeSetType;
  
  /** Resources to import (for import change sets) */
  ResourcesToImport?: ResourceToImport[];
  
  /** Unique identifier for idempotency */
  ClientRequestToken?: string;
  
  /** Description of the change set */
  Description?: string;
  
  /** Include nested stacks in change set */
  IncludeNestedStacks?: boolean;
  
  /** Callback URL for change set creation progress */
  OnStackFailure?: OnStackFailure;
}

interface CreateChangeSetCommandOutput {
  /** Unique change set identifier */
  Id?: string;
  
  /** Unique stack identifier */
  StackId?: string;
}

import { 
  CloudFormationClient, 
  CreateChangeSetCommand,
  DescribeChangeSetCommand,
  ExecuteChangeSetCommand 
} from "@aws-sdk/client-cloudformation";

const client = new CloudFormationClient({ region: "us-east-1" });

// Create change set for stack update
const createCommand = new CreateChangeSetCommand({
  StackName: "my-stack",
  ChangeSetName: "update-instance-type",
  TemplateBody: JSON.stringify({
    AWSTemplateFormatVersion: "2010-09-09",
    Parameters: {
      InstanceType: {
        Type: "String",
        Default: "t3.medium"
      }
    },
    Resources: {
      MyInstance: {
        Type: "AWS::EC2::Instance",
        Properties: {
          InstanceType: { Ref: "InstanceType" },
          ImageId: "ami-0abcdef1234567890"
        }
      }
    }
  }),
  Parameters: [
    { ParameterKey: "InstanceType", ParameterValue: "t3.large" }
  ],
  Description: "Update instance type from t3.medium to t3.large"
});

const result = await client.send(createCommand);
console.log("Change set created:", result.Id);

/**
 * Returns the inputs for the change set and list of changes
 * Shows detailed information about what will be modified
 */
class DescribeChangeSetCommand {
  constructor(input: DescribeChangeSetCommandInput);
}

interface DescribeChangeSetCommandInput {
  /** Name or ARN of the change set */
  ChangeSetName: string;
  
  /** Name or ARN of the stack (required if change set name not ARN) */
  StackName?: string;
  
  /** Token for pagination */
  NextToken?: string;
  
  /** Include property differences in the response */
  IncludePropertyValues?: boolean;
}

interface DescribeChangeSetCommandOutput {
  /** Change set name */
  ChangeSetName?: string;
  
  /** Change set unique identifier */
  ChangeSetId?: string;
  
  /** Stack name */
  StackName?: string;
  
  /** Stack unique identifier */
  StackId?: string;
  
  /** Change set description */
  Description?: string;
  
  /** List of changes in the change set */
  Changes?: Change[];
  
  /** Token for next page of results */
  NextToken?: string;
  
  /** Parameters used in the change set */
  Parameters?: Parameter[];
  
  /** Change set creation time */
  CreationTime?: Date;
  
  /** Execution status of the change set */
  ExecutionStatus?: ExecutionStatus;
  
  /** Current status of the change set */
  Status?: ChangeSetStatus;
  
  /** Reason for current status */
  StatusReason?: string;
  
  /** SNS notification ARNs */
  NotificationARNs?: string[];
  
  /** Rollback configuration */
  RollbackConfiguration?: RollbackConfiguration;
  
  /** IAM capabilities */
  Capabilities?: Capability[];
  
  /** Tags applied to the stack */
  Tags?: Tag[];
  
  /** Include nested stacks */
  IncludeNestedStacks?: boolean;
  
  /** Parent change set ID */
  ParentChangeSetId?: string;
  
  /** Root change set ID */
  RootChangeSetId?: string;
  
  /** Callback URL */
  OnStackFailure?: OnStackFailure;
}

interface Change {
  /** Type of change */
  Type?: ChangeType;
  
  /** Hook invocation point */
  HookInvocationCount?: number;
  
  /** Resource change details */
  ResourceChange?: ResourceChange;
}

interface ResourceChange {
  /** Type of resource change action */
  Action?: ChangeAction;
  
  /** Logical resource identifier */
  LogicalResourceId?: string;
  
  /** Physical resource identifier */
  PhysicalResourceId?: string;
  
  /** AWS resource type */
  ResourceType?: string;
  
  /** Replacement requirement */
  Replacement?: Replacement;
  
  /** Resource attributes that are triggering change */
  Scope?: ResourceAttribute[];
  
  /** Property differences */
  Details?: ResourceChangeDetail[];
  
  /** Change set ID if nested stack */
  ChangeSetId?: string;
  
  /** Module information */
  ModuleInfo?: ModuleInfo;
}

/**
 * Updates a stack using values in a change set
 * After execution, the change set is deleted and cannot be used again
 */
class ExecuteChangeSetCommand {
  constructor(input: ExecuteChangeSetCommandInput);
}

interface ExecuteChangeSetCommandInput {
  /** Name or ARN of the change set */
  ChangeSetName: string;
  
  /** Name or ARN of the stack (required if change set name not ARN) */
  StackName?: string;  
  
  /** Unique identifier for idempotency */
  ClientRequestToken?: string;
  
  /** Disable rollback during execution */
  DisableRollback?: boolean;
  
  /** Retain resources even if execution fails */
  RetainExceptOnCreate?: boolean;
}

interface ExecuteChangeSetCommandOutput {
  /** Stack identifier */
  StackId?: string;
}

/**
 * Returns summary information about change sets for a stack
 * Includes nested stack change sets up to specified depth
 */
class ListChangeSetsCommand {
  constructor(input: ListChangeSetsCommandInput);
}

interface ListChangeSetsCommandInput {
  /** Name or ARN of the stack */
  StackName: string;
  
  /** Token for pagination */
  NextToken?: string;
}

interface ListChangeSetsCommandOutput {
  /** List of change set summaries */
  Summaries?: ChangeSetSummary[];
  
  /** Token for next page of results */
  NextToken?: string;
}

interface ChangeSetSummary {
  /** Unique change set identifier */
  ChangeSetId?: string;
  
  /** Change set name */
  ChangeSetName?: string;
  
  /** Stack identifier */
  StackId?: string;
  
  /** Stack name */
  StackName?: string;
  
  /** Execution status */
  ExecutionStatus?: ExecutionStatus;
  
  /** Change set status */
  Status?: ChangeSetStatus;
  
  /** Reason for current status */
  StatusReason?: string;
  
  /** Creation time */
  CreationTime?: Date;
  
  /** Description */
  Description?: string;
  
  /** Include nested stacks */
  IncludeNestedStacks?: boolean;
  
  /** Parent change set ID */
  ParentChangeSetId?: string;
  
  /** Root change set ID */
  RootChangeSetId?: string;
}

/**
 * Deletes the specified change set
 * Cannot delete change sets that are currently being executed
 */
class DeleteChangeSetCommand {
  constructor(input: DeleteChangeSetCommandInput);
}

interface DeleteChangeSetCommandInput {
  /** Name or ARN of the change set to delete */
  ChangeSetName: string;
  
  /** Name or ARN of the stack (required if change set name not ARN) */
  StackName?: string;
}

// Review change set before execution
const describeCommand = new DescribeChangeSetCommand({
  ChangeSetName: "update-instance-type",
  StackName: "my-stack",
  IncludePropertyValues: true
});

const changeSet = await client.send(describeCommand);

console.log("Change set status:", changeSet.Status);
console.log("Changes:");
changeSet.Changes?.forEach(change => {
  const resource = change.ResourceChange;
  console.log(`${resource?.Action}: ${resource?.LogicalResourceId} (${resource?.ResourceType})`);
  if (resource?.Replacement) {
    console.log(`  Replacement: ${resource.Replacement}`);
  }
});

// Execute the change set if ready
if (changeSet.Status === "CREATE_COMPLETE") {
  const executeCommand = new ExecuteChangeSetCommand({
    ChangeSetName: "update-instance-type",
    StackName: "my-stack"
  });
  
  await client.send(executeCommand);
  console.log("Change set execution started");
}

// List all change sets for a stack
const listCommand = new ListChangeSetsCommand({
  StackName: "my-stack"
});

const changeSets = await client.send(listCommand);
changeSets.Summaries?.forEach(summary => {
  console.log(`${summary.ChangeSetName}: ${summary.Status} (${summary.ExecutionStatus})`);
});

type ChangeSetType = "CREATE" | "UPDATE" | "IMPORT";

type ChangeSetStatus = 
  | "CREATE_PENDING" 
  | "CREATE_IN_PROGRESS" 
  | "CREATE_COMPLETE" 
  | "DELETE_PENDING" 
  | "DELETE_IN_PROGRESS" 
  | "DELETE_COMPLETE" 
  | "DELETE_FAILED" 
  | "FAILED";

type ExecutionStatus = "UNAVAILABLE" | "AVAILABLE" | "EXECUTE_IN_PROGRESS" | "EXECUTE_COMPLETE" | "EXECUTE_FAILED" | "OBSOLETE";

type ChangeAction = "Add" | "Modify" | "Remove" | "Import" | "Dynamic";

type Replacement = "True" | "False" | "Conditional";

type ResourceAttribute = 
  | "Properties" 
  | "Metadata" 
  | "CreationPolicy" 
  | "UpdatePolicy" 
  | "DeletionPolicy" 
  | "Tags" 
  | "UpdateReplacePolicy";