Upgrades APIs

APIs for managing Upgrades

Table of Contents

Perform Upgrade

1. Perform Upgrade

Perform Upgrade API is used to perform upgrades. Upgrades are sequential. So in order to upgrade to a release, your environment must be on the version before that release. Upgrades are applied on a workload domain basis. The management domain contains the core infrastructure, so you must upgrade the management domain before upgrading the other workload domains. You must upgrade all required components to keep your system in an optimum state.

Note : Performing upgrades is supported on VMware Cloud Foundation 3.5 BOM resources and above.

1.1. Steps to Perform Upgrade. API

Download the required bundle.
- Online bundle download - Follow the VMware cloud Foundation online bundle download guide to download bundles in environment.
  - Execute Get Depot Settings API to retrieve the existing My VMware Account information.
  - Execute Update Depot Settings API to update the existing My VMware Account information.
  - Execute Update Bundle for Downloading API to Download Bundles from VMware depot account.
- Offline bundle download - Use the Bundle Transfer Utility tool. Please refer https://docs.vmware.com/en/VMware-Cloud-Foundation/4.0/vcf-40-lifecycle/GUID-8FA44ACE-8F04-47DA-845E-E0863094F7B0.html. to manually download the bundles from the depot on your local computer and then copy them to SDDC Manager.
  - Execute Upload a Bundle API to upload it to SDDC Manager.
Execute Get the Upgradables API to retrieve the list of upgradables (bundle and resource detail) in the system.
Execute Prechecks API to perform required system level health checks.
Perform upgrade and monitor the upgrade progress.

2. Domain Upgrade API

2.1. Prerequisites API

The following data is required:

Bundle ID.
Resource Type. Ex: DOMAIN.
One or more Resource upgrade specifications.
Each Resource upgrade specification should contain.
- Resource ID. Ex: Domain ID.
- Upgrade scheduled time or Upgrade now option.

The following data is optional:

A boolean for parallel ESXi upgrade (default is 'true')
A boolean for quickboot run for ESXi upgrade (default is 'false')

Tip : Refer to: UpgradeSpec and ResourceUpgradeSpec.

2.2. Steps API

Invoke the API. This API returns a task which can be polled and monitored.

cURL Request

$ curl 'https://sfo-vcf01.rainpole.io/v1/upgrades' -i -X POST \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/json' \
    -H 'Authorization: Bearer etYWRta....' \
    -d '{
  "bundleId" : "3b6af93f-f53d-4716-9374-c35fec4bc5a2",
  "resourceType" : "DOMAIN",
  "parallelUpgrade" : true,
  "resourceUpgradeSpecs" : [ {
    "resourceId" : "562d4905-56fb-4bdd-adb1-c706786c7542",
    "scheduledTimestamp" : "2024-08-27T21:11:49.353Z",
    "upgradeNow" : false,
    "esxUpgradeOptionsSpec" : {
      "enableQuickboot" : true
    }
  } ]
}'

HTTP Request

POST /v1/upgrades HTTP/1.1
Content-Type: application/json
Accept: application/json
Content-Length: 361
Host: sfo-vcf01.rainpole.io
Authorization: Bearer etYWRta....

{
  "bundleId" : "3b6af93f-f53d-4716-9374-c35fec4bc5a2",
  "resourceType" : "DOMAIN",
  "parallelUpgrade" : true,
  "resourceUpgradeSpecs" : [ {
    "resourceId" : "562d4905-56fb-4bdd-adb1-c706786c7542",
    "scheduledTimestamp" : "2024-08-27T21:11:49.353Z",
    "upgradeNow" : false,
    "esxUpgradeOptionsSpec" : {
      "enableQuickboot" : true
    }
  } ]
}

HTTP Response

HTTP/1.1 202 Accepted
Content-Type: application/json
Location: /v1/tasks/8964bd34-9b1a-44cb-8a18-d7f0de009e2d
Content-Length: 503

