Workloads

These APIs allow you to visualize the inventory of compute resources available under either vSphere or AWS.

Note

A compute resource is a virtual machine without a sensor installed.

The API operations center around the VCenterComputeResource object for vSphere compute resources, or around the AWSComputeResource for AWS compute resources.

Note

The object name ComputeResource is an alias for VCenterComputeResource, provided for backwards compatibility with earlier versions of the SDK.

Search Compute Resources

By querying on one of the compute resource object types, you can obtain a list of matching compute resources. The SDK supports filtering by a number of different criteria, which are different for each compute resource type.

For VCenterComputeResource:

  • 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

For AWSComputeResource:

  • auto_scaling_group_name

  • availability_zone

  • cloud_provider_account_id

  • cloud_provider_resource_id

  • cloud_provider_tags

  • id

  • installation_status

  • name

  • platform

  • platform_details

  • region

  • subnet_id

  • virtual_private_cloud_id

Any of these criteria may be specified to be included in search results by calling the method set_XXX, or excluded by calling the method exclude_XXX, where XXX is the specific criteria name.

Example (vSphere workloads):

>>> from cbc_sdk import CBCloudAPI
>>> from cbc_sdk.workload import VCenterComputeResource

>>> cbc = CBCloudAPI()
>>> query = cbc.select(VCenterComputeResource).set_os_type(['WINDOWS']).set_cluster_name(['example-cluster-name'])
>>> for result in list(query):
...     print(result)

Example Output:

VCenterComputeResource object, bound to https://defense-dev01.cbdtest.io.
-------------------------------------------------------------------------------

        appliance_uuid: c74bca54-e903-49e8-9962-2bb895f428c1
          cluster_name: example-cluster-name
            created_at: 2021-02-25T04:54:41.362Z
       datacenter_name: cwp-bucket-1-datacenter
           eligibility: ELIGIBLE
      eligibility_code: None
         esx_host_name: 10.105.17.113
         esx_host_uuid: a2311b42-3e53-8f21-97d7-66680007185f
             host_name: appd2012
                    id: 19902164
   installation_status: NOT_INSTALLED
  installation_status_code:
            ip_address: 10.105.17.84
                  name: cwp-bucket-1-windows_2012
       os_architecture: 64
        os_description: Microsoft Windows Server 2012 (64-bit)
               os_type: WINDOWS
                  uuid: 500e14e6-3ea6-23aa-11bd-8e68444c6ce4
      vcenter_host_url: 10.105.17.114
          vcenter_name: VMware vCenter Server 6.7.0 build-14368073
          vcenter_uuid: 9a8a0be5-ae1e-49ce-b2aa-34bc7dc445e3
   vmwaretools_version: 11328
VCenterComputeResource object, bound to https://defense-dev01.cbdtest.io.
-------------------------------------------------------------------------------

        appliance_uuid: c74bca54-e903-49e8-9962-2bb895f428c1
          cluster_name: example-cluster-name
            created_at: 2021-02-25T04:54:41.362Z
       datacenter_name: cwp-bucket-1-datacenter
           eligibility: ELIGIBLE
      eligibility_code: None
         esx_host_name: 10.105.17.113
         esx_host_uuid: a2311b42-3e53-8f21-97d7-66680007185f
             host_name: appd2k8r2
                    id: 19902168
   installation_status: NOT_INSTALLED
  installation_status_code:
            ip_address: 10.105.17.237
                  name: cwp-bucket-1-windows_2008
       os_architecture: 64
        os_description: Microsoft Windows Server 2008 R2 (64-bit)
               os_type: WINDOWS
                  uuid: 500e51ff-ca0d-5a70-a799-2595c9e87000
      vcenter_host_url: 10.105.17.114
          vcenter_name: VMware vCenter Server 6.7.0 build-14368073
          vcenter_uuid: 9a8a0be5-ae1e-49ce-b2aa-34bc7dc445e3
   vmwaretools_version: 11328 ComputeResource object, bound to https://defense-dev01.cbdtest.io.

Example (AWS workloads):

>>> from cbc_sdk import CBCloudAPI
>>> from cbc_sdk.workload import AWSComputeResource

>>> cbc = CBCloudAPI()
>>> query = cbc.select(AWSComputeResource).set_region(['us-west-1'])
>>> results = list(query)
>>> for result in results:
...     print(result)

