Filesystem semantics
Documentation home · CSI sessions · Durable handles
Use these volumes for ordinary shared content, uploads and rename-based publication. The driver provides explicit coordinated operations, not general POSIX/database compatibility. Access mode and replica count are independent: RWX/RWO chooses client ownership, while replicas choose storage quorum.
File semantics
| Behaviour | Contract |
|---|---|
| Permissions, ownership | Replicated basic 0777 mode, UID and GID; Linux default_permissions enforces each application's access. Backing files remain private 0600/0700 worker files. Root directory initially belongs to root with mode 0755. Initialize ownership before dropping application privileges. |
| umask | Kernel creation mask is respected. Special mode bits, ACLs and special files are unsupported. |
| Nonroot and fsGroup | CSIDriver.fsGroupPolicy: None; no automatic recursive ownership changes. Initialize explicit shared UID/GID/modes before dropping privileges. A supplemental fsGroup can participate in normal Linux permission checks, but does not change preexisting shared ownership. |
| Timestamps | Replicated nanosecond mtime/ctime and explicit atime/mtime updates. Reads use noatime semantics. Rename updates ctime and parent times, preserving file mtime. |
| Rename | Ordered atomic rename/replacement across mounts; existing open destination handles retain the replaced object. renameat2 flags are rejected. |
| Open/unlink | Stable object IDs and quorum-ordered 90-second handle leases, renewed every 20 seconds, protect renamed/unlinked files across coordinator changes. The final committed handle/namespace reference removal reclaims data; expired handles return ESTALE. Isolation beyond a lease does not promise descriptor survival. See handle lifetime. |
| Truncate | Ordered grow/shrink; holes read as zero. O_TRUNC is a replicated mutation. |
| Append | Each FUSE write on O_APPEND selects EOF atomically at the coordinator. A large user write split into several FUSE requests is several ordered writes, not an atomic multi-request record. FD position after concurrent remote appends is kernel-local; applications requiring the global append offset are excluded. |
| Sparse files | Offset writes and truncate preserve holes. Checkpoints transfer allocated extents rather than logical zero ranges; backing filesystems must implement SEEK_DATA/SEEK_HOLE. Hole punching/fallocate is unsupported. |
| Directory iteration | Coherent sorted snapshot per directory stream; up to 4096 entries. Changes after opening the stream require a new enumeration. No snapshot across separate directory streams is promised. |
| Links | Regular-file hard links share stable inode identity. UTF-8 symlink targets are inert replicated metadata interpreted by the workload kernel; atomic symlink replacement supports publication. Workers never follow a target through their backing filesystem. Directory/symlink hard links and cross-volume links are rejected. |
| xattrs | All xattr operations explicitly return EOPNOTSUPP. |
| Locks | Both POSIX record locks and flock explicitly return EOPNOTSUPP, with FUSE forwarding enabled. Local-only lock success would be incorrect for RWX. |
| mmap | Shared mmap returns ENODEV/EOPNOTSUPP with direct I/O and no direct-I/O mmap capability. File-backed databases, executable mappings and applications requiring locks/mmap are excluded. Private copied mappings are not a shared-memory coherence promise. |
| Cache coherence | Direct I/O; zero attribute, entry and negative-entry timeouts. A completed remote operation is visible to a subsequent operation on another mount after a fresh quorum read barrier. Concurrent overlapping writes are ordered per protocol request; a multi-request read is not a transaction snapshot. |
| fsync/flush | Every acknowledged mutation is persisted in a majority's Raft journals and applied by the serving coordinator. fsync verifies current authority and syncs its local file. It does not wait for every follower's materialization. Flush reports remote errors. Hardware/storage must honor fsync. |
SQLite, other file-backed database engines, distributed advisory locking, shared mmap, xattr-dependent programs and general POSIX compliance are not claimed. Atomic rename is appropriate for publishing complete files. Replication is not a backup and does not resolve application-level concurrent-edit conflicts.
Visibility and application coordination
A completed mutation is visible to a later operation after the fresh quorum/read barrier. Separate calls do not form a transaction; two applications editing one file still need their own conflict/serialization policy. Large writes can split into multiple ordered FUSE requests. Atomic rename is useful for publishing a complete new file; it is not a distributed lock or a cross-volume operation.
Read-only Pod publication is supported on the bind mount, but ReadOnlyMany is
not an accepted provisioning capability. Use the supported RWX/RWO claim mode
and a read-only application mount when appropriate.
Retry outcomes
The client keeps an immutable serialized request and expiry-bound replay ID.
Every operation has a 15-second total budget and three-second transport attempts.
A timeout/error after submission can follow commitment. Never assume it is safe
to repeat a non-idempotent application operation under a new ID. Expired IDs and
expired descriptors return ESTALE. See replication.
Lifetime and reclamation
Handles have quorum-ordered 90-second leases and renew every 20 seconds. An unlinked/replaced regular file remains while a durable handle or namespace hardlink references it. Ordered final close, expiry or unlink removes the last reference and permits reclamation. Lack of quorum prevents independent wall-clock deletion by a minority. A long pause or clock jump can expire an otherwise live descriptor; normal reopen/remount rules still apply.
Historical pre-lease unlink retention is replayed according to its original command semantics before current ordered maintenance reclaims obsolete objects. Mixed-version active mounts and format downgrades are unsupported.
Implementation ceilings
| Bound | Current value / interpretation |
|---|---|
| Protocol file data | 1 MiB per request. |
| Logical file length | 1 TiB encoded maximum, not a supported-capacity promise. |
| Directory stream | 4096 entries per sorted enumeration. |
| Checkpoint metadata | 64 MiB encoding ceiling. |
| Objects and retained dedup results | 100,000 each. |
| Sparse extents | 65,536 per file. |
| Client descriptors | 512 per mounted volume. |
| Durable worker handle records | 100,000 per volume. |
These are bounded representation/admission limits, not quotas or free-space reservations. Disk-full errors can occur before them, and logical admission can fail while physical space remains. Checkpoints and transfer spools add storage consumption; see capacity.
Workload exclusions
SQLite and other file-backed database engines, distributed advisory locking, shared mmap, xattr/ACL-dependent applications, special files and unrestricted POSIX compatibility are outside this contract. Run databases on a separate appropriate service. Replication is not an external backup or an application conflict-merging mechanism.