Enhance Azure Backup documentation and scripts with improved parameter descriptions and logic for HANA DB recovery tasks

Author: devanshjainms

docs/AZURE_BACKUP.md

@@ -60,7 +60,7 @@ SAP_FUNCTIONAL_TEST_TYPE:   AzureBackupDatabase
 Add the following variables to your system's `sap-parameters.yaml` file (under `WORKSPACES/SYSTEM/<SYSTEM_CONFIG_NAME>/`):
 
 ```yaml
-# Recovery Services vault ARM resource ID
+# Recovery Services vault ARM resource ID (required)
 backup_vault_resource_id:         "/subscriptions/xxxx/resourceGroups/my-rg/providers/Microsoft.RecoveryServices/vaults/my-vault"
 
 # Whether to restore SYSTEMDB (set false to skip)
@@ -84,6 +84,19 @@ backup_restore_point_time:        ""
 hana_userstore_key:               "SYSTEM"
 ```
 
+#### Parameter Reference
+
+| Parameter | Default | Description |
+|-----------|---------|-------------|
+| `backup_vault_resource_id` | `""` | Full ARM resource ID of the Recovery Services vault (required) |
+| `backup_restore_systemdb` | `true` | Whether to include SYSTEMDB in restore operations |
+| `backup_restore_tenants` | `[]` | List of tenant DB names to restore; empty means all tenants |
+| `backup_target_filesystem_path` | `"/sapinstall/hana_backup/"` | Filesystem path for restore-as-files (test case 3) |
+| `backup_target_vm_name` | `""` | Target VM hostname for cross-VM restore (test case 5) |
+| `backup_target_vm_rg` | `""` | Target VM resource group; defaults to source VM's RG if empty |
+| `backup_restore_point_time` | `""` | Point-in-time for restore in ISO 8601 UTC; empty uses latest recovery point |
+| `hana_userstore_key` | `"SYSTEM"` | HANA hdbuserstore key for database connectivity |
+
 ### 3. User-Assigned Managed Identity (Optional)
 
 If your management server uses a user-assigned managed identity, set the client ID in `vars.yaml`:

src/module_utils/backup_discovery.py

@@ -85,7 +85,9 @@ def _matches_source_vm(
             if not lower_server:
                 return False
 
-            if self._source_vm in lower_server or lower_server in self._source_vm:
+            if min(len(self._source_vm), len(lower_server)) >= 5 and (
+                self._source_vm in lower_server or lower_server in self._source_vm
+            ):
                 return True
 
             parts = re.split(r"[-_]", self._source_vm)

src/roles/backup_db_hana/tasks/recover-db-commands.yml

@@ -290,7 +290,7 @@
                                         set -o pipefail
                                         source /usr/sap/{{ db_sid | upper }}/home/.sapenv.sh && \
                                         hdbnsutil -sr_register --online \
-                                          --name={{ backup_secondary_site_name | default(cluster_status_pre.secondary_site_name | default(backup_hsr_secondary_site | default('site2')), true) }} \
+                                          --name={{ backup_secondary_site_name | default(cluster_status_pre.secondary_site_name | default(backup_hsr_secondary_site | default('site2'), true), true) }} \
                                           --remoteHost={{ backup_primary_node }} \
                                           --remoteInstance={{ db_instance_number }} \
                                           --replicationMode={{ cluster_status_pre.replication_mode

src/roles/backup_db_hana/tasks/rescue-backup.yml

@@ -90,7 +90,7 @@
                                         set -o pipefail
                                         source /usr/sap/{{ db_sid | upper }}/home/.sapenv.sh && \
                                         hdbnsutil -sr_register \
-                                          --name={{ backup_secondary_site_name | default(cluster_status_pre.secondary_site_name | default(backup_hsr_secondary_site | default('site2')), true) }} \
+                                          --name={{ backup_secondary_site_name | default(cluster_status_pre.secondary_site_name | default(backup_hsr_secondary_site | default('site2'), true), true) }} \
                                           --remoteHost={{ backup_primary_node | default(ansible_hostname) }} \
                                           --remoteInstance={{ db_instance_number }} \
                                           --replicationMode={{ cluster_status_pre.replication_mode | default(backup_hsr_replication_mode | default('syncmem')) }} \

src/roles/backup_db_hana/tasks/restore-to-db.yml

@@ -214,7 +214,11 @@
       changed_when:                 hsr_disable_result.rc == 0
       when:                         database_high_availability | default(false) | bool
 
-    - name:                         "Test Execution: Stop HANA DB before restore"
+    # NOTE: The stop→start cycle is intentional, not redundant.
+    # After HSR unregister + sr_disable above, HANA still runs with stale HSR
+    # metadata in memory. HDB stop clears that state; HDB start brings HANA
+    # back in clean standalone mode.
+    - name:                         "Test Execution: Stop HANA DB to clear HSR state"
       become:                       true
       become_user:                  "{{ db_sid | lower }}adm"
       ansible.builtin.shell: |
@@ -425,7 +429,7 @@
                                     set -o pipefail
                                     source /usr/sap/{{ db_sid | upper }}/home/.sapenv.sh && \
                                     hdbnsutil -sr_register \
-                                      --name={{ backup_secondary_site_name | default(cluster_status_pre.secondary_site_name | default(backup_hsr_secondary_site | default('site2')), true) }} \
+                                      --name={{ backup_secondary_site_name | default(cluster_status_pre.secondary_site_name | default(backup_hsr_secondary_site | default('site2'), true), true) }} \
                                       --remoteHost={{ backup_primary_node }} \
                                       --remoteInstance={{ db_instance_number }} \
                                       --replicationMode={{ cluster_status_pre.replication_mode | default(backup_hsr_replication_mode | default('syncmem')) }} \

src/roles/backup_db_hana/tasks/restore-to-filesystem.yml

@@ -533,7 +533,7 @@
                                     set -o pipefail
                                     source /usr/sap/{{ db_sid | upper }}/home/.sapenv.sh && \
                                     hdbnsutil -sr_register --online \
-                                      --name={{ backup_secondary_site_name | default(cluster_status_pre.secondary_site_name | default(backup_hsr_secondary_site | default('site2')), true) }} \
+                                      --name={{ backup_secondary_site_name | default(cluster_status_pre.secondary_site_name | default(backup_hsr_secondary_site | default('site2'), true), true) }} \
                                       --remoteHost={{ backup_primary_node }} \
                                       --remoteInstance={{ db_instance_number }} \
                                       --replicationMode={{ cluster_status_pre.replication_mode | default(backup_hsr_replication_mode | default('syncmem')) }} \