Understanding updates and upgrades

Once you've deployed ArcGIS Enterprise on Kubernetes, you can update or upgrade the software to provide your organization with the latest available ArcGIS Enterprise enhancements and features, ensuring its security, reliability, and performance.

The following describes the differences between updates and upgrades:

  • An update is narrowly focused and may address performance, security, or functionality issues and bugs. Updates do not introduce new functionality or change the look and feel of the software. For example, an update moves the software from version 10.9.0.300 to version 10.9.0.412.
  • An upgrade is a new version of the software, with new features, improved functionality, and sometimes a different look and feel. For example, an upgrade moves the software from version 10.9.0 to version 10.9.1.

Upgrade and update requirements

Before applying an update or upgrade, consider the following requirements:

Apply or remove an update

An administrator can apply updates and upgrades using ArcGIS Enterprise Manager or ArcGIS Enterprise Administrator API. In ArcGIS Enterprise Manager, this is done from the Software updates page.

  • When a new version of ArcGIS Enterprise on Kubernetes is released, the option to upgrade appears at the top of the page.
  • When software updates are available, they appear on the lower part of the page.

The Software updates page contains the following tabs that represent the status of new updates, those that have been applied, and the history of those that have been applied or rolled back:

  • Updates—Newly available updates that aren't yet applied to your organization.
  • Applied—Updates your organization has applied. You can manually remove an update on this tab.
  • History—Software update opportunities your organization has taken, including applied or rolled-back patches and applied upgrades.

Read-only mode

When an update or upgrade is in progress, ArcGIS Enterprise is set to read-only mode. In this mode, your organization members can view content, users and groups, and settings but cannot modify them. During this time, a notification appears in the top banner of ArcGIS Enterprise Manager to inform the organization.

When an upgrade or update is complete, read-only mode is turned off and normal operations can resume in the organization.

Update and upgrade processes

The update and upgrade processes are integrated into the software. You can access enhancements and new features without installing additional software. Administrators can use ArcGIS Enterprise Manager or ArcGIS Enterprise Administrator API to determine when an update or upgrade is available.

When an update is available, it is represented as a new container image or set of images and is pushed to the container registry host (for example, docker.io). ArcGIS Enterprise Administrator API uses a well-known URL to identify an Esri published version manifest document to determine whether an update is available. By identifying the manifest, an upgrade strategy is developed and the option to update or upgrade becomes available.

Updates and upgrades generally follow the two patterns described below.

Blue-green

When applicable, new Kubernetes deployments are started using the new container images to upgrade and migrate the underlying data. Secondary data store instances or other replicas are then added to the data store. Once the new data store is deemed healthy, the old data store is shut down, leaving only a healthy instance of the new data store. An example of when this strategy might be used is updating hosted data stores.

Rolling

As new pods that are enabled by new container images are deployed, the old pods are shut down in a rolling manner. This process minimizes downtime. An example of when this strategy might be used is updating GIS services.

Troubleshoot

If you encounter a failure while performing an update or upgrade, use the following approaches to troubleshoot and resolve issues.

  • When conducting an update or upgrade, view the History tab to identify if an error occurred. As status messages are returned, the option to view logs is also available and can provide insight into whether action is required. It is recommended that you filter the log level to severe to determine specific logs during the update time period.
  • If you encounter a message about a deployment failing to refresh for a particular deployment, do the following:
    • On the Logs page in ArcGIS Enterprise Manager, click Manage columns.
    • Enable the Stack trace option to make it a visible column.
    • If you encounter a time-out error in the stack trace, such as: Timing out patch operation, this may be because the start up time for one or more containers has exceed expected wait times and time out, causing the upgrade to fail. To address this issue, increase the value for containerStartUpTimeoutSeconds in ArcGIS Enterprise Administrator API at System > Properties. The new value must be greater than the default value of 1800 seconds. Once you've increased the value, run the upgrade again.
  • If members cannot access the organization after an upgrade, for example, administrators or other member accounts cannot sign in to ArcGIS Enterprise Manager or the portal, it may be due to an issue with the relational data store. If this is the case, do the following:
    • In Lens or another Kubernetes cluster monitoring tool, locate the arcgis-relational-store pods. If one or more of these pods are not running, restore the system from your backup.