Using APIs to Upgrade Virtual Appliances

This topic provides instructions on calling the Trend Micro Cloud One™ APIs required for Network Security virtual appliance upgrades. Available functions include:

• Querying appliance status to determine whether an upgrade or rollback is available
• Triggering an upgrade or rollback operation
• Checking upgrade and rollback progress and status

For the examples that follow, assume that the Trend Micro Cloud One API key is stored in a variable named SECRET, and that the Trend Micro Cloud One Region is stored in a variable named REGION. For example, replace <YOUR_API_KEY> with the secret from your API key and <YOUR_CLOUD_ONE_REGION> with your account's region ID. For information on Trend Micro Cloud One accounts and regions, see the Accounts help.

SECRET= "<YOUR_API_KEY>"
REGION= "<YOUR_CLOUDONE_REGION, e.g. us-1>"

The examples below are written for bash, uses jq to reformat the output and curl to perform requests. Learn more about these APIs in the API Reference.

Determine Appliance Id

All the API calls below operate on a single appliance instance which is identified by an ID. Retrieve a list of all your managed appliances, to determine the IDs of your managed virtual appliances by entering the following in curl.

The jq command extracts the mapping between the CloudOne ID and the instanceID.

URL="https://network.${REGION}.cloudone.trendmicro.com/api/appliances"
curl --location --request GET "${URL}" \
--header "Authorization: ApiKey ${SECRET}" \
--header "api-version: v1" \
| jq '.appliances[] | {ID: .ID, instanceId: .instanceId}'

Sample response

{
 "ID": 2,
 "instanceId": "i-053cced65fea28c18"
}
{
 "ID": 8,
 "instanceId": "i-0e7b568dd0f88d0c1"
}

Status query

To query whether an upgrade is available the appliance ID needs to be specified in a call to the "migrationversions" API with the "applianceId" specifying the appropriate virtual appliance:

URL="https://network.${REGION}.cloudone.trendmicro.com/api/migrationversions"
curl --location --request GET "${URL}?applianceId=8" \
--header "Authorization: ApiKey ${SECRET}" \
--header "api-version: v1" \
| jq

Sample response

The response below indicates an upgrade is available.

{
 "baseVersion": "2021.3.0.10968",
 "state": "outOfDate",
 "permission": "write",
 "upgrade": "2021.4.1.10996",
 "rollback": null
 }

This response indicates that the appliance is already at the latest available version so no upgrade is available. The appliance can however be rolled back to a previously upgradable version.

{
"baseVersion": "2021.4.1.10996",
"state": "upToDate",
"permission": "write",
"upgrade": null,
"rollback": "2021.3.0.10968"
}

Trigger upgrade

If the status query indicates than an upgrade is available, then you can initiate an upgrade by calling the "appliancemigrations" API with the "upgrade" action in the request. Specify the appropriate "applianceId" value to identify the appliance to be upgraded:

URL="https://network.${REGION}.cloudone.trendmicro.com/api/appliancemigrations"
curl --data '{"action": "upgrade", "applianceId": 8}' \
--location --request POST "${URL}" \
--header "Authorization: ApiKey ${SECRET}" \
--header "api-version: v1" \
--header "Content-Type: application/json"

No output is returned if the request is successful. The upgrade proceeds in the background and you can track progress by calling the status query API.

Trigger rollback

The status query shows that a rollback version is available if a software version was upgraded. Call the "appliancemigrations" API with the the "rollback" action in the request to rollback to a prior software version.

URL="https://network.${REGION}.cloudone.trendmicro.com/api/appliancemigrations"
curl --data '{"action": "rollback", "applianceId": 8}' \
--location --request POST "${URL}" \
--header "Authorization: ApiKey ${SECRET}" \
--header "api-version: v1" \
--header "Content-Type: application/json"

No output is returned if the upgrade is successful. The upgrade proceeds in the background and you can track progress by calling the status upgrade API.

Check upgrade and rollback progress

Make a GET request to the "appliancemigrations" API to check on the progress and outcome of upgrade and rollback requests. This API provides status information for multiple instances at once.

URL="https://network.${REGION}.cloudone.trendmicro.com/api/appliancemigrations"
curl --location --request GET "${URL}?applianceIds=8" \
--header "Authorization: ApiKey ${SECRET}" \
--header "api-version: v1" \
| jq

Sample responses

{
"statuses": [
  {
   "applianceId": 8,
   "action": "upgrade",
   "currentStep": 3,
   "totalSteps": 0,
   "state": "handling package",
   "result": "",
   "message": "verifying package",
   "time": 0
  }
 ]
}

{
"statuses": [
  {
   "applianceId": 8,
   "action": "upgrade",
   "currentStep": 4,
   "totalSteps": 0,
   "state": "upgrading",
   "result": "",
   "message": "installing package",
   "time": 0
  }
 ]
} 

{
"statuses": [
  {
   "applianceId": 8,
   "action": "upgrade",
   "currentStep": 4,
   "totalSteps": 0,
   "state": "upgrading",
   "result": "",
   "message": "installing package",
   "time": 0
  }
 ]
} 

{
"statuses": [
  {
   "applianceId": 8,
   "action": "upgrade",
   "currentStep": 6,
   "totalSteps": 6,
   "state": "finish",
   "result": "success",
   "message": "installation complete",
   "time": 1619182490160
  }
 ]
} 

{
"statuses": [
  {
   "applianceId": 8,
   "action": "rollback",
   "currentStep": 3,
   "totalSteps": 4,
   "state": "rollback",
   "result": "",
   "message": "rollback software",
   "time": 1619182744545
  }
 ]
} 

{
"statuses": [
  {
   "applianceId": 8,
   "action": "rollback",
   "currentStep": 4,
   "totalSteps": 0,
   "state": "finish",
   "result": "success",
   "message": "rollback complete",
   "time": 0
  }
 ]
}