Upgrade a self-hosted data plane
The order and the rules for keeping a self-hosted data plane current: what upgrades first, what keeps working while the data plane lags a release, how to read the release notes before upgrading, and when a patch is worth taking off-schedule. The command itself is covered by the tare upgrade reference; this page is the part around the command.
The order: the management plane leads, the data plane follows
The Tetrate-hosted management plane is always on the current release; Tetrate upgrades it as part of the weekly cut. A data plane is therefore never newer than its management plane, and the operator's half of every upgrade is the data plane and the tare CLI, whose version matches the release tag.
Because the management plane is always current, "upgrade the management plane first" is not a step an operator performs: it has already happened by the time a release appears on the release notes page. The operator's decision is only when the data plane follows.
Nothing forces an immediate upgrade
Each release is supported for six months from the day it ships, and a supported data plane keeps working against the current management plane for that whole window. The end-of-support date for every release is on its release notes entry and on Release compatibility.
Fixes are not backported: getting a fix means upgrading to a release that contains it. That, rather than compatibility, is what usually decides the timing.
What lags while the data plane is behind
A management plane feature can need a newer data plane. The feature stays off for that data plane until it is upgraded; nothing breaks, and the rest of the release keeps working. Each such feature names its version in the release notes ("available once the data plane is on X or later"), and the Minimum data plane column on Release compatibility carries the highest such version per release: a data plane at or above it has every feature of that release.
Read the release before upgrading
Every entry on the release notes page carries an Upgrade and rollback block. Four things in it decide what the upgrade needs:
- The breaking-change line. When operator action is required before upgrading, the entry carries a warning naming the action. A release can also carry a breaking change that requires no action; the line says which.
- The traffic line. Most upgrades roll through without dropping traffic. When a release does not, the line says so, and a maintenance window is needed.
- The rollback line. Rollback to the previous release is unconditional unless the entry carries a rollback condition; a conditional rollback names exactly what stops working after rolling back.
- The Kubernetes range. The range is fixed per release and enforced at install and upgrade time, and managed Kubernetes cannot be downgraded in place, so a cluster below a new release's floor must be recreated before the data plane can follow. The range per release is on Release compatibility.
Deprecations is the fifth check, on a slower clock: anything deprecated keeps working for twelve months, and the running list shows what is on the clock and its replacement.
When to take a patch off-schedule
Releases are cut every Wednesday, and a patch ships when it is needed rather than waiting for the next cut. A patch that carries only security updates, the shape v0.2.1 had, changes no source, API, configuration, or behavior: it rolls through without dropping traffic and rolls back unconditionally, so the cost of taking it immediately is low and the reason it shipped early is the reason not to wait.
Run the upgrade
- tare CLI path:
tare upgradewith the data plane's identity file. The command upgrades atomically and rolls back on failure; flags, the doctor rows, and the drain behavior are in the tare upgrade reference. - Helm and GitOps paths: the upgrade is a re-render at the new tag through the same path that installed: pull the new chart version for a Helm install, or re-render and commit the manifests for a GitOps install, CRDs first where they sync as their own Application.
Afterward, tare doctor confirms component state, and the data plane's reported version appears in the Admin Console data plane list's Version column. See Check the management plane version and release notes.
Rolling back
Rollback to the previous release is unconditional unless that release's notes carry a rollback condition. A conditional rollback never blocks the rollback itself: the condition names what stops working until the data plane is rolled forward again, so the decision can be made with the blast radius known.
Where to go next