{
  "id" : "8964bd34-9b1a-44cb-8a18-d7f0de009e2d",
  "name" : "Upgrade DOMAIN - [acme-domain] using BUNDLE - PSC:6.7.0-13010631 VCENTER:6.7.0-13010631",
  "type" : "UPGRADE",
  "status" : "IN_PROGRESS",
  "creationTimestamp" : "2024-08-27T21:11:49.349Z",
  "resources" : [ {
    "resourceId" : "562d4905-56fb-4bdd-adb1-c706786c7542",
    "type" : "DOMAIN"
  }, {
    "resourceId" : "3b6af93f-f53d-4716-9374-c35fec4bc5a2",
    "type" : "BUNDLE"
  } ],
  "isCancellable" : false,
  "isRetryable" : false
}

Poll the status of the task using the task API with the ID from the response of the previous API.

Tip : Refer to: Get a Task.

3. Cluster Upgrade API

Note : For Cluster level upgrades, the Cluster ID's can be retrieved based on the Host's that are available for upgrade, Refer to: Get the Hosts and Get the Clusters API's.

3.1. Prerequisites API

The following data is required:

Bundle ID.
Resource Type. Ex: CLUSTER.
One or more Resource upgrade specifications.
Each Resource upgrade specification should contain.
- Resource ID. Ex: Cluster ID.
- Upgrade scheduled time or Upgrade now option.

The following data is optional:

A boolean for parallel ESXi upgrade (default is 'true')
A boolean for quickboot run for ESXi upgrade (default is 'false')

Tip : Refer to: UpgradeSpec and ResourceUpgradeSpec.

3.2. Steps API

Invoke the API. This API returns a task which can be polled and monitored.

cURL Request

$ curl 'https://sfo-vcf01.rainpole.io/v1/upgrades' -i -X POST \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/json' \
    -H 'Authorization: Bearer etYWRta....' \
    -d '{
  "bundleId" : "3b6af93f-f53d-4716-9374-c35fec4bc5a2",
  "resourceType" : "CLUSTER",
  "parallelUpgrade" : true,
  "resourceUpgradeSpecs" : [ {
    "resourceId" : "c146b9bf-1c46-44c5-928a-9010cac170f5",
    "scheduledTimestamp" : "2024-08-27T22:11:54.931Z",
    "upgradeNow" : false,
    "esxUpgradeOptionsSpec" : {
      "esxUpgradeFailureAction" : {
        "retryDelay" : 0,
        "retryCount" : 0,
        "action" : "FAIL"
      },
      "enforceHclValidation" : true,
      "enableQuickPatch" : false,
      "enableQuickboot" : true,
      "disableHac" : true,
      "disableDpm" : true,
      "preRemediationPowerAction" : "DO_NOT_CHANGE_POWER_STATE"
    }
  } ]
}'

HTTP Request

POST /v1/upgrades HTTP/1.1
Content-Type: application/json
Accept: application/json
Content-Length: 675
Host: sfo-vcf01.rainpole.io
Authorization: Bearer etYWRta....

{
  "bundleId" : "3b6af93f-f53d-4716-9374-c35fec4bc5a2",
  "resourceType" : "CLUSTER",
  "parallelUpgrade" : true,
  "resourceUpgradeSpecs" : [ {
    "resourceId" : "c146b9bf-1c46-44c5-928a-9010cac170f5",
    "scheduledTimestamp" : "2024-08-27T22:11:54.931Z",
    "upgradeNow" : false,
    "esxUpgradeOptionsSpec" : {
      "esxUpgradeFailureAction" : {
        "retryDelay" : 0,
        "retryCount" : 0,
        "action" : "FAIL"
      },
      "enforceHclValidation" : true,
      "enableQuickPatch" : false,
      "enableQuickboot" : true,
      "disableHac" : true,
      "disableDpm" : true,
      "preRemediationPowerAction" : "DO_NOT_CHANGE_POWER_STATE"
    }
  } ]
}

