Upgrades

FlexFS provides several upgrade paths depending on which components you are upgrading and your tolerance for downtime.

Upgrade overview

Component	Upgrade method	Downtime
Servers (meta, proxy, admin)	`manage.flexfs upgrade`	Brief restart per service
Mount clients	Auto-update (automatic) or `update.flexfs` (manual)	Live FUSE session handoff
CSI driver	Helm upgrade or manifest reapply	Controller pod restarts; node pods use `OnDelete` (manual restart)

Server upgrades with manage.flexfs

The manage.flexfs upgrade command performs a complete upgrade cycle: clean state, download new binaries, install them, and restart the services those binaries belong to.

sudo manage.flexfs upgrade

This will:

Clean runtime state (flexFS temporary files)
Download the latest binaries for all installed flexFS components from get.flexfs.io
Install them to /sbin/
Stop the services whose binaries were upgraded
Start those same services again

Only the services belonging to an upgraded binary are cycled, and only where a systemd unit for them exists. With no binary names given, every flexFS binary in /sbin is upgraded, so a bare upgrade restarts every installed service.

Specifying a version

sudo manage.flexfs upgrade --version v1.9.x

Upgrading specific binaries

sudo manage.flexfs upgrade meta proxy

This downloads and upgrades only the specified binaries, and restarts only the services among them — here meta and proxy. Services whose binaries were not upgraded keep running untouched.

Specifying architecture

sudo manage.flexfs upgrade --arch aarch64

By default, the host architecture is detected automatically.

Vacuum journal logs

Add --vacuum to rotate and vacuum the systemd journal as part of the upgrade. This runs journalctl --rotate followed by journalctl --vacuum-time=1s, which deletes essentially all archived journal data on the whole host, not just flexFS entries — including the logs from the upgrade’s own pre-restart phase. Use it only when journal disk pressure is the reason for the upgrade:

sudo manage.flexfs upgrade --vacuum

Upgrade and deploy in one step

Add --deploy to deploy mount.flexfs to the admin server’s channels immediately after the upgrade completes — equivalent to running manage.flexfs upgrade followed by manage.flexfs deploy:

sudo manage.flexfs upgrade --deploy

The deploy step reuses the upgrade’s --version, so the deployed mount client matches the version you just upgraded to. Use --channel and --adminPath to control the deploy step:

sudo manage.flexfs upgrade --deploy --channel staging

Downloading binaries separately

If you prefer more control, use manage.flexfs download to download binaries without installing or restarting:

# Download to /tmp
sudo manage.flexfs download meta proxy mount

# Download and install to /sbin
sudo manage.flexfs download meta proxy mount --install

Flag	Description
`--arch`	Architecture: `amd64` or `aarch64`.
`--install`	Install binaries to `/sbin/` after downloading.
`--version`	Version branch to download (e.g., `v1.9.x`).

See the manage.flexfs CLI reference for types and defaults.

Deploying mount client updates

The manage.flexfs deploy command downloads the latest mount.flexfs binary and places it in the admin server’s deploy directory, making it available for auto-update by mount clients.

sudo manage.flexfs deploy

Flag	Description
`--adminPath`	Path to the admin folder.
`--channel`	Deployment channel: `staging`, `production`, or `all`.
`--version`	Version branch to deploy.

See the manage.flexfs CLI reference for types and defaults.

Channels

The deploy directory has two channels:

Channel	Description
`staging`	Mount clients with `--staging` flag pull from this channel. Use for testing updates before wide rollout.
`production`	Default channel for all mount clients.

Deploy flow:

# Deploy to staging first
sudo manage.flexfs deploy --channel staging

# Test with staging mounts, then promote to production
sudo manage.flexfs deploy --channel production

Or deploy to both at once:

sudo manage.flexfs deploy --channel all

Mount client auto-update

Mount clients automatically check the admin server for new versions and update themselves. When an update is available:

The mount client downloads the new mount.flexfs binary from the admin server’s deploy endpoint.
It performs a FUSE session handoff — the new binary takes over the existing FUSE mount without interrupting running applications.
The old process exits cleanly.

Controlling auto-update

Flag	Effect
`--noRemount`	Download the update but do not perform the FUSE session handoff. The update takes effect on next manual mount.
`--noUpdate`	Disable auto-update entirely.
`--staging`	Pull updates from the staging channel instead of production.

See the mount.flexfs CLI reference for the authoritative entries, including types and defaults.

Manual mount client update

Use update.flexfs to manually update the mount client binary:

sudo update.flexfs

This downloads the latest version and replaces the binary at /sbin/mount.flexfs, then cleanly unmounts any active mounts. Add --mount to remount fstab entries afterward, or --force to force the update on mounts that are still in use.

Version compatibility

FlexFS maintains backward compatibility within a major version series. A v1.9.x mount client can connect to v1.9.x servers without issues. When upgrading, update servers first, then mount clients.

Optional protocol capabilities — such as coordinated concurrent I/O (exact byte-range locks and cross-mount-safe appends) and serialized append grants — are negotiated at connection time: the feature is used only when both the mount client and the metadata server support it, and otherwise both sides transparently fall back to the previous behavior. Because of this, upgrade the metadata server before the mount clients so the capability is available as soon as clients advertise it. Mixed-version fleets remain fully interoperable during the rollout.

Service ordering

When manage.flexfs starts services, it follows the correct dependency order:

Error server (error.flexfs, if installed) — an internal service that starts first so it is listening before the others report to it
Statistics server (stat.flexfs, if installed)
Admin server (admin.flexfs, if installed)
Free server (free.flexfs, if installed)
Proxy server (proxy.flexfs, if installed)
Metadata server (meta.flexfs)

When stopping, the order is reversed.