volume

README

Volume Drivers

Volume drivers implement the Volume Plugin Interface. This provides an interface to register a volume driver and advertise the driver to Docker. Registering a driver with this volume interface will cause Docker to be able to communicate with the driver to create and assign volumes to a container.

A volume spec is needed to create a volume. A volume spec looks like:

// VolumeSpec has the properties needed to create a volume.
type VolumeSpec struct {
	// Ephemeral storage
	Ephemeral bool
	// Thin provisioned volume size in bytes
	Size uint64
	// Format disk with this FileSystem
	Format Filesystem
	// BlockSize for file system
	BlockSize int
	// HA Level specifies the number of nodes that are
	// allowed to fail, and yet data is availabel.
	// A value of 0 implies that data is not erasure coded,
	// a failure of a node will lead to data loss.
	HALevel int
	// This disk's CoS
	Cos VolumeCos
	// Perform dedupe on this disk
	Dedupe bool
	// SnapshotInterval in minutes, set to 0 to disable Snapshots
	SnapshotInterval int
	// Volume configuration labels
	ConfigLabels Labels
}

Various volume driver implementations can be found in the drivers directory.

Block Drivers

Block drivers operate at the block layer. They provide raw volumes formatted with a user specified filesystem. This volume is then mounted into the container at a path specified using the docker run -v option.

File Drivers

File drivers operate at the filesystem layer.

Documentation

Index

• Constants
• Variables
• func CloudBackupWaitForCompletion(cl CloudBackupDriver, taskId string, opType api.CloudBackupOpType) error
• func NewCredentialError(msg string) error
• type BlockDriver
• type CloudBackupDriver
• type CloudMigrateDriver
• type CredentialError
  • func (e *CredentialError) Error() string
• type CredsDriver
• type Enumerator
• type FilesystemCheckDriver
• type FilesystemTrimDriver
• type IODriver
• type ProtoDriver
• type QuiesceDriver
• type SnapshotDriver
• type StatsDriver
• type Store
• type StoreEnumerator
• type VolumeDriver
• type VolumeDriverProvider
• type VolumeDriverRegistry
  • func NewVolumeDriverRegistry(nameToInitFunc map[string]func(map[string]string) (VolumeDriver, error)) VolumeDriverRegistry

Constants

const (
	// APIVersion for the volume management apis
	APIVersion = "v1"
	// PluginAPIBase where the docker unix socket resides
	PluginAPIBase = "/run/docker/plugins/"
	// DriverAPIBase where the osd unix socket resides
	DriverAPIBase = "/var/lib/osd/driver/"
	// MountBase for osd mountpoints
	MountBase = "/var/lib/osd/mounts/"
	// VolumeBase for osd volumes
	VolumeBase = "/var/lib/osd/"
)

Constants used by the VolumeDriver

const (
	// LocationConstaint is a label that specifies data location constraint.
	LocationConstraint = "LocationConstraint"
	// LocalNode is an alias for this node - similar to localhost.
	LocalNode = "LocalNode"
	// FromTrashCan is a label that specified a volume being in the TrashCan
	FromTrashCan = "FromTrashCan"
)

Variables

