incus_profile
incus_profile manages one profile of Incus
on a node. A profile is a named set of configuration keys and devices that
Incus gives to every instance that lists the profile, such as a memory limit
or a network card. The module creates the profile, keeps its description, its
keys, and its devices as the task writes them, or removes it. It does this
through the program incus, which it runs as root on the node, and it
manages the Incus server of that node.
incus_instance manages the instances, which
name their profiles in its input profiles.
Set up
The module installs nothing. These node tasks install Incus, start its
server, and make the server ready for its first instance. They work on every
distribution of the table; each when chooses the tasks of 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.
Inputs
| Input | Meaning | When omitted |
|---|---|---|
name |
The profile's name in Incus, such as web. |
Required. |
state |
present: the profile exists with what the task gives. absent: the profile is removed. |
present. |
description |
The text that Incus shows beside the profile. | A new profile has none; an existing one keeps its text. |
config |
Incus configuration keys with their values as text, such as limits.cpu: "2". You must also supply config_keys_not_listed. |
The profile's keys are left alone. |
config_keys_not_listed |
remove: config is the profile's whole configuration, and every other key is removed. keep: the keys in config are set, and every other key stays. |
Required with config. |
devices |
The profile's devices by name. Each device is a mapping of Incus device options with their values as text. You must also supply devices_not_listed. Replaces each listed device's whole definition, also with devices_not_listed: keep. |
The profile's devices are left alone. |
devices_not_listed |
remove: devices holds all of the profile's devices, and every other device is removed. keep: the listed devices are set, and every other device stays. |
Required with devices. |
incus_project |
The Incus project that holds the profile. 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. incus_projectdoes not start with a hyphen. The programincuswould read such a value as one of its options.absentaccepts onlynameandincus_project.- Incus applies a changed profile at once to every instance that lists it, also to a running one.
- A project can use the profiles of the project
default(its Incus settingfeatures.profilesisfalse). Such a project has no profile of its own, and a task that names it inincus_projectfails: write the task withoutincus_project.
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 profile. 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 profile:
would_change, withwould create the profile web; would set the description; would set the configuration key limits.cpu; would set the device eth0. - For a profile whose description, keys, or devices differ:
would_change, with each difference, such aswould set the configuration key limits.cpu; would remove the device old-disk. The reason names keys and devices and never a value. - For
state: absent:would remove the profile web. not_checkedwhile the programincusis not installed, while the Incus server does not answer, and while the Incus project ofincus_projectdoes not exist. An earlier node task may provide each of them.- It fails as a run does when the inputs break a rule and when
incus_projectnames a project without profiles of its own. - It does not ask Incus whether Incus accepts a change. Incus checks a
key, a value, and a device only when it writes them, and it refuses to
delete a profile that an instance uses and the profile
default. So a dryrun can reportwould_changefor a task whose run then fails with Incus's message. - 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 profile that limits each of its instances to two CPUs and connects them to
the bridge incusbr0. The task's keys and devices are all the profile has:
- incus_profile:
name: web
description: Limits and the bridge for web containers
config:
limits.cpu: "2"
config_keys_not_listed: remove
devices:
eth0:
type: nic
network: incusbr0
devices_not_listed: remove
Set one key of Incus's profile default and leave its other keys and its
devices alone:
- incus_profile:
name: default
config:
boot.autostart: "true"
config_keys_not_listed: keep
Remove a profile of the Incus project staging, after the instance that
used it:
- incus_instance:
name: shop-test
state: deleted_with_all_its_data
incus_project: staging
- incus_profile:
name: web
state: absent
incus_project: staging
Errors and what they mean
A reason that holds a text after Error: holds Incus's own message. Incus
words its messages differently in each of its versions.
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. |
incus_profile.incus_project: the Incus project ... uses the profiles of the project default |
The project has no profile of its own. Incus would change the profile of the project default under this project's name. Write the task without incus_project. |
creating the profile ...: Error: ... |
Incus refused the name, for example a name with a slash. Choose a name that Incus accepts. |
writing the new profile ...: Error: ...; the task removed the new profile again |
Incus refused a key, a value, or a device of a profile that this task had just created. The task removed the profile, so nothing is left, and it fails once. Correct what Incus's message names. When the reason ends with removing the new profile again failed, the empty profile is still there, and the task reports created: true. |
writing the profile ...: Error: ... |
Incus refused a key, a value, or a device. The profile is as it was, and the task fails once. Correct what Incus's message names. |
Incus saved the profile all the same |
Incus wrote the profile, and an instance that uses it could not take the change, for example a device whose port is in use. Incus's own message says "profile change still saved". The profile is as the task writes it, so the next run finds nothing to write, while that instance still lacks the change. The task fails once. Correct the instance that Incus's message names; Incus applies the profile to it when the instance starts again. |
removing the profile ...: Error: ... |
Incus refused: an instance still uses the profile, or it is the profile default, which Incus never deletes. Take the profile out of its instances first, or delete those instances in earlier node tasks. |
reading ... from the Incus server on this node: ... (error code N) |
The server answered a read with an error. 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: absent 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 new profile that
Incus refuses is created and removed again, and its task 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 |
|---|---|
| Debian 13 | 6.0.4 |
| Debian 12 | 6.0.4, from backports |
| Ubuntu 26.04 | 6.0.5 |
| Ubuntu 24.04 | 6.0.0 |
| Rocky Linux 9 | 6.23, from the COPR repository |
| AlmaLinux 10 | 6.23, from the COPR repository |
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. -
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
profilethere would replace the module'sincus profilecommands. -
Every read is
incus query --raw. The command prints JSON, and a code in the JSON says whether the profile exists. Incus's error texts differ between versions, so the module decides nothing from a text. -
The module writes the whole profile back.
incus profile edittakes a whole document and removes what the document leaves out. So the module reads the profile right before the write, changes the description, the keys, and the devices that the task names, and writes all of it. -
A new profile takes two commands. The module creates the profile empty and then writes it. Incus 6.0.0 ignores a document that
incus profile creategets, without an error, so one command would leave an empty profile there. -
A new profile that Incus refuses is removed again. A failed run then leaves nothing, as on the newer Incus versions, whose
incus profile createcreates no profile from a refused document. No instance can use the profile yet. -
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 does not ask who uses a profile. Incus refuses to delete a profile in use, and the task fails with Incus's message. A playbook that deletes the instances first and then removes the profile passes its dryrun and its run.
-
A failed write is read again.
incus profile editcan save a profile and still fail, when an instance that uses the profile cannot take the change. MMX tries a failed task again, and that try would find the saved profile and report success. So the module reads the profile after a failed write, and a profile that Incus saved fails the task once, with Incus's message. -
A document that Incus refuses fails the task once. Another try sends the same document and gets the same answer.
This page is official_extra_modules/incus_profile/README.md in the MMX repository.