Upgrade NGINX Service Mesh

This topic explains how to upgrade NGINX Service Mesh.

Overview

This document contains instructions for upgrading NGINX Service Mesh.

For Helm users, see how to upgrade using Helm.

For OpenShift users, upgrade will be available beginning in v1.3.

Incompatibilities between previous and current versions may require specific steps in order to upgrade properly. Be sure to read through the specific details for your target version.

In-Place Upgrade

Important:
Each release may have version-specific steps for performing a successful upgrade. If there is a dedicated entry in this document for your target version, please follow those steps instead.
Important:
If you wish to change the deployment configuration (for example, setting a new flag or changing the value of an existing flag), then you will need to follow the Manual Upgrade steps.

You can upgrade to the latest nginx-meshctl release from the version immediately before it (for example, from v1.1.0 to v1.2.0). After you have installed the latest version of nginx-meshctl, you can run:

nginx-meshctl upgrade

This will remove the older version of the NGINX Service Mesh control plane and install the latest version. All user configuration (traffic policies, mesh configuration, deploy configuration) is preserved through the upgrade. However, since the control plane is removed during an upgrade, metrics and tracing info is lost if you are not using your own Prometheus or tracing backend. New applications will not be injected during the upgrade and existing applications will not receive configuration updates. It is recommended that upgrades are only performed during a maintenance window due to the expected downtime.

Once the upgrade is complete, if your applications support rolling updates, re-roll using the following command:

kubectl rollout restart <resource type>/<resource name>

Otherwise, the application Pods need to be deleted and re-created.

Manual Upgrade

Important:
This upgrade method is the most disruptive, as it involves fully removing the existing mesh and deploying the newer version.

If breaking changes are introduced between versions, or you wish to change the deployment configuration, then a manual upgrade strategy is necessary.

Note:
Some deployment configuration fields can be updated after the mesh has already been deployed, and therefore a manual upgrade strategy is unnecessary. Those fields are discussed in the API reference guide.

Before downloading the newer version of nginx-meshctl, you will need to remove NGINX Service Mesh using your existing version of nginx-meshctl. See the following steps.

Save Custom Resources

Warning:
When you manually upgrade NGINX Service Mesh, all of your Custom Resources will be deleted. This includes TrafficSplits, TrafficTargets, RateLimits, and so on.

Before you proceed with the upgrade, run the commands shown below to back up your Custom Resources.

kubectl get trafficsplits.split.smi-spec.io -A -o yaml > trafficsplits.yaml
kubectl get traffictargets.access.smi-spec.io -A -o yaml > traffictargets.yaml
kubectl get httproutegroups.specs.smi-spec.io -A -o yaml > httproutegroups.yaml
kubectl get tcproutes.specs.smi-spec.io -A -o yaml > tcproutes.yaml
kubectl get ratelimits.specs.smi.nginx.com -A -o yaml > ratelimits.yaml
kubectl get circuitbreakers.specs.smi.nginx.com -A -o yaml > circuitbreakers.yaml

Remove NGINX Service Mesh

Remove NGINX Service Mesh using your existing version of nginx-meshctl.

nginx-meshctl remove

At this point, you can discard your old version of nginx-meshctl.

Redeploy NGINX Service Mesh

Download and install the newer version of nginx-meshctl.

Redeploy NGINX Service Mesh.

Use the backups you made earlier to recreate your custom resources:

kubectl create -f trafficsplits.yaml -f traffictargets.yaml -f httproutegroups.yaml -f tcproutes.yaml -f ratelimits.yaml -f circuitbreakers.yaml

If your applications support rolling updates, re-roll using the following command:

kubectl rollout restart <resource type>/<resource name>

Otherwise, the application Pods need to be deleted and re-created.