VMware Cloud Foundation – APIs for Managing SOS

With the release of VMware Cloud Foundation v4.4.0, VMware introduced a number of enhancements and new Public APIs. One of particular interest is the APIs for Managing SOS, with the introduction of this Public API its now possible to perform health checks and generate support bundles as well as download them to your local system.

For those not familiar with SoS, it stands for Supportability and Serviceability (SoS) Utility which is a command-line tool used to run health checks and collect logs for VMware Cloud Foundation components. For more information see the VMware Cloud Foundation documentation here.

Let’s first take a look at what the APIs are that have been included in the VMware Cloud Foundation v4.4.0, these are:

API Description
GET /v1/system/health-summary Fetch All Health Summary Tasks
GET /v1/system/health-summary/{id} Fetch the progress of a Health summary task
GET /v1/system/health-summary/{id}/data Download Health Summary Bundle
POST /v1/system/health-summary Initiates Health Summary checks
GET /v1/system/support-bundles Fetch All Support bundle Tasks
GET /v1/system/support-bundles/{id} Fetch the progress of support bundle task
GET /v1/system/support-bundles/{id}/data Download Support bundles
POST /v1/system/support-bundles Initiates Support bundle download

With the introduction of these new Public APIs its now possible to perform either health checks (health-summary) or generate support bundles (support-bundles) and then once complete, download the .tar file for each. The process is similar for for both:

  1. Perform the health check or generate support bundle using the POST method. This starts the operation with a unique task ID.

  2. Obtain the task ID for the operation using the GET /v1/system/health-summary or /v1/system/support-bundles API. This provides a list of all tasks related to the action.

  3. Download the .tar file using the GET /v1/system/health-summary/{id}/data or /v1/system/support-bundles/{id}/data API. This downloads the .tar file from SDDC Manager to the local system.

Procedure

Let’s walk through this process using the health-summary APIs as an example.

  1. Obtain the authentication token, because we are using the Public API we need to get an authentication token from SDDC Manager. We will do this by capturing the token to a variable that we can then use for each subsequent API call as this simplifies the command for us.
TOKEN=`curl -X POST -H "Content-Type: application/json" -d '{"username": "administrator@vsphere.local","password": "VMw@re1!"}' -k https://localhost/v1/tokens | awk -F "\"" '{ print $4}'`
  1. Prepare the health-summary json spec. When using the POST /v1/system/health-summary. To perform the health check you must first create the json spec, this instructs the API on what health checks you want to perform. Using the sample below and make the desired changes and save it.
{
  "healthChecks": {
      "certificateHealth": false,
      "composabilityHealth": false,
      "computeHealth": false,
      "connectivityHealth": false,
      "dnsHealth": false,
      "generalHealth": true,
      "hardwareCompatibilityHealth": false,
      "ntpHealth": false,
      "passwordHealth": false,
      "servicesHealth": false,
      "storageHealth": false
  },
  "options": {
      "config": {
          "force": false,
          "skipKnownHostCheck": false
      },
      "include": {
          "summaryReport": true
      }
  },
  "scope": {
      "domains": [ {
          "clusterNames": [ "" ],
          "domainName": ""
      } ],
      "includeAllDomains": true,
      "includeFreeHosts": true
  }
}
  1. Start a health check operation using the json spec created in step 2.
curl -X POST -H "Content-Type: application/json" -H "Authorization: Bearer $TOKEN" -k https://sfo-vcf01.sfo.rainpole.io/v1/system/health-summary -d @/tmp/healthCheck.json

On a successful submission you get the following example response, here you can see the unique task id for the operation, we will need this for future steps.

{"id": "9f4b293d-a332-47d2-b2cf-960c7c242035", "description": "Health-Check operation for SDDC"}
  1. Check the status of the health check operation.
curl -X GET -H "Content-Type: application/json" -H "Authorization: Bearer $TOKEN" -k https://sfo-vcf01.sfo.rainpole.io/v1/system/health-summary/9f4b293d-a332-47d2-b2cf-960c7c242035

The following example response will be returned:

{"bundleName": "healthcheck-2022-02-25-09-24-22-2347", "status": "IN_PROGRESS", "bundleAvailable": "No", "id": "9f4b293d-a332-47d2-b2cf-960c7c242035", "completionTimestamp": "", "description": "Health-Check operation for SDDC", "creationTimestamp": "2022-02-25T09:24:22.303Z"}

Here we can can see that the operation has a "status" of IN_PROGRESS, this means the health check is still running and we need to wait for this to complete. Repeat this process until the "status" changes to COMPLETED_WITH_SUCCESS. Once its complete ensure that "bundleAvailable" also says Yes.

  1. Request the health check .tar file for a completed operation.
curl -X GET -H "Content-Type: application/json" -H "Authorization: Bearer $TOKEN" -k https://sfo-vcf01.sfo.rainpole.io/v1/system/health-summary/9f4b293d-a332-47d2-b2cf-960c7c242035/data --output /tmp/health-summary-9f4b293d-a332-47d2-b2cf-960c7c242035.tar

The same process can be used to perform the support bundle generation and .tar file download. For reference here is the json spec used to submit the support bundle operation using the POST /v1/system/support-bundles API.

{
    "logs": {
        "apiLogs": true,
        "esxLogs": false,
        "nsxLogs": false,
        "sddcManagerLogs": false,
        "systemDebugLogs": false,
        "vcLogs": false,
        "vmScreenshots": false,
        "vraLogs": false,
        "vrliLogs": false,
        "vropsLogs": false,
        "vrslcmLogs": false,
        "vxrailManagerLogs": false,
        "wcpLogs": false
    },
    "options": {
        "config": {
            "force": false,
            "skipKnownHostCheck": false
        },
        "include": {
            "healthCheck": false,
            "summaryReport": false
        }
    },
    "scope": {
        "domains": [ {
            "clusterNames": [ "" ],
            "domainName": ""
        } ],
        "includeFreeHosts": false
    }
}

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s