Supported capabilities and limits
Documentation home · Getting started · Filesystem semantics
This page describes the implemented operating contract for 4.1.0, retaining the operator-approved scope introduced in 4.0.0. Publication status is recorded by the tag pipeline. A floating dependency build does not inherit the runtime observations of older binaries. Historical results are identified separately in the staging record.
Intended deployment and design priorities
The intended audience is small to medium deployments on VM-based nodes with roughly 4–16 GB RAM and 4–16 vCPUs: hobbyists, small companies, shared website content/uploads and multiple application frontends. These are design targets, not demonstrated hardware capacity or performance guarantees. Lightweight RWX sharing is the primary goal; replication adds resilience within the documented membership and recovery limits. Mission-critical availability is not the target.
The operator accepts shared process failure boundaries and explicit service interruptions/recovery in exchange for a smaller footprint and simpler operation. Per-volume Pods and enterprise-style isolation are not requirements. This guides the consolidation into a small manager deployment and shared node workers. That topology is implemented in 4.1.0, using individual backing PVCs and opt-in exclusive local-CSI consumer publications. It has not been deployed or observed recovering existing volumes; release 4.0.1 retains the previous Pod topology. See architecture.
This trade-off does not weaken volume identity, writer fencing, ordered durable acknowledgement or explicit failure on uncertain authority. A smaller deployment may temporarily stop serving. Successful acknowledgement means the required durability conditions were met at that time; it cannot guarantee survival after subsequent loss of the necessary storage copies. The operator accepts that some failure levels cause irrecoverable data loss. The consolidation reports known retained replica-state loss explicitly, with the affected volume and known scope or recovery point, and distinguishes it from uncertain outcomes and unavailability. Detection does not establish the exact extent of lost application files. An unavailable replica is not by itself proof of lost application data; loss of one redundant copy may leave the data intact elsewhere. Report uncertainty when the evidence cannot establish the outcome. Preserve accurate success reporting, volume isolation and configured replica/quorum requirements. Quotas and other parked capabilities are not prerequisites for consolidation.
Platform and workload
| Area | Contract |
|---|---|
| Kubernetes | CSI filesystem provisioning and node stage/publish/unpublish/unstage. The application provisioner is csi.replicated.tak-os.org. |
| Application access | RWX and implemented RWO node ownership. RWO permits multiple Pods on the same staged node. No RWOP, ReadOnlyMany provisioning capability or raw block. |
| Host | Linux with working kernel FUSE, /dev/fuse, kubelet mount propagation and a privileged mount owner. Published architecture follows enabled TLSPU jobs; the recorded releases use amd64. Windows and rootless mount ownership are unsupported. |
| Backing storage | Ordinary tak-os-local-csi filesystem PVCs on distinct eligible storage nodes. Local CSI owns physical allocation and reclamation. |
| Backing filesystem | Working file/directory sync, atomic rename, sparse-file SEEK_DATA/SEEK_HOLE and truthful storage errors. NFS or recursive use of this replicated driver is not a supported backing layer. |
| Workload | Shared content, uploads and atomic file publication. Applications coordinate conflicting edits. File-backed databases and general POSIX compatibility are excluded. |
| Scale evidence | Historical measurements cover four volumes with replica counts 1/2/3/4, ten backing workers and two clients per volume. That is an observed small deployment, not a maximum-capacity or latency promise. |
No fixed Kubernetes, compiler, library or container version is imposed by this page. Build inputs float. The historical environment records actual earlier versions so that observations remain attributable; they are not current pins.
File behavior
Basic modes/UID/GID/umask, timestamps, sparse offset writes/truncation, ordered append, atomic rename/replacement, hardlinks and inert symbolic-link metadata are implemented. Direct I/O and fresh quorum/read barriers provide operation-level visibility. Multi-request reads/writes are not transactions. Open-unlink lifetime uses durable expiring handles. See the full file contract.
Locks/flock, xattrs, ACLs, special files or mode bits, shared mmap, snapshots,
clones, expansion/shrink, caller-selected fsType/mount flags and CSI mount groups
are unsupported. fsGroupPolicy: None leaves existing ownership unchanged;
initialize application directories explicitly before dropping privileges.
Replication and availability
| Configured replicas | Required majority | Current members that may be unavailable while quorum I/O continues |
|---|---|---|
| 1 | 1 | 0 |
| 2 | 2 | 0 |
| 3 | 2 | 1 |
| 4 | 3 | 1 |
There is no witness or silent quorum reduction. An acknowledged mutation is
journaled on a majority and applied by the serving coordinator. fsync also
synchronizes its derived file; it does not wait for every follower to materialize.
Durability assumes honest synchronization throughout the host/storage stack and
does not cover losing more durable copies than the majority model tolerates.
| Event | Behavior and boundary |
|---|---|
| Worker/minority unavailable | A surviving current majority can elect/serve; a returning original member catches up from verified state. RF1/RF2 cannot mask the unavailable member required by their quorum. |
| CSI frontend process lost | A surviving separate mount owner can retain its FUSE sessions and request identities. |
| Mount owner/whole Pod/kernel/host lost | Sessions disconnect. Close consumers and use normal unpublish/unstage/remount. Transparent descriptor survival is not promised. |
| Manager/API outage | Existing direct I/O avoids the API, but lifecycle, new mounts and credential refresh can stall. Credential expiry eventually denies I/O. |
| Controlled replacement | Requires a distinct eligible spare node, current quorum, verified learner state and affirmative durable old-member serving fence before final removal/reclamation. |
| Permanent original-node loss | Replacement/reclamation remain blocked until original authority returns. This capability is parked; Node deletion/name reuse and force-cleanup are not supported substitutes. |
| Quorum irretrievably lost | Preserve/isolate old authority and recover application files from an independently protected backup into a new generation, with explicit accepted loss. No journal promotion or automatic reduced-quorum adoption. |
Continuing I/O with a surviving quorum does not guarantee automatic restoration of lost redundancy. A temporary extra voter during replacement can increase required votes until the original member is removed.
Security and operations
Managers, cluster administrators and privileged storage/workload nodes are trusted. TLS and independent file/control credentials isolate ordinary volume clients; they do not provide hostile-root isolation or individual application user authentication at the worker. Normal renewal retains the original CA and is not emergency CA compromise revocation.
Requested PVC size is not an enforced quota or reservation. Real storage must cover the derived tree, journals, checkpoints and transfer spools. Protocol ceilings are bounded implementation/admission rules, not capacity guarantees. Observe low space and failed sync; keep external backups outside the replica failure domain. No production p99, IOPS floor or availability SLO is implied.
Parked and compatibility boundaries
Quotas, dynamic count changes, expansion/shrink, snapshots/clones, backup orchestration, retired-driver migration, permanent-node disposal, witnesses and other advanced storage layouts remain parked. There is no supported on-disk or wire migration from the retired pre-3.x implementation.
Upgrade with clients quiesced and all roles compatible, preserving original volume, backing, membership and trust identity. Active mixed-version rolling operation and format downgrade are unsupported. RWO data cannot be opened by an older RWX-only runtime. See compatibility, capacity and release policy.