Example Output:

AWSComputeResource object, bound to https://defense-dev01.cbdtest.io.
-------------------------------------------------------------------------------

         auto_scaling_group_name: Demo-AutoScalingGroup
               availability_zone: us-west-1c
       cloud_provider_account_id: 267678331262
      cloud_provider_resource_id: i-043de738ce129b77a
             cloud_provider_tags: [list:4 items]:
                                  [0]: Name##Demo-ASG
                                  [1]: aws:ec2launchtemplate:id##lt-0e3d35dba4f5ba16f
                                  [2]: aws:autoscaling:groupName##Demo-AutoScalingGroup
                                  [...]
                     create_time: 2022-06-02T05:23:27Z
                 deployment_type: AWS
                     eligibility: NOT_ELIGIBLE
                eligibility_code: [list:1 item]:
                                  [0]: SSM_DOC_NOT_INSTALLED
                     external_ip: 18.144.80.202
                              id: 8x5tjvywq-aws-i-043de738ce129b77a
               image_description: Amazon Linux 2 Kernel 5.10 AMI 2.0.20220426.0 x...
                        image_id: ami-02541b8af977f6cdd
                      image_name: amzn2-ami-kernel-5.10-hvm-2.0.20220426.0-x86_64...
             installation_status: NOT_INSTALLED
        installation_status_code: None
    installation_status_code_key: None
                  instance_state: running
                   instance_type: t2.micro
                     internal_ip: 172.31.11.73
                            name: Demo-ASG
                         org_key: 8X5TJVYWQ
                        platform: Unix/Linux
                platform_details: Linux/UNIX
                   platform_name: None
                platform_version: None
                          region: us-west-1
               security_group_id: [list:1 item]:
                                  [0]: sg-085972ee2f0be60aa
                       subnet_id: subnet-03cb2d09e07350698
        virtual_private_cloud_id: vpc-0faa4803c3de51c87
AWSComputeResource object, bound to https://defense-dev01.cbdtest.io.
-------------------------------------------------------------------------------

         auto_scaling_group_name: None
               availability_zone: us-west-1c
       cloud_provider_account_id: 267678331262
      cloud_provider_resource_id: i-0febda35fcaf2dbd1
             cloud_provider_tags: [list:1 item]:
                                  [0]: Name##Rushit-Test-2
                     create_time: 2022-07-11T08:26:58Z
                 deployment_type: AWS
                     eligibility: NOT_ELIGIBLE
                eligibility_code: [list:1 item]:
                                  [0]: SSM_DOC_NOT_INSTALLED
                     external_ip: 54.193.100.2
                              id: 8x5tjvywq-aws-i-0febda35fcaf2dbd1
               image_description: Amazon Linux 2 Kernel 5.10 AMI 2.0.20220606.1 x...
                        image_id: ami-0d9858aa3c6322f73
                      image_name: amzn2-ami-kernel-5.10-hvm-2.0.20220606.1-x86_64...
             installation_status: NOT_INSTALLED
        installation_status_code: None
    installation_status_code_key: None
                  instance_state: running
                   instance_type: t2.micro
                     internal_ip: 172.31.7.55
                            name: Rushit-Test-2
                         org_key: 8X5TJVYWQ
                        platform: Unix/Linux
                platform_details: Linux/UNIX
                   platform_name: None
                platform_version: None
                          region: us-west-1
               security_group_id: [list:1 item]:
                                  [0]: sg-08473e77b9e4921e3
                       subnet_id: subnet-03cb2d09e07350698
        virtual_private_cloud_id: vpc-0faa4803c3de51c87
