Class: Pvectl::Commands::Describe::Command

Inherits:
Object
  • Object
show all
Defined in:
lib/pvectl/commands/describe/command.rb

Overview

Dispatcher for the ‘pvectl describe <resource_type> <name>` command.

Uses EXISTING Get infrastructure:

  • Commands::Get::ResourceRegistry for handler lookup

  • Services::Get::ResourceService for orchestration

  • Handlers call describe() instead of list()

Examples:

Basic usage

Commands::Describe::Command.execute("node", "pve1", options, global_options)

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(resource_type, resource_name, options, global_options, extra_args: [], registry: Get::ResourceRegistry) ⇒ Command

Creates a new Describe command instance.

Parameters:

  • resource_type (String, nil) —

    type of resource

  • resource_name (String, nil) —

    name of resource to describe

  • options (Hash) —

    command options

  • global_options (Hash) —

    global CLI options

  • registry (Class) (defaults to: Get::ResourceRegistry) —

    registry class for dependency injection



161
162
163
164
165
166
167
168
169
 
# File 'lib/pvectl/commands/describe/command.rb', line 161

def initialize(resource_type, resource_name, options, global_options,
               extra_args: [], registry: Get::ResourceRegistry)
  @resource_type = resource_type
  @resource_name = resource_name
  @options = options
  @global_options = global_options
  @extra_args = extra_args
  @registry = registry
end

Class Method Details

.execute(resource_type, resource_name, options, global_options, extra_args: []) ⇒ Integer

Executes the describe command.

Parameters:

  • resource_type (String, nil) —

    type of resource (e.g., “node”)

  • resource_name (String, nil) —

    name of resource to describe

  • options (Hash) —

    command-specific options

  • global_options (Hash) —

    global CLI options

Returns:

  • (Integer) —

    exit code



150
151
152
 
# File 'lib/pvectl/commands/describe/command.rb', line 150

def self.execute(resource_type, resource_name, options, global_options, extra_args: [])
  new(resource_type, resource_name, options, global_options, extra_args: extra_args).execute
end

.register(cli) ⇒ void

This method returns an undefined value.

Registers the describe command with the CLI.

Parameters:

  • cli (GLI::App) —

    the CLI application object



21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
 
# File 'lib/pvectl/commands/describe/command.rb', line 21

def self.register(cli)
  cli.desc "Show detailed information about a resource"
  cli.long_desc <<~HELP
    Show detailed information about a specific resource. Displays all
    configuration details, runtime status, and related resources in
    structured, labeled sections.

    Unlike 'get' which lists many resources in a table, 'describe' shows
    everything known about a single resource in a readable format.
    Unknown or future Proxmox config keys appear in an "Additional
    Configuration" catch-all section, so new API fields are never hidden.

    RESOURCE TYPES
      node NAME                 Full node diagnostics (CPU, memory, storage, services)
      vm VMID                   Comprehensive VM configuration (see VM SECTIONS below)
      container VMID            Comprehensive container configuration (see CT SECTIONS below)
      storage NAME              Storage pool info, content types, usage
      snapshot NAME             Snapshot metadata and snapshot tree (use --vmid)
      volume TYPE ID DISK       Virtual disk details (e.g., describe volume vm 100 scsi0)

    VM SECTIONS (matches PVE web UI tabs)
      Summary        HA state, CPU/memory usage, bootdisk size, uptime,
                     QEMU version, machine type, network/disk I/O
      Block Device Statistics
                     Per-disk I/O counters (read/written bytes, IOPS)
                     for running VMs
      Hardware       Memory (with balloon details: actual, max, free
                     and total inside guest when ballooning active),
                     balloon, processors, BIOS, machine, display,
                     SCSI controller, EFI/TPM, disks, network, USB/PCI,
                     serial ports, audio
      Cloud-Init     Type, user, DNS, SSH keys, IP config
      Options        Start at boot, startup order, OS type, boot order,
                     tablet, hotplug, ACPI, KVM, freeze, localtime,
                     NUMA, QEMU guest agent, protection, firewall,
                     hookscript
      Firewall       Enable, input/output policies, aliases, IP sets
      Firewall Rules Per-rule table (ENABLED, TYPE, ACTION, PROTO,
                     SOURCE, DEST, COMMENT)
      Task History   Recent operations (type, status, date, duration, user)
      Snapshots      Name, date, VM state, description
      Pending        Configuration changes awaiting reboot
      Additional     Catch-all for unrecognized config keys

    CT SECTIONS (matches PVE web UI tabs)
      Summary        CPU/memory/swap/rootfs usage, uptime, PID, network I/O
      Resources      Memory, swap, cores, root filesystem, mountpoints
      Network        Interfaces with bridge, IP, MAC
      DNS            Nameserver, search domain
      Options        Start at boot, startup order, OS type, architecture,
                     unprivileged, features, console mode, TTY, protection,
                     hookscript
      Firewall       Enable, input/output policies, aliases, IP sets
      Firewall Rules Per-rule table (ENABLED, TYPE, ACTION, PROTO,
                     SOURCE, DEST, COMMENT)
      Task History   Recent operations (type, status, date, duration, user)
      Snapshots      Name, date, description
      High Avail.    HA state and group
      Additional     Catch-all for unrecognized config keys

    EXAMPLES
      Full node diagnostics:
        $ pvectl describe node pve1

      VM details — all configuration sections:
        $ pvectl describe vm 100

      Container details — all configuration sections:
        $ pvectl describe container 200

      Storage pool information (node-specific):
        $ pvectl describe storage local-lvm --node pve1

      Snapshot metadata for a specific VM:
        $ pvectl describe snapshot before-upgrade --vmid 100

      Snapshot search across multiple VMs:
        $ pvectl describe snapshot before-upgrade --vmid 100 --vmid 101

      Snapshot search cluster-wide (all VMs and containers):
        $ pvectl describe snapshot before-upgrade

      Virtual disk details:
        $ pvectl describe volume vm 100 scsi0

      Container rootfs:
        $ pvectl describe volume ct 200 rootfs

    NOTES
      For local storage, --node is required because local storage exists
      independently on each node.

      Snapshot describe shows a visual tree of all snapshots for the
      matching VMs, highlighting the described snapshot.

      VM and container describe output includes ALL configuration from
      the Proxmox API. Any fields not recognized by the presenter are
      grouped in the "Additional Configuration" section at the end.

    SEE ALSO
      pvectl help get           List resources in table format
      pvectl help get volume    List virtual disks attached to VMs/containers
      pvectl help logs          Show task history and logs
  HELP
  cli.arg_name "RESOURCE_TYPE NAME"
  cli.command :describe do |c|
    c.desc "Filter by node name (required for local storage)"
    c.flag [:node], arg_name: "NODE"

    c.desc "Filter by VM/CT ID (repeatable)"
    c.flag [:vmid], arg_name: "VMID", multiple: true

    c.action do |global_options, options, args|
      resource_type = args[0]
      resource_name = args[1]
      extra_args = args[2..] || []
      exit_code = execute(resource_type, resource_name, options, global_options, extra_args: extra_args)
      exit exit_code if exit_code != 0
    end
  end
end

Instance Method Details

#execute ⇒ Integer

Executes the describe operation.

Returns:

  • (Integer) —

    exit code



174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
 
# File 'lib/pvectl/commands/describe/command.rb', line 174

def execute
  return missing_resource_type_error if @resource_type.nil?
  return missing_resource_name_error if @resource_name.nil?

  handler = @registry.for(@resource_type)
  return unknown_resource_error unless handler

  run_describe(handler)
  ExitCodes::SUCCESS
rescue Pvectl::ResourceNotFoundError => e
  $stderr.puts "Error: #{e.message}"
  ExitCodes::NOT_FOUND
rescue Timeout::Error => e
  $stderr.puts "Error: #{e.message}"
  ExitCodes::CONNECTION_ERROR
rescue Errno::ECONNREFUSED => e
  $stderr.puts "Error: #{e.message}"
  ExitCodes::CONNECTION_ERROR
rescue SocketError => e
  $stderr.puts "Error: #{e.message}"
  ExitCodes::CONNECTION_ERROR
end