craft_providers.lxd package

Submodules

Module contents

LXD environment provider.

class craft_providers.lxd.LXC(*, lxc_path=PosixPath('lxc'))[source]

Bases: object

Wrapper for lxc command-line interface.

Parameters

lxc_path (Path) –

config_device_add_disk(*, instance_name, source, path, device, project='default', remote='local')[source]

Mount host source directory to target mount point.

Parameters
  • instance_name (str) – Name of instance.

  • source (Path) – Host path.

  • path (PurePath) – Mount target in instance.

  • device (str) – Name of device.

  • project (str) – Name of LXD project.

  • remote (str) – Name of LXD remote.

Raises

LXDError – on unexpected error.

Return type

None

config_device_remove(*, instance_name, device, project='default', remote='local')[source]

Mount host source directory to target mount point.

Parameters
  • instance_name (str) – Name of instance.

  • device (str) – Name of device.

  • project (str) – Name of LXD project.

  • remote (str) – Name of LXD remote.

Raises

LXDError – on unexpected error.

Return type

None

config_device_show(*, instance_name, project='default', remote='local')[source]

Show full device configuration.

Parameters
  • instance_name (str) – Name of instance.

  • project (str) – Name of LXD project.

  • remote (str) – Name of LXD remote.

Raises

LXDError – on unexpected error.

Return type

Dict[str, Any]

config_set(*, instance_name, key, value, project='default', remote='local')[source]

Set instance_name configuration key.

Parameters
  • instance_name (str) – Name of instance.

  • key (str) – Config key name.

  • value (str) – Config key value.

  • project (str) – Name of LXD project.

  • remote (str) – Name of LXD remote.

Raises

LXDError – on unexpected error.

Return type

None

copy(*, source_remote='local', source_instance_name, destination_remote='local', destination_instance_name, project='default')[source]

Copy instances within or in between LXD servers.

Calls lxc copy <source_remote>:<source_instance_name> <destination_remote>: destination_instance_name>. A running instance can be copied but the manpages state “This may cause data corruption or data loss depending on the used filesystem and applications. Use with care.”

Parameters
  • source_remote (str) – Name of source LXD remote.

  • source_instance_name (str) – Name of instance to copy from.

  • destination_remote (str) – Name of remote LXD destination.

  • destination_instance_name (str) – Name of instance to copy to.

  • project (str) – Name of LXD project.

Raises

LXDError – on unexpected error.

Return type

None

delete(*, instance_name, force=False, project='default', remote='local')[source]

Delete instance.

Parameters
  • instance_name (str) – Name of instance.

  • force (bool) – Force deletion if running.

  • project (str) – Name of LXD project.

  • remote (str) – Name of LXD remote.

Raises

LXDError – on unexpected error.

Return type

None

exec(*, command, instance_name, cwd=None, mode=None, project='default', remote='local', runner=<function run>, **kwargs)[source]

Execute command in instance_name with specified runner.

Parameters
  • command (List[str]) – Command to execute in the instance.

  • instance_name (str) – Name of instance to execute in.

  • cwd (Optional[str]) – Optional current working directory for command.

  • mode (Optional[str]) – Override terminal mode Valid options include: “auto”, “interactive”, “non-interactive”. lxd default is “auto”.

  • project (str) – Name of LXD project.

  • remote (str) – Name of LXD remote.

  • runner (Callable) – Execution function to invoke, e.g. subprocess.run or Popen. First argument is finalized command with the attached kwargs.

  • kwargs – Additional kwargs for runner.

Returns

Runner’s instance.

file_pull(*, instance_name, source, destination, create_dirs=False, recursive=False, project='default', remote='local')[source]

Retrieve file from instance_name.

Parameters
  • instance_name (str) – Name of instance.

  • source (PurePath) – Path in environment to pull.

  • destination (Path) – Path in host to write to.

  • create_dirs (bool) – Create any directories necessary.

  • recursive (bool) – Recursively transfer files.

  • project (str) – Name of LXD project.

  • remote (str) – Name of LXD remote.

Raises

LXDError – on unexpected error.

Return type

None

file_push(*, instance_name, source, destination, create_dirs=False, recursive=False, gid=None, uid=None, mode=None, project='default', remote='local')[source]

Create file with content and file mode.

