damex.incus.incus_instances role – Ensure Incus instances.

Note

This role is part of the damex.incus collection (version 1.6.1).

It is not included in ansible-core. To check whether it is installed, run ansible-galaxy collection list.

To install it use: ansible-galaxy collection install damex.incus.

To use it in a playbook, specify: damex.incus.incus_instances.

Entry point `main` – Ensure Incus instances.

Synopsis 

Ensure Incus instances.

Parameters 

Parameter	Comments
incus_instances list / elements=dictionary	List of instances to ensure.
config dictionary	Instance configuration keys.
agent.nic_config boolean	Use instance NIC names and MTU for default interfaces. Choices: `false` `true`
boot.autorestart boolean	Whether to restart the instance after a crash. Choices: `false` `true`
boot.autostart boolean	Whether to start the instance on daemon startup. Choices: `false` `true`
boot.autostart.delay integer	Seconds to wait after the instance started.
boot.autostart.priority integer	Instance startup priority (higher starts first).
boot.host_shutdown_action string	Action to take on host shutdown.
boot.host_shutdown_timeout integer	Seconds to wait for instance to stop on host shutdown.
boot.stop.priority integer	Instance shutdown priority (higher stops first).
cloud-init.network-config dictionary	Cloud-init network configuration.
bonds list / elements=dictionary	Bond interface configurations.
addresses list / elements=string	Static addresses in CIDR notation.
dhcp4 boolean	Whether to enable DHCPv4. Choices: `false` `true`
interfaces list / elements=string	Member interfaces for the bond.
name string / required	Bond name.
nameservers dictionary	DNS server configuration.
addresses list / elements=string	List of DNS server addresses.
parameters dictionary	Bond parameters.
mii-monitor-interval integer	MII monitoring interval in milliseconds.
mode string	Bonding mode.
routes list / elements=dictionary	Static routes for the bond.
to string	Route destination in CIDR notation.
via string	Gateway address for the route.
bridges list / elements=dictionary	Bridge interface configurations.
addresses list / elements=string	Static addresses in CIDR notation.
dhcp4 boolean	Whether to enable DHCPv4. Choices: `false` `true`
interfaces list / elements=string	Member interfaces for the bridge.
name string / required	Bridge name.
nameservers dictionary	DNS server configuration.
addresses list / elements=string	List of DNS server addresses.
parameters dictionary	Bridge parameters.
forward-delay integer	Forwarding delay in seconds.
stp boolean	Whether to enable Spanning Tree Protocol. Choices: `false` `true`
routes list / elements=dictionary	Static routes for the bridge.
to string	Route destination in CIDR notation.
via string	Gateway address for the route.
ethernets list / elements=dictionary	Ethernet interface configurations.
addresses list / elements=string	Static addresses in CIDR notation.
dhcp4 boolean	Whether to enable DHCPv4. Choices: `false` `true`
match dictionary	Match rules for the interface.
driver string	Kernel driver name to match.
name string / required	Interface name.
nameservers dictionary	DNS server configuration.
addresses list / elements=string	List of DNS server addresses.
routes list / elements=dictionary	Static routes for the interface.
to string	Route destination in CIDR notation.
via string	Gateway address for the route.
renderer string	Network renderer to use.
version integer	Network config format version.
vlans list / elements=dictionary	VLAN interface configurations.
addresses list / elements=string	Static addresses in CIDR notation.
dhcp4 boolean	Whether to enable DHCPv4. Choices: `false` `true`
id integer / required	VLAN ID.
link string / required	Parent interface for the VLAN.
name string / required	VLAN interface name.
nameservers dictionary	DNS server configuration.
addresses list / elements=string	List of DNS server addresses.
routes list / elements=dictionary	Static routes for the VLAN.
to string	Route destination in CIDR notation.
via string	Gateway address for the route.
cloud-init.user-data dictionary	Cloud-init user data configuration.
bootcmd list / elements=any	Commands to run early in the boot process.
chpasswd dictionary	Password change settings.
expire boolean	Whether the password expires on first login. Choices: `false` `true`
package_upgrade boolean	Whether to upgrade packages on first boot. Choices: `false` `true`
packages list / elements=string	Packages to install on first boot.
password string	Password for the default user.
power_state dictionary	Power state change after cloud-init completes.
mode string	Power state action to take. Choices: `"reboot"` `"poweroff"` `"halt"`
runcmd list / elements=any	Commands to run after cloud-init completes.
ssh_pwauth boolean	Whether to enable SSH password authentication. Choices: `false` `true`
user string	Default user name.
write_files list / elements=dictionary	Files to create on first boot.
content string	Content to write to the file.
owner string	Owner and group of the file.
path string / required	Absolute path of the file to create.
permissions string	File permissions in octal notation.
cloud-init.vendor-data dictionary	Cloud-init vendor data configuration.
bootcmd list / elements=any	Commands to run early in the boot process.
chpasswd dictionary	Password change settings.
expire boolean	Whether the password expires on first login. Choices: `false` `true`
package_upgrade boolean	Whether to upgrade packages on first boot. Choices: `false` `true`
packages list / elements=string	Packages to install on first boot.
password string	Password for the default user.
power_state dictionary	Power state change after cloud-init completes.
mode string	Power state action to take. Choices: `"reboot"` `"poweroff"` `"halt"`
runcmd list / elements=any	Commands to run after cloud-init completes.
ssh_pwauth boolean	Whether to enable SSH password authentication. Choices: `false` `true`
user string	Default user name.
write_files list / elements=dictionary	Files to create on first boot.
content string	Content to write to the file.
owner string	Owner and group of the file.
path string / required	Absolute path of the file to create.
permissions string	File permissions in octal notation.
cluster.evacuate string	Evacuation behavior during cluster evacuation. Choices: `"auto"` `"live-migrate"` `"migrate"` `"stop"` `"stateful-stop"` `"force-stop"`
limits.cpu string	Number or range of CPUs to expose.
limits.cpu.allowance string	CPU time allowance as a percentage or fixed duration.
limits.cpu.nodes string	NUMA nodes to restrict the instance to.
limits.cpu.priority integer	CPU scheduling priority compared to other instances.
limits.disk.priority integer	I/O request priority when under load (0-10).
limits.hugepages.1GB string	Limit for 1GB huge pages.
limits.hugepages.1MB string	Limit for 1MB huge pages.
limits.hugepages.2MB string	Limit for 2MB huge pages.
limits.hugepages.64KB string	Limit for 64KB huge pages.
limits.memory string	Percentage of host memory or fixed value in bytes.
limits.memory.enforce string	Memory limit enforcement mode.
limits.memory.hotplug string	Whether to enable memory hotplug.
limits.memory.hugepages boolean	Whether to back instance memory with huge pages. Choices: `false` `true`
limits.memory.oom_priority integer	OOM killer priority for the instance.
limits.memory.swap string	Whether to encourage or discourage swapping.
limits.memory.swap.priority integer	Swap priority compared to other instances.
limits.network.priority integer	Network I/O priority compared to other instances.
limits.processes integer	Maximum number of processes in the instance.
linux.kernel_modules string	Comma-separated kernel modules to load.
migration.incremental.memory boolean	Whether to use incremental memory transfer. Choices: `false` `true`
migration.incremental.memory.goal integer	Target percentage of dirty memory for completion.
migration.incremental.memory.iterations integer	Maximum number of memory transfer iterations.
migration.stateful boolean	Allow stateful stop/start and snapshots. Choices: `false` `true`
nvidia.driver.capabilities string	NVIDIA driver capabilities to expose.
nvidia.require.cuda string	Required CUDA version.
nvidia.require.driver string	Required NVIDIA driver version.
nvidia.runtime boolean	Pass NVIDIA runtime libraries into the container. Choices: `false` `true`
oci.cwd string	Working directory for the OCI container.
oci.entrypoint string	Entrypoint for the OCI container.
oci.gid string	GID to run the OCI container as.
oci.uid string	UID to run the OCI container as.
raw.apparmor string	Raw AppArmor profile entries.
raw.idmap string	Raw ID map configuration.
raw.lxc string	Raw LXC configuration to append.
raw.qemu string	Raw QEMU command-line arguments.
raw.qemu.conf string	Raw QEMU configuration overrides.
raw.qemu.qmp.early string	Raw QMP commands before instance start.
raw.qemu.qmp.post-start string	Raw QMP commands after instance start.
raw.qemu.qmp.pre-start string	Raw QMP commands just before instance start.
raw.qemu.scriptlet string	Raw QEMU scriptlet.
raw.seccomp string	Raw Seccomp configuration.
security.agent.metrics boolean	Whether the incus-agent exposes metrics. Choices: `false` `true`
security.bpffs.delegate_attachs string	Delegated BPF attach types.
security.bpffs.delegate_cmds string	Delegated BPF commands.
security.bpffs.delegate_maps string	Delegated BPF map types.
security.bpffs.delegate_progs string	Delegated BPF program types.
security.bpffs.path string	Path to the BPFFS mount in the instance.
security.csm boolean	Whether to enable Compatibility Support Module. Choices: `false` `true`
security.guestapi boolean	Whether to enable the guest API. Choices: `false` `true`
security.guestapi.images boolean	Whether to allow image access via the guest API. Choices: `false` `true`
security.idmap.base integer	Base host UID/GID for the ID map.
security.idmap.isolated boolean	Whether to use a unique ID map for the instance. Choices: `false` `true`
security.idmap.size integer	Size of the ID map range.
security.iommu boolean	Whether to enable IOMMU for the instance. Choices: `false` `true`
security.nesting boolean	Allow running Incus inside the instance. Choices: `false` `true`
security.privileged boolean	Whether to run the instance in privileged mode. Choices: `false` `true`
security.protection.delete boolean	Whether to prevent deletion of the instance. Choices: `false` `true`
security.protection.shift boolean	Whether to prevent UID/GID shifting. Choices: `false` `true`
security.secureboot boolean	Whether to enable UEFI Secure Boot. Choices: `false` `true`
security.sev boolean	Whether to enable AMD SEV encryption. Choices: `false` `true`
security.sev.policy.es boolean	Whether to enable SEV-ES for the instance. Choices: `false` `true`
security.sev.session.data string	SEV session data blob.
security.sev.session.dh string	SEV Diffie-Hellman key.
security.syscalls.allow string	Allowed syscalls whitelist.
security.syscalls.deny string	Denied syscalls blacklist.
security.syscalls.deny_compat boolean	Whether to block compat syscalls on amd64. Choices: `false` `true`
security.syscalls.deny_default boolean	Whether to enable default syscall deny list. Choices: `false` `true`
security.syscalls.intercept.bpf boolean	Whether to intercept bpf syscalls. Choices: `false` `true`
security.syscalls.intercept.bpf.devices boolean	Whether to allow device-type BPF programs. Choices: `false` `true`
security.syscalls.intercept.mknod boolean	Whether to intercept mknod syscalls. Choices: `false` `true`
security.syscalls.intercept.mount boolean	Whether to intercept mount syscalls. Choices: `false` `true`
security.syscalls.intercept.mount.allowed string	Filesystems allowed for intercepted mounts.
security.syscalls.intercept.mount.fuse string	FUSE mounts to redirect intercepted mounts to.
security.syscalls.intercept.mount.shift boolean	Whether to use ID-mapped mounts for intercepted mounts. Choices: `false` `true`
security.syscalls.intercept.sched_setscheduler boolean	Whether to intercept sched_setscheduler syscalls. Choices: `false` `true`
security.syscalls.intercept.setxattr boolean	Whether to intercept setxattr syscalls. Choices: `false` `true`
security.syscalls.intercept.sysinfo boolean	Whether to intercept sysinfo syscalls. Choices: `false` `true`
snapshots.expiry string	Automatic expiry time for snapshots.
snapshots.expiry.manual string	Expiry time for manually created snapshots.
snapshots.pattern string	Pongo2 template for snapshot names.
snapshots.schedule string	Cron expression for automatic snapshots.
snapshots.schedule.stopped boolean	Whether to snapshot stopped instances. Choices: `false` `true`
devices list / elements=dictionary	Devices to attach to the instance.
hwaddr string	MAC address for the NIC.
ipv4.address string	IPv4 address for the NIC.
ipv4.routes string	IPv4 routes to add for the NIC.
ipv6.address string	IPv6 address for the NIC.
ipv6.routes string	IPv6 routes to add for the NIC.
mtu string	MTU of the NIC.
name string / required	Name of the device.
network string	Managed network to attach the NIC to.
nictype string	NIC type.
parent string	Parent network device on the host.
path string	Mount path inside the instance.
pool string	Storage pool for the disk device.
readonly boolean	Whether the disk is read-only. Choices: `false` `true`
size string	Size of the disk device.
source string	Source path or volume for the disk device.
type string / required	Device type. Choices: `"disk"` `"nic"`
ephemeral boolean	Whether the instance is ephemeral. Choices: `false` `true`
name string / required	Name of the instance.
profiles list / elements=string	List of profiles to apply to the instance.
project string	Incus project to scope the instance to.
source string / required	Image source for the instance.
state string	Desired state of the instance. Choices: `"started"` `"stopped"` `"restarted"` `"absent"`
type string	Instance type. Choices: `"container"` `"virtual-machine"`
incus_instances_client_cert path	Path to the TLS client certificate.
incus_instances_client_key path	Path to the TLS client key.
incus_instances_ephemeral boolean	Whether instances are ephemeral. Choices: `false` `true`
incus_instances_profiles list / elements=string	List of profiles to apply to instances.
incus_instances_project string	Incus project to scope instances to.
incus_instances_server_cert path	Path to the TLS server certificate.
incus_instances_socket_path path	Path to the Incus Unix socket.
incus_instances_state string	Desired state of the instances. Choices: `"started"` `"stopped"` `"restarted"` `"absent"`
incus_instances_token string	Authentication token for the Incus API.
incus_instances_type string	Instance type. Choices: `"container"` `"virtual-machine"`
incus_instances_url string	URL of the Incus server API.
incus_instances_validate_certs boolean	Whether to validate TLS certificates. Choices: `false` `true`

Examples 

- name: Ensure incus instances
  hosts: incus
  tasks:
    - name: Ensure incus instances
      ansible.builtin.import_role:
        name: damex.incus.incus_instances
      vars:
        incus_instances:
          - name: web-01
            source: images:debian/13
            profiles:
              - default
            config:
              limits.cpu: "2"
              limits.memory: 2GB
          - name: db-01
            source: images:ubuntu/24.04
            type: virtual-machine
            config:
              limits.cpu: "4"
              limits.memory: 4GB
            devices:
              data:
                type: disk
                source: data
                path: /var/lib/postgresql

- name: Ensure incus instances with cloud-init
  hosts: incus
  tasks:
    - name: Ensure incus instances with cloud-init
      ansible.builtin.import_role:
        name: damex.incus.incus_instances
      vars:
        incus_instances:
          - name: app-01
            source: images:debian/13
            config:
              cloud-init.user-data:
                users:
                  - name: deploy
                    groups: sudo
                    shell: /bin/bash
                    ssh_authorized_keys:
                      - ssh-ed25519 AAAA... [email protected]
                packages:
                  - nginx
                  - postgresql-client

Collection links