cephfs

func (*DataPool) RemoveUnused ¶ added in v0.4.0

func (attachment *DataPool) RemoveUnused(ctx context.Context) error

RemoveUnused removes only the FSMap registration of a fresh helper attachment. A pool selected even once by a managed group/subvolume/clone is refused, including partial creations. Native groups/subvolumes must have no references and every RADOS namespace must be empty; unknown clone or retained snapshot information is conservatively refused. No pool, application tag or data is deleted. Native rm_data_pool cannot detect arbitrary POSIX layout references: the caller MUST stop external clients and reset all such layouts before removal, and prevent external edits from racing it. This method does not establish safety for a live workload. Default data pools are immutable. A copied handle shares removal state; retry reconciles a lost command reply.

func (*Filesystem) AddDataPool ¶

func (fs *Filesystem) AddDataPool(ctx context.Context, name string) (*DataPool, error)

AddDataPool attaches an existing pool with application=cephfs and no prior filesystem role. Replicated pools and EC pools with allow_ec_overwrites are accepted. Metadata pools, cross-filesystem reuse and repeated attachments are refused. It creates or deletes no pools. A handle returned with an error records an attempted attachment; retrying the same name reconciles an unknown successful command using the original native IDs. External edits must not race these operations. Ceph's retained application tag after detachment must be inspected and explicitly cleared through Ceph before a new attachment.

Clear the retained tag with ceph osd pool application rm <name> cephfs data before attaching a detached pool again.

func (*Filesystem) AddSnapshotSchedule ¶ added in v0.4.0

func (fs *Filesystem) AddSnapshotSchedule(ctx context.Context, schedule SnapshotSchedule) (*SnapshotScheduleLease, error)

AddSnapshotSchedule adds a snapshot schedule, and its retention, to a directory of the filesystem through the MGR snap_schedule module, which takes "scheduled-…" snapshots in the directory's .snap. It never enables the module: enable it with override.SetMGRModule first, and wait until the active MGR, which restarts to load it, answers again. A disabled module is ceph.ErrInvalidRequest, and so is a directory that already has a schedule or another lease. The module keeps retention per directory, and a directory keeps retention rules after its last schedule is removed: rules that the new schedule inherits are refused with ceph.ErrInvalidRequest after the schedule was added, with a lease that removes it.

A non-nil lease returned with an error must be restored: after an add whose reply was lost, Restore takes the only schedule with the requested repeat and start as the lease's.

func (*Filesystem) CreateSubvolume ¶

func (fs *Filesystem) CreateSubvolume(ctx context.Context, config SubvolumeConfig) (*Subvolume, error)

CreateSubvolume creates a fresh subvolume in the default or an existing named group. It rejects duplicates and unknown filesystem data pools before create. A non-nil result on failure identifies an attempted resource; it never removes partial data. Only successfully confirmed handles support Resize/Remove.

func (*Filesystem) CreateSubvolumeGroup ¶

func (fs *Filesystem) CreateSubvolumeGroup(ctx context.Context, config SubvolumeGroupConfig) (*SubvolumeGroup, error)

CreateSubvolumeGroup creates a fresh group. Native Ceph's create is idempotent and can change an existing group's quota/layout; this helper rejects duplicates before issuing create. Do not race external subvolume/group commands with these operations. A non-nil handle on error records an attempted creation, but only a fully confirmed identity can be mutated. Cluster termination cleans up the entire disposable filesystem even after partial creation.

func (*Filesystem) DataPools ¶

func (fs *Filesystem) DataPools(ctx context.Context) ([]DataPoolState, error)

DataPools reads the authoritative FSMap registration and current pool IDs. AdditionalDataPools in the creation descriptor describes initial settings; this method also reports subsequent native attachments and removals.

func (*Filesystem) MDSStatus ¶

func (fs *Filesystem) MDSStatus(ctx context.Context) (*FilesystemStatus, error)

MDSStatus reads one native FSMap, so rank ownership and standby state come from the same epoch. Active ranks include external daemons with Owned=false; standby lists contain only this fixture's daemons with matching affinity.

func (*Filesystem) MDSs ¶