Parameters
  • instance_name (str) – Name of instance to push file to.

  • source (Path) – Path in host to push.

  • destination (PurePath) – Path in environment to write to.

  • create_dirs (bool) – Create any directories necessary.

  • recursive (bool) – Recursively transfer files.

  • gid (Optional[int]) – Optional gid to set on push (lxd’s default is -1).

  • uid (Optional[int]) – Optional uid to set on push (lxd’s default is -1).

  • mode (Optional[str]) – Optional file mode to set on file.

  • project (str) – Name of LXD project.

  • remote (str) – Name of LXD remote.

Raises

LXDError – on unexpected error.

Return type

None

has_image(image_name, *, project='default', remote='local')[source]

Check if image with given alias name is present.

Parameters
  • image_name – Name of image alias.

  • project (str) – Name of LXD project.

  • remote (str) – Name of LXD remote.

Return type

bool

image_copy(*, image, image_remote, alias=None, project='default', remote='local')[source]

Copy image.

Parameters
  • instance_name – Optional instance name.

  • alias (Optional[str]) – New alias to add to image.

  • image (str) – Image to copy.

  • project (str) – Name of LXD project.

  • remote (str) – Name of LXD remote.

  • image_remote (str) –

Raises

LXDError – on unexpected error.

Return type

None

image_delete(*, image, project='default', remote='local')[source]

Delete image.

Parameters
  • image (str) – Image to delete.

  • project (str) – Name of LXD project.

  • remote (str) – Name of LXD remote.

Raises

LXDError – on unexpected error.

Return type

None

image_list(*, project='default', remote='local')[source]

List images.

Parameters
  • project (str) – Name of LXD project.

  • remote (str) – Name of LXD remote.

Return type

List[Dict[str, Any]]

info(*, instance_name=None, project='default', remote='local')[source]

Show instance or server information.

Parameters
  • instance_name (Optional[str]) – Optional instance name.

  • project (str) – Name of LXD project.

  • remote (str) – Name of LXD remote.

Raises

LXDError – on unexpected error.

Return type

Dict[str, Any]

launch(*, instance_name, image, image_remote, config_keys=None, ephemeral=False, project='default', remote='local')[source]

Launch instance.

Parameters
  • instance_name (str) – Name of instance to launch.

  • image (str) – Name of image to use.

  • image_remote (str) – Name of image’s remote.

  • config_keys (Optional[Dict[str, str]]) – Configuration keys to set.

  • ephemeral (bool) – Use ephemeral instance.

  • project (str) – Name of LXD project.

  • remote (str) – Name of LXD remote.

Raises

LXDError – on unexpected error.

Return type

None

list(*, project='default', remote='local')[source]

List instances and their status.

Parameters
  • project (str) – Name of LXD project.

  • remote (str) – Name of LXD remote.

Return type

List[Dict[str, Any]]

Returns

List of containers and their info.

Raises

LXDError – on unexpected error.

list_names(*, project='default', remote='local')[source]

List container names.

A helper to get a list of container names from list().

Parameters
  • project (str) – Name of LXD project.

  • remote (str) – Name of LXD remote.

Return type

List[str]

Returns

List of container names.

Raises

LXDError – on unexpected error.

profile_edit(*, profile, config, project='default', remote='local')[source]

Set profile configuration.

Parameters
  • profile (str) – Name of profile.

  • project (str) – Name of LXD project.

  • remote (str) – Name of LXD remote.

  • config (Dict[str, Any]) –

Raises

LXDError – on unexpected error.

Return type

None

profile_show(*, profile, project='default', remote='local')[source]

Get profile configuration.

Parameters
  • profile (str) – Name of profile.

  • project (str) – Name of LXD project.

  • remote (str) – Name of LXD remote.

Raises

LXDError – on unexpected error.

Return type

Dict[str, Any]

project_create(*, project, remote='local')[source]

Create project.

Parameters
  • project (str) – Name of LXD project to create.

  • remote (str) – Name of LXD remote to create project on.

Raises

LXDError – on unexpected error.

Return type

None

project_delete(*, project, remote='local')[source]

Delete project, if it exists.

Parameters
  • project (str) – Name of LXD project to delete.

  • remote (str) – Name of LXD remote.

Raises

LXDError – on unexpected error.

Return type

None

project_list(remote='local')[source]

Get list of projects.

Parameters

remote (str) – Name of LXD remote to query.

Return type

List[str]

Returns

List of project names.

Raises

LXDError – on unexpected error.

publish(*, instance_name, alias=None, force=False, image_remote='local', project='default', remote='local')[source]

Publish image from instance.