AWSComputeResource object, bound to https://defense-dev01.cbdtest.io.
-------------------------------------------------------------------------------

         auto_scaling_group_name: Demo-AutoScalingGroup
               availability_zone: us-west-1a
       cloud_provider_account_id: 267678331262
      cloud_provider_resource_id: i-0b8b62d7c3aea1f9f
             cloud_provider_tags: [list:5 items]:
                                  [0]: Name##Demo-ASG
                                  [1]: Test##Rushit-ASG
                                  [2]: aws:ec2launchtemplate:id##lt-0e3d35dba4f5ba16f
                                  [...]
                     create_time: 2022-06-02T05:21:26Z
                 deployment_type: AWS
                     eligibility: NOT_ELIGIBLE
                eligibility_code: [list:1 item]:
                                  [0]: SSM_DOC_NOT_INSTALLED
                     external_ip: 54.176.174.194
                              id: 8x5tjvywq-aws-i-0b8b62d7c3aea1f9f
               image_description: Amazon Linux 2 Kernel 5.10 AMI 2.0.20220426.0 x...
                        image_id: ami-02541b8af977f6cdd
                      image_name: amzn2-ami-kernel-5.10-hvm-2.0.20220426.0-x86_64...
             installation_status: NOT_INSTALLED
        installation_status_code: None
    installation_status_code_key: None
                  instance_state: running
                   instance_type: t2.micro
                     internal_ip: 172.31.17.166
                            name: Demo-ASG
                         org_key: 8X5TJVYWQ
                        platform: Unix/Linux
                platform_details: Linux/UNIX
                   platform_name: None
                platform_version: None
                          region: us-west-1
               security_group_id: [list:1 item]:
                                  [0]: sg-085972ee2f0be60aa
                       subnet_id: subnet-02ccab8946d24f386
        virtual_private_cloud_id: vpc-0faa4803c3de51c87

Fetch Compute Resource by ID

Using a query of the VCenterComputeResource or AWSComputeResource objects, you can get the compute resource by ID from your organization.

Example (vCenter workloads):

>>> from cbc_sdk import CBCloudAPI
>>> from cbc_sdk.workload import VCenterComputeResource

>>> # This is an example id that we want to query
>>> id = 15054425

>>> cbc = CBCloudAPI()
>>> query = cbc.select(VCenterComputeResource, id)

>>> # A string object is returned here, so we can print the result directly.
>>> print(query)

VCenterComputeResource object, bound to https://defense-dev01.cbdtest.io.
 Last refreshed at Mon Mar  1 12:02:14 2021
-------------------------------------------------------------------------------

          appliance_uuid: c89f183b-f201-4bca-bacc-80184b5b8823
            cluster_name: example-cluster-name
              created_at: 2020-11-18T07:41:16.834Z
         datacenter_name: None
             eligibility: NOT_ELIGIBLE
        eligibility_code: ['Launcher not found']
           esx_host_name: 10.105.7.129
           esx_host_uuid: bb8d2842-0438-9a74-7964-1d0efad10f28
               host_name: localhost.localdomain
                      id: 15054425
     installation_status: NOT_INSTALLED
    installation_status_code: None
              ip_address: 10.105.7.201
                    name: CB-ServiceTest
         os_architecture: 64
          os_description: CentOS 7 (64-bit)
                 os_type: CENTOS
                    uuid: 5022227f-947a-84f8-5816-747f5e18e5ac
        vcenter_host_url: 10.105.5.63
            vcenter_name: VMware vCenter Server 7.0.0 build-15952599
            vcenter_uuid: 4a6b1382-f917-4e1a-8564-374cb7274bd7
     vmwaretools_version: 10336

Example (AWS workloads):

>>> from cbc_sdk import CBCloudAPI
>>> from cbc_sdk.workload import AWSComputeResource

>>> # This is an example id that we want to query
>>> id = '8x5tjvywq-aws-i-043de738ce129b77a'

>>> cbc = CBCloudAPI()
>>> query = cbc.select(AWSComputeResource, id)

>>> # A string object is returned here, so we can print the result directly.
>>> print(query)
AWSComputeResource object, bound to https://defense-dev01.cbdtest.io.
 Last refreshed at Wed Oct 12 11:11:41 2022
