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)
    • for the category Appliances Details > “appliances.details”, 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}/applianceservice/v1/orgs/{org_key}

API calls

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

Appliance Overview

Get a list of appliances using the API Key IDs associated with each appliance

RBAC Permissions Required

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

Request

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

Request Body

[
  "<string>"
]

Body Schema

Field Definition Data Type Values
Array List of API Key IDs Array 
[
  "JWN58JV6IT"
]

Response

Code Description Content-Type Content
200 Successfully fetch appliance ids 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/overview

Request Body 

[
  "JWN58JV6IT"
]

Response 

[
  {
    "api_id": "JWN58JV6IT",
    "appliance_name": "example-appliance",
    "appliance_uuid": "60d7daec-617d-443f-bae5-fee9627639ba"
  }
]

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

Get Appliances

Get a list of appliances.

RBAC Permissions Required

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

Request

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

Query Schema

Field Definition Data Type Values
status Filter the results by the appliance status String Supported:
CONNECTED, DISCONNECTED, UNHEALTHY
vc_connectivity Filter the results by the vcenter connectivity String Supported:
CONNECTED, DISCONNECTED, UNHEALTHY
vc_uuid Fetch the appliance associated with the specified vcenter uuid 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

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

Response 

[
    {
        "api_id": "CRER15EQ37",
        "name": "cwp-bucket-1-appliance",
        "heartbeat_timestamp": "2020-10-16T20:05:00.247953Z",
        "version": "1.0.0.0-17044458",
        "plugin_version": null,
        "ip_address": "10.0.0.88",
        "appliance_uuid": "b2c09f13-600c-4a76-b82b-737fa795a1b6",
        "appliance_group_uuid": "be9a29c8-1b5e-4d4b-9998-ee9da8c1436c",
        "vc_connectivity": "DISCONNECTED",
        "status": "DISCONNECTED",
        "vcenter_uuid": null
    },
    {
        "api_id": "ECGT1AWSZ9",
        "name": "my-custom-appliance",
        "heartbeat_timestamp": "2020-08-28T05:25:46.369Z",
        "version": "1.0.0.0-17044458",
        "plugin_version": null,
        "ip_address": "10.0.0.12",
        "appliance_uuid": "e4e0131b-d8ea-4a98-a752-7fbfb6c253e0",
        "appliance_group_uuid": "93f69b41-880d-4227-8e1d-8619de72da94",
        "vc_connectivity": "CONNECTED",
        "status": "CONNECTED",
        "vcenter_uuid": null
    }
]

Get Appliance by UUID

Get an appliance by uuid

RBAC Permissions Required

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

Request

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

Response

Code Description Content-Type Content
200 Successfully fetch appliance 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

GET https://defense-eap01.conferdeploy.net/applianceservice/v1/orgs/ABCD1234/appliances/e4e0131b-d8ea-4a98-a752-7fbfb6c253e0

Response 

{
    "api_id": "ECGT1AWSZ9",
    "name": "my-custom-appliance",
    "heartbeat_timestamp": "2020-08-28T05:25:46.369Z",
    "version": "1.0.0.0-17044458",
    "plugin_version": null,
    "ip_address": "10.0.0.12",
    "appliance_uuid": "e4e0131b-d8ea-4a98-a752-7fbfb6c253e0",
    "appliance_group_uuid": "93f69b41-880d-4227-8e1d-8619de72da94",
    "vc_connectivity": "CONNECTED",
    "status": "CONNECTED",
    "vcenter_uuid": null
}

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/e4e0131b-d8ea-4a98-a752-7fbfb6c253e0

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

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/e4e0131b-d8ea-4a98-a752-7fbfb6c253e0/health

Response 

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

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

Configure Worker Heartbeat Time Interval

Configure the Worker HeartBeat time interval that will be used for appliances to check in

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