Add SAP System-level Function Support with Asynchronous Status Tracking (#1)

* Adding support for system wide functions
* Nested Jinja makes the use of dynamic variables inside sapcontrol functions complicated. Falling back to declarative commands.
* Adding steps to make sure that the system is started before attempting RKS
* Enhance debug output for SAP Control parameters
---------

Signed-off-by: Nicolas Bettembourg <[email protected]>
Co-authored-by: Rainer Leber <[email protected]>

Author: nbttmbrg

roles/sap_control/README.md

@@ -7,6 +7,7 @@ This Ansible Role executes basic SAP administration tasks on Linux operating sys
 This Ansible Role executes basic SAP administration tasks on Linux operating systems, including:
 - Start/Stop/Restart of SAP HANA Database Server
 - Start/Stop/Restart of SAP NetWeaver Application Server
+- Start/Stop/Restart/Update of SAP Netweaver System
 - Multiple Automatic discovery and Start/Stop/Restart of SAP HANA Database Server or SAP NetWeaver Application Server
 
 ## Example execution
@@ -62,7 +63,7 @@ Assumptions for executing this role include:
 | :--- |:--- | :--- |
 | `SID` | SAP system SID | no, only if you are targetting a single SAP system|
 | `nowait` | Default: `false` | no, use only when absolutely sure! This will bypass all waiting and ignore all necessary steps for a graceful stop / start|
-| `sap_control_function` | Function to execute:<br/><ul><li>`restart_all_sap`</li><li>`restart_all_nw`</li><li>`restart_all_hana`</li><li>`restart_sap_nw`</li><li>`restart_sap_hana`</li><li>`stop_all_sap`</li><li>`start_all_sap`</li><li>`stop_all_nw`</li><li>`start_all_nw`</li><li>`stop_all_hana`</li><li>`start_all_hana`</li><li>`stop_sap_nw`</li><li>`start_sap_nw`</li><li>`stop_sap_hana`</li><li>`start_sap_hana`</li></ul> | yes, only this is required to detect the Instance Number which is used with SAP Host Agent `sapcontrol` CLI<br/><br/><br/>_Note: Executions using `all` will automatically detect any System IDs and corresponding Instance Numbers_ |
+| `sap_control_function` | Function to execute:<br/><ul><li>`restart_all_sap`</li><li>`restart_all_nw`</li><li>`restart_all_hana`</li><li>`restart_sap_nw`</li><li>`restart_sap_hana`</li><li>`stop_all_sap`</li><li>`start_all_sap`</li><li>`stop_all_nw`</li><li>`start_all_nw`</li><li>`stop_all_hana`</li><li>`start_all_hana`</li><li>`stop_sap_nw`</li><li>`start_sap_nw`</li><li>`stop_sap_hana`</li><li>`start_sap_hana`</li><li>`restartsystem_all_nw`</li><li>`updatesystem_all_nw`</li><li>`startsystem_all_nw`</li><li>`stopsystem_all_nw`</li></ul> | yes, only this is required to detect the Instance Number which is used with SAP Host Agent `sapcontrol` CLI<br/><br/><br/>_Note: Executions using `all` will automatically detect any System IDs and corresponding Instance Numbers_ |
 
 ## Ansible Role workflow and structure
 

roles/sap_control/defaults/main.yml

@@ -6,6 +6,41 @@ sap_control_name_header: "initial"
 nowait: false
 sap_control_start: "StartWait 180 2"
 sap_control_stop: "StopWait 180 2"
+sap_control_startsystem: "StartSystem ALL 180"  # function StartSystem waittimeout
+sap_control_stopsystem: "StopSystem ALL 180 480"  # function StopSystem waittimeout softtimeout
+sap_control_restartsystem: "RestartSystem ALL 180 480"  # function RestartSystem waittimeout softtimeout
+sap_control_updatesystem: "UpdateSystem 180 480 0"  # function UpdateSystem waittimeout softtimeout force
+sap_control_waitforstopped: "WaitforStopped 180 2"  # function WaitforStopped waittimeout delay
+sap_control_waitforstarted: "WaitforStarted 180 2"  # function WaitforStarted waittimeout delay
+
+# Parameters to handle async functions in sapcontrol_async.yml
+
+sap_control_startsystem_waitforasync:
+  test_function: "GetSystemInstanceList"
+  retries: 60
+  delay: 10
+  until_false: 'GRAY\s*$|RED\s*$|YELLOW\s*$'
+  until_true: 'GREEN\s*$'
+
+sap_control_restartsystem_waitforasync:
+  test_function: "GetSystemInstanceList"
+  retries: 60
+  delay: 10
+  until_false: 'GRAY\s*$|RED\s*$|YELLOW\s*$'
+  until_true: 'GREEN\s*$'
+
+sap_control_stopsystem_waitforasync:
+  test_function: "GetSystemInstanceList"
+  retries: 60
+  delay: 10
+  until_false: 'GREEN\s*$|RED\s*$|YELLOW\s*$'
+  until_true: 'GRAY\s*$'
+
+sap_control_updatesystem_waitforasync:
+  test_function: "GetSystemUpdateList"
+  retries: 60
+  delay: 10
+  until_false: 'GRAY\s*$|RED\s*$|YELLOW\s*$|GREEN\s*$'
 
 # get_all_sap_sid_dir_nw: "/sapmnt"
 # get_all_sap_sid_dir_hana: "/hana/shared"
@@ -22,6 +57,10 @@ sap_control_instance_type_sortorder:
 
 # Functions
 sap_control_functions_list:
+  - restartsystem_all_nw
+  - updatesystem_all_nw
+  - startsystem_all_nw
+  - stopsystem_all_nw
   - restart_all_sap
   - stop_all_sap
   - start_all_sap
@@ -38,7 +77,21 @@ sap_control_functions_list:
   - stop_sap_hana
   - start_sap_hana
 
+
 # Functions flow
+restartsystem_all_nw_list:
+  - sap_control_function_current: "nw_restartsystem"
+
+startsystem_all_nw_list:
+  - sap_control_function_current: "nw_startsystem"
+
+stopsystem_all_nw_list:
+  - sap_control_function_current: "nw_stopsystem"
+
+updatesystem_all_nw_list:
+  - sap_control_function_current: "nw_startsystem"
+  - sap_control_function_current: "nw_updatesystem"
+
 restart_all_sap_list:
   - sap_control_function_current: "nw_stop"
   - sap_control_function_current: "hana_stop"

roles/sap_control/tasks/main.yml

@@ -104,10 +104,18 @@
   ansible.builtin.debug:
     msg:
       - "Starting sap_control with the following parameters: "
-      - "{{ sap_control_function }}"
-      - "{{ sap_control_start }}"
-      - "{{ sap_control_stop }}"
-      - "{{ nowait }}"
+      - "Function: {{ sap_control_function }}"
+      - "Standard commands:"
+      - "  Start: {{ sap_control_start }}"
+      - "  Stop: {{ sap_control_stop }}"
+      - "System commands (if applicable):"
+      - "  StartSystem: {{ sap_control_startsystem }}"
+      - "  StopSystem: {{ sap_control_stopsystem }}"
+      - "  RestartSystem: {{ sap_control_restartsystem }}"
+      - "  UpdateSystem: {{ sap_control_updatesystem }}"
+      - "  WaitforStopped: {{ sap_control_waitforstopped }}"
+      - "  WaitforStarted: {{ sap_control_waitforstarted }}"
+      - "NoWait: {{ nowait }}"
 
 # Start SAP Control
 - name: SAP Control

roles/sap_control/tasks/prepare.yml

@@ -11,13 +11,13 @@
 
 - name: Prepare - Sort sap_facts_register by sap_control_instance_type_sortorder
   ansible.builtin.set_fact:
-    sorted_sap_facts: "{{ (sorted_sap_facts | default([]) | unique) + ( __type_list | difference(sorted_sap_facts | default([]))) }}"
+    sorted_sap_facts: "{{ (sorted_sap_facts | default([]) | unique) + (__type_list | difference(sorted_sap_facts | default([]))) }}"
   loop: "{{ sap_control_instance_type_sortorder | reverse if funct_type == 'stop' else sap_control_instance_type_sortorder }}"
   vars:
     __type_list: "{{ sap_facts_register.ansible_facts.sap | selectattr('TYPE', 'equalto', item) | list }}"
-  when: 
+  when:
     - __type_list | length > 0
-  
+
 - name: Prepare - SAP Control
   vars:
     sap_control_execute_sid: "{{ item.SID }}"
@@ -28,4 +28,18 @@
   loop: "{{ sorted_sap_facts }}"
   when:
     - item.InstanceType | lower == sap_type | lower
-...
+    - not funct_type is match('.*system')
+
+- name: Prepare - SAP Control (System wide functions)
+  vars:
+    sap_control_execute_sid: "{{ item.SID }}"
+    sap_control_execute_type: "{{ item.Type }}"
+    sap_control_execute_instance_nr: "{{ item.NR }}"
+    sap_control_execute_instance_type: "{{ item.InstanceType }}"
+  ansible.builtin.include_tasks: "sapcontrol.yml"
+  loop: "{{ sorted_sap_facts }}"
+  when:
+    - item.InstanceType | lower == sap_type | lower
+    - funct_type is match('.*system')
+    - item.TYPE | lower == 'ascs'
+      or item.TYPE | lower == 'scs'

roles/sap_control/tasks/sapcontrol.yml

@@ -22,6 +22,14 @@
   register: sapcontrol_status
   failed_when: "'FAIL' in sapcontrol_status.stdout"
 
+# Include sapcontrol async tasks
+- name: SAP {{ sap_control_name_header }} - Include async tasks
+  vars:
+    async_function_dict: "{{ vars['sap_control_' + funct_type + '_waitforasync'] }}"
+  ansible.builtin.include_tasks: sapcontrol_async.yml
+  when:
+    - funct_type is match('.*system')
+
 # Cleanipc
 - name: SAP {{ sap_control_name_header }} - Cleanipc
   ansible.builtin.include_tasks: functions/cleanipc.yml

roles/sap_control/tasks/sapcontrol_async.yml

@@ -0,0 +1,29 @@
+---
+- name: Pause for 5 Seconds
+  ansible.builtin.wait_for:
+    timeout: 5
+
+- name: SAP {{ sap_control_name_header }} - Checking if Async action is over by executing sapcontrol -nr {{ passed_sap_nr }} -function {{ async_function_dict.test_function }}
+  ansible.builtin.shell: |
+    source ~/.profile && sapcontrol -nr {{ passed_sap_nr }} -function {{ async_function_dict.test_function }}
+  args:
+    executable: /bin/bash
+  become: true
+  become_user: "{{ passed_sap_sid | lower }}adm"
+  register: test_function_result
+#  failed_when: "'FAIL' in test_function_result.stdout"
+  retries: "{{ async_function_dict.retries | default(0) | int }}"
+  delay: "{{ async_function_dict.delay | default(0) | int }}"
+  until: >
+    (async_function_dict.until_false is not defined
+    or async_function_dict.until_false is defined and not test_function_result.stdout | regex_search(async_function_dict.until_false, multiline=True)) and
+    (async_function_dict.until_true is not defined or
+    async_function_dict.until_true is defined and test_function_result.stdout | regex_search(async_function_dict.until_true, multiline=True))
+  failed_when: false
+
+- name: Debug stdout
+  ansible.builtin.debug:
+    msg: |
+       Async function {{ async_function_dict.test_function }} for SAP SID {{ passed_sap_sid }}
+       is done with result:
+       {{ test_function_result.stdout }}