var (
	// ErrAlreadyShutdown returned when driver is shutdown
	ErrAlreadyShutdown = errors.New("VolumeDriverProvider already shutdown")
	// ErrExit returned when driver already registered
	ErrExist = errors.New("Already exists")
	// ErrDriverNotFound returned when a driver is not registered
	ErrDriverNotFound = errors.New("Driver implementation not found")
	// ErrDriverInitializing returned when a driver is initializing
	ErrDriverInitializing = errors.New("Driver is initializing")
	// ErrEnoEnt returned when volume does not exist
	ErrEnoEnt = errors.New("Volume does not exist.")
	// ErrEnomem returned when we are out of memory
	ErrEnomem = errors.New("Out of memory.")
	// ErrEinval returned when an invalid input is provided
	ErrEinval = errors.New("Invalid argument")
	// ErrVolDetached returned when volume is in detached state
	ErrVolDetached = errors.New("Volume is detached")
	// ErrAttachedHostSpecNotFound returned when the attached host's spec is not found
	ErrAttachedHostSpecNotFound = errors.New("Spec of the attached host is not found")
	// ErrVolAttached returned when volume is in attached state
	ErrVolAttached = errors.New("Volume is attached")
	// ErrVolAttachedOnRemoteNode returned when volume is attached on different node
	ErrVolAttachedOnRemoteNode = errors.New("Volume is attached on another node")
	// ErrNonSharedVolAttachedOnRemoteNode returned when a non-shared volume is attached on different node
	ErrNonSharedVolAttachedOnRemoteNode = errors.New("Non-shared volume is already attached on another node." +
		" Non-shared volumes can only be attached on one node at a time.")
	// ErrVolAttachedScale returned when volume is attached and can be scaled
	ErrVolAttachedScale = errors.New("Volume is attached on another node." +
		" Increase scale factor to create more instances")
	// ErrVolHasSnaps returned when volume has previous snapshots
	ErrVolHasSnaps = errors.New("Volume has snapshots associated")
	// ErrNotSupported returned when the operation is not supported
	ErrNotSupported = errors.New("Operation not supported")
	// ErrVolBusy returned when volume is in busy state
	ErrVolBusy = errors.New("Volume is busy")
	// ErrAborted returned when capacityUsageInfo cannot be returned
	ErrAborted = errors.New("Aborted CapacityUsage request")
	// ErrInvalidName returned when Cloudbackup Name/request is invalid
	ErrInvalidName = errors.New("Invalid name for cloud backup/restore request")
	// ErrFsResizeFailed returned when Filesystem resize failed because of filesystem
	// errors
	ErrFsResizeFailed = errors.New("Filesystem Resize failed due to filesystem errors")
	// ErrNoVolumeUpdate is returned when a volume update has no changes requested
	ErrNoVolumeUpdate = errors.New("No change requested")
)

var (
	// BlockNotSupported is a default (null) block driver implementation.  This can be
	// used by drivers that do not want to (or care about) implementing the attach,
	// format and detach interfaces.
	BlockNotSupported = &blockNotSupported{}
	// SnapshotNotSupported is a null snapshot driver implementation. This can be used
	// by drivers that do not want to implement the snapshot interface
	SnapshotNotSupported = &snapshotNotSupported{}
	// IONotSupported is a null IODriver interface
	IONotSupported = &ioNotSupported{}
	// StatsNotSupported is a null stats driver implementation. This can be used
	// by drivers that do not want to implement the stats interface.
	StatsNotSupported = &statsNotSupported{}
	// QuiesceNotSupported implements quiesce/unquiesce by returning not
	// supported error.
	QuiesceNotSupported = &quiesceNotSupported{}
	// CredsNotSupported implements credentials by returning not supported error
	CredsNotSupported = &credsNotSupported{}
	// CloudBackupNotSupported implements cloudBackupDriver by returning
	// Not supported error
	CloudBackupNotSupported = &cloudBackupNotSupported{}
	// CloudMigrateNotSupported implements cloudMigrateDriver by returning
	// Not supported error
	CloudMigrateNotSupported = &cloudMigrateNotSupported{}
	// FilesystemTrimNotSupported implements FilesystemTrimDriver by returning
	// Not supported error
	FilesystemTrimNotSupported = &filesystemTrimNotSupported{}
	// FilesystemCheckNotSupported implements FilesystemCheckDriver by returning
	// Not supported error
	FilesystemCheckNotSupported = &filesystemCheckNotSupported{}
)

Functions

func CloudBackupWaitForCompletion

func CloudBackupWaitForCompletion(
	cl CloudBackupDriver,
	taskId string,
	opType api.CloudBackupOpType,
) error

func NewCredentialError

