Release galaxy-2.11.0

galaxy.yml

@@ -24,7 +24,7 @@ namespace: sap
 
 name: sap_operations
 
-version: 2.10.1
+version: 2.11.0
 
 readme: README.md
 

plugins/doc_fragments/hana.py

@@ -0,0 +1,102 @@
+# SPDX-License-Identifier: GPL-3.0-only
+# SPDX-FileCopyrightText: 2024 Red Hat, Project Atmosphere
+#
+# Copyright 2024 Red Hat, Project Atmosphere
+#
+# This program is free software: you can redistribute it and/or modify it under the terms of the GNU
+# General Public License as published by the Free Software Foundation, version 3 of the License.
+#
+# This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without
+# even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
+# See the GNU General Public License for more details.
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+# You should have received a copy of the GNU General Public License along with this program.
+# If not, see <https://www.gnu.org/licenses/>.
+
+
+from __future__ import absolute_import, division, print_function
+
+__metaclass__ = type
+
+
+class ModuleDocFragment(object):
+    DOCUMENTATION = """
+---
+options: {}
+notes:
+  - |
+    Variable binary_path is required, because hdbuserstore command cannot be found in $PATH environment variable.
+    If running ansible module using become directive with <hanasid>adm user and flag '-i' \
+    (interactive - meaning load all environment for the user) ansible modules fail.
+    This is due to the fact that <hanasid>adm user sets environment variables PYTHONHOME and PYTHONPATH \
+    (to use HANA python, not platform python) that confuses ansible.
+    And also HANA python might not have all the necessary packages installed to run ansible module.
+    In that case hdbuserstore command will not be in PATH environment variable for <hanasid>adm user and I(binary_path) has to be provided.
+  - |
+    There are several workaround around this unpleasant situation. First one is recommended.
+  - |
+    Workaround 1 (recommended)
+  - Run hdbsuserstore module with <hanasid>adm user with '-i' (interactive) flag like so
+  - "- name: Set the key mykey"
+  - "sap.sap_operations.hdbuserstore:"
+  - "   key: mykey"
+  - "   env: localhost:30113"
+  - "   username: myuser"
+  - "   password: mypassword"
+  - "become: true"
+  - "become_user: <hanasid>adm"
+  - "become_flags: -i"
+  - "vars:"
+  - "    ansible_python_interpreter: '/usr/libexec/platform-python -E'"
+  - |
+    Option '-E' for python interpreter will ignore all PYTHON environment variables, so ansible will run platform python without any problems.
+    Variable I(ansible_python_interpreter) have to be set to value "/usr/libexec/platform-python -E" on all RHEL versions for any ansible module
+    execution when using become directive for <hanasid>adm user with become flag '-i'.
+  - |
+    ansible_python_interpreter: "/usr/libexec/platform-python -E" can be set at task level (as above),\
+    at play level, or be set as host variable either in inventory file or as task in playbook:
+  - |
+    To use other SAP HANA related ansible modules (for instances hana_system_replication_info),\
+    this is the only option, because other modules might not have parameters to accommodate for binary tool path.
+  - |
+    Workaround 2 (only for hdbuserstore module)
+  - |
+    Do not use interactive flag when becoming <hanasid>adm user.
+  - "- name: Set the key mykey"
+  - "sap.sap_operations.hdbuserstore:"
+  - "   key: mykey"
+  - "   env: localhost:30113"
+  - "   username: myuser"
+  - "   password: mypassword"
+  - "   binary_path: /usr/sap/HAN/SYS/exe/hdb"
+  - "become: true"
+  - "become_user: <hanasid>adm"
+  - |
+    In that case hdbuserstore command will not be in PATH environment variable for <hanasid>adm user and I(binary_path) has to be provided.
+  - |
+    Workaround 3 (only for hdbuserstore module)
+  - Do not use interactive flag when becoming <hanasid>adm user. But do not want to provide value for variable I(binary_path).
+  - In that case value for I(binary_path) can be extracted from HANA parameter DIR_EXECUTABLE that one can get with I(parameter_info) module
+  - "- name: Get DIR_EXECUTABLE"
+  - "sap.sap_operations.parameter_info:"
+  - "   instance_number: 00"
+  - "   name: DIR_EXECUTABLE"
+  - "become: true"
+  - "become_user: <hanasid>adm"
+  - "register: __DIR_EXECUTABLE"
+  - "- name: Set the key mykey"
+  - "sap.sap_operations.hdbuserstore:"
+  - "   key: mykey"
+  - "   env: localhost:30113"
+  - "   username: myuser"
+  - "   password: mypassword"
+  - "   binary_path: '{{ __DIR_EXECUTABLE.parameter_value[0] }}'"
+  - "become: true"
+  - "become_user: <hanasid>adm"
+"""

plugins/module_utils/common.py

@@ -0,0 +1,33 @@
+# SPDX-License-Identifier: GPL-3.0-only
+# SPDX-FileCopyrightText: 2024 Red Hat, Project Atmosphere
+#
+# Copyright 2024 Red Hat, Project Atmosphere
+#
+# This program is free software: you can redistribute it and/or modify it under the terms of the GNU
+# General Public License as published by the Free Software Foundation, version 3 of the License.
+#
+# This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without
+# even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
+# See the GNU General Public License for more details.
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+# You should have received a copy of the GNU General Public License along with this program.
+# If not, see <https://www.gnu.org/licenses/>.
+
+from __future__ import absolute_import, division, print_function
+
+
+__metaclass__ = type
+
+
+def convert_string2bool(value):
+    if value.lower() == "true":
+        return True
+    if value.lower() == "false":
+        return False
+    return value

