Upgrade Guide
This page explains how Meshery’s components version and upgrade in relation to one another. For the hands-on procedure, follow the Upgrading Meshery guide.
Upgrading Meshery Server, Adapters, and UI
Various components of Meshery will need to be upgraded as new releases become available. Meshery is comprised of a number of components including a server, adapters, UI, and CLI. As an application, Meshery is a composition of different functional components.
Figure: Meshery components
Some of the components must be upgraded simultaneously, while others may be upgraded independently. The following table depicts components, their versions, and deployment units (deployment groups).
Versioning of Meshery Components
| Components | Sub-component | Considering or Updating |
|---|---|---|
| Meshery Adapters | Any and All Adapters | Docker Deployment: Watchtower updates this component in accordance with the user’s release channel subscription. |
| Meshery Server | Meshery UI | Manages lifecycle of Meshery Operator; Adapters, UI, Load Generators, Database. Docker Deployment: Watchtower updates this component in accordance with the user’s release channel subscription. |
| Load Generators | ||
| Database | ||
| Meshery Operator | MeshSync | Meshery Operator manages the lifecycle of this component and its sub-components. |
| Meshery Broker | Meshery Operator manages the lifecycle of this event bus component. | |
| `mesheryctl` | mesheryctl manages the lifecycle of Meshery Server.
| |
| Remote Providers | Meshery Cloud | Process Extension: Integrators manage the lifecycle of their Remote Providers. The process is unique per provider. |
| Meshery Extensions | Static Extension: Integrators manage the lifecycle of their Meshery Extensions. The process is unique per provider. |
Sub-components deploy as a unit; however, they do not share the same version number.
How Meshery Server manages Meshery Operator
Meshery Server owns the lifecycle of Meshery Operator on every managed cluster. Understanding this relationship explains what upgrades automatically and what you should — and should not — touch by hand.
Installation. When Meshery Server connects to a Kubernetes cluster (in
operator deployment mode), it installs the meshery-operator Helm chart from
meshery.io/charts into the meshery namespace.
The chart version it requests matches the Meshery Server release version —
each Server release snapshots the operator chart (and the operator version
pinned inside it) as of that release.
Upgrades. Upgrading Meshery Server is what upgrades the Operator: on
(re)connection, the Server re-applies the operator chart at its own (new)
version. That helm upgrade triggers the chart’s CRD update Job — a
pre-upgrade hook that server-side-applies the current Broker and MeshSync
CRD schemas (Helm alone never updates CRDs on upgrade) — and rolls the
Operator Deployment to the operator image pinned in the chart. The Operator
then reconciles MeshSync and the Broker.
Reconciliation. The Server periodically re-applies the operator chart if the Operator is missing or unhealthy. Two practical consequences:
- Manual operator changes are temporary. A hand-run
helm upgrade meshery-operator --version <x>or an edited image tag on a Server-managed cluster will be reverted to the Server’s pinned chart version by the next reconciliation. Standalone/manual operator installs are only durable on clusters that Meshery Server does not manage. - Operator versions are pinned, not floating. The operator image is a
fixed version per chart release (no
stable-latestdrift): an Operator pod restart never silently changes the operator version. Upgrades happen only when the chart content changes — that is, when you upgrade Meshery Server.
CRDs persist. The brokers.meshery.io and meshsyncs.meshery.io CRDs
(and your Broker/MeshSync objects) deliberately survive operator
uninstalls and Helm release deletion. Removing them — and with them every
custom resource of those types — is an explicit, manual step:
kubectl delete crd brokers.meshery.io meshsyncs.meshery.io.
You can toggle operator deployment per cluster in Meshery UI under Settings, or avoid deploying the operator entirely by choosing MeshSync’s embedded mode for the connection. See Meshery Operator for the architecture.
Meshery Docker Deployments
In order to pull the latest images for Meshery Server, Adapters, and UI, execute the following command:
mesheryctl system update
If you wish to update a running Meshery deployment with the images you just pulled, you’ll also have to execute:
mesheryctl system restart
Meshery Kubernetes Deployments
Upgrade with Helm, pinning an explicit chart version and using the upgrade-friendly probe values:
helm upgrade meshery meshery/meshery --namespace meshery --version <target-version> -f values-upgrade.yaml --wait
The Upgrading Meshery guide covers the full procedure, verification steps, and rollback; the Operational Readiness Checklist covers production upgrade strategy.
Upgrading Meshery CLI
The Meshery command-line client, mesheryctl, is available in different package managers. Use the instructions relevant to your environment.
Upgrading mesheryctl using Homebrew
To upgrade `mesheryctl`, execute the following command:
brew upgrade mesheryctl
Upgrading mesheryctl using Bash
Upgrade mesheryctl and run Meshery on Mac or Linux with this script:
curl -L https://meshery.io/install | DEPLOY_MESHERY=false bash -
Upgrading mesheryctl using Scoop
To upgrade mesheryctl, execute the following command:
scoop update mesheryctl