You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
@@ -16,7 +18,9 @@ The main function you need from this module is [**Invoke-InfrastructureMaintenan
16
18
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**.
17
19
18
20
## Update detection and installation
21
+
19
22
**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:
23
+
20
24
* Use the `UpdateInstallFilter` configuration attribute (or the `$ModuleWideInstallUpdateDefaultFilterString` module configuration variable) to specify filter for updates installation.
21
25
* Use the `UpdateCheckFilter` configuration attribute (or the `$ModuleWideCheckUpdateDefaultFilterString` module configuration variable) to specify filter for updates detection.
22
26
@@ -25,7 +29,9 @@ If the detection process (**Test-WindowsUpdateNeeded**) finds available updates,
25
29
There's no built-in way to install a specific update, but it is possible by leveraging plug-ins (see below), since you can execute custom commands and scripts there.
26
30
27
31
## Host types
32
+
28
33
While the module can potentially support machines with various type of workloads, currently there are only three supported types:
34
+
29
35
***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.
30
36
***HV-Vanilla** - for stand-alone hypervisors. Workload movement is provided by the [HVVMReliableMigration](https://github.com/FozzyHosting/HVVMReliableMigration) module.
31
37
***Generic** - hosts of this type do not need any specific actions to move workload and the only purpose to perform maintenance on them, using this module, is to prevent a situation when all hosts supporting a service are down at the same time.
@@ -35,42 +41,53 @@ Note, that failover cluster support was never the goal while developing the modu
35
41
The module does not specify type-specific modules as requirements, since you might use it for one type of hosts but not for another. Just bear in mind that you still will need those modules to service particular types of hosts.
36
42
37
43
## Configuration
44
+
38
45
The module's main configuration file `AutomaticMaintenance-Hosts.json` contains a list of hosts to process. Read more about the configuration [here](docs-additional/Configuration.md).
39
46
40
47
## Plug-ins
48
+
41
49
You can run your custom scripts in between of the maintenance steps specified above. You can even pass variables from one of them to another!
42
50
Read more about this awesome concept [here](docs-additional/Plug-ins.md).
43
51
44
52
## Error processing
53
+
45
54
All the module's functions but **Invoke-InfrastructureMaintenance** process errors by raising a terminating exception. **Invoke-InfrastructureMaintenance** writes an error message and a stack trace into an error log (see below).
46
55
47
56
By default, if you run **Invoke-InfrastructureMaintenance** and there is an error log from a previous crash, it will stop. You can configure this behaviour with the `$ModuleWideFailOnPreviousFailure` variable.
* An error log file (`AutomaticMaintenance-Error.log`).
57
69
* Debug log files: Invoke-ComputerMaintenance function will write all executed commands into separate log-files - one per host (`AutomaticMaintenance-<Host Name>-<Current Date>.log`).
58
70
* Maintenance track log file. Its main purpose is to let you keep a track of when which host has been maintained (`AutomaticMaintenance-HostMaintenanceLog.log`).
59
71
60
72
## Dependencies
73
+
61
74
The module depends on the following modules:
75
+
62
76
*[PendingReboot](https://github.com/bcwilhite/PendingReboot) - To detect if a reboot is required after updates installation.
63
77
*[ResourceLocker](https://github.com/FozzyHosting/ResourceLocker) - To let other automation know that the host is about to reboot. Also it is used to prevent reboots while the host is used by some other functions/scripts.
64
78
*[SimpleTextLogger](https://github.com/FozzyHosting/SimpleTextLogger) - To log actions and errors.
65
79
*[SplitOutput](https://github.com/exchange12rocks/SplitOutput) - To log debug output.
66
80
67
81
### HV-SCVMM
82
+
68
83
For hosts of the `HV-SCVMM` type, the module uses [SCVMReliableMigration](https://github.com/FozzyHosting/SCVMReliableMigration) to migrate workload between them.
69
84
70
85
### HV-Vanilla
86
+
71
87
For hosts of the `HV-Vanilla` type, the module uses [HVVMReliableMigration](https://github.com/FozzyHosting/HVVMReliableMigration) to migrate workload.
72
88
73
89
## Module-wide variables
90
+
74
91
There are several variables defined in the .psm1-file, which are used by the module's functions as default values for parameters:
75
92
76
93
*`[string]$LogFileFolderPath` - Specifies the path to a folder where debug and error log files will be placed.
@@ -105,22 +122,31 @@ There are several variables defined in the .psm1-file, which are used by the mod
105
122
*`[string]$ModuleWideInstallUpdateTaskDescription` - The description of a Task Scheduler task which executes code to find and install updates.
106
123
*`[string]$ModuleWideCheckUpdateDefaultFilterString` - A filter which is used to detect new updates. Used if an `UpdateCheckFilter` attribute is not defined in host's configuration.
107
124
*`[string]$ModuleWideInstallUpdateDefaultFilterString` - A filter which is used during updates installation. Used if an `UpdateInstallFilter` attribute is not defined in host's configuration.
108
-
*`[string]$ModuleWideUpdateSearchCriteria` - Criteria for the IUpdateSearcher::Search method (https://docs.microsoft.com/en-us/windows/desktop/api/wuapi/nf-wuapi-iupdatesearcher-search)
125
+
*`[string]$ModuleWideUpdateSearchCriteria` - Criteria for the IUpdateSearcher::Search method (<https://docs.microsoft.com/en-us/windows/desktop/api/wuapi/nf-wuapi-iupdatesearcher-search>)
109
126
110
127
*`[bool]$ModuleWideHVVanillaPutInASubfolder` - When set to `$true` (default), places vanilla Hyper-V virtual machines in subfolders, named as VMs themselves, therefore mimicking SCVMM behavior. Requires access to WinRM on the target computer and access to the Win32_Directory WMI class.
111
128
112
129
## Loading variables from an external source
130
+
113
131
All module-wide variables can be redefined with a `Config.ps1` file, located in the module's root folder. Just put variable definitions in there as you would do with any other PowerShell script. You may find an example of a config file `Config-Example.ps1` in the module's root folder.
114
132
115
133
## Limitations
134
+
116
135
* Currently, all hosts should be available by all of the following protocols: RPC, WinRM, SMB.
117
136
* %SystemRoot%\system32\dllhost.exe should be able to accept network connections to RPC Dynamic ports not only as a service, but as an ordinary process as well.
The module's configuration consists of two files located in the module's folder: `AutomaticMaintenance-Hosts.json` and `AutomaticMaintenance-Templates.json`
3
4
4
5
## AutomaticMaintenance-Hosts.json
6
+
5
7
The main file where you should put all hosts which you want to maintain.
6
8
7
9
Please take a look at [AutomaticMaintenance-Hosts-Example.json](../AutomaticMaintenance-Hosts-Example.json) for examples on how to build this file.
8
10
9
11
## AutomaticMaintenance-Templates.json
12
+
10
13
This file allows you to build your configuration more efficiently by introducing a concept of templates
11
14
You don't HAVE to use templates: if you don't like them, just describe each host separately in a hosts configuration file.
12
15
13
16
Please take a look at [AutomaticMaintenance-Templates-Example.json](../AutomaticMaintenance-Templates-Example.json) for examples on how to build this file.
14
17
15
18
Each template must have at least two attributes:
19
+
16
20
* Name - The name of a template. Should be unique.
17
21
* Properties - An array of properties to apply to hosts, which use this template.
18
22
19
23
### Template including
24
+
20
25
You can include templates into each other. Use an attribute `Include` for that.
21
26
The `Include` attribute defines a collection of objects. Each of those objects must have two following attributes:
27
+
22
28
* Name - The name of a template from which the current template should inherit host properties.
23
29
* Priority - Used to resolve conflicts if you include several templates into one.
24
30
25
31
## Attributes
32
+
26
33
* Name - The name of a host where you want to install updates automatically. Should be unique.
27
34
* Type - A type of a host. Currently, the acceptable values are `HV-SCVMM`, `HV-Vanilla`, `Generic`.
28
35
* UpdateInstallFilter - A filter which is used to filter out unneeded updates, like preview versions etc.
29
36
* 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.
30
37
31
38
The following set of attributes describes plug-ins:
39
+
32
40
* PreClearCommands
33
41
* PostClearCommands
34
42
* PreRestoreCommands
@@ -39,110 +47,111 @@ The following set of attributes describes plug-ins:
39
47
Each attribute is usually a name of a PowerShell script, located in the `$ModuleWideScriptBlocksFolderPath` folder in the module's folder. See more about these commands [here](Plug-ins.md)
40
48
41
49
### Workload-specific attributes
50
+
42
51
#### HV-SCVMM
52
+
43
53
* VMMServerName - A name of a VMM server which manages the current host.
44
54
* Workload - Defines a container with workload objects which describe how to migrate virtual machines before host maintenance.
45
55
46
56
Workload objects have the following attributes:
57
+
47
58
* Path - Path where VM's configuration is located.
48
59
* DestinationName - Destination host's name where to move virtual machines.
49
60
* DestinationPath - Local path on the destination host.
50
61
* Filter - Defines a filter which will be used to pick VMs from the source host. For example, if you wish for some VMs not to mirate, but stay at the source host during maintenance, you can filter them out here.
51
62
52
63
#### HV-Vanilla
64
+
53
65
Generally, the same as `HV-SCVMM`, just without the `VMMServerName` attribute.
66
+
54
67
* PutInASubfolder - When set to `true`, places vanilla Hyper-V virtual machines in subfolders, named as VMs themselves, therefore mimicking SCVMM behavior. Can be set on both the host and workload levels. When defined on the workload level, rewrites the value defined on the host level. If the attribute is not defined in host configuration, the default value (`$ModuleWideHVVanillaPutInASubfolder`) is used.
55
68
56
69
## Configuration testing
70
+
57
71
The module exposes the **Get-ComputerMaintenanceConfiguration** function to retrieve a resulting configuration for a host. This function is used by the module itself to build host's configuration. Use it to test your configuration files before deploying them to production.
58
72
59
73
To review the resulting configuration from the `AutomaticMaintenance-Hosts-Example.json` and `AutomaticMaintenance-Templates-Example.json` files, remove example suffixes from their names and load the module into a current PowerShell session. Then run **Get-ComputerMaintenanceConfiguration**, specifying different computer names. Here's what you should get (the output here is sorted to improve readability):
SRV02 also uses Example-Template, but on the host level, there's a new attribute defined: `MyCustomAttribute`. The attribute neatly merged with the resulting configuration.
SRV03 is a stand-alone Hyper-V host, that's why it uses `Example-Template2`, which describes how to maintain Hyper-V hosts in this example infrastructure.
114
125
Note, that `Example-Template2` does not have plug-ins defined, but the template itself inherits properties from `Example-Template`, that's why we see all those attributes in the configuration. This also gives us `UpdateInstallFilter`.
Similar to SRV03, but has `MyCustomAttribute` defined at the host level. Also note that the `PostRestoreCommands` property is empty because at the host level it is also empty — you can redefine attributes at any level. The `Workload` property is redefined as well.
0 commit comments