incus

Execution module for managing Incus instances.

Provides instance lifecycle (create, delete, start, stop, config, devices) as thin wrappers over the client seam, plus agentless in-instance state via call(), sls() and sls_build(), which ship the Salt thin into an instance over incus exec and run salt-call --local there. No resident minion is required: the thin is shipped per run and staging is removed on every exit.

sls() has two render strategies via precompiled: the default ships SLS source and renders in-instance; precompiled=True compiles the low state on the control node and ships a self-contained tarball. Pillar is always resolved on the control node and shipped as a root-only file, never on the command line.

depends:

incus binary

saltext.incus.modules.incus.__virtual__()

Only load when the incus binary is present.

saltext.incus.modules.incus.create(name, image, profiles=None, config=None, devices=None, start=False, ephemeral=False, project=None)

Create an instance from image and return its info dict.

name

Instance name.

image

Source image, for example images:debian/12.

profiles

Optional list of profile names to attach. When omitted the Incus default profile applies. Profile membership is not reconciled after creation in this version.

config

Optional mapping of instance config keys to set at creation.

devices

Optional mapping of device name to device definition. Each definition must include a type key.

startFalse

Start the instance after creating it.

ephemeralFalse

Create an ephemeral instance (deleted when stopped).

CLI Example:

salt '*' incus.create web01 images:debian/12 start=True
salt '*' incus.create web01 images:debian/12 config='{boot.autostart: true}'

saltext.incus.modules.incus.delete(name, force=True, project=None)

Delete an instance.

CLI Example:

salt '*' incus.delete web01

saltext.incus.modules.incus.start(name, project=None)

Start an instance.

CLI Example:

salt '*' incus.start web01

saltext.incus.modules.incus.stop(name, timeout=30, force=False, project=None)

Stop an instance.

CLI Example:

salt '*' incus.stop web01

saltext.incus.modules.incus.restart(name, timeout=30, force=False, project=None)

Restart an instance.

CLI Example:

salt '*' incus.restart web01

saltext.incus.modules.incus.info(name, project=None)

Return the instance info dict (config, devices, profiles, status) or None if it does not exist.

CLI Example:

salt '*' incus.info web01

saltext.incus.modules.incus.exists(name, project=None)

Return True if the instance exists.

CLI Example:

salt '*' incus.exists web01

saltext.incus.modules.incus.list_(project=None)

Return a list of instance names.

CLI Example:

salt '*' incus.list

saltext.incus.modules.incus.config_set(name, key, value, project=None)

Set a single instance config key.

CLI Example:

salt '*' incus.config_set web01 boot.autostart true

saltext.incus.modules.incus.config_unset(name, key, project=None)

Unset a single instance config key.

CLI Example:

salt '*' incus.config_unset web01 boot.autostart

saltext.incus.modules.incus.device_add(name, device_name, device_type, project=None, **options)

Add a device to an instance.

CLI Example:

salt '*' incus.device_add web01 data disk source=/srv/data path=/data

saltext.incus.modules.incus.device_remove(name, device_name, project=None)

Remove a device from an instance.

CLI Example:

salt '*' incus.device_remove web01 data

saltext.incus.modules.incus.call(name, function, *args, project=None, transport='thin', **kwargs)

Run a single Salt execution function inside an instance.

The instance does not need Salt installed (with transport='thin', the default); it only needs a Python 3 interpreter. With transport='baked' the instance’s own salt-call is used and no thin is shipped.

CLI Example:

salt '*' incus.call web01 test.ping
salt '*' incus.call web01 cmd.run 'id -un'

saltext.incus.modules.incus.sls(name, mods, saltenv='base', pillar=None, test=False, transport='thin', pillar_mode='file', precompiled=False, cleanup=True, project=None, extra_filerefs='')

Apply the states in mods inside an instance and return the highstate result dict.

name

Instance name.

mods

SLS modules to apply, as a list or a comma-separated string.

saltenvbase

Environment to pull the SLS / compile against on the control node.

pillar

Pillar to use, already resolved on the control node (decrypt GPG/Vault values before passing them here). Shipped as a root-only file, never on the command line.

testFalse

Run in test mode; nothing is changed inside the instance.

transportthin

thin ships the Salt thin per run (the instance needs only Python 3). baked uses the instance’s own salt-call.

pillar_modefile

How pillar is delivered. Only file is supported.

precompiledFalse

False ships SLS source and runs state.apply in-instance. True compiles low state on the control node and applies it with state.pkg so no source reaches the instance.

cleanupTrue

Remove the in-instance staging directory after the run. Set False to leave it in place for debugging.

CLI Example:

salt '*' incus.sls web01 mods=access.users,access.sshd
salt '*' incus.sls web01 mods=hardening precompiled=True test=True

saltext.incus.modules.incus.sls_build(name, base, mods, project=None, public=False, saltenv='base', pillar=None, test=False, transport='thin', precompiled=False, cleanup=True)

Build an image by applying states to a throwaway instance, then publishing.

A temporary instance is launched from base, mods are applied inside it with sls(), the instance is stopped and published to a local image aliased name, and the temporary instance is always deleted.

name

Alias for the resulting image.

base

Source image to build from, for example images:debian/12.

mods

SLS modules to apply, as a list or comma-separated string.

testFalse

Compile and apply in test mode and skip publishing (a dry run).

CLI Example:

salt '*' incus.sls_build mycorp/web base=images:debian/12 mods=web,hardening