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}
 

config/samples/kustomization.yaml

@@ -9,5 +9,6 @@ resources:
 - proxy_gcp.yaml
 - proxy_kvm.yaml
 - proxy_kvm2.yaml
+- proxy_proxmox.yaml
 - proxy_external.yaml
 # +kubebuilder:scaffold:manifestskustomizesamples

config/samples/providers-config.yaml

@@ -88,3 +88,31 @@ providers:
   #         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}

config/samples/proxy_proxmox.yaml

@@ -0,0 +1,46 @@
+# A Managed proxy backed by a Proxmox VE cluster through the proxmox
+# provider: the operator full-clones a prepared template on the named node,
+# attaches a NoCloud seed ISO carrying this cloud-init, and starts the VM on
+# the configured network (here VLAN 4 on vmbr0, IP from that network's
+# DHCP), where cloud-init installs Squid. Requires a providers-config entry
+# named "proxmox-home" (see providers-config.yaml) and the proxmox-token
+# Secret (docs/proxmox-provider.md).
+#
+# placement.zone is a node name from proxmox.nodes (optional when only one
+# node is configured); machineType and image are keys in the provider's
+# machineTypes and templates maps. The address comes from the guest agent,
+# which a vendor-data script installs at first boot, so the VM's network
+# needs a route to a package mirror.
+apiVersion: crawl.example.com/v1alpha1
+kind: Proxy
+metadata:
+  name: proxy-proxmox-sample
+spec:
+  mode: Managed
+  provider: proxmox-home
+  placement:
+    zone: pv1-1
+    machineType: small
+    image: debian-13
+  port: 3128
+  cloudInit:
+    inline: |
+      #cloud-config
+      packages:
+        - squid
+      write_files:
+        - path: /etc/squid/conf.d/proxy-operator.conf
+          content: |
+            http_port 3128
+            http_access allow all
+            via off
+            forwarded_for off
+      runcmd:
+        - systemctl restart squid
+      # Optional: log in with `ssh debian@<ip>` (the Debian image's default
+      # user) to look around; `qm terminal <vmid>` on the node works too.
+      # ssh_authorized_keys:
+      #   - ssh-ed25519 AAAA... you@laptop
+  attributes:
+    geo: home
+    purpose: crawl