VM Workloads Search API

Overview

This API lets Carbon Black Cloud Workload users visualize the inventory of vSphere workloads that do not have Carbon Black Cloud sensors installed.

Use Cases

  • Life cycle management from cloud
  • Provides search and facet results in a single call to reduce inconsistency

Requirements

  • Appliance and vSphere configured to communicate with the Carbon Black Cloud see Installation Guide for more information
  • Carbon Black Cloud Workload - You must have purchased one of the Carbon Black Cloud Workload packages
  • All API calls require an API key with appropriate permissions see Authentication

Authentication

  • Access Level: Before you create your API Key, you need to create a “Custom” Access Level:

    • for the category Workload Management > View Workloads without sensors > “workloads.vcenter.vm”, allow permission to READ (or see each call below for individual requirements)

  • API Key: When you create your API Key, use the Access Level Type of “Custom”, then select the Access Level you created.

  • Environment: use the URL of your Carbon Black Cloud console (this is the Dashboard URL)

  • API Route: {cbc-hostname}/lcm/view/v1/orgs/{org_key}/compute_resources/{id}

API calls

Note: when you insert your org_key, you must also remove the { } brackets.

Fetch Compute Resource by ID

Get the compute resource by ID from your organization

RBAC Permissions Required

Identity Manager Permission (.notation name) Operation(s) Environment
Carbon Black Cloud workloads.vcenter.vm READ Majority of environments
VMware Cloud Services Platform _API.Workload.Management:workloads.Vcenter.Vm.read N/A - included in permission name Prod UK

Request

GET {cbc-hostname}/lcm/view/v1/orgs/{org_key}/compute_resources/{id}

Response

Code Description Content-Type Content
200 Successfully return compute resource application/json View example response below
403 Forbidden N/A N/A
404 Compute resource does not exist for id application/json N/A
500 Internal Server Error N/A N/A

Example

Request

GET https://defense-eap01.conferdeploy.net/lcm/view/v1/orgs/ABCD1234/compute_resources/14101309

Response 

{
    "id": "14101309",
    "appliance_uuid": "e66fdd46-2268-4f34-8a3f-226fa6d3edd0",
    "cluster_name": "cwp-bucket-1-cluster",
    "datacenter_name": "cwp-bucket-1-datacenter",
    "esx_host_name": "10.234.56.789",
    "esx_host_uuid": "a2311b42-3e53-8f21-97d7-66680007185f",
    "vcenter_name": "VMware vCenter Server 6.7.0 build-14368073",
    "vcenter_host_url": "10.234.56.789",
    "vcenter_uuid": "9a8a0be5-ae1e-49ce-b2aa-34bc7dc445e3",
    "name": "cwp-bucket-1-appliance",
    "host_name": "photon-machine",
    "created_at": "2020-10-29T16:37:17.610Z",
    "ip_address": "10.234.56.789",
    "eligibility": "UNSUPPORTED",
    "eligibility_code": [
        "Unsupported OS"
    ],
    "installation_status": "NOT_INSTALLED",
    "installation_status_code": null,
    "uuid": "500edcd7-e8ff-868a-6513-4e2fabcfcccd",
    "os_description": "VMware Photon OS (64-bit)",
    "os_type": "OTHER",
    "os_architecture": "32",
    "vmwaretools_version": "11296"
}

Search and Facet Compute Resources

Search and facet compute resources in your organization

RBAC Permissions Required

Identity Manager Permission (.notation name) Operation(s) Environment
Carbon Black Cloud workloads.vcenter.vm READ Majority of environments
VMware Cloud Services Platform _API.Workload.Management:workloads.Vcenter.Vm.read N/A - included in permission name Prod UK

Request

POST {cbc-hostname}/lcm/view/v1/orgs/{org_key}/compute_resources/_search

Request Body 

{
  "start": "<long>",
  "rows": "<long>",
  "sort": [
    {
      "field": "<string>",
      "order": "<string>"
    }
  ],
  "query": "<string>",
  "criteria": {
    "appliance_uuid": [ "<string>" ],
    "cluster_name": [ "<string>" ],
    "datacenter_name": [ "<string>" ],
    "esx_host_name": [ "<string>" ],
    "esx_host_uuid": [ "<string>" ],
    "vcenter_name": [ "<string>" ],
    "vcenter_host_url": [ "<string>" ],
    "vcenter_uuid": [ "<string>" ],
    "name": [ "<string>" ],
    "host_name": [ "<string>" ],
    "ip_address": [ "<string>" ],
    "device_guid": [ "<string>" ],
    "registration_id": [ "<string>" ],
    "eligibility": [ "<string>" ],
    "eligibility_code": [ "<string>" ],
    "installation_status": [ "<string>" ],
    "installation_type": [ "<string>" ],
    "uuid": [ "<string>" ],
    "os_description": [ "<string>" ],
    "os_type": [ "<string>" ],
    "os_architecture": [ "<string>" ],
    "vmwaretools_version": [ "<string>" ]
  },
  "terms": {
    "rows": "<long>",
    "fields": [
      "<string>"
    ]
  }
}

