Merge pull request #163 from Icinga:feature/icinga2_plain_config_generator

Feature: Adds native Icinga config generation support and adds simple publish command

Adds native support for writing Icinga 2 configuration for plugins and allows to easy publish new configurations for modules with the new Cmdlet Publish-IcingaPluginConfiguration

Author: LordHepipud

doc/05-Icinga-Integration.md

@@ -16,7 +16,8 @@ Configuring Check-Commands
 
 To get started, there are two ways to configure check command objects:
 
-* [Automated configuration](icingaintegration/01-Director-Baskets.md) with Baskets
+* [Automated Icinga Director configuration](icingaintegration/01-Director-Baskets.md) with Baskets
+* [Automated Icinga 2 configuration](icingaintegration/04-Icinga-Config.md) with plain Icinga config
 * [Manual configuration](icingaintegration/02-Manual-Integration.md) of check commands
 * [Using PowerShell Arrays in Icinga](icingaintegration/03-PowerShell-Arrays.md)
 * [Windows Terminal Integration](icingaintegration/50-Windows-Terminal.md)

doc/31-Changelog.md

@@ -25,6 +25,7 @@ Released closed milestones can be found on [GitHub](https://github.com/Icinga/ic
 * [#153](https://github.com/Icinga/icinga-powershell-framework/pull/153) Adds support to add a knowledge base id to `Exit-IcingaThrowException` for easier referencing. This should mostly be used for custom messages, as we should track the main knowledge base id's inside the messages directly. Native messages should be split in a hashtable with a `Message` and `IWKB` key
 * [#155](https://github.com/Icinga/icinga-powershell-framework/pull/155) Adds support to write all objects collected by `Get-IcingaWindowsInformation` into the Windows EventLog in case the debug output for the Icinga PowerShell Framework is enabled.
 * [#162](https://github.com/Icinga/icinga-powershell-framework/pull/162) Adds feature to test the length of plugin custom variables during config generation and throws error in case the total length is bigger than 64 digits, as imports into the Icinga Director by using baskets is not possible otherwise
+* [#163](https://github.com/Icinga/icinga-powershell-framework/pull/163) Adds native support for writing Icinga 2 configuration for plugins and allows to easy publish new configurations for modules with the new Cmdlet `Publish-IcingaPluginConfiguration`
 * [#164](https://github.com/Icinga/icinga-powershell-framework/pull/164) Adds `exit` after calling `icinga` on Windows Terminal integration to ensure the shell will close in case the Icinga shell is closed
 
 ### Bugfixes

doc/icingaintegration/04-Icinga-Config.md

@@ -0,0 +1,56 @@
+# Icinga Config Generator
+
+To make the integration as easy as possible, the Framework is shipping with an Icinga 2 configuration generator. Each Check-Plugin available within the Framework is able to auto-generate a Icinga config which can be copied to your Icinga 2 hosts.
+
+## Generating Configuration
+
+To automatically generate the Icinga configuration, open a PowerShell terminal and type in
+
+```powershell
+icinga
+```
+
+to load the Icinga PowerShell Framework.
+
+Afterwards use the command
+
+```powershell
+Get-IcingaCheckCommandConfig -IcingaConfig;
+```
+
+to automatically generate the configuration for all found Check-Commands.
+
+If you wish to specify specific commands only, you can filter them as well:
+
+```powershell
+Get-IcingaCheckCommandConfig -CheckName Invoke-IcingaCheckBiosSerial, Invoke-IcingaCheckCPU -IcingaConfig;
+```
+
+Last but not least you can output the Icinga configuration directly into a file. To do this, simply use the `OutDirectory` argument. You only require to specify a directory here, as the file including a timestamp is generated by the Cmdlet itself
+
+```powershell
+Get-IcingaCheckCommandConfig -OutDirectory 'C:\Users\myuser\Documents\'
+```
+
+Once the file is exported, you can copy the `.conf` files onto your Icinga 2 hosts to use them.
+
+**Note:** Because of a possible configuration error cased by multiple `PowerShell Base` CheckCommands, it is generated separately. You only require this once on your system and is cross-compatible with every single CheckCommand.
+
+## Custom File Names
+
+You can modify the name of the output `.conf` file  by using the `-FileName` argument in combination with the other arguments:
+
+```powershell
+Get-IcingaCheckCommandConfig -CheckName Invoke-IcingaCheckBiosSerial, Invoke-IcingaCheckCPU -IcingaConfig -OutDirectory 'C:\Users\myuser\Documents\' -FileName 'IcingaForWindows';
+```
+
+This will generate the plugins configuration `C:\Users\myuser\Documents\IcingaForWindows.conf` and `C:\Users\myuser\Documents\PowerShell_Base.conf`
+
+The `.conf` ending is not required, as the Cmdlet will take care of that for you.
+
+## Developer Note
+
+The generated Icinga configuration will benefit from a detailed documentation of the module and each single argument. Descriptions for arguments are parsed into the commands description field, informing users of what the argument actually does. Furthermore arguments are automatically mapped to certain object types. A `switch` argument for example will always be rendered with a `set_if` flag, ensuring you only require to set the corresponding custom variable to true to set this argument.
+In addition `array` arguments use the Icinga DSL to properly build PowerShell arrays based on Icinga arrays.
+
+This will increase the entire usability of the module and prevent you from having to document plugins multiple times.

lib/core/framework/Publish-IcingaPluginConfiguration.psm1

@@ -0,0 +1,104 @@
+<#
+.SYNOPSIS
+   Fetches plugins within the namespace `Invoke-IcingaCheck*` for a given
+   component name or the direct path and creates Icinga Director as well as
+   Icinga 2 configuration files.
+
+   The configuration files are printed within a `config` folder of the
+   specific module and splitted into `director` and `icinga`
+.DESCRIPTION
+   etches plugins within the namespace `Invoke-IcingaCheck*` for a given
+   component name or the direct path and creates Icinga Director as well as
+   Icinga 2 configuration files.
+
+   The configuration files are printed within a `config` folder of the
+   specific module and splitted into `director` and `icinga`
+.FUNCTIONALITY
+   Creates Icinga 2 and Icinga Director configuration files for plugins
+.EXAMPLE
+   PS>Publish-IcingaPluginConfiguration -ComponentName 'plugins';
+.EXAMPLE
+   PS>Publish-IcingaPluginConfiguration -ComponentPath 'C:\Program Files\WindowsPowerShell\modules\icinga-powershell-plugins';
+.PARAMETER ComponentName
+   The name of the component to lookup for plugins and write configuration for.
+   The leading icinga-powershell- is not required and you should simply use the name,
+   like 'plugins' or 'mssql'
+.PARAMETER ComponentPath
+   The path to the root directory of a PowerShell Plugin repository, like
+   'C:\Program Files\WindowsPowerShell\modules\icinga-powershell-plugins'
+.INPUTS
+   System.String
+.LINK
+   https://github.com/Icinga/icinga-powershell-framework
+#>
+
+function Publish-IcingaPluginConfiguration()
+{
+    param (
+        [string]$ComponentName,
+        [string]$ComponentPath
+    );
+
+    if ([string]::IsNullOrEmpty($ComponentName) -And [string]::IsNullOrEmpty($ComponentPath)) {
+        Write-IcingaConsoleError 'Please specify either a component name like "plugins" or set the component path to the root folder if a component, like "C:\Program Files\WindowsPowerShell\modules\icinga-powershell\plugins".';
+        return;
+    }
+
+    if ([string]::IsNullOrEmpty($ComponentPath)) {
+        $ComponentPath = Join-Path -Path (Get-IcingaFrameworkRootPath) -ChildPath ([string]::Format('icinga-powershell-{0}', $ComponentName));
+    }
+
+    if ((Test-Path $ComponentPath) -eq $FALSE) {
+        Write-IcingaConsoleError 'The path "{0}" for the Icinga for Windows component is not valid' -Objects $ComponentPath;
+        return;
+    }
+
+    try {
+        Import-Module $ComponentPath -Global -Force -ErrorAction Stop;
+    } catch {
+        [string]$Message = $_.Exception.Message;
+        Write-IcingaConsoleError 'Failed to import the module on path "{0}". Please verify that this is a valid PowerShell module root folder. Exception: {1}{2}' -Objects $ComponentPath, (New-IcingaNewLine), $Message;
+        return;  
+    }
+
+    $CheckCommands = Get-Command -ListImported -Name 'Invoke-IcingaCheck*' -ErrorAction SilentlyContinue;
+
+    if ($null -eq $CheckCommands) {
+        Write-IcingaConsoleError 'No Icinga CheckCommands were configured for module "{0}". Please verify that this is a valid PowerShell module root folder. Exception: {1}{2}' -Objects $ComponentPath, (New-IcingaNewLine), $Message;
+        return;
+    }
+
+    [array]$CheckList = @();
+
+    [string]$BasketConfigDir = Join-Path -Path $ComponentPath -ChildPath 'config\director';
+    [string]$IcingaConfigDir = Join-Path -Path $ComponentPath -ChildPath 'config\icinga';
+
+    if ((Test-Path $BasketConfigDir)) {
+        Remove-Item -Path $BasketConfigDir -Recurse -Force | Out-Null;
+    }
+    if ((Test-Path $IcingaConfigDir)) {
+        Remove-Item -Path $IcingaConfigDir -Recurse -Force | Out-Null;
+    }
+
+    if ((Test-Path $BasketConfigDir) -eq $FALSE) {
+        New-Item -Path $BasketConfigDir -ItemType Directory | Out-Null;
+    }
+    if ((Test-Path $IcingaConfigDir) -eq $FALSE) {
+        New-Item -Path $IcingaConfigDir -ItemType Directory | Out-Null;
+    }
+
+    foreach ($check in $CheckCommands) {
+        [string]$CheckPath = $check.Module.ModuleBase;
+
+        if ($CheckPath.Contains($ComponentPath) -eq $FALSE) {
+            continue;
+        }
+
+        $CheckList += [string]$check;
+        Get-IcingaCheckCommandConfig -CheckName $check -OutDirectory $BasketConfigDir -FileName $check;
+        Get-IcingaCheckCommandConfig -CheckName $check -OutDirectory $IcingaConfigDir -FileName $check -IcingaConfig;
+    }
+
+    Get-IcingaCheckCommandConfig -CheckName $CheckList -OutDirectory $BasketConfigDir -FileName ([string]::Format('{0}_Bundle', (Get-Culture).TextInfo.ToTitleCase($ComponentName)));
+    Get-IcingaCheckCommandConfig -CheckName $CheckList -OutDirectory $IcingaConfigDir -FileName ([string]::Format('{0}_Bundle', (Get-Culture).TextInfo.ToTitleCase($ComponentName))) -IcingaConfig;
+}