feat(deploy): add Ansible playbook + standalone deploy-spur skill for bare-metal deployment

deploy/ansible/.gitignore

@@ -0,0 +1,7 @@
+# Real inventories contain host IPs and credentials — never commit them.
+# Only the *.example.ini templates (placeholder addresses) are tracked.
+inventory/*.ini
+!inventory/*.example.ini
+
+# Ansible runtime artifacts
+*.retry

deploy/ansible/ansible.cfg

@@ -0,0 +1,14 @@
+[defaults]
+inventory = inventory/hosts.ini
+# On by default for safety. For first-time provisioning of fresh hosts whose
+# keys aren't yet in known_hosts, override per-run with
+# ANSIBLE_HOST_KEY_CHECKING=False ansible-playbook ...
+host_key_checking = True
+forks = 20
+retry_files_enabled = False
+deprecation_warnings = False
+interpreter_python = auto_silent
+
+[ssh_connection]
+pipelining = True
+ssh_args = -o ControlMaster=auto -o ControlPersist=60s -o BatchMode=yes -o ConnectTimeout=15

deploy/ansible/deploy.yml

@@ -0,0 +1,62 @@
+---
+# Spur deployment — works for single-node, multi-node-direct, multi-node-wireguard.
+#
+# Run:
+#   cd deploy/ansible
+#   ansible-playbook deploy.yml -i inventory/hosts.ini
+#
+# Subset to specific hosts:
+#   ansible-playbook deploy.yml -i inventory/hosts.ini --limit gpu-1
+#
+# Tear down (keeps installed binaries):
+#   ansible-playbook teardown.yml -i inventory/hosts.ini
+
+- name: Preflight + install Spur on all hosts
+  # Include the accounting host so a dedicated (non-controller/agent) accounting
+  # node still gets the spurdbd binary.
+  hosts: "spur_controllers:spur_agents:{{ spur_accounting_host | default(groups['spur_controllers'][0]) }}"
+  gather_facts: yes
+  any_errors_fatal: true
+  roles:
+    - role: spur_install
+
+- name: Configure WireGuard mesh (when spur_transport == wireguard)
+  hosts: spur_controllers:spur_agents
+  gather_facts: no
+  any_errors_fatal: true
+  roles:
+    - role: spur_wireguard
+      when: spur_transport == 'wireguard'
+
+- name: Deploy accounting stack (postgres + spurdbd) on the accounting host
+  # Runs BEFORE the controller so spurdbd is listening when spurctld starts and
+  # first tries to reach accounting. Accounting is a single service for the whole
+  # cluster; it runs on spur_accounting_host (default: first controller, but may be
+  # any managed host incl. a dedicated node). Set spur_accounting_enabled=false to skip.
+  hosts: "{{ spur_accounting_host | default(groups['spur_controllers'][0]) }}"
+  gather_facts: yes
+  any_errors_fatal: true
+  roles:
+    - role: spur_accounting
+      when: spur_accounting_enabled | bool
+
+- name: Start controller
+  hosts: spur_controllers
+  gather_facts: no
+  any_errors_fatal: true
+  roles:
+    - role: spur_controller
+
+- name: Start agents
+  hosts: spur_agents
+  gather_facts: no
+  any_errors_fatal: true
+  serial: 0      # parallel
+  roles:
+    - role: spur_agent
+
+- name: Verify with test jobs
+  hosts: spur_controllers[0]
+  gather_facts: no
+  roles:
+    - role: spur_verify

deploy/ansible/group_vars/all.yml

@@ -0,0 +1,54 @@
+---
+# Cluster identity
+spur_cluster_name: spur-cluster
+
+# Install
+spur_version: latest                # latest | nightly | vX.Y.Z
+spur_install_dir: /root/.local/bin
+spur_home: /root/spur
+
+# Transport: direct (LAN, no encryption) | wireguard (encrypted mesh)
+spur_transport: direct
+
+# WireGuard mesh settings (only used when spur_transport == wireguard)
+spur_wg_cidr: 10.44.0.0/16
+spur_wg_port: 51820
+spur_wg_interface: spur0
+
+# Ports
+spur_controller_port: 6817
+spur_agent_port: 6818
+spur_raft_port: 6821
+
+# Accounting (PostgreSQL + spurdbd). OPTIONAL — set spur_accounting_enabled: false to skip.
+# Single service for the whole cluster. Runs on spur_accounting_host (default: the
+# first controller), which may be any managed host — a controller, an agent, or a
+# dedicated node. Controllers report usage to it over gRPC; it owns the local postgres.
+spur_accounting_enabled: true
+# spur_accounting_host: set in inventory to pin the accounting node (any managed
+# host). Left unset here so an inventory value wins; defaults to the first
+# controller via `| default(groups['spur_controllers'][0])` where referenced.
+spur_accounting_db_name: spur
+spur_accounting_db_user: spur
+spur_accounting_db_password: spur
+spur_accounting_port: 6819
+
+# Logging
+spur_log_level: info
+
+# Wipe Raft state on (re)deploy. Default false so re-runs/upgrades are non-destructive; set true for a fresh install.
+spur_wipe_state: false
+
+# HA mode is enabled automatically when groups['spur_controllers'] has more than one host.
+# In HA mode:
+#   - every controller is given a node_id (its 1-based position in groups['spur_controllers'])
+#   - spur.conf gets `peers = ["ctl1:6821", "ctl2:6821", ...]` (same order on every host)
+#   - agents are pointed at the FIRST controller; openraft forwards writes to the leader,
+#     but agents do not yet fail over to a different controller if the first one dies
+#     (Spur 0.3.0 limitation — `spurd --controller` takes a single URL). Put an L4 VIP /
+#     DNS round-robin in front of port 6817 for real failover. See README.
+spur_ha_enabled: "{{ (groups.get('spur_controllers', []) | length) > 1 }}"
+
+# Whether the controller node also runs spurd (lets controller be a compute target).
+# Auto: true if a host is in BOTH controller and agent groups.
+spur_controller_runs_agent: "{{ inventory_hostname in groups.get('spur_agents', []) and inventory_hostname in groups.get('spur_controllers', []) }}"

deploy/ansible/inventory/hosts.example.ini

@@ -0,0 +1,36 @@
+; ============================================================================
+; Spur Ansible inventory — examples for three deployment shapes.
+; Copy this file to hosts.ini and edit. Pick ONE shape per inventory file.
+; ============================================================================
+
+; --- Single-node (controller + agent on the same host) ----------------------
+; [spur_controllers]
+; node1 ansible_host=10.0.0.10 ansible_user=root
+;
+; [spur_agents]
+; node1 ansible_host=10.0.0.10 ansible_user=root
+
+; --- Multi-node, direct LAN transport ---------------------------------------
+; [spur_controllers]
+; ctl  ansible_host=10.0.0.10 ansible_user=root
+;
+; [spur_agents]
+; ctl    ansible_host=10.0.0.10 ansible_user=root  ; controller also runs an agent (optional)
+; gpu-1  ansible_host=10.0.0.11 ansible_user=root
+; gpu-2  ansible_host=10.0.0.12 ansible_user=root
+;
+; [all:vars]
+; spur_transport=direct
+
+; --- Multi-node, WireGuard mesh transport -----------------------------------
+; [spur_controllers]
+; ctl  ansible_host=ctl.example.com ansible_user=root spur_wg_address=10.44.0.1
+;
+; [spur_agents]
+; gpu-1 ansible_host=gpu1.example.com ansible_user=root spur_wg_address=10.44.0.2
+; gpu-2 ansible_host=gpu2.example.com ansible_user=root spur_wg_address=10.44.0.3
+;
+; [all:vars]
+; spur_transport=wireguard
+; spur_wg_cidr=10.44.0.0/16
+; spur_wg_port=51820

deploy/ansible/inventory/hosts.ha.example.ini

@@ -0,0 +1,36 @@
+; ============================================================================
+; HA Spur cluster — 3 controllers + N agents.
+;
+; Quorum math: tolerate floor((N-1)/2) controller failures.
+;   3 controllers → tolerates 1 failure
+;   5 controllers → tolerates 2 failures
+;
+; HA mode is auto-enabled when len(spur_controllers) > 1. The playbook:
+;   - assigns node_id = position-in-group (1-based)
+;   - writes `peers = ["ctl1:6821", "ctl2:6821", "ctl3:6821"]` to every controller's
+;     spur.conf in the SAME order (openraft requires this)
+;
+; CAVEAT: spurd --controller is single-target in Spur 0.3.0. Agents are pointed at
+; the first controller in the inventory. If THAT controller dies, agents lose
+; their connection even though the Raft cluster still has a leader. Put an
+; L4 VIP / DNS round-robin in front of the controllers' :6817 to get real
+; client-side failover, and set ansible_host to the VIP/DNS name on the first
+; controller (or override spur_controller_addr globally).
+; ============================================================================
+
+[spur_controllers]
+ctl-0 ansible_host=10.0.0.10 ansible_user=root
+ctl-1 ansible_host=10.0.0.11 ansible_user=root
+ctl-2 ansible_host=10.0.0.12 ansible_user=root
+
+[spur_agents]
+; Controllers can also be compute targets (small clusters):
+ctl-0 ansible_host=10.0.0.10 ansible_user=root
+ctl-1 ansible_host=10.0.0.11 ansible_user=root
+ctl-2 ansible_host=10.0.0.12 ansible_user=root
+; Dedicated workers:
+gpu-1 ansible_host=10.0.0.21 ansible_user=root
+gpu-2 ansible_host=10.0.0.22 ansible_user=root
+
+[all:vars]
+spur_transport=direct

deploy/ansible/requirements.yml

@@ -0,0 +1,9 @@
+---
+# Control-node collection dependencies.
+# Install with: ansible-galaxy collection install -r requirements.yml
+#
+# The ansible.utils ipaddr/ipmath filters also require the Python `netaddr`
+# library on the control node:  python3 -m pip install netaddr
+collections:
+  # Provides ansible.utils.ipaddr / ipmath used by the spur_wireguard role.
+  - name: ansible.utils

deploy/ansible/roles/spur_accounting/defaults/main.yml

@@ -0,0 +1,6 @@
+---
+spur_accounting_enabled: true
+spur_accounting_db_name: spur
+spur_accounting_db_user: spur
+spur_accounting_db_password: spur
+spur_accounting_port: 6819

deploy/ansible/roles/spur_accounting/tasks/main.yml

@@ -0,0 +1,102 @@
+---
+# Optional accounting stack: PostgreSQL + spurdbd. Runs on the first controller only
+# (accounting is a single service for the whole cluster). Everything is gated on
+# spur_accounting_enabled so `-e spur_accounting_enabled=false` skips the stack entirely.
+
+- name: Install PostgreSQL
+  ansible.builtin.apt:
+    name:
+      - postgresql
+      - postgresql-contrib
+    state: present
+    update_cache: true
+  when: spur_accounting_enabled | bool
+
+- name: Ensure PostgreSQL is enabled and started
+  ansible.builtin.service:
+    name: postgresql
+    enabled: true
+    state: started
+  when: spur_accounting_enabled | bool
+
+# The community.postgresql collection is not guaranteed to be installed on the
+# control node, so create the role/database with psql via `become_user: postgres`.
+# Both operations are made idempotent by checking for existence first.
+- name: Check whether the spur DB role exists
+  ansible.builtin.command: >-
+    psql -tAc "SELECT 1 FROM pg_roles WHERE rolname = '{{ spur_accounting_db_user }}'"
+  become: true
+  become_user: postgres
+  register: spur_db_role_check
+  changed_when: false
+  when: spur_accounting_enabled | bool
+
+- name: Create the spur DB role
+  ansible.builtin.command: >-
+    psql -c "CREATE ROLE {{ spur_accounting_db_user }} LOGIN PASSWORD '{{ spur_accounting_db_password }}'"
+  become: true
+  become_user: postgres
+  when:
+    - spur_accounting_enabled | bool
+    - spur_db_role_check.stdout | trim != "1"
+
+- name: Check whether the spur database exists
+  ansible.builtin.command: >-
+    psql -tAc "SELECT 1 FROM pg_database WHERE datname = '{{ spur_accounting_db_name }}'"
+  become: true
+  become_user: postgres
+  register: spur_db_check
+  changed_when: false
+  when: spur_accounting_enabled | bool
+
+- name: Create the spur database owned by the spur role
+  ansible.builtin.command: >-
+    psql -c "CREATE DATABASE {{ spur_accounting_db_name }} OWNER {{ spur_accounting_db_user }}"
+  become: true
+  become_user: postgres
+  when:
+    - spur_accounting_enabled | bool
+    - spur_db_check.stdout | trim != "1"
+
+- name: Verify spurdbd binary is present
+  ansible.builtin.stat:
+    path: "{{ spur_install_dir }}/spurdbd"
+  register: spurdbd_bin
+  when: spur_accounting_enabled | bool
+
+- name: Fail if spurdbd binary is missing
+  ansible.builtin.fail:
+    msg: >-
+      spurdbd binary not found at {{ spur_install_dir }}/spurdbd. The upstream
+      install.sh should install it alongside spur/spurctld/spurd — re-run the
+      installer or disable accounting with spur_accounting_enabled=false.
+  when:
+    - spur_accounting_enabled | bool
+    - not spurdbd_bin.stat.exists
+
+- name: Install spurdbd systemd unit
+  ansible.builtin.template:
+    src: spurdbd.service.j2
+    dest: /etc/systemd/system/spurdbd.service
+    mode: "0644"
+  register: spurdbd_unit
+  when: spur_accounting_enabled | bool
+
+- name: Reload systemd so the unit is picked up
+  ansible.builtin.systemd:
+    daemon_reload: true
+  when: spur_accounting_enabled | bool
+
+- name: Enable and (re)start spurdbd
+  ansible.builtin.systemd:
+    name: spurdbd
+    enabled: true
+    state: restarted
+  when: spur_accounting_enabled | bool
+
+- name: Wait for spurdbd to listen on {{ spur_accounting_port }}
+  ansible.builtin.wait_for:
+    port: "{{ spur_accounting_port }}"
+    host: "127.0.0.1"
+    timeout: 30
+  when: spur_accounting_enabled | bool

deploy/ansible/roles/spur_accounting/templates/spurdbd.service.j2

@@ -0,0 +1,16 @@
+[Unit]
+Description=Spur Accounting Daemon (spurdbd)
+After=network-online.target postgresql.service
+Wants=network-online.target
+Requires=postgresql.service
+
+[Service]
+Type=simple
+ExecStart={{ spur_install_dir }}/spurdbd --database-url postgresql://{{ spur_accounting_db_user }}:{{ spur_accounting_db_password }}@localhost/{{ spur_accounting_db_name }} --listen [::]:{{ spur_accounting_port }} --migrate --log-level {{ spur_log_level }}
+Restart=on-failure
+RestartSec=3
+User=root
+LimitNOFILE=65536
+
+[Install]
+WantedBy=multi-user.target

deploy/ansible/roles/spur_agent/defaults/main.yml

@@ -0,0 +1 @@
+---

deploy/ansible/roles/spur_agent/tasks/main.yml

@@ -0,0 +1,43 @@
+---
+- name: Resolve agent's advertised address
+  ansible.builtin.set_fact:
+    spur_agent_listen_ip: >-
+      {{ spur_wg_address if spur_transport == 'wireguard'
+         else (ansible_host | default(ansible_default_ipv4.address)) }}
+    spur_node_name: "{{ spur_node_name | default(ansible_hostname) }}"
+
+- name: Resolve controller address agents will talk to
+  # NOTE: spurd --controller takes a single URL in Spur 0.3.0. In HA mode we still
+  # point at the first controller — non-leader controllers forward writes via the
+  # Raft cluster. Real failover when ctl[0] dies needs a VIP / DNS in front of 6817.
+  ansible.builtin.set_fact:
+    spur_controller_addr: >-
+      {{ hostvars[groups['spur_controllers'][0]]['spur_wg_address']
+         if spur_transport == 'wireguard'
+         else hostvars[groups['spur_controllers'][0]]['ansible_host']
+              | default(hostvars[groups['spur_controllers'][0]]['ansible_default_ipv4']['address']) }}
+
+- name: Install spurd systemd unit
+  # WorkingDirectory in the unit is {{ spur_home }} so job stdout (spur-<N>.out)
+  # always lands there regardless of where the daemon was launched from.
+  ansible.builtin.template:
+    src: spurd.service.j2
+    dest: /etc/systemd/system/spurd.service
+    mode: "0644"
+  register: spurd_unit
+
+- name: Reload systemd so the unit is picked up
+  ansible.builtin.systemd:
+    daemon_reload: true
+
+- name: Enable and (re)start spurd
+  ansible.builtin.systemd:
+    name: spurd
+    enabled: true
+    state: restarted
+
+- name: Wait for spurd to listen on {{ spur_agent_port }}
+  ansible.builtin.wait_for:
+    port: "{{ spur_agent_port }}"
+    host: "127.0.0.1"
+    timeout: 30