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:

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}'`

2. 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
  }
}

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

4. 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.

5. 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
    }
}