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:
SDAF: SAP deployment automation framework
Control plane: Common term for Resource groups Deployer and Library. Generally it is part of a permanent infrastructure in the cloud.
Deployer: Resource group providing services such as keyvault, Deployer VM and associated resources.
Deployer VM: Central point that contains SDAF installation and where the deployment is executed from. Since SUT VMs have no public IPs, this is also serving as a jump-host to reach them via SSH.
Library: Resource group providing storage for terraform state files, SAP media and private DNS zone.
Workload zone: Resource group that provides services similar to support server.
SAP Systems: Resource group containing SAP SUTs and related resources.
homedir();Returns home directory path for current user from env variable $HOME.
deployment_dir([create=>1]);create: Create directory if it does not exist.
Returns deployment directory path with job ID appended as unique identifier. Optionally it can create directory if it does not exists.
log_dir([create=>1]);create: Create directory if it does not exist.
Returns logging directory path with job ID appended as unique identifier. Optionally creates the directory.
sdaf_scripts_dir();Returns directory containing SDAF scripts.
env_variable_file();Returns full path to a file containing all required SDAF OS env variables. Sourcing this file is essential for running SDAF.
log_command_output(command=>$command, log_file=>$log_file);command: Command which output should be logged into file.
log_file: Full log file path and filename to pipe command output into.
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 fileaz_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:
_SECRET_AZURE_SDAF_APP_ID
_SECRET_AZURE_SDAF_APP_PASSWORD
_SECRET_AZURE_SDAF_TENANT_ID
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($entries);$entries: ARRAYREF of entries to be appended to variable source file
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($variable_name, $variable_value);$variable_name: Variable name
$variable_value: Variable value. Empty value is accepted as well.
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($variable_name);$variable_name: 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(
subscription_id=>$subscription_id
[, env_code=>$env_code]
[, deployer_vnet_code=>$deployer_vnet_code]
[, workload_vnet_code=>$workload_vnet_code]
[, region_code=>$region_code]
[, sap_sid=>$sap_sid]
[, sdaf_tfstate_storage_account=$sdaf_tfstate_storage_account]
[, sdaf_key_vault=>$sdaf_key_vault]
);subscription_id: Azure subscription ID
env_code: Code for SDAF deployment env. Default: 'SDAF_ENV_CODE'
deployer_vnet_code: Deployer virtual network code. Default: 'SDAF_DEPLOYER_VNET_CODE'
workload_vnet_code: Virtual network code for workload zone. Default: 'SDAF_WORKLOAD_VNET_CODE'
region_code: SDAF internal code for azure region. Default: 'SDAF_REGION_CODE'
sap_sid: SAP system ID. Default: 'SAP_SID'
sdaf_tfstate_storage_account: Storage account residing in library resource group. Location for stored tfstate files. Default 'SDAF_TFSTATE_STORAGE_ACCOUNT'
sdaf_key_vault: Key vault name inside Deployer resource group. Default '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();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_get_deployer_ip(deployer_resource_group=>$deployer_resource_group);deployer_resource_group: Deployer key vault name
Retrieves public IP of the deployer VM.
sdaf_prepare_ssh_keys(deployer_key_vault=>$deployer_key_vault);deployer_key_vault: Deployer key vault name
Retrieves public and private ssh key from DEPLOYER keyvault and sets up permissions.
az_get_ssh_key(deployer_key_vault=$deployer_key_vault, ssh_key_name=$key_name, ssh_key_filename=$ssh_key_filename);deployer_key_vault: Deployer key vault name
ssh_key_name: SSH key name residing on keyvault
ssh_key_filename: Target filename for SSH key
Retrieves SSH key from DEPLOYER keyvault.
serial_console_diag_banner($input_text);input_text: string that will be printed in uppercase surrounded by '#' to make it more visible in output
Prints a simple line 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.
get_tfvars_path(
deployment_type=>$deployment_type,
env_code=>$env_code,
region_code=>$region_code,
[vnet_code=>$vnet_code,
sap_sid=>$sap_sid]);Returns full tfvars filepath respective to deployment type.
deployment_type: Type of the deployment (workload_zone, sap_system, library... etc)
env_code: SDAF parameter for environment code (for our purpose we can use 'LAB')
region_code: SDAF parameter to choose PC region. Note SDAF is using internal abbreviations (SECE = swedencentral)
vnet_code: SDAF parameter for virtual network code. Library and deployer use different vnet than SUT env
sap_sid: SDAF parameter for sap system ID
prepare_tfvars_file(deployment_type=>$deployment_type);$deployment_type: Type of the deployment (workload_zone, sap_system, library... etc)
Downloads tfvars template files from openQA data dir and places them into correct place within SDAF repo structure. Returns full path of the tfvars file.
replace_tfvars_variables();$deployment_type: Type of the deployment (workload_zone, sap_system, library... etc)
Replaces placeholder pattern %OPENQA_VARIABLE% with corresponding OpenQA variable value. If OpenQA variable is not set, placeholder is replaced with empty value.
sdaf_execute_deployment(deployment_type=>$deployment_type [, timeout=>$timeout]);deployment_type: Type of the deployment: workload_zone or sap_system
timeout: Execution timeout. Default: 1800s.
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(deployment_type=>$deployment_type, tfvars_filename=>tfvars_filename);deployment_type: Type of the deployment: workload_zone or sap_system
tfvars_filename: Filename of tfvars file
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_repo(
[, env_code=>$env_code]
[, region_code=>$region_code]
[, workload_vnet_code=>$workload_vnet_code]
[, deployer_vnet_code=>$workload_vnet_code]
[, sap_sid=>$sap_sid]);Prepares directory structure and Clones git repository for SDAF samples and automation code.
env_code: Code for SDAF deployment env. Default: 'SDAF_ENV_CODE'
deployer_vnet_code: Deployer virtual network code. Default 'SDAF_DEPLOYER_VNET_CODE'
workload_vnet_code: Virtual network code for workload zone. Default: 'SDAF_WORKLOAD_VNET_CODE'
region_code: SDAF internal code for azure region. Default: 'SDAF_REGION_CODE'
sap_sid: SAP system ID. Default 'SAP_SID'
generate_resource_group_name(deployment_type=>$deployment_type);$deployment_type: Type of the deployment (workload_zone, sap_system, library... etc)
Returns name of the resource group for the deployment type specified by $deployment_type . Resource group pattern: SDAF-OpenQA-[deployment type]-[deployment id]-[OpenQA job id]
resource_group_exists($resource_group);$resource_group: Resource group name to check
Checks if resource group exists. Function accepts only full resource name. Croaks if command does not return true/false value.
sdaf_execute_remover(deployment_type=>$deployment_type);$deployment_type: Type of the deployment (workload_zone, sap_system)
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();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.