func (fs *Filesystem) MDSs() []*MDS

MDSs returns a snapshot of this filesystem's owned daemons in creation order.

func (*Filesystem) OverrideSessionTimeouts ¶ added in v0.4.0

func (fs *Filesystem) OverrideSessionTimeouts(ctx context.Context, requested SessionTimeouts) (*SessionTimeoutsOverrideHandle, error)

OverrideSessionTimeouts sets both limits so a test can observe evicted clients in seconds instead of Ceph's default 60 and 300 seconds. Each value must be a whole number of seconds and at least 30 seconds, the native minimum. Only one handle per filesystem may be active. The native CLI changes one value per command, so apply and restore are not atomic.

func (*Filesystem) QuiesceSubvolumes ¶

func (fs *Filesystem) QuiesceSubvolumes(ctx context.Context, volumes []*Subvolume, config QuiesceConfig) (*Quiesce, error)

QuiesceSubvolumes pauses I/O to confirmed owned subvolumes as one native set. It uses --if-version=0 to create exclusively, validates every current resource identity, and awaits QUIESCED with finite native timeout and expiration. Existing sets and application writers remain caller-owned. Take checkpoints with client/admin APIs while paused, then explicitly Release. Multiple native sets can overlap paths; releasing this set does not cancel other sets.

func (*Filesystem) Remove ¶ added in v0.4.0

func (fs *Filesystem) Remove(ctx context.Context) error

Remove deletes this owned filesystem: it gracefully stops its ranks and removes it in the FSMap, terminates its MDS daemons, deletes their Cephx keys and removes the metadata, default data and AdditionalDataPools that its configuration created, together with their CRUSH rules and EC profiles. Pools attached later with AddDataPool are detached but kept; remove them with ceph.Pool.Remove (see ceph.Container.Pool). File data in the removed pools is destroyed. Stop clients, CephFS mirrors and subvolume operations on the filesystem first; their handles fail afterwards. A retry after an error continues with whatever remains. If graceful shutdown cannot complete within the caller or startup timeout, removal returns an error without forcing the MDSs to fail. The filesystem may remain marked down and stays owned for a later retry.

Remove acts on this descriptor. One that Remove already removed, or that is not the one the cluster owns for its name, returns an error.

It requests fs set <name> down true and requires the filesystem's native up map to be empty before fs rm, so a rank that is still stopping or reconnecting blocks removal, and health warnings never authorize a forced fs fail.

func (*Filesystem) ScaleMDS ¶

func (fs *Filesystem) ScaleMDS(ctx context.Context, active, standby int) (returnErr error)

ScaleMDS changes the active/standby daemon counts of this existing filesystem without recreating its pools or data. Active must be 1..256 and Standby must be non-negative. Additional MDSs preserve the initial customizers and affinity. Ceph hands retired ranks back to standbys before this method stops surplus owned daemons. Ordinary standbys are removed before replay followers.

The explicit topology request acknowledges Ceph's max_mds health-warning confirmation (--yes-i-really-mean-it) in this disposable fixture. Run scaling with healthy owned daemons and without concurrent external failure injection or FSMap edits. An error retains desired counts and every partial resource for cluster cleanup; it never deletes the filesystem, its pools or file data. Scaling to zero standby leaves the filesystem's replay preference unchanged.

func (*Filesystem) SessionTimeouts ¶

func (fs *Filesystem) SessionTimeouts(ctx context.Context) (SessionTimeouts, error)

SessionTimeouts reads both limits from the filesystem's current MDSMap.

func (*Filesystem) Sessions ¶

func (fs *Filesystem) Sessions(ctx context.Context) ([]Session, error)

Sessions lists client sessions from every active rank of the filesystem, including the fixture's own short-lived libcephfs probes. Filter by Hostname or EntityID to find a particular client. It reads native state only.

func (*Filesystem) SubvolumeAuthorizedClients ¶

func (fs *Filesystem) SubvolumeAuthorizedClients(ctx context.Context, name, group string) ([]SubvolumeAuthorizedClient, error)

SubvolumeAuthorizedClients reads native volumes authorization metadata, including principals created through raw Ceph. It grants no mutation ownership.

