Perform Upgrades and Rollbacks

To take advantage of the latest features, enhancements, and fixes in new versions of Tanzu Service Mesh, you can install upgrades on your cluster.

When an upgrade is installed on a cluster, the data plane components that run on the cluster are upgraded to the versions released within the selected Tanzu Service Mesh version.

If an upgrade fails for some reason, Tanzu Service Mesh automatically rolls back to the previous version installed on the cluster. You can also choose to roll back a cluster to the previous version manually.

Consider the following restrictions that apply to upgrades and rollbacks:

You can only upgrade from a major version to a minor or patch version released within that major version or to the next major version. An upgrade cannot skip major versions. For example, if your clusters are on version 2.0.0, you can upgrade to 2.0.1, 2.1.0, or 3.0.0, but not to 4.0.0.
You can roll back only to the version of Tanzu Service Mesh that was last installed on a cluster. For example, if version 4.0.0 was previously installed on the cluster, and you upgraded it to version 4.0.1, you can roll back to version 4.0.0, but not to 3.0.0.
The latest minor version and the latest major version can be both available to upgrade to. For example, if your cluster is on version 2.0.0, you can choose to upgrade it to 2.0.1 or to 3.0.0.

For information about the changes and fixes in a specific version of Tanzu Service Mesh, see VMware Tanzu Service Mesh Data Plane Release Notes.

Prerequisites

Get an API token and an access code to authenticate your requests to the Tanzu Service Mesh API. You must use the access code in the csp-auth-token header in your requests. For information about generating an API token and getting an access code, see Authentication with the Tanzu Service Mesh REST API.

Procedure

To get a list of the versions that are available to upgrade or roll back to, submit the following request.
```
GET https://{server_name}/tsm/v1alpha2/projects/default/clusters/{cluster_id}/apps
```
Where {cluster_id} is the identifier of your cluster in Tanzu Service Mesh. You specified an identifier for the cluster when onboarding it to Tanzu Service Mesh.
The version field at the beginning of the response contains the version of the Tanzu Service Mesh that is currently installed on the cluster. Inside availableVersions, the versions that have the installable field set to true are available for the cluster to upgrade or roll back to.

If a version is not available for the cluster, installable is set to false, and the reason field contains the reason for unavailability. Some of the reasons why a version can be unavailable for a cluster:
- Please upgrade to Kubernetes {version} or later to upgrade Tanzu Service Mesh. You cannot upgrade the cluster to a new version because the cluster uses an old version of Kubernetes. To upgrade to the new version, first upgrade the cluster to the specified version of Kubernetes or a later version.
- Please upgrade to Tanzu Service Mesh {version} to upgrade to {version}. To upgrade the cluster to the specified version, you must first upgrade it to another version, which is the next version available to upgrade to from the current version.
- Rollback to Tanzu Service Mesh {version} is not available. You cannot roll back the cluster to the specified version because it is not the version that was previously installed on the cluster.
Make note of the version that you want to upgrade or roll back the cluster to.
To install this version on the cluster, submit the following request.
```
PUT https://{server_name}/tsm/v1alpha2/projects/default/clusters/{cluster_id}/apps/{app_id}
```
Replace cluster_id with the identifier of the cluster and replace app_id with tsm.

In the request body, set version to the version that you want to install (for example, v4.0.0).
```
{
   "version":"{version}"
}
```
Note:
To install the latest available version of Tanzu Service Mesh on the cluster, set version to default.
The response contains the identifier of the installation job.
To determine whether the selected version was successfully installed, submit a GET request to https://{server_name}/tsm/v1alpha2/projects/default/clusters/{cluster_id}/apps again.
If the selected version was successfully installed on the cluster, the version field at the beginning of the response contains the version, and the state field contains Healthy.
Note:
- If state contains Installing or Upgrading, the installation is still in progress. Wait a few minutes.
- If state contains a value other than Healthy, Installing or Upgrading, the installation failed. Retry the installation by repeating step 3. If the installation still fails, contact VMware Support.
- To determine the status of the installation, you can also make a call to GET https://{server_name}/tsm/v1alpha2/projects/default/jobs/{id}. Replace {id} with the identifier of the installation job that was returned in step 3. If the installation was successful, the state field contains Completed, and the message field contains Tanzu Service Mesh upgraded or Tanzu Service Mesh rolled back.