susCostOpt.py(7)

NAME
susCostOpt.py - Provider for SAP HANA srHook method postTakeover().

DESCRIPTION
susCostOpt.py can be used to provide a script for the SAP HANA srHook method postTakeover(). The SAP HANA nameserver provides a Python-based API ("HA/DR providers"), which is called at important points of the host auto-failover and system replication takeover processes. These so called hooks can be used for arbitrary operations that need to be executed. The method postTakeover() is called after successful sr_takeover action. susCostOpt.py executes SQL statements to remove the memory allocation limit and switches off HANA column table preload after takeover from primary to secondary site in an SAP HANA scale-up cost-optimized scenario. This hook script needs to be configured and activated on the secondary node.

SUPPORTED PARAMETERS
The "HA/DR providers" API accepts the following parameters for the ha_dr_provider_suscostopt section:

provider = susCostOpt
    Mandatory. Must not be changed.

path = /usr/share/SAPHanaSR
    Mandatory. Please change only if requested.

costopt_primary_global_allocation_limit = [ 0 | <limit-in-mb> ]
    Optional. Not set or set to 0 means unlimited.

userkey = <costoptkey>
    Optional. Default is saphanasr_<SID>_costopt.

execution_order = 2
    Mandatory. Needs to run after SAPHanaSR.py.

The "HA/DR providers" API accepts the following parameter for the trace section:

ha_dr_suscostopt = [ info | debug ]
    Optional. Will be added automatically if not set.

RETURN CODES
0 Successful program execution.
>0 Usage, syntax or execution errors.

EXAMPLES

* Example for entry in SAP HANA global configuration /hana/shared/$SID/global/hdb/custom/config/global.ini .

The section ha_dr_provider_suscostopt is needed on the secondary site only. Additional settings in sections memorymanager and system_replication on secondary site are needed for the cost-optimised scenario. The example SID is HA1, memory limit is 24000MB in case of running as HANA secondary, 32000MB in case of running as HANA primary. These settings will be changed in case of takeover. So they need to be restored in order to recover the original state. See also example recovery procedure. The HANA has to be stopped before the file can be changed.

    [memorymanager]
    global_allocation_limit = 24000

    [system_replication]
    preload_column_tables = false
     ...

    [ha_dr_provider_suscostopt]
    provider = susCostOpt
    path = /usr/share/SAPHanaSR
    userkey = saphanasr_HA1_costopt
    costopt_primary_global_allocation_limit = 32000
    execution_order = 2

    [trace]
    ha_dr_suscostopt = info
     ...

* Example for checking the HANA tracefiles for postTakeover() events.

To be executed on HANA secondary site.

    # su - ha1adm
    ~> cdtrace
    ~> grep susCostOpt.*postTakeover nameserver_*.trc

* Example for checking the HANA tracefiles for when the hook script has been loaded.

To be executed on HANA secondary site.

    # su - ha1adm
    ~> cdtrace
    ~> grep HADR.*load.*susCostOpt nameserver_*.trc
    ~> grep susCostOpt.init nameserver_*.trc

* Example for adding the HANA database user to <sid>adm´s keystore.

The HANA database user SYSTEM has permission to change memory limit and column pre-load. For security reasons on production systems always a dedicated user with restricted permission needs to be created. The keystore for <sid>adm has to be created on secondary site. The example SID is HA1, lowercase-SID is ha1, instance number is 10, TCP port for database access is 31013, database user is SYSTEM, userkey in keystore is saphanasr_HA1_costopt, password is SuSE1234. Please refer to SAP documentation for details on HANA commands.

    # su - ha1adm
    ~> hdbuserstore SET saphanasr_HA1_costopt localhost:31013 SYSTEM SuSE1234
    ~> hdbuserstore LIST saphanasr_HA1_costopt

* Overview on recovery procedure for reverting to normal operation after takeover.

