- URL:
- https://<root>/system/upgrades/upgrade
- Methods:
POST- Required Capability:
- Access allowed with either "Security and infrastructure" or "Servers" privileges
- Version Introduced:
- 10.9
Description
The upgrade operation upgrades, through either a patch or a release, an ArcGIS Enterprise on Kubernetes deployment to the current version.
Before performing an upgrade, the unique ID associated with the patch or release must be retrieved from the version manifest using the Available operation. The version manifest is a JSON array of version objects that contain update-specific information, including a JSON array of container objects that specify affected containers and include their name, checksum, and image values.
Once the ID has been retrieved, you must also retrieve the required upgrade settings that will be passed through as part of the upgrade operation. Some settings will require user input before they can be used during an upgrade. For more information about current upgrade settings, see the Upgrade settings section below.
Once the upgrade job request has been submitted, the deployment will either install a new patch on the base version or upgrade the entire deployment to the latest release. While the job is running, the Upgrades resource will return detailed, real-time job messages and status information. The upgrades resource's child operations and resources will remain inaccessible for the duration of the upgrade.
Request parameters
| Parameter | Details |
|---|---|
(Required) | The unique ID associated with a patch or release. You can get the version manifest ID for a patch or release from the JSON view of the Available operation. Example |
(Optional) | The ArcGIS Enterprise on Kubernetes license file ( |
(Optional) | The file containing the version manifest. |
(Optional; Required for version 11.0) | A JSON object containing details for release upgrade settings. These settings, retrieved from the Get Upgrade Settings operation, must be included in the request for the upgrade to be successful. Currently, the object supports the following three upgrade settings: For more information about these settings, see the Upgrade settings section below. |
(Required for deployments using cloud-native relational data stores) | Introduced at 11.4. A JSON object containing the storage configurations for a deployment's cloud-native relational data store, ensuring that the system has the required storage volume configuration established after the upgrade completes. The
When upgrading from 11.4 to 11.5 (or later), or upgrading from one later version of ArcGIS Enterprise on Kubernetes to another, this parameter will need to be included in the request if a cloud-native relational stores have been registered with the deployment. This parameter is not applicable to environments upgrading from 11.3 to 11.4. Example |
(Required for deployments using cloud-native relational data stores) | Introduced at 11.4. A JSON array containing the deployment's cloud storage configuration for a cloud-native relational data store, including the credentials for the service. For more information on the required properties for When upgrading from 11.4 to 11.5 (or later), or upgrading from one later version of ArcGIS Enterprise on Kubernetes to another, this parameter will need to be included in the request if a cloud-native relational stores have been registered with the deployment. This parameter is not applicable to environments upgrading from 11.3 to 11.4. Example |
| The response format. The default format is Values: |
Upgrade settings
The table below outlines the currently supported settings that are required when upgrading an ArcGIS Enterprise on Kubernetes deployment.
| Property | Details |
|---|---|
| When set to Values: |
| A JSON object that stores an uploaded ArcGIS Enterprise on Kubernetes license file ( Example |
| A JSON object containing the storage configurations for persistent volumes that are required while upgrading. |
Deprecated parameters
The following parameters have been deprecated at ArcGIS Enterprise on Kubernetes 11.0. The information previously specified by these parameters is now included with the upgrade parameter:
| Parameter | Details |
|---|---|
(Optional) | A valid ArcGIS GIS Server license file (either |
(Optional) | When set to Values: |
Example usages
Example one: license file
The following is a sample POST request for the upgrade operation, demonstrating a request that includes the license parameter:
POST /context/admin/system/upgrades/upgrade HTTP/1.1
Host: organization.domain.com
Content-Type: multipart/form-data; boundary=----WebKitFormBoundaryAMpB0mfM6ckdcpcb
Content-Length: []
------WebKitFormBoundaryAMpB0mfM6ckdcpcb
Content-Disposition: form-data; name="versionManifest"
{"id":"rel_123456_4000"}
------WebKitFormBoundaryAMpB0mfM6ckdcpcb
Content-Disposition: form-data; name="licenseFile"; filename="AllUTs_AllAddOnApps.json"
Content-Type: application/json
{"MyEsri": {"version":"10.9.1","definitions": {"userTypes": [{"id":"viewerUT","name":"Viewer","description":"Viewer","level":"1","isEsriDefault":true,"apps": [{"isAppBundle":true,"id":"officeAppsAB","entitlements":[]},{"isAppBundle":false,"id":"runtimelite","entitlements":["runtimelite"]},{"isAppBundle":true,"id":"essentialAppsAB","entitlements":[]}]},...],"licenseManagement": {"licenses": [{"license": "U0VSV..."}]}}}}
------WebKitFormBoundaryAMpB0mfM6ckdcpcb
Content-Disposition: form-data; name="versionManifestFile"; filename=""
Content-Type: application/octet-stream
------WebKitFormBoundaryAMpB0mfM6ckdcpcb
Content-Disposition: form-data; name="updateToLatestPatch"
False
------WebKitFormBoundaryAMpB0mfM6ckdcpcb
Content-Disposition: form-data; name="volumesConfig"
------WebKitFormBoundaryAMpB0mfM6ckdcpcb
Content-Disposition: form-data; name="cloudConfig"
------WebKitFormBoundaryAMpB0mfM6ckdcpcb
Content-Disposition: form-data; name="upgradeSettings"
{}
------WebKitFormBoundaryAMpB0mfM6ckdcpcb
Content-Disposition: form-data; name="f"
pjson
------WebKitFormBoundaryAMpB0mfM6ckdcpcb
Content-Disposition: form-data; name="token"
<token>
------WebKitFormBoundaryAMpB0mfM6ckdcpcb--Example two: upgrade settings
Prerequisites
Before performing this operation, the list of required settings needed for the upgrade must be retrieved using the Get Upgrade Settings operation:
POST /context/admin/system/upgrades/getUpgradeSettings HTTP/1.1
Host: organization.domain.com
Content-Type: application/x-www-form-urlencoded
Content-Length: []
upgradeId={"id": "rel_08042022_3000"}&f=pjson&token=<token>Once the list of upgrade settings is retrieved, modify the settings as necessary. For example, when upgrading an ArcGIS Enterprise on Kubernetes deployment from version 10.9.1 to 11.0, you must modify the value property for the license JSON object to reflect the upload ID of an uploaded ArcGIS Enterprise on Kubernetes license file:
{
"userInputs": [
{
"seqNum": 0,
"defaultValue": false,
"name": "updateToLatestPatch",
"description": "updateToLatestPatch",
"isManagerInvisibleField": true,
"id": "updateToLatestPatch",
"type": "Boolean",
"value": true,
"required": true,
"newfield": ""
},
{
"seqNum": 1,
"validFileExtensions": ["json"],
"name": "licenseUpload",
"description": "licenseFieldDescToken",
"id": "licenseUpload",
"type": "File",
"value": "caf81a83-b6a7-4810-9e7c-dbff96c6050a",
"required": true,
"newfield": ""
}
]
}Example two: upgrade settings
The following is a sample POST request for the upgrade operation, demonstrating a request that includes the upgrade parameter:
POST /context/admin/system/upgrades/upgrade HTTP/1.1
Host: organization.domain.com
Content-Type: multipart/form-data; boundary=----WebKitFormBoundaryAMpB0mfM6ckdcpcb
Content-Length: []
------WebKitFormBoundaryAMpB0mfM6ckdcpcb
Content-Disposition: form-data; name="versionManifest"
{"id": "rel_08042022_3000"}
------WebKitFormBoundaryAMpB0mfM6ckdcpcb
Content-Disposition: form-data; name="licenseFile"; filename="AllUTs_AllAddOnApps.json"
Content-Type: application/json
------WebKitFormBoundaryAMpB0mfM6ckdcpcb
Content-Disposition: form-data; name="versionManifestFile"; filename=""
Content-Type: application/octet-stream
------WebKitFormBoundaryAMpB0mfM6ckdcpcb
Content-Disposition: form-data; name="updateToLatestPatch"
False
------WebKitFormBoundaryAMpB0mfM6ckdcpcb
Content-Disposition: form-data; name="volumesConfig"
------WebKitFormBoundaryAMpB0mfM6ckdcpcb
Content-Disposition: form-data; name="cloudConfig"
------WebKitFormBoundaryAMpB0mfM6ckdcpcb
Content-Disposition: form-data; name="upgradeSettings"
{
"userInputs": [
{
"seqNum": 0,
"defaultValue": false,
"name": "updateToLatestPatch",
"description": "updateToLatestPatch",
"isManagerInvisibleField": true,
"id": "updateToLatestPatch",
"type": "Boolean",
"value": true,
"required": true,
"newfield": ""
},
{
"seqNum": 1,
"validFileExtensions": ["json"],
"name": "licenseUpload",
"description": "licenseFieldDescToken",
"id": "licenseUpload",
"type": "File",
"value": "caf81a83-b6a7-4810-9e7c-dbff96c6050a",
"required": true,
"newfield": ""
}
]
}
------WebKitFormBoundaryAMpB0mfM6ckdcpcb
Content-Disposition: form-data; name="f"
pjson
------WebKitFormBoundaryAMpB0mfM6ckdcpcb
Content-Disposition: form-data; name="token"
<token>
------WebKitFormBoundaryAMpB0mfM6ckdcpcb--Example three: cloud-native relational store
The following is a sample POST request for the upgrade operation, demonstrating a request that includes inputs for the volumes and cloud parameters:
POST /context/admin/system/upgrades/upgrade HTTP/1.1
Host: organization.domain.com
Content-Type: multipart/form-data; boundary=----WebKitFormBoundaryAMpB0mfM6ckdcpcb
Content-Length: []
------WebKitFormBoundaryAMpB0mfM6ckdcpcb
Content-Disposition: form-data; name="versionManifest"
{"id":"rel_123456_4000"}
------WebKitFormBoundaryAMpB0mfM6ckdcpcb
Content-Disposition: form-data; name="licenseFile"; filename="AllUTs_AllAddOnApps.json"
Content-Type: application/json
------WebKitFormBoundaryAMpB0mfM6ckdcpcb
Content-Disposition: form-data; name="versionManifestFile"; filename=""
Content-Type: application/octet-stream
------WebKitFormBoundaryAMpB0mfM6ckdcpcb
Content-Disposition: form-data; name="updateToLatestPatch"
False
------WebKitFormBoundaryAMpB0mfM6ckdcpcb
Content-Disposition: form-data; name="volumesConfig"
{
"volumesConfig": [
{
"provisioningType": "DYNAMIC",
"component": "REALTIONAL_UPGRADE",
"size": "16Gi",
"storageClass": "tz405rmnc1",
"labels": {
"arcgis/tier": "storage",
"arcgis/app": "postgres"
}
}
]
}
------WebKitFormBoundaryAMpB0mfM6ckdcpcb
Content-Disposition: form-data; name="cloudConfig"
[
{
"name": "AWS",
"credential": {
"type": "IAM-ROLE"
},
"cloudServices": [
{
"name": "AWS RDS for PostgreSQL",
"category": "databases",
"type": "relationalStore",
"instanceProvided": true,
"usage": "DEFAULT",
"connection": {
"region": "XXXX",
"dbUri": "XXXX",
"dbReadonlyUri": "XXXX",
"dbPort": 5674,
"credential": {
"type": "databaseUser",
"databaseUsers": {
"adminUser": {
"authType": "PASSWORD",
"name": "XXXX",
"password": "XXXX"
}
}
}
}
}
]
}
]
------WebKitFormBoundaryAMpB0mfM6ckdcpcb
Content-Disposition: form-data; name="upgradeSettings"
{}
------WebKitFormBoundaryAMpB0mfM6ckdcpcb
Content-Disposition: form-data; name="f"
pjson
------WebKitFormBoundaryAMpB0mfM6ckdcpcb
Content-Disposition: form-data; name="token"
<token>
------WebKitFormBoundaryAMpB0mfM6ckdcpcb--JSON Response examples
The example below demonstrates the immediate JSON response returned by a successful upgrade request.
{
"status": {
"state": "in_progress",
"code": 1,
"messages": [
{
"message": "Starting the upgrade process from 10.9.0.505 to 10.9.0.506.",
"when": 1601404416045,
"code": 2010
}
]
}
}Once the upgrade process is complete, the JSON view of the Upgrades resource will return the full job messages of the job and success status.