ganeti.cmdlib.instance

module documentation

Utility function mainly, but not only used by instance LU's.

Function	`ApplyContainerMods`	Applies descriptions in `mods` to `container`.
Function	`BuildDiskEnv`	Helper method to create disk's hooks env
Function	`BuildDiskLogicalIDEnv`	Helper method to create hooks env related to disk's logical_id
Function	`BuildInstanceHookEnv`	Builds instance related env variables for hooks
Function	`BuildInstanceHookEnvByObject`	Builds instance related env variables for hooks from an object.
Function	`CheckCompressionTool`	Checks if the provided compression tool is allowed to be used.
Function	`CheckForConflictingIp`	In case of conflicting IP address raise error.
Function	`CheckHostnameSane`	Ensures that a given hostname resolves to a 'sane' name.
Function	`CheckInstanceBridgesExist`	Check that the brigdes needed by an instance exist.
Function	`CheckInstanceExistence`	Raises an error if an instance with the given name exists already.
Function	`CheckNicsBridgesExist`	Check that the brigdes needed by a list of nics exist.
Function	`CheckNodeFreeMemory`	Checks if a node has enough free memory.
Function	`CheckNodeNotDrained`	Ensure that a given node is not drained.
Function	`CheckNodesPhysicalCPUs`	Checks if nodes have enough physical CPUs
Function	`CheckNodeVmCapable`	Ensure that a given node is vm capable.
Function	`CheckOpportunisticLocking`	Generate error if opportunistic locking is not possible.
Function	`CheckTargetNodeIPolicy`	Checks that the target node is correct in terms of instance policy.
Function	`ComputeFullBeParams`	Computes the full beparams.
Function	`ComputeInstanceCommunicationNIC`	Compute the name of the instance NIC used by instance communication.
Function	`ComputeIPolicyInstanceSpecViolation`	Compute if instance specs meets the specs of ipolicy.
Function	`ComputeNics`	Computes the nics.
Function	`CopyLockList`	Makes a copy of a list of lock names.
Function	`CreateInstanceAllocRequest`	Wrapper around IAReqInstanceAlloc.
Function	`GetClusterDomainSecret`	Reads the cluster domain secret.
Function	`GetIndexFromIdentifier`	Check if the identifier represents a valid container index and return it.
Function	`GetInstanceInfoText`	Compute that text that should be added to the disk's metadata.
Function	`GetItemFromContainer`	Return the item refered by the identifier.
Function	`InsertItemToIndex`	Insert an item to the provided index of a container.
Function	`NICListToTuple`	Build a list of nic information tuples.
Function	`NICToTuple`	Build a tupple of nic information.
Function	`PrepareContainerMods`	Prepares a list of container modifications by adding a private data field.
Function	`ReleaseLocks`	Releases locks owned by an LU.
Function	`RemoveDisks`	Remove all or a subset of disks for an instance.
Function	`RemoveInstance`	Utility function to remove an instance.
Function	`UpdateMetadata`	Updates instance metadata on the metadata daemon on the instance's primary node.
Function	`_ComputeIPolicyNodeViolation`	Compute if instance meets the specs of the new target group.
Function	`_StoragePathsRemoved`	Returns an iterable of all storage paths to be removed.
Variable	`_TApplyContModsCbChanges`	Undocumented

def ApplyContainerMods(kind, container, chgdesc, mods, create_fn, attach_fn, modify_fn, remove_fn, detach_fn, post_add_fn=None): ¶

Applies descriptions in mods to container.

Parameters
kind:string	One-word item description
container:list	Container to modify
chgdesc:None or list	List of applied changes
mods:list	Modifications as returned by `PrepareContainerMods`
create_fn:callable	Callback for creating a new item (`constants.DDM_ADD`); receives absolute item index, parameters and private data object as added by `PrepareContainerMods`, returns tuple containing new item and changes as list
attach_fn:callable	Callback for attaching an existing item to a container (`constants.DDM_ATTACH`); receives absolute item index and item UUID or name, returns tuple containing new item and changes as list
modify_fn:callable	Callback for modifying an existing item (`constants.DDM_MODIFY`); receives absolute item index, item, parameters and private data object as added by `PrepareContainerMods`, returns changes as list
remove_fn:callable	Callback on removing item; receives absolute item index, item and private data object as added by `PrepareContainerMods`
detach_fn:callable	Callback on detaching item; receives absolute item index, item and private data object as added by `PrepareContainerMods`
post_add_fn:callable	Callable for post-processing a newly created item after it has been put into the container. It receives the index of the new item and the new item as parameters.

