proxcli 0.8.2__tar.gz → 0.9.0__tar.gz

{proxcli-0.8.2 → proxcli-0.9.0}/CHANGELOG.md

@@ -7,6 +7,25 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.9.0] - 2026-06-20
+
+### Added
+- **vm create cloud-init support**: ``--citype``, ``--ciuser``,
+  ``--cipassword``, ``--sshkeys`` (file path or inline),
+  ``--nameserver``, ``--searchdomain``, ``--cicustom``.
+- **vm create --import-from**: import an existing disk image from storage
+  as the VM's boot disk (e.g. ``--import-from local:import/deb12.qcow2``).
+  Requires a Proxmox storage with ``images`` or ``import`` content types.
+- **vm cloud-init drive auto-creation**: when cloud-init flags are used
+  on ``vm create``, an ``ide2`` cloud-init drive is automatically attached.
+  Proxmox VE 9 regenerates the ISO on config change — no separate generate step.
+- **vm cloudinit generate**: re-submits the current ``citype`` to trigger
+  regeneration.  Adapted for Proxmox VE 9 which removed the
+  ``POST /cloudinit`` endpoint.
+- **docs/cloud-init.md**: complete guide on creating and managing
+  cloud-init VMs with proxcli, including prerequisites, examples,
+  custom user-data, and troubleshooting.
+
 ## [0.8.2] - 2026-06-20
 
 ### Added
@@ -136,6 +155,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - CSRF ticket auto-refresh on 401.
 - AI-agent-friendly: default JSON output, strict exit codes, `--dry-run` mode.
 
+[0.9.0]: https://github.com/xezpeleta/proxcli/releases/tag/v0.9.0
 [0.8.2]: https://github.com/xezpeleta/proxcli/releases/tag/v0.8.2
 [0.8.1]: https://github.com/xezpeleta/proxcli/releases/tag/v0.8.1
 [0.8.0]: https://github.com/xezpeleta/proxcli/releases/tag/v0.8.0