HTTP Response

HTTP/1.1 202 Accepted
Content-Type: application/json
Location: /v1/tasks/8964bd34-9b1a-44cb-8a18-d7f0de009e2d
Content-Length: 481

{
  "id" : "8964bd34-9b1a-44cb-8a18-d7f0de009e2d",
  "name" : "Upgrade DOMAIN - [acme-domain] using BUNDLE - HOST:6.7.0-13006603",
  "type" : "UPGRADE",
  "status" : "IN_PROGRESS",
  "creationTimestamp" : "2024-08-27T21:11:54.931Z",
  "resources" : [ {
    "resourceId" : "562d4905-56fb-4bdd-adb1-c706786c7542",
    "type" : "DOMAIN"
  }, {
    "resourceId" : "3b6af93f-f53d-4716-9374-c35fec4bc5a2",
    "type" : "BUNDLE"
  } ],
  "isCancellable" : false,
  "isRetryable" : false
}

Poll the status of the task using the task API with the ID from the response of the previous API.

Tip : Refer to: Get a Task.

4. vLCM Cluster Upgrade API

Note : For vLCM Cluster level upgrades, the Cluster ID's can be retrieved based on the Host's that are available for upgrade, Refer to: Get the Hosts and Get the Clusters API's.

4.1. Prerequisites API

The following data is required:

Bundle ID.
Resource Type. Ex: CLUSTER.
Optional Draft Mode.
One or more Resource upgrade specifications.
Each Resource upgrade specification should contain.
- Resource ID. Ex: Cluster ID.
- Upgrade scheduled time or Upgrade now option.
- Personality Spec
  - Personality ID
  - Optional Hardware Support Specs

The following data is optional:

A boolean for quickboot run for ESXi upgrade (default is 'true' if not specified)

Tip : Refer to: UpgradeSpec, ResourceUpgradeSpec, PersonalitySpec and HardwareSupportSpec.

4.2. Steps API

Invoke the API. This API returns a task which can be polled and monitored. If the API is invoked with draftMode set to true, see Step 3

cURL Request

$ curl 'https://sfo-vcf01.rainpole.io/v1/upgrades' -i -X POST \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/json' \
    -H 'Authorization: Bearer etYWRta....' \
    -d '{
  "bundleId" : "3b6af93f-f53d-4716-9374-c35fec4bc5a2",
  "resourceType" : "CLUSTER",
  "draftMode" : false,
  "resourceUpgradeSpecs" : [ {
    "resourceId" : "c146b9bf-1c46-44c5-928a-9010cac170f5",
    "scheduledTimestamp" : "2024-08-27T22:11:48.252Z",
    "upgradeNow" : false,
    "personalitySpec" : {
      "personalityId" : "c6dbbf37-12f8-4179-820e-ab731996eb60",
      "hardwareSupportSpecs" : [ {
        "name" : "HSM",
        "packageSpec" : {
          "name" : "HSP",
          "version" : "1.0.0"
        }
      } ]
    },
    "esxUpgradeOptionsSpec" : {
      "enableQuickboot" : true
    }
  } ]
}'

HTTP Request

POST /v1/upgrades HTTP/1.1
Content-Type: application/json
Accept: application/json
Content-Length: 615
Host: sfo-vcf01.rainpole.io
Authorization: Bearer etYWRta....

{
  "bundleId" : "3b6af93f-f53d-4716-9374-c35fec4bc5a2",
  "resourceType" : "CLUSTER",
  "draftMode" : false,
  "resourceUpgradeSpecs" : [ {
    "resourceId" : "c146b9bf-1c46-44c5-928a-9010cac170f5",
    "scheduledTimestamp" : "2024-08-27T22:11:48.252Z",
    "upgradeNow" : false,
    "personalitySpec" : {
      "personalityId" : "c6dbbf37-12f8-4179-820e-ab731996eb60",
      "hardwareSupportSpecs" : [ {
        "name" : "HSM",
        "packageSpec" : {
          "name" : "HSP",
          "version" : "1.0.0"
        }
      } ]
    },
    "esxUpgradeOptionsSpec" : {
      "enableQuickboot" : true
    }
  } ]
}

