morpheus-cli 9.0.2 → 9.1.0

data/lib/morpheus/cli/commands/host_vm_groups_command.rb

@@ -0,0 +1,423 @@
+require 'morpheus/cli/cli_command'
+
+class Morpheus::Cli::HostVmGroupsCommand
+  include Morpheus::Cli::CliCommand
+  include Morpheus::Cli::ProvisioningHelper
+  include Morpheus::Cli::WhoamiHelper
+  include Morpheus::Cli::InfrastructureHelper
+  include Morpheus::Cli::AffinityHelper
+
+  set_command_name :'host-vm-groups'
+
+  register_subcommands :list, :get, :add, :update, :remove
+
+  def connect(opts)
+    @api_client = establish_remote_appliance_connection(opts)
+    @host_vm_groups_interface = @api_client.host_vm_groups
+    @clouds_interface = @api_client.clouds
+    @clusters_interface = @api_client.clusters
+    @cloud_resource_pools_interface = @api_client.cloud_resource_pools
+  end
+
+  def handle(args)
+    handle_subcommand(args)
+  end
+
+  def list(args)
+    options = {}
+    params = {}
+    optparse = Morpheus::Cli::OptionParser.new do |opts|
+      opts.banner = subcommand_usage()
+      opts.on('--cloud CLOUD', String, "Filter by cloud name or id") do |val|
+        options[:cloud] = val
+      end
+      opts.on('--cluster CLUSTER', String, "Filter by cluster name or id") do |val|
+        options[:cluster] = val
+      end
+      build_standard_list_options(opts, options)
+      opts.footer = "List host/VM groups.\n" \
+        "Use --cloud or --cluster to scope results. Without a scope all groups visible to the user are listed."
+    end
+    optparse.parse!(args)
+    verify_args!(args:args, optparse:optparse, count:0)
+    connect(options)
+
+    if options[:cloud] && options[:cluster]
+      cloud = find_cloud_by_name_or_id(options[:cloud])
+      return 1 if cloud.nil?
+      pool = find_resource_pool_cluster_by_name_or_id(cloud, options[:cluster])
+      return 1 if pool.nil?
+      params.merge!(parse_list_options(options))
+      params['poolId'] = pool['id']
+      @clouds_interface.setopts(options)
+      if options[:dry_run]
+        print_dry_run @clouds_interface.dry.list_host_vm_groups(cloud['id'], params)
+        return
+      end
+      json_response = @clouds_interface.list_host_vm_groups(cloud['id'], params)
+      render_response(json_response, options, 'hostVmGroups') do
+        rows = json_response['hostVmGroups']
+        print_h1 "Host/VM Groups: #{cloud['name']} / #{pool['name']}", parse_list_subtitles(options), options
+        if rows.empty?
+          print cyan, "No host/VM groups found.", reset, "\n"
+        else
+          print as_pretty_table(rows, host_vm_group_list_columns, options)
+          print_results_pagination(json_response)
+        end
+        print reset, "\n"
+      end
+    elsif options[:cloud]
+      cloud = find_cloud_by_name_or_id(options[:cloud])
+      return 1 if cloud.nil?
+      params.merge!(parse_list_options(options))
+      @clouds_interface.setopts(options)
+      if options[:dry_run]
+        print_dry_run @clouds_interface.dry.list_host_vm_groups(cloud['id'], params)
+        return
+      end
+      json_response = @clouds_interface.list_host_vm_groups(cloud['id'], params)
+      render_response(json_response, options, 'hostVmGroups') do
+        rows = json_response['hostVmGroups']
+        print_h1 "Host/VM Groups: #{cloud['name']}", parse_list_subtitles(options), options
+        if rows.empty?
+          print cyan, "No host/VM groups found.", reset, "\n"
+        else
+          print as_pretty_table(rows, host_vm_group_list_columns, options)
+          print_results_pagination(json_response)
+        end
+        print reset, "\n"
+      end
+    elsif options[:cluster]
+      cluster_scope = find_cluster_list_scope_by_name_or_id(options[:cluster])
+      return 1 if cluster_scope.nil?
+      params.merge!(parse_list_options(options))
+      if cluster_scope[:type] == :managed_cluster
+        cluster = cluster_scope[:cluster]
+        @clusters_interface.setopts(options)
+        if options[:dry_run]
+          print_dry_run @clusters_interface.dry.list_host_vm_groups(cluster['id'], params)
+          return
+        end
+        json_response = @clusters_interface.list_host_vm_groups(cluster['id'], params)
+        scope_name = cluster['name']
+      else
+        cloud = cluster_scope[:cloud]
+        pool = cluster_scope[:pool]
+        params['poolId'] = pool['id']
+        @clouds_interface.setopts(options)
+        if options[:dry_run]
+          print_dry_run @clouds_interface.dry.list_host_vm_groups(cloud['id'], params)
+          return
+        end
+        json_response = @clouds_interface.list_host_vm_groups(cloud['id'], params)
+        scope_name = "#{cloud['name']} / #{pool['name']}"
+      end
+      render_response(json_response, options, 'hostVmGroups') do
+        rows = json_response['hostVmGroups']
+        print_h1 "Host/VM Groups: #{scope_name}", parse_list_subtitles(options), options
+        if rows.empty?
+          print cyan, "No host/VM groups found.", reset, "\n"
+        else
+          print as_pretty_table(rows, host_vm_group_list_columns, options)
+          print_results_pagination(json_response)
+        end
+        print reset, "\n"
+      end
+    else
+      # No top-level list route; /api/host-vm-groups exposes only /{id}.
+      print_error Morpheus::Terminal.angry_prompt
+      puts_error "#{command_name} list requires a scope: pass --cloud CLOUD or --cluster CLUSTER\n#{optparse}"
+      return 1, "scope required"
+    end
+    return 0, nil
+  end
+
+  def get(args)
+    options = {}
+    optparse = Morpheus::Cli::OptionParser.new do |opts|
+      opts.banner = subcommand_usage("[id]")
+      build_standard_get_options(opts, options)
+      opts.footer = "Get details about a host/VM group.\n" \
+        "[id] is required. This is the numeric id of the host/VM group."
+    end
+    optparse.parse!(args)
+    verify_args!(args:args, optparse:optparse, count:1)
+    connect(options)
+
+    id = args[0]
+    params = {}
+    params.merge!(parse_query_options(options))
+    @host_vm_groups_interface.setopts(options)
+    if options[:dry_run]
+      print_dry_run @host_vm_groups_interface.dry.get(id, params)
+      return
+    end
+    json_response = @host_vm_groups_interface.get(id, params)
+    render_response(json_response, options, 'hostVmGroup') do
+      row = json_response['hostVmGroup']
+      print_h1 "Host/VM Group Details", [], options
+      print_description_list(host_vm_group_detail_columns, row)
+      if row['servers'] && row['servers'].size > 0
+        print_h2 "Servers", options
+        print as_pretty_table(row['servers'], [:id, :name], options)
+      end
+      print reset, "\n"
+    end
+    return 0, nil
+  end
+
+  def add(args)
+    options = {}
+    optparse = Morpheus::Cli::OptionParser.new do |opts|
+      opts.banner = subcommand_usage("[options]")
+      opts.on('--cloud CLOUD', String, "Cloud name or id") do |val|
+        options[:options] ||= {}
+        options[:options]['cloudId'] = val
+      end
+      opts.on('--cluster CLUSTER', String, "Cluster name or id") do |val|
+        options[:options] ||= {}
+        options[:options]['clusterId'] = val
+      end
+      opts.on('--servers ID1,ID2', Array, "Server ids to add to the group") do |val|
+        options[:options] ||= {}
+        options[:options]['servers'] = val.map {|s| {'id' => s.to_i}}
+      end
+      add_perms_options(opts, options, ['plans'])
+      build_standard_add_options(opts, options)
+      opts.footer = "Create a new host/VM group.\n" \
+        "Specify --cloud or --cluster to scope the group."
+    end
+    optparse.parse!(args)
+    verify_args!(args:args, optparse:optparse, count:0)
+    connect(options)
+
+    begin
+      if options[:payload]
+        payload = options[:payload]
+        payload.deep_merge!(options[:options].reject {|k,v| k.is_a?(Symbol) }) if options[:options]
+      else
+        options[:options] ||= {}
+        host_vm_group = Morpheus::Cli::OptionTypes.prompt(add_host_vm_group_option_types, options[:options], @api_client, {})
+
+        unless options[:options].key?('servers')
+          server_prompt = Morpheus::Cli::OptionTypes.prompt([{
+            'fieldName' => 'servers', 'fieldLabel' => 'Server', 'type' => 'multiTypeahead',
+            'optionSource' => 'searchServers', 'searchParameter' => 'phrase',
+            'description' => 'Select servers to add to the group.'
+          }], options[:options], @api_client, {})
+          host_vm_group['servers'] = server_prompt['servers'] if server_prompt['servers']
+        else
+          host_vm_group['servers'] = options[:options]['servers']
+        end
+
+        perms = prompt_permissions(options, is_master_account ? ['plans'] : ['plans', 'visibility', 'tenants'])
+        host_vm_group['resourcePermissions'] = perms['resourcePermissions'] unless perms['resourcePermissions'].nil?
+        host_vm_group['tenants'] = perms['tenantPermissions'] unless perms['tenantPermissions'].nil? || perms['tenantPermissions']['accounts'].empty?
+        host_vm_group['visibility'] = perms['resourcePool']['visibility'] if !perms['resourcePool'].nil? && !perms['resourcePool']['visibility'].nil?
+
+        payload = {'hostVmGroup' => host_vm_group}
+      end
+
+      # Create is scoped -- POST /api/clusters/{id}/host-vm-groups or
+      # /api/zones/{id}/host-vm-groups. There is no top-level create route.
+      scope_cloud   = options[:options] && options[:options]['cloudId']
+      scope_cluster = options[:options] && options[:options]['clusterId']
+      if scope_cloud && scope_cluster
+        cloud = find_cloud_by_name_or_id(scope_cloud)
+        return 1 if cloud.nil?
+        pool = find_resource_pool_cluster_by_name_or_id(cloud, scope_cluster)
+        return 1 if pool.nil?
+        if payload['hostVmGroup'].is_a?(Hash)
+          payload['hostVmGroup'].delete('cloudId')
+          payload['hostVmGroup'].delete('clusterId')
+          payload['hostVmGroup']['pool'] = {'id' => pool['id']}
+        end
+        @clouds_interface.setopts(options)
+        if options[:dry_run]
+          print_dry_run @clouds_interface.dry.create_host_vm_group(cloud['id'], payload)
+          return
+        end
+        json_response = @clouds_interface.create_host_vm_group(cloud['id'], payload)
+      elsif scope_cloud
+        cloud = find_cloud_by_name_or_id(scope_cloud)
+        return 1 if cloud.nil?
+        payload['hostVmGroup'].delete('cloudId') if payload['hostVmGroup'].is_a?(Hash)
+        @clouds_interface.setopts(options)
+        if options[:dry_run]
+          print_dry_run @clouds_interface.dry.create_host_vm_group(cloud['id'], payload)
+          return
+        end
+        json_response = @clouds_interface.create_host_vm_group(cloud['id'], payload)
+      elsif scope_cluster
+        cluster_scope = find_cluster_list_scope_by_name_or_id(scope_cluster)
+        return 1 if cluster_scope.nil?
+        if cluster_scope[:type] == :managed_cluster
+          cluster = cluster_scope[:cluster]
+          payload['hostVmGroup'].delete('clusterId') if payload['hostVmGroup'].is_a?(Hash)
+          @clusters_interface.setopts(options)
+          if options[:dry_run]
+            print_dry_run @clusters_interface.dry.create_host_vm_group(cluster['id'], payload)
+            return
+          end
+          json_response = @clusters_interface.create_host_vm_group(cluster['id'], payload)
+        else
+          cloud = cluster_scope[:cloud]
+          pool = cluster_scope[:pool]
+          if payload['hostVmGroup'].is_a?(Hash)
+            payload['hostVmGroup'].delete('clusterId')
+            payload['hostVmGroup']['pool'] = {'id' => pool['id']}
+          end
+          @clouds_interface.setopts(options)
+          if options[:dry_run]
+            print_dry_run @clouds_interface.dry.create_host_vm_group(cloud['id'], payload)
+            return
+          end
+          json_response = @clouds_interface.create_host_vm_group(cloud['id'], payload)
+        end
+      else
+        print_error Morpheus::Terminal.angry_prompt
+        puts_error "#{command_name} add requires a scope: pass --cloud CLOUD or --cluster CLUSTER\n#{optparse}"
+        return 1, "scope required"
+      end
+      render_response(json_response, options, 'hostVmGroup') do
+        row = json_response['hostVmGroup']
+        print_green_success "Created host/VM group #{row ? row['name'] : ''}"
+      end
+      return 0, nil
+    rescue RestClient::Exception => e
+      handle_affinity_rest_exception(e, options)
+      exit 1
+    end
+  end
+
+  def update(args)
+    options = {}
+    optparse = Morpheus::Cli::OptionParser.new do |opts|
+      opts.banner = subcommand_usage("[id] [options]")
+      build_option_type_options(opts, options, update_host_vm_group_option_types)
+      opts.on('--servers ID1,ID2', Array, "Server ids") do |val|
+        options[:options] ||= {}
+        options[:options]['servers'] = val.map {|s| {'id' => s.to_i}}
+      end
+      add_perms_options(opts, options, ['plans'])
+      build_standard_update_options(opts, options)
+      opts.footer = "Update a host/VM group.\n" \
+        "[id] is required. This is the numeric id of the host/VM group."
+    end
+    optparse.parse!(args)
+    verify_args!(args:args, optparse:optparse, count:1)
+    connect(options)
+
+    begin
+      id = args[0]
+      if options[:payload]
+        payload = options[:payload]
+        payload.deep_merge!(options[:options].reject {|k,v| k.is_a?(Symbol) }) if options[:options]
+      else
+        payload = {'hostVmGroup' => {}}
+        v_prompt = Morpheus::Cli::OptionTypes.no_prompt(update_host_vm_group_option_types, options[:options], @api_client, {})
+        payload.deep_merge!({'hostVmGroup' => v_prompt})
+
+        perms = prompt_permissions(options, is_master_account ? ['plans'] : ['plans', 'visibility', 'tenants'])
+        payload['hostVmGroup']['permissions'] = perms['resourcePermissions'] if perms['resourcePermissions']
+        payload['hostVmGroup']['visibility'] = perms['resourcePool']['visibility'] if !perms['resourcePool'].nil? && !perms['resourcePool']['visibility'].nil?
+
+        if options[:options]
+          payload.deep_merge!({'hostVmGroup' => options[:options].reject {|k,v| k.is_a?(Symbol) || payload['hostVmGroup'].key?(k) }})
+        end
+        if payload['hostVmGroup'].empty?
+          raise_command_error "Specify at least one option to update.\n#{optparse}"
+        end
+      end
+
+      @host_vm_groups_interface.setopts(options)
+      if options[:dry_run]
+        print_dry_run @host_vm_groups_interface.dry.update(id, payload)
+        return
+      end
+      json_response = @host_vm_groups_interface.update(id, payload)
+      render_response(json_response, options, 'hostVmGroup') do
+        updated = json_response['hostVmGroup']
+        print_green_success "Updated host/VM group #{updated ? updated['name'] : id}"
+      end
+      return 0, nil
+    rescue RestClient::Exception => e
+      handle_affinity_rest_exception(e, options)
+      exit 1
+    end
+  end
+
+  def remove(args)
+    options = {}
+    optparse = Morpheus::Cli::OptionParser.new do |opts|
+      opts.banner = subcommand_usage("[id]")
+      build_standard_remove_options(opts, options)
+      opts.footer = "Delete a host/VM group.\n" \
+        "[id] is required. This is the numeric id of the host/VM group."
+    end
+    optparse.parse!(args)
+    verify_args!(args:args, optparse:optparse, count:1)
+    connect(options)
+
+    id = args[0]
+    unless options[:yes] || ::Morpheus::Cli::OptionTypes.confirm("Are you sure you want to delete host/VM group '#{id}'?", options)
+      return 9, "aborted command"
+    end
+
+    @host_vm_groups_interface.setopts(options)
+    if options[:dry_run]
+      print_dry_run @host_vm_groups_interface.dry.destroy(id)
+      return
+    end
+    begin
+      json_response = @host_vm_groups_interface.destroy(id)
+      render_response(json_response, options) do
+        print_green_success "Removed host/VM group #{id}"
+      end
+      return 0, nil
+    rescue RestClient::Exception => e
+      handle_affinity_rest_exception(e, options)
+      exit 1
+    end
+  end
+
+  private
+
+  def host_vm_group_list_columns
+    {
+      "ID"            => 'id',
+      "Name"          => 'name',
+      "Type"          => lambda {|it| format_host_vm_group_type(it['type']) },
+      "Resource Pool" => lambda {|it| it['pool'] ? (it['pool']['name'] || it['pool']['id']) : '' },
+      "Servers"       => lambda {|it| (it['servers'] || []).size },
+    }.upcase_keys!
+  end
+
+  def host_vm_group_detail_columns
+    {
+      "ID"            => 'id',
+      "Name"          => 'name',
+      "Type"          => lambda {|it| format_host_vm_group_type(it['type']) },
+      "Ref Type"      => 'refType',
+      "Ref ID"        => 'refId',
+      "Resource Pool" => lambda {|it| it['pool'] ? (it['pool']['name'] || it['pool']['id']) : '' },
+      "Visibility"    => lambda {|it| it['visibility'].to_s.capitalize },
+      "Servers"       => lambda {|it| (it['servers'] || []).size },
+      "Source"        => 'source',
+    }
+  end
+
+  def add_host_vm_group_option_types
+    [
+      {'fieldName' => 'name', 'fieldLabel' => 'Name', 'type' => 'text', 'required' => true},
+      host_vm_group_type_option_type(required: true, default: 'HOST_GROUP'),
+    ]
+  end
+
+  def update_host_vm_group_option_types
+    [
+      {'fieldName' => 'name', 'fieldLabel' => 'Name', 'type' => 'text'},
+    ]
+  end
+
+end

