proxmox: deployment files, sample, user guide and doc rows

The optional proxmox-token Secret (token, ca.pem) mounted at
/etc/proxy-operator/proxmox, make proxmox-token-secret with content
checks that never print the token, a commented proxmox-home entry in
both providers configs, and config/samples/proxy_proxmox.yaml.
TestLoadConfig_proxmoxSampleEntry loads the commented entry from both
files, and a second test ties the sample Proxy's placement to it.

docs/proxmox-provider.md is the user guide: prerequisites and privileges,
cluster setup, config reference, placement, what lands on Proxmox,
logging, tracing, timeouts, health check, error classes, known gaps and
testing. providers-existing.md gains the proxmox column and section;
architecture.md, the README, providers.md and CLAUDE.md gain their rows.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

config/manager/manager.yaml

@@ -166,6 +166,18 @@ spec:
         - name: kvm-ssh
           mountPath: /etc/proxy-operator/kvm
           readOnly: true
+        # API token and CA for the proxmox provider (tokenFile / caFile in
+        # the providers config point here). Optional: the mount is empty when
+        # the Secret does not exist, and only proxmox entries need it. The
+        # token file is read on every request; the CA once, on first use.
+        # Create it with:
+        #   kubectl -n egress-proxies-operator-system create secret generic proxmox-token \
+        #     --from-file=token=<file holding user@realm!tokenid=secret> \
+        #     --from-file=ca.pem=<the node's /etc/pve/pve-root-ca.pem>
+        # or `make proxmox-token-secret`.
+        - name: proxmox-token
+          mountPath: /etc/proxy-operator/proxmox
+          readOnly: true
         # Scratch space: the root filesystem is read-only, and the kvm
         # provider builds each VM's cloud-init seed ISO through a temp
         # directory (a few hundred KB, deleted right after upload).
@@ -180,6 +192,11 @@ spec:
         secret:
           secretName: kvm-ssh
           optional: true
+      # The proxmox provider's token and CA; see the mount above.
+      - name: proxmox-token
+        secret:
+          secretName: proxmox-token
+          optional: true
       - name: tmp
         emptyDir:
           sizeLimit: 64Mi

config/manager/providers_config.yaml

@@ -84,4 +84,32 @@ data:
               bridge: br0
               # socket: /var/run/libvirt/libvirt-sock
               # pool: default
+      # proxmox clones a prepared template on a Proxmox VE cluster through its
+      # REST API and seeds it with a NoCloud ISO uploaded to isoStorage; it needs
+      # no SSH. Both files come from the optional proxmox-token Secret mounted by
+      # config/manager/manager.yaml. The url's host must be a name or address in
+      # the node certificate. See docs/proxmox-provider.md.
+      # - name: proxmox-home
+      #   type: proxmox
+      #   proxmox:
+      #     url: https://192.168.0.8:8006
+      #     tokenFile: /etc/proxy-operator/proxmox/token
+      #     caFile: /etc/proxy-operator/proxmox/ca.pem
+      #     # insecureSkipTLSVerify: true   # instead of caFile; logged as a warning
+      #     nodes: [pv1-1]                  # placement.zone names a node; optional with one node
+      #     isoStorage: proxy-seeds         # iso content; the token needs Datastore.Allocate here
+      #     # storage: local-lvm            # clone target; default is the template's disk storage
+      #     # bridge: vmbr0                 # replaces the cloned net0's bridge
+      #     vlanTag: 4                      # set on the cloned net0, MAC kept
+      #     # vmidRange: {min: 100000, max: 199999}
+      #     # requestTimeoutSeconds: 30
+      #     # installGuestAgent: false
+      #     # vendorData: |
+      #     #   #cloud-config
+      #     #   ...
+      #     templates:                      # placement.image names a key; add keys, never repoint one
+      #       debian-13: {vmid: 9001}
+      #     machineTypes:                   # placement.machineType names a key here
+      #       small:  {cores: 1, memoryMiB: 1024}
+      #       medium: {cores: 2, memoryMiB: 2048, diskGiB: 10}