damex.incus.incus_profile module – Ensure Incus profile

Note

This module 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_profile.

Synopsis

  • Create, update, and delete Incus profiles via the Incus REST API.

  • Profiles are project-scoped resources.

Parameters

Parameter

Comments

client_cert

path

Path to the client certificate for remote authentication.

Requires url and client_key. Mutually exclusive with token.

client_key

path

Path to the client key for remote authentication.

Requires url and client_cert.

config

dictionary

Configuration key-value pairs.

Boolean values are converted to lowercase strings.

Dict values for cloud-init.* keys are serialized to YAML.

Default: {}

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.

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

description

string

Profile description.

Default: ""

devices

list / elements=dictionary

Devices as a list.

Each item must include a name field used as the device key in the Incus API.

Boolean values are converted to lowercase strings.

Default: []

hwaddr

string

Override the NIC MAC address (nic only).

ipv4.address

string

Static IPv4 address to assign to the NIC (nic only).

ipv4.routes

string

Comma-separated IPv4 routes to add on the host for this NIC (nic only).

ipv6.address

string

Static IPv6 address to assign to the NIC (nic only).

ipv6.routes

string

Comma-separated IPv6 routes to add on host for this NIC (nic only).

mtu

string

Override the NIC MTU (nic only).

name

string / required

Device name used as the key in the Incus API.

network

string

Managed Incus network to attach the NIC to (nic only).

nictype

string

NIC device sub-type, e.g. bridged (nic only).

parent

string

Host bridge or interface to attach the NIC to (nic only).

path

string

Filesystem mount path inside the instance (disk only).

pool

string

Incus storage pool backing the disk device (disk only).

readonly

boolean

Expose the disk as read-only inside the instance (disk only).

Choices:

  • false

  • true

size

string

Maximum size of the disk device, e.g. 20GiB (disk only).

source

string

Host path or device to pass through (disk only).

type

string / required

Device type.

Choices:

  • "disk"

  • "nic"

name

string / required

Name of the profile.

project

string

Incus project to query.

Default: "default"

server_cert

path

Path to the server certificate for remote verification.

Requires url.

socket_path

string

Path to the Incus Unix socket for local connections.

Default: "/var/lib/incus/unix.socket"

state

string

Desired state of the profile.

Choices:

  • "present" ← (default)

  • "absent"

token

string

Token for remote authentication.

Requires url. Mutually exclusive with client_cert.

url

string

URL of the remote Incus server (e.g. https://host:8443).

If specified, connects via HTTPS instead of Unix socket.

validate_certs

boolean

Whether to validate the server TLS certificate.

Choices:

  • false

  • true ← (default)

wait

boolean

Whether to wait for async operations to complete before returning.

Set to false for fire-and-forget behaviour.

Choices:

  • false

  • true ← (default)

Examples

- name: Create profile
  damex.incus.incus_profile:
    name: base
    description: Base profile
    config:
      limits.cpu: "2"
      limits.memory: 2GiB
    devices:
      - name: root
        type: disk
        path: /
        pool: default
      - name: eth0
        type: nic
        network: incusbr0

- name: Remove profile
  damex.incus.incus_profile:
    name: base
    state: absent

Authors

  • Roman Kuzmitskii (@damex)