func (*Filesystem) SubvolumeGroupInfo ¶

func (fs *Filesystem) SubvolumeGroupInfo(ctx context.Context, name string) (*SubvolumeGroupInfo, error)

SubvolumeGroupInfo queries the current native group quota/layout and path.

func (*Filesystem) SubvolumeGroups ¶

func (fs *Filesystem) SubvolumeGroups(ctx context.Context) ([]string, error)

SubvolumeGroups lists native named groups, sorted by name. It omits Ceph's internal default group and includes groups created outside these helpers.

func (*Filesystem) SubvolumeInfo ¶

func (fs *Filesystem) SubvolumeInfo(ctx context.Context, name, groupName string) (*SubvolumeInfo, error)

SubvolumeInfo queries current metadata. name identifies the subvolume and an empty groupName selects the default group. A snapshot-retained entry lacks a usable Path and is never accepted as an active owned resource.

func (*Filesystem) SubvolumeSnapshotInfo ¶

func (fs *Filesystem) SubvolumeSnapshotInfo(ctx context.Context, subvolumeName, groupName, snapshotName string) (*SubvolumeSnapshotInfo, error)

SubvolumeSnapshotInfo queries native metadata for any existing snapshot. Reading an external snapshot does not grant mutation ownership.

func (*Filesystem) Subvolumes ¶

func (fs *Filesystem) Subvolumes(ctx context.Context, groupName string) ([]string, error)

Subvolumes lists native names in groupName, sorted by name. Empty selects the default group. Native snapshot-retained entries can appear in this listing.

func (*Filesystem) WaitReady ¶

func (fs *Filesystem) WaitReady(ctx context.Context) error

WaitReady waits for all configured ranks to be owned and active and all configured standbys to register. Replay mode also waits for journal followers. After a standby takes over a failed active daemon, use MDSStatus to check recovered ranks or restart a daemon before WaitReady; readiness includes the requested standby capacity.

package main

import (
	"context"
	"fmt"
	"time"

	"github.com/JSYoo5B/ceph-testcontainers-go/cephfs"
)

func main() {
	// This unavailable descriptor verifies expected API-error delivery and the
	// one-shot channel lifecycle without Docker. It is not a ready fixture or a
	// replacement for Run/Start; real callers use their owned filesystem.
	fs := &cephfs.Filesystem{}
	waitCtx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
	resultCh := make(chan error, 1)
	var results <-chan error = resultCh // One result for one consumer, not a broadcast.
	joined := make(chan struct{})
	defer func() { cancel(); <-joined }() // Register before launching the worker.
	go func() {
		defer close(joined)
		resultCh <- fs.WaitReady(waitCtx)
		close(resultCh)
	}()

	var outcomeErr error
	var open bool
	select {
	case outcomeErr, open = <-results:
	case <-waitCtx.Done():
		cancel()
		<-joined
		outcomeErr, open = <-results
	}
	cancel()
	<-joined // Join before callbacks or fixture cleanup with a fresh context.
	if !open {
		panic("wait closed without a terminal result")
	}
	if _, open := <-results; open {
		panic("wait sent more than one terminal result")
	}
	consume := func(err error) {
		fmt.Println("consumer received error:", err != nil)
	}
	consume(outcomeErr) // Caller code after join, outside the wait's fixture gates.
	fmt.Println("worker joined and channel closed")
}

Output:
consumer received error: true
worker joined and channel closed

func (*MDS) AddReplacement ¶ added in v0.4.0

func (stopped *MDS) AddReplacement(ctx context.Context) (*MDS, error)

AddReplacement starts a new indexed MDS for the filesystem of this stopped MDS, its sole original member, preserving its pools, data and desired one-active/zero-standby policy. The old name must already be globally absent and rank zero failed; native failure is caller-controlled. No native fail, auth deletion or old CID removal is performed. Once the new rank is ready, MDS.RemoveStopped can retire the original old container using the new healthy survivor.