func NewCredentialError(msg string) error

Types

type BlockDriver

type BlockDriver interface {
	// Attach map device to the host.
	// On success the devicePath specifies location where the device is exported
	// Errors ErrEnoEnt, ErrVolAttached may be returned.
	Attach(ctx context.Context, volumeID string, attachOptions map[string]string) (string, error)
	// Detach device from the host.
	// Errors ErrEnoEnt, ErrVolDetached may be returned.
	Detach(ctx context.Context, volumeID string, options map[string]string) error
}

BlockDriver needs to be implemented by block volume drivers. Filesystem volume drivers can ignore this interface and include the builtin DefaultBlockDriver.

type CloudBackupDriver

type CloudBackupDriver interface {
	// CloudBackupCreate uploads snapshot of a volume to the cloud
	CloudBackupCreate(input *api.CloudBackupCreateRequest) (*api.CloudBackupCreateResponse, error)
	// CloudBackupGroupCreate creates and then uploads volumegroup snapshots
	CloudBackupGroupCreate(input *api.CloudBackupGroupCreateRequest) (*api.CloudBackupGroupCreateResponse, error)
	// CloudBackupRestore downloads a cloud backup and restores it to a volume
	CloudBackupRestore(input *api.CloudBackupRestoreRequest) (*api.CloudBackupRestoreResponse, error)
	// CloudBackupEnumerate enumerates the backups for a given cluster/credential/volumeID
	CloudBackupEnumerate(input *api.CloudBackupEnumerateRequest) (*api.CloudBackupEnumerateResponse, error)
	// CloudBackupDelete deletes the specified backup in cloud
	CloudBackupDelete(input *api.CloudBackupDeleteRequest) error
	// CloudBackupDelete deletes all the backups for a given volume in cloud
	CloudBackupDeleteAll(input *api.CloudBackupDeleteAllRequest) error
	// CloudBackupStatus indicates the most recent status of backup/restores
	CloudBackupStatus(input *api.CloudBackupStatusRequest) (*api.CloudBackupStatusResponse, error)
	// CloudBackupCatalog displays listing of backup content
	CloudBackupCatalog(input *api.CloudBackupCatalogRequest) (*api.CloudBackupCatalogResponse, error)
	// CloudBackupHistory displays past backup/restore operations on a volume
	CloudBackupHistory(input *api.CloudBackupHistoryRequest) (*api.CloudBackupHistoryResponse, error)
	// CloudBackupStateChange allows a current backup state transisions(pause/resume/stop)
	CloudBackupStateChange(input *api.CloudBackupStateChangeRequest) error
	// CloudBackupSchedCreate creates a schedule to backup volume to cloud
	CloudBackupSchedCreate(input *api.CloudBackupSchedCreateRequest) (*api.CloudBackupSchedCreateResponse, error)
	// CloudBackupGroupSchedCreate creates a schedule to backup a volumegroup to cloud
	CloudBackupGroupSchedCreate(input *api.CloudBackupGroupSchedCreateRequest) (*api.CloudBackupSchedCreateResponse, error)
	// CloudBackupSchedCreate creates a schedule to backup volume to cloud
	CloudBackupSchedUpdate(input *api.CloudBackupSchedUpdateRequest) error
	// CloudBackupGroupSchedCreate creates a schedule to backup a volumegroup to cloud
	CloudBackupGroupSchedUpdate(input *api.CloudBackupGroupSchedUpdateRequest) error
	// CloudBackupSchedDelete delete a backup schedule
	CloudBackupSchedDelete(input *api.CloudBackupSchedDeleteRequest) error
	// CloudBackupSchedEnumerate enumerates the configured backup schedules in the cluster
	CloudBackupSchedEnumerate() (*api.CloudBackupSchedEnumerateResponse, error)
	// CloudBackupSize fetches the size of a cloud backup
	CloudBackupSize(input *api.SdkCloudBackupSizeRequest) (*api.SdkCloudBackupSizeResponse, error)
}

