pycloudlib.lxd.instance module¶
LXD instance.
-
class
pycloudlib.lxd.instance.
LXDInstance
(name, key_pair=None, execute_via_ssh=True, series=None, ephemeral=None)[source]¶ Bases:
pycloudlib.instance.BaseInstance
LXD backed instance.
-
__init__
(name, key_pair=None, execute_via_ssh=True, series=None, ephemeral=None)[source]¶ 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
()[source]¶ 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)[source]¶ 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)[source]¶ Delete a snapshot of the instance.
Parameters: snapshot_name – the name to delete
-
edit
(key, value)[source]¶ 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)[source]¶ 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.
-
pull_file
(remote_path, local_path)[source]¶ 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)[source]¶ 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)[source]¶ 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)[source]¶ Shutdown instance.
Parameters: - wait – boolean, wait for instance to shutdown
- force – boolean, force instance to shutdown
-
snapshot
(snapshot_name)[source]¶ 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)[source]¶ 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_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)[source]¶ 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.
-
-
class
pycloudlib.lxd.instance.
LXDVirtualMachineInstance
(name, key_pair=None, execute_via_ssh=True, series=None, ephemeral=None)[source]¶ 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.
-