Extends docs for upgrading to v1.10.0 and adds KB entry

doc/100-General/01-Upgrading.md

@@ -6,6 +6,10 @@ Specific version upgrades are described below. Please note that version updates
 
 ## Upgrading to v1.10.0 (2022-08-30)
 
+### <span style="color:red">**Breaking changes with v1.10.0 - Read carefully before upgrading!**</span>
+
+### Updating existing installations to v1.10.0
+
 Icinga for Windows v1.10.0 made some changes regarding encoding, to ensure Icinga checks are always properly encoded to work with German umlauts. Because of this change, the update from a previous Icinga for Windows version to v1.10.0 requires some additional steps. To properly upgrade your environment, please use the following code and add the `icinga-powershell-framework` update procedure in-between:
 
 ```powershell
@@ -23,9 +27,32 @@ Copy-Item -Path (Join-Path -Path $FrameworkRootPath -ChildPath '\templates\frame
 Import-Module icinga-powershell-framework -Force;
 Import-Module icinga-powershell-framework -Global -Force;
 
+# Restart the Icinga for Windows service in case installed, to ensure the functionality
+Restart-IcingaWindowsService;
+
 # Add your own update procedure code
 ```
 
+In case your installation is already broken, please have a look on the corresponding knowledge base entry [IWKB000014](../knowledgebase/IWKB000014.md).
+
+### New Performance-Data Metrics
+
+Icinga for Windows v1.10.0 made a change on how performance metrics are designed. Instead of the old labels
+
+```
+used_partition_c
+```
+
+we moved to the `check_multi` output, which allows easier filtering inside graphing solutions:
+
+```
+c::ifw_partitionspace::used
+```
+
+Once upgrade to v1.10.0, please ensure to update all installed components like [Plugins](https://icinga.com/docs/icinga-for-windows/latest/plugins/doc/01-Introduction/), [MSSQL](https://icinga.com/docs/icinga-for-windows/latest/mssql/doc/01-Introduction/), [Hyper-V](https://icinga.com/docs/icinga-for-windows/latest/hyperv/doc/01-Introduction/) and [Cluster](https://icinga.com/docs/icinga-for-windows/latest/cluster/doc/01-Introduction/) to the latest versions, to properly support the new format and write Performance Metrics with the correct index, template and naming handling.
+
+Prior to this release, we have published a [Blogpost on Icinga](https://icinga.com/blog/2022/07/18/icinga-for-windows-preview-visualize-your-metrics/) to announce these changes early on.
+
 ## Upgrading to v1.8.0 (2022-02-08)
 
 ### Service Binary

doc/300-Knowledge-Base.md

@@ -21,3 +21,4 @@ For this reason you will find a list of Icinga knowledge base entries below. Ent
 | [IWKB000011](knowledgebase/IWKB000011.md) | The Icinga PowerShell Framework is either not installed on the system or not configured properly. Please check https://icinga.com/docs/windows for further details Error: The term 'Use-Icinga' is not recognized as the name of a cmdlet, function, script file, or operable program. Check the spelling of the name, or if a path was included, verify that the path is correct and try again. |
 | [IWKB000012](knowledgebase/IWKB000012.md) | Icinga for Windows cannot be used with Microsoft Defender: `Windows Defender Antivirus has detected malware or other potentially unwanted software` |
 | [IWKB000013](knowledgebase/IWKB000013.md) | The local Icinga Agent certificate seems not to be signed by our Icinga CA yet. Using this certificate for the REST-Api as example might not work yet. Please check the state of the certificate and complete the signing process if required |
+| [IWKB000014](knowledgebase/IWKB000014.md) | Installing or Updating Icinga for Windows causes error messages regarding `framework_cache.psm1` errors |

doc/knowledgebase/IWKB000014.md

@@ -0,0 +1,42 @@
+# Icinga Knowledge Base - IWKB000014
+
+## Short Message
+
+Installing or Updating Icinga for Windows causes error messages regarding `framework_cache.psm1` errors.
+
+## Example Exception
+
+![EventLog Defender](../images/04_knowledgebase/IWKB000014/01_framework_cache_exception.png)
+
+## Reason
+
+This or a similar error can happen, if for some reason the `framework_cache.psm1` is corrupted during the installation or update.
+
+While upgrading from older versions to `v1.10.0`, this is an `expected` error, because of various changes we made and notified about in the [Upgrading Docs](../100-General/01-Upgrading.md).
+
+## Solution
+
+To resolve this issue, we simply require to reset the `framework_cache.psm1`. Starting with Icinga for Windows v1.10.0, there is a template available we can copy over the current file and resetting the state. As we assume in this, that your Icinga for Windows installation is already broken, we use native PowerShell tools instead of Icinga for Windows tools.
+
+Use the following code snippet to repair your installation within an `administrative PowerShell`:
+
+```powershell
+[array]$FrameworkModule = Get-Module -ListAvailable -Name 'icinga-powershell-framework';
+[string]$TemplateCache  = Join-Path `
+    -Path $FrameworkModule[0].ModuleBase `
+    -ChildPath 'templates\framework_cache.psm1.template';
+[string]$FrameworkCache = Join-Path `
+    -Path $FrameworkModule[0].ModuleBase `
+    -ChildPath 'cache\framework_cache.psm1';
+
+Copy-Item -Path $TemplateCache -Destination $FrameworkCache -Force;
+
+Import-Module -Name 'icinga-powershell-framework' -Force;
+Import-Module -Name 'icinga-powershell-framework' -Global -Force;
+
+icinga { Write-Host 'Icinga for Windows successfully repaired' };
+
+Restart-IcingaWindowsService;
+```
+
+Once executed, Icinga for Windows should rebuild the cache and work again as intended. Please keep the `icinga` call within the example, as this will ensure that possible pending migrations of Icinga for Windows will be applied.