Merge branch 'dev' into 'master'

exchange12rocks · exchange12rocks · commit c9a285f6277d · 2019-04-11T09:28:10.000Z
Release v.2.6

See merge request fozzy-winadmins/AutomaticMaintenance!2
diff --git a/AutomaticMaintenance.psd1 b/AutomaticMaintenance.psd1
@@ -1,11 +1,12 @@
 @{
     RootModule        = 'AutomaticMaintenance.psm1'
-    ModuleVersion     = '2.5.1'
+    ModuleVersion     = '2.6'
     GUID              = '8e34abf8-40ba-4c68-8bf8-f235cd001d82'
     Author            = 'Kirill Nikolaev'
     CompanyName       = 'Fozzy Inc.'
     Copyright         = '(c) 2018 Fozzy Inc. All rights reserved.'
     PowerShellVersion = '3.0'
+    Description       = 'Helps IT engineers to establish a continuous update process in large intertangled infrastructures.'
     RequiredModules   = @(
         'PendingReboot'
         'ResourceLocker'
@@ -19,4 +20,12 @@
     )
     CmdletsToExport   = @()
     AliasesToExport   = @()
+    PrivateData       = @{
+        PSData = @{
+            Tags         = @()
+            LicenseUri   = 'https://github.com/FozzyHosting/AutomaticMaintenance/blob/master/LICENSE'
+            ProjectUri   = 'https://github.com/FozzyHosting/AutomaticMaintenance/'
+            ReleaseNotes = ''
+        }  
+    }
 }
diff --git a/Public/Invoke-InfrastructureMaintenance.ps1 b/Public/Invoke-InfrastructureMaintenance.ps1
@@ -34,7 +34,7 @@ function Invoke-InfrastructureMaintenance {
                 Write-Debug -Message 'if ($LogErrorFileContent)'
                 if ($LogErrorFileContent) {
                     $Message = ('Error log file {0} is not empty. To ignore this, set the module configuration variable $ModuleWideFailOnPreviousFailure to $false.' -f $LogErrorFilePath)
-                    PSCmdlet.ThrowTerminatingError((New-Object -TypeName 'System.Management.Automation.ErrorRecord' -ArgumentList ((New-Object -TypeName 'System.ApplicationException' -ArgumentList $Message), 'FileIsNotEmpty', [System.Management.Automation.ErrorCategory]::InvalidData, $null)))
+                    $PSCmdlet.ThrowTerminatingError((New-Object -TypeName 'System.Management.Automation.ErrorRecord' -ArgumentList ((New-Object -TypeName 'System.ApplicationException' -ArgumentList $Message), 'FileIsNotEmpty', [System.Management.Automation.ErrorCategory]::InvalidData, $null)))
                 }
             }
         }
@@ -52,40 +52,70 @@ function Invoke-InfrastructureMaintenance {
             }
         }
 
