lib/sles4sap/sap_deployment_automation_framework/deployment.pm

SYNOPSIS

Library with common functions for Microsoft SDAF deployment automation. Documentation can be found on the projects official website

Github repositories: Automation scripts Sample configurations

Basic terminology:

log_command_output

log_command_output(command=>$command, log_file=>$log_file);

Using 'tee' to redirect command output into log does not return code for executed command, but execution of 'tee' itself. This function transforms given command so the RC reflects exit code of the command itself instead of 'tee'. Function returns only string with transformed command, nothing is being executed.

Command structure: "(command_to_execute 2>$1 | tee /log/file.log; exit ${PIPESTATUS[0]})"

'exit ${PIPESTATUS[0]}' - returns 'command_to_execute' return code instead of one from 'tee'
(...) - puts everything into subshell to prevent 'exit' logging out of current shell
tee - writes output also into the log file

az_login

az_login();

Logs into azure account using SPN credentials. Those are not typed directly into the command but using OS env variables. To avoid exposure of credentials in serial console, there is a special temporary file used which contains required variables.

SPN credentials are defined by secret OpenQA parameters:

SDAF needs SPN credentials with special permissions. Check link below for details. https://learn.microsoft.com/en-us/azure/sap/automation/deploy-control-plane?tabs=linux#prepare-the-deployment-credentials

create_sdaf_os_var_file

create_sdaf_os_var_file($entries);

Creates a simple file with bash env variables and uploads it to the target host without revealing content in serial console. File is sourced afterwards. For detailed variable description check : https://learn.microsoft.com/en-us/azure/sap/automation/naming

set_os_variable

set_os_variable($variable_name, $variable_value);

Adds or replaces existing OS env variable value in env variable file (see function 'set_common_sdaf_os_env()'). File is sourced afterwards to load the value. Croaks with incorrect usage.

WARNING: This is executed via 'assert_script_run' therefore output will be visible in logs

get_os_variable

get_os_variable($variable_name);

Returns value of requested OS env variable name. Variable is acquired using 'echo' command and is visible in serial terminal output. Keep in mind, this variable is only active until logout.

set_common_sdaf_os_env

set_common_sdaf_os_env(
    subscription_id=>$subscription_id
    [, env_code=>$env_code]
    [, deployer_vnet_code=>$deployer_vnet_code]
    [, sdaf_region_code=>$sdaf_region_code]
    [, sap_sid=>$sap_sid]
    [, sdaf_tfstate_storage_account=$sdaf_tfstate_storage_account]
    [, sdaf_key_vault=>$sdaf_key_vault]
);

Creates a file with common OS env variables required to run SDAF. File is sourced afterwards to make the values active. Keep in mind that values are lost after user logout (for example after disconnecting console redirection). You can load them back using load_os_env_variables() function OS env variables are core of how to execute SDAF and many are used even internally by SDAF code. For detailed variable description check : https://learn.microsoft.com/en-us/azure/sap/automation/naming

load_os_env_variables

load_os_env_variables();

Sources file containing OS env variables required for executing SDAF. Currently deployer VM is a permanent installation with all tests using it. Therefore using .bashrc file for storing variables is not an option since tests would constantly overwrite variables between each other.

sdaf_ssh_key_from_keyvault

sdaf_ssh_key_from_keyvault(key_vault=>$key_vault [, target_file=>'/path/to/glory/and_happiness']);

Retrieves public and private ssh key from specified keyvault and sets up permissions.

serial_console_diag_banner

serial_console_diag_banner($input_text);

Prints a banner in serial console that highlights a point in output to make it more readable. Can be used for example to mark start and end of a function or a point in test so it is easier to find while debugging. Below is an example of the printed banner: # # $input_text #

sdaf_execute_deployment

sdaf_execute_deployment(deployment_type=>$deployment_type [, timeout=>$timeout]);

Executes SDAF deployment according to the type specified. Croaks with unsupported deployment type, dies upon command failure. https://learn.microsoft.com/en-us/azure/sap/automation/deploy-workload-zone?tabs=linux#deploy-the-sap-workload-zone https://learn.microsoft.com/en-us/azure/sap/automation/tutorial#deploy-the-sap-system-infrastructure

get_sdaf_deployment_command

get_sdaf_deployment_command(deployment_type=>$deployment_type, tfvars_filename=>tfvars_filename);

Function composes SDAF deployment script command for sap_system or workload_zone according to official documentation. Although the documentation uses env OS variable references in the command, function replaces them with actual values. This is done for better debugging and logging transparency. Only sensitive values are hidden by using references.

prepare_sdaf_project

prepare_sdaf_project(
     [, env_code=>$env_code]
     [, sdaf_region_code=>$sdaf_region_code]
     [, deployer_vnet_code=>$deployer_vnet_code]
     [, sap_sid=>$sap_sid]);

Prepares directory structure and Clones git repository for SDAF samples and automation code.

resource_group_exists

resource_group_exists($resource_group);

Checks if resource group exists. Function accepts only full resource name. Croaks if command does not return true/false value.

sdaf_execute_remover

sdaf_execute_remover(deployment_type=>$deployment_type);

Uses remover.sh script which is part of the SDAF project. This script can be used only on workload zone or sap system. Control plane and library have separate removal script, but are currently part of permanent setup and should not be destroyed. Returns RC to allow additional cleanup tasks required even after script failure. https://learn.microsoft.com/en-us/azure/sap/automation/bash/remover

sdaf_cleanup

sdaf_cleanup();

Performs full cleanup routine for sap systems and workload zone by executing SDAF remover.sh file. Deletes all files related to test run on deployer VM, even in case remover script fails. Resource groups need to be deleted manually in case of failure.

sdaf_execute_playbook

sdaf_execute_playbook(
    playbook_filename=>'playbook_04_00_01_db_ha.yaml',
    sdaf_config_root_dir=>'/path/to/joy/and/happiness/'
    sap_sid=>'ABC',
    timeout=>'42',
    verbosity_level=>'3'
    );

Execute playbook specified by playbook_filename and record command output in separate log file. Verbosity level of ansible-playbook is controlled by openQA parameter SDAF_ANSIBLE_VERBOSITY_LEVEL. If undefined, it will use standard output without adding any -v flag. See function sdaf_execute_playbook for details.

sdaf_ansible_verbosity_level

sdaf_ansible_verbosity_level($verbosity_level);

Returns string that is to be used as verbosity parameter -v for 'ansible-playbook' command. This is controlled by positional argument $verbosity_level. Values can specify verbosity level using integer up to 6 (max supported by ansible) or just set to anything equal to 'true' which will default to -vvvv. Value -vvvv should be enough to debug network connection problems according to ansible documentation: https://docs.ansible.com/ansible/latest/cli/ansible-playbook.html#cmdoption-ansible-playbook-v

ansible_hanasr_show_status

ansible_hanasr_show_status(sdaf_config_root_dir=>'/some/path' [, sap_sid=>'CAT']);

Display simple command outputs from all DB hosts using ansible command.