Theme
Aa
← man.tcos.us gopher root · man.tcos.us
lu: · ·
HEE-PVE-DEPLOY(8)                  HEE Tools                  HEE-PVE-DEPLOY(8)

NAME
       hee-pve-deploy - deploy and provision a Proxmox LXC from one declarative
       manifest

SYNOPSIS
              hee-pve-deploy [-h] [--node NODE] [--host HOST] [--dry-run]
                hee-pve-deploy MANIFEST.yaml [--node pve] [--host 10.0.0.153] [--dry-run]
                               [--reprovision] [--anchors FILE] [--addons FILE] [--agent-roster FILE]

              positional arguments:
                manifest              pve/services/<name>.yaml -- see the manifest format
                                      above

              options:
                -h, --help            show this help message and exit
                --node NODE
                --host HOST
                --dry-run             resolve the manifest and print every command that
                                      would run -- create, add-ons, files, provision --
                                      creating and changing nothing. Without it the deploy
                                      is applied.
                --reprovision         on a hostname that ALREADY EXISTS: re-ship every
                                      'files:' entry (sha256-compared against the container
                                      first and reported new/changed/unchanged) and re-run
                                      every 'provision:' script, instead of the idempotent
                                      skip -- exits with provision:'s own exit code. Never
                                      runs 'pct set': a live mounts:/features: mismatch
                                      against the manifest is printed as a WARNING naming
                                      the pct set it would take, and nothing is applied --
                                      that still needs a destroy and a create. On a hostname
                                      that does NOT exist yet this flag is a no-op: a plain
                                      create happens, same as without it.
                --anchors ANCHORS     registry of roles whose address may be pinned. A
                                      manifest that declares address or hwaddr must name a
                                      role listed there; anything else has its address
                                      allocated.
                --addons ADDONS       the org's container-addons registry, the only place an
                                      'addons:' name resolves. Unreadable means every add-on
                                      is refused, never silently skipped.
                --agent-roster AGENT_ROSTER
                                      the org's signed agent roster, the only place a model
                                      is named. Read only by 'generate: agent-roster-model'
                                      files entries; it must be ratified and its .asc must
                                      verify, or nothing is rendered.

