Add shell check comments, Update function descriptions

Add shellcheck comments for warnings that can be safely ignored.
Improve function readability by formatting them all in the same style.

Author: s-fairchild

pkg/deploy/generator/scripts/gatewayVMSS.sh

@@ -147,8 +147,11 @@ RPIMAGE='$rpimage'"
     reboot_vm
 }
 
+# export AZURE_CLOUD_NAME="${AZURECLOUDNAME:?"Failed to carry over variables"}"
 export AZURE_CLOUD_NAME="${AZURECLOUDNAME:?"Failed to carry over variables"}"
 
+# util="util.sh"
+#
 # util.sh does not exist when deployed to VMSS via VMSS extensions
 # Provides shellcheck definitions
 util="util.sh"

pkg/deploy/generator/scripts/rpVMSS.sh

@@ -8,10 +8,12 @@ main() {
     # transaction attempt retry time in seconds
     # shellcheck disable=SC2034
     local -ri retry_wait_time=30
-    local -ri pkg_retry_count=60
 
     create_required_dirs
+
     configure_sshd
+
+    local -ri pkg_retry_count=60
     configure_rpm_repos retry_wait_time \
                         "$pkg_retry_count"
 
@@ -53,10 +55,16 @@ main() {
     # shellcheck disable=SC2153 disable=SC2034
     local -r mdmimage="${RPIMAGE%%/*}/${MDMIMAGE#*/}"
     local -r rpimage="$RPIMAGE"
+
+    # shellcheck disable=SC2034
     local -r miseimage="${RPIMAGE%%/*}/${MISEIMAGE#*/}"
+
+    # shellcheck disable=SC2034
     local -r otelimage="$OTELIMAGE"
+
     # shellcheck disable=SC2034
     local -r fluentbit_image="$FLUENTBITIMAGE"
+
     # shellcheck disable=SC2034
     local -rA aro_images=(
         ["mdm"]="mdmimage"
@@ -214,11 +222,15 @@ MSI_RP_ENDPOINT='$MSIRPENDPOINT'
     reboot_vm
 }
 
+# export AZURE_CLOUD_NAME="${AZURECLOUDNAME:?"Failed to carry over variables"}"
+#
 # This variable is used by az-cli
 # It's assumed that if this variable hasn't been carried over, that others are also not present, so we fail early by returning an error
 # This was mostly helpful when testing on a development VM, but is still applicable
 export AZURE_CLOUD_NAME="${AZURECLOUDNAME:?"Failed to carry over variables"}"
 
+# util="util.sh"
+#
 # util.sh does not exist when deployed to VMSS via VMSS extensions
 # Provides shellcheck definitions
 util="util.sh"

pkg/deploy/generator/scripts/util-common.sh

@@ -67,29 +67,36 @@ xtrace_set() {
     (( XTRACE_IS_SET == XTRACE_UNSET )) && set -x
 }
 
-# log is a wrapper for echo that includes the function name
-# Args
-# 1) msg - string
-# 2) stack_level - int; optional, defaults to the function at the bottom of the call stack
+# log()
+#
+# Wrapper for echo that includes the function name
+# args:
+#   1) msg - string
+#   2) stack_level - int; optional
+#       * defaults to the function at the bottom of the call stack
 log() {
     local -r msg="${1:-"log message is empty"}"
     local -r stack_level="${2:-1}"
     echo "${FUNCNAME[${stack_level}]}: ${msg}"
 }
 
-# abort is a wrapper for log that exits with an error code
+# abort()
+#
+# Wrapper for log that exits with an error code
 abort() {
     local -ri origin_stacklevel=2
     log "${1}" "$origin_stacklevel"
     log "Exiting"
     exit 1
 }
 
-# write_file
-# Args
-# 1) filename - string
-# 2) file_contents - string
-# 3) clobber - boolean; optional - defaults to false
+# write_file()
+#
+# args:
+#   1) filename - string
+#   2) file_contents - string
+#   3) clobber - boolean; optional
+#       * defaults to false
 write_file() {
     local -n filename="$1"
     local -n file_contents="$2"
@@ -104,11 +111,16 @@ write_file() {
     fi
 }
 
-# retry Adding retry logic to yum commands in order to avoid stalling out on resource locks
+# retry()
+#
+# Add retry logic to commands in order to avoid stalling out on resource locks
 # args:
-# 1) cmd_retry - nameref, array; Command and arguement(s) to retry
-# 2) wait_time - nameref, integer; Time to wait before retrying command
-# 3) retries - integer, optional; Ammount of times to retry command, defaults to 5
+#   1) cmd_retry - nameref, array
+#       * Command and argument(s) to retry
+#   2) wait_time - nameref, integer
+#       * Time to wait before retrying command
+#   3) retries - integer, optional
+#       * Amount of times to retry command, defaults to 5
 retry() {
     local -n cmd_retry="$1"
     local -n wait_time="$2"
@@ -127,9 +139,11 @@ retry() {
     abort "${cmd_retry[*]} failed after #$retries attempts"
 }
 
-# verify_role
+# verify_role()
+#
 # args:
-# 1) test_role - nameref; role being verified
+#   1) test_role - nameref
+#       * role being verified
 verify_role() {
     local -n test_role="$1"
 
@@ -141,11 +155,15 @@ verify_role() {
     fi
 }
 
-# get_keyvault_suffix
+# get_keyvault_suffix()
+#
 # args:
-# 1) rl - nameref, string; role to get short role for
-# 2) kv_suffix - nameref, string; short role will be assigned to this nameref
-# 3) sec_prefix - nameref, string; keyvault certificate prefix will be assigned to this nameref
+#   1) rl - nameref, string;
+#       * role to get short role for
+#   2) kv_suffix - nameref, string;
+#       * short role will be assigned to this nameref
+#   3) sec_prefix - nameref, string;
+#       * keyvault certificate prefix will be assigned to this nameref
 get_keyvault_suffix() {
     local -n rl="$1"
     local -n kv_suffix="$2"
@@ -169,9 +187,11 @@ get_keyvault_suffix() {
     esac
 }
 
+# reboot_vm()
+#
 # reboot_vm restores calls shutdown -r in a subshell
-# Reboots should scheduled after all VM extensions have had time to complete
-# Reference: https://learn.microsoft.com/en-us/azure/virtual-machines/extensions/custom-script-linux#tips
+#   * Reboots should scheduled after all VM extensions have had time to complete
+#   * Reference: https://learn.microsoft.com/en-us/azure/virtual-machines/extensions/custom-script-linux#tips
 reboot_vm() {
     log "starting"
 

pkg/deploy/generator/scripts/util-packages.sh

@@ -1,6 +1,7 @@
 #!/bin/bash
 # Repository and package management related functions
 
+# configure_repo_mariner_extended()
 configure_repo_mariner_extended() {
     local -r extended_repo_config="https://packages.microsoft.com/cbl-mariner/2.0/prod/extended/x86_64/config.repo"
     curl -sSL "$extended_repo_config" -o /etc/yum.repos.d/mariner-extended.repo
@@ -19,21 +20,28 @@ configure_repo_mariner_extended() {
 }
 
 # configure_rpm_repos
+#
 # New repositories should be added in their own functions, and called here
 # args:
-# 1) wait_time - nameref, integer; Time to wait before retrying command
-# 2) retries - integer, optional; Amount of times to retry command, defaults to 5
+#   1) wait_time - nameref, integer
+#       * Time to wait before retrying command
+#   2) retries - integer, optional
+#       * Amount of times to retry command, defaults to 5
 configure_rpm_repos() {
     log "starting"
 
     configure_repo_mariner_extended "$1" "${2:-1}"
 }
 
 # dnf_install_pkgs
+#
 # args:
-# 1) pkgs - nameref, string array; Packages to be installed
-# 2) wait_time - nameref, integer; Time to wait before retrying command
-# 3) retries - integer, optional; Amount of times to retry command, defaults to 5
+#   1) pkgs - nameref, string array
+#       * Packages to be installed
+#   2) wait_time - nameref, integer
+#       * Time to wait before retrying command
+#   3) retries - integer, optional
+#       * Amount of times to retry command, defaults to 5
 dnf_install_pkgs() {
     local -n pkgs="$1"
     log "starting"
@@ -55,11 +63,15 @@ dnf_install_pkgs() {
 
 
 # dnf_update_pkgs
+#
 # args:
-# 1) excludes - nameref, string array, optional; Packages to exclude from updating
-#       Each index must be prefixed with -x 
-# 2) wait_time - nameref, integer; Time to wait before retrying command
-# 3) retries - integer, optional; Ammount of times to retry command, defaults to 5
+#   1) excludes - nameref, string array, optional
+#       * Packages to exclude from updating
+#       * Each index must be prefixed with -x 
+#   2) wait_time - nameref, integer
+#       * Time to wait before retrying command
+#   3) retries - integer, optional
+#       * Ammount of times to retry command, defaults to 5
 dnf_update_pkgs() {
     local -n excludes="${1:-empty_str}"
     log "starting"
@@ -87,9 +99,12 @@ dnf_update_pkgs() {
 }
 
 # rpm_import_keys
+#
 # args:
-# 1) keys - nameref, string array; rpm keys to be imported
-# 2) wait_time - nameref, integer; Time to wait before retrying command
+#   1) keys - nameref, string array
+#       * rpm keys to be imported
+#   2) wait_time - nameref, integer
+#       * Time to wait before retrying command
 rpm_import_keys() {
     local -n keys="$1"
     log "starting"
@@ -112,6 +127,8 @@ rpm_import_keys() {
     done
 }
 
+# util_common="util-common.sh"
+#
 # util-common.sh does not exist when deployed to VMSS via VMSS extensions
 # Provides shellcheck definitions
 util_common="util-common.sh"