CloudBackupDriver interface provides Cloud backup features

type CloudMigrateDriver

type CloudMigrateDriver interface {
	// CloudMigrateStart starts a migrate operation
	CloudMigrateStart(request *api.CloudMigrateStartRequest) (*api.CloudMigrateStartResponse, error)
	// CloudMigrateCancel cancels a migrate operation
	CloudMigrateCancel(request *api.CloudMigrateCancelRequest) error
	// CloudMigrateStatus returns status for the migration operations
	CloudMigrateStatus(request *api.CloudMigrateStatusRequest) (*api.CloudMigrateStatusResponse, error)
}

CloudMigrateDriver interface provides Cloud migration features

type CredentialError

type CredentialError struct {
	// Msg is human understandable error message
	Msg string
}

CredentialError error returned for credential operations

func (*CredentialError) Error

func (e *CredentialError) Error() string

type CredsDriver

type CredsDriver interface {
	// CredsCreate creates credential for a given cloud provider
	CredsCreate(params map[string]string) (string, error)
	// CredsUpdate updates credential for an already configured credential
	CredsUpdate(name string, params map[string]string) error
	// CredsEnumerate lists the configured credentials in the cluster
	CredsEnumerate() (map[string]interface{}, error)
	// CredsDelete deletes the credential associated credUUID
	CredsDelete(credUUID string) error
	// CredsValidate validates the credential associated credUUID
	CredsValidate(credUUID string) error
	// CredsDeleteReferences delets any  with the creds
	CredsDeleteReferences(credUUID string) error
}

CredsDriver provides methods to handle credentials

type Enumerator

type Enumerator interface {
	// Inspect specified volumes.
	// Returns slice of volumes that were found.
	Inspect(volumeIDs []string) ([]*api.Volume, error)
	// Enumerate volumes that map to the volumeLocator. Locator fields may be regexp.
	// If locator fields are left blank, this will return all volumes.
	Enumerate(locator *api.VolumeLocator, labels map[string]string) ([]*api.Volume, error)
	// Enumerate snaps for specified volumes
	SnapEnumerate(volID []string, snapLabels map[string]string) ([]*api.Volume, error)
}

Enumerator provides a set of interfaces to get details on a set of volumes.

type FilesystemCheckDriver

type FilesystemCheckDriver interface {
	// FilesystemCheckStart starts a filesystem check background operation
	// on a specified volume
	FilesystemCheckStart(request *api.SdkFilesystemCheckStartRequest) (*api.SdkFilesystemCheckStartResponse, error)
	// FilesystemCheckStatus returns the status of a filesystem check
	// background operation on the filesystem of a specified volume, if any.
	FilesystemCheckStatus(request *api.SdkFilesystemCheckStatusRequest) (*api.SdkFilesystemCheckStatusResponse, error)
	// FilesystemCheckStop stops the filesystem check background operation on
	// the filesystem of a specified volume, if any.
	FilesystemCheckStop(request *api.SdkFilesystemCheckStopRequest) (*api.SdkFilesystemCheckStopResponse, error)
}

FilesystemCheckDriver interface exposes APIs to manage filesystem check operation on a volume

type FilesystemTrimDriver

type FilesystemTrimDriver interface {
	// FilesystemTrimStart starts a filesystem trim background operation on a
	// specified volume
	FilesystemTrimStart(request *api.SdkFilesystemTrimStartRequest) (*api.SdkFilesystemTrimStartResponse, error)
	// FilesystemTrimStatus returns the status of a filesystem trim
	// background operation on a specified volume, if any
	FilesystemTrimStatus(request *api.SdkFilesystemTrimStatusRequest) (*api.SdkFilesystemTrimStatusResponse, error)
	// AutoFilesystemTrimStatus returns the status of auto fs trim
	// operations on volumes
	AutoFilesystemTrimStatus(request *api.SdkAutoFSTrimStatusRequest) (*api.SdkAutoFSTrimStatusResponse, error)
	// AutoFilesystemTrimUsage returns the volume usage and trimmable
	// space of locally mounted pxd volumes
	AutoFilesystemTrimUsage(request *api.SdkAutoFSTrimUsageRequest) (*api.SdkAutoFSTrimUsageResponse, error)
	// FilesystemTrimStop stops a filesystem trim background operation on
	// a specified volume, if any
	FilesystemTrimStop(request *api.SdkFilesystemTrimStopRequest) (*api.SdkFilesystemTrimStopResponse, error)
}