Field Definition Data Type Values
criteria Criteria is an object that represents values that must be in the results. Object 
{
  "installation_status": [
    "NOT_INSTALLED"
  ]
}
Supported fields:
appliance_uuid, cluster_name, datacenter_name, esx_host_name, esx_host_uuid, vcenter_name, vcenter_host_url, vcenter_uuid, name, host_name, ip_address, device_guid, registration_id, eligibility, eligibility_code, installation_status, installation_type, uuid, os_description, os_type, os_architecture, vmwaretools_version

See Compute Resource for values
query Query in lucene syntax and/or including value searches. String N/A
rows Number of rows to request, can be paginated. Long Default: 20
Max: 200
Cannot be larger than 200, if a value larger than 200 is provided, 200 will be used.
start First row to use for pagination Long Default: 0
sort Sort is a collection of sort parameters that specify a field and order to sort the results. Array 
[{
  "field": "device_timestamp",
  "order": "asc"
}]
order supports asc or desc

Supported fields: created_at, name, host_name, eligibility, installation_status, os_description, vmwaretools_version
terms The compute resource fields to facet and how many of the top entries to return. Object 
{
  "fields": [
    "eligibility"
  ],
  "rows": 20
}
Default: 20

Supported Fields: eligibility, installation_status, vmwaretools_version, os_type

Response

Code Description Content-Type Content
200 Successful Search/Facet Request application/json View example response below
400 The JSON body was malformed, or some part of the JSON body included an invalid value N/A N/A
403 Forbidden N/A N/A
500 Internal Server Error N/A N/A

Example

Request

POST https://defense-eap01.conferdeploy.net/lcm/view/v1/orgs/ABCD1234/compute_resources/_search

Request_Body 

{
   "criteria":{
      "installation_status":[
         "NOT_INSTALLED",
         "PENDING",
         "ERROR"
      ]
   },
   "sort":[
      {
         "field":"created_at",
         "order":"DESC"
      },
      {
         "field":"eligibility",
         "order":"ASC"
      }
   ],
   "start":0,
   "rows":50,
   "query":"",
   "terms":{
      "rows":10,
      "fields":[
         "eligibility",
         "installation_status",
         "os_type"
      ]
   }
}

Response 

