Add Icinga for Windows role 'ifw'

changelogs/fragments/feature_icinga_for_windows.yml

@@ -0,0 +1,5 @@
+major_changes:
+  - "Introduction of role :code:`ifw` - Icinga for Windows: This role allows to install the Icinga PowerShell Framework, manage components and repositories, and install and configure Icinga 2 through Icinga for Windows."
+  - "Module :code:`ifw_backgrounddaemon`: Registers/unregisters an Icinga for Windows background daemon."
+  - "Module :code:`ifw_component`: Installs/removes/updates Icinga for Windows components (e.g. :code:`agent`, :code:`plugins`)."
+  - "Module :code:`ifw_restapicommand`: Adds/removes commands to/from the whitelist/blacklist of the Icinga for Windows REST-Api."

doc/role-ifw/README.md

@@ -0,0 +1 @@
+../../roles/ifw/README.md

plugins/modules/ifw_backgrounddaemon.ps1

@@ -0,0 +1,125 @@
+#!powershell
+
+#AnsibleRequires -CSharpUtil Ansible.Basic
+
+### Input parameters
+$spec = @{
+    options = @{
+        state = @{ type = "str"; choices = "absent", "present"; default = "present" }
+        command = @{ type = "str"; required = $true }
+        arguments = @{ type = "dict"; required = $false; default = @{} }
+    }
+    supports_check_mode = $true
+}
+
+
+### Module initilization
+$module = [Ansible.Basic.AnsibleModule]::Create($args, $spec)
+
+
+### Make use of input parameters
+$Changed = $false
+$State = $module.Params.state
+$Command = $module.Params.command
+$Arguments = $module.Params.arguments
+
+# Sanetize $Arguments, prepend "-" to get "<COMMAND> -<FLAG> <VALUE>"
+$TmpArguments = @{}
+foreach ($Argument in $Arguments.Keys) {
+    if (-Not $Argument.StartsWith("-")) {
+        $TmpArguments."-$($Argument)" = $Arguments.$Argument
+    }
+}
+$Arguments = $TmpArguments
+
+
+### Main code
+# Check if IfW is installed
+if (-Not (Get-Command | Where-Object -Property Name -EQ "Show-IcingaRegisteredBackgroundDaemons")) { 
+    throw "Necessary command 'Show-IcingaRegisteredBackgroundDaemons' was not found. Is IfW installed?"
+}
+
+# Check that $Command is valid and available
+if (-Not (Get-Command | Where-Object -Property Name -EQ $Command)) { 
+    throw "Necessary command '$($Command)' was not found."
+}
+
+
+# Check if BackgroundDaemon for given command exists
+function BackgroundDaemon-Exists () {
+    param(
+        [String]$Command
+    );
+
+    $Exists = (Show-IcingaRegisteredBackgroundDaemons) -Contains $Command
+    return $Exists
+}
+
+# Check if given command arguments are equal to existing command arguments
+function ArgumentsAreEqual () {
+    param(
+        $Arguments,
+        $ExistingArguments
+    );
+
+    $ArgumentsAreEqual = $true
+    foreach ($Key in $Arguments.keys) {
+        if ($Arguments.$Key -NE $ExistingArguments.$Key) {
+            $ArgumentsAreEqual = $false
+            break
+        }
+    }
+    return $ArgumentsAreEqual
+}
+
+# Get existing arguments for given command
+function Get-ExistingArguments () {
+    param(
+        [String]$Command
+    );
+
+    $Arguments = (Read-IcingaPowerShellConfig).BackgroundDaemon.EnabledDaemons."$($Command)".Arguments
+
+    return $Arguments
+}
+
+
+
+$CommandIsRegistered = BackgroundDaemon-Exists -Command $Command
+$ExistingArguments = Get-ExistingArguments -Command $Command
+$ArgumentsAreEqual = ArgumentsAreEqual -Arguments $Arguments -ExistingArguments $ExistingArguments
+
+
+# Update if needed
+if ($State -EQ "absent" -And $CommandIsRegistered) {
+    if (-Not $module.CheckMode) {
+        Unregister-IcingaBackgroundDaemon `
+            -BackgroundDaemon $Command | Out-Null
+    }
+    $Changed = $true
+
+} elseif ($State -EQ "present" -And (-Not $CommandIsRegistered -Or -Not $ArgumentsAreEqual)) {
+    if (-Not $module.CheckMode) {
+        Register-IcingaBackgroundDaemon `
+            -Command $Command `
+            -Arguments $Arguments | Out-Null
+    }
+    $Changed = $true
+}
+
+$Before = @{
+    command = (&{ if ($CommandIsRegistered) { $Command } else { $null } } )
+    arguments = (&{ if ($CommandIsRegistered) { $ExistingArguments } else { $null } } )
+}
+$After = @{
+    command = (&{ if ($State -EQ "present") { $Command } else { $null } } )
+    arguments = (&{ if ($State -EQ "present") { $Arguments } else { $null } } )
+}
+
+
+
+### Module return
+$module.Result.before = $Before
+$module.Result.after = $After
+$module.Result.changed = $Changed
+$module.ExitJson()

plugins/modules/ifw_backgrounddaemon.py

@@ -0,0 +1,104 @@
+DOCUMENTATION = '''
+---
+name: ifw_backgrounddaemon
+short_description: (Un-)Registers an IfW Background Daemon.
+description:
+  - This module allows you to register/unregister an Icinga for Windows Background Daemon.
+  - They are used to collect metrics over time or used for the IfW API Check Forwarder.
+version_added: 0.1.0
+author:
+  - Matthias Döhler <[email protected]>
+seealso:
+  - name: Icinga for Windows Background Daemons
+    description: Reference for the Background Daemons.
+    link: https://icinga.com/docs/icinga-for-windows/latest/doc/110-Installation/05-Background-Daemons/
+  - name: Icinga for Windows API Check Forwareder
+    description: Reference for a possible use case regarding the API Check Forwarder.
+    link: https://icinga.com/docs/icinga-for-windows/latest/doc/110-Installation/30-API-Check-Forwarder/
+options:
+  state:
+    description:
+      - The state of the Background Daemon.
+    required: false
+    default: present
+    choices: [ "present", "absent" ]
+    type: str
+  command:
+    description:
+      - The name of a valid command available in the used PowerShell.
+      - This could be something like C(Start-MyCustomDaemon).
+      - If O(state=absent), only the O(command) is used to determine which Background Daemon should be removed.
+    required: true
+    type: str
+  arguments:
+    description:
+      - Arguments to be passed to O(command).
+      - Must be key value pairs.
+      - The leading C(-) is prepended in front of the argument name/key (C(key) becomes C(-key)).
+    required: false
+    type: dict
+'''
+
+EXAMPLES = r'''
+# The PowerShell equivalent is:
+# Register-IcingaBackgroundDaemon `
+#     -Command 'Start-MyCustomDaemon' `
+#     -Arguments @{
+#         '-MySwitchParameter'  = $True;
+#         '-MyIntegerParameter' = 42;
+#         '-MyStringParameter'  = 'Example';
+#     };
+- name: Register a Background Daemon for a specific command passing argument flags with values to that command
+  netways.icinga.ifw_backgrounddaemon:
+    state: present
+    command: "Start-MyCustomDaemon"
+    arguments:
+      MySwitchParameter: true
+      MyIntegerParameter: 42
+      MyStringParameter: "Example"
+
+- name: Register the Icinga for Windows RESTApi as a Background Daemon to use API Check Forwarder
+  netways.icinga.ifw_backgrounddaemon:
+    state: present
+    command: "Start-IcingaWindowsRESTApi"
+'''
+
+RETURN = r'''
+before:
+  description:
+    - Shows information about the previously (un-)registered command and its arguments.
+    - If no change occurs, will be the same as RV(after).
+  returned: success
+  type: dict
+  contains:
+    command:
+      description: The name of the previously (un-)registered command.
+      returned: success
+      type: str
+      sample:
+    arguments:
+      description: The arguments used previously for the specified command.
+      returned: success
+      type: dict
+      sample:
+after:
+  description:
+    - Shows information about the newly (un-)registered command and its arguments.
+    - If no change occurs, will be the same as RV(before).
+  returned: success
+  type: dict
+  contains:
+    command:
+      description: The name of the newly (un-)registered command.
+      returned: success
+      type: str
+      sample: Start-MyCustomDaemon
+    arguments:
+      description: The arguments now used for the specified command.
+      returned: success
+      type: dict
+      sample:
+        -MyIntegerParameter: 42
+        -MyStringParameter: "Example"
+        -MySwitchParameter: true
+'''