Add coder/proxmox-vm/Readme.md
This commit is contained in:
161
coder/proxmox-vm/Readme.md
Normal file
161
coder/proxmox-vm/Readme.md
Normal file
@@ -0,0 +1,161 @@
|
|||||||
|
---
|
||||||
|
display_name: Proxmox VM
|
||||||
|
description: Provision VMs on Proxmox VE as Coder workspaces
|
||||||
|
icon: ../../../../.icons/proxmox.svg
|
||||||
|
verified: false
|
||||||
|
tags: [proxmox, vm, cloud-init, qemu]
|
||||||
|
---
|
||||||
|
|
||||||
|
# Proxmox VM Template for Coder
|
||||||
|
|
||||||
|
Provision Linux VMs on Proxmox as [Coder workspaces](https://coder.com/docs/workspaces). The template clones a cloud‑init base image, injects user‑data via Snippets, and runs the Coder agent under the workspace owner's Linux user.
|
||||||
|
|
||||||
|
## Prerequisites
|
||||||
|
|
||||||
|
- Proxmox VE 8/9
|
||||||
|
- Proxmox API token with access to nodes and storages
|
||||||
|
- SSH access from Coder provisioner to Proxmox VE
|
||||||
|
- Storage with "Snippets" content enabled
|
||||||
|
- Ubuntu cloud‑init image/template on Proxmox
|
||||||
|
- Latest images: https://cloud-images.ubuntu.com/ ([source](https://cloud-images.ubuntu.com/))
|
||||||
|
|
||||||
|
## Prepare a Proxmox Cloud‑Init Template (once)
|
||||||
|
|
||||||
|
Run on the Proxmox node. This uses a RELEASE variable so you always pull a current image.
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Choose a release (e.g., jammy or noble)
|
||||||
|
RELEASE=jammy
|
||||||
|
IMG_URL="https://cloud-images.ubuntu.com/${RELEASE}/current/${RELEASE}-server-cloudimg-amd64.img"
|
||||||
|
IMG_PATH="/var/lib/vz/template/iso/${RELEASE}-server-cloudimg-amd64.img"
|
||||||
|
|
||||||
|
# Download cloud image
|
||||||
|
wget "$IMG_URL" -O "$IMG_PATH"
|
||||||
|
|
||||||
|
# Create base VM (example ID 999), enable QGA, correct boot order
|
||||||
|
NAME="ubuntu-${RELEASE}-cloudinit"
|
||||||
|
qm create 999 --name "$NAME" --memory 4096 --cores 2 \
|
||||||
|
--net0 virtio,bridge=vmbr0 --agent enabled=1
|
||||||
|
qm set 999 --scsihw virtio-scsi-pci
|
||||||
|
qm importdisk 999 "$IMG_PATH" local-lvm
|
||||||
|
qm set 999 --scsi0 local-lvm:vm-999-disk-0
|
||||||
|
qm set 999 --ide2 local-lvm:cloudinit
|
||||||
|
qm set 999 --serial0 socket --vga serial0
|
||||||
|
qm set 999 --boot 'order=scsi0;ide2;net0'
|
||||||
|
|
||||||
|
# Enable Snippets on storage 'local' (one‑time)
|
||||||
|
pvesm set local --content snippets,vztmpl,backup,iso
|
||||||
|
|
||||||
|
# Convert to template
|
||||||
|
qm template 999
|
||||||
|
```
|
||||||
|
|
||||||
|
Verify:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
qm config 999 | grep -E 'template:|agent:|boot:|ide2:|scsi0:'
|
||||||
|
```
|
||||||
|
|
||||||
|
### Enable Snippets via GUI
|
||||||
|
|
||||||
|
- Datacenter → Storage → select `local` → Edit → Content → check "Snippets" → OK
|
||||||
|
- Ensure `/var/lib/vz/snippets/` exists on the node for snippet files
|
||||||
|
- Template page → Cloud‑Init → Snippet Storage: `local` → File: your yml → Apply
|
||||||
|
|
||||||
|
## Configure this template
|
||||||
|
|
||||||
|
Edit `terraform.tfvars` with your environment:
|
||||||
|
|
||||||
|
```hcl
|
||||||
|
# Proxmox API
|
||||||
|
proxmox_api_url = "https://<PVE_HOST>:8006/api2/json"
|
||||||
|
proxmox_api_token_id = "<USER@REALM>!<TOKEN>"
|
||||||
|
proxmox_api_token_secret = "<SECRET>"
|
||||||
|
|
||||||
|
# SSH to the node (for snippet upload)
|
||||||
|
proxmox_host = "<PVE_HOST>"
|
||||||
|
proxmox_password = "<NODE_ROOT_OR_SUDO_PASSWORD>"
|
||||||
|
proxmox_ssh_user = "root"
|
||||||
|
|
||||||
|
# Infra defaults
|
||||||
|
proxmox_node = "pve"
|
||||||
|
disk_storage = "local-lvm"
|
||||||
|
snippet_storage = "local"
|
||||||
|
bridge = "vmbr0"
|
||||||
|
vlan = 0
|
||||||
|
clone_template_vmid = 999
|
||||||
|
```
|
||||||
|
|
||||||
|
### Variables (terraform.tfvars)
|
||||||
|
|
||||||
|
- These values are standard Terraform variables that the template reads at apply time.
|
||||||
|
- Place secrets (e.g., `proxmox_api_token_secret`, `proxmox_password`) in `terraform.tfvars` or inject with environment variables using `TF_VAR_*` (e.g., `TF_VAR_proxmox_api_token_secret`).
|
||||||
|
- You can also override with `-var`/`-var-file` if you run Terraform directly. With Coder, the repo's `terraform.tfvars` is bundled when pushing the template.
|
||||||
|
|
||||||
|
Variables expected:
|
||||||
|
|
||||||
|
- `proxmox_api_url`, `proxmox_api_token_id`, `proxmox_api_token_secret` (sensitive)
|
||||||
|
- `proxmox_host`, `proxmox_password` (sensitive), `proxmox_ssh_user`
|
||||||
|
- `proxmox_node`, `disk_storage`, `snippet_storage`, `bridge`, `vlan`, `clone_template_vmid`
|
||||||
|
- Coder parameters: `cpu_cores`, `memory_mb`, `disk_size_gb`
|
||||||
|
|
||||||
|
## Proxmox API Token (GUI/CLI)
|
||||||
|
|
||||||
|
Docs: https://pve.proxmox.com/wiki/User_Management#pveum_tokens
|
||||||
|
|
||||||
|
GUI:
|
||||||
|
|
||||||
|
1. (Optional) Create automation user: Datacenter → Permissions → Users → Add (e.g., `terraform@pve`)
|
||||||
|
2. Permissions: Datacenter → Permissions → Add → User Permission
|
||||||
|
- Path: `/` (or narrower covering your nodes/storages)
|
||||||
|
- Role: `PVEVMAdmin` + `PVEStorageAdmin` (or `PVEAdmin` for simplicity)
|
||||||
|
3. Token: Datacenter → Permissions → API Tokens → Add → copy Token ID and Secret
|
||||||
|
4. Test:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
curl -k -H "Authorization: PVEAPIToken=<USER@REALM>!<TOKEN>=<SECRET>" \
|
||||||
|
https:// < PVE_HOST > :8006/api2/json/version
|
||||||
|
```
|
||||||
|
|
||||||
|
CLI:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
pveum user add terraform@pve --comment 'Terraform automation user'
|
||||||
|
pveum aclmod / -user terraform@pve -role PVEAdmin
|
||||||
|
pveum user token add terraform@pve terraform --privsep 0
|
||||||
|
```
|
||||||
|
|
||||||
|
## Use
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# From this directory
|
||||||
|
coder templates push --yes proxmox-cloudinit --directory . | cat
|
||||||
|
```
|
||||||
|
|
||||||
|
Create a workspace from the template in the Coder UI. First boot usually takes 60–120s while cloud‑init runs.
|
||||||
|
|
||||||
|
## How it works
|
||||||
|
|
||||||
|
- Uploads rendered cloud‑init user‑data to `<storage>:snippets/<vm>.yml` via the provider's `proxmox_virtual_environment_file`
|
||||||
|
- VM config: `virtio-scsi-pci`, boot order `scsi0, ide2, net0`, QGA enabled
|
||||||
|
- Linux user equals Coder workspace owner (sanitized). To avoid collisions, reserved names (`admin`, `root`, etc.) get a suffix (e.g., `admin1`). User is created with `primary_group: adm`, `groups: [sudo]`, `no_user_group: true`
|
||||||
|
- systemd service runs as that user:
|
||||||
|
- `coder-agent.service`
|
||||||
|
|
||||||
|
## Troubleshooting quick hits
|
||||||
|
|
||||||
|
- iPXE boot loop: ensure template has bootable root disk and boot order `scsi0,ide2,net0`
|
||||||
|
- QGA not responding: install/enable QGA in template; allow 60–120s on first boot
|
||||||
|
- Snippet upload errors: storage must include `Snippets`; token needs Datastore permissions; path format `<storage>:snippets/<file>` handled by provider
|
||||||
|
- Permissions errors: ensure the token's role covers the target node(s) and storages
|
||||||
|
- Verify snippet/QGA: `qm config <vmid> | egrep 'cicustom|ide2|ciuser'`
|
||||||
|
|
||||||
|
## References
|
||||||
|
|
||||||
|
- Ubuntu Cloud Images (latest): https://cloud-images.ubuntu.com/ ([source](https://cloud-images.ubuntu.com/))
|
||||||
|
- Proxmox qm(1) manual: https://pve.proxmox.com/pve-docs/qm.1.html
|
||||||
|
- Proxmox Cloud‑Init Support: https://pve.proxmox.com/wiki/Cloud-Init_Support
|
||||||
|
- Terraform Proxmox provider (bpg): `bpg/proxmox` on the Terraform Registry
|
||||||
|
- Coder – Best practices & templates:
|
||||||
|
- https://coder.com/docs/tutorials/best-practices/speed-up-templates
|
||||||
|
- https://coder.com/docs/tutorials/template-from-scratch
|
||||||
Reference in New Issue
Block a user