-------------------------------------------------------------------------------

         auto_scaling_group_name: Demo-AutoScalingGroup
               availability_zone: us-west-1c
       cloud_provider_account_id: 267678331262
      cloud_provider_resource_id: i-043de738ce129b77a
             cloud_provider_tags: [list:4 items]:
                                  [0]: Name##Demo-ASG
                                  [1]: aws:ec2launchtemplate:id##lt-0e3d35dba4f5ba16f
                                  [2]: aws:autoscaling:groupName##Demo-AutoScalingGroup
                                  [...]
                     create_time: 2022-06-02T05:23:27Z
                 deployment_type: AWS
                     eligibility: NOT_ELIGIBLE
                eligibility_code: [list:1 item]:
                                  [0]: SSM_DOC_NOT_INSTALLED
                     external_ip: 18.144.80.202
                              id: 8x5tjvywq-aws-i-043de738ce129b77a
               image_description: Amazon Linux 2 Kernel 5.10 AMI 2.0.20220426.0 x...
                        image_id: ami-02541b8af977f6cdd
                      image_name: amzn2-ami-kernel-5.10-hvm-2.0.20220426.0-x86_64...
             installation_status: NOT_INSTALLED
        installation_status_code: None
    installation_status_code_key: None
                  instance_state: running
                   instance_type: t2.micro
                     internal_ip: 172.31.11.73
                            name: Demo-ASG
                         org_key: 8X5TJVYWQ
                        platform: Unix/Linux
                platform_details: Linux/UNIX
                   platform_name: None
                platform_version: None
                          region: us-west-1
               security_group_id: [list:1 item]:
                                  [0]: sg-085972ee2f0be60aa
                       subnet_id: subnet-03cb2d09e07350698
        virtual_private_cloud_id: vpc-0faa4803c3de51c87

Facet Compute Resources

Any compute resource search may be turned into a faceting by calling the facet() method on the query object returned by select(), after setting search criteria. A faceting breaks down each specified field for all compute resources matching the criteria, showing which values that field can take and how many times that field value shows up in the matching compute resources. Only a subset of fields can be faceted on, as listed here:

For VCenterComputeResource:

  • eligibility

  • installation_status

  • vmwaretools_version

  • os_type

For AWSComputeResource:

  • auto_scaling_group_name

  • cloud_provider_tags

  • platform

  • platform_details

  • virtual_private_cloud_id

Example (vCenter workloads):

>>> from cbc_sdk import CBCloudAPI
>>> from cbc_sdk.workload import VCenterComputeResource
>>> cbc = CBCloudAPI()
>>> query = cbc.select(VCenterComputeResource)
>>> facets = query.facet(['os_type', 'eligibility'])
>>> for facet in facets:
...    print facet
...
ComputeResourceFacet object, bound to https://defense-dev01.cbdtest.io.
-------------------------------------------------------------------------------

     field: os_type
        id: os_type
    values: [list:6 items]:
            [0]: [ComputeResourceFacetValue object]:
                    id: OTHER
                  name: OTHER
                 total: 230

            [1]: [ComputeResourceFacetValue object]:
                    id: UBUNTU
                  name: UBUNTU
                 total: 68

            [2]: [ComputeResourceFacetValue object]:
                    id: WINDOWS
                  name: WINDOWS
                 total: 46

            [...]
ComputeResourceFacet object, bound to https://defense-dev01.cbdtest.io.
-------------------------------------------------------------------------------

     field: eligibility
        id: eligibility
    values: [list:3 items]:
            [0]: [ComputeResourceFacetValue object]:
                    id: NOT_ELIGIBLE
                  name: NOT_ELIGIBLE
                 total: 237

            [1]: [ComputeResourceFacetValue object]:
                    id: UNSUPPORTED
                  name: UNSUPPORTED
                 total: 185

            [2]: [ComputeResourceFacetValue object]:
                    id: ELIGIBLE
                  name: ELIGIBLE
                 total: 25

Example (AWS workloads):

>>> from cbc_sdk import CBCloudAPI
>>> from cbc_sdk.workload import AWSComputeResource
>>> cbc = CBCloudAPI()
>>> query = cbc.select(AWSComputeResource)
>>> facets = query.facet(['platform', 'virtual_private_cloud_id'])
>>> for facet in facets:
...    print facet
...
ComputeResourceFacet object, bound to https://defense-dev01.cbdtest.io.
-------------------------------------------------------------------------------

     field: virtual_private_cloud_id
        id: virtual_private_cloud_id
    values: [list:8 items]:
            [0]: [ComputeResourceFacetValue object]:
                    id: vpc-02371233d7ac6d33c
                  name: vpc-02371233d7ac6d33c
                 total: 28

            [1]: [ComputeResourceFacetValue object]:
                    id: vpc-5102d53a
                  name: vpc-5102d53a
                 total: 12

            [2]: [ComputeResourceFacetValue object]:
                    id: vpc-0968a1d4ea101fc26
                  name: vpc-0968a1d4ea101fc26
                 total: 7

            [...]
