knife-proxmox-ve 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 44a5c4bf238510fc6036949da54fbc039f51c0ff7d3d9afd851be8b4f6e2681e
+  data.tar.gz: e3de5df406aa26142068a1f087f485604e7f0f0237fc20da7473ff7ec6caf187
+SHA512:
+  metadata.gz: 3d4500fc914372ba78bec85f72786a58bae1177fa3d900f8faa75896f664bda4f6805da6ea2f2aad35f81abbc995981f7de52b85b464b7f4b8142d28a9ab5580
+  data.tar.gz: 63006a55bc3d193884fbca1344d99f88719e7bfe475b9d67a48ddadde9ccff2d723f06c757e26263964206c2631511f2b3dc48aba1ea556883ded843925803a5

data/CHANGELOG.md

@@ -0,0 +1,24 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-06-04
+
+### Added
+
+- `knife proxmox vm create` — create a VM on Proxmox VE by cloning a prepared
+  template and configuring CPU/RAM/network/cloud-init.
+- `knife proxmox vm bootstrap` — create a VM and automatically bootstrap it with
+  Chef/CINC in a single command, waiting for the VM to boot first.
+- Read-only helpers: `knife proxmox cluster list`, `knife proxmox template list`
+  and `knife proxmox vm list`.
+- Support for multiple Proxmox clusters defined in `~/.cinc/config.rb`.
+- Authentication via Proxmox VE API tokens.
+
+[Unreleased]: https://github.com/pwojcieszonek/knife-proxmox-ve/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/pwojcieszonek/knife-proxmox-ve/releases/tag/v0.1.0

data/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or Derivative
+          Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and do
+          not modify the License. You may add Your own attribution notices
+          within Derivative Works that You distribute, alongside or as an
+          addendum to the NOTICE text from the Work, provided that such
+          additional attribution notices cannot be construed as modifying
+          the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 Piotr Wojcieszonek
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

data/README.md

