pvectl 0.2.0

data/lib/pvectl/commands/shared_flags.rb

@@ -0,0 +1,155 @@
+# frozen_string_literal: true
+
+module Pvectl
+  module Commands
+    # Shared flag definitions for command registration.
+    #
+    # Provides reusable flag groups that multiple commands share.
+    # Called during command registration to DRY up flag definitions.
+    #
+    # @example Usage in a command's register method
+    #   def self.register(cli)
+    #     cli.command :start do |c|
+    #       SharedFlags.lifecycle(c)
+    #       c.action { |g, o, a| ... }
+    #     end
+    #   end
+    #
+    module SharedFlags
+      # Defines the 8 flags shared by all lifecycle commands.
+      #
+      # @param command [GLI::Command] the command to add flags to
+      # @return [void]
+      def self.lifecycle(command)
+        command.desc "Timeout in seconds for sync operations"
+        command.flag [:timeout], type: Integer, arg_name: "SECONDS"
+
+        command.desc "Force async mode (return task ID immediately)"
+        command.switch [:async], negatable: false
+
+        command.desc "Force sync mode (wait for completion)"
+        command.switch [:wait], negatable: false
+
+        command.desc "Select all VMs"
+        command.switch [:all, :A], negatable: false
+
+        command.desc "Filter by node name"
+        command.flag [:node, :n], arg_name: "NODE"
+
+        command.desc "Skip confirmation prompt"
+        command.switch [:yes, :y], negatable: false
+
+        command.desc "Stop on first error (default: continue and report all)"
+        command.switch [:"fail-fast"], negatable: false
+
+        command.desc "Filter VMs by selector (e.g., status=running,tags=prod)"
+        command.flag [:l, :selector], arg_name: "SELECTOR", multiple: true
+      end
+
+      # Defines config flags shared between VM and container operations.
+      #
+      # @param command [GLI::Command] the command to add flags to
+      # @return [void]
+      def self.common_config(command)
+        command.desc "Number of CPU cores"
+        command.flag [:cores], type: Integer, arg_name: "N"
+
+        command.desc "Memory in MB"
+        command.flag [:memory], type: Integer, arg_name: "MB"
+
+        command.desc "Network config (repeatable): VM: bridge=X[,model=Y,tag=Z], CT: bridge=X[,name=Y,ip=Z]"
+        command.flag [:net], arg_name: "CONFIG", multiple: true
+
+        command.desc "Tags (comma-separated)"
+        command.flag [:tags], arg_name: "TAGS"
+
+        command.desc "Target node"
+        command.flag [:node], arg_name: "NODE"
+
+        command.desc "Start resource after operation"
+        command.switch [:start], negatable: true, default_value: nil
+      end
+
+      # Defines VM-specific config flags.
+      #
+      # @param command [GLI::Command] the command to add flags to
+      # @return [void]
+      def self.vm_config(command)
+        command.desc "Number of CPU sockets"
+        command.flag [:sockets], type: Integer, arg_name: "N"
+
+        command.desc "CPU type"
+        command.flag [:"cpu-type"], arg_name: "TYPE"
+
+        command.desc "Enable NUMA"
+        command.switch [:numa], negatable: true, default_value: nil
+
+        command.desc "Balloon memory in MB (0 to disable)"
+        command.flag [:balloon], type: Integer, arg_name: "MB"
+
+        command.desc "Disk config (repeatable)"
+        command.flag [:disk], arg_name: "CONFIG", multiple: true
+
+        command.desc "SCSI controller type"
+        command.flag [:scsihw], arg_name: "TYPE"
+
+        command.desc "CD-ROM ISO image"
+        command.flag [:cdrom], arg_name: "ISO"
+
+        command.desc "BIOS type"
+        command.flag [:bios], arg_name: "TYPE"
+
+        command.desc "Boot order"
+        command.flag [:"boot-order"], arg_name: "ORDER"
+
+        command.desc "Machine type"
+        command.flag [:machine], arg_name: "TYPE"
+
+        command.desc "EFI disk config"
+        command.flag [:efidisk], arg_name: "CONFIG"
+
+        command.desc "Cloud-init config"
+        command.flag [:"cloud-init"], arg_name: "CONFIG"
+
+        command.desc "Enable QEMU guest agent"
+        command.switch [:agent], negatable: true, default_value: nil
+
+        command.desc "OS type"
+        command.flag [:ostype], arg_name: "TYPE"
+      end
+
+      # Defines container-specific config flags.
+      #
+      # @param command [GLI::Command] the command to add flags to
+      # @return [void]
+      def self.container_config(command)
+        command.desc "Root filesystem config"
+        command.flag [:rootfs], arg_name: "CONFIG"
+
+        command.desc "Mount point config (repeatable)"
+        command.flag [:mp], arg_name: "CONFIG", multiple: true
+
+        command.desc "Swap size in MB"
+        command.flag [:swap], type: Integer, arg_name: "MB"
+
+        command.desc "Create privileged container"
+        command.switch [:privileged], negatable: true, default_value: nil
+
+        command.desc "Container features"
+        command.flag [:features], arg_name: "FEATURES"
+
+        command.desc "Root password"
+        command.flag [:password], arg_name: "PASSWORD"
+
+        command.desc "SSH public keys file"
+        command.flag [:"ssh-public-keys"], arg_name: "FILE"
+
+        command.desc "Start at boot"
+        command.switch [:onboot], negatable: true, default_value: nil
+
+        command.desc "Startup/shutdown order"
+        command.flag [:startup], arg_name: "SPEC"
+      end
+    end
+  end
+end

