ganeti.storage.base.BlockDev

class documentation

class BlockDev(object):

Known subclasses: ganeti.storage.bdev.LogicalVolume, ganeti.storage.bdev.PersistentBlockDevice, ganeti.storage.bdev.RADOSBlockDevice, ganeti.storage.drbd.DRBD8Dev, ganeti.storage.extstorage.ExtStorageDevice, ganeti.storage.filestorage.FileStorage, ganeti.storage.gluster.GlusterStorage

View In Hierarchy

Block device abstract class.

A block device can be in the following states:

not existing on the system, and by `Create()` it goes into:
existing but not setup/not active, and by `Assemble()` goes into:
active read-write and by `Open()` it goes into
online (=used, or ready for use)

A device can also be online but read-only, however we are not using the readonly state (LV has it, if needed in the future) and we are usually looking at this like at a stack, so it's easier to conceptualise the transition from not-existing to online and back like a linear one.

The many different states of the device are due to the fact that we need to cover many device types:

logical volumes are created, lvchange -a y $lv, and used
drbd devices are attached to a local disk/remote peer and made primary

A block device is identified by three items:

the /dev path of the device (dynamic)
a unique ID of the device (static)
it's major/minor pair (dynamic)

Not all devices implement both the first two as distinct items. LVM logical volumes have their unique ID (the pair volume group, logical volume name) in a 1-to-1 relation to the dev path. For DRBD devices, the /dev path is again dynamic and the unique id is the pair (host1, dev1), (host2, dev2).

You can get to a device in two ways:

creating the (real) device, which returns you an attached instance (lvcreate)
attaching of a python instance to an existing (real) device

The second point, the attachment to a device, is different depending on whether the device is assembled or not. At init() time, we search for a device with the same unique_id as us. If found, good. It also means that the device is already assembled. If not, after assembly we'll have our correct major/minor.

Class Method	`Create`	Create the device.
Method	`__eq__`	Undocumented
Method	`__init__`	Undocumented
Method	`__repr__`	Undocumented
Method	`Assemble`	Assemble the device from its components.
Method	`Attach`	Find a device which matches our config and attach to it.
Method	`Close`	Notifies that the device will no longer be used for I/O.
Method	`CombinedSyncStatus`	Calculate the mirror status recursively for our children.
Method	`Export`	Builds the shell command for exporting data from device.
Method	`GetActualDimensions`	Return the actual disk size and number of spindles used.
Method	`GetActualSize`	Return the actual disk size.
Method	`GetActualSpindles`	Return the actual number of spindles used.
Method	`GetSyncStatus`	Returns the sync status of the device.
Method	`GetUserspaceAccessUri`	Return URIs hypervisors can use to access disks in userspace mode.
Method	`Grow`	Grow the block device.
Method	`Import`	Builds the shell command for importing data to device.
Method	`Open`	Make the device ready for use.
Method	`PauseResumeSync`	Pause/Resume the sync of the mirror.
Method	`Remove`	Remove this device.
Method	`Rename`	Rename this device.
Method	`SetInfo`	Update metadata with info text.
Method	`SetSyncParams`	Adjust the synchronization parameters of the mirror.
Method	`Shutdown`	Shut down the device, freeing its children.
Method	`Snapshot`	Creates a snapshot of the block device.
Instance Variable	`attached`	Undocumented
Instance Variable	`dev_path`	Undocumented
Instance Variable	`dyn_params`	Undocumented
Instance Variable	`major`	Undocumented
Instance Variable	`minor`	Undocumented
Instance Variable	`params`	Undocumented
Instance Variable	`size`	Undocumented
Instance Variable	`unique_id`	Undocumented
Instance Variable	`_children`	Undocumented

@classmethod
def Create(cls, unique_id, children, size, spindles, params, excl_stor, dyn_params, **kwargs): ¶

overridden in ganeti.storage.bdev.LogicalVolume, ganeti.storage.bdev.PersistentBlockDevice, ganeti.storage.bdev.RADOSBlockDevice, ganeti.storage.drbd.DRBD8Dev, ganeti.storage.extstorage.ExtStorageDevice, ganeti.storage.filestorage.FileStorage, ganeti.storage.gluster.GlusterStorage

Create the device.

If the device cannot be created, it will return None instead. Error messages go to the logging system.

Note that for some devices, the unique_id is used, and for other, the children. The idea is that these two, taken together, are enough for both creation and assembly (later).

Parameters
unique_id:2-element tuple or list	unique identifier; the details depend on the actual device type
children:list of `BlockDev`	for hierarchical devices, the child devices
size:float	size in MiB
spindles:int	number of physical disk to dedicate to the device
params:dict	device-specific options/parameters
excl_stor:bool	whether exclusive_storage is active
dyn_params:dict	dynamic parameters of the disk only valid for this node. As set by `objects.Disk.UpdateDynamicDiskParams`.
**kwargs	Undocumented
Returns
`BlockDev`	the created device, or `None` in case of an error

def __eq__(self, other): ¶

Undocumented

def __init__(self, unique_id, children, size, params, dyn_params, **kwargs): ¶

Undocumented

def __repr__(self): ¶

Undocumented

def Assemble(self): ¶

Assemble the device from its components.

Implementations of this method by child classes must ensure that:

after the device has been assembled, it knows its major/minor numbers; this allows other devices (usually parents) to probe correctly for their children
calling this method on an existing, in-use device is safe
if the device is already configured (and in an OK state), this method is idempotent

def Attach(self, **kwargs): ¶

Find a device which matches our config and attach to it.

def Close(self): ¶

Notifies that the device will no longer be used for I/O.

