Documentation
¶
Overview ¶
Package subvolume prepares the subvolume state of an existing CephFS filesystem: subvolume groups and subvolumes, their snapshots and clones, principals restricted to one subvolume, and directory pin policies of subvolumes and groups.
Create and CreateGroup create owned resources in a *cephfs.Filesystem; the listing and metadata functions (Names, GroupNames, Info, GroupInfo, SnapshotInfo, AuthorizedClients) read native state by name, including resources created outside this package. An operation on an owned resource is a method of its handle, which records the native identity it created and refuses a replaced resource. These functions act on a filesystem that cephfs.Run, cephfs.Start or cephfs.WithFilesystems created; they start no container.
Index ¶
- func GroupNames(ctx context.Context, fs *cephfs.Filesystem) ([]string, error)
- func Names(ctx context.Context, fs *cephfs.Filesystem, groupName string) ([]string, error)
- type Authorization
- type AuthorizationConfig
- type AuthorizedClient
- type Clone
- func (clone *Clone) Cancel(ctx context.Context) error
- func (clone *Clone) RemovePartial(ctx context.Context) error
- func (clone *Clone) Status(ctx context.Context) (*CloneStatus, error)
- func (clone *Clone) Wait(ctx context.Context) (*Subvolume, error)
- func (clone *Clone) Watch(ctx context.Context, cfg ceph.WatchConfig) (*CloneWatch, error)
- type CloneConfig
- type CloneStatus
- type CloneWatch
- type CloneWatchEvent
- type Config
- type Group
- type GroupConfig
- type GroupMetadata
- type Metadata
- type PinOverrideHandle
- type PinPolicy
- type PinSetting
- type PinType
- type Snapshot
- type SnapshotMetadata
- type SnapshotPendingClone
- type Subvolume
- func (volume *Subvolume) Authorize(ctx context.Context, config AuthorizationConfig) (*Authorization, error)
- func (subvolume *Subvolume) CreateSnapshot(ctx context.Context, name string) (*Snapshot, error)
- func (volume *Subvolume) OverridePin(ctx context.Context, setting PinSetting) (*PinOverrideHandle, error)
- func (volume *Subvolume) PinPolicy(ctx context.Context) (*PinPolicy, error)
- func (subvolume *Subvolume) Remove(ctx context.Context) error
- func (subvolume *Subvolume) Resize(ctx context.Context, sizeBytes int64) error
- func (subvolume *Subvolume) Snapshots(ctx context.Context) ([]string, error)
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func GroupNames ¶
GroupNames lists the native named groups of fs, sorted by name. It omits Ceph's internal default group and includes groups created outside these helpers.
Types ¶
type Authorization ¶
type Authorization struct {
Client *ceph.ClientConfig
AuthID string
Access string
FilesystemName string
SubvolumeName string
GroupName string
Path string
DataPool string
PoolNamespace string
// contains filtered or unexported fields
}
Authorization describes an owned native volumes grant. Client provides credentials for ClientConfig.WithIdentity and independent Linux clients. Exported fields are descriptions; changing them cannot redirect mutations. Copies share grant/deauthorization state. The namespace cap covers the entire actual namespace, which may be shared by clones inheriting a source layout.
func (*Authorization) Deauthorize ¶
func (grant *Authorization) 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 Authorization.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 (*Authorization) EvictClients ¶
func (grant *Authorization) 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.
type AuthorizationConfig ¶
AuthorizationConfig creates a fresh Cephx principal. Access must be "r" or "rw". Namespace-isolated subvolumes are required: a path cap alone cannot restrict direct RADOS access to the subvolume's file data.
type AuthorizedClient ¶
AuthorizedClient is one entry in native authorized_list. This is volumes metadata, not a complete audit of independently edited Cephx caps.
func AuthorizedClients ¶
func AuthorizedClients(ctx context.Context, fs *cephfs.Filesystem, name, group string) ([]AuthorizedClient, error)
AuthorizedClients reads the native volumes authorization metadata of the subvolume name in group of fs, including principals created through raw Ceph. It grants no mutation ownership.
type Clone ¶
type Clone struct {
Name, GroupName, FilesystemName string
// contains filtered or unexported fields
}
Clone is an asynchronous, owned clone request. Clone.Wait returns a usable subvolume only after native cloning completes. A non-nil descriptor on error records the attempted request but cannot be adopted or canceled automatically. Cluster cleanup removes incomplete data too.
func (*Clone) Cancel ¶
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 (*Clone) RemovePartial ¶
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 (*Clone) Status ¶
func (clone *Clone) Status(ctx context.Context) (*CloneStatus, 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 (*Clone) Wait ¶
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 (*Clone) Watch ¶
func (clone *Clone) Watch(ctx context.Context, cfg ceph.WatchConfig) (*CloneWatch, error)
Watch polls the native status of this owned clone request and reports its changes until a terminal state. The default WatchConfig.Interval is 3 seconds.
Before it returns, Watch makes one read under ctx and QueryTimeout, with the checks of Clone.Status: the request must be one this filesystem submitted, and the target's native UUID, inode and birth time, its source and the filesystem's FSMap ID must still be the ones captured at submission. A failed first read returns its error and starts nothing. That read is the baseline: the first event, already buffered. Receive it before triggering the change to observe.
Each read holds the filesystem's subvolume operation gate, taken through its QueryTimeout context, for that read only, and releases it before the event is sent and during the wait for the next read, so the consumer may call any fixture operation, Clone.Cancel included, while the watch runs. Unlike Status, a read never enables the MGR volumes module. A successful read whose status equals the previous successful read produces no event. A failed read produces a WatchGap and the watch continues; the next successful read is WatchResumed. A complete, failed or canceled status ends the watch after its event is delivered, and Stop then returns nil; when the baseline is already terminal, it is the only event. Calling Stop first also returns nil. A nil Stop therefore does not show that the clone completed; check the status of the last event. These end the watch with an error instead: ctx ending, a terminated cluster, a filesystem that is no longer the active one created by this cluster or whose FSMap ID or original pools changed, a target removed by Clone.RemovePartial, a target or source replaced outside this fixture, and a full buffer (ceph.ErrWatchOverflow).
The watch is read-only: stopping it neither cancels the clone nor removes partial data, and a complete status is not a usable subvolume; Clone.Wait remains the readiness result. The stream reports differences between samples, not a complete history of native transitions: a short pending or in-progress phase can fall between two reads.
Example ¶
The baseline is buffered before Watch returns, so the test acts on a known clone state: here it cancels the clone once the watch has seen it pending or in progress, and the terminal event then carries the native outcome. A clone that completed first ends the watch with a complete status instead. This example is compiled, not run.
package main
import (
"context"
"fmt"
"time"
"github.com/JSYoo5B/ceph-testcontainers-go/ceph"
"github.com/JSYoo5B/ceph-testcontainers-go/cephfs"
"github.com/JSYoo5B/ceph-testcontainers-go/cephfs/subvolume"
)
func main() {
ctx := context.Background()
cluster, err := cephfs.Run(ctx, ceph.DefaultImage)
if cluster != nil {
defer func() { _ = cluster.Terminate(context.Background()) }()
}
if err != nil {
panic(err)
}
fs := cephfs.Filesystems(cluster.Container)[0]
source, err := subvolume.Create(ctx, fs, subvolume.Config{Name: "source", SizeBytes: 64 << 20})
if err != nil {
panic(err)
}
// ... the SUT writes its data under source.Path ...
snapshot, err := source.CreateSnapshot(ctx, "checkpoint")
if err != nil {
panic(err)
}
clone, err := snapshot.Clone(ctx, subvolume.CloneConfig{Name: "restore"})
if err != nil {
panic(err)
}
watch, err := clone.Watch(ctx, ceph.WatchConfig{Interval: time.Second})
if err != nil {
panic(err)
}
defer func() { _ = watch.Stop() }() // before the cluster's Terminate
canceled := false
for event := range watch.Events() {
if event.Kind == ceph.WatchGap {
continue
}
switch event.Status.State {
case "pending", "in-progress":
if !canceled {
// A clone that completes first refuses the cancellation;
// its terminal event still follows.
if err := clone.Cancel(ctx); err != nil {
fmt.Println("cancel refused:", err)
}
canceled = true
}
default:
fmt.Printf("clone %s (errno %d) at event %d\n", event.Status.State, event.Status.FailureErrno, event.Sequence)
}
}
if err := watch.Stop(); err != nil {
panic(err) // the watch ended before a terminal status
}
}
Output:
type CloneConfig ¶
type CloneConfig struct {
Name, GroupName, DataPool string
}
CloneConfig names a new clone in an existing group. DataPool optionally overrides the snapshot's data pool. Ceph copies the snapshot's quota and layout; with a DataPool override it clears the inherited RADOS namespace. Quota and namespace changes are deliberately not part of the clone request.
type CloneStatus ¶
type CloneStatus struct {
State, SourceFilesystem, SourceSubvolume, SourceGroup, SourceSnapshot string
FailureErrno int
FailureMessage string
Progress map[string]string
}
CloneStatus reports native pending, in-progress, complete, failed or canceled state. FailureErrno is zero when no native failure was recorded. Source fields are normally absent after successful completion.
type CloneWatch ¶
type CloneWatch struct {
// contains filtered or unexported fields
}
CloneWatch is a running watch of one owned clone request. One goroutine reads the native clone status and sends events; Events closes after that goroutine has stopped using the filesystem. Stop ends the watch and waits for it.
func (*CloneWatch) Events ¶
func (w *CloneWatch) Events() <-chan CloneWatchEvent
Events returns the receive-only event channel. The baseline is already in it when Clone.Watch returns. The channel closes when the watch ends; Stop returns why.
func (*CloneWatch) Stop ¶
func (w *CloneWatch) Stop() error
Stop cancels the watch if it is still running, waits until its goroutine has returned and Events is closed, and returns the cause that ended the watch: nil when Stop ended it or a terminal status was delivered, the context's error when the Clone.Watch context ended, a ceph.ErrWatchOverflow error, or the ceph.ErrInvalidRequest read error that ended it (a terminated cluster, a filesystem that is no longer active, or a replaced or removed target), which names the clone and keeps the refusal. A failed or canceled clone is not an error of Stop; its event carries the outcome. Buffered events stay readable after Stop. Stop is safe to call more than once and from any goroutine; every call returns the same cause. It never cancels the clone. Call it before the fixture's cleanup: cancelling the context alone does not wait.
type CloneWatchEvent ¶
type CloneWatchEvent struct {
Sequence uint64
Kind ceph.WatchEventKind
Started, Finished time.Time
Status *CloneStatus
Err error
}
CloneWatchEvent is one event of a CloneWatch.
Sequence starts at 1 with the baseline and increases by one for each event, and no event is dropped, so consecutive numbers mean the consumer saw every event the watch produced. Started and Finished are the local clock around the read, not the time Ceph changed state; the native status carries no timestamp.
Status is the native clone status of a successful read, nil on a gap. Every field of it is compared, Progress entry by entry, exactly as Ceph reports it; nothing is parsed into a percentage. Source fields are normally absent once the clone is complete. A failed or canceled clone is an outcome in Status (State, FailureErrno and FailureMessage), not an Err: Err is only the failure of a read. Each event has its own Status and Progress map, which the consumer may keep or change. Two statuses separated by a gap, or simply by the polling interval, do not establish the transitions in between.
type Config ¶
type Config struct {
Name string
GroupName string
SizeBytes int64
DataPool string
NamespaceIsolated bool
}
Config creates a directory tree managed by the MGR volumes module. An empty GroupName selects Ceph's default group. Zero SizeBytes leaves it unlimited. DataPool selects an existing filesystem data pool; empty inherits the group's layout. NamespaceIsolated gives file data a separate RADOS namespace; client access still requires appropriate Cephx capabilities.
type Group ¶
type Group struct {
Name string
FilesystemName string
Path string
// contains filtered or unexported fields
}
Group is an owned group returned by CreateGroup. Public fields are creation-time descriptions; mutations use the private identity captured after successful creation. Get current quota through GroupInfo. Removing a group requires it to be empty.
func CreateGroup ¶
func CreateGroup(ctx context.Context, fs *cephfs.Filesystem, config GroupConfig) (*Group, error)
CreateGroup creates a fresh group in fs. 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 (*Group) OverridePin ¶
func (group *Group) OverridePin(ctx context.Context, setting PinSetting) (*PinOverrideHandle, error)
OverridePin changes one owned group's local policy field.
func (*Group) Remove ¶
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. Restore this group's pin overrides first. External edits must not race removal.
type GroupConfig ¶
GroupConfig creates a named group inside an existing filesystem. SizeBytes is its aggregate directory quota; zero leaves it unlimited. DataPool optionally selects one of the filesystem's existing data pools. These helpers do not create pools, filesystems, MDS daemons or orchestrator services.
type GroupMetadata ¶
type GroupMetadata struct {
Name string
Path string
DataPool string
QuotaBytes int64
BytesUsed int64
CreatedAt string
}
GroupMetadata reports native group metadata. QuotaBytes is zero for an unlimited quota. BytesUsed is Ceph's directory size accounting, which can lag recent writes. CreatedAt is the directory birth time used by the native volumes module.
func GroupInfo ¶
func GroupInfo(ctx context.Context, fs *cephfs.Filesystem, name string) (*GroupMetadata, error)
GroupInfo queries the current native quota/layout and path of the group name in fs.
type Metadata ¶
type Metadata struct {
Name string
GroupName string
Path string
DataPool string
PoolNamespace string
QuotaBytes int64
BytesUsed int64
CreatedAt string
State string
Type string
}
Metadata reports a native subvolume, including its real mount path and RADOS namespace. Read-only queries also describe resources created outside these helpers, but those resources cannot be resized or removed through an owned handle. QuotaBytes is zero for unlimited.
type PinOverrideHandle ¶
type PinOverrideHandle struct {
// contains filtered or unexported fields
}
PinOverrideHandle manages restoration of one confirmed owned resource's policy field, retaining prior state and possibly uncertain application. Copies share restoration state. Retain a non-nil result even on error: cancellation or a lost reply can leave native state changed. Explicit Restore returns that field to its prior canonical virtual value; other fields, directories and data are preserved. It refuses a different current field or native resource identity. Same-value outside edits and changes below native text precision cannot be distinguished; do not race external pin edits or delete/recreate the directory while the handle is used.
func (*PinOverrideHandle) Restore ¶
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. A confirmed outside value is preserved. Restore returns ErrInvalidRequest, releases the field, and every copy of the handle retains that refusal.
type PinPolicy ¶
type PinPolicy struct {
Path string
Inode uint64
ExportRank int
Distributed bool
RandomProbability float64
}
PinPolicy reports the local virtual xattrs on the directory targeted by the native volumes pin command. For subvolumes, Path is the base directory, one level above the UUID data directory returned by Info. ExportRank -1, Distributed false and RandomProbability 0 are native virtual defaults. These local values do not report inherited policy or actual MDS authority. RandomProbability has the precision of native virtual-xattr text.
type PinSetting ¶
PinSetting changes one policy field. Export accepts an integer owned active rank, or -1 to remove the local pin. Distributed accepts 0 or 1. Random accepts a probability in [0,1], additionally capped by the MDS's mds_export_ephemeral_random_max. Ephemeral feature configuration is caller- controlled; setting a policy does not prove its runtime effect.
type PinType ¶
type PinType string
PinType selects one native directory policy. Policies can coexist; ancestry and Ceph's native precedence determine actual subtree placement.
const ( // PinExport pins the directory to one active rank held by an owned MDS; // the value -1 removes the local pin. PinExport PinType = "export" // PinDistributed spreads the immediate children across ranks; the value // is 0 or 1. PinDistributed PinType = "distributed" // PinRandom pins descendants to a random rank with a probability in // [0, 1], further capped by mds_export_ephemeral_random_max. PinRandom PinType = "random" )
type Snapshot ¶
type Snapshot struct {
Name, SubvolumeName, GroupName, FilesystemName, Path string
// contains filtered or unexported fields
}
Snapshot is an owned snapshot of a confirmed subvolume. Its public fields describe creation; mutations use the captured private identity. Snapshot creation does not quiesce concurrent application writers. A descriptor returned with a create or metadata-read error has unconfirmed identity.
func (*Snapshot) Clone ¶
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 Clone.RemovePartial or raw Ceph cleanup.
func (*Snapshot) Remove ¶
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.
type SnapshotMetadata ¶
type SnapshotMetadata struct {
Name, SubvolumeName, GroupName, Path, CreatedAt, DataPool string
HasPendingClones bool
PendingClones []SnapshotPendingClone
OrphanClonesCount int
}
SnapshotMetadata contains current native snapshot metadata. Path identifies the frozen data directory, including Ceph's incarnation UUID.
func SnapshotInfo ¶
func SnapshotInfo(ctx context.Context, fs *cephfs.Filesystem, subvolumeName, groupName, snapshotName string) (*SnapshotMetadata, error)
SnapshotInfo queries native metadata for any existing snapshot of a subvolume in fs. Reading an external snapshot does not grant mutation ownership.
type SnapshotPendingClone ¶
type SnapshotPendingClone struct {
Name string `json:"name"`
GroupName string `json:"target_group"`
}
SnapshotPendingClone identifies a native clone still using a snapshot. An empty GroupName selects the default group.
type Subvolume ¶
type Subvolume struct {
Name string
GroupName string
FilesystemName string
Path string
// contains filtered or unexported fields
}
Subvolume is an owned subvolume returned by Create. Its public fields describe creation. Info queries current native state. Remove deletes this directory tree and its contents, preserving its filesystem and pools; native trash purging is asynchronous.
func Create ¶
Create creates a fresh subvolume in the default or an existing named group of fs. 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 (*Subvolume) Authorize ¶
func (volume *Subvolume) Authorize(ctx context.Context, config AuthorizationConfig) (*Authorization, 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. When the native grant was attempted, clean it up with Authorization.Deauthorize. When only the Client was created and the grant was never attempted, Deauthorize refuses the result with ceph.ErrInvalidRequest because the principal holds no file-data rights: remove it with grant.Client.Delete. External auth/layout edits must not race these operations.
func (*Subvolume) CreateSnapshot ¶
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.
A create or metadata-read failure can return an unconfirmed descriptor. Use SnapshotInfo to inspect the native name. Remove and Clone require a confirmed identity. Deleting by name could remove another client's snapshot.
func (*Subvolume) OverridePin ¶
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 ¶
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 ¶
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. Restore this subvolume's pin overrides first. Its filesystem, groups and pools remain available.
func (*Subvolume) Resize ¶
Resize changes only an owned subvolume's quota, with the same zero and --no_shrink behavior as Group.Resize.