collection: Update sample playbooks and remove deprecated variables

playbooks/README.md

@@ -1,64 +1,55 @@
 
 # Ansible Collection Playbooks
 
-The playbooks starting with `sample-` in this directory can be used as examples for your own playbooksi and cannot be called directly from the commandline.
-The other playbooks can be called directly with a prepared variable file or imported in your own playbooks or workflows.
-The playbooks can run against localhost, all hosts or defined group.
+The playbooks in this directory are samples of how to use the roles of this collection.<br>
+Each `sample-` playbook shows one role or scenario with the mandatory variables only, so copy it and adapt it for your own playbooks.<br>
+The header of every sample lists its prerequisites and refers to the README of the role for all available variables.
 
-## Usage of playbooks
+> **NOTE: For complete end-to-end deployments of SAP systems, use [ansible.playbooks_for_sap](https://github.com/sap-linuxlab/ansible.playbooks_for_sap) (AP4S).**<br>
+> It is the collection of ready-to-use playbooks, which combine the roles of this collection into full scenarios.<br>
+> The samples here intentionally cover a single role each.
 
-### Prepare System for SAP HANA installation: `sap_hana_prepare_exec.yml`
+## Samples
 
-This playbook runs against localhost and/or remote hosts.
-You need to define the variable `sap_hana_group`to run this playbook against a particular group of hosts which is defined in your inventory.
-If you do not define the parameter `sap_hana_group` the playbook will run against all hosts in the inventory unless limited with `-l hostname' or localhost if no inventory is defined.
+All host groups, hostnames, addresses and passwords are placeholders.<br>
+Passwords in the samples are examples only, do not use them. Protect real credentials, e.g. with `ansible-vault`.
 
-To run this playbook you need to prepare a variable file with a minimum viable set of variables.
+| Area | Sample | Shows |
+| --- | --- | --- |
+| Preconfigure | `sample-sap-general-preconfigure.yml` | Role `sap_general_preconfigure` |
+| Preconfigure | `sample-sap-hana-preconfigure.yml` | Roles `sap_general_preconfigure` and `sap_hana_preconfigure` |
+| Preconfigure | `sample-sap-netweaver-preconfigure.yml` | Roles `sap_general_preconfigure` and `sap_netweaver_preconfigure` |
+| Storage | `sample-sap-storage-setup.yml` | Role `sap_storage_setup` with multipath, striped and plain block disks, swap disk, swap file and NFS mount |
+| Installation media | `sample-sap-install-media-detect.yml` | Role `sap_install_media_detect` for SAP HANA, ASCS and PAS hosts |
+| SAP HANA | `sample-sap-hana-install-scaleup.yml` | Role `sap_hana_install`, scale-up system |
+| SAP HANA | `sample-sap-hana-install-scaleout.yml` | Role `sap_hana_install`, scale-out system |
+| SAP SWPM | `sample-sap-swpm-role-variables.yml` | Role `sap_swpm` with role variables, installation or restore |
+| SAP SWPM | `sample-sap-swpm-templates.yml` | Role `sap_swpm` with `sap_swpm_templates_install_dictionary` |
+| SAP SWPM | `sample-sap-swpm-existing-inifile.yml` | Role `sap_swpm` with an existing `inifile.params` |
+| High Availability | `sample-sap-ha-pacemaker-cluster-hana-scale-up.yml` | Role `sap_ha_pacemaker_cluster`, SAP HANA scale-up cluster |
+| High Availability | `sample-sap-ha-pacemaker-cluster-ascs-ers.yml` | Role `sap_ha_pacemaker_cluster`, SAP NetWeaver ASCS and ERS cluster |
 
-#### Example: 
+The directory `vars` contains the variable files used by the SWPM samples, because their variable sets are too long to read inline.
 
-Create a parameter file `my_vars.yml` with similar content:
+For SAP HANA System Replication, see the example in the README of the role `sap_ha_install_hana_hsr`.
 
-```[yaml]
-    # sap_playbook_parameter_confirm: false   # Set to true if you want to list parameters and confirm execution
-    sap_domain: my.sap.domain
-    sap_general_preconfigure_modify_etc_hosts: true
-    sap_general_preconfigure_update: true
-    sap_general_preconfigure_fail_if_reboot_required: false
-    sap_hana_preconfigure_update: true
-    sap_hana_preconfigure_fail_if_reboot_required: false
-    sap_hana_preconfigure_reboot_ok: true
-```
+## Usage
 
-Create the file `my_inventory` similar to:
+Copy a sample and adapt the host groups and variables for your environment. Then run it against your inventory:
 
-```[yaml]
-[my_hanas]
-hana1
-hana2
+```bash
+ansible-playbook -i my_inventory sample-sap-hana-install-scaleup.yml
 ```
 
-Now you can run the playbook with
-
-```[bash]
-ansible-playbook community.sap_install.sap_hana_preconfigure_exec.yml -i my_inventory -e @my_vars.yml -e sap_hana_group=my_hanas
-```
+When running against remote hosts, the connection user needs to be able to become root.<br>
+Pass `-u <user>` for the SSH user, `-k` to ask for the SSH password and `-K` to ask for the privilege escalation password, if they are required.
 
-When you call this playbook against a remote host make sure the user can connect and assume root without a password or pass the following parameters if necessary
+> **NOTE:** Use `--check` first with the sample `sample-sap-storage-setup.yml`, to review changes before disks are configured.
 
-```[bash]
- -u <connection user>: User that establishes the ssh connection
- -k: asks for password or passphrase of the connection user, if required for ssh
- -K: asks for the privilege escalation password of the connection user to become root on the target host
-```
+## Plugin tests
 
-You can also call the playbook inside another playbook with:
+The playbooks starting with `test-` test the plugins of this collection and are not samples for users.
 
-```
-- name: Include HANA preparation from collection for group my_hanas
-  ansible.builtin.import_playbook: community.sap_install.sap_hana_prepare_exec.yml
-  vars:
-    sap_hana_group: my_hanas
-    # add other vars here, or define somewhere else
-```
+> **NOTE:** Playbooks with a hyphen in the file name cannot be called directly by `ansible-playbook` using the collection name.<br>
+> That is why all playbooks in this directory are meant to be copied or run by their file path.
 

playbooks/sample-sap-general-preconfigure.yml

@@ -0,0 +1,27 @@
+# SPDX-License-Identifier: Apache-2.0
+---
+
+# Ansible Playbook for preconfiguration of hosts for any SAP software, using the role 'sap_general_preconfigure'.
+# The role is a prerequisite for the product specific preconfigure roles, e.g. 'sap_hana_preconfigure' and 'sap_netweaver_preconfigure'.
+#
+# Prerequisites:
+# - The hosts are registered to a repository source with the repositories required for SAP software.
+# - The hosts have a DNS domain, which the role takes from the host FQDN (Ansible fact 'domain'),
+#   unless 'sap_general_preconfigure_domain' is set. It is not needed if 'sap_general_preconfigure_modify_etc_hosts' is set to false.
+#
+# See the README of the role 'sap_general_preconfigure' for all available variables.
+
+- name: Ansible Play for SAP general preconfigure
+  hosts: sap_hosts
+  become: true
+  any_errors_fatal: true
+  tasks:
+
+    - name: Execute Ansible Role sap_general_preconfigure
+      ansible.builtin.include_role:
+        name: community.sap_install.sap_general_preconfigure
+      vars:
+        sap_general_preconfigure_domain: 'example.com'  # Defines the valid DNS domain for the hosts.
+        sap_general_preconfigure_update: true  # Ensures that the system is updated.
+        sap_general_preconfigure_reboot_ok: true  # Allows the system to reboot if required.
+        sap_general_preconfigure_fail_if_reboot_required: false  # Ensures that the playbook will not fail if reboot is required.

playbooks/sample-sap-ha-pacemaker-cluster-ascs-ers.yml

@@ -0,0 +1,54 @@
+# SPDX-License-Identifier: Apache-2.0
+---
+
+# Ansible Playbook for installing and configuring a Pacemaker cluster for SAP NetWeaver ABAP ASCS and ERS with 2 nodes.
+# The ASCS and ERS cluster defaults to ENSA2 with Simple Mount, unless overridden by the role variables.
+#
+# The role configures the ASCS and ERS resource groups, each with an instance filesystem,
+# the instance resource and a virtual IP address of the instance.
+#
+# WARNING: The role destroys and then recreates the Pacemaker cluster on the hosts.
+#
+# Prerequisites:
+# - SAP NetWeaver ASCS and ERS instances are installed, e.g. by the role 'sap_swpm'.
+# - The required ports are open, see the README of the role 'sap_ha_pacemaker_cluster'.
+# - Cloud platform resources required by the resource agents exist, because the role does not create them.
+# - Hosts with more than one network interface need 'sap_ha_pacemaker_cluster_vip_client_interface' defined,
+#   to select the interface for the virtual IP addresses. The role fails otherwise.
+# - Fencing: The role detects the platform and prepares the fence agent resource. Without fencing, STONITH is disabled.
+#   On a platform without detection, define the fence agent with 'sap_ha_pacemaker_cluster_stonith_custom'.
+#   The role does not provision the fencing devices (e.g. SBD block devices or watchdog), they have to be present before.
+#   The role only activates them in the cluster configuration.
+#
+# See the README of the role 'sap_ha_pacemaker_cluster' for all available variables.
+
+- name: Ansible Play for SAP NetWeaver ASCS and ERS Pacemaker cluster setup
+  hosts: nwas_ascs, nwas_ers
+  become: true
+  any_errors_fatal: true
+  tasks:
+
+    - name: Execute Ansible Role sap_ha_pacemaker_cluster
+      ansible.builtin.include_role:
+        name: community.sap_install.sap_ha_pacemaker_cluster
+      vars:
+        sap_ha_pacemaker_cluster_cluster_name: ascs-ers-cluster
+        sap_ha_pacemaker_cluster_hacluster_user_password: 'NewPass$321'  # Do not use, this is example only!
+
+        sap_ha_pacemaker_cluster_host_type:
+          - nwas_abap_ascs_ers
+
+        # SID and instance numbers of ASCS and ERS.
+        sap_ha_pacemaker_cluster_nwas_sid: AE1
+        sap_ha_pacemaker_cluster_nwas_ascs_instance_nr: '00'
+        sap_ha_pacemaker_cluster_nwas_ers_instance_nr: '10'
+
+        # Instance names and profile paths created by the installer, in the format <SID>_<ASCS|ERS><instance number>_<virtual hostname>.
+        sap_ha_pacemaker_cluster_nwas_ascs_sapinstance_instance_name: AE1_ASCS00_ascs-node-ha
+        sap_ha_pacemaker_cluster_nwas_ascs_sapinstance_start_profile_string: /sapmnt/AE1/profile/AE1_ASCS00_ascs-node-ha
+        sap_ha_pacemaker_cluster_nwas_ers_sapinstance_instance_name: AE1_ERS10_ers-node-ha
+        sap_ha_pacemaker_cluster_nwas_ers_sapinstance_start_profile_string: /sapmnt/AE1/profile/AE1_ERS10_ers-node-ha
+
+        # Virtual IP addresses of the instances. They move between the nodes together with the instance.
+        sap_ha_pacemaker_cluster_vip_nwas_ascs_ip_address: 192.168.10.100
+        sap_ha_pacemaker_cluster_vip_nwas_ers_ip_address: 192.168.10.110

playbooks/sample-sap-ha-pacemaker-cluster-hana-scale-up.yml

@@ -0,0 +1,56 @@
+# SPDX-License-Identifier: Apache-2.0
+---
+
+# Ansible Playbook for installing and configuring a Pacemaker cluster for a SAP HANA scale-up system with 2 nodes.
+# The cluster defaults to using the SAP HANA Angi resource agent, if it is available and installable.
+#
+# WARNING: The role destroys and then recreates the Pacemaker cluster on the hosts.
+#
+# Prerequisites:
+# - SAP HANA is installed and SAP HANA System Replication is configured between the nodes.
+# - The required ports are open, see the README of the role 'sap_ha_pacemaker_cluster'.
+# - Cloud platform resources required by the resource agents exist, because the role does not create them.
+# - Hosts with more than one network interface need 'sap_ha_pacemaker_cluster_vip_client_interface' defined,
+#   to select the interface for the virtual IP address. The role fails otherwise.
+# - Fencing: The role detects the platform and prepares the fence agent resource. Without fencing, STONITH is disabled.
+#   On a platform without detection, define the fence agent with 'sap_ha_pacemaker_cluster_stonith_custom'.
+#   The role does not provision the fencing devices (e.g. SBD block devices or watchdog), they have to be present before.
+#   The role only activates them in the cluster configuration.
+#
+# See the README of the role 'sap_ha_pacemaker_cluster' for all available variables.
+
+- name: Ansible Play for SAP HANA scale-up Pacemaker cluster setup
+  hosts: hana_primary, hana_secondary
+  become: true
+  any_errors_fatal: true
+  tasks:
+
+    - name: Execute Ansible Role sap_ha_pacemaker_cluster
+      ansible.builtin.include_role:
+        name: community.sap_install.sap_ha_pacemaker_cluster
+      vars:
+        sap_ha_pacemaker_cluster_cluster_name: clusterhdb
+        sap_ha_pacemaker_cluster_hacluster_user_password: 'NewPass$321'  # Do not use, this is example only!
+
+        sap_ha_pacemaker_cluster_host_type:
+          - hana_scaleup_perf
+
+        sap_ha_pacemaker_cluster_hana_sid: H01
+        sap_ha_pacemaker_cluster_hana_instance_nr: '01'
+
+        # Ensures that packages conflicting with SAP HANA Angi are uninstalled before it is used.
+        # WARNING: This is a one-way step, which is destructive on a running cluster without migration to SAP HANA Angi.
+        sap_ha_pacemaker_cluster_saphanasr_angi_force: true
+
+        sap_ha_pacemaker_cluster_cluster_nodes:
+          - node_name: h01hana0
+            node_ip: 10.10.10.10
+            node_role: primary
+            hana_site: DC01
+          - node_name: h01hana1
+            node_ip: 10.10.10.11
+            node_role: secondary
+            hana_site: DC02
+
+        # Virtual IP of the primary SAP HANA instance, it moves between the nodes together with the primary role.
+        sap_ha_pacemaker_cluster_vip_hana_primary_ip_address: 10.10.10.12

playbooks/sample-sap-hana-install-scaleout.yml

@@ -0,0 +1,34 @@
+# SPDX-License-Identifier: Apache-2.0
+---
+
+# Ansible Playbook for installing a new scale-out SAP HANA system, using the role 'sap_hana_install'.
+#
+# The system is installed from master node 'host0', which is the first host of the play,
+# and the other hosts are added to it as listed in 'sap_hana_install_addhosts'.
+#
+# Prerequisites:
+# - The software directory contains the IMDB_SERVER*SAR file, IMDB_*SAR files of all components to be installed and the SAPCAR executable.
+# - All hosts are prepared for SAP HANA, e.g. by the roles 'sap_general_preconfigure' and 'sap_hana_preconfigure'.
+# - SSH communication works between all hosts.
+#
+# See the README of the role 'sap_hana_install' for all available variables.
+
+- name: Ansible Play for SAP HANA installation - Scale-out
+  hosts: host0, host1, host2, host3
+  become: true
+  any_errors_fatal: true
+  tasks:
+
+    - name: Execute Ansible Role sap_hana_install
+      ansible.builtin.include_role:
+        name: community.sap_install.sap_hana_install
+      vars:
+        sap_hana_install_sid: 'H01'
+        sap_hana_install_instance_nr: '01'
+        sap_hana_install_addhosts: 'host1:role=worker,host2:role=worker:group=g02,host3:role=standby:group=g02'
+        sap_hana_install_software_directory: /software/hana
+        sap_hana_install_master_password: 'NewPass$321'  # Do not use, this is example only!
+        sap_hana_install_sapadm_password: 'NewPass$321'  # Do not use, this is example only!
+
+        # Set to 'false', if hosts1 to host3 are being added to an existing host0 master node.
+        sap_hana_install_new_system: true

playbooks/sample-sap-hana-install-scaleup.yml

@@ -0,0 +1,25 @@
+# SPDX-License-Identifier: Apache-2.0
+---
+
+# Ansible Playbook for installing a new scale-up (single node) SAP HANA system, using the role 'sap_hana_install'.
+#
+# Prerequisites:
+# - The software directory contains the IMDB_SERVER*SAR file, IMDB_*SAR files of all components to be installed and the SAPCAR executable.
+# - The host is prepared for SAP HANA, e.g. by the roles 'sap_general_preconfigure' and 'sap_hana_preconfigure'.
+#
+# See the README of the role 'sap_hana_install' for all available variables.
+
+- name: Ansible Play for SAP HANA installation - Scale-up
+  hosts: hana_hosts
+  become: true
+  any_errors_fatal: true
+  tasks:
+
+    - name: Execute Ansible Role sap_hana_install
+      ansible.builtin.include_role:
+        name: community.sap_install.sap_hana_install
+      vars:
+        sap_hana_install_sid: 'H01'
+        sap_hana_install_instance_nr: '01'
+        sap_hana_install_software_directory: /software/hana
+        sap_hana_install_master_password: 'NewPass$321'  # Do not use, this is example only!