Enhance ISO selection logic and update documentation for improved clarity and usage instructions
This commit is contained in:
parent
b6886cb34a
commit
9a7bd81d17
12 changed files with 287 additions and 16 deletions
172
README.md
172
README.md
|
|
@ -1,25 +1,173 @@
|
|||
# pve-vm-setup
|
||||
|
||||
Textual TUI for creating Proxmox VMs with live reference data, guarded create controls, and a guided multi-step wizard.
|
||||
|
||||
## What it does
|
||||
|
||||
- logs into a Proxmox VE API endpoint
|
||||
- loads nodes, pools, storages, bridges, tags, and ISO images from the live cluster
|
||||
- walks through VM creation in a step-by-step wizard
|
||||
- can run in a safe read-only mode, a normal live-create mode, or a restricted test mode
|
||||
|
||||
## Commands
|
||||
|
||||
- Install: `uv sync`
|
||||
- Run app: `uv run python -m pve_vm_setup`
|
||||
- Run live diagnostics: `uv run python -m pve_vm_setup --doctor-live`
|
||||
- Run directly from this repo (without cloning): `uvx git+https://git.s1q.dev/phg/pve-vm-setup.git`
|
||||
- Install dependencies: `uv sync`
|
||||
- Run the app from the checkout repository: `uv run -m pve_vm_setup`
|
||||
- Run live diagnostics: `uv run -m pve_vm_setup --doctor-live`
|
||||
- Run tests: `uv run pytest`
|
||||
- Run read-only live tests: `uv run pytest -m live`
|
||||
- Run create-gated live tests: `uv run pytest -m live_create`
|
||||
- Run live create tests: `uv run pytest -m live_create`
|
||||
- Lint: `uv run ruff check .`
|
||||
- Format: `uv run ruff format .`
|
||||
|
||||
## Live configuration
|
||||
## Typical usage
|
||||
|
||||
Start from `.env.example` and provide the Proxmox credentials in `.env`.
|
||||
1. Copy `.env.example` to `.env`.
|
||||
2. Fill in the Proxmox connection settings.
|
||||
3. Decide whether this machine should be allowed to create VMs at all.
|
||||
4. Optionally enable test mode if you want live creates restricted to a known node/pool and auto-tagged.
|
||||
5. Start the app with `uv run python -m pve_vm_setup`.
|
||||
6. Log in and complete the wizard.
|
||||
|
||||
Additional live-access controls:
|
||||
Before the final create request, the app asks whether the VM should be started automatically after creation.
|
||||
|
||||
- `PROXMOX_VERIFY_TLS=false` disables certificate verification for internal/self-signed installs
|
||||
- `PROXMOX_API_BASE=/api2/json` makes the API base explicit
|
||||
- `PROXMOX_PREVENT_CREATE=false` allows VM creation by default; set it to `true` to block creates
|
||||
- `PROXMOX_ENABLE_TEST_MODE=true` enables scoped test mode for live creates
|
||||
- When test mode is enabled, `PROXMOX_TEST_NODE`, `PROXMOX_TEST_POOL`, `PROXMOX_TEST_TAG`, and `PROXMOX_TEST_VM_NAME_PREFIX` are required and are used to constrain and mark created VMs
|
||||
## Operating modes
|
||||
|
||||
### Read-only mode
|
||||
|
||||
Use this when you want to browse live data and validate the setup without creating anything.
|
||||
|
||||
- Set `PROXMOX_PREVENT_CREATE=true`
|
||||
- Recommended for first-time setup
|
||||
- `--doctor-live` is useful here
|
||||
|
||||
### Normal live-create mode
|
||||
|
||||
Use this when you want to create real VMs without the extra test-mode restrictions.
|
||||
|
||||
- Set `PROXMOX_PREVENT_CREATE=false` or leave it unset
|
||||
- Leave `PROXMOX_ENABLE_TEST_MODE=false`
|
||||
- Recommended only when you are comfortable with the target cluster and defaults
|
||||
|
||||
### Restricted test mode
|
||||
|
||||
Use this when you want live creates, but only inside a constrained sandbox.
|
||||
|
||||
- Set `PROXMOX_PREVENT_CREATE=false`
|
||||
- Set `PROXMOX_ENABLE_TEST_MODE=true`
|
||||
- `PROXMOX_TEST_NODE`, `PROXMOX_TEST_POOL`, `PROXMOX_TEST_TAG`, and `PROXMOX_TEST_VM_NAME_PREFIX` become required
|
||||
- The app restricts creates to the configured node and pool
|
||||
- The app automatically adds the configured tag and name prefix
|
||||
|
||||
## Environment variables
|
||||
|
||||
Start from `.env.example`. The table below describes every supported variable that is currently parsed by the app.
|
||||
|
||||
| Variable | Required | Default | Recommended | Purpose |
|
||||
| --- | --- | --- | --- | --- |
|
||||
| `PROXMOX_URL` | Required for live access | none | Yes | Base Proxmox URL, for example `https://pve.example.com:8006`. |
|
||||
| `PROXMOX_REALM` | Required for live access | none | Yes | Proxmox auth realm, for example `pam`, `pve`, or `ldap`. |
|
||||
| `PROXMOX_USER` | Required for live access | none | Yes | Username used for API login. If it does not contain `@realm`, the configured realm is appended automatically. |
|
||||
| `PROXMOX_PASSWORD` | Required for live access | none | Yes | Password for the Proxmox user. |
|
||||
| `PROXMOX_VERIFY_TLS` | Optional | `false` | Yes, if your certificates are valid | Controls TLS certificate verification for API calls. Set to `true` for properly trusted certificates. Set to `false` only for internal or self-signed setups you explicitly trust. |
|
||||
| `PROXMOX_API_BASE` | Optional | `/api2/json` | Usually leave as-is | API base path appended to `PROXMOX_URL`. Only change this if your deployment needs a different base path. |
|
||||
| `PROXMOX_REQUEST_TIMEOUT_SECONDS` | Optional | `15` | Usually yes | Request timeout used for API calls and task polling. Increase it if your environment is slow. |
|
||||
| `PROXMOX_DEFAULT_ISO_SELECTOR` | Optional | unset | Optional | Controls which ISO image is auto-selected in the OS step. Uses glob matching by default. If prefixed with `regex:`, the remainder is treated as a regular expression. |
|
||||
| `PROXMOX_PREVENT_CREATE` | Optional | `false` | Yes | Global create safety switch. Set to `true` to block VM creation completely. Leave unset or set to `false` to allow creates. |
|
||||
| `PROXMOX_ENABLE_TEST_MODE` | Optional | `false` | Yes for shared or risky environments | Enables restricted live-create mode. When enabled, the `PROXMOX_TEST_*` scope settings become mandatory. |
|
||||
| `PROXMOX_TEST_NODE` | Required only in test mode | none | Yes in test mode | Node that live creates are restricted to. |
|
||||
| `PROXMOX_TEST_POOL` | Required only in test mode | none | Yes in test mode | Pool that live creates are restricted to. |
|
||||
| `PROXMOX_TEST_TAG` | Required only in test mode | `codex-e2e` | Yes in test mode | Tag added automatically to created VMs in test mode. |
|
||||
| `PROXMOX_TEST_VM_NAME_PREFIX` | Required only in test mode | `codex-e2e-` | Yes in test mode | Prefix added automatically to VM names in test mode. |
|
||||
| `PROXMOX_KEEP_FAILED_VM` | Optional | `true` | Leave as-is for now | Parsed by settings, but currently not acted on by the create workflow yet. Treat it as reserved for future cleanup behavior. |
|
||||
|
||||
## ISO selector syntax
|
||||
|
||||
`PROXMOX_DEFAULT_ISO_SELECTOR` supports two forms:
|
||||
|
||||
- Glob syntax, used by default
|
||||
- Regex syntax, enabled with a `regex:` prefix
|
||||
|
||||
Examples:
|
||||
|
||||
- `PROXMOX_DEFAULT_ISO_SELECTOR=*ubuntu*`
|
||||
- `PROXMOX_DEFAULT_ISO_SELECTOR=*debian-12*`
|
||||
- `PROXMOX_DEFAULT_ISO_SELECTOR=regex:nixos-minimal-\d{2}\.\d{2}\..*-x86_64-linux\.iso$`
|
||||
|
||||
Behavior:
|
||||
|
||||
- if the selector matches one or more ISOs, the app picks from those matches
|
||||
- if multiple matching NixOS-style ISOs exist, it prefers the latest one by release naming
|
||||
- if nothing matches, the app falls back to the built-in default picker
|
||||
|
||||
## Recommended `.env` setups
|
||||
|
||||
### Safe initial setup
|
||||
|
||||
```dotenv
|
||||
PROXMOX_URL=https://pve.example.com:8006
|
||||
PROXMOX_REALM=pam
|
||||
PROXMOX_USER=root
|
||||
PROXMOX_PASSWORD=replace-me
|
||||
PROXMOX_VERIFY_TLS=true
|
||||
PROXMOX_PREVENT_CREATE=true
|
||||
PROXMOX_ENABLE_TEST_MODE=false
|
||||
```
|
||||
|
||||
### Normal live-create setup
|
||||
|
||||
```dotenv
|
||||
PROXMOX_URL=https://pve.example.com:8006
|
||||
PROXMOX_REALM=pam
|
||||
PROXMOX_USER=root
|
||||
PROXMOX_PASSWORD=replace-me
|
||||
PROXMOX_VERIFY_TLS=true
|
||||
PROXMOX_PREVENT_CREATE=false
|
||||
PROXMOX_ENABLE_TEST_MODE=false
|
||||
PROXMOX_DEFAULT_ISO_SELECTOR=*nixos*
|
||||
```
|
||||
|
||||
### Restricted test setup
|
||||
|
||||
```dotenv
|
||||
PROXMOX_URL=https://pve.example.com:8006
|
||||
PROXMOX_REALM=pam
|
||||
PROXMOX_USER=root
|
||||
PROXMOX_PASSWORD=replace-me
|
||||
PROXMOX_VERIFY_TLS=true
|
||||
PROXMOX_PREVENT_CREATE=false
|
||||
PROXMOX_ENABLE_TEST_MODE=true
|
||||
PROXMOX_TEST_NODE=pve-test-01
|
||||
PROXMOX_TEST_POOL=sandbox
|
||||
PROXMOX_TEST_TAG=codex-e2e
|
||||
PROXMOX_TEST_VM_NAME_PREFIX=codex-e2e-
|
||||
```
|
||||
|
||||
## Notes and caveats
|
||||
|
||||
- Live access requires `PROXMOX_URL`, `PROXMOX_USER`, `PROXMOX_PASSWORD`, and `PROXMOX_REALM`.
|
||||
- Test mode is not the same as read-only mode. Test mode still performs real creates when creation is allowed.
|
||||
- If `PROXMOX_PREVENT_CREATE=true`, the confirm step validates but actual creation is blocked.
|
||||
- `PROXMOX_TEST_POOL` is currently required when test mode is enabled.
|
||||
- `PROXMOX_KEEP_FAILED_VM` is currently reserved and not yet implemented in the workflow logic.
|
||||
|
||||
## Live diagnostics
|
||||
|
||||
Run:
|
||||
|
||||
```bash
|
||||
uv run python -m pve_vm_setup --doctor-live
|
||||
```
|
||||
|
||||
This verifies:
|
||||
|
||||
- transport reachability
|
||||
- API base access
|
||||
- visible nodes
|
||||
- configured test node and pool, when test mode is enabled
|
||||
|
||||
Use this before enabling creates against a real cluster.
|
||||
|
||||
## Engineering rules
|
||||
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue