sap_control: Complete redesign and rework

roles/sap_control/README.md

@@ -1,72 +1,192 @@
+<!-- BEGIN Title -->
 # sap_control Ansible Role
+<!-- END Title -->
+
+## Description
+<!-- BEGIN Description -->
+The Ansible role `sap_control` executes predefined that cover range of SAP administration tasks, 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.
+<!-- END Description -->
+
+<!-- BEGIN Disclaimer -->
+## Disclaimer
+> **IMPORTANT:** This role is designed to perform administrative actions on SAP systems, such as starting and stopping instances.  
+> Misuse of this role, especially in production environments, can lead to system downtime and potential data loss.  
+> It is crucial to understand the function you are executing and its impact on your SAP landscape.  
+> Always test in non-production environments before applying to production systems. Use with caution.  
+<!-- END Disclaimer -->
+
+<!-- BEGIN Dependencies -->
+## Dependencies
+> This is optional dependency, active only when the variable `sap_control_use_sap_system_facts` is set to `true`.
+- `community.sap_libs`
+    - Modules:
+        - `sap_system_facts`
+  - This collection is part of main Ansible package.
+<!-- END Dependencies -->
+
+<!-- BEGIN Prerequisites -->
+This Ansible Role assumes that SAP Netweaver and HANA are installed in standard locations.
+- The `<sid>adm` user exists for each SAP system.
+- The `sapcontrol` executable is in the `PATH` of the `<sid>adm` user.
+   - This role validates standard `sapcontrol` location `/usr/sap/<SID>/<INSTANCE>/exe/sapcontrol`.
+- Standard SAP directory structures are used:
+  - `/usr/sap` and `/sapmnt` for SAP Netweaver
+  - `/usr/sap` and `/hana/shared` for SAP HANA
+<!-- END Prerequisites -->
+
+## Execution
+<!-- BEGIN Execution -->
+Primary variable is `sap_control_function` and it drives all logic of this role.  
+The function names are constructed using the pattern: [`ACTION`]_[`SCOPE`]_[`TARGET`]
+
+`ACTION`: The operation to perform.
+- Process-level: `start`, `stop`, `restart`
+- System-level (asynchronous): `startsystem`, `stopsystem`, `restartsystem`, `updatesystem`
+
+`SCOPE`: The instances the action applies to.
+- `all`: Applies to all detected instances of the target type.
+- `sap`: Applies to a single instance specified by `sap_control_sid`.
+
+`TARGET`: The type of SAP system.
+- `hana`: SAP HANA instances.
+- `nw`: SAP NetWeaver instances.
+- `sap`: All SAP instances (both `hana` and `nw`).
+
+Following functions are available:
+| Target and Scope | Start | Stop | Restart | Other |
+| --- | --- | --- | --- | --- |
+| HANA | start_all_hana<br>start_sap_hana | stop_all_hana<br>stop_sap_hana | restart_all_hana<br>restart_sap_hana | |
+| Netweaver | start_all_nw<br>start_sap_nw | stop_all_nw<br>stop_sap_nw | restart_all_nw<br>restart_sap_nw | |
+| Combined | start_all_sap | stop_all_sap | restart_all_sap | |
+| System | startsystem_all_nw<br>startsystem_sap_nw | stopsystem_all_nw<br>stopsystem_sap_nw | restartsystem_all_nw<br>restartsystem_sap_nw | updatesystem_all_nw<br>updatesystem_sap_nw |
+
+### System Functions
+`system` functions are not operating SAP systems instance by instance, instead they leave this for `sapcontrol` to decide by utilizing functions like `StartSystem`, `StopSystem` and others.
+
+This role will asynchronously poll completion of these functions by getting system status (e.g. `GetSystemInstanceList`).
+The default polling duration is 600 seconds (60 retries with a 10-second delay)
+
+For larger systems where this may not be sufficient, you can adjust the duration using the following variables:
+- `sap_control_async_retries`
+- `sap_control_async_delay`
+<!-- END Execution -->
+
+### Execution Flow
+<!-- BEGIN Execution Flow -->
+1. Assert and validate all variables.
+2. Detect existing SAP System IDs and Instances on host.
+   - Alternatively collection this information using `community.sap_libs.sap_system_facts` module if the variable `sap_control_use_sap_system_facts` is set to `true`.
+3. Prepare list of commands for execution.
+4. Check if `sapstartsrv` service is running.
+   - Service is restarted when required, because it is required for `sapcontrol` commands.
+5. Execute `sapcontrol` commands and wait for completion.
+6. Execute `cleanipc` command unless the variable `sap_control_cleanipc` is set to `false`.
+7. Show output message with current status of processes for each instance.
+<!-- END Execution Flow -->
+
+### Example
+<!-- BEGIN Execution Example -->
+Example of starting all SAP Netweaver instances on host(s).
+```yaml
+---
+- name: Ansible Play for SAP Control
+  hosts: all
+  become: true
+  tasks:
+    - name: Execute Ansible Role sap_control
+      ansible.builtin.include_role:
+        name: community.sap_operations.sap_control
+      vars:
+        sap_control_function: start_all_nw
+```
 
