Merge pull request #243 from DecoyJoe/feature/improve-cinc-support

Author: johnmccrae

README.md

@@ -29,23 +29,23 @@ For systems where the init system will not properly handle starting the service
 
 ### Updating Windows Nodes
 
-On Windows, a one time scheduled task `Chef_upgrade` is created in combination with a PowerShell-based upgrade script and the downloaded [Handle](https://docs.microsoft.com/en-us/sysinternals/downloads/handle) tool. When the Chef_upgrade scheduled task runs, it executes the PowerShell upgrade script, which first determines whether it can successfully stop any existing Chef Infra Client service and associated Ruby processes, since the MSI Installer will fail if there is a running Chef Infra Client service or ruby.exe process. If it cannot it will sleep for one minute and try again up to five times. If after five tries it still hasn't been successful it modifies the `Chef_upgrade` scheduled task to run 10 minutes in the future to try the process again. This eliminates the situation where the scheduled task fails and the Chef Infra Client is no longer configured to run automatically (since the service has been stopped), which in large environments is costly to recover from (requiring reboots of many servers).
+On Windows, a one time scheduled task `Chef_upgrade` is created in combination with a PowerShell-based upgrade script and the downloaded [Handle](https://docs.microsoft.com/en-us/sysinternals/downloads/handle) tool. After the resource stages everything for the upgrade it will terminate the client execution with exit code `213`, then the `Chef_upgrade` scheduled task will execute after `upgrade_delay` seconds (defaults to 60). The scheduled task executes the PowerShell upgrade script, which first determines whether it can successfully stop any existing Chef Infra Client service and associated Ruby processes, since the MSI Installer will fail if there is a running Chef Infra Client service or ruby.exe process. If it cannot it will sleep for one minute and try again up to five times. If after five tries it still hasn't been successful it modifies the `Chef_upgrade` scheduled task to run 10 minutes in the future to try the process again. This eliminates the situation where the scheduled task fails and the Chef Infra Client is no longer configured to run automatically (since the service has been stopped), which in large environments is costly to recover from (requiring reboots of many servers).
 
-The PowerShell upgrade script then moves the current installation to a staging directory and that clears the way for the newer installer to run. Any existing file handles to the old installation folder are forcibly removed and the Eventlog service will be restarted immediately prior to the new installation to release any open file locks. After installation, a log file from the upgrade can be found at `c:\opscode\chef_upgrade.log` until the next Chef Infra Client run where it will be cleaned up along with the backup folder. Upon successful installation the `Chef_upgrade` scheduled task is deleted.
+The PowerShell upgrade script then moves the current installation to a `chef.upgrade` staging directory and that clears the way for the newer installer to run. Any existing file handles to the old installation folder are forcibly removed and the Eventlog service will be restarted immediately prior to the new installation to release any open file locks. After installation, a log file from the upgrade can be found at `c:\opscode\chef_upgrade.log` until the next Chef Infra Client run where it will be cleaned up along with the backup folder. Upon successful installation the `Chef_upgrade` scheduled task is deleted.
 
-On Windows, the recommended `post_install_action` is `exec` instead of `kill` if you intend to run Chef Infra Client periodically. In `chef_client_updater` versions `>= 3.1.0` and `<= 3.2.9`, the updater resource by default started a new Chef Infra Client run after upgrading. Newer versions simply run `chef-client` only if `post_install_action` is set to `exec`. To run a custom other PowerShell command after-upgrade, define `post_install_action` `exec` and define your custom command in `exec_command`
+On Windows the only supported `post_install_action` is `kill` (the property will be forced to `kill` if given `exec` and platform is Windows) because the Chef Infra Client process must be terminated before the `Chef_upgrade` scheduled task starts in order to release all open file locks by the client, otherwise the upgrade will fail with file-in-use errors.
 
 #### Running Chef Infra Client as a Scheduled Task
 
 If you run as a scheduled task, then this will work smoothly. The path to the newly installed Chef Infra Client will be the same and the scheduled task will launch it. Part of this resource's job on the next run is to make sure the staging directory with the older client is removed.
 
 #### Running Chef Infra Client As A Windows Service
 
-If you run Chef Infra Client as a service, things get a tiny bit more complicated. When the new installer runs, the service is removed. This isn't a big deal if you've got the chef-client cookbook set to configure the Windows service. If that is the case, define `post_install_action` `exec` and the Chef-run triggered after the upgrade will take care of installing the service. Alternatively you can migrate to running Chef Infra Client as a scheduled task as described below.
+If you run Chef Infra Client as a service, things get a tiny bit more complicated because when the new installer runs, the service is removed. It's recommended you migrate to running Chef Infra Client as a scheduled task as described below.
 
 #### Migrating from Running Chef Infra Client as a Windows Service to Running as a Scheduled Task During the Upgrade
 
-If you run Chef Infra Client as a service, but want to upgrade to a version of the client with an MSI unstaller that supports running as a scheduled task (any Chef Infra Client >= 12.18) it is now possible with the `install_command_options` property (added in version 3.8.0 of the chef_client_updater cookbook). This property accepts a Hash of key/value pairs, with {daemon: 'task'} the necessary pair to notify the MSI Installer to install Chef Infra Client as a scheduled task.
+If you run Chef Infra Client as a service, but want to upgrade to a version of the client with an MSI unstaller that supports running as a scheduled task (any Chef Infra Client >= 12.18) it is now possible with the `install_command_options` property (added in version 3.8.0 of the chef_client_updater cookbook). This property accepts a Hash of key/value pairs, with `{daemon: 'task'}` being the necessary pair to notify the MSI Installer to install Chef Infra Client as a scheduled task.
 
 ### Upgrading from Chef Infra Client 11
 
@@ -94,19 +94,21 @@ Installs the mixlib-install/mixlib-install gems and upgrades the Chef Infra Clie
 #### properties
 
 - `channel` - The chef channel you fetch the Chef Infra Client from. `stable` contains all officially released Chef Infra Client builds where as `current` contains unreleased builds. Default: `stable`
-- `prevent_downgrade` - Don't allow this cookbook to downgrade the Chef Infra Client version. Default: false
-- `version` - The version of the Chef Infra Client to install. Default :latest
-- `post_install_action` - After installing the Chef Infra Client what should we do. `exec` to exec the new client or `kill` to kill the client and rely on the init system to start up the new version. Default: `kill`
+- `prevent_downgrade` - Don't allow this cookbook to downgrade the Chef Infra Client version. Default: `false`
+- `version` - The version of the Chef Infra Client to install. Default `:latest`
+- `post_install_action` - After installing the Chef Infra Client what should we do. `exec` to exec the new client or `kill` to kill the client and rely on the init system to start up the new version. On Windows only `kill` is supported. Default: `kill`
 - `exec_command` - The chef-client command. default: $PROGRAM_NAME.split(' ').first. You can also enter a custom post-action command.
-- `exec_args` - An array of arguments to exec the Chef Infra Client with. default: ARGV
+- `exec_args` - An array of arguments to exec the Chef Infra Client with. Default: `ARGV`
 - `download_url_override` - The direct URL for the Chef Infra Client package.
 - `checksum` - The SHA-256 checksum of the Chef Infra Client package from the direct URL.
-- `install_timeout` - The install timeout for non-windows systems. The default is 600, slow machines may need to extend this.
-- `upgrade_delay` - The delay in seconds before the scheduled task to upgrade Chef Infra Client runs on windows. default: 61. Lowering this limit is not recommended.
-- `product_name` - The name of the product to upgrade. This can be `chef` or `chefdk` default: chef
-- 'install_command_options' - A Hash of additional options that will be passed to the Mixlib::Install instance responsible for installing the given product_name. To install Chef Infra Client as a scheduled task on windows, one can pass {daemon: 'task'}. Default: {}
-- `rubygems_url` - The location to source rubygems. Replaces the default https://www.rubygems.org.
-- `handle_zip_download_url` - Url to the Handle zip archive used by Windows. Used to override the default in airgapped environments. default: https://download.sysinternals.com/files/Handle.zip (Note that you can also override the `default['chef_client_updater']['handle_exe_path']` attribute if you already have that binary somewhere on your system)
+- `install_timeout` - The install timeout for non-windows systems. The default is `600`, slow machines may need to extend this.
+- `upgrade_delay` - The delay in seconds before the scheduled task to upgrade Chef Infra Client runs on windows. Default: `60`. Lowering this limit is not recommended.
+- `product_name` - The name of the product to upgrade. This can be `chef`, `chefdk`, or `cinc`. Default: `chef`
+- `install_command_options` - A Hash of additional options that will be passed to the Mixlib::Install instance responsible for installing the given product_name. To install Chef Infra Client as a scheduled task on windows, one can pass `{daemon: 'task'}`. Default: `{}`
+- `rubygems_url` - The location to source rubygems. Default: https://www.rubygems.org
+- `handle_zip_download_url` - Url to the Handle zip archive used by Windows. Used to override the default in airgapped environments. Default: https://download.sysinternals.com/files/Handle.zip (Note that you can also override the `default['chef_client_updater']['handle_exe_path']` attribute if you already have that binary somewhere on your system)
+- `event_log_service_restart` - Whether the Event Log Service on Windows should be restarted to release any locked files. Default: `true`
+- `install_command_options` - Additional parameters to pass to the [mixlib-install script](https://github.com/chef/mixlib-install/tree/main#install-scripts). Default: `{}`
 
 #### examples