# Ipa Destroy

> Destroy composed infrastructure patterns by executing teardown targets in generated Makefiles. Use when the user says 'destroy', 'tear down', 'delete stacks', 'remove infrastructure', 'clean up stacks', or invokes /ipa-destroy.

- Skill: `aws-samples/ipa-destroy` (Agent Skill)
- Install (CLI): `npx skillmds@latest add aws-samples/ipa-destroy`
- Raw SKILL.md: https://api.skillmd.com/api/skills/aws-samples/ipa-destroy/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: aws-samples (https://skillmd.com/u/aws-samples)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/aws-samples/ipa-destroy

---


# /ipa-destroy — Destroy Infrastructure Pattern

This skill tears down a composed infrastructure pattern by executing the teardown targets in generated Makefiles. It validates prerequisites, checks which stacks exist, displays a teardown plan with data loss warnings, requires double confirmation, executes the teardown, verifies deletion, and reports results.

**Lifecycle**: `/ipa-init` → `/ipa-compose` → `/ipa-prepare` → `/ipa-deploy` → **`/ipa-destroy`**

> **AWS credential resolution**: All `aws` CLI commands must be prefixed with `source .env 2>/dev/null;` to load credentials into the environment. Do NOT pass `--profile` or `--region` flags explicitly.

---

## What This Skill Does

1. Validates prerequisites (.env, Makefiles, AWS credentials, required tools)
2. Checks which pattern stacks currently exist (pre-teardown status)
3. Displays a teardown plan with data loss warnings
4. Requires double confirmation (including typing the namespace)
5. Runs `make -f scripts/deploy.mk teardown` (deletes stacks in reverse dependency order)
6. Verifies all stacks are deleted
7. Reports results

## What This Skill Does NOT Do

- Does not deploy anything — that's `/ipa-deploy`'s job
- Does not ask "deploy or teardown?" — it proceeds directly to teardown
- Does not generate Makefiles — that's `/ipa-compose`'s job
- Does not create or modify IAM roles — that's `/ipa-security`'s job
- Does not read stack SKILL.md files — Makefiles are the only deployment contract
- Does not call AWS APIs directly — delegates to `make` which calls `aws cloudformation delete-stack`
- Does not delete the security stack — security infrastructure is managed by `/ipa-security`
- Does not delete prepare stacks (ECR, etc.) — prepare infrastructure is managed separately. To tear down prepare stacks manually: `make -f scripts/prepare.mk teardown-prepare`
- Does not support per-stack targeting — always tears down the full pattern via the aggregate target
- Does not modify `.env` — it is a read-only consumer of configuration

## Information Sources

| Source | What Destroy Reads | When |
|--------|-------------------|------|
| `.env` | `APP_NAMESPACE`, `APP_ENV`, `AWS_REGION`, `AWS_PROFILE`, `AWS_ACCOUNT_ID`, `APP_BUILDER_ROLE_ARN` | Pre-flight validation |
| `scripts/deploy.mk` | Teardown target names, stack names, reverse dependency order | Pre-teardown status check + execution |
| `make -n` | Dry-run output showing teardown commands that would execute | Teardown plan display |
| `aws cloudformation describe-stacks --query 'Stacks[0].StackStatus' --output text` | Stack status | Pre-teardown status check + post-teardown verification |
| `aws cloudformation describe-stack-events` | Stack events | Failure diagnosis |
| `aws cloudformation list-stacks` | All managed stacks | Optional status overview |

---

## Step 1: Pre-Flight Validation

Run **all** checks below and collect results. Report **all** failures at once with per-item remediation — do not stop at the first failure.

### 1.1 Verify .env Exists

Check that `.env` exists at the project root and is non-empty.

**If missing**: "`.env` not found. Run `/ipa-init` to initialize project configuration."

### 1.2 Verify Required .env Variables

Read `.env` and verify these variables exist and are non-empty:

| Variable | Written By | Error If Missing |
|----------|------------|-----------------|
| `APP_NAMESPACE` | `/ipa-init` | "Missing `APP_NAMESPACE`. Run `/ipa-init`." |
| `APP_ENV` | `/ipa-init` | "Missing `APP_ENV`. Run `/ipa-init`." |
| `AWS_REGION` | `/ipa-init` | "Missing `AWS_REGION`. Run `/ipa-init`." |
| `AWS_PROFILE` | `/ipa-init` | "Missing `AWS_PROFILE`. Run `/ipa-init`." |
| `AWS_ACCOUNT_ID` | `/ipa-init` | "Missing `AWS_ACCOUNT_ID`. Run `/ipa-init`." |
| `APP_BUILDER_ROLE_ARN` | `/ipa-security` | "Missing `APP_BUILDER_ROLE_ARN`. Run `/ipa-security`." |

Store all variable values for use in subsequent steps.