On postTakeover() the hook script changes configuration in memory and in persistence. It is neccessary to recover the initial settings on secondary site (step 7) before the fully operational state can be re-established (steps 8-11). Futher the HANA cluster resource default is AUTOMATED_REGISTER=false. This also makes administrative interaction neccessary (steps 1-4). If AUTOMATED_REGISTER=true is set, the Linux cluster will do that automatically. See manual page ocf_suse_SAPHana(7) for details on cluster resource settings. Use exact same site names as known to the Linux cluster. See manual page SAPHanaSR_maintenance_examples(7). Before doing anything with the cluster, and after something has been done, the status of Linux cluster and HANA system replication has to be checked. See manual page SAPHanaSR_maintenance_examples(7).

The procedure at a glance:

    1. set HANA multi-state resource into maintenance
    2. cleanup HANA primitive resource
    3. site_A: register former primary as new secondary
    4. site_A: start new secondary, and wait for SR sync to finish
    5. site_B: stop primary
    6. site_A: do sr_takeover on secondary
    7. site_B: adapt global.ini on stopped former primary
    8. site_B: register former primary as new secondary
    9. site_B: start new secondary, and wait for SR sync to finish
    10. refresh HANA multi-state resource
    11. take HANA multi-state resource out of maintenance

* Adpating configuration for secondary in memory and in persistence (global.ini).

This can be done for adapting the global.ini to prepare a future secondary. E.g. in the context of the above procedure for reverting back to the initial state. In that context it might be done before the primary gets stopped at step 5. In that case above step 7 is not needed anymore.

Example instance number is 00, SID is S07, user keystore is saphanasr_S07_costopt, memory limit for the secondary database is 128000 MB.

    # su - s07adm
    ~> hdbsql -i 00 -U saphanasr_S07_costopt -d SYSTEMDB
    hdbsql SYSTEMDB=> ALTER SYSTEM ALTER CONFIGURATION ('global.ini','SYSTEM') \
    SET ('memorymanager','global_allocation_limit') = '128000' \
    WITH RECONFIGURE
    hdbsql SYSTEMDB=> ALTER SYSTEM ALTER CONFIGURATION ('global.ini','SYSTEM') \
    SET ('system_replication','preload_column_tables') = 'false' \
    WITH RECONFIGURE
    hdbsql SYSTEMDB=> quit

FILES

/usr/share/SAPHanaSR/susCostOpt.py
    the hook provider, delivered with the RPM

/hana/shared/$SID/global/hdb/custom/config/global.ini
    on-disk representation of HANA global system configuration

/usr/sap/$SID/home/.hdb/$HOST/
    path to HANA user keystore

/usr/sap/$SID/HDB$nr/$HOST/trace
    path to HANA tracefiles

REQUIREMENTS
1. SAP HANA 2.0 SPS04 or later provides the HA/DR provider hook method postTakeover().

2. No other HADR provider hook script should be configured for the postTakeover() method. Hook scripts for other methods, provided in SAPHanaSR, can be used in parallel to susCostOpt.py, if not documented contradictingly.

3. The hook provider needs to be added to the HANA global configuration on the secondary site, in memory and on disk (in persistence).

4. An HANA database user with permission for changing memory limit and table preload needs to be added to <sid>adm´s keystore on the secondary site.

5. If the hook provider should be pre-compiled, the particular Python version that comes with SAP HANA has to be used.

BUGS
In case of any problem, please use your favourite SAP support process to open a request for the component BC-OP-LNX-SUSE. Please report any other feedback and suggestions to feedback@suse.com.

SEE ALSO
SAPHanaSR(7) , SAPHanaSR.py(7) , ocf_suse_SAPHanaTopology(7) , ocf_suse_SAPHana(7) , ocf_heartbeat_SAPInstance(7) , crm(8) , python3(8) , SAPHanaSR-manageProvider(8) ,
https://help.sap.com/docs/SAP_HANA_PLATFORM?locale=en-US
https://help.sap.com/docs/SAP_HANA_PLATFORM/6b94445c94ae495c83a19646e7c3fd56/5df2e766549a405e95de4c5d7f2efc2d.html?locale=en-US

AUTHORS
A.Briel, F.Herschel, L.Pinne.

COPYRIGHT
(c) 2022-2023 SUSE LLC
susCostOpt.py comes with ABSOLUTELY NO WARRANTY.
For details see the GNU General Public License at http://www.gnu.org/licenses/gpl.html