data/lib/pvectl/commands/shutdown.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+module Pvectl
+  module Commands
+    # Handler for the `pvectl shutdown` command.
+    #
+    # Shuts down one or more virtual machines gracefully (ACPI).
+    #
+    # @example Shutdown a single VM
+    #   pvectl shutdown vm 100
+    #
+    # @example Shutdown with sync mode
+    #   pvectl shutdown vm 100 --wait
+    #
+    class Shutdown
+      include VmLifecycleCommand
+
+      # Registers the shutdown command with the CLI.
+      #
+      # @param cli [GLI::App] the CLI application object
+      # @return [void]
+      def self.register(cli)
+        cli.desc "Shutdown virtual machines or containers gracefully"
+        cli.long_desc <<~HELP
+          Gracefully shut down one or more virtual machines or containers.
+          Sends an ACPI shutdown signal to VMs or a clean shutdown to containers,
+          allowing the guest OS to shut down properly.
+
+          This is the recommended way to stop production workloads. For
+          immediate termination, use 'pvectl stop' instead.
+
+          EXAMPLES
+            Graceful shutdown of a VM:
+              $ pvectl shutdown vm 100
+
+            Shutdown with wait and timeout:
+              $ pvectl shutdown vm 100 --wait --timeout 120
+
+            Shutdown all running VMs on a node:
+              $ pvectl shutdown vm --all --node pve1 -l status=running --yes
+
+          NOTES
+            Requires QEMU Guest Agent or ACPI support in the VM for graceful
+            shutdown. If the guest doesn't respond, the shutdown may time out.
+
+            Use --timeout with --wait to set a maximum wait time.
+
+          SEE ALSO
+            pvectl help stop            Hard stop (immediate, may cause data loss)
+            pvectl help restart         Reboot resources
+        HELP
+        cli.arg_name "RESOURCE_TYPE [ID...]"
+        cli.command :shutdown do |c|
+          SharedFlags.lifecycle(c)
+
+          c.action do |global_options, options, args|
+            resource_type = args.shift
+            resource_ids = args
+            exit_code = case resource_type
+            when "container", "ct"
+              ShutdownContainer.execute(resource_type, resource_ids, options, global_options)
+            else
+              execute(resource_type, resource_ids, options, global_options)
+            end
+            exit exit_code if exit_code != 0
+          end
+        end
+      end
+
+      OPERATION = :shutdown
+    end
+  end
+end

