Initial VPS operations handbook

ansible/roles/k3s_preflight/defaults/main.yml

@@ -0,0 +1,14 @@
+---
+# Read-only checks for a dedicated, single-node Matrix K3s host.
+k3s_preflight_required_memory_mib: 6144
+k3s_preflight_required_root_free_gib: 50
+k3s_preflight_required_hosts:
+  - "{{ matrix_server_name }}"
+  - "{{ matrix_synapse_host }}"
+  - "{{ matrix_element_host }}"
+  - "{{ matrix_mas_host }}"
+  - "{{ matrix_admin_host }}"
+  - "{{ matrix_rtc_host }}"
+k3s_preflight_required_ports:
+  - 80
+  - 443

ansible/roles/k3s_preflight/tasks/main.yml

@@ -0,0 +1,69 @@
+---
+- name: Read host memory in MiB
+  ansible.builtin.set_fact:
+    k3s_preflight_memory_mib: "{{ (ansible_memtotal_mb | int) }}"
+
+- name: Read root filesystem capacity facts
+  ansible.builtin.set_fact:
+    k3s_preflight_root_mount: >-
+      {{ (ansible_mounts | selectattr('mount', 'equalto', '/') | list | first) | default({}) }}
+
+- name: Assert host has the baseline resources for Matrix
+  ansible.builtin.assert:
+    that:
+      - k3s_preflight_memory_mib | int >= k3s_preflight_required_memory_mib | int
+      - (k3s_preflight_root_mount.size_available | default(0) | int) >= (k3s_preflight_required_root_free_gib | int * 1024 * 1024 * 1024)
+    fail_msg: >-
+      Matrix requires at least {{ k3s_preflight_required_memory_mib }} MiB RAM and
+      {{ k3s_preflight_required_root_free_gib }} GiB available on /. No change was made.
+
+- name: Check whether K3s is already installed
+  ansible.builtin.stat:
+    path: /usr/local/bin/k3s
+  register: k3s_preflight_binary
+
+- name: Read listeners on required public ports
+  ansible.builtin.command:
+    argv: [ss, -lntH]
+  changed_when: false
+  register: k3s_preflight_listeners
+
+- name: Assert public ports are unused before initial K3s installation
+  ansible.builtin.assert:
+    that:
+      - >-
+        (k3s_preflight_binary.stat.exists | bool) or
+        ((k3s_preflight_listeners.stdout_lines | select('search', '(:|\\.)' ~ (item | string) ~ '$') | list | length) == 0)
+    fail_msg: "Port {{ item }} is already listening; resolve the ingress ownership conflict first."
+  loop: "{{ k3s_preflight_required_ports }}"
+
+- name: Resolve Matrix hostnames over IPv4
+  ansible.builtin.command:
+    argv: [getent, ahostsv4, "{{ item }}"]
+  changed_when: false
+  register: k3s_preflight_dns
+  loop: "{{ k3s_preflight_required_hosts }}"
+
+- name: Assert every Matrix hostname resolves to the selected VPS
+  ansible.builtin.assert:
+    that:
+      - item.stdout is search(ansible_host_ipv4 | regex_escape)
+    fail_msg: >-
+      {{ item.item }} does not resolve to {{ ansible_host_ipv4 }} over IPv4. DNS must
+      be correct before HTTP-01 certificates can be issued.
+  loop: "{{ k3s_preflight_dns.results }}"
+
+- name: Check the local backup path parent filesystem
+  ansible.builtin.command:
+    argv: [df, -P, "{{ matrix_backup_path | dirname }}"]
+  changed_when: false
+  register: k3s_preflight_backup_filesystem
+
+- name: Report read-only preflight state
+  ansible.builtin.debug:
+    msg:
+      k3s_installed: "{{ k3s_preflight_binary.stat.exists }}"
+      memory_mib: "{{ k3s_preflight_memory_mib }}"
+      root_available_bytes: "{{ k3s_preflight_root_mount.size_available | default(0) }}"
+      backup_path: "{{ matrix_backup_path }}"
+      backup_filesystem: "{{ k3s_preflight_backup_filesystem.stdout_lines[-1] }}"