HTTP Response

HTTP/1.1 202 Accepted
Content-Type: application/json
Location: /v1/tasks/8964bd34-9b1a-44cb-8a18-d7f0de009e2d
Content-Length: 477

{
  "id" : "8964bd34-9b1a-44cb-8a18-d7f0de009e2d",
  "name" : "Upgrade SDDC_MANAGER - [] using BUNDLE - HOST:6.7.0-13006603",
  "type" : "UPGRADE",
  "status" : "IN_PROGRESS",
  "creationTimestamp" : "2024-08-27T21:11:48.246Z",
  "resources" : [ {
    "resourceId" : "c146b9bf-1c46-44c5-928a-9010cac170f5",
    "type" : "CLUSTER"
  }, {
    "resourceId" : "3b6af93f-f53d-4716-9374-c35fec4bc5a2",
    "type" : "BUNDLE"
  } ],
  "isCancellable" : false,
  "isRetryable" : false
}

Poll the status of the task using the task API with the ID from the response of the previous API.

Tip : Refer to: Get a Task.

If the upgrade is created with draftMode set to true, the upgrade status will be in "DRAFT" state and you can trigger a hardware compatibility and compliance check before scheduling the upgrade. Invoke the API, with the upgrade ID from step 1, to trigger/start the hardware compatibility and compliance check.

cURL Request

$ curl 'https://sfo-vcf01.rainpole.io/v1/upgrades/ad9db936-62ef-4efe-986e-f551676012df/prechecks' -i -X POST \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/json' \
    -H 'Authorization: Bearer etYWRta....'

HTTP Request

POST /v1/upgrades/ad9db936-62ef-4efe-986e-f551676012df/prechecks HTTP/1.1
Content-Type: application/json
Accept: application/json
Host: sfo-vcf01.rainpole.io
Authorization: Bearer etYWRta....

HTTP Response

HTTP/1.1 202 Accepted
Content-Type: application/json
Location: /v1/tasks/a88512fc-18d0-458a-adf8-4ba10eab63ad
Content-Length: 2033

{
  "id" : "a88512fc-18d0-458a-adf8-4ba10eab63ad",
  "name" : "PRECHECK",
  "type" : "PRECHECK",
  "status" : "IN_PROGRESS",
  "creationTimestamp" : "2024-08-27T21:11:49.105Z",
  "completionTimestamp" : "2024-08-27T21:11:49.105Z",
  "subTasks" : [ {
    "name" : "vLCM Precheck for cluster: acme-cluster",
    "description" : "vLCM Precheck for cluster: acme-cluster",
    "status" : "IN_PROGRESS",
    "creationTimestamp" : "2024-08-27T21:11:49.110Z",
    "stages" : [ {
      "name" : "vLCM cluster health check",
      "description" : "Perform Stage - Perform Stage - Precheck if the cluster are in a good state to be updated with the desired software image",
      "status" : "UNKNOWN",
      "errors" : [ ]
    } ],
    "resources" : [ {
      "resourceId" : "c146b9bf-1c46-44c5-928a-9010cac170f5",
      "type" : "CLUSTER"
    } ],
    "subTasks" : [ {
      "name" : "vLCM Precheck for host: 10.0.0.100",
      "description" : "vLCM Precheck for host: 10.0.0.100",
      "status" : "IN_PROGRESS",
      "creationTimestamp" : "2024-08-27T21:11:49.111Z",
      "stages" : [ {
        "name" : "vLCM image scan",
        "description" : "Perform Stage - Perform Stage - Host compliance",
        "status" : "UNKNOWN",
        "errors" : [ ]
      }, {
        "name" : "vLCM image baseOS scan",
        "description" : "Perform Stage - Perform Stage - Validating the baseOS version.",
        "status" : "FAILED",
        "errors" : [ {
          "errorCode" : "com.vmware.vcIntegrity.lifecycle.HostScan.BaseImageDowngrade",
          "errorType" : "ERROR",
          "message" : "Desired Base Image version 7.0.0-1.20.16321839 is a downgrade of the installed version ESXi.",
          "remediationMessage" : "Replace the Base Image in the desired state with one of the same or higher version."
        } ]
      } ],
      "resources" : [ {
        "resourceId" : "00c68b46-f478-4d94-8bde-c15fd980df04",
        "type" : "ESX"
      } ],
      "subTasks" : [ ]
    } ]
  } ],
  "isCancellable" : false,
  "isRetryable" : false
}

