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_uuidcluster_namedatacenter_nameesx_host_nameesx_host_uuidvcenter_namevcenter_host_urlvcenter_uuidnamehost_nameip_addressdevice_guidregistration_ideligibilityeligibility_codeinstallation_statusinstallation_typeuuidos_descriptionos_typeos_architecturevmwaretools_version
For AWSComputeResource:
auto_scaling_group_nameavailability_zonecloud_provider_account_idcloud_provider_resource_idcloud_provider_tagsidinstallation_statusnameplatformplatform_detailsregionsubnet_idvirtual_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:
eligibilityinstallation_statusvmwaretools_versionos_type
For AWSComputeResource:
auto_scaling_group_namecloud_provider_tagsplatformplatform_detailsvirtual_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_zoneregionsubnet_idvirtual_private_cloud_idsecurity_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}
Interactive example script featuring Workloads Search
We have a number of example scripts you can use with the CBC SDK.
This interactive script highlights the capabilities of the CBC SDK. It uses user input to guide you through the functionalities of the Workloads Search.
You can download it from: here