pycloudlib.lxd.instance module

LXD instance.

class pycloudlib.lxd.instance.LXDInstance(name, key_pair=None, execute_via_ssh=True, series=None, ephemeral=None)

Bases: pycloudlib.instance.BaseInstance

LXD backed instance.

__init__(name, key_pair=None, execute_via_ssh=True, series=None, ephemeral=None)

Set up instance.

Parameters:

• name – name of instance
• key_pair – SSH key object
• execute_via_ssh – Boolean True to use ssh instead of lxc exec for all operations.
• series – Ubuntu release name: xenial, bionic etc.
• ephemeral – Boolean True if instance is ephemeral. If left unspecified, ephemeral type will be determined and cached by the ephemeral method.

add_network_interface() → str

Add nic to running instance.

clean()

Clean an instance to make it look prestine.

This will clean out specifically the cloud-init files and system logs.

console_log()

Return console log.

Uses the ‘–show-log’ option of console to get the console log from an instance.

Returns:bytes of this instance’s console

delete(wait=True)

Delete the current instance.

By default this will use the ‘–force’ option to prevent the need to always stop the instance first. This makes it easier to work with ephemeral instances as well, which are deleted on stop.

Parameters:wait – wait for delete

delete_snapshot(snapshot_name)

Delete a snapshot of the instance.

Parameters:snapshot_name – the name to delete

edit(key, value)

Edit the config of the instance.

Parameters:

• key – The config key to edit
• value – The new value to set the key to

ephemeral

Return boolean if ephemeral or not.

Will return False if unknown.

Returns:boolean if ephemeral

execute(command, stdin=None, description=None, *, use_sudo=False, no_log=False, **kwargs)

Execute command in instance, recording output, error and exit code.

Assumes functional networking and execution with the target filesystem being available at /.

Parameters:

• command – the command to execute as root inside the image. If command is a string, then it will be executed as: [‘sh’, ‘-c’, command]
• stdin – bytes content for standard in
• description – purpose of command
• use_sudo – boolean to run the command as sudo

Returns:

Result object

Raises SSHException if there are any problem with the ssh connection

get_boot_id()

Get the instance boot_id.

Returns:string with the boot UUID

install(packages)

Install specific packages.

Parameters:packages – string or list of package(s) to install Returns:result from install

ip

Return IP address of instance.

Returns:IP address assigned to instance.

Raises: PycloudlibTimeoutError when exhausting retries trying to parse

lxc list for ip addresses.

is_vm

Return boolean if vm type or not.

Will return False if unknown.

Returns:boolean if virtual-machine

local_snapshot(snapshot_name, stateful=False)

Create an LXD snapshot (not a launchable image).

Parameters:

• snapshot_name – name to call snapshot
• stateful – boolean, stateful snapshot or not

name

Return instance name.

parse_ip(query: dict)

Return ip address from lxd query.

Returns None if no address found

pull_file(remote_path, local_path)

Pull file from an instance.

The remote path must be absolute path with LXD due to the way files are pulled off. Specifically, the format is ‘name/path’ with path assumed to start from ‘/’.

Parameters:

• remote_path – path to remote file to pull down
• local_path – local path to put the file

push_file(local_path, remote_path)

Push file to an instance.

The remote path must be absolute path with LXD due to the way files are pulled off. Specifically, the format is ‘name/path’ with path assumed to start from ‘/’.

Parameters:

• local_path – local path to file to push up
• remote_path – path to push file

remove_network_interface(ip_address: str)

Remove nic from running instance.

restart(wait=True, **kwargs)

Restart an instance.

restore(snapshot_name)

Restore instance from a specific snapshot.

Parameters:snapshot_name – Name of snapshot to restore from

run_script(script, description=None)

Run script in target and return stdout.

Parameters:

• script – script contents
• description – purpose of script

Returns:

result from script execution

Raises SSHException if there are any problem with the ssh connection

shutdown(wait=True, force=False, **kwargs)

Shutdown instance.

Parameters:

• wait – boolean, wait for instance to shutdown
• force – boolean, force instance to shutdown

snapshot(snapshot_name)

Create an image snapshot.

Snapshot is a bit of a misnomer here. Since “snapshot” in the context of clouds means “create a launchable container from this instance”, we actually need to do a publish here. If you need the lxd “snapshot” functionality, use local_snapshot

Parameters:snapshot_name – name to call snapshot

start(wait=True)

Start instance.

Parameters:wait – boolean, wait for instance to fully start

state

Return current status of instance.

If unable to get status will return ‘Unknown’.

Returns:Reported status from lxc info

update()

Run apt-get update/upgrade on instance.

Returns:result from upgrade

wait()

Wait for instance to be up and cloud-init to be complete.

wait_for_delete()

Wait for delete.

Not used for LXD.

wait_for_restart(old_boot_id)

Wait for instance to be restarted and cloud-init to be complete.

old_boot_id is the boot id prior to restart

wait_for_state(desired_state: str, num_retries: int = 100)

Wait for instance to reach desired state value.

Parameters:

• desired_state – String representing one of lxc instance states seen by lxc ls -s. For example, ACTIVE, FROZEN, RUNNING, STOPPED
• retries – Integer for number of retry attempts before raising a PycloudlibTimeoutError.

wait_for_stop()

Wait for cloud instance to transition to stop state.