-This Ansible Role executes basic SAP administration tasks on Linux operating systems.
-
-## Ansible Role Overview
-
-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
-
-### Example Playbook
-
+Example of stopping `B01` SAP Netweaver and HANA instances on host(s) using `community.sap_libs.sap_system_facts`, without `cleanipc` execution.
 ```yaml
-- hosts: sap_servers
-  roles:
-    - { role: community.sap_operations.sap_control }
+---
+- name: Ansible Play for SAP Control
+  hosts: all
+  become: true
+  tasks:
+    - name: Execute Ansible Role sap_control
+      ansible.builtin.include_role:
+        name: community.sap_operations.sap_control
+      vars:
+        sap_control_function: stop_all_sap
+        sap_control_sid: B01
+        sap_control_use_sap_system_facts: true
+        sap_control_cleanipc: false
 ```
+<!-- END Execution Example -->
+
+## Testing
+This Ansible Role has been tested in following scenarios.
+Operating systems:
+ - SUSE Linux Enterprise Server for SAP applications 15 SP6 and SP7 (SLE4SAP)
+ - SUSE Linux Enterprise Server for SAP applications 16 (SLE4SAP)
 
-### Example Inputs
+SAP Products:
+- SAP Netweaver 7.50 and higher
+- SAP HANA 2.0 SP04 and higher
 
-- Using restart all
-  ```yaml
-  sap_control_function: "restart_all_sap"
-  ```
-- Using a specific SAP SID
-  ```yaml
-  sap_control_function: "stop_sap_hana"
-  sap_sid: "HDB"
-  ```
+## License
+<!-- BEGIN License -->
+Apache 2.0
+<!-- END License -->
 
-## Ansible Role Requirements and Dependencies
+## Maintainers
+<!-- BEGIN Maintainers -->
+- [Marcel Mamula](https://github.com/marcelmamula)
+<!-- END Maintainers -->
 
-### Operating System
+## Role Variables
+<!-- BEGIN Role Variables -->
+### sap_control_function
+- _Type:_ `string`
 
-This role has been tested with RHEL, and is designed for Linux operating systems.
+The sapcontrol function to execute on target host.  
+These are predefined functions defined in variable `__sap_control_function_definitions`.
 
-This role has not been tested and amended for SAP NetWeaver Application Server instantiations on IBM AIX or Windows Server.
+### sap_control_sid
+- _Type:_ `string`
 
-Assumptions for executing this role include:
-- Instances of either SAP HANA Database Server or SAP NetWeaver Application Server are installed to the target host
-- Relevent OS Packages for SAP are installed
-- Registered OS License and OS Package repositories are available (from the relevant content delivery network of the OS vendor)
+The 3-letter SAP System ID (e.g., 'PRD', 'QAS').  
+This is required when executing a function that targets a specific SAP instance (e.g., `start_sap_nw`) instead of all instances on the host.
 
-### SAP software instances
+### sap_control_command_nowait
+- _Type:_ `boolean`
+- _Default:_ `false`
 
-This role has been tested with SAP NetWeaver Application Server 7.53 and SAP HANA Database Server 2.0 SPS04 rev 20.
+If set to `true`, the role will not wait for start/stop operations to complete.  
+> **NOTE:** This option should be used with caution, as the role will not verify the final status of the instance.
 
-This role has not been tested with other versions of SAP NetWeaver Application Server, however it should work for all versions above SAP NetWeaver Application Server 7.50.
+### sap_control_cleanipc
+- _Type:_ `boolean`
+- _Default:_ `true`
 
-This role has not been tested with other versions of SAP HANA Database Server, however it should work for all versions above SAP HANA 2.0 SPS00.
+If set to `false`, the `cleanipc` command will not be executed after stopping an SAP instance.
 
-Assumptions for executing this role include:
-- Installations used default `/usr/sap` and `/sapmnt` directories
-- Installations for SAP HANA used default `/hana/shared` directory
+### sap_control_use_sap_system_facts
+- _Type:_ `boolean`
+- _Default:_ `false`
 
-## Ansible Role Variables
+Enable this variable to use `community.sap_libs.sap_system_facts` to detect SAP instances.  
+This can be useful if this role is part of a playbook that expects facts set by that module.  
+> **NOTE:** This module will not detect instances with `sapstartsrv` stopped.
 
-| **variable** | **info** | **required** |
-| :--- |:--- | :--- |
-| `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><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_ |
+### sap_control_async_retries
+- _Type:_ `string` or `integer`
 
-## Ansible Role workflow and structure
+Overrides the number of retries for asynchronous tasks.  
+If not set, the role uses the default value defined in the function step (e.g., 60 for `startsystem_all_nw`).  
+Applies to functions that include `system` in their name.  
 
-The following diagram demonstrates the Ansible Role workflow, where the variable `sap_control_function` is set with different values (such as **"restart_all"**) and will perform different sequence of SAP Host Agent `sapcontrol` CLI functions.
+### sap_control_async_delay
+- _Type:_ `string` or `integer`
 
-![sap_control](/docs/diagrams/workflow_role_sap_control.svg)
+Overrides the delay (in seconds) between retries for asynchronous tasks.  
+If not set, the role uses the default value defined in the function step (e.g., 10 for `startsystem_all_nw`).  
+Applies to functions that include `system` in their name.  
+<!-- END Role Variables -->