Tip : Refer to: performPrechecks API

Poll the status of the hardware compatibility and compliance check task using the task API with the ID from the response of the previous API.

cURL Request

$ curl 'https://sfo-vcf01.rainpole.io/v1/upgrades/ad9db936-62ef-4efe-986e-f551676012df/prechecks/ad9db936-62ef-4efe-986e-f551676012df' -i -X GET \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/json' \
    -H 'Authorization: Bearer etYWRta....'

HTTP Request

GET /v1/upgrades/ad9db936-62ef-4efe-986e-f551676012df/prechecks/ad9db936-62ef-4efe-986e-f551676012df HTTP/1.1
Content-Type: application/json
Accept: application/json
Host: sfo-vcf01.rainpole.io
Authorization: Bearer etYWRta....

HTTP Response

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 2033

{
  "id" : "a88512fc-18d0-458a-adf8-4ba10eab63ad",
  "name" : "PRECHECK",
  "type" : "PRECHECK",
  "status" : "IN_PROGRESS",
  "creationTimestamp" : "2024-08-27T21:11:50.437Z",
  "completionTimestamp" : "2024-08-27T21:11:50.437Z",
  "subTasks" : [ {
    "name" : "vLCM Precheck for cluster: acme-cluster",
    "description" : "vLCM Precheck for cluster: acme-cluster",
    "status" : "IN_PROGRESS",
    "creationTimestamp" : "2024-08-27T21:11:50.437Z",
    "stages" : [ {
      "name" : "vLCM cluster health check",
      "description" : "Perform Stage - Perform Stage - Precheck if the cluster are in a good state to be updated with the desired software image",
      "status" : "UNKNOWN",
      "errors" : [ ]
    } ],
    "resources" : [ {
      "resourceId" : "c146b9bf-1c46-44c5-928a-9010cac170f5",
      "type" : "CLUSTER"
    } ],
    "subTasks" : [ {
      "name" : "vLCM Precheck for host: 10.0.0.100",
      "description" : "vLCM Precheck for host: 10.0.0.100",
      "status" : "IN_PROGRESS",
      "creationTimestamp" : "2024-08-27T21:11:50.437Z",
      "stages" : [ {
        "name" : "vLCM image scan",
        "description" : "Perform Stage - Perform Stage - Host compliance",
        "status" : "UNKNOWN",
        "errors" : [ ]
      }, {
        "name" : "vLCM image baseOS scan",
        "description" : "Perform Stage - Perform Stage - Validating the baseOS version.",
        "status" : "FAILED",
        "errors" : [ {
          "errorCode" : "com.vmware.vcIntegrity.lifecycle.HostScan.BaseImageDowngrade",
          "errorType" : "ERROR",
          "message" : "Desired Base Image version 7.0.0-1.20.16321839 is a downgrade of the installed version ESXi.",
          "remediationMessage" : "Replace the Base Image in the desired state with one of the same or higher version."
        } ]
      } ],
      "resources" : [ {
        "resourceId" : "00c68b46-f478-4d94-8bde-c15fd980df04",
        "type" : "ESX"
      } ],
      "subTasks" : [ ]
    } ]
  } ],
  "isCancellable" : false,
  "isRetryable" : false
}

