Add soft-deleted check and purge (#104)

Author: simonkurtz-MSFT

.github/copilot-instructions.python.md

@@ -23,6 +23,7 @@ applyTo: "**/*.py"
 - Use 4-space indentation and PEP 8 conventions.
 - Use only straight quotes (U+0027 and U+0022), not typographic quotes.
 - Use whitespace to separate logical sections and add a blank line before `return` statements.
+- Use f-strings unless there is no interpolation.
 
 ## Import Style Guidelines
 

TROUBLESHOOTING.md

@@ -223,6 +223,99 @@ In one case, `%USERPROFILE%\.azure\bin` contained a `bicep.exe` file but with a
 
 ## Resource Management Issues
 
+### Soft-Deleted Resources (APIM and Key Vault)
+
+When you delete Azure API Management services or Key Vaults, they are soft-deleted and remain recoverable for a period of time (typically 48 days for APIM, 90 days for Key Vault). These soft-deleted resources continue to reserve their names and can cause deployment conflicts.
+
+**Common Issues:**
+- Deployment fails with "Name already exists" even though resource appears deleted
+- Cannot reuse the same name for a new APIM service or Key Vault
+- Key Vault creation fails during infrastructure deployment
+- Subscription quotas are affected by soft-deleted resources
+
+**Error During Infrastructure Deployment:**
+```
+Creating Key Vault: kv-sbfc4encghfag
+❌ Failed to create Key Vault: kv-sbfc4encghfag
+   This may be caused by a soft-deleted Key Vault with the same name.
+   Check for soft-deleted resources: python shared/python/show_soft_deleted_resources.py
+```
+
+**Check for Soft-Deleted Resources:**
+```bash
+# Using Python script (recommended)
+python shared/python/show_soft_deleted_resources.py
+
+# Manual check
+az apim deletedservice list
+az keyvault list-deleted
+```
+
+**Purge Soft-Deleted Resources:**
+
+⚠️ **WARNING:** Purging is permanent and irreversible. Resources cannot be recovered after purging.
+
+```bash
+# Purge all soft-deleted resources with confirmation
+python shared/python/show_soft_deleted_resources.py --purge
+
+# Purge without confirmation (use with caution!)
+python shared/python/show_soft_deleted_resources.py --purge --yes
+
+# Manual purge
+az apim deletedservice purge --service-name <name> --location <location>
+az keyvault purge --name <name> --location <location>
+```
+
+**Best Practices:**
+1. Check for soft-deleted resources before deploying with the same name
+2. Use unique names for resources to avoid conflicts
+3. Purge soft-deleted resources if you need to reuse the name immediately
+4. Consider using timestamps or random suffixes in resource names during development
+
+#### Understanding Key Vault Purge Protection
+
+Key Vaults can have **purge protection** enabled, which prevents them from being manually purged before their scheduled purge date. This is a security feature that cannot be disabled once enabled.
+
+**Error When Purging Protected Key Vaults:**
+```
+(MethodNotAllowed) Operation 'DeletedVaultPurge' is not allowed.
+Code: MethodNotAllowed
+Message: Operation 'DeletedVaultPurge' is not allowed.
+```
+
+**Identifying Purge Protection:**
+The `show_soft_deleted_resources.py` script automatically detects and displays purge protection status:
+```bash
+python shared/python/show_soft_deleted_resources.py
+```
+
+Sample output:
+```
+1/2:
+    Vault Name       : kv-glgoiqn66pbnu
+    Location         : eastus2
+    Deletion Date    : 2025-12-13 10:30:00 UTC
+    Purge Date       : 2026-03-12 10:30:00 UTC
+    Purge Protection : 🔒 ENABLED
+    Vault ID         : /subscriptions/.../vaults/kv-glgoiqn66pbnu
+
+⚠️  1 vault(s) have PURGE PROTECTION enabled and cannot be manually purged.
+   These vaults will be automatically purged on their scheduled purge date.
+```
+
+**Handling Purge-Protected Key Vaults:**
+- ✅ **Recoverable:** You can still recover the vault before the scheduled purge date
+- ❌ **Cannot purge manually:** The vault cannot be purged until its scheduled purge date
+- 💡 **Use different names:** Deploy new Key Vaults with different names
+- 🔒 **Security feature:** This is by design to prevent accidental data loss
+
+**Recovery Option:**
+```bash
+# Recover a soft-deleted Key Vault (even with purge protection)
+az keyvault recover --name <vault-name>
+```
+
 ### Resource Group Does Not Exist
 
 **Error Message:**

shared/python/infrastructures.py

@@ -861,13 +861,20 @@ def _create_keyvault(self, key_vault_name: str) -> bool:
         if not check_kv.success:
             # Create Key Vault via Azure CLI with RBAC authorization (consistent with Bicep module)
             print(f'   Creating Key Vault: {key_vault_name}')
-            az.run(
+            create_kv = az.run(
                 f'az keyvault create --name {key_vault_name} --resource-group {self.rg_name} --location {self.rg_location} --enable-rbac-authorization true',
-                f'✅ Key Vault created: {key_vault_name}',
-                '❌ Failed to create Key Vault',
-                print_command_to_run = False
+                print_command_to_run = False,
+                print_errors = False
             )
 
+            if not create_kv.success:
+                print(f'   ❌ Failed to create Key Vault: {key_vault_name}')
+                print('      This may be caused by a soft-deleted Key Vault with the same name.')
+                print('      Check for soft-deleted resources: python shared/python/show_soft_deleted_resources.py\n')
+                return False
+
+            print(f'   ✅ Key Vault created: {key_vault_name}')
+
             #Assign Key Vault Certificates Officer role to current user for certificate creation
 
             # Key Vault Certificates Officer role
@@ -878,6 +885,7 @@ def _create_keyvault(self, key_vault_name: str) -> bool:
             )
             if not assign_kv_role.success:
                 print('   ❌ Failed to assign Key Vault Certificates Officer role to current user')
+                print('      This is an RBAC permission issue - verify your account has sufficient permissions.')
                 return False
 
             print('   ✅ Assigned Key Vault Certificates Officer role to current user')