Any failure after the auth/start attempt leaves this request cleanup-only, including its use as typed scaling/retirement authority. A nonnil result remains owned even on error. Retrying the original or an exact copied handle never implicitly starts another daemon or completes a partial request. A completed retry reattests and returns only the exact new handle. Direct Start/Stop, native policy/failure edits and exported-field edits must not run concurrently. Native name/GID and original Docker CID are independent evidence; this method does not establish process-to-GID attribution.

Without a standby, Ceph can keep a dead daemon registered as laggy; fail its GID explicitly with ceph mds fail <gid> before calling it. Do not start, stop or fail daemons by hand while it runs.

func (*MDS) RemoveStopped ¶ added in v0.4.0

func (daemon *MDS) RemoveStopped(ctx context.Context) error

RemoveStopped retires this original owned, stopped MDS container after its immutable daemon name has left every native filesystem and global standby list. Healthy original owned daemons must still serve every desired active rank. It neither fails a native MDS nor deletes its auth entity or changes desired capacity. Use Filesystem.ScaleMDS afterward to create missing replacement members.

Only successful original startups are eligible. A partial startup remains owned for cluster Terminate. An uncertain Docker removal retains the original handle for explicit retry; initial arbitrary absence is not success. Direct failure injection, Start/Stop and raw policy changes must not run concurrently.

func (*PinOverrideHandle) Restore ¶ added in v0.4.0

func (change *PinOverrideHandle) Restore(ctx context.Context) error

Restore confirms the same owned directory/inode and returns only this field to its previous canonical native value. It is idempotent across handle copies; after an uncertain reply, retry with a fresh context to reconcile readback.

func (*Quiesce) ID ¶

func (q *Quiesce) ID() string

ID returns the native quiesce set ID, for example to inspect it with ceph fs quiesce <fs> --set-id <id> --query.

func (*Quiesce) Release ¶

func (q *Quiesce) Release(ctx context.Context) error

Release resumes this set's I/O only at its captured QUIESCED version, using native optimistic concurrency. Expired/timed-out/canceled sets are reported as errors, so a test cannot treat an interrupted checkpoint as consistent. Lost replies can be retried; confirmed RELEASED copies become no-ops. Native set records are retained by the QDB and disposed of with the cluster.

func (*Quiesce) Status ¶

func (q *Quiesce) Status(ctx context.Context) (*QuiesceState, error)

Status queries this set without renewing the native expiration timer. It verifies filesystem and exact nonexcluded members; it does not adopt new versions as permission to release an externally edited set.

func (*SessionTimeoutsOverrideHandle) Restore ¶ added in v0.4.0

func (change *SessionTimeoutsOverrideHandle) Restore(ctx context.Context) error

Restore returns both limits to the values captured before the change. It is idempotent across handle copies. A value that is neither the applied nor the captured one is an outside edit and is refused rather than overwritten.

func (*SnapshotScheduleLease) Restore ¶ added in v0.4.0

func (l *SnapshotScheduleLease) Restore(ctx context.Context) error

Restore removes the retention rules that the lease added, then its schedule; the snapshots stay. The module keeps retention per directory: every schedule of the directory shares it, and it stays after the last schedule is removed. Restore reads the directory back on every call, so a retry continues where an earlier call stopped, and it completes only once both the lease's rules and its schedule are confirmed gone:

• a rule that the directory no longer lists, or that the module reports as not set when no schedule shows the retention, is done;
• while another schedule of the directory, of any repeat, would lose a rule of the lease, Restore refuses with ceph.ErrInvalidRequest without a change, and so it does for a rule whose count changed or a schedule with the lease's repeat that is not the lease's. The lease stays retryable, for example after the other schedule's owner removed it.

func (*SnapshotScheduleLease) Snapshots ¶ added in v0.4.0

func (l *SnapshotScheduleLease) Snapshots(ctx context.Context) ([]string, error)

Snapshots lists the snapshots in the directory's .snap that the module took, named "scheduled-…", oldest first, through libcephfs in the client container.

func (*SnapshotScheduleLease) Status ¶ added in v0.4.0

func (l *SnapshotScheduleLease) Status(ctx context.Context) (SnapshotScheduleStatus, error)

Status reads the schedule's state from the snap_schedule module.

func (*Subvolume) Authorize ¶ added in v0.4.0

