craft_providers.lxd package
Submodules
- craft_providers.lxd.errors module
- craft_providers.lxd.installer module
- craft_providers.lxd.launcher module
- craft_providers.lxd.lxc module
- craft_providers.lxd.lxd module
- craft_providers.lxd.lxd_instance module
- craft_providers.lxd.lxd_provider module
- craft_providers.lxd.project module
- craft_providers.lxd.remotes module
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
- 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'
- 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
]) – Ifmap_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
- supports_mount()[source]
Check if instance supports mounting from host.
- Return type
bool
- Returns
True if mount is supported.
- 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
- classmethod ensure_provider_is_available()[source]
Ensure provider is available and ready, installing if required.
- Raises
LXDInstallationError – if LXD cannot be installed
LXDError – if provider is not available
- 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.
- craft_providers.lxd.install(sudo=True)[source]
Install LXD.
Install application, using sudo if specified.
- Return type
str
- Returns
LXD version.
- Raises
LXDInstallationError – on installation error.
LXDError – on unexpected error.
- 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=False, project='default', remote='local', lxc=<craft_providers.lxd.lxc.LXC object>)[source]
Create, start, and configure instance.
If auto_clean is enabled, automatically delete an existing instance that is deemed to be incompatible, rebuilding it with the specified environment.
- Parameters
name (
str
) – Name of instance.base_configuration (
Base
) – Base configuration to apply to 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
) – Automatically clean instance, if incompatible.auto_create_project (
bool
) – Automatically create LXD project, if needed.ephemeral (
bool
) – Create ephemeral instance.map_user_uid (
bool
) – Map host uid/gid to instance’s root uid/gid.uid (
Optional
[int
]) – The uid to be mapped, ifmap_user_id
is enabled.use_snapshots (
bool
) – Use LXD snapshots for bootstrapping images.project (
str
) – LXD project to create instance in.remote (
str
) – LXD remote to create instance on.lxc (
LXC
) – LXC client.
- Return type
- Returns
LXD instance.
- Raises
BaseConfigurationError – on unexpected error configuration base.
LXDError – on unexpected LXD error.