{proxcli-0.8.2 → proxcli-0.9.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: proxcli
-Version: 0.8.2
+Version: 0.9.0
 Summary: A CLI tool to interact with Proxmox VE nodes and clusters via the REST API
 Author-email: Xabi Ezpeleta <xezpeleta@gmail.com>
 License: MIT

proxcli-0.9.0/docs/cloud-init.md

@@ -0,0 +1,255 @@
+# Cloud-Init VM Management with proxcli
+
+Cloud-init allows you to create and fully configure VMs declaratively — users,
+SSH keys, networking, and packages are defined via `proxcli` flags rather than
+manual post-install steps.
+
+## Prerequisites
+
+### 1. Storage with `images` and `import` content types
+
+You need a Proxmox storage that supports both `images` (for VM disks) and
+`import` (for uploading disk images).  On Proxmox VE, edit the storage in
+**Datacenter → Storage → Edit** and add the content types:
+
+- `Disk image` — to store VM disks
+- `ISO image` — optional, if you also want to store ISOs there
+
+Example: a `dir` type storage with path `/var/lib/vz` that has `images`, `iso`,
+and `import` enabled.
+
+Verify with:
+```bash
+proxmox storage list
+```
+
+Look for a storage where `content` includes `images` and (for uploads) `import`.
+
+### 2. Download a cloud-init image
+
+Cloud images are pre-built OS images with cloud-init installed.  You can find
+them at:
+
+- **Debian**: https://cloud.debian.org/images/cloud/bookworm/latest/
+  - File: `debian-12-genericcloud-amd64.qcow2` (333 MB)
+- **Ubuntu**: https://cloud-images.ubuntu.com/releases/24.04/release/
+  - File: `ubuntu-24.04-server-cloudimg-amd64.img` (593 MB)
+
+```bash
+# Download examples
+curl -LO https://cloud.debian.org/images/cloud/bookworm/latest/debian-12-genericcloud-amd64.qcow2
+curl -LO https://cloud-images.ubuntu.com/releases/noble/release/ubuntu-24.04-server-cloudimg-amd64.img
+```
+
+### 3. Upload the image to Proxmox storage
+
+```bash
+proxmox storage upload \
+  --node <node> \
+  --storage <storage> \
+  --content-type import \
+  --file debian-12-genericcloud-amd64.qcow2
+```
+
+After upload, the image will be available as `<storage>:import/<filename>`.
+You can verify with:
+
+```bash
+proxmox storage content <storage> --node <node>
+```
+
+---
+
+## Creating a Cloud-Init VM
+
+The complete workflow is a **single `vm create` command** — Proxmox handles
+disk import, cloud-init drive creation, and ISO generation automatically:
+
+```bash
+proxmox vm create \
+  --node sanmarko \
+  --memory 4096 \
+  --cores 2 \
+  --name my-cloud-vm \
+  --import-from local:import/debian-12-genericcloud-amd64.qcow2 \
+  --citype nocloud \
+  --ciuser debian \
+  --cipassword 'SecurePassword123!' \
+  --sshkeys ~/.ssh/id_rsa.pub \
+  --nameserver 1.1.1.1 \
+  --searchdomain mydomain.lan \
+  --net 'virtio,bridge=vmbr0'
+```
+
+### Flag reference
+
+| Flag | Description |
+|------|-------------|
+| `--import-from <storage:path>` | Import the boot disk from an existing volume |
+| `--citype nocloud\|configdrive2` | Cloud-init data source type |
+| `--ciuser <username>` | Default user (e.g. `debian`, `ubuntu`) |
+| `--cipassword <password>` | User password (hashed by cloud-init) |
+| `--sshkeys <file\|inline>` | SSH public keys (reads file if it exists, otherwise uses inline) |
+| `--nameserver <ip>` | DNS server |
+| `--searchdomain <domain>` | DNS search domain |
+| `--cicustom <config>` | Custom cloud-init config (`user=...,vendor=...`) |
+| `--storage <name>` | Target storage for the imported disk (defaults to `rbd_ssd`) |
+
+### What happens
+
+1. Proxmox assigns a VM ID (or use `--vmid` to specify)
+2. The cloud image is **streamed from the import storage to the target storage**
+   and attached as `scsi0`
+3. A cloud-init drive is created (`ide2`) with the configured user, password,
+   SSH keys, and network settings
+4. The VM is created in *stopped* state, ready to start
+
+### Verify the configuration
+
+```bash
+proxmox vm show <vmid>
+```
+
+The output includes:
+- `scsi0` pointing to the imported disk on the target storage
+- `citype`, `ciuser`, `cipassword`, `nameserver`, etc.
+- `ide2` with the cloud-init ISO
+
+---
+
+## Managing Cloud-Init VMs
+
+### Updating cloud-init configuration
+
+After the VM is created, you can update cloud-init parameters using
+`PUT /nodes/{node}/qemu/{vmid}/config` (no dedicated proxcli command yet):
+
+```bash
+# Currently via curl; a proxcli vm update command is planned
+# This triggers automatic cloud-init ISO regeneration in Proxmox VE 9
+```
+
+In Proxmox VE 9+, the cloud-init ISO is **regenerated automatically** whenever
+cloud-init config parameters change.  There is no separate "generate" step.
+
+### Dumping current cloud-init config
+
+```bash
+proxmox vm cloudinit generate <vmid>
+```
+
+This reads the current `citype` from the VM config and re-submits it to
+trigger regeneration.  (In Proxmox VE 9, config changes auto-regenerate,
+but this command is provided for environments where explicit generation
+is needed.)
+
+### Starting the VM
+
+```bash
+proxmox vm start <vmid>
+```
+
+On first boot, cloud-init will:
+1. Set the hostname
+2. Create the specified user with the given password
+3. Install the SSH keys
+4. Configure networking
+5. Run any `#cloud-config` directives (if using `--cicustom`)
+
+---
+
+## Complete Example: Debian 12 Cloud VM
+
+```bash
+# 1. Upload the cloud image (one-time)
+proxmox storage upload \
+  --node sanmarko --storage local --content-type import \
+  --file debian-12-genericcloud-amd64.qcow2
+
+# 2. Create the VM
+proxmox vm create \
+  --node sanmarko \
+  --name webserver \
+  --memory 4096 --cores 2 \
+  --import-from local:import/debian-12-genericcloud-amd64.qcow2 \
+  --citype nocloud \
+  --ciuser debian \
+  --cipassword 'ChangeMe123!' \
+  --sshkeys ~/.ssh/id_rsa.pub \
+  --nameserver 1.1.1.1 \
+  --searchdomain tknika.net \
+  --net 'virtio,bridge=vmbr0'
+
+# 3. Start it
+proxmox vm start <vmid>
+
+# 4. SSH in (after boot completes)
+ssh debian@<ip>
+```
+
+---
+
+## Custom Cloud-Init Config
+
+For advanced customization (packages, runcmd, write_files), use `--cicustom`
+with a user-data YAML file:
+
+```bash
+proxmox vm create \
+  ... \
+  --cicustom 'user=local:snippets/user-data.yaml'
+```
+
+Upload the snippet first:
+```bash
+proxmox storage upload \
+  --node sanmarko --storage local --content-type snippets \
+  --file user-data.yaml
+```
+
+Example `user-data.yaml`:
+```yaml
+#cloud-config
+packages:
+  - nginx
+  - htop
+  - curl
+
+package_update: true
+package_upgrade: true
+
+runcmd:
+  - systemctl enable --now nginx
+  - echo "Hello from cloud-init" > /etc/motd
+```
+
+---
+
+## Troubleshooting
+
+### "storage does not support 'import' content"
+
+Your storage only has `iso` or `images` enabled.  Go to **Datacenter → Storage**
+in the Proxmox UI and add `Disk image` and `Import` content types to the storage.
+
+### "has wrong type 'iso' - needs to be 'images' or 'import'"
+
+You uploaded the image with `--content-type iso` instead of `--content-type import`.
+Re-upload with the correct content type, or change the storage's content types.
+
+### "Only root can pass arbitrary filesystem paths"
+
+The `import-from` parameter uses a **volume ID** (`local:import/file.qcow2`),
+not a filesystem path (`/var/lib/vz/...`).  Make sure the image is uploaded to
+Proxmox storage first via `storage upload`.
+
+### Cloud-init not running on boot
+
+Check that the cloud-init drive is attached:
+```bash
+proxmox vm show <vmid>
+# Look for: ide2: local:XXX/vm-XXX-cloudinit.qcow2,media=cdrom
+```
+
+If missing, the cloud-init drive wasn't created.  This happens when no
+cloud-init flags (`--ciuser`, `--citype`, etc.) are passed to `vm create`.

{proxcli-0.8.2 → proxcli-0.9.0}/proxmox/cli/vm.py

@@ -44,6 +44,16 @@ def register_vm_parser(subparsers: argparse._SubParsersAction) -> None:
     vm_create.add_argument("--machine", default=None, help="Machine type (e.g. q35)")
     vm_create.add_argument("--boot", default=None, help="Boot order (e.g. order=cd;net)")
     vm_create.add_argument("--disk", default=None, help="Disk size (e.g. 32G). Uses --storage if set, else local-lvm.")
+    vm_create.add_argument("--citype", default=None, choices=["nocloud", "configdrive2"],
+                           help="Cloud-init type")
+    vm_create.add_argument("--ciuser", default=None, help="Cloud-init user")
+    vm_create.add_argument("--cipassword", default=None, help="Cloud-init password")
+    vm_create.add_argument("--sshkeys", default=None, help="Cloud-init SSH public keys (file path or inline)")
+    vm_create.add_argument("--nameserver", default=None, help="Cloud-init DNS server")
+    vm_create.add_argument("--searchdomain", default=None, help="Cloud-init DNS search domain")
+    vm_create.add_argument("--cicustom", default=None, help="Cloud-init custom config (user=...,vendor=...)")
+    vm_create.add_argument("--import-from", default=None, dest="import_from",
+                           help="Import disk from existing volume (e.g. local:import/deb12.qcow2)")
     vm_create.set_defaults(func=_vm_create)
 
     # --- vm start ---
@@ -133,6 +143,15 @@ def register_vm_parser(subparsers: argparse._SubParsersAction) -> None:
     agent_ifaces.add_argument("--node", help="Node name (auto-detected if omitted)")
     agent_ifaces.set_defaults(func=_vm_agent_interfaces)
 
+    # --- cloudinit ---
+    cloudinit = vm_sub.add_parser("cloudinit", help="Manage cloud-init")
+    cloudinit_sub = cloudinit.add_subparsers(dest="cloudinit_action", title="cloud-init actions", required=True)
+
+    ci_generate = cloudinit_sub.add_parser("generate", help="Regenerate cloud-init ISO from current config")
+    ci_generate.add_argument("vmid", type=vmid_type, help="VM ID")
+    ci_generate.add_argument("--node", help="Node name (auto-detected if omitted)")
+    ci_generate.set_defaults(func=_vm_cloudinit_generate)
+
     # --- firewall ---
     fw = vm_sub.add_parser("firewall", help="Manage VM firewall")
     fw_sub = fw.add_subparsers(dest="fw_resource", title="resources", required=True)
@@ -312,6 +331,46 @@ def _vm_create(args: argparse.Namespace, client: ProxmoxClient) -> dict:
         else:
             disk_raw = args.disk
         data["scsi0"] = disk_raw.replace("=", "%3D").replace(":", "%3A").replace(",", "%2C")
+    elif args.import_from:
+        # Import from existing volume: storage_id=0,import-from=<volid>
+        parts = args.import_from.split(":", 1)
+        if len(parts) == 2:
+            src_storage, src_file = parts
+        else:
+            return {"error": f"Invalid import-from format: {args.import_from}. Use <storage>:<path>"}
+        # Build: dst_storage:0,import-from=src_storage:path
+        target_storage = args.storage or "rbd_ssd"
+        import_raw = f"{target_storage}:0,import-from={args.import_from}"
+        data["scsi0"] = import_raw.replace("=", "%3D").replace(":", "%3A").replace(",", "%2C")
+
+    # Cloud-init
+    cloudinit_used = bool(args.citype or args.ciuser or args.cipassword or args.sshkeys
+                        or args.nameserver or args.searchdomain or args.cicustom)
+    if args.citype:
+        data["citype"] = args.citype
+    if args.ciuser:
+        data["ciuser"] = args.ciuser
+    if args.cipassword:
+        data["cipassword"] = args.cipassword
+    if args.nameserver:
+        data["nameserver"] = args.nameserver
+    if args.searchdomain:
+        data["searchdomain"] = args.searchdomain
+    if args.cicustom:
+        data["cicustom"] = args.cicustom
+    if args.sshkeys:
+        # sshkeys can be a file path or inline content
+        try:
+            with open(args.sshkeys) as f:
+                sshkeys_value = f.read().strip()
+        except (OSError, FileNotFoundError):
+            sshkeys_value = args.sshkeys
+        # URL-encode the SSH keys for form body
+        # Replace newlines with %0A
+        data["sshkeys"] = sshkeys_value.replace("\n", "%0A").replace("\r", "%0D").replace("=", "%3D").replace(",", "%2C").replace(":", "%3A")
+    # Add cloud-init drive if cloud-init is being used and no cdrom is set
+    if cloudinit_used and not args.cdrom:
+        data["ide2"] = "local:cloudinit,media=cdrom"
 
     # Build form-encoded body manually — httpx's data= would double-encode %
     from urllib.parse import urlencode
@@ -396,6 +455,34 @@ def _vm_agent_interfaces(args: argparse.Namespace, client: ProxmoxClient) -> dic
     return result
 
 
+# ---------------------------------------------------------------------------
+# VM cloud-init handlers
+# ---------------------------------------------------------------------------
+
+def _vm_cloudinit_generate(args: argparse.Namespace, client: ProxmoxClient) -> dict:
+    """Regenerate the cloud-init ISO from the VM's current cloud-init config.
+
+    In Proxmox VE 9, cloud-init ISOs are regenerated automatically when
+    config changes. This triggers regeneration by re-setting the citype.
+    """
+    node = _resolve_node(client, args.node, args.vmid)
+    if not node:
+        return {"error": f"VM {args.vmid} not found"}
+    # Proxmox VE 9 regenerates cloud-init on config change.
+    # Re-submit the current citype to trigger regeneration.
+    config = client.get(f"/nodes/{node}/qemu/{args.vmid}/config")
+    if not isinstance(config, dict):
+        return {"error": f"Could not read config for VM {args.vmid}"}
+    citype = config.get("citype")
+    if not citype:
+        return {"error": f"VM {args.vmid} has no cloud-init configured (missing citype)"}
+    result = client.put(
+        f"/nodes/{node}/qemu/{args.vmid}/config",
+        data={"citype": citype},
+    )
+    return {"data": result} if isinstance(result, (str, type(None))) or not isinstance(result, dict) else result
+
+
 # ---------------------------------------------------------------------------
 # VM snapshot handlers
 # ---------------------------------------------------------------------------

{proxcli-0.8.2 → proxcli-0.9.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "proxcli"
-version = "0.8.2"
+version = "0.9.0"
 description = "A CLI tool to interact with Proxmox VE nodes and clusters via the REST API"
 readme = "README.md"
 authors = [

{proxcli-0.8.2 → proxcli-0.9.0}/uv.lock

@@ -254,7 +254,7 @@ wheels = [
 
 [[package]]
 name = "proxcli"
-version = "0.8.2"
+version = "0.9.0"
 source = { editable = "." }
 dependencies = [
     { name = "httpx" },