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

Permission (.notation name) Operation(s)
workloads.vcenter.vm READ

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

Permission (.notation name) Operation(s)
workloads.vcenter.vm READ

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"
                }
            ]
        }
    ]
}

Schemas

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 7, 2021