Once the hardware compatibility and compliance check task is completed and result is reviewed, schedule the upgrade.

cURL Request

$ curl 'https://sfo-vcf01.rainpole.io/v1/upgrades/ad9db936-62ef-4efe-986e-f551676012df' -i -X PATCH \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/json' \
    -H 'Authorization: Bearer etYWRta....' \
    -d '{
  "scheduledTimestamp" : "2024-08-27T22:11:54.472Z",
  "upgradeNow" : false
}'

HTTP Request

PATCH /v1/upgrades/ad9db936-62ef-4efe-986e-f551676012df HTTP/1.1
Content-Type: application/json
Accept: application/json
Content-Length: 79
Host: sfo-vcf01.rainpole.io
Authorization: Bearer etYWRta....

{
  "scheduledTimestamp" : "2024-08-27T22:11:54.472Z",
  "upgradeNow" : false
}

HTTP Response

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 1623

{
  "id" : "ad9db936-62ef-4efe-986e-f551676012df",
  "bundleId" : "3b6af93f-f53d-4716-9374-c35fec4bc5a2",
  "resourceType" : "CLUSTER",
  "resourceUpgradeSpecs" : [ {
    "resourceId" : "c146b9bf-1c46-44c5-928a-9010cac170f5",
    "shutdownVms" : null,
    "toVersion" : null,
    "scheduledTimestamp" : "2024-08-27T22:11:54.472Z",
    "upgradeNow" : null,
    "personalitySpec" : null,
    "customIsoSpec" : null,
    "enableQuickboot" : null,
    "evacuateOfflineVms" : null,
    "esxUpgradeOptionsSpec" : {
      "enableQuickboot" : true,
      "evacuateOfflineVms" : false
    },
    "hostsToUpgrade" : null
  } ],
  "status" : "SCHEDULED",
  "taskId" : "ad9db936-62ef-4efe-986e-f551676012df",
  "bundle" : {
    "id" : "3b6af93f-f53d-4716-9374-c35fec4bc5a2",
    "type" : "VMWARE_SOFTWARE",
    "description" : "ESX update bundle -  13004448(67EP7)==>13010696 (vsphere67U2)",
    "version" : "253.0.0-111959",
    "severity" : null,
    "vendor" : "VMware",
    "releasedDate" : "2019-05-10T10:29:10.645Z",
    "isCumulative" : false,
    "isCompliant" : null,
    "sizeMB" : 4.3201446533203125E-4,
    "downloadStatus" : "SUCCESSFUL",
    "components" : [ {
      "description" : "ESX_HOST Update Bundle",
      "vendor" : "VMware",
      "releasedDate" : "2019-05-10T10:29:10.645Z",
      "toVersion" : "6.7.0-13006603",
      "fromVersion" : "6.7.0-13004448",
      "imageType" : "INSTALL",
      "id" : "a65d9d83-88b9-475f-a2ba-ee5d9be34f8d",
      "type" : "HOST",
      "isUserInputRequired" : null
    } ],
    "applicabilityStatus" : null,
    "applicabilityOrder" : null,
    "isPartiallyUpgraded" : null
  }
}

Tip : Refer to Commit/Reschedule Upgrade API

Poll the status of the upgrade task using the task API with the ID from the response of the previous API.

Tip : Refer to: Get a Task.

4.3. Related APIs API

[_getupgradables] API [_startprecheck] API [_getprechecktask] API [_performupgrade] API [_gettasks] API [_gettask] API
Last updated 2024-08-27 16:13:54 -0700

Operations

GET

Get Upgrades

Retrieve a list of upgrades

POST

Perform Upgrade

Start an upgrade operation

POST

Start Upgrade Precheck

Start an upgrade precheck operation

GET

Get Upgrade By Id