### 1.3 Verify Deployment Scripts Exist

Check that `scripts/deploy.mk` exists and contains a `teardown` target.

**If missing**: "`scripts/deploy.mk` not found. Run `/ipa-compose` to generate deployment artifacts."

**If no teardown target**: "`scripts/deploy.mk` has no `teardown` target. Run `/ipa-compose` to regenerate deployment artifacts."

### 1.4 Verify Security Stack Is Deployed

Run:

```bash
source .env 2>/dev/null; aws cloudformation describe-stacks --stack-name {APP_NAMESPACE}-{APP_ENV}-security --query 'Stacks[0].StackStatus' --output text
```

Expected: `CREATE_COMPLETE` or `UPDATE_COMPLETE`.

**If not deployed**: "Security stack `{APP_NAMESPACE}-{APP_ENV}-security` is not deployed. Run `/ipa-security` first."

### 1.5 Verify AWS Credentials

Run:

```bash
source .env 2>/dev/null; aws sts get-caller-identity
```

**If fails**: "AWS credentials are invalid or expired for profile `{AWS_PROFILE}`. Refresh your credentials and try again."

### 1.6 Verify Make Is Installed

Run `which make`.

**If missing**: "GNU Make is not installed. On macOS it is pre-installed. On Linux: `sudo apt install make`."

### Validation Summary

If **any** checks fail, display all failures in a single summary table and **STOP**:

```
Pre-flight validation failed:

  ✗ .env variable APP_BUILDER_ROLE_ARN missing — Run /ipa-security
  ✗ AWS credentials expired — Refresh credentials for profile {AWS_PROFILE}

Fix the above issues and re-run /ipa-destroy.
```

If **all** checks pass: "Pre-flight validation passed. All prerequisites verified."

---

## Step 2: Pre-Teardown Status Check

Before displaying the teardown plan, check which stacks currently exist. This provides a status-aware plan that shows "will delete" vs "already gone."

### 2.1 Extract Stack Names from deploy.mk

Run `make -n -f scripts/deploy.mk teardown` and extract the `--stack-name` values from the output. These are the stacks that the teardown would target.

### 2.2 Check Each Stack's Current Status

For each stack name extracted above, run:

```bash
source .env 2>/dev/null; aws cloudformation describe-stacks --stack-name {stack-name} --query 'Stacks[0].StackStatus' --output text
```

Categorize each stack:

| Status | Category | Action |
|--------|----------|--------|
| `CREATE_COMPLETE`, `UPDATE_COMPLETE` | Exists | Will be deleted |
| `DOES_NOT_EXIST` (or command returns "stack not found") | Gone | Skip (already deleted) |
| `*_IN_PROGRESS` | Transitioning | Warn builder — stack is mid-operation |
| `ROLLBACK_COMPLETE`, `DELETE_FAILED`, `*_FAILED` | Failed state | Will attempt deletion |

### 2.3 Nothing to Destroy

If **ALL** stacks are in the "Gone" category:

"No pattern stacks to destroy. All stacks have already been deleted."

**STOP** — there is nothing to tear down.

---

## Step 3: Display Teardown Plan + Warnings

### 3.1 Show Status-Aware Plan

Display the teardown plan with each stack's current status and the action that will be taken:

```
⚠️  TEARDOWN PLAN: {APP_NAMESPACE}-{APP_ENV}

  Stack                              Current Status      Action
  ─────────────────────────────────  ──────────────────  ──────
  {APP_NAMESPACE}-{APP_ENV}-lambda   CREATE_COMPLETE     DELETE
  {APP_NAMESPACE}-{APP_ENV}-cognito  CREATE_COMPLETE     DELETE
  {APP_NAMESPACE}-{APP_ENV}-ecr      DOES_NOT_EXIST      skip (already deleted)

WARNING: This will permanently delete all stacks listed above.
Stateful resources (ECR repositories with images, DynamoDB tables with data,
S3 buckets with objects) will be destroyed. This action cannot be undone.
```

### 3.2 Show Dry-Run Commands

Run Make dry-run and display the commands:

```bash
make -n -f scripts/deploy.mk teardown
```

Show the output so the builder can see exactly what commands will execute.

---

## Step 4: Double Confirmation

Teardown is a destructive operation. Require two separate confirmations before proceeding.

### 4.1 First Confirmation

"Are you sure you want to destroy all infrastructure? (yes/no):"

If the builder does not confirm: "Destroy cancelled. No stacks were deleted." **STOP**.

### 4.2 Second Confirmation

"Type the namespace `{APP_NAMESPACE}` to confirm:"

Verify the typed value matches `APP_NAMESPACE` exactly (case-sensitive).

If the value does not match: "Destroy cancelled. Namespace did not match. No stacks were deleted." **STOP**.

---

