Mastering the Command 'pulumi destroy' (with examples)

The pulumi destroy command is a powerful tool in the Pulumi CLI toolkit, designed to remove infrastructure resources created by Pulumi that are no longer needed. It intelligently tears down all existing resources in a given stack and can be configured with various options to handle specific situations, such as targeting specific stacks, automatically approving actions, excluding certain resources, or continuing operations despite encountering errors. This command is pivotal for maintaining cloud resource hygiene and efficiently managing infrastructure life cycles.

Use case 1: Destroy all resources in the current stack

Code:

pulumi destroy

Motivation:

This command is useful when you want to clean up all resources in the current stack without consideration for switching or specifying another stack. It allows you to effectively roll back the infrastructure to a pristine state, freeing up resources and avoiding unnecessary costs.

Explanation:

• pulumi destroy: Initiates the process of destroying all resources aligned with the current active stack settings. No additional options are needed, making it a straightforward command when you’re confident that you want everything in the current stack removed.

Example output:

Previewing destroy (dev):

Resources:
    deletion complete
Resource changes:
    - 5 to delete

Do you want to perform this destroy? yes
Destroying (dev):

Resources:
    - 5 to delete
    - aws:ec2/instance:Instance: my-instance
    - aws:s3/bucket:Bucket: my-bucket
    - ...

info: 5 changes performed:
    + 0 resources created
    - 5 resources deleted
    ~ 0 resources replaced

Use case 2: Destroy all resources in a specific stack

Code:

pulumi destroy --stack stack

Motivation:

When managing multiple stacks, it’s often necessary to work on or clean up a specific stack without affecting others. This command aids in making controlled and precise alterations or removals to an individual stack, ensuring that only the targeted resources are affected.

Explanation:

• pulumi destroy: This part of the command tells the CLI to destroy resources.
• --stack stack: This argument specifies the stack’s name that you wish to target for destruction. It ensures that only the resources associated with the named stack are impacted, leaving other stacks untouched.

Example output:

Previewing destroy (production):

Resources:
    deletion complete
Resource changes:
    - 8 to delete

Do you want to perform this destroy? yes
Destroying (production):

Resources:
    - 8 to delete
    - aws:ec2/instance:Instance: production-instance
    - aws:s3/bucket:Bucket: production-bucket
    - ...

info: 8 changes performed:
    + 0 resources created
    - 8 resources deleted
    ~ 0 resources replaced

Use case 3: Automatically approve and destroy resources after previewing

Code:

pulumi destroy --yes

Motivation:

Automating approvals is crucial in non-interactive or scripting environments where human intervention is impractical. By using this command, you can expedite processes by omitting the need for manual confirmation, which is particularly handy in deployment pipelines or automated testing scenarios.

Explanation:

• pulumi destroy: Initiates resource destruction in the current stack.
• --yes: Automatically confirms the operation, bypassing the manual approval step after the preview. This is particularly useful when the command is executed in an automated environment or when human oversight isn’t readily available.

Example output:

Previewing destroy (dev):

Resources:
    deletion complete
Resource changes:
    - 3 to delete

Destroying (dev) automatically:

Resources:
    - 3 to delete
    - aws:ec2/instance:Instance: dev-instance
    - aws:s3/bucket:Bucket: dev-bucket
    - ...

info: 3 changes performed:
    + 0 resources created
    - 3 resources deleted
    ~ 0 resources replaced

Use case 4: Exclude protected resources from being destroyed

Code:

pulumi destroy --exclude-protected

Motivation:

Sometimes, certain resources are designated as ‘protected,’ and they should not be deleted regardless of other operations targeting their stack. This command is ideal for preserving critical infrastructure components while still allowing for clean-up processes involving other resources in the stack.

Explanation:

• pulumi destroy: Command to start destroying resources.
• --exclude-protected: This option ensures that resources marked as protected are not destroyed. Protected resources typically include vital elements that need to persist regardless of other changes to the infrastructure.

Example output:

Previewing destroy (test):

Excluding 2 protected resources from destruction.

Resource changes:
    - 4 to delete

Do you want to perform this destroy? yes
Destroying (test):

Resources:
    - 4 to delete
    - aws:ec2/instance:Instance: unused-instance
    - aws:s3/bucket:Bucket: old-bucket
    - ...

info: 4 changes performed:
    + 0 resources created
    - 4 resources deleted
    - 2 resources protected

Use case 5: Remove the stack and its configuration file after all resources in the stack are deleted

Code:

pulumi destroy --remove

Motivation:

Following resource destruction, there may be instances where both the stack and its associated configuration data are no longer required. This command simplifies such scenarios by ensuring both resources and stack information are erased, reducing clutter and streamlining project management.

Explanation:

• pulumi destroy: Begins the process of removing all resources in the stack.
• --remove: Instructs Pulumi to also delete the stack metadata, including its configuration file, after all resources are wiped out, thus cleaning up additional data associated with the stack.

Example output:

Previewing destroy (cleanup):

Resources:
    deletion complete
Resource changes:
    - 7 to delete

Do you want to remove the stack after destroy? yes
Destroying (cleanup) and removing stack:

Resources:
    - 7 to delete
    - azure:storage/account:Account: old-archive
    - gcp:compute/network:Network: old-network
    - ...

info: 7 changes performed:
    + 0 resources created
    - 7 resources deleted
    - stack 'clean-up' removed

Use case 6: Continue destroying the resources, even if an error is encountered

Code:

pulumi destroy --continue-on-error

Motivation:

In a situation where it’s critical to ensure that as many resources as possible are deleted, even in the face of errors, this command comes into play. It’s especially useful if certain resources have circular dependencies or intermittent issues that might abort a typical destruction process.

Explanation:

• pulumi destroy: Starts the destruction operation for the chosen stack.
• --continue-on-error: Instructs the command to proceed with deleting all possible resources even if there are failures, ensuring maximum resource cleanup despite partial errors.

Example output:

Previewing destroy (stubborn-stack):

Resource changes:
    - 9 to delete

Do you want to perform this destroy and continue on error? yes
Destroying (stubborn-stack), continuing on error:

Resources:
    - 9 to delete
    - aws:ec2/instance:Instance: unreliable-instance
    Error deleting aws:ec2/instance:Instance unrealiable-instance: dependency failure
    - aws:s3/bucket:Bucket: persist-bucket

info: 7 changes performed, 2 errors encountered
    + 0 resources created
    - 7 resources deleted
    ~ 2 resources failed

Conclusion

The pulumi destroy command is an essential part of infrastructure management using Pulumi, offering flexibility and control over resource destruction. From cleaning up an entire stack to maintaining specific resource protections, it supports a wide range of scenarios through its rich set of options. By understanding and applying these use cases, developers and IT professionals can efficiently manage infrastructure configurations and ensure optimal resource utilization across environments.