func (volume *Subvolume) Authorize(ctx context.Context, config SubvolumeAuthorizationConfig) (*SubvolumeAuthorization, error)

Authorize creates a fresh identity with an explicit fresh key, then asks MGR volumes to grant its exact native UUID path and pool/namespace. It refuses existing principals and non-isolated layouts. Native --allow_existing_id is used only for this immediately created, key-verified identity, never to adopt a user. MON visibility is restricted to this filesystem. This grant provides no layout, snapshot or root-squash administration capabilities.

A non-nil result with an error may contain an owned partial creation. It is never silently adopted by a second Authorize call; inspect through Ceph or explicitly SubvolumeAuthorization.Deauthorize when its Client creation was confirmed. External auth/layout edits must not race these operations.

func (*Subvolume) CreateSnapshot ¶ added in v0.4.0

func (subvolume *Subvolume) CreateSnapshot(ctx context.Context, name string) (*SubvolumeSnapshot, error)

CreateSnapshot creates a fresh snapshot without modifying an existing same-named snapshot. Application writers must be synchronized by the caller before taking a consistency-sensitive checkpoint. External CLI mutations must not race the native preflight and creation.

func (*Subvolume) OverridePin ¶ added in v0.4.0

func (volume *Subvolume) OverridePin(ctx context.Context, setting PinSetting) (*PinOverrideHandle, error)

OverridePin changes one local field using Ceph's volumes command. The native subvolume data path is left intact. Overlapping handles for the same target/field are rejected; independent fields may be changed separately.

func (*Subvolume) PinPolicy ¶ added in v0.4.0

func (volume *Subvolume) PinPolicy(ctx context.Context) (*PinPolicy, error)

PinPolicy reads all three local fields on an owned subvolume's base directory through libcephfs inside the client container (ClientContainer). No host mount or Go native dependency is required; the client image must supply Python libcephfs.

func (*Subvolume) Remove ¶ added in v0.4.0

func (subvolume *Subvolume) Remove(ctx context.Context) error

Remove removes this owned directory tree and its contents without --force or --retain-snapshots. Native Ceph refuses subvolumes with snapshots; use the snapshot helpers to remove owned snapshots first. Trash purging is async. Repeat removal after confirmed success is a no-op; external edits must not race this operation. Its filesystem, groups and pools remain available.

func (*Subvolume) Resize ¶ added in v0.4.0

func (subvolume *Subvolume) Resize(ctx context.Context, sizeBytes int64) error

Resize changes only an owned subvolume's quota, with the same zero and --no_shrink behavior as SubvolumeGroup.Resize.

func (*Subvolume) Snapshots ¶ added in v0.4.0

func (subvolume *Subvolume) Snapshots(ctx context.Context) ([]string, error)

Snapshots lists native snapshots of an owned subvolume, including snapshots made by an external client. Only snapshots returned by this fixture's Subvolume.CreateSnapshot can be removed or cloned through an owned descriptor.

func (*SubvolumeAuthorization) Deauthorize ¶ added in v0.4.0

func (grant *SubvolumeAuthorization) Deauthorize(ctx context.Context) error

Deauthorize removes only this native path/pool/namespace grant and volumes metadata. It verifies the original volume, layout and principal key; unrelated capabilities and the key are preserved unless native Ceph deletes an identity with no remaining rights. It does not revoke overlapping grants added separately, remove files or evict established sessions. Use a fresh client to observe changed permissions, then SubvolumeAuthorization.EvictClients when needed. A lost reply keeps retry state; native metadata/caps are reconciled before repeating the command. Outside edits after an uncertain result are surfaced without restoring or overwriting them.

func (*SubvolumeAuthorization) EvictClients ¶ added in v0.4.0

func (grant *SubvolumeAuthorization) EvictClients(ctx context.Context) error

EvictClients evicts existing sessions with this principal and the exact original subvolume mount root. Deauthorization must have completed first; independently mounted roots and future connections permitted by other grants are outside this native operation's scope. Eviction may blocklist the client's connection address. A native error may represent partial eviction across MDS ranks; a retry repeats the same owned scope.