@@ -0,0 +1,225 @@
+# knife-proxmox-ve
+
+A [knife](https://docs.chef.io/workstation/knife/) plugin (Chef Infra / CINC
+Workstation) that **creates VMs on Proxmox VE** by cloning a pre-configured template,
+configuring it, starting it, and waiting for it to boot. Use `vm create` to provision a
+VM, or `vm bootstrap` to provision it **and automatically bootstrap it with Chef/CINC**
+in one command.
+
+The plugin only ever *clones* a prepared template; it never builds an image. All VM
+parameters are optional: anything you don't pass keeps the value baked into the
+template.
+
+## Requirements
+
+- Chef Workstation / CINC Workstation 18+ (the plugin depends on the `knife` gem ≥ 18).
+- A Proxmox VE **API token** (see [Authentication](#authentication)).
+- A template that already has a **cloud-init drive** (e.g. `ide2=<storage>:cloudinit`)
+  and the **QEMU guest agent** enabled. Cloud-init settings are silently ignored by
+  Proxmox if the template has no cloud-init drive — the plugin fails fast when it
+  detects this.
+
+## Installation
+
+```bash
+chef gem install knife-proxmox-ve     # Chef Workstation
+cinc gem install knife-proxmox-ve     # CINC Workstation
+```
+
+knife discovers the commands automatically (no registration step). For development
+from a checkout, run via `cinc exec bundle exec knife proxmox ...`.
+
+## Configuration
+
+Proxmox clusters are defined in `~/.cinc/config.rb` (or `~/.chef/config.rb`) under
+`knife[:proxmox_clusters]`. Each key is a cluster name selectable with
+`--proxmox-cluster`.
+
+```ruby
+knife[:proxmox_clusters] = {
+  "production" => {
+    host:         "pve1.example.com",    # required
+    port:         8006,                  # optional (default 8006)
+    token_id:     "knife@pve!automation", # required; the USER@REALM!TOKENID part
+    token_secret: nil,                   # optional in-file; prefer the ENV override below
+    verify_ssl:   true,                  # optional (default true); false warns every run
+
+    # Optional per-cluster provisioning defaults (any CLI flag overrides these):
+    storage:      "local-lvm",
+    bridge:       "vmbr0",
+    ciuser:       "ubuntu",
+    nameserver:   "10.0.0.1",
+    searchdomain: "example.com",
+    target_node:  nil,
+  },
+}
+
+# Cluster used when --proxmox-cluster is omitted:
+knife[:proxmox_default_cluster] = "production"
+```
+
+### Authentication
+
+The plugin authenticates with a Proxmox **API token** (`Authorization: PVEAPIToken=...`).
+The token secret is resolved with this precedence (highest first):
+
+1. `KNIFE_PROXMOX_TOKEN_SECRET` — global override for whichever cluster is selected
+2. `KNIFE_PROXMOX_TOKEN_SECRET_<CLUSTER>` — per cluster (key upcased, non-alphanumerics → `_`)
+3. `token_secret:` in the cluster hash
+
+Prefer an environment variable so the secret never sits in a file. **If you do store
+`token_secret:` in `config.rb`, `chmod 600 ~/.cinc/config.rb`** — anyone who can read
+the file can read the token.
+
+```bash
+export KNIFE_PROXMOX_TOKEN_SECRET="xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
+```
+
+> Proxmox API tokens default to **privilege separation**: a fresh token has no rights
+> until you grant ACLs to the token itself. A first-run `HTTP 403` almost always means
+> this. The token needs: `VM.Clone`, `VM.Config.Disk`, `VM.Config.Network`,
+> `VM.Config.Memory`, `VM.Config.CPU`, `VM.Config.Cloudinit`, `VM.Config.Options`,
+> `VM.PowerMgmt`, `VM.Audit`, `VM.Monitor` (guest-agent calls; PVE 8 and earlier),
+> `VM.Allocate`, and `Datastore.AllocateSpace` on the target storage (full clones).
+
+### TLS
+
+HTTPS to `:8006` is verified by default. Set `verify_ssl: false` per cluster only for
+self-signed lab hosts — the plugin warns on **every** command when verification is off,
+because the connection (carrying the token) is then MITM-exploitable.
+
+## Commands
+
+### `knife proxmox vm create NAME`
+
+Clone a template → configure → start. Stops there — **no Chef bootstrap runs**. Use it to
+stand up a VM you do not (yet) want to manage with Chef. `NAME` (the new VM's name) and
+`--template` are the only required inputs; every other parameter falls back to the template's
+value.
+
+Because it never connects to the VM, `vm create` does **not** wait for SSH and does **not**
+fail if the guest has no network — its job is done once the VM is cloned, configured and
+started. The IP is reported best-effort: known immediately for a static `--ip`, or polled
+from the guest agent (bounded by `--boot-timeout`) for `dhcp`; if none is found it warns and
+still succeeds, omitting the IP from the summary.
+
+cloud-init auth (`--ssh-public-key` / `--cipassword`) is **optional** here: a template with
+a baked-in login is a valid result. Pass a key/password if you want one planted on the guest.
+
+```bash
+knife proxmox vm create web-01 \
+  --proxmox-cluster production \
+  --template ubuntu-2404-template \
+  --cores 2 --memory 4096 \
+  --bridge vmbr0 --vlan 100 \
+  --ip 10.0.10.50/24 --gateway 10.0.10.1 \
+  --nameserver 10.0.0.1 --searchdomain example.com \
+  --ciuser ubuntu --ssh-public-key ~/.ssh/id_ed25519.pub
+```
+
+### `knife proxmox vm bootstrap NAME`
+
+Everything `vm create` does, then **bootstraps the node with Chef/CINC**: clone → configure →
+start → wait for SSH → `knife bootstrap`. Because it must connect, an SSH public key or a
+cloud-init password is **required**. `NAME` and `--template` are otherwise the only required
+inputs; every other parameter falls back to the template's value.
+
+```bash
+knife proxmox vm bootstrap web-01 \
+  --proxmox-cluster production \
+  --template ubuntu-2404-template \
+  --cores 2 --memory 4096 \
+  --bridge vmbr0 --vlan 100 \
+  --ip 10.0.10.50/24 --gateway 10.0.10.1 \
+  --nameserver 10.0.0.1 --searchdomain example.com \
+  --ciuser ubuntu --ssh-public-key ~/.ssh/id_ed25519.pub \
+  --node web-01 --run-list 'role[base]'
+```
+
+Both commands share the provisioning flags below.
+
+| Flag | Meaning |
+|------|---------|
+| `--template NAME_OR_VMID` | Source template (name or numeric VMID). **Required.** |
+| `--proxmox-cluster NAME` | Cluster key from `knife[:proxmox_clusters]`. |
+| `--target-node NODE` | Node to clone onto (requires shared storage for a cross-node clone). |
+| `--newid VMID` | Use a specific VMID instead of the cluster's next free id. |
+| `--linked-clone` | Linked clone instead of the default full clone (`--storage` is then ignored). |
+| `--storage NAME` / `--pool NAME` | Target storage / resource pool. |
+| `--cores N` / `--sockets N` / `--memory MiB` | CPU / RAM. |
+| `--bridge vmbrN` / `--vlan TAG` | net0 bridge and VLAN tag (needs a VLAN-aware bridge). |
+| `--ip CIDR\|dhcp` / `--gateway IP` / `--prefix N` | Static IPv4 (`10.0.10.5/24`, or a bare IP with `--prefix`) or `dhcp`. |
+| `--nameserver IP` / `--searchdomain DOMAIN` | cloud-init DNS. |
+| `--ciuser USER` | cloud-init user. |
+| `--ssh-public-key PATH` | Public key injected via cloud-init (preferred auth). |
+| `--cipassword` | Prompt (no echo) for a cloud-init password; or set `KNIFE_PROXMOX_CIPASSWORD`. |
+| `--clone-timeout SEC` / `--boot-timeout SEC` | Clone and boot/SSH wait limits (default 600 / 300). |
+
+For `vm bootstrap`, the standard `knife bootstrap` options are inherited: `-N/--node-name`,
+`-r/--run-list`, `-E/--environment`, `--connection-user`, `--ssh-identity-file`,
+`--bootstrap-version`, `--ssh-verify-host-key` (defaults to `:accept_new` for the
+freshly-created host), `--yes`, etc. They do not apply to `vm create`, which never bootstraps.
+
+**Clone mode.** The clone is a **full clone by default**. Pass `--linked-clone` for a linked
+clone (faster, thin) — it requires a storage that supports it, and any `--storage` (CLI or
+cluster default) is then dropped, because Proxmox rejects a target storage on a linked clone.
+
+**Bootstrap product (CINC by default).** A `vm bootstrap`'d VM is bootstrapped with **CINC** out of the
+box — the install is pinned to the CINC omnitruck regardless of whether you invoke a CINC- or
+Chef-branded `knife`, which also avoids Chef's commercial license gate. To bootstrap with Chef
+Infra Client instead, opt in via `config.rb`:
+
+```ruby
+knife[:proxmox_bootstrap_product] = "chef"   # or "chef-ice"; standard Chef licensing then applies
+```
+
+An explicit `--bootstrap-product`, `--bootstrap-url` or `--bootstrap-install-command` always wins.
+
+**cloud-init wait.** Before installing the client, `vm bootstrap` waits for cloud-init to finish
+(`cloud-init status --wait`) so the omnibus install never races cloud-init for the apt/dpkg lock
+on the freshly booted VM. This makes `vm bootstrap` deterministic in a single run; override it
+with `--bootstrap-preinstall-command` (it is skipped on images without cloud-init).
+
+**SSH authentication.** Injecting a public key (`--ssh-public-key`) is the preferred path — for
+`vm bootstrap` the matching private key is then used for the bootstrap connection. A cloud-init
+password is supported as a fallback via `KNIFE_PROXMOX_CIPASSWORD` or the `--cipassword` no-echo
+prompt (never as a literal command-line argument). A credential is **required** for `vm bootstrap`
+(it must connect) and **optional** for `vm create`. For `--ip dhcp` the guest must run the QEMU
+guest agent so the leased address can be discovered.
+
+### `knife proxmox cluster list`
+
+Lists the configured clusters with host, token id, `verify_ssl`, and whether a token
+secret resolves (the secret value is never printed). Marks the default cluster with `*`.
+Makes no API call.
+
+### `knife proxmox template list [--proxmox-cluster NAME]`
+
+Lists the qemu templates on the selected cluster (name, VMID, node, disk, memory).
+
+### `knife proxmox vm list [--proxmox-cluster NAME] [--node NODE]`
+
+Lists the cluster's qemu VMs (name, VMID, node, status, memory, uptime). `--node` filters
+client-side.
+
+All read commands honour `--format json|yaml` for scripting.
+
+## Development
+
+Tests run under **cinc-workstation**, so the suite exercises the same `knife` build the
+gem ships on (a cinc-internal build that differs from the rubygems release — e.g.
+`Bootstrap#fetch_license` was removed in it). No bundler is involved.
+
+```bash
+cinc exec rake                      # chefstyle + rspec (the default task)
+cinc exec rake spec                 # rspec only
+cinc exec rake style                # chefstyle only
+```
+
+> Do **not** use `bundle exec` against cinc: `Gemfile.lock` pins the public knife, which the
+> cinc gem repo does not carry, so `cinc exec bundle exec` fails. The `Gemfile`/`Gemfile.lock`
+> exist only for `gem build`/release (`cinc exec rake build`).
+
+## License
+
+Apache-2.0.

data/lib/chef/knife/helpers/proxmox_base.rb

@@ -0,0 +1,172 @@
+# frozen_string_literal: true
+
+require "knife-proxmox-ve/client"
+require "knife-proxmox-ve/api"
+
+class Chef
+  class Knife
+    # Shared behaviour mixed into every `knife proxmox ...` command (SEAM 2).
+    #
+    # Owns cluster resolution, the Client/Api factory and the secret-from-ENV override so
+    # individual commands stay declarative: they call #proxmox_api, #proxmox_client and
+    # #msg_pair and never touch the clusters hash or the environment directly.
+    #
+    # The token secret is resolved with ENV precedence and is never sent empty — a missing
+    # secret is a loud, fatal error, not a silent default.
+    module ProxmoxBase
+      # Global ENV override applied to whichever cluster is selected.
+      ENV_SECRET_GLOBAL = "KNIFE_PROXMOX_TOKEN_SECRET"
+
+      # Per-cluster ENV override prefix; suffix is the cluster key normalized via #env_key.
+      ENV_SECRET_PREFIX = "KNIFE_PROXMOX_TOKEN_SECRET_"
+
+      def self.included(includer)
+        includer.class_eval do
+          option :proxmox_cluster,
+            long:        "--proxmox-cluster NAME",
+            description: "Proxmox cluster key from knife[:proxmox_clusters]"
+        end
+      end
+
+      # The selected cluster as a symbol-keyed Hash, with :token_secret resolved through the
+      # ENV override. Fatals (and lists available keys) when no cluster is selected or the
+      # selected key is unknown. Memoized.
+      def proxmox_cluster_config
+        @proxmox_cluster_config ||= resolve_cluster_config
+      end
+
+      # The transport client for the selected cluster. Warns on every run when TLS
+      # verification is disabled. Memoized.
+      def proxmox_client
+        @proxmox_client ||= build_proxmox_client
+      end
+
+      # The endpoint map over #proxmox_client. Memoized.
+      def proxmox_api
+        # Anchor at top level: inside Chef::Knife, a bare Knife resolves to Chef::Knife.
+        @proxmox_api ||= ::Knife::Proxmox::Api.new(proxmox_client)
+      end
+
+      # Print a colored "label: value" line, skipping blank values. Not a knife-core helper;
+      # commands depend on it being defined here.
+      def msg_pair(label, value, color = :cyan)
+        ui.info("#{ui.color(label, color)}: #{value}") if value && !value.to_s.empty?
+      end
+
+      # Whether a token secret resolves for the given cluster (symbol-keyed hash), using the
+      # same precedence as #resolve_token_secret but without fatal-ing. Lets `cluster list`
+      # report secret presence from a single source of truth.
+      def proxmox_token_secret_present?(cluster_key, cluster_hash)
+        !token_secret_from_sources(cluster_key, cluster_hash).nil?
+      end
+
+      private
+
+      def resolve_cluster_config
+        cluster_key = config[:proxmox_cluster] || Chef::Config[:knife][:proxmox_default_cluster]
+        if cluster_key.nil? || cluster_key.to_s.empty?
+          ui.fatal!(
+            "no Proxmox cluster selected: pass --proxmox-cluster NAME or set " \
+            "knife[:proxmox_default_cluster]. Available: #{available_cluster_keys}"
+          )
+        end
+
+        cluster = proxmox_clusters[cluster_key.to_s] || proxmox_clusters[cluster_key.to_sym]
+        unless cluster
+          ui.fatal!(
+            "unknown Proxmox cluster #{cluster_key.inspect}. " \
+            "Available: #{available_cluster_keys}"
+          )
+        end
+
+        cluster = cluster.transform_keys(&:to_sym)
+        cluster[:token_secret] = resolve_token_secret(cluster_key.to_s, cluster)
+        cluster
+      end
+
+      def build_proxmox_client
+        cluster = proxmox_cluster_config
+        verify_ssl = cluster.fetch(:verify_ssl, true) != false
+        ui.warn(tls_disabled_warning(cluster)) unless verify_ssl
+
+        # Anchor at top level: inside Chef::Knife, a bare Knife resolves to Chef::Knife.
+        ::Knife::Proxmox::Client.new(
+          host:         cluster[:host],
+          token_id:     cluster[:token_id],
+          token_secret: cluster[:token_secret],
+          port:         cluster.fetch(:port, 8006),
+          verify_ssl:
+        )
+      end
+
+      def proxmox_clusters
+        # The nested clusters hash has no CLI equivalent; read it straight from Chef::Config.
+        Chef::Config[:knife][:proxmox_clusters] || {}
+      end
+
+      # Resolve the token secret or fatal, so an empty secret never reaches the wire.
+      def resolve_token_secret(cluster_key, cluster_hash)
+        guard_env_key_collisions
+
+        secret = token_secret_from_sources(cluster_key, cluster_hash)
+        unless secret
+          ui.fatal!(
+            "no Proxmox token secret for cluster #{cluster_key.inspect}: set #{ENV_SECRET_GLOBAL}, " \
+            "#{per_cluster_env_var(cluster_key)}, or knife[:proxmox_clusters][#{cluster_key.inspect}][:token_secret]"
+          )
+        end
+
+        secret
+      end
+
+      # Token-secret precedence: global ENV, then per-cluster ENV, then the config file.
+      # The single source of truth for the precedence order (reused by the presence check).
+      def token_secret_from_sources(cluster_key, cluster_hash)
+        present(ENV[ENV_SECRET_GLOBAL]) ||
+          present(ENV[per_cluster_env_var(cluster_key)]) ||
+          present(cluster_hash[:token_secret])
+      end
+
+      # The per-cluster ENV var name for a given cluster key.
+      def per_cluster_env_var(cluster_key)
+        "#{ENV_SECRET_PREFIX}#{env_key(cluster_key)}"
+      end
+
+      # Normalize a cluster key into an ENV-var-safe suffix: upcase, non-alphanumeric -> "_".
+      def env_key(cluster_key)
+        cluster_key.to_s.upcase.gsub(/[^A-Z0-9]/, "_")
+      end
+
+      # Fatal if two configured cluster keys collapse to the same per-cluster ENV var name,
+      # because an override meant for one would silently apply to the other.
+      def guard_env_key_collisions
+        groups = proxmox_clusters.keys.group_by { |key| env_key(key) }
+        collision = groups.find { |_normalized, keys| keys.length > 1 }
+        return unless collision
+
+        normalized, keys = collision
+        ui.fatal!(
+          "Proxmox cluster keys #{keys.map(&:to_s).sort.inspect} both map to ENV var " \
+          "#{ENV_SECRET_PREFIX}#{normalized}; rename one to disambiguate the per-cluster secret override"
+        )
+      end
+
+      def available_cluster_keys
+        keys = proxmox_clusters.keys.map(&:to_s).sort
+        keys.empty? ? "(none configured)" : keys.join(", ")
+      end
+
+      def present(value)
+        return nil if value.nil?
+
+        str = value.to_s
+        str.empty? ? nil : value
+      end
+
+      def tls_disabled_warning(cluster)
+        "TLS certificate verification is DISABLED for Proxmox host " \
+          "#{cluster[:host]} (verify_ssl: false) — connection is vulnerable to MITM"
+      end
+    end
+  end
+end