data/lib/pvectl/commands/shutdown_container.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Pvectl
+  module Commands
+    # Handler for the `pvectl shutdown container` command.
+    #
+    # Shuts down one or more LXC containers gracefully.
+    #
+    # @example Shutdown a single container
+    #   pvectl shutdown container 200
+    #
+    class ShutdownContainer
+      include ContainerLifecycleCommand
+
+      OPERATION = :shutdown
+    end
+  end
+end

data/lib/pvectl/commands/start.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+module Pvectl
+  module Commands
+    # Handler for the `pvectl start` command.
+    #
+    # Starts one or more virtual machines.
+    #
+    # @example Start a single VM
+    #   pvectl start vm 100
+    #
+    # @example Start with JSON output
+    #   pvectl start vm 100 -o json
+    #
+    class Start
+      include VmLifecycleCommand
+
+      # Registers the start command with the CLI.
+      #
+      # @param cli [GLI::App] the CLI application object
+      # @return [void]
+      def self.register(cli)
+        cli.desc "Start virtual machines or containers"
+        cli.long_desc <<~HELP
+          Start one or more virtual machines or containers. Supports single
+          resource, multiple IDs, and batch operations with selectors.
+
+          By default, operations run asynchronously (fire-and-forget). Use
+          --wait to wait for completion, or --async to explicitly force async.
+
+          EXAMPLES
+            Start a single VM:
+              $ pvectl start vm 100
+
+            Start multiple VMs:
+              $ pvectl start vm 100 101 102
+
+            Start a container:
+              $ pvectl start ct 200
+
+            Start all stopped VMs on a node:
+              $ pvectl start vm --all -l status=stopped --node pve1
+
+            Wait for start to complete with timeout:
+              $ pvectl start vm 100 --wait --timeout 60
+
+          NOTES
+            Batch operations (--all) require --yes or interactive confirmation.
+
+            Use selectors (-l) to filter: status, name, tags, pool.
+            Multiple selectors use AND logic.
+
+          SEE ALSO
+            pvectl help stop            Hard stop resources
+            pvectl help shutdown        Graceful shutdown
+            pvectl help get vms         List VMs and their status
+        HELP
+        cli.arg_name "RESOURCE_TYPE [ID...]"
+        cli.command :start do |c|
+          SharedFlags.lifecycle(c)
+
+          c.action do |global_options, options, args|
+            resource_type = args.shift
+            resource_ids = args
+            exit_code = case resource_type
+            when "container", "ct"
+              StartContainer.execute(resource_type, resource_ids, options, global_options)
+            else
+              execute(resource_type, resource_ids, options, global_options)
+            end
+            exit exit_code if exit_code != 0
+          end
+        end
+      end
+
+      OPERATION = :start
+    end
+  end
+end

data/lib/pvectl/commands/start_container.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Pvectl
+  module Commands
+    # Handler for the `pvectl start container` command.
+    #
+    # Starts one or more LXC containers.
+    #
+    # @example Start a single container
+    #   pvectl start container 200
+    #
+    class StartContainer
+      include ContainerLifecycleCommand
+
+      OPERATION = :start
+    end
+  end
+end