## Step 5: Execute Teardown

Run:

```bash
make -f scripts/deploy.mk teardown
```

Display Make output as it runs. Each target prints its AWS CLI command, providing natural progress indication.

**If teardown succeeds** (exit code = 0): proceed to Step 6.

**If teardown partially fails**: Report which stacks were deleted and which remain:

```
Teardown partially completed:

  ✓ {APP_NAMESPACE}-{APP_ENV}-lambda   — deleted
  ✗ {APP_NAMESPACE}-{APP_ENV}-cognito  — DELETE_FAILED
  · {APP_NAMESPACE}-{APP_ENV}-ecr      — not attempted

Check the failed stack and see the Failure Handling section below.
After fixing the issue, re-run /ipa-destroy — already-deleted stacks will be skipped.
```

**Idempotency**: Re-running `/ipa-destroy` after a partial failure is always safe. The execution layer handles all state transitions:
- Non-existent stack → succeeds silently (already deleted)
- `DELETE_FAILED` → retries deletion
- `*_COMPLETE` → proceeds with deletion

---

## Step 6: Post-Teardown Verification

For each stack in the teardown plan, run:

```bash
source .env 2>/dev/null; aws cloudformation describe-stacks --stack-name {stack-name} --query 'Stacks[0].StackStatus' --output text
```

Confirm all return `DOES_NOT_EXIST` (i.e., the command returns an error indicating the stack does not exist) or `DELETE_COMPLETE`.

If any stack still exists with a non-deleted status, report it as part of the completion report.

---

## Step 7: Completion Report

Display a structured report:

```
Destroy Complete: {APP_NAMESPACE}-{APP_ENV}

  All pattern stacks have been deleted:

  ✓ {APP_NAMESPACE}-{APP_ENV}-lambda   — deleted
  ✓ {APP_NAMESPACE}-{APP_ENV}-cognito  — deleted
  · {APP_NAMESPACE}-{APP_ENV}-ecr      — already deleted (skipped)

Note: Security stack {APP_NAMESPACE}-{APP_ENV}-security is preserved.
To remove security infrastructure, use /ipa-security.

Note: Prepare stacks (scripts/prepare.mk) are preserved.
To remove prepare infrastructure: make -f scripts/prepare.mk teardown-prepare

Re-run /ipa-destroy at any time — it is safe to re-run (idempotent).
```

---

## Failure Handling

### Teardown-Specific Errors

| Error | Cause | Fix |
|-------|-------|-----|
| `Cannot delete export {name}` | Another stack imports an output from this stack (cross-stack reference) | Delete the dependent stack first. Teardown targets in `deploy.mk` are ordered to prevent this — check for manually-created stacks outside IPA that may reference this stack's exports |
| `The bucket you tried to delete is not empty` | S3 bucket contains uploaded frontend files from post-deploy | Empty the bucket first: `source .env 2>/dev/null; aws s3 rm s3://{bucket-name} --recursive`, then re-run `/ipa-destroy` |
| `RepositoryNotEmptyException` or `Repository not empty` | ECR repository contains images | Delete all images first: `source .env 2>/dev/null; aws ecr batch-delete-image --repository-name {repo} --image-ids "$(aws ecr list-images --repository-name {repo} --query 'imageIds[*]' --output json)"`, then re-run `/ipa-destroy` |
| Partial teardown (some stacks deleted, others remain) | A stack in the middle of the reverse-order sequence failed to delete | Fix the failing stack (see specific errors above), then re-run `/ipa-destroy`. Already-deleted stacks will be skipped (they no longer exist) |
| `Stack [{stack}] does not exist` during teardown | Stack was already deleted (manually or in a previous attempt) | This is safe to ignore. The teardown will continue with remaining stacks |
| `DELETE_FAILED` | A resource within the stack cannot be deleted | Run `source .env 2>/dev/null; aws cloudformation describe-stack-events --stack-name {stack-name}` to identify the blocking resource. Fix the issue manually (empty the resource, remove dependencies), then re-run `/ipa-destroy` |

### Credential Errors

| Error | Cause | Fix |
|-------|-------|-----|
| `ExpiredTokenException` or `ExpiredToken` | AWS session token has expired | Refresh credentials: re-authenticate with your AWS profile, then re-run `/ipa-destroy` |
| `Access Denied` | Insufficient permissions to delete stacks | Run `/ipa-security` to update the builder role's IAM permissions, then re-run `/ipa-destroy` |

### Tool Errors

| Error | Cause | Fix |
|-------|-------|-----|
| `make: command not found` | GNU Make is not installed | macOS: pre-installed. Linux: `sudo apt install make` |
| `make: *** No rule to make target 'teardown'` | `scripts/deploy.mk` is missing or malformed | Run `/ipa-compose` to regenerate deployment artifacts |