Upgrading Meshery

This guide walks through upgrading a running Meshery deployment. Meshery is a composition of components that upgrade in a specific order: the CLI first, the Server second, and the components on managed clusters — Meshery Operator, MeshSync, and Broker — automatically, driven by the Server. You do not upgrade the Operator by hand.

For background on which components version together, see the Upgrade Guide. For production practices (pinned versions, upgrade-friendly probes, rollback rehearsal), see the Operational Readiness Checklist.

Before you begin

• Note your release channel (stable for production; edge for testing).
• Record current versions so you can verify the upgrade:

mesheryctl version
kubectl -n meshery get deploy meshery-operator \
  -o jsonpath='{.spec.template.spec.containers[0].image}{"\n"}'

Step 1: Upgrade mesheryctl

Use the package manager you installed with:

brew upgrade mesheryctl        # Homebrew
scoop update mesheryctl        # Scoop
curl -L https://meshery.io/install | DEPLOY_MESHERY=false bash -   # Bash

Step 2: Upgrade Meshery Server

Docker deployments

mesheryctl system update    # pull latest images per your release channel
mesheryctl system restart   # apply them to the running deployment

Kubernetes deployments (Helm)

Pin an explicit chart version rather than tracking latest, and use the upgrade-friendly probe values so Server pods are not killed while reloading capabilities:

helm repo update meshery
helm upgrade meshery meshery/meshery --namespace meshery \
  --version <target-version> \
  -f values-upgrade.yaml \
  --wait --timeout 10m

Keep your copy of values-upgrade.yaml version-controlled alongside your own values.

Step 3: Managed-cluster components upgrade themselves

When the upgraded Meshery Server (re)connects to a managed cluster, it re-applies the meshery-operator Helm chart at the chart version matching the Server release. That single helm upgrade, performed by the Server:

1. runs the chart’s CRD update Job, which server-side-applies the current Broker and MeshSync CRD schemas (Helm alone never updates CRDs on upgrade — the Job is what delivers schema changes to live clusters);
2. rolls the Operator Deployment to the operator image version pinned in that chart;
3. the Operator then reconciles MeshSync and Broker to their expected versions and configuration.

No action is required on managed clusters. See How Meshery Server manages Meshery Operator for the mechanics and caveats.

Step 4: Verify

# Server and components
mesheryctl system status

# Operator image now matches the release bundled with your Server version
kubectl -n meshery get deploy meshery-operator \
  -o jsonpath='{.spec.template.spec.containers[0].image}{"\n"}'

# CRDs are current (v1alpha2 storage) and healthy
kubectl get crds brokers.meshery.io meshsyncs.meshery.io

# Broker and MeshSync are reconciled and ready
kubectl -n meshery get brokers,meshsyncs
kubectl -n meshery get statefulset/meshery-nats deployment/meshery-meshsync

In Meshery UI, confirm the cluster connection shows the Operator, MeshSync, and Broker as connected under Settings → Environment.

Rolling back

helm rollback meshery --namespace meshery    # Kubernetes deployments

Rolling back the Server is low-risk for data: durable state lives with your Remote Provider, and the local database is a rebuildable cache. Two notes:

• The Operator follows the Server: after a rollback, the Server re-applies the older operator chart on managed clusters.
• CRD schemas are not rolled back by helm rollback directly. When the rolled-back Server reconnects to managed clusters, it re-applies the older operator chart as a Helm upgrade, and that chart’s CRD update Job re-applies the older schemas. Stored objects remain readable throughout, because served versions stay identical across current schema revisions.