Appliance Service API

Overview

This API lets Carbon Black Cloud Workload users query appliance registration details and health status.

This also allows user to fine tune appliance configurations like heartbeat interval.

Requirements

  • Appliance and vSphere configured to communicate with the Carbon Black Cloud see Installation Guide for more information
  • Carbon Black Cloud Workload - You must be a Carbon Black Cloud Workload customer
  • 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 Appliances Registration > “appliances.registration”, allow permission to CREATE, READ and UPDATE (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}/applianceservice/v1/orgs/{org_key}

API calls

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

Register Appliance

Register an appliance.

RBAC Permissions Required

Permission (.notation name) Operation(s)
appliances.registration CREATE

Request

POST {cbc-hostname}/applianceservice/v1/orgs/{org_key}/appliances

Request Body

{
  "api_key": "<string>",
  "api_id": "<string>",
  "name": "<string>",
  "version": "<string>",
  "plugin_version": "<string>",
  "ip_address": "<string>",
  "appliance_group_uuid": "<string>"
}

Body Schema

Field Definition Data Type Values
api_key API Secret Key for appliance String N/A
api_id API Key ID for appliance String N/A
name Appliance name String N/A
version Appliance version String N/A
plugin_version vCenter plugin version String N/A
ip_address IP address of the appliance String N/A
appliance_group_uuid Unique group identifier generated during registration String N/A

Response

Code Description Content-Type Content
200 Successfully registered appliance application/json View example response below
403 Forbidden N/A N/A
500 Internal Server Error N/A N/A

Example

Request

POST https://defense-eap01.conferdeploy.net/applianceservice/v1/orgs/ABCD1234/appliances

Request Body 

{
  "api_key": "34PY53HZGWVHQKZP6R5TMHU9",
  "api_id": "JWN58JV6IT",
  "name": "POC-Appliance",
  "version": "1.0.0",
  "plugin_version": "1.0.0",
  "ip_address": "10.0.9.1",
  "appliance_group_uuid": "ef9688ed-62c4-44a1-a388-e41fcf50748b"
}

Response 

{
  "appliance_uuid": "cae48003-6301-423a-9c57-1f0ce89bac0a",
  "appliance_group_uuid": "ef9688ed-62c4-44a1-a388-e41fcf50748b"
}

Update Appliance Info

Update an appliance’s information.

RBAC Permissions Required

Permission (.notation name) Operation(s)
appliances.registration UPDATE

Request

PUT {cbc-hostname}/applianceservice/v1/orgs/{org_key}/appliances/{appliance_id}

Request Body

{
  "version": "<string>",
  "plugin_version": "<string>",
  "appliance_group_uuid": "<string>",
}

Body Schema

Field Definition Data Type Values
version Appliance version String N/A
plugin_version vCenter plugin version String N/A
appliance_group_uuid Unique group identifier generated during registration String N/A

Response

Code Description Content-Type Content
200 Successfully updated appliance information N/A N/A
403 Forbidden N/A N/A
404 Appliance not found with the specified appliance ID N/A N/A
500 Internal Server Error N/A N/A

Example

Request

PUT https://defense-eap01.conferdeploy.net/applianceservice/v1/orgs/ABCD1234/appliances/1234

Request Body 

{
  "version": "1.0.0",
  "plugin_version": "1.0.0",
  "appliance_group_uuid": "ef9688ed-62c4-44a1-a388-e41fcf50748b"
}

Response 

200 OK No Content

Get Appliance Health details

Obtain health details of the specified appliance.

RBAC Permissions Required

Permission (.notation name) Operation(s)
appliances.registration READ

Request

GET {cbc-hostname}/applianceservice/v1/orgs/{org_key}/appliances/{appliance_id}/health

Response

Code Description Content-Type Content
200 Successful retrieved appliance health details application/json View example response below
403 Forbidden N/A N/A
404 Appliance not found with the specified appliance ID N/A N/A
500 Internal Server Error N/A N/A

Example

Request

GET https://defense-eap01.conferdeploy.net/applianceservice/v1/orgs/ABCD1234/appliances/1234/health

Response 

{
  "appliance_health": "CONNECTED",
  "gateway": "CONNECTED",
  "apw": "CONNECTED",
  "vsw": "CONNECTED",
  "acs": "CONNECTED",
  "vc_connectivity": "CONNECTED",
  "inventory": "CONNECTED",
  "ip_address": "10.0.0.1"
}

Health statuses can be one of CONNECTED, DISCONNECTED, UNHEALTHY.

Post Worker Heartbeat Time Interval

Post Worker HeartBeat time interval.

RBAC Permissions Required

Permission (.notation name) Operation(s)
appliances.registration CREATE

Request

POST {cbc-hostname}/applianceservice/v1/orgs/{orgKey}/workers/config

Request Body

{
  "appliance_uuid": "<string>",
  "appliance_group_uuid": "<string>",
  "heartbeat_interval": "<integer>",
  "workerType": "<string>"
}

Body Schema

Field Definition Data Type Values
appliance_uuid Unique appliance identifier generated during registration String N/A
appliance_group_uuid Unique group identifier generated during registration String N/A
heartbeat_interval Heartbeat interval runtime in milliseconds Integer N/A
workerType Appliance worker type String VSPHERE, APPLIANCE, ACCESS_CONTROL

Response

Code Description Content-Type Content
200 Successfully updated appliance heartbeat interval 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/applianceservice/v1/orgs/ABCD1234/workers/config

Request Body 

{
  "appliance_uuid": "f07f9fda-b122-11ea-b3de-0242ac130004",
  "appliance_group_uuid": "f07f9fda-b122-11ea-b3de-0242ac130005",
  "heartbeat_interval": "30000",
  "workerType": "APPLIANCE"
}

Response 

200 OK No Content

Last modified on November 10, 2020