DESCRIPTION
                                    [--reprovision] [--anchors ANCHORS] [--addons ADDONS]
                                    [--agent-roster AGENT_ROSTER]
                                    manifest

              hee-pve-deploy -- deploy and provision a Proxmox LXC from one declarative manifest.

              One YAML file per service; this tool creates the container via the real
              Proxmox API (pvesh over SSH to the node), idempotent by hostname, then
              applies the manifest's add-ons, files and provision scripts inside it.

              Real trigger (2026-08-24, Spencer): "build extensible deploy via api to
              pve strat" -- tiny, bare-minimum LXC per core service (bastion, qmail
              MTA, snmpd), matching docs/guides/PVE_CAPACITY_PLANNING_METHODOLOGY.md's
              step 5 ("a new service is a new manifest entry, not new deploy code").

              Never installs anything on the pve host itself -- pvesh is Proxmox's
              own real API-wrapper CLI, already there on any real Proxmox node; this
              tool just calls it over SSH from wherever hee runs.

              Manifest format (pve/services/<name>.yaml):
                hostname: bastion
                template: alpine-3.23-default_20260116_amd64.tar.xz
                cores: 1
                memory_mb: 256
                disk_gb: 4
                storage: ssd1
                bridge: vmbr0
                unprivileged: true
                onboot: 1                         # start on host boot. DEFAULTS TO 1 here, unlike Proxmox's own 0
                features: {nesting: true, keyctl: true}   # pve LXC features; only for a container that runs containers
                addons: [agent-tooling]           # named apk sets from the org's registry (--addons)
                agent: ci-triage                  # agent roster role, only for a container that runs an agent
                files:                            # committed files pushed INTO the container
                  - {src: pve/lab-dhcp/dnsmasq.conf, dst: /etc/dnsmasq.conf, mode: "0644"}
                  - {src: tools/meme-factory, dst: /opt/meme-factory}   # a committed DIRECTORY, shipped as one tar
                  - {generate: agent-roster-model, dst: /etc/claude-code/managed-settings.d/50-model.json, mode: "0644"}
                provision:                        # committed POSIX sh scripts run inside it
                  - pve/lab-dhcp/provision.sh
                resolver:                         # the container's /etc/resolv.conf, and nothing overwrites it
                  nameservers: [10.0.0.194, 10.0.0.72]
                  search: [lab.tcos.us, tcos.us]
                  ndots: 2
                mounts:                           # directories of the pve HOST lent to the container (bind mounts)
                  - {host: /srv/storage, ct: /data/storage}            # read-write
                  - {host: /srv/media, ct: /data/media, ro: true}      # read-only

              `files:` and `provision:` paths are relative to the root of the repo the
              manifest lives in (git rev-parse --show-toplevel), never to the current
              directory and never absolute. A `src` that is a directory is shipped whole:
              every file git tracks under it (`git ls-files`, so nothing untracked, no
              results/, no .git) goes over as one tar and is unpacked at `dst`. Real
              trigger (2026-09-19): the meme-factory service is a tree in a PRIVATE repo,
              and a container holds no repository credential, so the deploy is the only
              honest way the code gets there; the previous shape was a hand `pct push` per
              file or a clone with a credential the container must not have. `mode` is
              refused on a directory entry (git's own modes travel in the tar): a manifest names what it ships, and what it
              ships is under review beside it. Real trigger (2026-09-10): the only
              precedent for configuring what runs INSIDE a container was a README of
              `pct exec N -- sh -c "cat > /etc/..."` one-liners (fleet-ops
              pve/snmp-joe/README.md) -- the same imperative shape pve/network.yaml was
              written to remove for bridges. Order: create -> addons -> files ->
              provision. The manifest is fully resolved BEFORE the container is created,
              so a missing file fails closed rather than leaving a half-provisioned
              container behind. Every step is previewed under --dry-run, including
              addons, which the dry run used to skip.

              A `files:` entry names either `src` (a committed file) or `generate` (a
              file rendered at deploy time, never committed). The one generator today is
              `agent-roster-model`: it reads the org's agent roster (--agent-roster), refuses unless
              the agent roster is `status: ratified` AND its detached signature verifies with a
              key the agent roster's own ratification_evidence names, then renders the
              Claude Code managed-settings drop-in that pins the manifest's `agent:` to
              the model the agent roster assigns. Real trigger (2026-09-10): the first agent
              manifests shipped five hand-kept managed-settings.json copies, each
              restating a model the signed agent roster already names -- a second source that
              would leave every container on the old model after an agent roster change, with
              nothing to say so. Operator: "generate from roster at deploy is correct,
              footgun". The model is named in exactly one place, and the dry run prints
              the rendered file.

              Every command run inside the container gets
              PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin. `pct exec`
              otherwise passes PVE's own /sbin:/bin:/usr/sbin:/usr/bin, which has no
              /usr/local/bin, so a provision script calling a tool it just linked there
              exited 127 (measured 2026-09-10).

              `resolver:` declares the container's DNS: up to three IPv4 nameservers, in
              order; an optional search list; and ndots (default 1). The tool writes
              /etc/resolv.conf from it right after the network is up, before add-ons, and
              makes it stick. Nothing else does, measured 2026-09-10: the golden template
              sets no resolver, pve rewrites /etc/resolv.conf from the HOST's file at every
              container start, and Alpine's udhcpc rewrites it from DHCP on every lease --
              ct113 was resolving through 10.0.0.72 and 1.1.1.1 handed out by the
              household router, and a public resolver answers NXDOMAIN for lab names. So
              it also writes /etc/.pve-ignore.resolv.conf (pve skips the file), and for a
              DHCP container /etc/udhcpc/udhcpc.conf with RESOLV_CONF="no". ndots matters
              on musl: the search list is used only when a name has FEWER dots than
              ndots, so `view.lab` (one dot) resolves as view.lab.tcos.us only with
              ndots 2. Operator: "proper search and ndot settings too (view.lab/foo should
              work)".

              `mounts:` lends a directory of the pve HOST to the container, rendered as
              `-mpN host,mp=ct[,ro=1]` in manifest order. It is the only way an
              unprivileged LXC gets shared storage: the container cannot mount NFS
              itself, so the host mounts or serves the storage and bind-mounts the
              directory in. Real trigger (2026-09-18): the meme-factory service needs the
              lab's $MNTPATH (/data/storage) inside its container, and ipk-factory has
              waited since 2026-09-03 for "the nfs share once set up" -- with no field,
              both would have been a hand `pct set`, the imperative shape this tool exists
              to remove. Rules: both paths absolute and normalized (no trailing slash, no
              `..`), no comma or `=` in either (pve's option syntax), `ct` never `/`, no
              two entries with the same `ct`. Known and not hidden: in an unprivileged
              container the host's uids are shifted (host uid N appears as 100000+N), so
              files owned by ordinary host users read as nobody:nogroup -- reading needs
              the world-read bit, writing needs a world-writable (1777) or
              100000-range-owned directory on the host, and this tool chmods nothing.
              pve accepts a bind mount only from root@pam, which pvesh over ssh to root
              is. A bind mount is never part of a container backup.

              `--reprovision` on a hostname that already exists re-ships every `files:`
              entry through the identical apply_files() a create uses (directory entries
              via the same `git archive HEAD` tar) and re-runs every `provision:` script,
              in place of the plain idempotent skip. Real trigger,
              human-execution-engine#760 (2026-09-19): the only tool path for the normal
              case -- a `provision:` bug found after the container exists -- was `scp`
              the fix to the node and `pct exec` it in by hand, the exact one-liner shape
              this tool exists to retire, on the one flow it had no answer for. It
              resolves the manifest fully first, exactly like create, and NEVER runs
              `pct set`: it cannot touch the container's config, so it cannot touch the
              MAC a DHCP reservation is keyed on or a mount -- those still need a destroy
              and a create. Each `files:` entry is sha256-compared against what a
              `pct exec VMID -- sha256sum` finds already in the container (a directory
              entry compares every file the tar carries, by path relative to `dst`) and
              reported `new`/`changed`/`unchanged` before it is re-shipped, and the
              tool's own exit code is `provision:`'s own. A live `mounts:`/`features:`
              that no longer matches the manifest (`pct config VMID`) is printed as a
              `WARNING` naming the exact `pct set` that would fix it -- computed, never
              run. On a hostname that does not exist yet, `--reprovision` is a no-op: a
              plain create happens, same as without it.

EXAMPLES
              (None marked "# ci": even --dry-run reads the live Proxmox host over ssh to
              diff against the manifest, which a CI runner cannot reach.)

              hee-pve-deploy pve/services/bastion.yaml --dry-run
                  Preview a create: every command, every file, every provision script --
                  nothing runs.

              hee-pve-deploy pve/services/bastion.yaml
                  Create it for real. Idempotent by hostname: run again unchanged and it
                  only reports the existing container.

              hee-pve-deploy pve/services/meme-factory.yaml --reprovision --dry-run
                  Preview a reprovision on an EXISTING container: the sha256 diff of
                  every files: entry (new/changed/unchanged), the mounts:/features:
                  WARNING if the live config has drifted from the manifest, and the
                  provision: scripts that would run. Nothing is applied.

              hee-pve-deploy pve/services/meme-factory.yaml --reprovision
                  Re-ship files:, re-run provision:, on a container that already
                  exists. Exit code is provision:'s own. Never touches mounts:/
                  features: -- those still need a destroy and a create.

                                                              HEE-PVE-DEPLOY(8)