To remove the principal itself afterwards, call grant.Client.Delete.

func (*SubvolumeClone) Cancel ¶ added in v0.4.0

func (clone *SubvolumeClone) Cancel(ctx context.Context) error

Cancel requests native cancellation of an owned pending or in-progress clone, then waits for canceled state and release of this clone's source snapshot protection. Its partial target is retained. A completed or failed clone is never treated as successfully canceled. Copied handles share identity; a retry after a lost reply first reconciles native canceled state. The original source snapshot must still exist. Native external clone/source edits must not race this operation; pending UUIDs are read from version-checked native volumes metadata captured immediately after submission.

func (*SubvolumeClone) RemovePartial ¶ added in v0.4.0

func (clone *SubvolumeClone) RemovePartial(ctx context.Context) error

RemovePartial explicitly removes an owned failed or canceled target with native --force. It refuses pending/in-progress/completed clones, replaced target incarnations and unresolved source protection. The original snapshot must remain present and unchanged. No source data or snapshots are removed. Native removal moves the target into asynchronous trash; success confirms logical absence, not physical purge completion. A failed command retains shared retry state so an unknown successful removal can be reconciled without deleting a subsequently recreated same-named target.

func (*SubvolumeClone) Status ¶ added in v0.4.0

func (clone *SubvolumeClone) Status(ctx context.Context) (*SubvolumeCloneStatus, error)

Status inspects this owned request. Native status is read-only; failed and canceled targets are preserved. Every query verifies the captured native UUID, inode and birth time too.

func (*SubvolumeClone) Wait ¶ added in v0.4.0

func (clone *SubvolumeClone) Wait(ctx context.Context) (*Subvolume, error)

Wait waits within the cluster startup timeout or the caller's earlier deadline. A timeout leaves cloning running and can be retried. Native failed/canceled states return promptly without removing partial data. A successful result supports existing Subvolume.Resize/Subvolume.Remove methods.

func (*SubvolumeGroup) OverridePin ¶ added in v0.4.0

func (group *SubvolumeGroup) OverridePin(ctx context.Context, setting PinSetting) (*PinOverrideHandle, error)

OverridePin changes one owned group's local policy field.

func (*SubvolumeGroup) PinPolicy ¶ added in v0.4.0

func (group *SubvolumeGroup) PinPolicy(ctx context.Context) (*PinPolicy, error)

PinPolicy reads an owned group's local directory policies.

func (*SubvolumeGroup) Remove ¶ added in v0.4.0

func (group *SubvolumeGroup) Remove(ctx context.Context) error

Remove removes an owned empty group without --force. A native refusal (for example a nonempty group) preserves its handle for retry. A repeat call after confirmed success is a no-op. External edits must not race removal.

func (*SubvolumeGroup) Resize ¶ added in v0.4.0

func (group *SubvolumeGroup) Resize(ctx context.Context, sizeBytes int64) error

Resize changes only an owned group's quota. Zero removes its limit. --no_shrink refuses a positive limit below native current usage; it never truncates files. Directory accounting and quota enforcement are native CephFS behavior and can lag concurrent writes.

func (*SubvolumeSnapshot) Clone ¶ added in v0.4.0

func (snapshot *SubvolumeSnapshot) Clone(ctx context.Context, config CloneConfig) (*SubvolumeClone, error)

Clone submits an asynchronous copy to a fresh subvolume. Duplicate targets are rejected; the source snapshot is retained. Immediately after submission it captures the target UUID, inode and birth time from version-checked native volumes metadata inside the client container. External edits must not race submission. A failed command or identity read returns a non-nil descriptor for inspection, but cannot be adopted or mutated through this API. Failed/canceled targets are retained until explicit SubvolumeClone.RemovePartial or raw Ceph cleanup.

func (*SubvolumeSnapshot) Remove ¶ added in v0.4.0

func (snapshot *SubvolumeSnapshot) Remove(ctx context.Context) error

Remove removes only this owned snapshot without --force. Pending clones protect their source snapshot both in this preflight and in native Ceph. Copies share removal state, and retry reconciles an uncertain successful deletion. Source data and completed clones are preserved.