FilesystemTrimDriver interface exposes APIs to manage filesystem trim operation on a volume

type IODriver

type IODriver interface {
	// Read sz bytes from specified volume at specified offset.
	// Return number of bytes read and error.
	Read(volumeID string, buf []byte, sz uint64, offset int64) (int64, error)
	// Write sz bytes from specified volume at specified offset.
	// Return number of bytes written and error.
	Write(volumeID string, buf []byte, sz uint64, offset int64) (int64, error)
	// Flush writes to stable storage.
	// Return error.
	Flush(volumeID string) error
}

IODriver interfaces applicable to object store interfaces.

type ProtoDriver

type ProtoDriver interface {
	SnapshotDriver
	StatsDriver
	QuiesceDriver
	CredsDriver
	CloudBackupDriver
	CloudMigrateDriver
	FilesystemTrimDriver
	FilesystemCheckDriver
	// Name returns the name of the driver.
	Name() string
	// Type of this driver
	Type() api.DriverType
	// Version information of the driver
	Version() (*api.StorageVersion, error)
	// Create a new Vol for the specific volume spec.
	// It returns a system generated VolumeID that uniquely identifies the volume
	Create(ctx context.Context, locator *api.VolumeLocator, Source *api.Source, spec *api.VolumeSpec) (string, error)
	// Delete volume.
	// Errors ErrEnoEnt, ErrVolHasSnaps may be returned.
	Delete(ctx context.Context, volumeID string) error
	// Mount volume at specified path
	// Errors ErrEnoEnt, ErrVolDetached may be returned.
	Mount(ctx context.Context, volumeID string, mountPath string, options map[string]string) error
	// MountedAt return volume mounted at specified mountpath.
	MountedAt(ctx context.Context, mountPath string) string
	// Unmount volume at specified path
	// Errors ErrEnoEnt, ErrVolDetached may be returned.
	Unmount(ctx context.Context, volumeID string, mountPath string, options map[string]string) error
	// Update not all fields of the spec are supported, ErrNotSupported will be thrown for unsupported
	// updates.
	Set(volumeID string, locator *api.VolumeLocator, spec *api.VolumeSpec) error
	// Status returns a set of key-value pairs which give low
	// level diagnostic status about this driver.
	Status() [][2]string
	// Shutdown and cleanup.
	Shutdown()
	// DU specified volume and potentially the subfolder if provided.
	Catalog(volumeid, subfolder string, depth string) (api.CatalogResponse, error)
	// Does a Filesystem Trim operation to free unused space to block device(block discard)
	VolService(volumeID string, vsreq *api.VolumeServiceRequest) (*api.VolumeServiceResponse, error)
}

ProtoDriver must be implemented by all volume drivers. It specifies the most basic functionality, such as creating and deleting volumes.

type QuiesceDriver

type QuiesceDriver interface {
	// Freezes mounted filesystem resulting in a quiesced volume state.
	// Only one freeze operation may be active at any given time per volume.
	// Unfreezes after timeout seconds if it is non-zero.
	// An optional quiesceID can be passed for driver-specific use.
	Quiesce(volumeID string, timeoutSeconds uint64, quiesceID string) error
	// Unfreezes mounted filesystem if it was frozen.
	Unquiesce(volumeID string) error
}

type SnapshotDriver

