Skip to content

Commit 4dc08b1

Browse files
committed
docs: document destroy command and add rollback guide
- Add destroy command section to docs/cli-commands.md (options, examples, TEXT/JSON output, two-phase behavior, use cases, notes) - Update command count from 8 to 9 in cli-commands.md - Add destroy to command overview table and pipeline commands list - Expand Clean Up Resources walkthrough to cover both destroy and delete - Add Rollback Workflow to Common Workflows section in cli-commands.md - Add destroy cleanup step to README.md Quick Start - Add Rollback Guide link to README.md documentation section - Add destroy cleanup step to all 6 translated READMEs (pt, fr, it, ja, zh, he) - Update examples/full-pipeline-lifecycle.sh Step 8 to use destroy - Update examples/cleanup-demo-resources.sh to use destroy with explanation - Add new docs/rollback-guide.md covering manual rollback strategies, destroy+redeploy clean slate approach, decision tree, catalog/project preservation, GitHub Actions automated rollback workflows, and bundle-based rollback setup
1 parent f222eb1 commit 4dc08b1

11 files changed

Lines changed: 703 additions & 22 deletions

File tree

README.md

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -52,6 +52,9 @@ aws-smus-cicd-cli deploy --targets test --manifest manifest.yaml
5252

5353
# Run validation tests
5454
aws-smus-cicd-cli test --manifest manifest.yaml --targets test
55+
56+
# Clean up when done
57+
aws-smus-cicd-cli destroy -manifest manifest.yaml --targets test --force
5558
```
5659

5760
**See it in action:** [Live GitHub Actions Example](https://github.com/aws/CICD-for-SageMakerUnifiedStudio/actions/runs/17631303500)
@@ -1117,6 +1120,7 @@ genai_dev_workflow:
11171120
### Guides
11181121
- **[Application Manifest](docs/manifest.md)** - Complete YAML configuration reference
11191122
- **[CLI Commands](docs/cli-commands.md)** - All available commands and options
1123+
- **[Rollback Guide](docs/rollback-guide.md)** - Recover from bad deployments and automate rollback
11201124
- **[Bootstrap Actions](docs/bootstrap-actions.md)** - Automated deployment actions and event-driven workflows
11211125
- **[Substitutions & Variables](docs/substitutions-and-variables.md)** - Dynamic configuration
11221126
- **[Connections Guide](docs/connections.md)** - Configure AWS service integrations

docs/cli-commands.md

Lines changed: 217 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22

33
[Back to Main README](../README.md)
44

5-
The SMUS CI/CD CLI provides eight main commands for managing CI/CD pipelines in SageMaker Unified Studio.
5+
The SMUS CI/CD CLI provides nine main commands for managing CI/CD pipelines in SageMaker Unified Studio.
66

77
## Global Options
88

@@ -50,6 +50,7 @@ aws-smus-cicd-cli describe --manifest manifest.yaml
5050
| `test` | Run tests for pipeline targets | `aws-smus-cicd-cli test --targets marketing-test-stage` |
5151
| `integrate` | Integrate with external tools (Q CLI) | `aws-smus-cicd-cli integrate qcli` |
5252
| `delete` | Remove target environments | `aws-smus-cicd-cli delete --stages marketing-test-stage --force` |
53+
| `destroy` | Delete all resources deployed by the manifest | `aws-smus-cicd-cli destroy --targets test --force` |
5354

5455
## Detailed Command Examples
5556

@@ -519,7 +520,43 @@ Domain: cicd-test-domain (us-east-1)
519520
**What this shows:** The test command runs Python tests from the configured test folder against your deployed bundle. Tests receive environment variables with domain ID, project ID, and other context information to validate the deployment. This ensures your pipeline is working correctly after deployment and provides automated validation of your data workflows.
520521

521522
### 8. Clean Up Resources
523+
524+
Use `delete` to remove the DataZone project only, or `destroy` to remove all deployed resources (QuickSight, S3, Airflow workflows, Glue jobs, catalog resources, and optionally the project).
525+
522526
```bash
527+
# Remove all deployed resources for a stage (recommended for full cleanup)
528+
aws-smus-cicd-cli destroy --targets test --manifest manifest.yaml --force
529+
```
530+
**Example Output:**
531+
```
532+
🔍 Validating 1 stage(s)...
533+
Validating stage 'test'...
534+
535+
📋 Destruction plan:
536+
537+
Stage: test
538+
airflow_workflow:
539+
- IntegrationTestMultiTarget_integration-test-test_test_dag
540+
s3_prefix:
541+
- src
542+
- workflows
543+
544+
Total resources to process: 3
545+
546+
⚠️ WARNING: This will permanently delete the above resources!
547+
548+
🗑️ Starting destruction...
549+
550+
Stage: test
551+
552+
📊 Destruction Summary
553+
test: deleted=3 not_found=0 skipped=0 error=0
554+
```
555+
556+
**What this shows:** The destroy command removes all resources deployed by the manifest for the targeted stage — Airflow workflows, S3 objects, QuickSight dashboards, Glue jobs, catalog resources, and optionally the DataZone project. It validates first (read-only), prints a full destruction plan, then prompts for confirmation before deleting anything. Use `--force` to skip the prompt in CI/CD pipelines.
557+
558+
```bash
559+
# Remove only the DataZone project (leaves deployed content in place)
523560
aws-smus-cicd-cli delete --stages test --manifest manifest.yaml --force
524561
```
525562
**Example Output:**
@@ -537,7 +574,7 @@ Targets to delete:
537574
✅ test: Project deleted successfully
538575
```
539576