class pycloudlib.lxd.instance.LXDVirtualMachineInstance(name, key_pair=None, execute_via_ssh=True, series=None, ephemeral=None)

Bases: pycloudlib.lxd.instance.LXDInstance

LXD Virtual Machine backed instance.

__init__(name, key_pair=None, execute_via_ssh=True, series=None, ephemeral=None)

Set up instance.

Parameters:

• name – name of instance
• key_pair – SSH key object
• execute_via_ssh – Boolean True to use ssh instead of lxc exec for all operations.
• series – Ubuntu release name: xenial, bionic etc.
• ephemeral – Boolean True if instance is ephemeral. If left unspecified, ephemeral type will be determined and cached by the ephemeral method.

add_network_interface() → str

Add nic to running instance.

clean()

Clean an instance to make it look prestine.

This will clean out specifically the cloud-init files and system logs.

console_log()

Return console log.

Uses the ‘–show-log’ option of console to get the console log from an instance.

Returns:bytes of this instance’s console

delete(wait=True)

Delete the current instance.

By default this will use the ‘–force’ option to prevent the need to always stop the instance first. This makes it easier to work with ephemeral instances as well, which are deleted on stop.

Parameters:wait – wait for delete

delete_snapshot(snapshot_name)

Delete a snapshot of the instance.

Parameters:snapshot_name – the name to delete

edit(key, value)

Edit the config of the instance.

Parameters:

• key – The config key to edit
• value – The new value to set the key to

ephemeral

Return boolean if ephemeral or not.

Will return False if unknown.

Returns:boolean if ephemeral

execute(command, stdin=None, description=None, *, use_sudo=False, no_log=False, **kwargs)

Execute command in instance, recording output, error and exit code.

Assumes functional networking and execution with the target filesystem being available at /.

Parameters:

• command – the command to execute as root inside the image. If command is a string, then it will be executed as: [‘sh’, ‘-c’, command]
• stdin – bytes content for standard in
• description – purpose of command
• use_sudo – boolean to run the command as sudo

Returns:

Result object

Raises SSHException if there are any problem with the ssh connection

get_boot_id()

Get the instance boot_id.

Returns:string with the boot UUID

install(packages)

Install specific packages.

Parameters:packages – string or list of package(s) to install Returns:result from install

ip

Return IP address of instance.

Returns:IP address assigned to instance.

Raises: PycloudlibTimeoutError when exhausting retries trying to parse

lxc list for ip addresses.

is_vm

Return boolean if vm type or not.

Will return False if unknown.

Returns:boolean if virtual-machine

local_snapshot(snapshot_name, stateful=False)

Create an LXD snapshot (not a launchable image).

Parameters:

• snapshot_name – name to call snapshot
• stateful – boolean, stateful snapshot or not

name

Return instance name.

parse_ip(query: dict)

Return ip address from lxd query.

Returns None if no address found

pull_file(remote_path, local_path)

Pull file from an instance.

The remote path must be absolute path with LXD due to the way files are pulled off. Specifically, the format is ‘name/path’ with path assumed to start from ‘/’.

Parameters:

• remote_path – path to remote file to pull down
• local_path – local path to put the file

push_file(local_path, remote_path)

Push file to an instance.

The remote path must be absolute path with LXD due to the way files are pulled off. Specifically, the format is ‘name/path’ with path assumed to start from ‘/’.

Parameters:

• local_path – local path to file to push up
• remote_path – path to push file

remove_network_interface(ip_address: str)

Remove nic from running instance.

restart(wait=True, **kwargs)

Restart an instance.

restore(snapshot_name)

Restore instance from a specific snapshot.

Parameters:snapshot_name – Name of snapshot to restore from

run_script(script, description=None)

Run script in target and return stdout.

Parameters:

• script – script contents
• description – purpose of script

Returns:

result from script execution

Raises SSHException if there are any problem with the ssh connection

shutdown(wait=True, force=False, **kwargs)

Shutdown instance.

Parameters:

• wait – boolean, wait for instance to shutdown
• force – boolean, force instance to shutdown

snapshot(snapshot_name)

Create an image snapshot.

Snapshot is a bit of a misnomer here. Since “snapshot” in the context of clouds means “create a launchable container from this instance”, we actually need to do a publish here. If you need the lxd “snapshot” functionality, use local_snapshot

Parameters:snapshot_name – name to call snapshot

start(wait=True)

Start instance.

Parameters:wait – boolean, wait for instance to fully start

state

Return current status of instance.

If unable to get status will return ‘Unknown’.

Returns:Reported status from lxc info

update()

Run apt-get update/upgrade on instance.

Returns:result from upgrade

wait()

Wait for instance to be up and cloud-init to be complete.

wait_for_delete()

Wait for delete.

Not used for LXD.

wait_for_restart(old_boot_id)

Wait for instance to be restarted and cloud-init to be complete.

old_boot_id is the boot id prior to restart

wait_for_state(desired_state: str, num_retries: int = 100)

Wait for instance to reach desired state value.

Parameters:

• desired_state – String representing one of lxc instance states seen by lxc ls -s. For example, ACTIVE, FROZEN, RUNNING, STOPPED
• retries – Integer for number of retry attempts before raising a PycloudlibTimeoutError.

wait_for_stop()

Wait for cloud instance to transition to stop state.