data/lib/pvectl/commands/stop.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+module Pvectl
+  module Commands
+    # Handler for the `pvectl stop` command.
+    #
+    # Stops one or more virtual machines (hard stop).
+    #
+    # @example Stop a single VM
+    #   pvectl stop vm 100
+    #
+    # @example Stop with JSON output
+    #   pvectl stop vm 100 -o json
+    #
+    class Stop
+      include VmLifecycleCommand
+
+      # Registers the stop command with the CLI.
+      #
+      # @param cli [GLI::App] the CLI application object
+      # @return [void]
+      def self.register(cli)
+        cli.desc "Stop virtual machines or containers (hard stop)"
+        cli.long_desc <<~HELP
+          Immediately stop one or more virtual machines or containers. This is
+          a hard stop (equivalent to pulling the power cord) — the guest OS is
+          NOT shut down gracefully.
+
+          For a clean shutdown, use 'pvectl shutdown' instead.
+
+          EXAMPLES
+            Hard stop a VM:
+              $ pvectl stop vm 100
+
+            Stop multiple containers:
+              $ pvectl stop ct 200 201
+
+            Stop all running VMs:
+              $ pvectl stop vm --all -l status=running --yes
+
+            Stop with sync wait:
+              $ pvectl stop vm 100 --wait --timeout 30
+
+          NOTES
+            Hard stop may cause data loss or filesystem corruption in the guest.
+            Prefer 'shutdown' for production workloads.
+
+            Batch operations (--all) require --yes or interactive confirmation.
+
+          SEE ALSO
+            pvectl help shutdown        Graceful shutdown (recommended)
+            pvectl help start           Start resources
+        HELP
+        cli.arg_name "RESOURCE_TYPE [ID...]"
+        cli.command :stop do |c|
+          SharedFlags.lifecycle(c)
+
+          c.action do |global_options, options, args|
+            resource_type = args.shift
+            resource_ids = args
+            exit_code = case resource_type
+            when "container", "ct"
+              StopContainer.execute(resource_type, resource_ids, options, global_options)
+            else
+              execute(resource_type, resource_ids, options, global_options)
+            end
+            exit exit_code if exit_code != 0
+          end
+        end
+      end
+
+      OPERATION = :stop
+    end
+  end
+end

data/lib/pvectl/commands/stop_container.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Pvectl
+  module Commands
+    # Handler for the `pvectl stop container` command.
+    #
+    # Stops one or more LXC containers (hard stop).
+    #
+    # @example Stop a single container
+    #   pvectl stop container 200
+    #
+    class StopContainer
+      include ContainerLifecycleCommand
+
+      OPERATION = :stop
+    end
+  end
+end

data/lib/pvectl/commands/suspend.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module Pvectl
+  module Commands
+    # Handler for the `pvectl suspend` command.
+    #
+    # Suspends one or more virtual machines (hibernate).
+    #
+    # @example Suspend a single VM
+    #   pvectl suspend vm 100
+    #
+    # @example Suspend with sync mode
+    #   pvectl suspend vm 100 --wait
+    #
+    class Suspend
+      include VmLifecycleCommand
+
+      # Registers the suspend command with the CLI.
+      #
+      # @param cli [GLI::App] the CLI application object
+      # @return [void]
+      def self.register(cli)
+        cli.desc "Suspend virtual machines (hibernate)"
+        cli.long_desc <<~HELP
+          Suspend (hibernate) one or more virtual machines. Saves the VM's
+          memory state to disk and stops it. The VM can be resumed later
+          with 'pvectl resume'.
+
+          Only available for VMs. Containers do not support suspend.
+
+          EXAMPLES
+            Suspend a VM:
+              $ pvectl suspend vm 100
+
+            Suspend all running VMs on a node:
+              $ pvectl suspend vm --all --node pve1 -l status=running --yes
+
+          NOTES
+            Suspend saves the full memory state to disk, which may take time
+            for VMs with large memory allocations.
+
+            Not available for containers.
+
+          SEE ALSO
+            pvectl help resume          Resume suspended VMs
+            pvectl help shutdown        Graceful shutdown (no state saved)
+        HELP
+        cli.arg_name "RESOURCE_TYPE [ID...]"
+        cli.command :suspend do |c|
+          SharedFlags.lifecycle(c)
+
+          c.action do |global_options, options, args|
+            resource_type = args.shift
+            resource_ids = args
+            exit_code = execute(resource_type, resource_ids, options, global_options)
+            exit exit_code if exit_code != 0
+          end
+        end
+      end
+
+      OPERATION = :suspend
+    end
+  end
+end