subvolume

package
v1.0.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 16, 2026 License: MIT Imports: 21 Imported by: 0

README

CephFS subvolumes

Import github.com/JSYoo5B/ceph-testcontainers-go/cephfs/subvolume to give an application that works in CephFS subvolumes the state its integration test needs in an existing filesystem: subvolume groups and subvolumes with quotas, data pools and RADOS namespaces, snapshots and clones, a Cephx principal restricted to one subvolume, and directory pin policies. The filesystem, its MDS topology and its data pools stay in the cephfs package; the package starts no container. See API purpose and purpose tags.

Order of use

  1. Start a filesystem with cephfs.Run, cephfs.Start or cephfs.WithFilesystems, and take its handle from cephfs.Filesystems(cluster.Container).
  2. Create the resources with subvolume.CreateGroup(ctx, fs, cfg) and subvolume.Create(ctx, fs, cfg). Each returns an owned handle; operations on an existing resource are methods of its handle: Resize, Subvolume.CreateSnapshot and Snapshot.Clone (then Clone.Wait), Subvolume.Authorize (a principal for this subvolume), OverridePin on a subvolume or group.
  3. Hand it to the SUT: pass fs.FilesystemName and Subvolume.Path, and run the client with grant.Client.WithIdentity() (the restricted principal) or cluster.WithClient() (admin keyring).
  4. Observe: subvolume.Info, subvolume.GroupInfo, subvolume.SnapshotInfo, subvolume.Names, subvolume.GroupNames and subvolume.AuthorizedClients read native state by name, including resources the SUT created; Subvolume.Snapshots, Clone.Status and PinPolicy read an owned resource, and Clone.Watch reports the changes of an owned clone request.
  5. Clean up: terminate the cluster; it removes the filesystem with every owned resource and principal. Use Remove, Clone.RemovePartial, Authorization.Deauthorize, Authorization.EvictClients and PinOverrideHandle.Restore only to test those steps or to restore state mid-test.
cluster, err := cephfs.Run(ctx, ceph.DefaultImage)
testcontainers.CleanupContainer(t, cluster)
if err != nil {
	t.Fatal(err)
}
fs := cephfs.Filesystems(cluster.Container)[0] // tc-cephfs
volume, err := subvolume.Create(ctx, fs, subvolume.Config{Name: "app", SizeBytes: 64 << 20, NamespaceIsolated: true})
if err != nil {
	t.Fatal(err)
}
grant, err := volume.Authorize(ctx, subvolume.AuthorizationConfig{ClientID: "app", Access: "rw"})
if err != nil {
	t.Fatal(err)
}
client, err := testcontainers.Run(ctx, appImage, grant.Client.WithIdentity())
testcontainers.CleanupContainer(t, client)
if err != nil {
	t.Fatal(err)
}
// The client mounts fs.FilesystemName with libcephfs and works under volume.Path.

To act on an asynchronous clone while it runs, clone.Watch(ctx, cfg) polls its native status in one goroutine and sends changes on one channel, Progress included, exactly as Ceph reports it. Receive the baseline before you cancel the clone or inject the fault. A complete, failed or canceled status is the last event, and Stop then returns nil: a failed clone is an outcome in that event, not a watch error. A replaced or removed target, source or filesystem and cluster termination end the watch. Stopping the watch never cancels the clone, and Clone.Wait stays the readiness result. The lifecycle that every Watch shares (baseline, gaps, overflow and Stop) is in watching state.

Concepts and limits

  • A handle is bound to the native resource it created: its filesystem, path and birth time. Editing its exported fields does not redirect an operation, copies share their state, and a replaced resource or a handle of another filesystem is refused. The name-based functions grant no ownership.
  • Creation refuses an existing name instead of relying on Ceph's idempotent create, which could change an existing quota or layout. A non-nil handle returned with an error records an attempted creation; only a confirmed one can be changed.
  • Do not race the operations with raw ceph fs subvolume edits on the same resources; the CLI has no compare-and-swap. Operations of one filesystem wait for each other within the caller's context.
  • Authorize needs a namespace-isolated subvolume and creates a fresh principal; it never adopts an existing one. Deauthorize a grant before removing its subvolume.
  • Snapshots do not pause writers: use cephfs/quiesce or application synchronisation. Quota enforcement and usage accounting are native and can lag writes; removal moves data to Ceph's trash and purges asynchronously.
  • Restore every pin override on a subvolume or group before removing it. A live override blocks removal with ceph.ErrInvalidRequest. If Restore finds an outside value on the same directory and inode, it preserves that value, releases the field and returns ceph.ErrInvalidRequest. The old handle keeps that error. Removal can proceed once the other overrides settle.
  • Pin reads and clone identity checks run libcephfs in the client container, so the client image needs the Python cephfs binding. A pin policy reports the local virtual xattrs, not inherited policy or actual MDS authority.

Reference

The full contract of every type and function is in go doc: pkg.go.dev or go doc -all github.com/JSYoo5B/ceph-testcontainers-go/cephfs/subvolume. See also Native commands for what has no typed API, Contexts and cleanup and Errors.

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

Examples

Constants

This section is empty.

Variables

This section is empty.

Functions

func GroupNames

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

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.

func Names

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

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

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

type AuthorizationConfig struct {
	ClientID string
	Access   string
}

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

type AuthorizedClient struct {
	AuthID string
	Access string
}

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

func (clone *Clone) 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 (*Clone) RemovePartial

func (clone *Clone) 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 (*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

func (clone *Clone) 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 (*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
	}
}

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) PinPolicy

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

PinPolicy reads an owned group's local directory policies.

func (*Group) Remove

func (group *Group) 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. Restore this group's pin overrides first. External edits must not race removal.

func (*Group) Resize

func (group *Group) 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.

type GroupConfig

type GroupConfig struct {
	Name      string
	SizeBytes int64
	DataPool  string
}

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.

func Info

func Info(ctx context.Context, fs *cephfs.Filesystem, name, groupName string) (*Metadata, error)

Info queries the current metadata of a subvolume in fs. 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.

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

type PinSetting struct {
	Type  PinType
	Value float64
}

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

func (snapshot *Snapshot) Clone(ctx context.Context, config CloneConfig) (*Clone, 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 Clone.RemovePartial or raw Ceph cleanup.

func (*Snapshot) Remove

func (snapshot *Snapshot) 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.

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

func Create(ctx context.Context, fs *cephfs.Filesystem, config Config) (*Subvolume, error)

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

func (subvolume *Subvolume) CreateSnapshot(ctx context.Context, name string) (*Snapshot, 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.

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

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

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. Restore this subvolume's pin overrides first. Its filesystem, groups and pools remain available.

func (*Subvolume) Resize

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 Group.Resize.

func (*Subvolume) Snapshots

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.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL