Skip to content

sap_control: Complete redesign and rework #48

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
marcelmamula wants to merge 4 commits into
base: dev
Choose a base branch
from
Open

sap_control: Complete redesign and rework #48

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
b6fc9bc
feat: Complete redesign and rework of sap_control role
marcelmamula Dec 11, 2025
9bb0048
Add additional asserts and use of retry override variables, improve l…
marcelmamula Dec 12, 2025
ae119d3
add reset for sort list
marcelmamula Dec 12, 2025
16cda4a
update readme and resolve linting error
marcelmamula Dec 12, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
222 changes: 171 additions & 51 deletions roles/sap_control/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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 -->
Loading