ComputeResourceFacet object, bound to https://defense-dev01.cbdtest.io.
-------------------------------------------------------------------------------

     field: platform
        id: platform
    values: [list:2 items]:
            [0]: [ComputeResourceFacetValue object]:
                    id: Unix/Linux
                  name: Unix/Linux
                 total: 56

            [1]: [ComputeResourceFacetValue object]:
                    id: Windows
                  name: Windows
                 total: 5

Download Compute Resource Listings

The details of compute resources matching a search may be directly downloaded from the Carbon Black Cloud by callin the download() method on the query object returned by select(), after setting search criteria. The format for downloading may be specified as either JSON or CSV.

The download() method returns a Job object, which is processed asynchronously and from which the results are available once the job has been completed.

Example (vCenter workloads):

>>> from cbc_sdk import CBCloudAPI
>>> from cbc_sdk.workload import VCenterComputeResource
>>> cbc = CBCloudAPI()
>>> query = cbc.select(VCenterComputeResource).set_os_type(["UBUNTU"]).set_eligibility(["ELIGIBLE"])
>>> query.set_installation_status(["ERROR"])
>>> job = query.download("CSV")
>>> job.await_completion()
>>> print(job.get_output_as_string())
Eligibility,Install Status,Name,OS,VMware Tools,Added Time,VM ID,VM name,IP address,Datacenter,Cluster,vCenter [...]
"ELIGIBLE",""ERROR"","wdc-10-180-200-134","UBUNTU","10336",""2021-07-27T11:01:01.636","776bf589-923e-4ccd-869d-[...]
"ELIGIBLE",""ERROR"","","UBUNTU","0",""2021-11-19T08:49:20.882","50294288-5baa-6e71-18f0-71c8a17f0caf","POC-DB-[...]
"ELIGIBLE",""ERROR"","ubunti1804desktop","UBUNTU","10338",""2022-04-04T04:54:50.861","503410f6-80aa-1f69-0285-[...]
"ELIGIBLE",""ERROR"","ubunti1804desktop","UBUNTU","10338",""2022-02-28T09:22:32.235","503410f6-80aa-1f69-0285-[...]
>>> # note: lines truncated in above output for formatting purposes

Example (AWS workloads):

>>> from cbc_sdk import CBCloudAPI
>>> from cbc_sdk.workload import AWSComputeResource

>>> cbc = CBCloudAPI()
>>> query = cbc.select(AWSComputeResource).set_region(['us-west-1'])
>>> job = query.download("CSV")
>>> job.await_completion()
>>> print(job.get_output_as_string())
Instance ID,Platform,Account ID,VPC ID,Added Time,AWS Tags,ASG,Instance Type,Image ID,Image name,Image [...]
"i-043de738ce129b77a","Unix/Linux","267678331262","vpc-0faa4803c3de51c87","2022-06-02T05:23:27",[...]
"i-0febda35fcaf2dbd1","Unix/Linux","267678331262","vpc-0faa4803c3de51c87","2022-07-11T08:26:58",[...]
"i-0b8b62d7c3aea1f9f","Unix/Linux","267678331262","vpc-0faa4803c3de51c87","2022-06-02T05:21:26",[...]
>>> # note: lines truncated in above output for formatting purposes

Summarize Compute Resources

Note

This functionality is not available for vCenter compute resources.

By calling the summarize() method on the query object returned by select(), after setting search criteria, a summary of compute resources may be generated. The fields which may be summarized are as follows:

For AWSComputeResource:

  • availability_zone

  • region

  • subnet_id

  • virtual_private_cloud_id

  • security_group_id

Example (AWS workloads):

>>> from cbc_sdk import CBCloudAPI
>>> from cbc_sdk.workload import AWSComputeResource
>>> cbc = CBCloudAPI()
>>> query = cbc.select(AWSComputeResource)
>>> summary = query.summarize(['availability_zone', 'region', 'virtual_private_cloud_id'])
>>> print(summary)
{'region': 5, 'availability_zone': 12, 'virtual_private_cloud_id': 8}