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
- 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'
- 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=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, ifmap_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
- Returns
LXD instance.
- Raises
BaseConfigurationError – on unexpected error configuration base.
BaseCompatibilityError – if instance is incompatible with the base.
LXDError – on unexpected LXD error.
ProviderError – if name of instance collides with base instance name.