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 download from the admin server (manual)	Live FUSE session handoff (automatic); remount (manual)
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 rm -f /sbin/update.flexfs
sudo manage.flexfs upgrade

The first command removes /sbin/update.flexfs if present. On a host where that file exists, manage.flexfs upgrade can fail trying to download it and stop before installing anything.

The upgrade will:

1. Clean runtime state (flexFS temporary files)
2. Download binaries for all installed flexFS components from the download server set in the manage.flexfs credentials file, or get.flexfs.io by default: the newest release on the running manage.flexfs build’s version branch, or the version given with --version
3. Install them to /sbin/
4. Stop the services whose binaries were upgraded
5. 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. A server run directly with its start subcommand rather than as a systemd service is not restarted; restart it yourself to run the new binary.

Specifying a version

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

--version accepts a version branch (e.g. v1.9.x, the newest release on that branch) or an exact release (e.g. v1.9.1).

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. On a host without an admin server, such as a Community installation, the deploy step does nothing. 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 (e.g., v1.9.x) or exact release (e.g., v1.9.1) to download. Defaults to the build’s version branch.

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. Run it with sudo when the admin server runs as root, as on an installer-built host; for an admin server that runs as another user, run it as that user. On a host without an admin server, such as a Community installation, it does nothing.

sudo manage.flexfs deploy

Flag	Description
--adminPath	Path to the admin folder. Defaults to ~/.flexfs/admin in the home folder of the user running the command (/root/.flexfs/admin under sudo).
--channel	Deployment channel: staging, production, or all.
--version	Version branch (e.g., v1.9.x) or exact release (e.g., v1.9.1) to deploy. Defaults to the build’s version branch.

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:

1. The mount client downloads the new mount.flexfs binary from the admin server’s deploy endpoint.
2. It performs a FUSE session handoff — the new binary takes over the existing FUSE mount without interrupting running applications.
3. 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.

Note

Auto-update is disabled entirely only by --noUpdate. Under --foreground (and --noRemount) the client still downloads and installs the new binary, but skips the FUSE session handoff, so the update takes effect on the next mount rather than in place.

Manual mount client update

Download the latest mount client from the admin server, then remount each flexFS mount so it runs the new binary:

sudo curl -fksSL https://<admin-addr>/deploy/production/v1.9.x/linux/amd64/mount.flexfs -o /sbin/mount.flexfs.new
sudo chmod 755 /sbin/mount.flexfs.new
sudo mv -f /sbin/mount.flexfs.new /sbin/mount.flexfs
sudo umount /mnt/flexfs && sudo mount /mnt/flexfs

Use aarch64 in place of amd64 on ARM hosts, and staging in place of production for mounts started with --staging. Remounting with mount requires an /etc/fstab entry; restart other mounts with the mount.flexfs start command that created them. Downloading to a separate file and renaming it replaces the binary safely while mounts are running it. Mounts keep running the previous binary until they are remounted, and a mount that is in use cannot be unmounted until the processes using it exit.

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. Mount clients older than v1.9.51 can report “directory not empty” for an rmdir or rename that newer clients report as “is a directory”, “not a directory”, or “invalid argument” (see this troubleshooting entry).

Optional protocol capabilities — such as coordinated concurrent I/O (exact byte-range locks and cross-mount-safe appends), serialized append grants, and prompt hand-over of append turns between mounts — 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 operate without it. 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:

1. Error server (error.flexfs, if installed) — an internal service that starts first so it is listening before the others report to it
2. Statistics server (stat.flexfs, if installed)
3. AWS Marketplace server (aws.flexfs, if installed) — an internal service that depends on the statistics server
4. Admin server (admin.flexfs, if installed)
5. Free server (free.flexfs, if installed)
6. Proxy server (proxy.flexfs, if installed)
7. Metadata server (meta.flexfs)

When stopping, the order is reversed.

Next steps

• Backup and recovery
• Performance tuning
• Auto-update details