def BuildDiskEnv(idx, disk): ¶

Helper method to create disk's hooks env

Parameters
idx:integer	The index of the disk
disk:`objects.Disk` or dict	The disk object or a simple dict in case of LUInstanceCreate

def BuildDiskLogicalIDEnv(idx, disk): ¶

Helper method to create hooks env related to disk's logical_id

Parameters
idx:integer	The index of the disk
disk:`objects.Disk`	The disk object

def BuildInstanceHookEnv(name, primary_node_name, secondary_node_names, os_type, status, minmem, maxmem, vcpus, nics, disk_template, disks, bep, hvp, hypervisor_name, tags): ¶

Builds instance related env variables for hooks

This builds the hook environment from individual variables.

Parameters
name:string	the name of the instance
primary_node_name:string	the name of the instance's primary node
secondary_node_names:list	list of secondary nodes as strings
os_type:string	the name of the instance's OS
status:string	the desired status of the instance
minmem:string	the minimum memory size of the instance
maxmem:string	the maximum memory size of the instance
vcpus:string	the count of VCPUs the instance has
nics:list	list of tuples (name, uuid, ip, mac, mode, link, vlan, net, netinfo) representing the NICs the instance has
disk_template:string	the disk template of the instance
disks:list	list of disks (either objects.Disk or dict)
bep:dict	the backend parameters for the instance
hvp:dict	the hypervisor parameters for the instance
hypervisor_name:string	the hypervisor for the instance
tags:list	list of instance tags as strings
Returns
dict	the hook environment for this instance

def BuildInstanceHookEnvByObject(lu, instance, secondary_nodes=None, disks=None, override=None): ¶

Builds instance related env variables for hooks from an object.

Parameters
lu:`LogicalUnit`	the logical unit on whose behalf we execute
instance:`objects.Instance`	the instance for which we should build the environment
secondary_nodes	Undocumented
disks	Undocumented
override:dict	dictionary with key/values that will override our values
Returns
dict	the hook environment dictionary

def CheckCompressionTool(lu, compression_tool): ¶

Checks if the provided compression tool is allowed to be used.

Parameters
lu	Undocumented
compression_tool:string	Compression tool to use for importing or exporting the instance
Returns
NoneType	None
Raises
`errors.OpPrereqError`	If the tool is not enabled by Ganeti or whitelisted

def CheckForConflictingIp(lu, ip, node_uuid): ¶

In case of conflicting IP address raise error.

Parameters
lu	Undocumented
ip:string	IP address
node_uuid:string	node UUID

def CheckHostnameSane(lu, name): ¶

Ensures that a given hostname resolves to a 'sane' name.

The given name is required to be a prefix of the resolved hostname, to prevent accidental mismatches.

Parameters
lu	the logical unit on behalf of which we're checking
name	the name we should resolve and check
Returns
the resolved hostname object

def CheckInstanceBridgesExist(lu, instance, node_uuid=None): ¶

Check that the brigdes needed by an instance exist.

def CheckInstanceExistence(lu, instance_name): ¶

Raises an error if an instance with the given name exists already.

Parameters

lu Undocumented

instance_name:string

The name of the instance.

To be used in the locking phase.

def CheckNicsBridgesExist(lu, nics, node_uuid): ¶

Check that the brigdes needed by a list of nics exist.

def CheckNodeFreeMemory(lu, node_uuid, reason, requested, hvname, hvparams): ¶

Checks if a node has enough free memory.

This function checks if a given node has the needed amount of free memory. In case the node has less memory or we cannot get the information from the node, this function raises an OpPrereqError exception.

Parameters
lu:`LogicalUnit`	a logical unit from which we get configuration data
node_uuid:`str`	the node to check
reason:`str`	string to use in the error message
requested:`int`	the amount of memory in MiB to check for
hvname:string	the hypervisor's name
hvparams:dict of strings	the hypervisor's parameters
Returns
integer	node current free memory
Raises
`errors.OpPrereqError`	if the node doesn't have enough memory, or we cannot check the node

