feat: Argument spec implementation for kernel settings role

meta/argument_specs.yml

@@ -0,0 +1,82 @@
+# SPDX-License-Identifier: MIT
+---
+argument_specs:
+  main:
+    short_description: The kernel_settings role.
+    description: >
+      The kernel_settings role allows you to modify kernel settings such as
+      `sysctl` parameters, `/sys` sysfs values, systemd CPU affinity, and
+      transparent hugepage settings. It uses `tuned` as the default provider
+      on Red Hat Enterprise Linux, derivatives, and Fedora.
+
+      Settings are additive by default. Use `previous: replaced` in a settings
+      list to replace all existing values in a group, or `{"state": "empty"}`
+      to remove all settings in a group. Use `state: absent` on individual
+      settings to remove them.
+    options:
+      kernel_settings_sysctl:
+        type: raw
+        default: []
+        description: >
+          List of `sysctl` settings to apply, or the dict `{"state":
+          "empty"}` to remove all `sysctl` settings. Each list item is a
+          dict with keys `name`, `value`, `state`, and `previous`. Use
+          `state: absent` to remove a setting by name. Use `previous:
+          replaced` as one list item to replace all existing settings with
+          the given values. Values must be strings or numbers, not YAML
+          boolean types.
+      kernel_settings_sysfs:
+        type: raw
+        default: []
+        description: >
+          List of `/sys` settings to apply, or the dict `{"state":
+          "empty"}` to remove all `sysfs` settings. Each list item is a
+          dict with keys `name`, `value`, `state`, and `previous`. The
+          `name` is the path under `/sys`. Use `state: absent` to remove a
+          setting by name. Use `previous: replaced` as one list item to
+          replace all existing settings with the given values.
+      kernel_settings_systemd_cpu_affinity:
+        type: raw
+        default: null
+        description: >
+          CPU affinity for systemd as a space-delimited list of CPU
+          numbers, for example `1,3,5,7`, as described in the
+          systemd-system.conf `CPUAffinity` option. Use the dict
+          `{"state": "absent"}` to remove the setting.
+      kernel_settings_transparent_hugepages:
+        type: raw
+        default: null
+        description: >
+          Transparent hugepages setting for the memory subsystem. Set to
+          `always`, `madvise`, or `never`. Use the dict `{"state":
+          "absent"}` to remove the setting.
+      kernel_settings_transparent_hugepages_defrag:
+        type: raw
+        default: null
+        description: >
+          Transparent hugepages defragmentation setting for the memory
+          subsystem. Set to `always`, `defer`, `defer+madvise`, `madvise`,
+          or `never`. The supported values may differ depending on the
+          OS. Use the dict `{"state": "absent"}` to remove the setting.
+      kernel_settings_purge:
+        type: bool
+        default: false
+        description: >
+          Whether to completely wipe out the current kernel settings
+          configuration and replace it with the given settings.
+      kernel_settings_reboot_ok:
+        type: bool
+        default: false
+        description: >
+          Whether the role is allowed to reboot the managed host when a
+          reboot is required to apply changes. When `false`, the role sets
+          `kernel_settings_reboot_required` to `true` instead of
+          rebooting.
+      kernel_settings_transactional_update_reboot_ok:
+        type: raw
+        default: null
+        description: >
+          Whether to permit reboots required by transactional updates. Set
+          to `true` to allow reboots, `false` to disallow reboots, or leave
+          unset so that the role will fail to ensure the reboot requirement
+          is not overlooked. Accepts a boolean value or `null`.

tasks/assert_role_vars.yml