-        Write-Debug -Message '$List = Get-ComputerList'
-        $List = Get-ComputerList
-        Write-Debug -Message ('$List: ''{0}''' -f [string]$List)
-
-        Write-Debug -Message 'if ($List)'
-        if ($List) {
-            foreach ($ComputerName in $List) {
-                Write-Debug -Message ('$ComputerName = ''{0}''' -f $ComputerName)
-                Write-Debug -Message ('$LogFilePath = ''{0}'' -f ''{1}''' -f $LogFilePathTemplate, $ComputerName)
-                $LogFilePath = $LogFilePathTemplate -f $ComputerName
-                Write-Debug -Message ('$LogFilePath = ''{0}''' -f $LogFilePath)
-
-                Write-Debug -Message ('$LogScriptBlock = [scriptblock]::Create((''Write-SimpleTextLog -Path ''''{{0}}'''' -MutexName ''''{{1}}'''''' -f {0}, {1}))' -f $LogFilePath, $LogMutexName)
-                $LogScriptBlock = [scriptblock]::Create(('Write-SimpleTextLog -Path ''{0}'' -MutexName ''{1}''' -f $LogFilePath, $LogMutexName))
-                Write-Debug -Message ('$LogScriptBlock = {0}' -f [string]$LogScriptBlock)
-
-                Write-Debug -Message ('$DebugLog: ''{0}''' -f [string]$DebugLog)
-                Write-Debug -Message 'if ($DebugLog)'
-                if ($DebugLog) {
-                    Write-Debug -Message ('$CurrentDebugPreference = ''{0}''' -f $global:DebugPreference)
-                    $CurrentDebugPreference = $global:DebugPreference
-                    Write-Debug -Message '$global:DebugPreference = ''Continue'''
-                    $global:DebugPreference = 'Continue'
-                    Write-Debug -Message ('Invoke-ComputerMaintenance -ComputerName ''{0}'' 5>&1 | Split-Output -ScriptBlock {{{1}}} -Mode Debug' -f $ComputerName, $LogScriptBlock)
-                    Invoke-ComputerMaintenance -ComputerName $ComputerName 5>&1 | Split-Output -ScriptBlock $LogScriptBlock -Mode Debug
+        Write-Debug -Message '[System.Collections.ArrayList]$ProcessedComputers = @()'
+        [System.Collections.ArrayList]$ProcessedComputers = @()
+
+        Write-Debug -Message 'do while ($UnprocessedComputers)'
+        do {
+            Write-Debug -Message '[System.Collections.ArrayList]$UnprocessedComputers = @()'
+            [System.Collections.ArrayList]$UnprocessedComputers = @()
+
+            Write-Debug -Message '$List = Get-ComputerList'
+            $List = Get-ComputerList
+            Write-Debug -Message ('$List: ''{0}''' -f [string]$List)
+
+            Write-Debug -Message 'if ($List)'
+            if ($List) {
+                Write-Debug -Message 'foreach ($ComputerName in $List)'
+                foreach ($ComputerName in $List) {
+                    Write-Debug -Message ('$ProcessedComputers: ''{0}''' -f [string]$ProcessedComputers)
+                    Write-Debug -Message ('$ComputerName = ''{0}''' -f $ComputerName)
+                    Write-Debug -Message ('if ($ProcessedComputers -notcontains $ComputerName)')
+                    if ($ProcessedComputers -notcontains $ComputerName) {
+                        Write-Debug -Message ('$null = $UnprocessedComputers.Add(''{0}'')' -f $ComputerName)
+                        $null = $UnprocessedComputers.Add($ComputerName)
+                        Write-Debug -Message ('$UnprocessedComputers: ''{0}''' -f [string]$UnprocessedComputers)
+                    }
                 }
-                else {
-                    Write-Debug -Message '$CurrentDebugPreference = $null'
-                    $CurrentDebugPreference = $null
-                    Write-Debug -Message ('Invoke-ComputerMaintenance -ComputerName ''{0}''' -f $ComputerName)
-                    Invoke-ComputerMaintenance -ComputerName $ComputerName
+
+                Write-Debug -Message ('$UnprocessedComputers: ''{0}''' -f [string]$UnprocessedComputers)
+                Write-Debug -Message 'if ($UnprocessedComputers)'
+                if ($UnprocessedComputers) {
+                    Write-Debug -Message '$ComputerName = $UnprocessedComputers[0]'
+                    $ComputerName = $UnprocessedComputers[0]
+                    Write-Debug -Message ('$ComputerName = ''{0}''' -f $ComputerName)
+
+                    Write-Debug -Message ('$LogFilePath = ''{0}'' -f ''{1}''' -f $LogFilePathTemplate, $ComputerName)
+                    $LogFilePath = $LogFilePathTemplate -f $ComputerName
+                    Write-Debug -Message ('$LogFilePath = ''{0}''' -f $LogFilePath)
+
+                    Write-Debug -Message ('$LogScriptBlock = [scriptblock]::Create((''Write-SimpleTextLog -Path ''''{{0}}'''' -MutexName ''''{{1}}'''''' -f {0}, {1}))' -f $LogFilePath, $LogMutexName)
+                    $LogScriptBlock = [scriptblock]::Create(('Write-SimpleTextLog -Path ''{0}'' -MutexName ''{1}''' -f $LogFilePath, $LogMutexName))
+                    Write-Debug -Message ('$LogScriptBlock = {0}' -f [string]$LogScriptBlock)
+
+                    Write-Debug -Message ('$DebugLog: ''{0}''' -f [string]$DebugLog)
+                    Write-Debug -Message 'if ($DebugLog)'
+                    if ($DebugLog) {
+                        Write-Debug -Message ('$CurrentDebugPreference = ''{0}''' -f $global:DebugPreference)
+                        $CurrentDebugPreference = $global:DebugPreference
+                        Write-Debug -Message '$global:DebugPreference = ''Continue'''
+                        $global:DebugPreference = 'Continue'
+                        Write-Debug -Message ('Invoke-ComputerMaintenance -ComputerName ''{0}'' 5>&1 | Split-Output -ScriptBlock {{{1}}} -Mode Debug' -f $ComputerName, $LogScriptBlock)
+                        Invoke-ComputerMaintenance -ComputerName $ComputerName 5>&1 | Split-Output -ScriptBlock $LogScriptBlock -Mode Debug
+                    }
+                    else {
+                        Write-Debug -Message '$CurrentDebugPreference = $null'
+                        $CurrentDebugPreference = $null
+                        Write-Debug -Message ('Invoke-ComputerMaintenance -ComputerName ''{0}''' -f $ComputerName)
+                        Invoke-ComputerMaintenance -ComputerName $ComputerName
+                    }
+
+                    Write-Debug -Message ('$null = $ProcessedComputers.Add(''{0}'')' -f $ComputerName)
+                    $null = $ProcessedComputers.Add($ComputerName)
+                    Write-Debug -Message ('$ProcessedComputers: ''{0}''' -f [string]$ProcessedComputers)
                 }
             }
-        }
+        } while ($UnprocessedComputers)
 
         Write-Debug -Message ('EXIT TRY {0}' -f $MyInvocation.MyCommand.Name)
     }