type SnapshotDriver interface {
	// Snapshot create volume snapshot.
	// Errors ErrEnoEnt may be returned
	Snapshot(volumeID string, readonly bool, locator *api.VolumeLocator, noRetry bool) (string, error)
	// Restore restores volume to specified snapshot.
	Restore(volumeID string, snapshotID string) error
	// SnapshotGroup takes a snapshot of a group of volumes that can be specified with either of the following
	//	1. group ID
	//	2. labels
	//	3. volumeIDs
	//	deleteOnFailure indicates whether to delete the successful snaps if some of the snapshots failed
	SnapshotGroup(groupID string, labels map[string]string, volumeIDs []string, deleteOnFailure bool) (*api.GroupSnapCreateResponse, error)
}

SnapshotDriver interfaces provides snapshot capability

type StatsDriver

type StatsDriver interface {
	// Stats for specified volume.
	// cumulative stats are /proc/diskstats style stats.
	// nonCumulative stats are stats for specific duration.
	// Errors ErrEnoEnt may be returned
	Stats(volumeID string, cumulative bool) (*api.Stats, error)
	// UsedSize returns currently used volume size.
	// Errors ErrEnoEnt may be returned.
	UsedSize(volumeID string) (uint64, error)
	// GetActiveRequests get active requests
	GetActiveRequests() (*api.ActiveRequests, error)
	// CapacityUsage returns both exclusive and shared usage
	// of a snap/volume
	CapacityUsage(ID string) (*api.CapacityUsageResponse, error)
	// VolumeUsageByNode returns capacity usage of all volumes and snaps for a
	// given node
	VolumeUsageByNode(nodeID string) (*api.VolumeUsageByNode, error)
}

StatsDriver interface provides stats features

type Store

type Store interface {
	// Lock volume specified by volumeID.
	Lock(volumeID string) (interface{}, error)
	// Lock volume with token obtained from call to Lock.
	Unlock(token interface{}) error
	// CreateVol returns error if volume with the same ID already existe.
	CreateVol(vol *api.Volume) error
	// GetVol from volumeID.
	GetVol(volumeID string) (*api.Volume, error)
	// UpdateVol with vol
	UpdateVol(vol *api.Volume) error
	// DeleteVol. Returns error if volume does not exist.
	DeleteVol(volumeID string) error
}

Store defines the interface for basic volume store operations

type StoreEnumerator

type StoreEnumerator interface {
	Store
	Enumerator
}

StoreEnumerator combines Store and Enumerator capabilities

type VolumeDriver

type VolumeDriver interface {
	IODriver
	ProtoDriver
	BlockDriver
	Enumerator
}

VolumeDriver is the main interface to be implemented by any storage driver. Every driver must at minimum implement the ProtoDriver sub interface.

type VolumeDriverProvider

type VolumeDriverProvider interface {
	// Get gets the VolumeDriver for the given name.
	// If a VolumeDriver was not created for the given name, the error ErrDriverNotFound is returned.
	Get(name string) (VolumeDriver, error)
	// Shutdown shuts down all volume drivers.
	Shutdown() error
}

VolumeDriverProvider provides VolumeDrivers.

type VolumeDriverRegistry

type VolumeDriverRegistry interface {
	VolumeDriverProvider
	// New creates the VolumeDriver for the given name.
	// If a VolumeDriver was already created for the given name, the error ErrExist is returned.
	Register(name string, params map[string]string) error

	// Add inserts a new VolumeDriver provider with a well known name.
	Add(name string, init func(map[string]string) (VolumeDriver, error)) error

	// Removes driver from registry. Does nothing if driver name does not exist.
	Remove(name string)
}

VolumeDriverRegistry registers VolumeDrivers.

func NewVolumeDriverRegistry

func NewVolumeDriverRegistry(nameToInitFunc map[string]func(map[string]string) (VolumeDriver, error)) VolumeDriverRegistry

NewVolumeDriverRegistry constructs a new VolumeDriverRegistry.