540-
**What this shows:** The delete command removes SageMaker Unified Studio projects and their associated resources. It provides a summary of deletion operations, showing which projects were successfully removed. This is useful for cleaning up test environments and managing resource lifecycle in your CI/CD pipeline.
577+
**What this shows:** The delete command removes only the SageMaker Unified Studio project and its associated CloudFormation stacks. Use this when you want to remove the project but leave deployed content (S3 files, QuickSight dashboards, etc.) intact.
541578

542579
```bash
543580
aws-smus-cicd-cli --help
@@ -553,6 +590,7 @@ aws-smus-cicd-cli --help
553590
5. **`run`** - Run workflow commands
554591
6. **`logs`** - Fetch workflow logs from CloudWatch
555592
7. **`delete`** - Delete projects and environments
593+
8. **`destroy`** - Destroy all resources deployed by the manifest
556594

557595
## Command Details
558596

@@ -952,6 +990,160 @@ aws-smus-cicd-cli delete -t test --force -o JSON
952990
- CloudFormation stacks are deleted automatically when projects are removed
953991
- Use `--async` for faster execution when managing multiple targets
954992

993+
### 9. destroy - Destroy All Deployed Resources
994+
995+
Deletes all resources previously deployed by the manifest: QuickSight dashboards/datasets/data sources, S3 objects at declared target paths, Airflow serverless workflows, workflow-created resources (e.g. Glue jobs), DataZone catalog resources, and optionally the DataZone project. This is the inverse of `deploy`.
996+
997+
> **Note:** `destroy` is distinct from `delete`. The `delete` command only removes the DataZone project. The `destroy` command removes all deployed content resources and conditionally removes the project.
998+
999+
```bash
1000+
aws-smus-cicd-cli destroy [OPTIONS]
1001+
```
1002+
1003+
#### Options
1004+
1005+
| Option | Short | Description | Example |
1006+
|--------|-------|-------------|---------|
1007+
| `--manifest` | `-m` | Path to application manifest file (default: `manifest.yaml`) | `--manifest manifest.yaml` |
1008+
| `--targets` | `-t` | Stage name(s) — single or comma-separated (default: all stages) | `--targets test` |
1009+
| `--force` | `-f` | Skip confirmation prompt | `--force` |
1010+
| `--output` | `-o` | Output format: TEXT (default) or JSON | `--output JSON` |
1011+
| `--help` | | Show command help | |
1012+
1013+
#### Examples
1014+
1015+
```bash
1016+
# Destroy all stages with confirmation prompt
1017+
aws-smus-cicd-cli destroy --manifest manifest.yaml
1018+
1019+
# Destroy a specific stage
1020+
aws-smus-cicd-cli destroy --targets test --manifest manifest.yaml
1021+
1022+
# Destroy multiple stages
1023+
aws-smus-cicd-cli destroy --targets test,prod --manifest manifest.yaml
1024+
1025+
# Destroy without confirmation (CI/CD pipelines)
1026+
aws-smus-cicd-cli destroy --targets test --force
1027+
1028+
# Destroy with JSON output for automation
1029+
aws-smus-cicd-cli destroy --targets test --force --output JSON
1030+
```
1031+
1032+
#### Example Output (TEXT format)
1033+
1034+
```
1035+
🔍 Validating 1 stage(s)...
1036+
Validating stage 'test'...
1037+
1038+
📋 Destruction plan:
1039+
1040+
Stage: test
1041+
airflow_workflow:
1042+
- MyApp_test-project_my_dag
1043+
glue_job:
1044+
- setup-covid-db-job
1045+
- summary-glue-job
1046+
quicksight_dashboard:
1047+
- deployed-test-covid-TotalDeathByCountry
1048+
quicksight_dataset:
1049+
- deployed-test-covid-TotalDeathByCountry
1050+
quicksight_data_source:
1051+
- deployed-test-covid-TotalDeathByCountry
1052+
s3_prefix:
1053+
- dashboard-glue-quick/bundle
1054+
- repos
1055+
1056+
Total resources to process: 7
1057+
1058+
⚠️ WARNING: This will permanently delete the above resources!
1059+
Are you sure you want to proceed with destruction? [y/n]: y
1060+
1061+
🗑️ Starting destruction...
1062+
1063+
Stage: test
1064+
1065+
📊 Destruction Summary
1066+
test: deleted=7 not_found=0 skipped=0 error=0
1067+
```
1068+
1069+
#### Example Output (JSON format)
1070+
1071+
```json
1072+
{
1073+
"application_name": "MyApp",
1074+
"targets": ["test"],
1075+
"stages": {
1076+
"test": [
1077+
{
1078+
"resource_type": "airflow_workflow",
1079+
"resource_id": "MyApp_test-project_my_dag",
1080+
"status": "deleted",
1081+
"message": "Workflow deleted"
1082+
},
1083+
{
1084+
"resource_type": "glue_job",
1085+
"resource_id": "setup-covid-db-job",
1086+
"status": "deleted",
1087+
"message": "Glue job deleted"
1088+
},
1089+
{
1090+
"resource_type": "s3_prefix",
1091+
"resource_id": "dashboard-glue-quick/bundle",
1092+
"status": "deleted",
1093+
"message": "S3 objects deleted"
1094+
}
1095+
]
1096+
}
1097+
}
1098+
```
1099+
1100+
#### Behavior
1101+
1102+
The command follows a strict two-phase model:
1103+
1104+
**Phase 1 — Validation (read-only):**
1105+
- Resolves domain and project IDs via DataZone
1106+
- Resolves S3 connections to determine bucket/prefix targets
1107+
- Enumerates QuickSight resources by prefix and detects collisions
1108+
- Checks for active Airflow workflow runs
1109+
- Fetches and parses workflow YAML files from S3 to discover workflow-created resources (e.g. Glue jobs)
1110+
- Collects ALL errors across ALL stages before aborting — no early exit
1111+
1112+
**Phase 2 — Destruction (after confirmation):**
1113+
1114+
Resources are deleted in this fixed dependency order per stage:
1115+
1. Stop active Airflow workflow runs
1116+
2. Delete workflow-created resources (Glue jobs, etc.)
1117+
3. Delete Airflow workflows
1118+
4. Delete bootstrap connections (created by `datazone.create_connection` actions)
1119+
5. Delete QuickSight dashboards → datasets → data sources
1120+
6. Delete S3 objects at declared `targetDirectory` prefixes
1121+
7. Delete catalog resources (glossaries, terms, form types, asset types, assets, data products) in reverse dependency order
1122+
8. Delete DataZone project (only if `project.create: true` in manifest)
1123+
1124+
**Key behaviors:**
1125+
- **Idempotent**: Resources already absent are logged as `not_found`, not errors. Safe to run multiple times.
1126+
- **Single confirmation gate**: All confirmations happen in one prompt after the full plan is printed.
1127+
- **Active run re-check**: Live workflow run status is re-queried at destruction time to catch runs that started or completed after validation.
1128+
- **Collision detection**: If more QuickSight resources or Airflow workflows match than declared in the manifest, destroy aborts before deleting anything.
1129+
- **Built-in connections protected**: `default.*` connections are never deleted.
1130+
- **Managed catalog resources protected**: Resources with `amazon.datazone.*` namespace are never deleted.
1131+
- **Always synchronous**: No `--async` mode. Each deletion step completes before the next begins.
1132+
- **Catalog warning**: When `deployment_configuration.catalog` is present, all project-owned catalog resources are deleted (not just imported ones). Set `disable: true` under `deployment_configuration.catalog` to skip catalog deletion.
1133+
1134+
#### Use Cases
1135+
1136+
- **Clean re-deployment**: Destroy a stage and redeploy from scratch to resolve state drift
1137+
- **Environment teardown**: Remove test or staging environments after validation
1138+
- **Rollback**: Remove a failed deployment before re-deploying a previous version
1139+
- **Project cleanup**: Remove all resources before deleting the project
1140+
1141+
#### Notes
1142+
- Requires sufficient IAM permissions to list and delete all resource types declared in the manifest (QuickSight, S3, Airflow Serverless, DataZone, Glue)
1143+
- S3 bucket and prefix resolution requires a live DataZone API call — the project must be reachable at destroy time
1144+
- Use `--force` in CI/CD pipelines to skip the interactive confirmation prompt; note that `--force` with `--output JSON` is required since JSON mode cannot prompt interactively
1145+
- The `Resource_Prefix` configured in `deployment_configuration.quicksight.overrideParameters` must be unique to avoid collision errors
1146+
9551147
## Global Options
9561148

9571149
All commands support:
@@ -1000,9 +1192,31 @@ aws-smus-cicd-cli run --workflow my_dag --command "dags list" --targets test
10001192

10011193
### Cleanup Workflow
10021194
```bash
1003-
# Delete test environment
1195+
# Delete test environment (DataZone project only)
10041196
aws-smus-cicd-cli delete -t test --force
10051197

10061198
# Delete multiple environments
10071199
aws-smus-cicd-cli delete -t test,staging --force --async
1200+
1201+
# Destroy all deployed resources (QuickSight, S3, Airflow, Glue, catalog, project)
1202+
aws-smus-cicd-cli destroy --targets test --force
1203+
1204+
# Destroy specific stage for clean re-deployment
1205+
aws-smus-cicd-cli destroy --targets test --manifest manifest.yaml
1206+
```
1207+
1208+
### Rollback Workflow
1209+
```bash
1210+
# Option 1: Redeploy previous bundle (no destroy needed if no resource conflicts)
1211+
# Download the versioned bundle, then deploy
1212+
aws s3 cp s3://bucket/bundles/MyApp-v1.2.0.zip ./artifacts/MyApp.zip
1213+
aws-smus-cicd-cli deploy --stages prod --manifest manifest.yaml
1214+
1215+
# Option 2: Destroy bad deployment then redeploy previous version (clean slate)
1216+
aws-smus-cicd-cli destroy --targets prod --force
1217+
aws s3 cp s3://bucket/bundles/MyApp-v1.2.0.zip ./artifacts/MyApp.zip
1218+
aws-smus-cicd-cli deploy --stages prod --manifest manifest.yaml
1219+
aws-smus-cicd-cli test --stages prod
10081220
```
1221+
1222+
**See more:** [Rollback Guide](rollback-guide.md)

docs/langs/fr/README.md

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -71,6 +71,9 @@ aws-smus-cicd-cli deploy --targets test --manifest manifest.yaml
7171

7272
# Exécuter les tests de validation
7373
aws-smus-cicd-cli test --manifest manifest.yaml --targets test
74+
75+
# Nettoyer quand c'est terminé
76+
aws-smus-cicd-cli destroy --targets test --force
7477
```
7578