@@ -110,5 +140,5 @@ function Invoke-InfrastructureMaintenance {
         Write-Debug -Message ('EXIT FINALLY {0}' -f $MyInvocation.MyCommand.Name)
     }
 
-    Write-Debug -Message ('EXIT {0}' -f $MyInvocation.MyCommand.Name)
+Write-Debug -Message ('EXIT {0}' -f $MyInvocation.MyCommand.Name)
 }
diff --git a/README.md b/README.md
@@ -15,6 +15,15 @@ The main function you need from this module is [**Invoke-InfrastructureMaintenan
 
 Under the hood, **Invoke-InfrastructureMaintenance** uses another function to actually perform maintenance on each host — [**Invoke-ComputerMaintenance**](docs/Invoke-ComputerMaintenance.md). If you want to use an external orchestration/configuration management system (Ansible, Puppet etc.), configure it to execute **Invoke-ComputerMaintenance**, not **Invoke-InfrastructureMaintenance**.
 
+## Update detection and installation
+**Invoke-ComputerMaintenance** uses the standard Windows Update API to detect and install updates. That means that to make updates available for a host, you have to make them available at WSUS or use direct connection to Microsoft Update. But you can exclude some updates from installation/detection:
+* Use the `UpdateInstallFilter` configuration attribute (or the `$ModuleWideInstallUpdateDefaultFilterString` module configuration variable) to specify filter for updates installation.
+* Use the `UpdateCheckFilter` configuration attribute (or the `$ModuleWideCheckUpdateDefaultFilterString` module configuration variable) to specify filter for updates detection.
+
+If the detection process (**Test-WindowsUpdateNeeded**) finds available updates, the host maintenance process will start. Otherwise, **Invoke-ComputerMaintenance** skips to the next host.
+
+There's no built-in way to install a specific update, but it is possible by leveraging step commands (see below), since you can execute custom commands and scripts there.
+
 ## Host types
 While the module can potentially support machines with various type of workloads, currently there are only two supported types:
 * **HV-SCVMM** - for stand-alone hypervisors (yes, *not* fail-over clusters) managed by SCVMM. Workload movement is provided by the [SCVMReliableMigration](https://github.com/FozzyHosting/SCVMReliableMigration) module.
@@ -85,8 +94,8 @@ There are several variables defined in the .psm1-file, which are used by the mod
 * `[System.TimeSpan]$ModuleWideInstallUpdateThreshold` - Specifies how long the module will wait for the update installation to finish.
 * `[string]$ModuleWideInstallUpdateTaskName` - The name of a Task Scheduler task which executes code to find and install updates.
 * `[string]$ModuleWideInstallUpdateTaskDescription` - The description of a Task Scheduler task which executes code to find and install updates.
-* `[string]$ModuleWideCheckUpdateDefaultFilterString` - A filter which is used to detect new updates.
-* `[string]$ModuleWideInstallUpdateDefaultFilterString` - A filter which is used during updates installation.
+* `[string]$ModuleWideCheckUpdateDefaultFilterString` - A filter which is used to detect new updates. Used if an `UpdateCheckFilter` attribute is not defined in host's configuration.
+* `[string]$ModuleWideInstallUpdateDefaultFilterString` - A filter which is used during updates installation. Used if an `UpdateInstallFilter` attribute is not defined in host's configuration.
 * `[string]$ModuleWideUpdateSearchCriteria` - Criteria for the IUpdateSearcher::Search method (https://docs.microsoft.com/en-us/windows/desktop/api/wuapi/nf-wuapi-iupdatesearcher-search)
 
 ## Loading variables from an external source
diff --git a/docs-additional/Configuration.md b/docs-additional/Configuration.md
@@ -24,8 +24,9 @@ The `Include` attribute defines a collection of objects. Each of those objects m
 
 ## Attributes
 * Name - The name of a host where you want to install updates automatically. Should be unique.
-* Type - A type of a host. Currently, acceptable values are "HV-SCVMM", "Generic".
+* Type - A type of a host. Currently, acceptable values are `HV-SCVMM`, `Generic`.
 * UpdateInstallFilter - A filter which is used to filter out unneeded updates, like preview versions etc.
+* Disabled - Settings this attribute to `True` allows you to temporary disable processing of this particular host. Useful when you need to perform some manual maintenance.
 
 The following set of attributes describes step commands (plug-ins):
 * PreClearCommands
@@ -35,7 +36,7 @@ The following set of attributes describes step commands (plug-ins):
 * TestCommands
 * FinallyCommands
 
-Each attribute is usually a name of a PowerShell script, located in a "ScriptBlocks" folder in the module's folder. See more about these commands [here](Step-Commands.md)
+Each attribute is usually a name of a PowerShell script, located in a `ScriptBlocks` folder in the module's folder. See more about these commands [here](Step-Commands.md)
 
 ### Workload-specific attributes
 #### HV-SCVMM
diff --git a/docs-additional/Step-Commands.md b/docs-additional/Step-Commands.md
@@ -1,14 +1,18 @@
-# Plug-ins (Step Commands)
-There are several steps defined (in the order of execute):
+# Step Commands (Plug-ins)
+Step commands are scripts which can be run at steps executed throughout the maintenance process, as defined below. Usually you would like to create a PowerShell script, put it into the `ScriptBlocks` folder, then insert the name of the script into an appropriate attribute in the main configuration file or in the templates file (or in both, if your config requires so - it's completely up to you).
+
+Step commands are good in letting other systems know that a host is about to reboot or it has returned back into service, but you of course can find them useful in other ways as well.
+
+There are several steps defined (in the order of execution):
 * Pre-Clear (PreClearCommands) - this step executes before workload is removed from the host. It's a good step to execute a command which will prevent further workload placing on the host.
 * Post-Clear (PostClearCommands) - this step executes right after workload is removed from the host. At this step you can disable monitoring, for example.
 * Test (TestCommands) - this step executes after the host is back after reboot. Its purpose is to run commands which ensure that it is safe to move workload back to the host.
 * Pre-Restore (PreRestoreCommands) - executes before moving workload back to the host. We recommend to enable monitoring here,if you disabled it at "Post-Clear".
 * Post-Restore (PostRestoreCommands) - executes when workload moving back has completed. If you prevented workload placement earlier, you can enable it now.
-* Finally (FinallyCommands) - this step always executes at the end of the process. If an error happens, it will execute after error processing.
+* Finally (FinallyCommands) - this step always executes at the end of the process. If an error happens, it will execute after error processing (The whole function is in a `try` block and `FinallyCommands` run at its `finally` section).
 
 ## Requirements
-Executable files (usually PowerShell scripts), specified in those attributes must accept two following parameters:
+Executable files (usually, PowerShell scripts), specified in those attributes must be in the `ScriptBlocks` folder and must accept two following parameters:
 * ComputerName - A string, containing a name of a computer which is in progress right now. Mandatory.
 * Variables - A collection of `System.Management.Automation.PSVariable` objects. Might be empty, but unlikely.
 