def CombinedSyncStatus(self): ¶

Calculate the mirror status recursively for our children.

The return value is the same as for `GetSyncStatus()` except the minimum percent and maximum time are calculated across our children.

Returns
objects.BlockDevStatus	Undocumented

def Export(self): ¶

overridden in ganeti.storage.bdev.RADOSBlockDevice

Builds the shell command for exporting data from device.

This method returns the command that will be used by the caller to export data from the source device during the disk template conversion operation.

Block devices that provide a more efficient way to transfer their data can override this method to use their specific utility.

Returns
list of strings	List containing the export command for device

def GetActualDimensions(self): ¶

Return the actual disk size and number of spindles used.

Returns
tuple	(size, spindles); spindles is `None` when they are not supported
Note
the device needs to be active when this is called

def GetActualSize(self): ¶

overridden in ganeti.storage.filestorage.FileStorage, ganeti.storage.gluster.GlusterStorage

Return the actual disk size.

Note
the device needs to be active when this is called

def GetActualSpindles(self): ¶

overridden in ganeti.storage.bdev.LogicalVolume

Return the actual number of spindles used.

This is not supported by all devices; if not supported, None is returned.

Note
the device needs to be active when this is called

def GetSyncStatus(self): ¶

overridden in ganeti.storage.bdev.LogicalVolume, ganeti.storage.drbd.DRBD8Dev

Returns the sync status of the device.

If this device is a mirroring device, this function returns the status of the mirror.

If sync_percent is None, it means the device is not syncing.

If estimated_time is None, it means we can't estimate the time needed, otherwise it's the time left in seconds.

If is_degraded is True, it means the device is missing redundancy. This is usually a sign that something went wrong in the device setup, if sync_percent is None.

The ldisk parameter represents the degradation of the local data. This is only valid for some devices, the rest will always return False (not degraded).

Returns
objects.BlockDevStatus	Undocumented

def GetUserspaceAccessUri(self, hypervisor): ¶

overridden in ganeti.storage.bdev.RADOSBlockDevice, ganeti.storage.extstorage.ExtStorageDevice, ganeti.storage.gluster.GlusterStorage

Return URIs hypervisors can use to access disks in userspace mode.

Returns
string	userspace device URI
Raises
`errors.BlockDeviceError`	if userspace access is not supported

def Grow(self, amount, dryrun, backingstore, excl_stor): ¶

Grow the block device.

Parameters
amount:integer	the amount (in mebibytes) to grow with
dryrun:boolean	whether to execute the operation in simulation mode only, without actually increasing the size
backingstore	whether to execute the operation on backing storage only, or on "logical" storage only; e.g. DRBD is logical storage, whereas LVM, file, RBD are backing storage
excl_stor:boolean	Whether exclusive_storage is active

def Import(self): ¶

overridden in ganeti.storage.bdev.PersistentBlockDevice, ganeti.storage.bdev.RADOSBlockDevice

Builds the shell command for importing data to device.

This method returns the command that will be used by the caller to import data to the target device during the disk template conversion operation.

Block devices that provide a more efficient way to transfer their data can override this method to use their specific utility.

Returns
list of strings	List containing the import command for device

def Open(self, force=False, exclusive=True): ¶

Make the device ready for use.

This makes the device ready for I/O.

The force parameter signifies that if the device has any kind of --force thing, it should be used, we know what we are doing.

The exclusive parameter denotes whether the device will be opened for exclusive access (True) or for concurrent shared access by multiple nodes (False) (e.g. during migration).

Parameters
force:boolean	Undocumented
exclusive	Undocumented

def PauseResumeSync(self, pause): ¶

overridden in ganeti.storage.drbd.DRBD8Dev

Pause/Resume the sync of the mirror.

In case this is not a mirroring device, this is no-op.

Parameters
pause:boolean	Whether to pause or resume

def Remove(self): ¶

Remove this device.

This makes sense only for some of the device types: LV and file storage. Also note that if the device can't attach, the removal can't be completed.

def Rename(self, new_id): ¶

Rename this device.

This may or may not make sense for a given device type.

def SetInfo(self, text): ¶

overridden in ganeti.storage.bdev.LogicalVolume, ganeti.storage.extstorage.ExtStorageDevice

Update metadata with info text.

Only supported for some device types.

def SetSyncParams(self, params): ¶

overridden in ganeti.storage.drbd.DRBD8Dev

Adjust the synchronization parameters of the mirror.

In case this is not a mirroring device, this is no-op.

Parameters
params	dictionary of LD level disk parameters related to the synchronization.
Returns
list	a list of error messages, emitted both by the current node and by children. An empty list means no errors.

def Shutdown(self): ¶

Shut down the device, freeing its children.

This undoes the `Assemble()` work, except for the child assembling; as such, the children on the device are still assembled after this call.

def Snapshot(self, snap_name, snap_size): ¶

overridden in ganeti.storage.bdev.LogicalVolume, ganeti.storage.extstorage.ExtStorageDevice

Creates a snapshot of the block device.

Currently this is used only during LUInstanceExport.

Parameters
snap_name:string	The name of the snapshot.
snap_size:int	The size of the snapshot.
Returns
tuple	The logical id of the newly created disk.

attached: bool = ¶

Undocumented

dev_path = ¶

Undocumented

dyn_params = ¶

Undocumented

major = ¶

Undocumented

minor = ¶

Undocumented

params = ¶

Undocumented

size = ¶

Undocumented

unique_id = ¶

Undocumented

_children = ¶

overridden in ganeti.storage.drbd.DRBD8Dev

Undocumented