{
    "num_found": 3,
    "results": [
        {
            "id": "14101309",
            "appliance_uuid": "e66fdd46-2268-4f34-8a3f-226fa6d3edd0",
            "cluster_name": "cwp-bucket-1-cluster",
            "datacenter_name": "cwp-bucket-1-datacenter",
            "esx_host_name": "10.234.56.789",
            "esx_host_uuid": "a2311b42-3e53-8f21-97d7-66680007185f",
            "vcenter_name": "VMware vCenter Server 6.7.0 build-14368073",
            "vcenter_host_url": "10.234.56.789",
            "vcenter_uuid": "9a8a0be5-ae1e-49ce-b2aa-34bc7dc445e3",
            "name": "cwp-bucket-1-appliance",
            "host_name": "photon-machine",
            "created_at": "2020-10-29T16:37:17.610Z",
            "ip_address": "10.234.56.789",
            "eligibility": "UNSUPPORTED",
            "eligibility_code": [
                "Unsupported OS"
            ],
            "installation_status": "NOT_INSTALLED",
            "installation_status_code": null,
            "uuid": "500edcd7-e8ff-868a-6513-4e2fabcfcccd",
            "os_description": "VMware Photon OS (64-bit)",
            "os_type": "OTHER",
            "os_architecture": "32",
            "vmwaretools_version": "11296"
        },
        {
            "id": "13764913",
            "appliance_uuid": "46fa4b1c-474b-4b2e-b3d3-56871f410455",
            "cluster_name": "cwp-bucket-2-cluster",
            "datacenter_name": "cwp-bucket-2-datacenter",
            "esx_host_name": "10.173.95.98",
            "esx_host_uuid": "50f21342-52b7-0946-3422-cbbf72eb2a52",
            "vcenter_name": "VMware vCenter Server 6.7.0 build-14368073",
            "vcenter_host_url": "10.173.88.158",
            "vcenter_uuid": "59c3c754-66bf-406b-be3a-aefb5d6e4662",
            "name": "cwp-bucket-2-windows_2008",
            "host_name": "appd2k8r2",
            "created_at": "2020-10-23T09:43:50.357Z",
            "ip_address": "10.173.88.13",
            "eligibility": "ELIGIBLE",
            "eligibility_code": null,
            "installation_status": "NOT_INSTALLED",
            "installation_status_code": null,
            "uuid": "5012aa35-16e8-7f75-6d10-73fa86e58300",
            "os_description": "Microsoft Windows Server 2008 R2 (64-bit)",
            "os_type": "WINDOWS",
            "os_architecture": "64",
            "vmwaretools_version": "11328"
        },
        {
            "id": "13764912",
            "appliance_uuid": "46fa4b1c-474b-4b2e-b3d3-56871f410455",
            "cluster_name": "cwp-bucket-2-cluster",
            "datacenter_name": "cwp-bucket-2-datacenter",
            "esx_host_name": "10.173.95.98",
            "esx_host_uuid": "50f21342-52b7-0946-3422-cbbf72eb2a52",
            "vcenter_name": "VMware vCenter Server 6.7.0 build-14368073",
            "vcenter_host_url": "10.173.88.158",
            "vcenter_uuid": "59c3c754-66bf-406b-be3a-aefb5d6e4662",
            "name": "cwp-bucket-2-centos_72",
            "host_name": "prome-1s-dhcp38.eng.vmware.com",
            "created_at": "2020-10-23T09:43:50.357Z",
            "ip_address": "10.173.88.57",
            "eligibility": "ELIGIBLE",
            "eligibility_code": null,
            "installation_status": "NOT_INSTALLED",
            "installation_status_code": null,
            "uuid": "501251d6-6470-aab6-a5ff-97e822f1e9c3",
            "os_description": "CentOS 7 (64-bit)",
            "os_type": "CENTOS",
            "os_architecture": "64",
            "vmwaretools_version": "10309"
        }
    ],
    "terms": [
        {
            "field": "os_type",
            "values": [
                {
                    "total": 1,
                    "id": "WINDOWS",
                    "name": "WINDOWS"
                },
                {
                    "total": 1,
                    "id": "CENTOS",
                    "name": "CENTOS"
                },
                {
                    "total": 1,
                    "id": "OTHER",
                    "name": "OTHER"
                }
            ]
        },
        {
            "field": "eligibility",
            "values": [
                {
                    "total": 2,
                    "id": "ELIGIBLE",
                    "name": "ELIGIBLE"
                },
                {
                    "total": 1,
                    "id": "UNSUPPORTED",
                    "name": "UNSUPPORTED"
                }
            ]
        },
        {
            "field": "installation_status",
            "values": [
                {
                    "total": 3,
                    "id": "NOT_INSTALLED",
                    "name": "NOT_INSTALLED"
                }
            ]
        }
    ]
}

Fields

Compute Resource

Field Definition Data Type Values
id Numerical identifier for the compute resource String N/A
appliance_uuid The UUID of the appliance the VM is associated with. String N/A
cluster_name Name of the cluster. A cluster is a group of hosts. String N/A
datacenter_name Name of the underlying datacenter. The datacenter managed object provides the interface to the common container object for hosts, virtual machines, networks, and datastores. String N/A
esx_host_name Name of the ESX host on which the VM is deployed String N/A
esx_host_uuid UUID of the ESX host on which VM is deployed String N/A
vcenter_name Name of the vcenter the vm is associated with String N/A
vcenter_host_url The hostname or ip address of the vcenter the vm is associated with String N/A
vcenter_uuid 128-bit SMBIOS UUID of a vcenter represented as a hexadecimal string String N/A
name The name of the compute resource String N/A
host_name The DNS name of associated with the compute resource String N/A
created_at The timestamp the compute resource was created ISO 8601 UTC timestamp N/A
ip_address The current ip address assigned to the compute resource String N/A
eligibility The status indicator indicating whether a compute resource is capable of installing a Carbon Black Cloud sensor String ELIGIBLE, NOT_ELIGIBLE, UNSUPPORTED
eligibility_code Reason messages for why a compute resource is not eligible Array 
["<string>"]

VMware Tools install required,
VMware Tools update required,
Launcher not found,
VM is offline,
Unsupported OS
installation_status The current state of installing the Carbon Black Cloud sensor on the compute resource String SUCCESS, ERROR, PENDING, NOT_INSTALLED
installation_status_code The reason an the installation process is in an ERROR state String Unsuccessful install, OLD_VMTOOLS
uuid Universally unique identifier for a compute resource String N/A
os_description The operating system, version, and architecture String N/A
os_type The type of operating system String WINDOWS, RHEL, UBUNTU, SUSE, SLES, CENTOS, OTHER, AMAZON_LINUX, ORACLE
os_architecture The compute resource’s operating system architecture String 32, 64
vmwaretools_version The current version of VMware tools installed in the compute resource String N/A

Troubleshooting & FAQ

Why did the compute resource disappear?

  • Check the Devices v6 API if you installed a sensor on the workload.

Why is the workload not eligible for a Carbon Black Cloud sensor installation?

  • The eligibility codes will describe the reasons behind the ineligibility such as VM is offline or VMware Tools install required
Last modified on June 21, 2022