Architecture Overview

FlexFS is a distributed network filesystem that provides POSIX-compatible access to cloud object storage. Its architecture separates metadata (file names, permissions, directory structure) from block data (file contents), routing each through purpose-built paths optimized for their access patterns.

High-level component diagram

Design principles

Metadata and data are separated. Metadata operations (lookup, create, rename, chmod, lock) flow through the metadata server over a binary RPC protocol. Block data (read, write) flows directly between mount clients and object storage over HTTPS REST — or optionally through proxy servers. This separation means that the metadata server is never a throughput bottleneck for large file I/O.

Blocks are the unit of storage. Every file is divided into fixed-size blocks (configurable from 256 KiB to 8 MiB per volume, defaulting to 4 MiB). Blocks are individually compressed, optionally encrypted, and stored as objects in a cloud bucket. Each block is identified by its inode number, block index, and a timestamp-based key.

Caching is multi-tiered. Mount clients maintain an in-memory LRU cache (L1), an optional on-disk cache with writeback support (L2), and can route reads and writes through Enterprise proxy groups that act as a shared caching layer (L3).

Encryption keys never leave the client. When end-to-end encryption is enabled (Enterprise), the mount client encrypts and decrypts all block data and metadata field values locally. The metadata server, proxy servers, and object storage never see plaintext content.

The 14 binaries

FlexFS ships as 14 standalone Linux binaries. They fall into three categories:

Category	Binaries	Role
Servers	admin.flexfs, free.flexfs, meta.flexfs, proxy.flexfs, stat.flexfs	Long-running services managed by systemd
Clients / Drivers	mount.flexfs, csi.flexfs	Mount the filesystem (FUSE mount client, Kubernetes CSI driver)
Utilities	configure.flexfs, manage.flexfs, analyze.flexfs, dedup.flexfs, find.flexfs, update.flexfs, license.flexfs	Administration, analysis, and maintenance tools

All binaries are statically linked and require no runtime dependencies beyond a Linux kernel with FUSE3 support (for mount.flexfs) or systemd (for servers).

See Component Roles for detailed descriptions of each binary.

Protocol summary

Path	Protocol	Transport	Purpose
mount.flexfs to meta.flexfs	Binary RPC	TCP + TLS	All metadata operations (lookup, create, setattr, lock, readdir, etc.)
mount.flexfs to object storage	HTTPS REST	TCP + TLS	Block read/write/delete (S3, GCS, Azure, OCI native APIs)
mount.flexfs to proxy.flexfs	HTTPS REST	TCP + TLS	Block read/write through proxy cache
Utilities to meta.flexfs	HTTPS REST	TCP + TLS	Analysis queries, deduplication, search
admin.flexfs REST API	HTTPS REST	TCP + TLS	Configuration management, deploy endpoints, volume settings
meta.flexfs to stat.flexfs	HTTPS REST	TCP + TLS	Usage metering (Enterprise)

Two editions

FlexFS is available in two editions sharing the same core architecture:

• Community Edition uses free.flexfs as its administration server. It supports a single volume with no end-to-end encryption, no proxy groups, and no dynamic Kubernetes provisioning. All other features — including local on-disk writeback caching, POSIX compliance, and all four storage backends — are fully available.

• Enterprise Edition uses admin.flexfs and configure.flexfs for multi-volume, multi-account management. It adds end-to-end encryption, proxy groups, volume quotas, retention policies, dynamic CSI provisioning, and the statistics server for billing and metering.

Both editions use the same mount.flexfs, meta.flexfs, and utility binaries.