arcane-mage 2.0.0__tar.gz → 2.2.0__tar.gz

{arcane_mage-2.0.0 → arcane_mage-2.2.0}/.gitignore

@@ -15,3 +15,4 @@ dev
 fluxnodes*.yaml
 .DS_Store
 .ruff_cache
+*.log

{arcane_mage-2.0.0 → arcane_mage-2.2.0}/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 2.1.0
+
+### Added
+
+- **`FluxnodeConfig.dev_token`**: optional dev-channel enrolment token, written to the autoinstall config next to the identity it is bound to; the installer verifies it
+
 ## 2.0.0
 
 ### Breaking Changes

{arcane_mage-2.0.0 → arcane_mage-2.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: arcane-mage
-Version: 2.0.0
+Version: 2.2.0
 Summary: Automation helper for Fluxnodes
 Author-email: David White <david@runonflux.io>
 License-File: LICENSE

arcane_mage-2.2.0/ansible_collection/runonflux/arcane_mage/README.md

@@ -0,0 +1,108 @@
+# Ansible Collection: runonflux.arcane_mage
+
+Ansible collection for provisioning ArcaneOS FluxNodes on Proxmox hypervisors using the [arcane-mage](https://github.com/RunOnFlux/arcane-mage) library.
+
+## Requirements
+
+- Python >= 3.13 on the Ansible controller
+- `arcane-mage >= 2.0.0` (`pip install arcane-mage`)
+- Proxmox VE >= 8.4.1
+- Proxmox API token with appropriate permissions
+
+## Installation
+
+### From source (development)
+
+```bash
+cd arcane-mage/ansible_collection/runonflux/arcane_mage
+ansible-galaxy collection build
+ansible-galaxy collection install runonflux-arcane_mage-*.tar.gz
+```
+
+### Using collections path
+
+Add the path to your `ansible.cfg`:
+
+```ini
+[defaults]
+collections_path = /path/to/arcane-mage/ansible_collection
+```
+
+## Modules
+
+| Module | Description |
+|--------|-------------|
+| `runonflux.arcane_mage.provision` | Provision an ArcaneOS FluxNode VM (UEFI, TPM 2.0, config disk) |
+| `runonflux.arcane_mage.deprovision` | Stop and delete a FluxNode VM |
+| `runonflux.arcane_mage.status` | Check VM status on a Proxmox node |
+| `runonflux.arcane_mage.validate` | Pre-flight validation (API, storage, ISO, network) |
+| `runonflux.arcane_mage.iso_info` | Get latest ArcaneOS ISO version, optionally download it |
+
+All modules use `delegate_to: localhost` since they communicate with Proxmox via its REST API.
+
+## Quick Start
+
+```yaml
+- name: Provision FluxNodes
+  hosts: proxmox_hosts
+  gather_facts: no
+  tasks:
+    - name: Get latest ISO
+      runonflux.arcane_mage.iso_info:
+      delegate_to: localhost
+      register: iso
+      run_once: true
+
+    - name: Download ISO to host
+      runonflux.arcane_mage.iso_info:
+        api_url: "https://{{ ansible_host }}:8006"
+        api_token: "{{ proxmox_token }}"
+        node: "{{ inventory_hostname | lower }}"
+        download: true
+      delegate_to: localhost
+
+    - name: Validate host is ready
+      runonflux.arcane_mage.validate:
+        api_url: "https://{{ ansible_host }}:8006"
+        api_token: "{{ proxmox_token }}"
+        node: "{{ inventory_hostname | lower }}"
+        network: vmbr4000
+        iso_name: "{{ iso.iso_name }}"
+      delegate_to: localhost
+
+    - name: Provision FluxNode
+      runonflux.arcane_mage.provision:
+        api_url: "https://{{ ansible_host }}:8006"
+        api_token: "{{ proxmox_token }}"
+        node: "{{ inventory_hostname | lower }}"
+        vm_name: "{{ inventory_hostname | lower }}-vs{{ idx + 1 }}"
+        node_tier: stratus
+        network: vmbr4000
+        iso_name: "{{ iso.iso_name }}"
+        hostname: "{{ inventory_hostname | lower }}-vs{{ idx + 1 }}"
+        console_password: "{{ console_password }}"
+        flux_id: "{{ flux_id }}"
+        identity_key: "{{ identity_key }}"
+        tx_id: "{{ tx_id }}"
+        output_id: "{{ output_id }}"
+        ip_allocation: static
+        ip_address: "{{ item }}/27"
+        gateway: "49.12.156.225"
+        start: true
+      delegate_to: localhost
+      loop: "{{ vswitch_vm_ips }}"
+      loop_control:
+        index_var: idx
+```
+
+## Node Tiers
+
+| Tier | Cores | RAM | Disk |
+|------|-------|-----|------|
+| cumulus | 4 | 8 GB | 220 GB |
+| nimbus | 8 | 32 GB | 440 GB |
+| stratus | 16 | 64 GB | 880 GB |
+
+## License
+
+MIT

arcane_mage-2.2.0/ansible_collection/runonflux/arcane_mage/galaxy.yml

@@ -0,0 +1,21 @@
+namespace: runonflux
+name: arcane_mage
+version: 1.0.0
+readme: README.md
+authors:
+  - RunOnFlux <info@runonflux.io>
+description: Ansible collection for provisioning ArcaneOS FluxNodes on Proxmox via arcane-mage
+license_file: ../../../LICENSE
+tags:
+  - proxmox
+  - fluxnode
+  - arcaneos
+  - provisioning
+  - automation
+repository: https://github.com/RunOnFlux/arcane-mage
+documentation: https://github.com/RunOnFlux/arcane-mage
+homepage: https://runonflux.com
+issues: https://github.com/RunOnFlux/arcane-mage/issues
+build_ignore:
+  - "*.pyc"
+  - __pycache__

arcane_mage-2.2.0/ansible_collection/runonflux/arcane_mage/meta/runtime.yml

@@ -0,0 +1 @@
+requires_ansible: ">=2.14.0"

arcane_mage-2.2.0/ansible_collection/runonflux/arcane_mage/plugins/modules/deprovision.py

@@ -0,0 +1,165 @@
+#!/usr/bin/python
+# -*- coding: utf-8 -*-
+
+# Copyright: (c) 2025, RunOnFlux
+# License: MIT
+
+DOCUMENTATION = r"""
+---
+module: deprovision
+short_description: Remove a FluxNode VM from Proxmox
+version_added: "1.0.0"
+description:
+  - Stops a running VM and deletes it along with all its disks.
+  - Idempotent — succeeds if the VM does not exist.
+  - Target VM by name or ID.
+options:
+  api_url:
+    description: Proxmox API URL.
+    required: true
+    type: str
+  api_token:
+    description: Proxmox API token in format C(user@realm!tokenname=tokenvalue).
+    required: true
+    type: str
+    no_log: true
+  verify_ssl:
+    description: Whether to verify SSL certificates.
+    type: bool
+    default: false
+  node:
+    description: Proxmox cluster node name.
+    required: true
+    type: str
+  vm_name:
+    description: Name of the VM to deprovision. Mutually exclusive with I(vm_id).
+    type: str
+  vm_id:
+    description: ID of the VM to deprovision. Mutually exclusive with I(vm_name).
+    type: int
+requirements:
+  - "python >= 3.13"
+  - "arcane-mage >= 2.0.0"
+author:
+  - RunOnFlux
+"""
+
+EXAMPLES = r"""
+- name: Remove a FluxNode VM by name
+  runonflux.arcane_mage.deprovision:
+    api_url: "https://65.109.86.37:8006"
+    api_token: "{{ proxmox_token }}"
+    node: tsa
+    vm_name: tsa-vs1
+  delegate_to: localhost
+
+- name: Remove a FluxNode VM by ID
+  runonflux.arcane_mage.deprovision:
+    api_url: "https://65.109.86.37:8006"
+    api_token: "{{ proxmox_token }}"
+    node: tsa
+    vm_id: 200
+  delegate_to: localhost
+"""
+
+RETURN = r"""
+deprovision_log:
+  description: List of deprovision step messages.
+  type: list
+  elements: str
+  returned: always
+"""
+
+import asyncio
+
+from ansible.module_utils.basic import AnsibleModule
+
+
+async def run_deprovision(params):
+    """Execute the deprovisioning workflow."""
+    from arcane_mage import Provisioner, ProxmoxApi
+
+    token = ProxmoxApi.parse_token(params["api_token"])
+    if not token:
+        return False, ["Invalid API token format. Expected: user@realm!tokenname=tokenvalue"]
+
+    api = ProxmoxApi.from_token(params["api_url"], token, verify_ssl=params["verify_ssl"])
+
+    log_messages = []
+
+    def callback(ok, msg):
+        log_messages.append(f"{'OK' if ok else 'FAIL'}: {msg}")
+
+    async with api:
+        provisioner = Provisioner(api)
+
+        # Check if VM exists first
+        vms_res = await api.get_vms(params["node"])
+        if not vms_res:
+            return False, ["Unable to list VMs on node"]
+
+        vm_name = params.get("vm_name")
+        vm_id = params.get("vm_id")
+
+        if vm_name:
+            existing = next((v for v in vms_res.payload if v.get("name") == vm_name), None)
+        else:
+            existing = next((v for v in vms_res.payload if v.get("vmid") == vm_id), None)
+
+        if not existing:
+            identifier = vm_name or str(vm_id)
+            return True, [f"VM '{identifier}' does not exist — nothing to do"]
+
+        success = await provisioner.deprovision_vm(
+            params["node"],
+            callback=callback,
+            vm_name=vm_name,
+            vm_id=vm_id,
+        )
+
+    return success, log_messages
+
+
+def main():
+    module_args = dict(
+        api_url=dict(type="str", required=True),
+        api_token=dict(type="str", required=True, no_log=True),
+        verify_ssl=dict(type="bool", default=False),
+        node=dict(type="str", required=True),
+        vm_name=dict(type="str"),
+        vm_id=dict(type="int"),
+    )
+
+    module = AnsibleModule(
+        argument_spec=module_args,
+        mutually_exclusive=[("vm_name", "vm_id")],
+        required_one_of=[("vm_name", "vm_id")],
+        supports_check_mode=True,
+    )
+
+    if module.check_mode:
+        module.exit_json(changed=False, deprovision_log=["Check mode — no changes made"])
+
+    try:
+        success, log_messages = asyncio.run(run_deprovision(module.params))
+    except ImportError:
+        module.fail_json(msg="arcane-mage library is not installed. Install with: pip install arcane-mage")
+    except Exception as e:
+        module.fail_json(msg=f"Deprovision error: {e}")
+
+    if not success:
+        module.fail_json(
+            msg="Failed to deprovision VM",
+            deprovision_log=log_messages,
+        )
+
+    already_absent = any("does not exist" in m for m in log_messages)
+
+    module.exit_json(
+        changed=not already_absent,
+        deprovision_log=log_messages,
+    )
+
+
+if __name__ == "__main__":
+    main()

arcane_mage-2.2.0/ansible_collection/runonflux/arcane_mage/plugins/modules/iso_info.py

@@ -0,0 +1,178 @@
+#!/usr/bin/python
+# -*- coding: utf-8 -*-
+
+# Copyright: (c) 2025, RunOnFlux
+# License: MIT
+
+DOCUMENTATION = r"""
+---
+module: iso_info
+short_description: Get the latest ArcaneOS ISO version
+version_added: "1.0.0"
+description:
+  - Queries the Flux release API for the latest ArcaneOS ISO filename.
+  - Optionally downloads the ISO to a Proxmox node via the Proxmox API.
+  - Useful for ensuring all hosts have the latest ISO before provisioning.
+options:
+  api_url:
+    description: >
+      Proxmox API URL. Required only when I(download=true).
+    type: str
+  api_token:
+    description: >
+      Proxmox API token. Required only when I(download=true).
+    type: str
+    no_log: true
+  verify_ssl:
+    description: Whether to verify SSL certificates.
+    type: bool
+    default: false
+  node:
+    description: >
+      Proxmox cluster node name. Required when I(download=true).
+    type: str
+  storage_iso:
+    description: Storage backend for ISO files.
+    type: str
+    default: local
+  download:
+    description: >
+      Whether to download the latest ISO to the Proxmox node.
+      Uses the Proxmox API download-url endpoint.
+    type: bool
+    default: false
+requirements:
+  - "python >= 3.13"
+  - "arcane-mage >= 2.0.0"
+author:
+  - RunOnFlux
+"""
+
+EXAMPLES = r"""
+- name: Get latest ISO version
+  runonflux.arcane_mage.iso_info:
+  delegate_to: localhost
+  register: iso_result
+
+- name: Download latest ISO to Proxmox node
+  runonflux.arcane_mage.iso_info:
+    api_url: "https://65.109.86.37:8006"
+    api_token: "{{ proxmox_token }}"
+    node: tsa
+    download: true
+  delegate_to: localhost
+
+- name: Use ISO name in provisioning
+  runonflux.arcane_mage.provision:
+    iso_name: "{{ iso_result.iso_name }}"
+    # ... other params
+  delegate_to: localhost
+"""
+
+RETURN = r"""
+iso_name:
+  description: The latest ISO filename (e.g., FluxLive-1775071308.iso).
+  type: str
+  returned: success
+downloaded:
+  description: Whether the ISO was downloaded to the node.
+  type: bool
+  returned: always
+"""
+
+import asyncio
+
+from ansible.module_utils.basic import AnsibleModule
+
+
+async def run_iso_info(params):
+    """Fetch latest ISO info and optionally download."""
+    from arcane_mage import ProxmoxApi, get_latest_iso_version
+
+    iso_name = await get_latest_iso_version()
+
+    if not iso_name:
+        return False, None, False, "Unable to fetch latest ISO version from release API"
+
+    if not params.get("download"):
+        return True, iso_name, False, ""
+
+    # Download to Proxmox node
+    if not params.get("api_url") or not params.get("api_token") or not params.get("node"):
+        return False, iso_name, False, "api_url, api_token, and node are required for download"
+
+    token = ProxmoxApi.parse_token(params["api_token"])
+    if not token:
+        return False, iso_name, False, "Invalid API token format"
+
+    api = ProxmoxApi.from_token(params["api_url"], token, verify_ssl=params["verify_ssl"])
+
+    async with api:
+        # Check if ISO already exists
+        content_res = await api.get_storage_content(params["node"], params["storage_iso"])
+        if content_res:
+            existing = next(
+                (c for c in content_res.payload if c.get("volid", "").endswith(iso_name)),
+                None,
+            )
+            if existing:
+                return True, iso_name, False, ""
+
+        # Download via Proxmox API (direct POST without verify-certificates param)
+        # URL format: https://images.runonflux.io/arcane/releases/<build>/FluxLive-<build>.iso
+        build_id = iso_name.replace("FluxLive-", "").replace(".iso", "")
+        download_url = f"https://images.runonflux.io/arcane/releases/{build_id}/{iso_name}"
+
+        endpoint = f"nodes/{params['node']}/storage/{params['storage_iso']}/download-url"
+        data = {"content": "iso", "filename": iso_name, "url": download_url}
+
+        res = await api._do_post(endpoint, data=data)
+
+        if not res:
+            error_detail = f"status={res.status} error={res.error}" if res else "no response"
+            return False, iso_name, False, f"Failed to initiate ISO download: {error_detail}"
+
+        # Wait for download task
+        ok = await api.wait_for_task(res.payload, params["node"], max_wait_s=600)
+        if not ok:
+            return False, iso_name, False, "ISO download task did not complete in time"
+
+    return True, iso_name, True, ""
+
+
+def main():
+    module_args = dict(
+        api_url=dict(type="str"),
+        api_token=dict(type="str", no_log=True),
+        verify_ssl=dict(type="bool", default=False),
+        node=dict(type="str"),
+        storage_iso=dict(type="str", default="local"),
+        download=dict(type="bool", default=False),
+    )
+
+    module = AnsibleModule(
+        argument_spec=module_args,
+        required_if=[
+            ("download", True, ["api_url", "api_token", "node"]),
+        ],
+        supports_check_mode=True,
+    )
+
+    if module.check_mode:
+        module.exit_json(changed=False, iso_name="", downloaded=False)
+
+    try:
+        success, iso_name, downloaded, error = asyncio.run(run_iso_info(module.params))
+    except ImportError:
+        module.fail_json(msg="arcane-mage library is not installed. Install with: pip install arcane-mage")
+    except Exception as e:
+        module.fail_json(msg=f"ISO info error: {e}")
+
+    if not success:
+        module.fail_json(msg=error, iso_name=iso_name or "")
+
+    module.exit_json(changed=downloaded, iso_name=iso_name, downloaded=downloaded)
+
+
+if __name__ == "__main__":
+    main()