@@ -0,0 +1,168 @@
+# SPDX-License-Identifier: MIT
+---
+- name: Assert kernel_settings_sysctl is a list of dicts or the empty sentinel
+  ansible.builtin.assert:
+    that:
+      - >-
+        (kernel_settings_sysctl is mapping
+         and kernel_settings_sysctl.keys() | list | difference(['state'])
+         | length == 0
+         and kernel_settings_sysctl.state == 'empty')
+        or (kernel_settings_sysctl is sequence
+            and kernel_settings_sysctl is not string
+            and kernel_settings_sysctl is not mapping
+            and kernel_settings_sysctl | reject('mapping') | list | length == 0)
+    fail_msg: >-
+      kernel_settings_sysctl must be a list of dictionaries or {"state":
+      "empty"}, got {{ kernel_settings_sysctl | type_debug }}
+
+- name: Assert kernel_settings_sysctl list items are valid
+  ansible.builtin.assert:
+    that:
+      - >-
+        item.keys() | list | difference(__kernel_settings_setting_valid_keys)
+        | length == 0
+      - not ('previous' in item) or item.previous == 'replaced'
+      - not ('state' in item) or item.state == 'absent'
+      - >-
+        (item.keys() | list == ['previous'] and item.previous == 'replaced')
+        or ('name' in item)
+      - >-
+        (item.keys() | list == ['previous'] and item.previous == 'replaced')
+        or ('state' in item and item.state == 'absent')
+        or ('value' in item)
+    fail_msg: >-
+      kernel_settings_sysctl[{{ idx }}] is invalid:
+      {{ item }}
+  vars:
+    __kernel_settings_setting_valid_keys:
+      - name
+      - value
+      - state
+      - previous
+  loop: >-
+    {{ kernel_settings_sysctl if (kernel_settings_sysctl is sequence
+          and kernel_settings_sysctl is not string
+          and kernel_settings_sysctl is not mapping)
+       else [] }}
+  loop_control:
+    index_var: idx
+    label: "{{ idx }}"
+
+- name: Assert kernel_settings_sysfs is a list of dicts or the empty sentinel
+  ansible.builtin.assert:
+    that:
+      - >-
+        (kernel_settings_sysfs is mapping
+         and kernel_settings_sysfs.keys() | list | difference(['state'])
+         | length == 0
+         and kernel_settings_sysfs.state == 'empty')
+        or (kernel_settings_sysfs is sequence
+            and kernel_settings_sysfs is not string
+            and kernel_settings_sysfs is not mapping
+            and kernel_settings_sysfs | reject('mapping') | list | length == 0)
+    fail_msg: >-
+      kernel_settings_sysfs must be a list of dictionaries or {"state":
+      "empty"}, got {{ kernel_settings_sysfs | type_debug }}
+
+- name: Assert kernel_settings_sysfs list items are valid
+  ansible.builtin.assert:
+    that:
+      - >-
+        item.keys() | list | difference(__kernel_settings_setting_valid_keys)
+        | length == 0
+      - not ('previous' in item) or item.previous == 'replaced'
+      - not ('state' in item) or item.state == 'absent'
+      - >-
+        (item.keys() | list == ['previous'] and item.previous == 'replaced')
+        or ('name' in item)
+      - >-
+        (item.keys() | list == ['previous'] and item.previous == 'replaced')
+        or ('state' in item and item.state == 'absent')
+        or ('value' in item)
+    fail_msg: >-
+      kernel_settings_sysfs[{{ idx }}] is invalid:
+      {{ item }}
+  vars:
+    __kernel_settings_setting_valid_keys:
+      - name
+      - value
+      - state
+      - previous
+  loop: >-
+    {{ kernel_settings_sysfs if (kernel_settings_sysfs is sequence
+          and kernel_settings_sysfs is not string
+          and kernel_settings_sysfs is not mapping)
+       else [] }}
+  loop_control:
+    index_var: idx
+    label: "{{ idx }}"
+
+- name: Assert kernel_settings_systemd_cpu_affinity is null, a string, or absent dict
+  ansible.builtin.assert:
+    that:
+      - >-
+        (kernel_settings_systemd_cpu_affinity is none)
+        or (kernel_settings_systemd_cpu_affinity is string)
+        or (
+          kernel_settings_systemd_cpu_affinity is mapping
+          and kernel_settings_systemd_cpu_affinity.keys() | list
+          | difference(['state']) | length == 0
+          and kernel_settings_systemd_cpu_affinity.state == 'absent'
+        )
+    fail_msg: >-
+      kernel_settings_systemd_cpu_affinity must be null, a string, or
+      {"state": "absent"}, got {{ kernel_settings_systemd_cpu_affinity | type_debug }}
+
+- name: Assert kernel_settings_transparent_hugepages is null, a valid string, or absent dict
+  ansible.builtin.assert:
+    that:
+      - >-
+        (kernel_settings_transparent_hugepages is none)
+        or (
+          kernel_settings_transparent_hugepages is string
+          and kernel_settings_transparent_hugepages in
+          ['always', 'madvise', 'never']
+        )
+        or (
+          kernel_settings_transparent_hugepages is mapping
+          and kernel_settings_transparent_hugepages.keys() | list
+          | difference(['state']) | length == 0
+          and kernel_settings_transparent_hugepages.state == 'absent'
+        )
+    fail_msg: >-
+      kernel_settings_transparent_hugepages must be null, one of always,
+      madvise, never, or {"state": "absent"},
+      got {{ kernel_settings_transparent_hugepages | type_debug }}
+
+- name: Assert kernel_settings_transparent_hugepages_defrag is null, a valid string, or absent dict
+  ansible.builtin.assert:
+    that:
+      - >-
+        (kernel_settings_transparent_hugepages_defrag is none)
+        or (
+          kernel_settings_transparent_hugepages_defrag is string
+          and kernel_settings_transparent_hugepages_defrag in
+          ['always', 'defer', 'defer+madvise', 'madvise', 'never']
+        )
+        or (
+          kernel_settings_transparent_hugepages_defrag is mapping
+          and kernel_settings_transparent_hugepages_defrag.keys() | list
+          | difference(['state']) | length == 0
+          and kernel_settings_transparent_hugepages_defrag.state == 'absent'
+        )
+    fail_msg: >-
+      kernel_settings_transparent_hugepages_defrag must be null, one of
+      always, defer, defer+madvise, madvise, never, or {"state":
+      "absent"}, got {{ kernel_settings_transparent_hugepages_defrag | type_debug }}
+
+- name: Assert kernel_settings_transactional_update_reboot_ok is null or a boolean
+  ansible.builtin.assert:
+    that:
+      - >-
+        (kernel_settings_transactional_update_reboot_ok is none)
+        or (kernel_settings_transactional_update_reboot_ok is sameas true)
+        or (kernel_settings_transactional_update_reboot_ok is sameas false)
+    fail_msg: >-
+      kernel_settings_transactional_update_reboot_ok must be null or a
+      boolean, got {{ kernel_settings_transactional_update_reboot_ok | type_debug }}

tasks/main.yml

@@ -1,4 +1,7 @@
 ---
+- name: Validate role parameters
+  ansible.builtin.include_tasks: assert_role_vars.yml
+
 - name: Check sysctl settings for boolean values
   fail:
     msg: Boolean values are not allowed for sysctl settings