From 635bbd447dbbab1cd6d442325c65f554eb958a7a Mon Sep 17 00:00:00 2001
From: June <june@jsts.xyz>
Date: Tue, 1 Jul 2025 04:13:52 +0200
Subject: [PATCH] reboot(role): intro. reboot role, which handles local conns.
 gracefully

Also use this role instead of plain ansible.builtin.reboot.
This is in preparation for using ansible_pull as we don't want to have
ansible.builtin.reboot fail local playbook runs.
---
 .../apt_update_and_upgrade/handlers/main.yaml |  6 +++--
 roles/reboot/README.md                        | 26 +++++++++++++++++++
 roles/reboot/defaults/main.yaml               |  2 ++
 roles/reboot/meta/argument_specs.yaml         | 13 ++++++++++
 roles/reboot/tasks/main.yaml                  | 14 ++++++++++
 5 files changed, 59 insertions(+), 2 deletions(-)
 create mode 100644 roles/reboot/README.md
 create mode 100644 roles/reboot/defaults/main.yaml
 create mode 100644 roles/reboot/meta/argument_specs.yaml
 create mode 100644 roles/reboot/tasks/main.yaml

diff --git a/roles/apt_update_and_upgrade/handlers/main.yaml b/roles/apt_update_and_upgrade/handlers/main.yaml
index 001bbe4..4af18be 100644
--- a/roles/apt_update_and_upgrade/handlers/main.yaml
+++ b/roles/apt_update_and_upgrade/handlers/main.yaml
@@ -1,3 +1,5 @@
 - name: reboot the system
-  become: true
-  ansible.builtin.reboot:
+  ansible.builtin.include_tasks: "../../reboot/tasks/main.yaml"
+  vars:
+    # Simply don't reboot on local connections and rely on proper handling of /var/run/reboot-required.
+    reboot__local_handling: ignore
diff --git a/roles/reboot/README.md b/roles/reboot/README.md
new file mode 100644
index 0000000..1aaa6a6
--- /dev/null
+++ b/roles/reboot/README.md
@@ -0,0 +1,26 @@
+# Role `reboot`
+
+A role for rebooting a host, which also handles local connections gracefully.
+
+## Optional Arguments
+
+- `reboot__local_handling`: How to handle reboot on local connections. The default mode is `none`.  
+  Possible choices:
+  - `none`: Just runs `ansible.builtin.reboot`, which would fail on local connections.
+  - `ignore`: Just doesn't reboot on local connections.
+  - `file`: Doesn't reboot on local connections and instead touches the file defined by `reboot__local_handling_file`.
+- `reboot__local_handling_file`: The file to touch, if `reboot__local_handling` is `file`. Defaults to `/var/run/ansible-reboot-required`.
+
+## Usage in a Handler
+
+Since a reboot should often be triggered from a handler and since handlers can't include or import roles, this roles logic can also be run by including the `main.yaml` task using `ansible.builtin.include_tasks` as a workaround.  
+When doing so, arguments should be specified explicitly as necessary (so at least `reboot__local_handling`) as the default role inclusion mechanisms like setting default values don't work.
+
+An example handler would look like this:
+
+```yaml
+- name: reboot the system
+  ansible.builtin.include_tasks: "../../reboot/tasks/main.yaml"
+  vars:
+    reboot__local_handling: ignore
+```
diff --git a/roles/reboot/defaults/main.yaml b/roles/reboot/defaults/main.yaml
new file mode 100644
index 0000000..dbcdd1b
--- /dev/null
+++ b/roles/reboot/defaults/main.yaml
@@ -0,0 +1,2 @@
+reboot__local_handling: none
+reboot__local_handling_file: /var/run/ansible-reboot-required
diff --git a/roles/reboot/meta/argument_specs.yaml b/roles/reboot/meta/argument_specs.yaml
new file mode 100644
index 0000000..7bad88f
--- /dev/null
+++ b/roles/reboot/meta/argument_specs.yaml
@@ -0,0 +1,13 @@
+argument_specs:
+  main:
+    options:
+      reboot__local_handling:
+        type: str
+        required: false
+        choices:
+          - "none"
+          - "ignore"
+          - "file"
+      reboot__local_handling_file:
+        type: path
+        required: false
diff --git a/roles/reboot/tasks/main.yaml b/roles/reboot/tasks/main.yaml
new file mode 100644
index 0000000..791bf73
--- /dev/null
+++ b/roles/reboot/tasks/main.yaml
@@ -0,0 +1,14 @@
+- name: Reboot
+  ansible.builtin.reboot:
+  become: true
+  when: ansible_connection != "local" or reboot__local_handling == "none"
+
+- name: Touch a reboot required file
+  ansible.builtin.file:
+    path: "{{ reboot__local_handling_file }}"
+    state: touch
+    owner: root
+    group: root
+    mode: "0644"
+  become: true
+  when: ansible_connection == "local" and reboot__local_handling == "file"