saltext.incus.utils.incus

Client seam for Incus: the single place the extension runs the incus CLI.

Every execution and state function reaches Incus through these helpers rather than shelling out directly, so a REST backend can later replace the CLI calls here without touching callers. Reads use incus query (JSON over the REST path); writes use incus subcommands. Commands are argument lists run without a shell.

depends:

incus binary

saltext.incus.utils.incus.__virtual__()

Only load when the incus binary is present.

saltext.incus.utils.incus.query(path, project=None, ignore_retcode=False)

Issue incus query against a REST path and return the parsed JSON.

Returns None when the query fails and ignore_retcode is set.

saltext.incus.utils.incus.query_instance(name, project=None)

Return the instance dict for name or None if it does not exist.

The dict carries config, devices, profiles, status and the expanded variants, exactly as the REST API reports them.

saltext.incus.utils.incus.list_instances(project=None)

Return a list of instance dicts for the project.

saltext.incus.utils.incus.create_instance(name, image, profiles=None, config=None, devices=None, ephemeral=False, project=None)

Create (but do not start) an instance from image.

config is applied at creation; devices are added afterwards, one per device. With profiles=None the Incus default profile applies.

saltext.incus.utils.incus.delete_instance(name, force=True, project=None)

Delete an instance. force is required to delete a running instance.

saltext.incus.utils.incus.start_instance(name, project=None)

Start an instance.

saltext.incus.utils.incus.stop_instance(name, timeout=30, force=False, project=None)

Stop an instance. force kills it immediately; otherwise timeout seconds are allowed for a clean shutdown.

saltext.incus.utils.incus.restart_instance(name, timeout=30, force=False, project=None)

Restart an instance.

saltext.incus.utils.incus.set_config(name, key, value, project=None)

Set a single instance config key.

saltext.incus.utils.incus.unset_config(name, key, project=None)

Unset a single instance config key.

saltext.incus.utils.incus.add_device(name, device_name, device_type, options=None, project=None)

Add a device to an instance.

options is a mapping of the device’s properties (everything other than type), for example {"source": "/srv/data", "path": "/data"} for a disk device.

saltext.incus.utils.incus.remove_device(name, device_name, project=None)

Remove a device from an instance.

saltext.incus.utils.incus.exec_in(name, argv, project=None, environment=None, cwd=None, stdin=None)

Run argv inside the instance and return a cmd.run_all-style dict.

The return code is surfaced, not raised, so callers can inspect it. Runs as the instance’s root user.

saltext.incus.utils.incus.push_file(name, local_path, remote_path, mode='0600', uid=0, gid=0, recursive=False, create_dirs=True, project=None)

Push a file or directory into the instance.

Defaults are deliberately locked down: 0600 and root ownership. The target is addressed as <instance><absolute-remote-path> which is how the Incus CLI maps a push onto an instance path.

saltext.incus.utils.incus.delete_path(name, remote_path, project=None)

Remove a path inside the instance with rm -rf (never fails if absent).

saltext.incus.utils.incus.publish(name, alias=None, public=False, force=False, project=None)

Publish a (normally stopped) instance to a local image.

Returns a dict with the image fingerprint (parsed from the CLI output) and the alias if one was requested.