data/lib/morpheus/cli/mixins/affinity_helper.rb

@@ -0,0 +1,118 @@
+require 'morpheus/cli/mixins/print_helper'
+
+# Mixin for Morpheus::Cli command classes
+# Single source of truth for affinity group / host-vm group enums and formatting.
+#
+# Keep this in sync with morpheus-ui and the OpenAPI shared affinity-type schema.
+# Defining these values here (rather than inline in each command) prevents the
+# definitions from drifting apart between cluster-scoped, cloud-scoped and
+# top-level flat-by-ID commands.
+module Morpheus::Cli::AffinityHelper
+
+  def self.included(klass)
+    klass.send :include, Morpheus::Cli::PrintHelper
+  end
+
+  # All affinity types supported by the API.
+  # The _MUST variants are mandatory placement constraints and are what the
+  # violations endpoint reports on.
+  AFFINITY_TYPES = [
+    {'name' => 'Keep Together (Should)', 'value' => 'KEEP_TOGETHER'},
+    {'name' => 'Keep Separate (Should)', 'value' => 'KEEP_SEPARATE'},
+    {'name' => 'Keep Together (Must)',   'value' => 'KEEP_TOGETHER_MUST'},
+    {'name' => 'Keep Separate (Must)',   'value' => 'KEEP_SEPARATE_MUST'},
+  ].freeze
+
+  # Group types, per HostVmGroup.HostVmGroupType (morpheus-ui rc-9.1.0,
+  # morpheus-domains/grails-app/domain/com/morpheus/HostVmGroup.groovy).
+  # SITE_GROUP exists in the enum but is not valid on either side of a combined
+  # VM-to-Host rule -- AffinityGroupService.applyRuleShapeFields rejects it.
+  HOST_VM_GROUP_TYPES = [
+    {'name' => 'Site Group', 'value' => 'SITE_GROUP'},
+    {'name' => 'Host Group', 'value' => 'HOST_GROUP'},
+    {'name' => 'VM Group',   'value' => 'VM_GROUP'},
+  ].freeze
+
+  def affinity_type_select_options
+    AFFINITY_TYPES.map {|it| it.dup }
+  end
+
+  def host_vm_group_type_select_options
+    HOST_VM_GROUP_TYPES.map {|it| it.dup }
+  end
+
+  # affinityType is editable on update as well as create.
+  # AffinityGroupService.updateAffinityGroup applies params.affinityGroup.affinityType,
+  # so callers may switch between MUST and non-MUST behaviour during an edit.
+  def affinity_type_option_type(required: false, default: nil)
+    opt = {
+      'fieldName'     => 'affinityType',
+      'fieldLabel'    => 'Type',
+      'type'          => 'select',
+      'selectOptions' => affinity_type_select_options,
+      'description'   => 'Affinity type. The _MUST variants are mandatory placement constraints.',
+    }
+    opt['required']     = true    if required
+    opt['defaultValue'] = default if default
+    opt
+  end
+
+  def host_vm_group_type_option_type(required: false, default: nil)
+    opt = {
+      'fieldName'     => 'type',
+      'fieldLabel'    => 'Group Type',
+      'type'          => 'select',
+      'selectOptions' => host_vm_group_type_select_options,
+      'description'   => 'Choose group type.',
+    }
+    opt['required']     = true    if required
+    opt['defaultValue'] = default if default
+    opt
+  end
+
+  def format_affinity_type(affinity_type)
+    found = AFFINITY_TYPES.find {|it| it['value'] == affinity_type.to_s }
+    found ? found['name'].sub(' (Should)', '') : affinity_type.to_s
+  end
+
+  def format_host_vm_group_type(type)
+    found = HOST_VM_GROUP_TYPES.find {|it| it['value'] == type.to_s }
+    found ? found['name'] : type.to_s
+  end
+
+  # Groups carry poolId; keep only those in the chosen cluster.
+  def filter_by_pool(rows, pool_id)
+    return rows if pool_id.nil?
+    rows.select {|r| r['poolId'].nil? || r['poolId'].to_s == pool_id.to_s }
+  end
+
+  # Surface the server's own error text for affinity failures.
+  #
+  # The API returns {success:false, msg:"<human text>", errors:{<field>:"<i18n key>"}}
+  # -- there is no top-level errorCode. AffinityGroupService and
+  # VmwareComputeService.combinedRuleGroupSyncGuard already compose actionable
+  # messages (cross-cluster group refs, groups not yet synced to vSphere, rule
+  # shape violations), so print them verbatim rather than restating them here.
+  def handle_affinity_rest_exception(e, options)
+    if e.respond_to?(:response) && e.response
+      begin
+        body = JSON.parse(e.response.to_s)
+        if body.is_a?(Hash) && (body['msg'] || body['errors'])
+          print_red_alert body['msg'] if body['msg']
+          errors = body['errors']
+          if errors.is_a?(Hash) && !errors.empty?
+            # Same stream as print_red_alert, so msg and field detail stay together.
+            errors.each do |field, message|
+              $stderr.print "#{red}  #{field}: #{message}#{reset}\n"
+            end
+          end
+          return
+        end
+      rescue TypeError, JSON::ParserError
+        # fall through to the generic handler
+      end
+    end
+    print_rest_exception(e, options)
+  end
+
+end