Parameters
  • instance_name (str) – Name of instance to publish image from.

  • alias (Optional[str]) – New alias to define at target.

  • force (bool) – Force publishing of image, even if container is running.

  • image_remote (str) – Name of remote to publish image to.

  • project (str) – Name of LXD project.

  • remote (str) – Name of LXD remote instance is found on.

Raises

LXDError – on unexpected error.

Return type

None

remote_add(*, remote, addr, protocol='simplestreams')[source]

Add a public remote.

Parameters
  • remote (str) – Name of remote to add.

  • addr (str) – Address of remote.

  • protocol (str) – Name of protocol (“simplestreams” or “lxd”).

Raises

LXDError – on unexpected error.

Return type

None

remote_list()[source]

Get list of remotes.

Return type

Dict[str, Any]

Returns

dictionary with remote name mapping to config.

start(*, instance_name, project='default', remote='local')[source]

Start container.

Parameters
  • instance_name (str) – Name of instance to start.

  • project (str) – Name of LXD project.

  • remote (str) – Name of LXD remote.

Raises

LXDError – on unexpected error.

Return type

None

stop(*, instance_name, force=False, timeout=- 1, project='default', remote='local')[source]

Stop container.

Parameters
  • instance_name (str) – Name of instance to stop.

  • force (bool) – Force instance to stop.

  • timeout (int) – Timeout in seconds. -1 is no timeout.

  • project (str) – Name of LXD project.

  • remote (str) – Name of LXD remote.

Raises

LXDError – on unexpected error.

Return type

None

class craft_providers.lxd.LXD(*, lxd_path=PosixPath('lxd'))[source]

Bases: object

Interface to lxd command-line.

Parameters

lxd_path (Path) – Path to lxd.

Variables

minimum_required_version – Minimum lxd version required for compatibility.

init(*, auto=False, sudo=False)[source]

Initialize LXD.

Sudo is required if user is not in lxd group.

Parameters
  • auto (bool) – Use default settings.

  • sudo (bool) – Use sudo to invoke init.

Return type

None

is_supported_version()[source]

Check if LXD version is supported.

A helper to check if LXD meets minimum supported version for craft-providers (currently >= 4.0).

Return type

bool

Returns

True if installed version is supported.

minimum_required_version = '4.0'
version()[source]

Query LXD version.

The version is of the format: <major>.<minor>[.<micro>]

Version examples: - 4.13 - 4.0.5 - 2.0.12

Return type

str

Returns

Version string.

wait_ready(*, sudo=False, timeout=None)[source]

Wait until LXD is ready.

Sudo is required if user is not in lxd group.

Parameters
  • sudo (bool) – Use sudo to invoke waitready.

  • timeout (Optional[int]) – Timeout in seconds.

Return type

None

exception craft_providers.lxd.LXDError(brief: str, details: Optional[str] = None, resolution: Optional[str] = None)[source]

Bases: craft_providers.errors.ProviderError

Unexpected LXD error.

Parameters
  • brief (str) –

  • details (Optional[str]) –

  • resolution (Optional[str]) –

brief: str
exception craft_providers.lxd.LXDInstallationError(reason, *, details=None)[source]

Bases: craft_providers.lxd.errors.LXDError

LXD Installation Error.

Parameters
  • reason (str) – Reason for install failure.

  • details (Optional[str]) – Optional details to include.

brief: str
class craft_providers.lxd.LXDInstance(*, name, default_command_environment=None, project='default', remote='local', lxc=None)[source]

Bases: craft_providers.executor.Executor

LXD Instance Lifecycle.

Parameters
  • name (str) –

  • default_command_environment (Optional[Dict[str, Optional[str]]]) –

  • project (str) –

  • remote (str) –

  • lxc (Optional[LXC]) –

delete(force=True)[source]

Delete instance.

Parameters

force (bool) – Delete even if running.

Raises

LXDError – On unexpected error.

Return type

None

execute_popen(command, *, cwd=None, env=None, **kwargs)[source]

Execute a command in instance, using subprocess.Popen().

The process’ environment will inherit the execution environment’s default environment (PATH, etc.), but can be additionally configured via env parameter.

Parameters
  • command (List[str]) – Command to execute.

  • env (Optional[Dict[str, Optional[str]]]) – Additional environment to set for process.

  • kwargs – Additional keyword arguments to pass.

  • cwd (Optional[Path]) –

Return type

Popen

Returns

Popen instance.

execute_run(command, *, cwd=None, env=None, **kwargs)[source]

Execute a command using subprocess.run().

The process’ environment will inherit the execution environment’s default environment (PATH, etc.), but can be additionally configured via env parameter.