plugins/module_utils/enq_admin.py

@@ -26,6 +26,9 @@
 
 
 from ansible.module_utils.basic import AnsibleModule
+from ansible_collections.sap.sap_operations.plugins.module_utils.common import (  # noqa: E501
+    convert_string2bool,
+)
 
 
 class AnsibleModuleEnqAdmin(AnsibleModule):
@@ -105,14 +108,6 @@ def run_enq_admin(args, module=None):
     return module.run_command(default_args + args)
 
 
-def convert_string2bool(value):
-    if value.lower() == "true":
-        return True
-    if value.lower() == "false":
-        return False
-    return value
-
-
 def get_table_from_csv_data(data):
     data_lines = data.split("\n")
     if len(data_lines) < 2:

plugins/module_utils/hana.py

@@ -0,0 +1,68 @@
+# SPDX-License-Identifier: GPL-3.0-only
+# SPDX-FileCopyrightText: 2024 Red Hat, Project Atmosphere
+#
+# Copyright 2024 Red Hat, Project Atmosphere
+#
+# This program is free software: you can redistribute it and/or modify it under the terms of the GNU
+# General Public License as published by the Free Software Foundation, version 3 of the License.
+#
+# This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without
+# even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
+# See the GNU General Public License for more details.
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+# You should have received a copy of the GNU General Public License along with this program.
+# If not, see <https://www.gnu.org/licenses/>.
+
+from __future__ import absolute_import, division, print_function
+from ansible_collections.sap.sap_operations.plugins.module_utils.common import (  # noqa: E501
+    convert_string2bool,
+)
+from ansible.module_utils.basic import AnsibleModule
+from typing import List
+from collections.abc import Callable
+
+HANA_SYSTEM_REPLICATION_INFO_MAPPING = {
+    "online": "online",
+    "mode": "mode",
+    "operation_mode": "operation mode",
+    "site_id": "site id",
+    "site_name": "site name",
+    "is_source_system": "is source system",
+    "is_secondary_consumer_system": "is secondary/consumer system",
+    "has_secondaries_consumers_attached": "has secondaries/consumers attached",
+    "is_takeover_active": "is a takeover active",
+    "is_primary_suspended": "is primary suspended",
+}
+
+
+def get_hdbnsutil_run_command(module: AnsibleModule) -> Callable:
+    def hdbnsutil_run_command(args: List[str]) -> tuple[int, str, str]:
+        rc, stdout, stderr = module.run_command(["hdbnsutil"] + args)
+        return rc, stdout, stderr
+
+    return hdbnsutil_run_command
+
+
+def get_hana_system_replication_info_from_stdout(stdout: str) -> dict:
+    """Parses the stdout of the 'hdbnsutil -sr_state' command and returns a dictionary containing the license information.
+
+    Args:
+        stdout (str): The stdout
+
+    Returns:
+        dict: A dictionary containing the hana system replication configuration information
+    """
+    hana_system_replication_info = dict()
+    for line in stdout.splitlines():
+        for key, value in HANA_SYSTEM_REPLICATION_INFO_MAPPING.items():
+            if value in line:
+                hana_system_replication_info[key] = convert_string2bool(
+                    line.split(":")[1].strip()
+                )
+    return hana_system_replication_info

plugins/modules/hana_backup.py

@@ -23,11 +23,11 @@
 # If not, see <https://www.gnu.org/licenses/>.
 
 from __future__ import absolute_import, division, print_function
-
 __metaclass__ = type
 
 
-DOCUMENTATION = r"""
+DOCUMENTATION = """
+---
 module: hana_backup
 
 author:
@@ -126,7 +126,8 @@
     type: str
 """
 
-EXAMPLES = r"""
+EXAMPLES = """
+---
 - name: Fetch the binary path of the hdbsql
   sap.sap_operations.parameter_info:
     instance_number: "00"
@@ -157,12 +158,11 @@
     wait: false
 """
 
-RETURN = r""" # """
-
+RETURN = """ # """
 
-import os
 
 from ansible.module_utils.basic import AnsibleModule
+import os
 
 
 def get_sql(module):

plugins/modules/hana_restore.py

@@ -22,11 +22,11 @@
 # If not, see <https://www.gnu.org/licenses/>
 
 from __future__ import absolute_import, division, print_function
-
 __metaclass__ = type
 
 
-DOCUMENTATION = r"""
+DOCUMENTATION = """
+---
 module: hana_restore
 
 extends_documentation_fragment: sap.sap_operations.community
@@ -129,7 +129,8 @@
 
 """  # noqa E501
 
-EXAMPLES = r"""
+EXAMPLES = """
+---
 - name: Fetch the binary path of the hdbsql
   sap.sap_operations.parameter_info:
     instance_number: "00"
@@ -182,11 +183,10 @@
   become_user: rheadm
 """
 
-RETURN = r""" # """
-
-import os
+RETURN = """ # """
 
 from ansible.module_utils.basic import AnsibleModule
+import os
 
 
 def get_path_sql(module, key):