incus_instance
incus_instance manages one instance of Incus
on a node: a system container or a virtual machine that Incus runs. It creates
the instance from an image, keeps its profiles, its configuration keys, and
its devices as the task writes them, starts it, shuts it down, or deletes it.
It does all of this through the program incus, which it runs as root on the
node, and it manages the Incus server of that node.
incus_profile manages the profiles that
instances share.
Set up
The module installs nothing. The node tasks below install Incus, start the
Incus server, and prepare the server for the first instance. The setup tasks
work on every distribution in the table. Each when chooses the tasks for
one distribution.
The example project examples/incus-host is
this list as a whole project.
| Distribution | Where Incus comes from | Package |
|---|---|---|
| Debian 13 | Debian's own repository | incus-base, or incus to also run virtual machines |
| Debian 12 | Debian's backports repository | incus-base |
| Ubuntu 26.04 | Ubuntu's own repository | incus-base, or incus to also run virtual machines |
| Ubuntu 24.04 | Ubuntu's own repository | incus |
| Rocky Linux 9 and AlmaLinux 10 | The COPR repository neelc/incus, which the Incus project names, with EPEL and CRB |
incus |
# Debian 13 packages Incus itself. Debian 12 has it in its backports
# repository, which the keyring of the node's own Debian signs.
- when:
all:
- equals: ["{{ .node.distribution.id }}", debian]
- number_equals: ["{{ .node.distribution.major_version }}", 12]
file:
path: /etc/apt/sources.list.d/bookworm-backports.sources
permissions_mode: "0644"
content: |
Types: deb
URIs: http://deb.debian.org/debian
Suites: bookworm-backports
Components: main
Signed-By: /usr/share/keyrings/debian-archive-keyring.gpg
# incus-base is Incus for containers. The package incus adds what
# virtual machines need. dnsmasq-base serves the addresses of Incus's
# bridge; the package only recommends it, and a server whose apt
# installs no recommended packages would lack it.
- when:
any:
- equals: ["{{ .node.distribution.id }}", debian]
- all:
- equals: ["{{ .node.distribution.id }}", ubuntu]
- number_at_least: ["{{ .node.distribution.major_version }}", 26]
apt_package: {packages: [{name: incus-base, version: newest_when_first_installed}, {name: dnsmasq-base, version: newest_when_first_installed}]}
# Ubuntu 24.04 has no package incus-base. Its package incus brings Incus
# without QEMU.
- when:
all:
- equals: ["{{ .node.distribution.id }}", ubuntu]
- number_equals: ["{{ .node.distribution.major_version }}", 24]
apt_package: {packages: [{name: incus, version: newest_when_first_installed}, {name: dnsmasq-base, version: newest_when_first_installed}]}
# Rocky Linux and AlmaLinux have no Incus package. The Incus project
# names the COPR repository neelc/incus for them. Its packages need
# libraries from EPEL, and EPEL needs the repository CRB. The COPR
# repository has one directory for release 9 and one for 10.
- when:
any:
- equals: ["{{ .node.distribution.id }}", rocky]
- equals: ["{{ .node.distribution.id }}", almalinux]
task_block:
id: incus_from_the_copr_repository
changes:
- dnf_package: {packages: [{name: epel-release, version: newest_when_first_installed}]}
- dnf_repository:
existing_repository: crb
enabled: true
- when: {number_equals: ["{{ .node.distribution.major_version }}", 9]}
dnf_repository:
name: copr-neelc-incus
description: Incus for Enterprise Linux 9 (COPR neelc/incus)
baseurl: ["https://download.copr.fedorainfracloud.org/results/neelc/incus/epel-9-$basearch/"]
signing_key_url: https://download.copr.fedorainfracloud.org/results/neelc/incus/pubkey.gpg
signing_key_sha256: 635810d20f5705f696a0c0ee0aa6e6ac9faeffeb55bb8e7e20b3d9014f930ce9
- when: {number_equals: ["{{ .node.distribution.major_version }}", 10]}
dnf_repository:
name: copr-neelc-incus
description: Incus for Enterprise Linux 10 (COPR neelc/incus)
baseurl: ["https://download.copr.fedorainfracloud.org/results/neelc/incus/rhel+epel-10-$basearch/"]
signing_key_url: https://download.copr.fedorainfracloud.org/results/neelc/incus/pubkey.gpg
signing_key_sha256: 635810d20f5705f696a0c0ee0aa6e6ac9faeffeb55bb8e7e20b3d9014f930ce9
- dnf_package: {packages: [{name: incus, version: newest_when_first_installed}]}
# The socket starts the Incus server at the first incus command. MMX
# installs a package without starting its services, and the packages of
# the Red Hat family enable nothing.
- systemd_service:
name: incus.socket
state: running
start_at_boot: true
# Start the server when the node boots, so that an instance with
# boot.autostart: "true" starts then. This unit starts the server only
# when an instance needs it.
- systemd_service:
name: incus-startup.service
state: do_not_start_or_stop
start_at_boot: true
# A container's accounts are a range of the node's user and group IDs
# that belongs to root. Debian's and Ubuntu's packages write this
# range; the others leave it out, and Incus then makes no container.
# The server reads the files only when it starts, so it is restarted
# when a line changes.
- task_block:
id: incus_server
changes:
- line:
insert_at_end_of_file: true
path: /etc/subuid
match: '^root:'
line: "root:1000000:1000000000"
- line:
insert_at_end_of_file: true
path: /etc/subgid
match: '^root:'
line: "root:1000000:1000000000"
activate:
- systemd_service:
name: incus.service
state: running
# Once for each server: a storage pool, the bridge incusbr0, and the
# root disk and the network card in the profile default. The guard
# asks for the root disk, the last thing that the command makes. Its
# exit code 127 says that incus is not installed yet, as in the dryrun
# of a new node.
- shell:
script: incus admin init --minimal
skip_if_this_command_succeeds:
script: incus profile device get default root pool
true_exit_codes: [0]
false_exit_codes: [1, 127]
In order, on the node:
- A package task installs Incus from the source of the node's distribution.
incus.socketis started and enabled. The socket starts the Incus server at the firstincuscommand.incus-startup.serviceis enabled to start the Incus server when the node boots. Withoutincus-startup.service, an instance withboot.autostart: "true"would start only after the firstincuscommand.- Root gets a range of user IDs and group IDs for containers, and the server is started. When a line changed, the server is restarted, because it reads the two files only at its start.
incus admin init --minimalmakes a storage pool nameddefault, the bridgeincusbr0, and the root disk and the network card of the profiledefault. It runs once: afterwards its guard finds the root disk.
A node whose apt must install no recommended packages. apt also installs the packages that a package only recommends, unless the node's apt settings say otherwise. To say otherwise, write this file before the package tasks:
- file:
path: /etc/apt/apt.conf.d/90-install-no-recommended-packages
permissions_mode: "0644"
content: |
APT::Install-Recommends "false";
The list above names dnsmasq-base, which Incus needs and which its package
only recommends, so it works with and without this file. What the file
leaves out:
| Distribution | Packages that are left out |
|---|---|
| Debian 13, Ubuntu 26.04 | apparmor, where the node does not have it already. |
| Ubuntu 24.04 | apparmor, where the node does not have it already, and incus-agent: the program that Incus puts into its virtual machine instances. |
Write the file on Ubuntu 24.04 when the node is itself a virtual machine of
another Incus. There the package incus-agent replaces the unit file
/usr/lib/systemd/system/incus-agent.service, through which the other Incus
reaches the node, and removing the package deletes that file.
Virtual machine instances need QEMU on the node, and a node that can run
virtual machines (/dev/kvm). On Debian 13 and Ubuntu 26.04, the package
incus brings QEMU in place of incus-base; restart incus.service
after you install it. Where apt installs no recommended packages, also
install what QEMU only recommends and Incus needs: ovmf, the firmware
that a virtual machine starts with; qemu-utils, whose qemu-img Incus
uses for a virtual machine's image; and qemu-system-modules-spice, for
the console that Incus gives every virtual machine. The package of the COPR
repository for the Red Hat family brings no QEMU program that Incus finds,
and Ubuntu 24.04's package brings none.
Inputs
| Input | Meaning | When omitted |
|---|---|---|
name |
The instance's name in Incus, such as shop-test. |
Required. |
state |
running: the instance exists and runs. stopped: it exists and is shut down. deleted_with_all_its_data: it is gone, with its root disk and its snapshots. |
Required. |
image_when_created |
The image that a new instance is created from. An image of another server has that server's name in front, such as images:debian/13. A name without a colon is an image of the node's own Incus, by its alias or by its fingerprint; Incus must have that image before the task runs. Used only when the instance does not exist yet. |
A task that would create the instance fails. |
instance_type |
container or virtual_machine. Incus creates an instance of the type of its image, so an image of the other type fails the task, and so does an existing instance of the other type. |
Required with running and stopped. |
profiles |
The instance's profiles, in order. Replaces the whole ordered list, because a later profile overrides an earlier one. An empty list means no profile. | Required with running and stopped. |
config |
Incus configuration keys with their values as text, such as limits.cpu: "2". Comes with config_keys_not_listed. |
The instance's keys are left alone. |
config_keys_not_listed |
remove: config is the instance's whole configuration, and every other key of the instance is removed. keep: the keys in config are set, and every other key stays. Incus's own volatile.* and image.* keys are never removed. |
Required with config. |
devices |
The instance's own devices by name. Each device is a mapping of Incus device options with their values as text. Comes with devices_not_listed. Replaces each listed device's whole definition, also with devices_not_listed: keep. |
The instance's devices are left alone. |
devices_not_listed |
remove: devices holds all of the instance's own devices, and every other own device is removed. keep: the listed devices are set, and every other own device stays. A device that a profile gives the instance is not the instance's own and is left alone. |
Required with devices. |
wait_for_shutdown_at_most |
How long state: stopped waits for shutdown. A positive duration of whole seconds, such as 30s or 2m. Incus takes a timeout in whole seconds. |
2m. |
power_off_when_shutdown_takes_longer |
What happens when wait_for_shutdown_at_most expires and the instance still runs. true: the module stops the instance at once (incus stop --force), as if its power were cut. false: the task fails. |
false. |
incus_project |
The Incus project that holds the instance. An Incus project is a group of instances and profiles inside one Incus server; it is not the MMX project. A project that does not exist is a missing prerequisite. | Incus's project default. |
- Every value is text. Incus stores each configuration value and each
device option as text. Write a number or
truein quotes:limits.cpu: "2",readonly: "true". - A key or an option cannot have an empty value. Incus stores none. To
remove a key, leave it out and write
config_keys_not_listed: remove. image_when_createdandincus_projectdo not start with a hyphen. The programincuswould read such a value as one of its options.deleted_with_all_its_dataaccepts onlynameandincus_project.- An existing instance is never created again.
image_when_createdsays what a new instance is created from. An instance that exists keeps its image, whatever the task names.
The module creates no Incus project. An earlier node task creates the
project of incus_project, for example:
- shell:
script: incus project create staging
skip_if_this_command_succeeds: incus project show staging
Outputs
| Output | Meaning |
|---|---|
created |
true when this task created the instance. In a dryrun: true when a run would create it. |
A later node task reads the created output as .node_tasks.<id>.created.
What a dryrun reports
A dryrun reads with incus query and runs no changing command.
- For a missing instance:
would_change, withwould create the container shop-test from the image images:debian/13; would start it. - For an instance whose profiles, keys, or devices differ:
would_change, with each difference, such aswould set the profiles to default, web; would set the configuration key limits.cpu; would remove the device old-disk. The reason names keys and devices and never a value. - For another state:
would start the instance shop-test,would resume the frozen instance shop-test,would shut down the instance shop-test, orwould delete the instance shop-test with all its data. not_checkedwhile the programincusis not installed, while the Incus server does not answer, while the Incus project ofincus_projectdoes not exist, and while the node's Incus has no image of the name inimage_when_created. An earlier node task may provide each of them.- It fails as a run does when the inputs break a rule, when the image
or the instance has the other type, and when
state: stoppedmeets a frozen or an ephemeral instance. - It does not ask Incus whether Incus accepts a change. Incus checks a
key, a value, and a device only when it writes them. So a dryrun can
report
would_changefor a task whose run then fails with Incus's message: an unknown key, an image that another server does not have, a device whose port is in use, an instance that is protected against deletion, or an instance that does not shut down in time. - What its reads leave on the node: the first
incuscommand of the account root writes root's client settings to/root/.config/incus/. On Debian and Ubuntu, a read starts a stopped Incus server throughincus.socket.
Examples
A Debian 13 container that runs, with two CPUs and 4 GiB of memory. Port 8080 of the node reaches port 80 inside it. The task's keys and devices are all the instance has of its own:
- incus_instance:
name: shop-test
state: running
image_when_created: images:debian/13
profiles: [default]
config:
limits.cpu: "2"
limits.memory: 4GiB
boot.autostart: "true"
config_keys_not_listed: remove
devices:
web:
type: proxy
listen: tcp:0.0.0.0:8080
connect: tcp:127.0.0.1:80
devices_not_listed: remove
instance_type: container
Set one key of a running container whose complete ordered profile list is
[default], keeping its other configuration keys and devices.
profiles must list every profile already assigned to the instance, in order;
copying [default] onto an instance with other profiles removes those profiles:
- incus_instance:
name: shop-test
state: running
config:
limits.memory: 8GiB
config_keys_not_listed: keep
instance_type: container
profiles: [default]
Shut an instance down, wait up to a minute, and stop it at once when it has not shut down by then; then delete another instance with its data:
- incus_instance:
name: shop-test
state: stopped
wait_for_shutdown_at_most: 60s
power_off_when_shutdown_takes_longer: true
instance_type: container
profiles: [default]
- incus_instance:
name: shop-old
state: deleted_with_all_its_data
Errors and what they mean
When an MMX reason includes Error:, the text after Error: is Incus's
own error message. Incus words its messages differently in each version.
MMX tries a failed task three times. A task below that "fails once" is not tried again: either another try would end the same way, or another try would find what the first try left and report success, and the failure would be lost.
| The reason holds | What it means, and what to do |
|---|---|
the program incus is not installed |
The node has no Incus. A dryrun reports the task not_checked; a run fails once. Install the package in an earlier node task; see Set up. |
the Incus server on this node does not answer |
The program is there, and the server is not started or does not answer. A dryrun reports not_checked; a run is tried again. Start incus.socket in an earlier node task. |
the Incus project ... does not exist |
incus_project names a project that Incus does not have. A dryrun reports not_checked; a run fails once. Create the project in an earlier node task; Inputs shows one. |
the Incus server on this node has no image ... |
image_when_created names an image of the node's own Incus, and Incus has none of that alias or fingerprint. A dryrun reports not_checked; a run fails once. Import the image in an earlier node task, or name an image of another server, such as images:debian/13. |
incus_instance.image_when_created: is required to create the instance ... |
The instance does not exist, and the task names no image. Write image_when_created. |
incus_instance.instance_type: ... the image ... is the image of a ... |
The image has the other type than the task. Nothing was created. Write the instance_type of the image, or name another image. |
incus_instance.instance_type: ... created an instance of the type ...; the task deleted the new instance again |
An image of another server has the other type than the task. The module saw that only after Incus created the instance, and deleted the instance, which never ran. Write the instance_type of the image. When the reason ends with deleting the new instance again failed, the instance is still there, and the task reports created: true. |
incus_instance.instance_type: ... Incus cannot change the type of an instance |
The instance exists with the other type. Write its type, or delete it first with deleted_with_all_its_data. |
incus_instance.state: the instance ... is frozen |
state: stopped met an instance that incus pause froze. Incus does not shut such an instance down. Run incus resume NAME, or a task with state: running, first. |
incus_instance.state: the instance ... is ephemeral |
Incus deletes an ephemeral instance when it stops, so stopped would destroy it. To delete it, write state: deleted_with_all_its_data. |
shutting down the instance ..., with a wait of N seconds |
The instance did not shut down within the wait. The reason ends with its status. The task fails once: another try would wait as long again. Give the instance more wait_for_shutdown_at_most, or write power_off_when_shutdown_takes_longer: true. |
creating the instance ... from the image ...: Error: ... |
Incus refused to create the instance: an image that the other server does not have, a wrong key or device, or no profile that gives a root disk. No instance is left. Correct what Incus's message names. |
created the instance ..., and starting it failed |
The instance exists and did not start, for example because a proxy device wants a port that is in use. The reason ends with the status that the instance has afterwards. The task fails once, with created: true. Correct the cause; the next run writes what differs and starts the instance. |
starting the instance ...: Error: ... |
An instance that existed before did not start. The reason ends with the status that the instance has afterwards. While it is Stopped, MMX tries the start again; when it is Running, the task fails once. Correct what Incus's message names. |
writing the configuration of the instance ...: Error: ... |
Incus refused the new configuration: an unknown key, a bad value, a key that a running virtual machine cannot take, or a new device that cannot start, such as a proxy device whose port is in use. Incus stored none of it, and the task fails once. The reason ends with the status that the instance has now. Correct what Incus's message names; for a running virtual machine, shut the instance down first. |
deleting the instance ...: Error: ... |
Incus refused, usually because the key security.protection.delete protects the instance. Set that key to "false" first, in the instance or in the profile that gives it. |
has the status ..., and this module acts only on the statuses Stopped, Running, and Frozen |
Incus is still starting or stopping the instance, or the instance is in an error state. The task is tried again; incus info NAME shows the instance. |
reading ... from the Incus server on this node: ... (error code N) |
The server answered a read with an error, such as Invalid instance name. Correct what the server's message names. |
config_keys_not_listed: is required with config, devices_not_listed: is required with devices |
A task that gives a list says what happens to the rest. Write the setting: remove or keep. |
state: deleted_with_all_its_data accepts only name and incus_project; remove ... |
The state takes no other input. Remove the input that the message names. |
has an empty value |
Incus stores no key and no device option without a value. Leave the key or the option out. |
must not be empty, must not start with a hyphen |
A name is empty, or the program incus would read it as one of its options. Correct the input that the message names. |
A task that Incus refuses reports changed. MMX reports changed for
every changing command that ran, also for one that Incus refused: MMX
cannot see whether a failed command changed something. A refused incus config edit stores nothing, and its task still reports failed and
changed.
A value that Incus refuses appears in the reason. Incus puts a refused
value into its message, such as Invalid value: .... When a secret of the
project is in config, MMX hides the whole result of the task, and the
reason with it.
Tested on
Distributions: Debian 12 and 13, Ubuntu 24.04 and 26.04, Rocky Linux 9, AlmaLinux 10.
The suite tests/integration/incus_instances.py runs incus_instance and
incus_profile through mmx against a real Incus server, on x86_64 virtual
machines.
| Distribution | Incus | A virtual machine instance in the suite |
|---|---|---|
| Debian 13 | 6.0.4 | no: the package incus-base runs containers only |
| Debian 12 | 6.0.4, from backports | no |
| Ubuntu 26.04 | 6.0.5 | yes: after the example's incus-base, the suite installs incus and the three packages above |
| Ubuntu 24.04 | 6.0.0 | no: the package brings no QEMU |
| Rocky Linux 9 | 6.23, from the COPR repository | no: the package brings no QEMU program that Incus finds |
| AlmaLinux 10 | 6.23, from the COPR repository | no |
The COPR repository is the work of one packager; the Incus project names it and does not maintain it.
Why it works this way
-
A listed device is one whole definition. Incus validates devices as complete definitions;
devices_not_listedcontrols only unnamed devices. -
Type and profiles are required. These choices depend on the instance; settings with no safe guess are required.
-
The image applies only at creation.
image_when_createdfollows the creation-only naming rule. -
The shutdown wait is a duration.
wait_for_shutdown_at_most: 2mreads like the time limits of core modules. Whole seconds match Incus's timeout. -
Every name has the prefix
local:, and every command names its project. Root's own client settings, in/root/.config/incus/, can name another default server (incus remote switch) and another default project (incus project switch). A task must manage the Incus of its node and the project that the task names. -
An alias in root's client settings still applies. Incus has no option that switches the aliases of that file off. An alias named
startthere would replace the module'sincus start. -
Every read is
incus query --raw. It prints JSON, and a code in it says whether the instance exists. Incus's error texts differ between its versions, so the module decides nothing from a text. -
The module writes the whole configuration back.
incus config edittakes a whole document and removes what the document leaves out, also Incus's own keys, the description, and the profiles. So the module reads the instance right before the write, changes the profiles, the keys, and the devices that the task names, and writes all of it. -
A configuration value travels through standard input only. The commands that MMX records hold no value, and a reason names keys and devices, never a value.
-
The module never restarts an instance. A restart ends what runs inside. Incus applies most keys to a running instance at once. A running container stores a key that needs a restart without a message and applies it at its next start; the test nodes showed this for
environment.*,security.privileged,security.nesting,security.idmap.isolated, andraw.lxc. A running virtual machine refuses such a key. -
stoppedwaits a bounded time. Incus's own stop waits without end for an instance that ignores the request; a container gets the request as the signal SIGPWR. A task must end, so the module passes the wait to Incus. Cutting the power can lose data, so it is the project's choice. A wait that ends fails the task once: MMX's next try would wait as long again. -
stoppedrefuses an ephemeral and a frozen instance. Incus deletes an ephemeral instance when it stops, and a state that destroys data is always spelled out. Incus's stop of a frozen instance did not end on the test nodes. -
profilesis the whole list. The order of an instance's profiles decides which value wins, so a list that keeps other profiles would have no defined order. -
The module checks the type. Without its option for a virtual machine, Incus creates an instance of the type of its image and says nothing. A task that asks for a container must not get a virtual machine.
-
A change that Incus refuses can still change the instance. On a test node, a memory limit that was too small for the running container was refused, and the kernel had ended the container by then. So a failed change's reason says which status the instance has afterwards.
-
A stop that fails is judged by the instance. After a failed stop, the module reads the instance: when it is stopped, the task has what it asked for.
-
A failure after the instance was created fails the task once. MMX tries a failed task again, and that try would find the new instance and report
created: falsefor an instance that this task created. An existing instance that runs after a failed start has one try for the same reason: the next try would find it running and report success. -
A document that Incus refuses fails the task once. Another try sends the same document and gets the same answer.
-
An image of the node's own Incus must be there before the task. The module asks Incus for the image by its alias and then by its fingerprint. An image that Incus does not have is a missing prerequisite, because an earlier node task may import it: a dryrun is not checked, and a run fails once.
This page is official_extra_modules/incus_instance/README.md in the MMX repository.