Parameters
  • command (List[str]) – Command to execute.

  • env (Optional[Dict[str, Optional[str]]]) – Additional environment to set for process.

  • kwargs – Keyword args to pass to subprocess.run().

  • cwd (Optional[Path]) –

Return type

CompletedProcess

Returns

Completed process.

Raises

subprocess.CalledProcessError – if command fails and check is True.

exists()[source]

Check if instance exists.

Return type

bool

Returns

True if instance exists.

Raises

LXDError – On unexpected error.

is_mounted(*, host_source, target)[source]

Check if path is mounted at target.

Parameters
  • host_source (Path) – Host path to check.

  • target (PurePath) – Instance path to check.

Return type

bool

Returns

True if host_source is mounted at target.

Raises

LXDError – On unexpected error.

is_running()[source]

Check if instance is running.

Return type

bool

Returns

True if instance is running.

Raises

LXDError – On unexpected error.

launch(*, image, image_remote, map_user_uid=False, ephemeral=False, uid=None)[source]

Launch instance.

Parameters
  • image (str) – Image name to launch.

  • image_remote (str) – Image remote name.

  • map_user_id – Whether id mapping should be used.

  • uid (Optional[int]) – If map_user_id is True, the host user ID to map to instance root.

  • ephemeral (bool) – Flag to enable ephemeral instance.

  • map_user_uid (bool) –

Raises

LXDError – On unexpected error.

Return type

None

mount(*, host_source, target)[source]

Mount host source directory to target mount point.

Checks first to see if already mounted. The source will be mounted as a disk named “disk-{target.as_posix()}”.

Parameters
  • host_source (Path) – Host path to mount.

  • target (PurePath) – Instance path to mount to.

Raises

LXDError – On unexpected error.

Return type

None

pull_file(*, source, destination)[source]

Copy a file from the environment to host.

Parameters
  • source (PurePath) – Environment file to copy.

  • destination (Path) – Host file path to copy to. Parent directory (destination.parent) must exist.

Raises
  • FileNotFoundError – If source file or destination’s parent directory does not exist.

  • LXDError – On unexpected error copying file.

Return type

None

push_file(*, source, destination)[source]

Copy a file from the host into the environment.

The destination file is overwritten if it exists.

Parameters
  • source (Path) – Host file to copy.

  • destination (PurePath) – Target environment file path to copy to. Parent directory (destination.parent) must exist.

Raises
  • FileNotFoundError – If source file or destination’s parent directory does not exist.

  • LXDError – On unexpected error copying file.

Return type

None

push_file_io(*, destination, content, file_mode, group='root', user='root')[source]

Create or replace file with content and file mode.

Parameters
  • destination (PurePath) – Path to file.

  • content (BytesIO) – Contents of file.

  • file_mode (str) – File mode string (e.g. ‘0644’).

  • group (str) – File group owner/id.

  • user (str) – File user owner/id.

Raises

LXDError – On unexpected error.

Return type

None

start()[source]

Start instance.

Raises

LXDError – on unexpected error.

Return type

None

stop()[source]

Stop instance.

Raises

LXDError – on unexpected error.

Return type

None

supports_mount()[source]

Check if instance supports mounting from host.

Return type

bool

Returns

True if mount is supported.

unmount(target)[source]

Unmount mount target shared with host.

Parameters

target (Path) – Target shared with host to unmount.

Raises

LXDError – On failure to unmount target.

Return type

None

unmount_all()[source]

Unmount all mounts shared with host.

Raises

LXDError – On failure to unmount target.

Return type

None

class craft_providers.lxd.LXDProvider(*, lxc=<craft_providers.lxd.lxc.LXC object>, lxd_project='default', lxd_remote='local')[source]

Bases: craft_providers.provider.Provider

LXD build environment provider.

This class is not stable and is likely to change. This class will be stable and recommended for use in the release of craft-providers 2.0.

Parameters
  • lxc (LXC) – Optional lxc client to use.

  • lxd_project (str) – LXD project to use (default is default).

  • lxd_remote (str) – LXD remote to use (default is local).

create_environment(*, instance_name)[source]

Create a bare environment for specified base.

No initializing, launching, or cleaning up of the environment occurs.

Parameters

instance_name (str) – Name of the instance.

Return type

Executor

classmethod ensure_provider_is_available()[source]

Ensure provider is available and ready, installing if required.

Raises
Return type

None

classmethod is_provider_installed()[source]