def CheckNodeNotDrained(lu, node_uuid): ¶

Ensure that a given node is not drained.

Parameters
lu	the LU on behalf of which we make the check
node_uuid	the node to check
Raises
`errors.OpPrereqError`	if the node is drained

def CheckNodesPhysicalCPUs(lu, node_uuids, requested, hypervisor_specs): ¶

Checks if nodes have enough physical CPUs

This function checks if all given nodes have the needed number of physical CPUs. In case any node has less CPUs or we cannot get the information from the node, this function raises an OpPrereqError exception.

Parameters
lu:`LogicalUnit`	a logical unit from which we get configuration data
node_uuids:`list`	the list of node UUIDs to check
requested:`int`	the minimum acceptable number of physical CPUs
hypervisor_specs:list of pairs (string, dict of strings)	list of hypervisor specifications in pairs (hypervisor_name, hvparams)
Raises
`errors.OpPrereqError`	if the node doesn't have enough CPUs, or we cannot check the node

def CheckNodeVmCapable(lu, node_uuid): ¶

Ensure that a given node is vm capable.

Parameters
lu	the LU on behalf of which we make the check
node_uuid	the node to check
Raises
`errors.OpPrereqError`	if the node is not vm capable

def CheckOpportunisticLocking(op): ¶

Generate error if opportunistic locking is not possible.

def CheckTargetNodeIPolicy(lu, ipolicy, instance, node, cfg, ignore=False, _compute_fn=_ComputeIPolicyNodeViolation): ¶

Checks that the target node is correct in terms of instance policy.

Parameters
lu	Undocumented
ipolicy	The ipolicy to verify
instance	The instance object to verify
node	The new node to relocate
cfg:`config.ConfigWriter`	Cluster configuration
ignore	Ignore violations of the ipolicy
_compute_fn	The function to verify ipolicy (unittest only)
See Also
`ganeti.cmdlib.common.ComputeIPolicySpecViolation`

def ComputeFullBeParams(op, cluster): ¶

Computes the full beparams.

Parameters
op	The instance opcode
cluster	The cluster config object
Returns
The fully filled beparams

def ComputeInstanceCommunicationNIC(instance_name): ¶

Compute the name of the instance NIC used by instance communication.

With instance communication, a new NIC is added to the instance. This NIC has a special name that identities it as being part of instance communication, and not just a normal NIC. This function generates the name of the NIC based on a prefix and the instance name

Parameters
instance_name:string	name of the instance the NIC belongs to
Returns
string	name of the NIC

def ComputeIPolicyInstanceSpecViolation(ipolicy, instance_spec, disk_types, _compute_fn=ComputeIPolicySpecViolation): ¶

Compute if instance specs meets the specs of ipolicy.

Parameters
ipolicy:dict	The ipolicy to verify against
instance_spec	The instance spec to verify
disk_types:list of strings	the disk templates of the instance
_compute_fn	The function to verify ipolicy (unittest only)
See Also
`ComputeIPolicySpecViolation`

def ComputeNics(op, cluster, default_ip, cfg, ec_id): ¶

Computes the nics.

Parameters
op	The instance opcode
cluster	Cluster configuration object
default_ip	The default ip to assign
cfg	An instance of the configuration object
ec_id	Execution context ID
Returns
The build up nics

def CopyLockList(names): ¶

Makes a copy of a list of lock names.

Handles locking.ALL_SET correctly.

def CreateInstanceAllocRequest(op, disks, nics, beparams, node_name_whitelist): ¶

Wrapper around IAReqInstanceAlloc.

Parameters
op	The instance opcode
disks	The computed disks
nics	The computed nics
beparams	The full filled beparams
node_name_whitelist	List of nodes which should appear as online to the allocator (unless the node is already marked offline)
Returns
A filled `iallocator.IAReqInstanceAlloc`

def GetClusterDomainSecret(): ¶

Reads the cluster domain secret.

def GetIndexFromIdentifier(identifier, kind, container): ¶

Check if the identifier represents a valid container index and return it.

Used in "add" and "attach" actions.

Parameters
identifier:string	Item index or name or UUID
kind:string	Type of item, e.g. "disk", "nic"
container:list	Container to calculate the index from

def GetInstanceInfoText(instance): ¶

Compute that text that should be added to the disk's metadata.

def GetItemFromContainer(identifier, kind, container): ¶

