instance

Manage compute instances.

class compute.instance.instance.Instance(domain: virDomain)

Manage compute instances.

__init__(domain: virDomain)

Initialise Instance.

Variables:
  • domain (libvirt.virDomain) – domain object

  • connection (libvirt.virConnect) – connection object

  • name (str) – domain name

  • guest_agent (GuestAgent) – GuestAgent object

Parameters:

domain – libvirt domain object

attach_device(device: EntityConfig, *, live: bool = False) None

Attach device to compute instance.

Parameters:
  • device – Object with device description e.g. DiskConfig

  • live – Affect a running instance

delete() None

Undefine instance.

delete_ssh_keys(user: str, ssh_keys: list[str]) None

Remove SSH keys from guest for specific user.

Parameters:
  • user – Username.

  • ssh_keys – List of public SSH keys.

detach_device(device: EntityConfig, *, live: bool = False) None

Dettach device from compute instance.

Parameters:
  • device – Object with device description e.g. DiskConfig

  • live – Affect a running instance

detach_disk(name: str) None

Detach disk device by target name.

There is no attach_disk() method. Use attach_device() with DiskConfig as argument.

Parameters:

name – Disk name e.g. ‘vda’, ‘sda’, etc. This name may not match the name of the disk inside the guest OS.

dump_xml(*, inactive: bool = False) str

Return instance XML description.

get_disks() list[compute.storage.volume.DiskConfig]

Return list of attached disks.

get_info() InstanceInfo

Return instance info.

get_max_memory() int

Maximum memory value for domain in KiB.

get_max_vcpus() int

Maximum vCPUs number for domain.

get_ssh_keys(user: str) list[str]

Return list of SSH keys on guest for specific user.

Parameters:

user – Username.

get_status() str

Return instance state: ‘running’, ‘shutoff’, etc.

Reference: https://libvirt.org/html/libvirt-libvirt-domain.html#virDomainState

is_autostart() bool

Return True if instance autostart is enabled, else return False.

is_running() bool

Return True if instance is running, else return False.

pause() None

Pause instance.

power_reset() None

Shutdown instance and start.

By analogy with real hardware, this is a normal server shutdown, and then turning off from the power supply and turning it on again.

This method is applicable in cases where there has been a configuration change in libvirt and you need to restart the instance to apply the new configuration.

reboot() None

Send ACPI signal to guest OS to reboot. OS may ignore this.

reset() None

Reset instance.

Copypaste from libvirt doc:

Reset a domain immediately without any guest OS shutdown. Reset emulates the power reset button on a machine, where all hardware sees the RST line set and reinitializes internal state.

Note that there is a risk of data loss caused by reset without any guest OS shutdown.

resize_disk(name: str, capacity: int, unit: DataUnit) None

Resize attached block device.

Parameters:
  • name – Disk device name e.g. vda, sda, etc.

  • capacity – New capacity.

  • unit – Capacity unit.

resume() None

Resume paused instance.

set_autostart(*, enabled: bool) None

Set autostart flag for instance.

Parameters:

enabled – Bool argument to set or unset autostart flag.

set_memory(memory: int, *, live: bool = False) None

Set memory.

If live is True and instance is not currently running set memory in config and will applied when instance boot.

Parameters:
  • memory – Memory value in mebibytes

  • live – Affect a running instance

set_ssh_keys(user: str, ssh_keys: list[str]) None

Add SSH keys to guest for specific user.

Parameters:
  • user – Username.

  • ssh_keys – List of public SSH keys.

set_user_password(user: str, password: str, *, encrypted: bool = False) None

Set new user password in guest OS.

This action performs by guest agent inside the guest.

Parameters:
  • user – Username.

  • password – Password.

  • encrypted – Set it to True if password is already encrypted. Right encryption method depends on guest OS.

set_vcpus(nvcpus: int, *, live: bool = False) None

Set vCPU number.

If live is True and instance is not currently running vCPUs will set in config and will applied when instance boot.

NB: Note that if this call is executed before the guest has finished booting, the guest may fail to process the change.

Parameters:
  • nvcpus – Number of vCPUs

  • live – Affect a running instance

shutdown(method: str | None = None) None

Shutdown instance.

Shutdown methods:

SOFT

Use guest agent to shutdown. If guest agent is unavailable NORMAL method will be used.

NORMAL

Use method choosen by hypervisor to shutdown. Usually send ACPI signal to guest OS. OS may ignore ACPI e.g. if guest is hanged.

HARD

Shutdown instance without any guest OS shutdown. This is simular to unplugging machine from power. Internally send SIGTERM to instance process and destroy it gracefully.

UNSAFE

Force shutdown. Internally send SIGKILL to instance process. There is high data corruption risk!

If method is None NORMAL method will used.

Parameters:

method – Method used to shutdown instance

start() None

Start defined instance.

class compute.instance.instance.InstanceConfig(schema: InstanceSchema)

Compute instance XML config builder.

__init__(schema: InstanceSchema)

Initialise InstanceConfig.

Parameters:

schema – InstanceSchema object

to_xml() str

Return XML config for libvirt.

class compute.instance.instance.InstanceInfo(state: str, max_memory: int, memory: int, nproc: int, cputime: int)

Store compute instance info.

Reference: https://libvirt.org/html/libvirt-libvirt-domain.html#virDomainInfo

cputime: int

Alias for field number 4

max_memory: int

Alias for field number 1

memory: int

Alias for field number 2

nproc: int

Alias for field number 3

state: str

Alias for field number 0