Check if provider is installed.

Return type

bool

Returns

True if installed.

launched_environment(*, project_name, project_path, base_configuration, build_base, instance_name)[source]

Configure and launch environment for specified base.

When this method loses context, all directories are unmounted and the environment is stopped. For more control of environment setup and teardown, use create_environment() instead.

Parameters
  • project_name (str) – Name of project.

  • project_path (Path) – Path to project.

  • base_configuration (Base) – Base configuration to apply to instance.

  • build_base (str) – Base to build from.

  • instance_name (str) – Name of the instance to launch.

Raises

LXDError – if instance cannot be configured and launched

Return type

Generator[Executor, None, None]

craft_providers.lxd.configure_buildd_image_remote(lxc=<craft_providers.lxd.lxc.LXC object>)[source]

Configure buildd remote, adding remote as required.

Parameters

lxc (LXC) – LXC client.

Return type

str

Returns

Name of remote to pass to launcher.

craft_providers.lxd.ensure_lxd_is_ready(*, remote='local', lxc=<craft_providers.lxd.lxc.LXC object>, lxd=<craft_providers.lxd.lxd.LXD object>)[source]

Ensure LXD is ready for use.

Raises

LXDError – on error.

Parameters
  • remote (str) –

  • lxc (LXC) –

  • lxd (LXD) –

Return type

None

craft_providers.lxd.install(sudo=True)[source]

Install LXD.

Install application, using sudo if specified.

Return type

str

Returns

LXD version.

Raises
Parameters

sudo (bool) –

craft_providers.lxd.is_initialized(*, remote, lxc)[source]

Verify that LXD has been initialized and configuration looks valid.

If LXD has been installed but the user has not initialized it (lxd init), the default profile won’t have devices configured. Trying to launch an instance or create a project using this profile will result in failures.

Return type

bool

Returns

True if initialized, else False.

Parameters
  • remote (str) –

  • lxc (LXC) –

craft_providers.lxd.is_installed()[source]

Check if LXD is installed (and found on PATH).

Return type

bool

Returns

True if lxd is installed.

craft_providers.lxd.is_user_permitted()[source]

Check if user has permissions to connect to LXD.

Return type

bool

Returns

True if user has correct permissions.

craft_providers.lxd.launch(name, *, base_configuration, image_name, image_remote, auto_clean=False, auto_create_project=False, ephemeral=False, map_user_uid=False, uid=None, use_snapshots=None, use_base_instance=False, project='default', remote='local', lxc=<craft_providers.lxd.lxc.LXC object>)[source]

Create, start, and configure an instance.

On the first run of an application, an instance will be launched from an image (i.e. an image from https://cloud-images.ubuntu.com). The instance is setup according to the Base configuration passed to this function.

After setup, a copy of this instance is saved (or cached) as a ‘base instance’. This is done to reduce setup time on subsequent runs. When the application requests a new instance on a subsequent run, the base instance will be copied to create the new instance. This instance is run through a small subset of the setup, which is referred to as ‘warmup’.

To keep build environments clean, consistent, and up-to-date, any base instance older than 3 months (90 days) is deleted and recreated.

Parameters
  • name (str) – Name of instance.

  • base_configuration (Base) – Base configuration to apply to the instance.

  • image_name (str) – LXD image to use, e.g. “20.04”.

  • image_remote (str) – LXD image to use, e.g. “ubuntu”.

  • auto_clean (bool) – If true and the existing instance is incompatible, then the

instance will be deleted and rebuilt. If false and the existing instance is incompatible, then a BaseCompatibilityError is raised. :type auto_create_project: bool :param auto_create_project: Automatically create LXD project, if needed. :type ephemeral: bool :param ephemeral: After the instance is stopped, delete it. Non-ephemeral instances cannot be converted to ephemeral instances, so if the instance already exists, it will be deleted, then recreated as an ephemeral instance. :type map_user_uid: bool :param map_user_uid: Map host uid/gid to instance’s root uid/gid. :type uid: Optional[int] :param uid: The uid to be mapped, if map_user_id is enabled. :type use_base_instance: Optional[bool] :param use_base_instance: Use the base instance mechanisms to reduce setup time. :type use_snapshots: Optional[bool] :param use_snapshots: Deprecated parameter replaced by use_base_instance. :type project: str :param project: LXD project to create instance in. :type remote: str :param remote: LXD remote to create instance on. :type lxc: LXC :param lxc: LXC client.

Return type

LXDInstance

Returns

LXD instance.

Raises