Return the item refered by the identifier.

Parameters
identifier:string	Item index or name or UUID
kind:string	One-word item description
container:list	Container to get the item from

def InsertItemToIndex(identifier, item, container): ¶

Insert an item to the provided index of a container.

Used in "add" and "attach" actions.

Parameters
identifier:string	Item index
item:object	The item to be inserted
container:list	Container to insert the item to

def NICListToTuple(lu, nics): ¶

Build a list of nic information tuples.

This list is suitable to be passed to _BuildInstanceHookEnv or as a return value in LUInstanceQueryData.

Parameters
lu:`LogicalUnit`	the logical unit on whose behalf we execute
nics:list of `objects.NIC`	list of nics to convert to hooks tuples

def NICToTuple(lu, nic): ¶

Build a tupple of nic information.

Parameters
lu:`LogicalUnit`	the logical unit on whose behalf we execute
nic:`objects.NIC`	nic to convert to hooks tuple

def PrepareContainerMods(mods, private_fn): ¶

Prepares a list of container modifications by adding a private data field.

Parameters
mods:list of tuples; (operation, index, parameters)	List of modifications
private_fn:callable or None	Callable for constructing a private data field for a modification
Returns
list	Undocumented

def ReleaseLocks(lu, level, names=None, keep=None): ¶

Releases locks owned by an LU.

Parameters
lu:`LogicalUnit`	Undocumented
level	Lock level
names:list or None	Names of locks to release
keep:list or None	Names of locks to retain

def RemoveDisks(lu, instance, disks=None, target_node_uuid=None, ignore_failures=False): ¶

Remove all or a subset of disks for an instance.

This abstracts away some work from `AddInstance()` and `RemoveInstance()`. Note that in case some of the devices couldn't be removed, the removal will continue with the other ones.

This function is also used by the disk template conversion mechanism to remove the old block devices of the instance. Since the instance has changed its template at the time we remove the original disks, we must specify the template of the disks we are about to remove as an argument.

Parameters
lu:`LogicalUnit`	the logical unit on whose behalf we execute
instance:`objects.Instance`	the instance whose disks we should remove
disks:list of `objects.Disk`	the disks to remove; if not specified, all the disks of the instance are removed
target_node_uuid:string	used to override the node on which to remove the disks
ignore_failures	Undocumented
Returns
boolean	the success of the removal

def RemoveInstance(lu, feedback_fn, instance, ignore_failures): ¶

Utility function to remove an instance.

def UpdateMetadata(feedback_fn, rpc, instance, osparams_public=None, osparams_private=None, osparams_secret=None): ¶

Updates instance metadata on the metadata daemon on the instance's primary node.

If the daemon isn't available (not compiled), do nothing.

In case the RPC fails, this function simply issues a warning and proceeds normally.

Parameters
feedback_fn:callable	function used send feedback back to the caller
rpc:`rpc.node.RpcRunner`	RPC runner
instance:`objects.Instance`	instance for which the metadata should be updated
osparams_public:NoneType or dict	public OS parameters used to override those defined in `instance`
osparams_private:NoneType or dict	private OS parameters used to override those defined in `instance`
osparams_secret:NoneType or dict	secret OS parameters used to override those defined in `instance`
Returns
NoneType	None

def _ComputeIPolicyNodeViolation(ipolicy, instance, current_group, target_group, cfg, _compute_fn=ComputeIPolicyInstanceViolation): ¶

Compute if instance meets the specs of the new target group.

Parameters
ipolicy	The ipolicy to verify
instance	The instance object to verify
current_group	The current group of the instance
target_group	The new group of the instance
cfg:`config.ConfigWriter`	Cluster configuration
_compute_fn	The function to verify ipolicy (unittest only)
See Also
`ganeti.cmdlib.common.ComputeIPolicySpecViolation`

def _StoragePathsRemoved(removed, disks): ¶

Returns an iterable of all storage paths to be removed.

A storage path is removed if no disks are contained in it anymore.

Parameters
removed:list of `objects.Disk`	The disks that are being removed
disks:list of `objects.Disk`	All disks attached to the instance
Returns
list of file paths	the storage directories that need to be removed

_TApplyContModsCbChanges = ¶

Undocumented

ganeti.cmdlib.instance_utils

`ganeti.cmdlib.instance_utils`