7679
**Voir en action :** [Live GitHub Actions Example](https://github.com/aws/CICD-for-SageMakerUnifiedStudio/actions/runs/17631303500)

docs/langs/he/README.md

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -88,6 +88,9 @@ aws-smus-cicd-cli deploy --targets test --manifest manifest.yaml
8888

8989
# Run validation tests
9090
aws-smus-cicd-cli test --manifest manifest.yaml --targets test
91+
92+
# Clean up when done
93+
aws-smus-cicd-cli destroy --targets test --force
9194
```
9295

9396
</div>

docs/langs/it/README.md

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -65,6 +65,9 @@ aws-smus-cicd-cli deploy --targets test --manifest manifest.yaml
6565

6666
# Run validation tests
6767
aws-smus-cicd-cli test --manifest manifest.yaml --targets test
68+
69+
# Clean up when done
70+
aws-smus-cicd-cli destroy --targets test --force
6871
```
6972

7073
**Guarda in azione:** [Live GitHub Actions Example](https://github.com/aws/CICD-for-SageMakerUnifiedStudio/actions/runs/17631303500)

docs/langs/ja/README.md

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -71,6 +71,9 @@ aws-smus-cicd-cli deploy --targets test --manifest manifest.yaml
7171

7272
# Run validation tests
7373
aws-smus-cicd-cli test --manifest manifest.yaml --targets test
74+
75+
# Clean up when done
76+
aws-smus-cicd-cli destroy --targets test --force
7477
```
7578

7679
**動作確認:** [Live GitHub Actions Example](https://github.com/aws/CICD-for-SageMakerUnifiedStudio/actions/runs/17631303500)

docs/langs/pt/README.md

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -68,6 +68,9 @@ aws-smus-cicd-cli deploy --targets test --manifest manifest.yaml
6868

6969
# Run validation tests
7070
aws-smus-cicd-cli test --manifest manifest.yaml --targets test
71+
72+
# Clean up when done
73+
aws-smus-cicd-cli destroy --targets test --force
7174
```
7275

7376
**Veja em ação:** [Live GitHub Actions Example](https://github.com/aws/CICD-for-SageMakerUnifiedStudio/actions/runs/17631303500)

docs/langs/zh/README.md

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -71,6 +71,9 @@ aws-smus-cicd-cli deploy --targets test --manifest manifest.yaml
7171

7272
# Run validation tests
7373
aws-smus-cicd-cli test --manifest manifest.yaml --targets test
74+
75+
# Clean up when done
76+
aws-smus-cicd-cli destroy --targets test --force
7477
```
7578

7679
**查看实际运行效果:** [Live GitHub Actions Example](https://github.com/aws/CICD-for-SageMakerUnifiedStudio/actions/runs/17631303500)

0 commit comments

Comments
 (0)