data/lib/morpheus/cli/mixins/infrastructure_helper.rb

@@ -21,6 +21,11 @@ module Morpheus::Cli::InfrastructureHelper
     @clouds_interface
   end
 
+  def clusters_interface
+    raise "#{self.class} has not defined @clusters_interface" if @clusters_interface.nil?
+    @clusters_interface
+  end
+
   def networks_interface
     # @api_client.networks
     raise "#{self.class} has not defined @networks_interface" if @networks_interface.nil?
@@ -414,6 +419,138 @@ module Morpheus::Cli::InfrastructureHelper
     end
   end
 
+  # Resolve a cloud-owned vSphere cluster: a ComputeZonePool with type='Cluster'
+  # that belongs to the given cloud. This is distinct from a Morpheus managed
+  # cluster (ComputeServerGroup, resolved via ClustersInterface / /api/clusters).
+  #
+  # MORPH-17279: --cloud CLOUD --cluster CLUSTER must resolve CLUSTER within
+  # CLOUD's own resource pools, not the top-level managed-cluster namespace.
+  # `cloud` is the already-resolved cloud Hash (from find_cloud_by_name_or_id).
+  def find_resource_pool_cluster_by_name_or_id(cloud, val)
+    if val.to_s =~ /\A\d{1,}\Z/
+      return find_resource_pool_cluster_by_id(cloud, val)
+    else
+      return find_resource_pool_cluster_by_name(cloud, val)
+    end
+  end
+
+  def find_resource_pool_cluster_by_id(cloud, id)
+    begin
+      # Scoped to the cloud so the server itself verifies pool ownership --
+      # ZoneResourcePoolsController#show 404s when the pool's zone does not
+      # match the requested cloud.
+      json_response = resource_pools_interface.get(cloud['id'], id.to_i)
+    rescue RestClient::Exception => e
+      if e.response && e.response.code == 404
+        print_red_alert "Cluster not found by id #{id} in cloud '#{cloud['name']}'"
+        return nil
+      else
+        raise e
+      end
+    end
+    resource_pool = json_response['resourcePool']
+    if resource_pool.nil?
+      print_red_alert "Cluster not found by id #{id} in cloud '#{cloud['name']}'"
+      return nil
+    end
+    if resource_pool['type'].to_s != 'Cluster'
+      print_red_alert "Resource pool #{id} in cloud '#{cloud['name']}' is a '#{resource_pool['type'] || 'unknown'}' resource pool, not a Cluster"
+      return nil
+    end
+    return resource_pool
+  end
+
+  def find_resource_pool_cluster_by_name(cloud, name)
+    json_response = resource_pools_interface.list(cloud['id'], {name: name.to_s, type: 'Cluster'})
+    # The cloud-scoped resource-pools endpoint returns a pool *tree*, backfilling
+    # ancestor folder pools so the hierarchy renders correctly. Ancestors do not
+    # satisfy our name/type filter, so re-filter here rather than trusting the
+    # raw result size for ambiguity detection.
+    resource_pools = (json_response['resourcePools'] || []).select do |it|
+      it['type'].to_s == 'Cluster' && (it['name'].to_s == name.to_s || it['displayName'].to_s == name.to_s)
+    end
+    if resource_pools.empty?
+      print_red_alert "Cluster not found by name '#{name}' in cloud '#{cloud['name']}'.\n" \
+        "To look up a Morpheus managed cluster instead, use --cluster '#{name}' without --cloud."
+      return nil
+    elsif resource_pools.size > 1
+      print_red_alert "#{resource_pools.size} clusters found by name '#{name}' in cloud '#{cloud['name']}'. Use a numeric cluster id instead."
+      rows = resource_pools.collect do |it|
+        {id: it['id'], name: it['name']}
+      end
+      puts as_pretty_table(rows, [:id, :name], {color:red})
+      return nil
+    else
+      return resource_pools[0]
+    end
+  end
+
+  def find_managed_cluster_by_name_or_id(val, report_not_found=true)
+    cluster = nil
+    if val.to_s =~ /\A\d{1,}\Z/
+      begin
+        cluster = clusters_interface.get(val.to_i)['cluster']
+      rescue RestClient::Exception => e
+        raise e unless e.response && e.response.code == 404
+      end
+    else
+      clusters = clusters_interface.list({name: val})['clusters'] || []
+      if clusters.size > 1
+        print_red_alert "#{clusters.size} managed clusters found by name '#{val}'. Use a numeric cluster id instead."
+        rows = clusters.collect {|it| {id: it['id'], name: it['name']} }
+        puts as_pretty_table(rows, [:id, :name], {color:red})
+        return nil
+      end
+      cluster = clusters[0]
+    end
+    if cluster.nil? && report_not_found
+      print_red_alert "Managed cluster not found by name or id '#{val}'.\n" \
+        "If '#{val}' is a vSphere cluster owned by a cloud, use --cloud CLOUD --cluster #{val} instead."
+    end
+    cluster
+  end
+
+  def find_cluster_list_scope_by_name_or_id(val)
+    if val.to_s =~ /\A\d{1,}\Z/
+      cluster = find_managed_cluster_by_name_or_id(val)
+      return cluster ? {type: :managed_cluster, cluster: cluster} : nil
+    end
+
+    managed_clusters = clusters_interface.list({name: val})['clusters'] || []
+    if managed_clusters.size > 1
+      print_red_alert "#{managed_clusters.size} managed clusters found by name '#{val}'. Use a numeric cluster id instead."
+      rows = managed_clusters.collect {|it| {id: it['id'], name: it['name']} }
+      puts as_pretty_table(rows, [:id, :name], {color:red})
+      return nil
+    elsif managed_clusters.size == 1
+      return {type: :managed_cluster, cluster: managed_clusters[0]}
+    end
+
+    json_response = resource_pools_interface.list_without_cloud({name: val.to_s, type: 'Cluster', max: 1000})
+    resource_pools = (json_response['resourcePools'] || []).select do |it|
+      it['type'].to_s == 'Cluster' && (it['name'].to_s == val.to_s || it['displayName'].to_s == val.to_s)
+    end
+    if resource_pools.empty?
+      print_red_alert "No managed or vSphere cluster found by name '#{val}'."
+      return nil
+    elsif resource_pools.size > 1
+      print_red_alert "#{resource_pools.size} vSphere clusters found by name '#{val}'. Use --cloud CLOUD --cluster #{val} to disambiguate."
+      rows = resource_pools.collect do |it|
+        {id: it['id'], name: it['name'], cloud: it['zone'] && it['zone']['name']}
+      end
+      puts as_pretty_table(rows, [:id, :name, :cloud], {color:red})
+      return nil
+    end
+
+    resource_pool = resource_pools[0]
+    cloud = resource_pool['zone']
+    if cloud.nil? || cloud['id'].nil?
+      print_red_alert "vSphere cluster '#{val}' does not include its owning cloud."
+      return nil
+    end
+    {type: :cloud_pool, cloud: cloud, pool: resource_pool}
+  end
+
   def find_resource_pool_group_by_name_or_id(val)
     if val.to_s =~ /\A\d{1,}\Z/
       return find_resource_pool_group_by_id(val)