Upgrade Lattice

This page is rolling a running install to a new cut. Day-one install is deploy (cluster) or fleet-deploy (Fleet).

Two archives, two installers. The console does not apply binaries. You copy the new .tar.gz onto each Ubuntu VM (WinSCP from Windows) and run that archive’s installer over SSH.

Just show me the steps — copy-paste at the bottom.

Which scenario

Community is scenario 1. Paid HA without Fleet is scenario 2. Fleet does not serve DHCP: each site is still 1 or 2.

Rules that apply to every cut

Run the new archive. Not lattice-install or fleet-install already on PATH (that is the old copy). On a terminal with no flags, the wizard sees an existing install and offers Upgrade this node.

Do not downgrade. Schema only goes forward. If a cut is bad, restore from backup.

Fleet first, then rolling cluster. If you run Fleet, upgrade Fleet (and its agents) before cluster software. A newer Fleet still talks to older clusters inside the window below. Do not run a cluster newer than this Fleet.

Do not skip more than two cluster cuts under this Fleet. This Fleet is meant to manage the cluster cut named in its Downloads notes, and the two published cluster cuts before that. You may leave some sites on those older cuts while you roll others. A site older than that window: bring that cluster forward (1 or 2) until it is inside the window before you expect Search, History, and cluster pages through Fleet to work.

How to count: published cluster versions (not Fleet — the two products version independently). Example: a Fleet that names cluster 0.1.0-rc.2 still covers 0.1.0-rc.1 and the cluster cut immediately before rc.1. It does not cover anything older in one hop. If you are outside the window, upgrade those clusters first; DHCP does not need Fleet for that.

One node at a time on HA. Relays do not change. Mixed node versions during a roll are expected; finish every node.

Backup first. Cluster: paid Cluster backups, or pg_dump on Community. Fleet: pg_dump of the Fleet database and /etc/lattice/fleet.env (sign-in token and encryption key). Without those, you re-enroll every site after a Fleet rebuild.

Air-gap cluster: lattice-install --mode save-bundle on a connected host, copy the image tar with the release, --bundle on the dark site.

1. Cluster only

One Ubuntu VM. Console and DHCP on this box blip (~1–2 minutes). Leases stay in Postgres; clients retry. There is no other node to fail over to.

From a Windows PC: download from Downloads, copy the .tar.gz to /tmp with WinSCP (or PowerShell scp), SSH in:

sudo tar -C /tmp -xzf /tmp/lattice-*-linux-amd64.tar.gz
sudo /tmp/lattice-*-linux-amd64/scripts/lattice-install --mode upgrade

Prove: console opens; lattice-dhcptest (or a real client) still gets an Ack. Details: deploy. Console Help → Upgrade this node has the same two lines.

2. HA cluster

Three Ubuntu VMs, one site, one VIP (ha). Order is replica, replica, then the current leader. The other nodes keep serving. No planned cluster-wide outage if you follow that order.

1. Backup (Cluster UI, or off-box pg_dump).
2. On a replica (not the current Postgres leader), the same two lines as §1.
3. The other replica.
4. The leader. The installer drains this node from the VIP and switchovers if it is the writer (--force if switchover stalls).
5. Extra dhcp-only / dns-only leaves: same command on each, after the trio. Only that leaf restarts.

Prove: Cluster → Nodes versions match; relays still Ack through the VIP. Mixed versions for a few minutes are expected.

3. Fleet + clusters

Fleet is a manager of managers. A Fleet blip does not stop DHCP at the sites. Cluster software is a different archive.

Order:

1. Window. If any site is more than two cluster cuts behind the Fleet you are installing, do §1 or §2 on those sites first.
2. This Fleet VM. New Fleet archive:

sudo tar -C /tmp -xzf /tmp/lattice-fleet-*-linux-amd64.tar.gz
sudo /tmp/lattice-fleet-*-linux-amd64/scripts/fleet-install --mode upgrade

Console blips; agents reconnect. DHCP is not on this path.

3. Agents, rolling, same two lines on each cluster host (same Fleet archive, not the cluster tarball). Existing agent identity is kept. Overview tiles show agent … — upgrade until that host matches this Fleet.
4. Clusters, site by site: §1 or §2 on that site. Finish and prove one site (Search a known MAC, History, a cluster page through Fleet) before the next. Stay inside the two-cut window.

Do not upgrade every cluster in parallel if you want a rollback window. Details: fleet-deploy.

4. HA Fleet + HA clusters

Two Fleet VMs behind a load balancer (fleet-ha) plus three-node clusters. Same window rule as §3.

Order:

1. Window — same as §3 step 1.
2. Fleet, one node at a time. Same two Fleet lines on the first Fleet VM; wait until /readyz is good and the console works through the load balancer; then the other Fleet VM. The node you are not touching keeps the console. DHCP is not on this path. Agents use the load-balancer hostname, not a node IP.
3. Agents, rolling, as in §3.
4. Each HA cluster, one site at a time: replica, replica, leader (§2). Finish the site (Search / History / a cluster page through Fleet) before the next site.

Do not upgrade both Fleet nodes at once. Do not start a second cluster roll until the first site is back on the VIP and leasing.

If something is wrong

• Do not install an older archive over a newer one.
• Restore from the backup you took. Cluster restore is onto a new cluster, then cut relays (ha). Fleet restore needs the dump and fleet.env.
• Support bundle: cluster Help → Collect support bundle, or lattice diag; Fleet Settings. Email [email protected]. Do not paste tokens. REPORTING.md.

Just the steps

From a Windows PC: copy the new .tar.gz to /tmp (WinSCP). SSH. Do not skip more than two cluster cuts under this Fleet.

Cluster node (single VM, or one HA node — replica, replica, leader):

sudo tar -C /tmp -xzf /tmp/lattice-*-linux-amd64.tar.gz
sudo /tmp/lattice-*-linux-amd64/scripts/lattice-install --mode upgrade

Fleet node or cluster agent:

sudo tar -C /tmp -xzf /tmp/lattice-fleet-*-linux-amd64.tar.gz
sudo /tmp/lattice-fleet-*-linux-amd64/scripts/fleet-install --mode upgrade

With Fleet: Fleet VMs first (HA: one node at a time) → agents rolling → clusters site by site. Without Fleet: cluster only (§1 or §2).

Also: windows-admin · deploy · ha · fleet-deploy · fleet-ha