damex.incus.incus_instance module – Ensure Incus instance

Note

This module is part of the damex.incus collection (version 1.11.7).

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_instance.

Synopsis

  • Create, configure, and manage the lifecycle of Incus instances via the Incus REST API.

  • Instances are project-scoped resources.

  • The instance type and source are set on creation and cannot be changed afterwards.

Parameters

Parameter

Comments

client_cert

string

Client certificate content for remote authentication.

Requires url and client_key. Mutually exclusive with token and client_cert_path.

client_cert_path

string

Client certificate path for remote authentication.

Requires url and client_key_path. Mutually exclusive with token and client_cert.

client_key

string

Client key content for remote authentication.

Requires url and client_cert. Mutually exclusive with client_key_path.

client_key_path

string

Client key path for remote authentication.

Requires url and client_cert_path. Mutually exclusive with client_key.

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

Auto-restart after crash.

Choices:

  • false

  • true

boot.autostart

boolean

Instance autostart 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.

accept-ra

boolean

IPv6 Router Advertisement acceptance.

Choices:

  • false

  • true

addresses

list / elements=string

Static addresses in CIDR notation.

dhcp4

boolean

DHCPv4.

Choices:

  • false

  • true

dhcp6

boolean

DHCPv6.

Choices:

  • false

  • true

gateway4

string

Default IPv4 gateway address.

gateway6

string

Default IPv6 gateway address.

interfaces

list / elements=string

Member interfaces for the bond.

mtu

integer

Maximum transmission unit for the interface.

name

string / required

Bond name.

nameservers

dictionary

DNS server configuration.

addresses

list / elements=string

DNS server addresses.

list / elements=string

DNS search domains.

optional

boolean

Optional boot interface.

Choices:

  • false

  • true

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.

metric

integer

Route metric.

scope

string

Route scope.

table

integer

Routing table ID.

to

string

Route destination in CIDR notation.

via

string

Gateway address for the route.

set-name

string

Rename the interface to this name.

bridges

list / elements=dictionary

Bridge interface configurations.

accept-ra

boolean

IPv6 Router Advertisement acceptance.

Choices:

  • false

  • true

addresses

list / elements=string

Static addresses in CIDR notation.

dhcp4

boolean

DHCPv4.

Choices:

  • false

  • true

dhcp6

boolean

DHCPv6.

Choices:

  • false

  • true

gateway4

string

Default IPv4 gateway address.

gateway6

string

Default IPv6 gateway address.

interfaces

list / elements=string

Member interfaces for the bridge.

mtu

integer

Maximum transmission unit for the interface.

name

string / required

Bridge name.

nameservers

dictionary

DNS server configuration.

addresses

list / elements=string

DNS server addresses.

list / elements=string

DNS search domains.

optional

boolean

Optional boot interface.

Choices:

  • false

  • true

parameters

dictionary

Bridge parameters.

forward-delay

integer

Forwarding delay in seconds.

stp

boolean

Spanning Tree Protocol.

Choices:

  • false

  • true

routes

list / elements=dictionary

Static routes for the bridge.

metric

integer

Route metric.

scope

string

Route scope.

table

integer

Routing table ID.

to

string

Route destination in CIDR notation.

via

string

Gateway address for the route.

set-name

string

Rename the interface to this name.

ethernets

list / elements=dictionary

Ethernet interface configurations.

accept-ra

boolean

IPv6 Router Advertisement acceptance.

Choices:

  • false

  • true

addresses

list / elements=string

Static addresses in CIDR notation.

dhcp4

boolean

DHCPv4.

Choices:

  • false

  • true

dhcp6

boolean

DHCPv6.

Choices:

  • false

  • true

gateway4

string

Default IPv4 gateway address.

gateway6

string

Default IPv6 gateway address.

match

dictionary

Match rules for the interface.

driver

string

Kernel driver name to match.

macaddress

string

MAC address to match.

name

string

Interface name to match.

mtu

integer

Maximum transmission unit for the interface.

name

string / required

Interface name.

nameservers

dictionary

DNS server configuration.

addresses

list / elements=string

DNS server addresses.

list / elements=string

DNS search domains.

optional

boolean

Optional boot interface.

Choices:

  • false

  • true

routes

list / elements=dictionary

Static routes for the interface.

metric

integer

Route metric.

scope

string

Route scope.

table

integer

Routing table ID.

to

string

Route destination in CIDR notation.

via

string

Gateway address for the route.

set-name

string

Rename the interface to this name.

renderer

string

Network renderer to use.

version

integer

Network config format version.

vlans

list / elements=dictionary

VLAN interface configurations.

accept-ra

boolean

IPv6 Router Advertisement acceptance.

Choices:

  • false

  • true

addresses

list / elements=string

Static addresses in CIDR notation.

dhcp4

boolean

DHCPv4.

Choices:

  • false

  • true

dhcp6

boolean

DHCPv6.

Choices:

  • false

  • true

gateway4

string

Default IPv4 gateway address.

gateway6

string

Default IPv6 gateway address.

id

integer / required

VLAN ID.

string / required

Parent interface for the VLAN.

mtu

integer

Maximum transmission unit for the interface.

name

string / required

VLAN interface name.

nameservers

dictionary

DNS server configuration.

addresses

list / elements=string

DNS server addresses.

list / elements=string

DNS search domains.

optional

boolean

Optional boot interface.

Choices:

  • false

  • true

routes

list / elements=dictionary

Static routes for the VLAN.

metric

integer

Route metric.

scope

string

Route scope.

table

integer

Routing table ID.

to

string

Route destination in CIDR notation.

via

string

Gateway address for the route.

set-name

string

Rename the interface to this name.

cloud-init.user-data

dictionary

Cloud-init user data configuration.

allow_public_ssh_keys

boolean

Public SSH key allowance.

Choices:

  • false

  • true

apt

dictionary

APT package manager configuration.

add_apt_repo_match

string

Regex for matching add-apt-repository entries.

conf

string

APT configuration to write.

debconf_selections

list / elements=dictionary

Debconf preseed selections.

name

string / required

Selection set identifier.

selection

string / required

Debconf selection lines.

disable_suites

list / elements=string

APT suites to disable.

ftp_proxy

string

FTP proxy URL for APT.

http_proxy

string

HTTP proxy URL for APT.

https_proxy

string

HTTPS proxy URL for APT.

preserve_sources_list

boolean

Existing sources.list preservation.

Choices:

  • false

  • true

primary

list / elements=any

Primary mirror configuration.

proxy

string

APT proxy URL.

security

list / elements=any

Security mirror configuration.

sources

list / elements=dictionary

Additional APT source definitions.

append

boolean

Source file append mode.

Choices:

  • false

  • true

filename

string

Name of the source list file.

key

string

Raw GPG key.

keyid

string

GPG key ID to import.

keyserver

string

Alternate keyserver to pull key from.

name

string / required

Source entry identifier and filename.

source

string

Sources.list entry.

sources_list

string

Custom sources.list content.

bootcmd

list / elements=any

Commands to run early in the boot process.

ca_certs

dictionary

CA certificate configuration.

remove_defaults

boolean

Default CA certificate removal.

Choices:

  • false

  • true

trusted

list / elements=string

Trusted CA certificates in PEM format.

chpasswd

dictionary

Password change settings.

expire

boolean

Password expiry on first login.

Choices:

  • false

  • true

users

list / elements=dictionary

User password entries.

name

string / required

User name.

password

string

Password for the user.

type

string

Password type.

Choices:

  • "text"

  • "hash"

  • "RANDOM"

disable_root

boolean

Root login.

Choices:

  • false

  • true

disable_root_opts

string

SSH options applied when root login is disabled.

disk_setup

list / elements=dictionary

Disk partitioning configuration.

layout

any

Partition layout specification.

name

string / required

Device path.

overwrite

boolean

Existing partition table overwrite.

Choices:

  • false

  • true

table_type

string

Partition table type.

Choices:

  • "mbr"

  • "gpt"

final_message

string

Message to display when cloud-init completes.

fqdn

string

Fully qualified domain name.

fs_setup

list / elements=dictionary

Filesystem creation configuration.

cmd

any

Custom mkfs command.

device

string

Device path.

extra_opts

list / elements=string

Extra options for mkfs.

filesystem

string

Filesystem type.

label

string

Filesystem label.

overwrite

boolean

Existing filesystem overwrite.

Choices:

  • false

  • true

partition

any

Partition specification.

replace_fs

boolean

Existing filesystem replacement.

Choices:

  • false

  • true

groups

list / elements=any

Groups to create.

growpart

dictionary

Partition growing configuration.

devices

list / elements=string

Devices to grow.

ignore_growroot_disabled

boolean

Growroot disabled marker bypass.

Choices:

  • false

  • true

mode

string

Growpart mode.

Choices:

  • "auto"

  • "growpart"

  • "gpart"

  • "off"

hostname

string

System hostname.

locale

string

System locale.

locale_configfile

string

Locale configuration file path.

manage_etc_hosts

boolean

/etc/hosts management.

Choices:

  • false

  • true

manage_resolv_conf

boolean

/etc/resolv.conf management.

Choices:

  • false

  • true

mount_default_fields

list / elements=any

Default values for mount entries with fewer than six fields.

mounts

list / elements=any

Mount point definitions.

ntp

dictionary

NTP client configuration.

allow

list / elements=string

Allowed NTP network ranges.

config

dictionary

NTP client-specific configuration.

check_exe

string

Executable name for the NTP client.

confpath

string

NTP client configuration file path.

packages

list / elements=string

Packages needed for the NTP client.

service_name

string

Service name for the NTP client.

template

string

Jinja template for NTP client configuration.

enabled

boolean

NTP.

Choices:

  • false

  • true

ntp_client

string

NTP client to use.

peers

list / elements=string

NTP peer nodes.

pools

list / elements=string

NTP pools.

servers

list / elements=string

NTP servers.

package_reboot_if_required

boolean

Post-upgrade reboot.

Choices:

  • false

  • true

package_update

boolean

First-boot package list update.

Choices:

  • false

  • true

package_upgrade

boolean

First-boot package upgrade.

Choices:

  • false

  • true

packages

list / elements=string

Packages to install on first boot.

password

string

Password for the default user.

phone_home

dictionary

Phone home configuration.

post

list / elements=string

Data fields to POST.

tries

integer

Number of attempts.

url

string / required

URL to POST instance data to.

power_state

dictionary

Power state change after cloud-init completes.

condition

any

Condition to check before power action.

delay

string

Delay before power action.

mode

string

Power state action to take.

Choices:

  • "reboot"

  • "poweroff"

  • "halt"

timeout

integer

Timeout in seconds for power action.

prefer_fqdn_over_hostname

boolean

FQDN preference over short hostname.

Choices:

  • false

  • true

resolv_conf

dictionary

DNS resolver configuration.

domain

string

Default DNS domain.

nameservers

list / elements=string

DNS server addresses.

options

dictionary

Resolver options for /etc/resolv.conf.

attempts

integer

Number of resolver query attempts.

edns0

boolean

EDNS0 extensions.

Choices:

  • false

  • true

inet6

boolean

IPv6 address preference.

Choices:

  • false

  • true

ndots

integer

Minimum dots in a name before absolute query.

no-check-names

boolean

Name checking disabling.

Choices:

  • false

  • true

no-reload

boolean

Automatic config reload disabling.

Choices:

  • false

  • true

no-tld-query

boolean

Top-level domain query disabling.

Choices:

  • false

  • true

rotate

boolean

Nameserver rotation.

Choices:

  • false

  • true

single-request

boolean

Sequential A and AAAA queries.

Choices:

  • false

  • true

single-request-reopen

boolean

Socket reopen for sequential queries.

Choices:

  • false

  • true

timeout

integer

Resolver query timeout in seconds.

trust-ad

boolean

Resolver AD flag trust.

Choices:

  • false

  • true

use-vc

boolean

TCP DNS queries.

Choices:

  • false

  • true

searchdomains

list / elements=string

DNS search domains.

sortlist

list / elements=string

DNS sort list.

runcmd

list / elements=any

Commands to run after cloud-init completes.

snap

dictionary

Snap package manager configuration.

commands

list / elements=any

Snap commands to execute.

ssh_authorized_keys

list / elements=string

SSH public keys to add to the default user.

ssh_deletekeys

boolean

Default SSH host key deletion.

Choices:

  • false

  • true

ssh_genkeytypes

list / elements=string

SSH key types to generate.

ssh_keys

dictionary

Pre-generated SSH host keys.

ecdsa_certificate

string

ECDSA host certificate.

ecdsa_private

string

ECDSA private host key.

ecdsa_public

string

ECDSA public host key.

ed25519_certificate

string

Ed25519 host certificate.

ed25519_private

string

Ed25519 private host key.

ed25519_public

string

Ed25519 public host key.

rsa_certificate

string

RSA host certificate.

rsa_private

string

RSA private host key.

rsa_public

string

RSA public host key.

ssh_publish_hostkeys

dictionary

SSH host key publishing configuration.

blacklist

list / elements=string

Key types to exclude from publishing.

enabled

boolean

Host key publishing.

Choices:

  • false

  • true

ssh_pwauth

boolean

SSH password authentication.

Choices:

  • false

  • true

ssh_quiet_keygen

boolean

SSH key generation output suppression.

Choices:

  • false

  • true

swap

dictionary

Swap configuration.

filename

string

Swap file path.

maxsize

any

Maximum swap size in bytes.

size

any

Swap size in bytes or auto.

timezone

string

System timezone.

user

string

Default user name.

users

list / elements=dictionary

Users to create.

create_groups

boolean

User group creation.

Choices:

  • false

  • true

doas

list / elements=string

Doas rules for the user.

expiredate

string

Account expiration date in YYYY-MM-DD format.

gecos

string

GECOS field for the user.

groups

any

Groups to add the user to.

hashed_passwd

string

Pre-hashed password for the user.

homedir

string

Home directory path.

inactive

string

Days after password expires until account is disabled.

lock_passwd

boolean

User password lock.

Choices:

  • false

  • true

name

string / required

User name.

no_create_home

boolean

Home directory creation skip.

Choices:

  • false

  • true

no_log_init

boolean

User initialization log skip.

Choices:

  • false

  • true

no_user_group

boolean

User group creation skip.

Choices:

  • false

  • true

passwd

string

Hashed password for the user.

plain_text_passwd

string

Plain text password for the user.

primary_group

string

Primary group for the user.

selinux_user

string

SELinux user for login mapping.

shell

string

Login shell for the user.

snapuser

string

Email for Snappy user creation.

ssh_authorized_keys

list / elements=string

SSH public keys to add to the user.

ssh_import_id

list / elements=string

SSH IDs to import public keys from.

ssh_redirect_user

boolean

SSH login redirection to default user.

Choices:

  • false

  • true

sudo

any

Sudo rule for the user.

system

boolean

System user.

Choices:

  • false

  • true

uid

integer

Numeric user ID.

write_files

list / elements=dictionary

Files to create on first boot.

append

boolean

File append mode.

Choices:

  • false

  • true

content

string

Content to write to the file.

defer

boolean

Deferred writing until final stage.

Choices:

  • false

  • true

encoding

string

Content encoding.

Choices:

  • "b64"

  • "base64"

  • "gz"

  • "gzip"

  • "gz+b64"

  • "gzip+b64"

  • "gz+base64"

  • "gzip+base64"

  • "text/plain"

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.

source

dictionary

URL source for file content.

headers

list / elements=dictionary

HTTP headers for the request.

name

string / required

Header name.

value

string / required

Header value.

uri

string / required

URL to fetch content from.

cloud-init.vendor-data

dictionary

Cloud-init vendor data configuration.

allow_public_ssh_keys

boolean

Public SSH key allowance.

Choices:

  • false

  • true

apt

dictionary

APT package manager configuration.

add_apt_repo_match

string

Regex for matching add-apt-repository entries.

conf

string

APT configuration to write.

debconf_selections

list / elements=dictionary

Debconf preseed selections.

name

string / required

Selection set identifier.

selection

string / required

Debconf selection lines.

disable_suites

list / elements=string

APT suites to disable.

ftp_proxy

string

FTP proxy URL for APT.

http_proxy

string

HTTP proxy URL for APT.

https_proxy

string

HTTPS proxy URL for APT.

preserve_sources_list

boolean

Existing sources.list preservation.

Choices:

  • false

  • true

primary

list / elements=any

Primary mirror configuration.

proxy

string

APT proxy URL.

security

list / elements=any

Security mirror configuration.

sources

list / elements=dictionary

Additional APT source definitions.

append

boolean

Source file append mode.

Choices:

  • false

  • true

filename

string

Name of the source list file.

key

string

Raw GPG key.

keyid

string

GPG key ID to import.

keyserver

string

Alternate keyserver to pull key from.

name

string / required

Source entry identifier and filename.

source

string

Sources.list entry.

sources_list

string

Custom sources.list content.

bootcmd

list / elements=any

Commands to run early in the boot process.

ca_certs

dictionary

CA certificate configuration.

remove_defaults

boolean

Default CA certificate removal.

Choices:

  • false

  • true

trusted

list / elements=string

Trusted CA certificates in PEM format.

chpasswd

dictionary

Password change settings.

expire

boolean

Password expiry on first login.

Choices:

  • false

  • true

users

list / elements=dictionary

User password entries.

name

string / required

User name.

password

string

Password for the user.

type

string

Password type.

Choices:

  • "text"

  • "hash"

  • "RANDOM"

disable_root

boolean

Root login.

Choices:

  • false

  • true

disable_root_opts

string

SSH options applied when root login is disabled.

disk_setup

list / elements=dictionary

Disk partitioning configuration.

layout

any

Partition layout specification.

name

string / required

Device path.

overwrite

boolean

Existing partition table overwrite.

Choices:

  • false

  • true

table_type

string

Partition table type.

Choices:

  • "mbr"

  • "gpt"

final_message

string

Message to display when cloud-init completes.

fqdn

string

Fully qualified domain name.

fs_setup

list / elements=dictionary

Filesystem creation configuration.

cmd

any

Custom mkfs command.

device

string

Device path.

extra_opts

list / elements=string

Extra options for mkfs.

filesystem

string

Filesystem type.

label

string

Filesystem label.

overwrite

boolean

Existing filesystem overwrite.

Choices:

  • false

  • true

partition

any

Partition specification.

replace_fs

boolean

Existing filesystem replacement.

Choices:

  • false

  • true

groups

list / elements=any

Groups to create.

growpart

dictionary

Partition growing configuration.

devices

list / elements=string

Devices to grow.

ignore_growroot_disabled

boolean

Growroot disabled marker bypass.

Choices:

  • false

  • true

mode

string

Growpart mode.

Choices:

  • "auto"

  • "growpart"

  • "gpart"

  • "off"

hostname

string

System hostname.

locale

string

System locale.

locale_configfile

string

Locale configuration file path.

manage_etc_hosts

boolean

/etc/hosts management.

Choices:

  • false

  • true

manage_resolv_conf

boolean

/etc/resolv.conf management.

Choices:

  • false

  • true

mount_default_fields

list / elements=any

Default values for mount entries with fewer than six fields.

mounts

list / elements=any

Mount point definitions.

ntp

dictionary

NTP client configuration.

allow

list / elements=string

Allowed NTP network ranges.

config

dictionary

NTP client-specific configuration.

check_exe

string

Executable name for the NTP client.

confpath

string

NTP client configuration file path.

packages

list / elements=string

Packages needed for the NTP client.

service_name

string

Service name for the NTP client.

template

string

Jinja template for NTP client configuration.

enabled

boolean

NTP.

Choices:

  • false

  • true

ntp_client

string

NTP client to use.

peers

list / elements=string

NTP peer nodes.

pools

list / elements=string

NTP pools.

servers

list / elements=string

NTP servers.

package_reboot_if_required

boolean

Post-upgrade reboot.

Choices:

  • false

  • true

package_update

boolean

First-boot package list update.

Choices:

  • false

  • true

package_upgrade

boolean

First-boot package upgrade.

Choices:

  • false

  • true

packages

list / elements=string

Packages to install on first boot.

password

string

Password for the default user.

phone_home

dictionary

Phone home configuration.

post

list / elements=string

Data fields to POST.

tries

integer

Number of attempts.

url

string / required

URL to POST instance data to.

power_state

dictionary

Power state change after cloud-init completes.

condition

any

Condition to check before power action.

delay

string

Delay before power action.

mode

string

Power state action to take.

Choices:

  • "reboot"

  • "poweroff"

  • "halt"

timeout

integer

Timeout in seconds for power action.

prefer_fqdn_over_hostname

boolean

FQDN preference over short hostname.

Choices:

  • false

  • true

resolv_conf

dictionary

DNS resolver configuration.

domain

string

Default DNS domain.

nameservers

list / elements=string

DNS server addresses.

options

dictionary

Resolver options for /etc/resolv.conf.

attempts

integer

Number of resolver query attempts.

edns0

boolean

EDNS0 extensions.

Choices:

  • false

  • true

inet6

boolean

IPv6 address preference.

Choices:

  • false

  • true

ndots

integer

Minimum dots in a name before absolute query.

no-check-names

boolean

Name checking disabling.

Choices:

  • false

  • true

no-reload

boolean

Automatic config reload disabling.

Choices:

  • false

  • true

no-tld-query

boolean

Top-level domain query disabling.

Choices:

  • false

  • true

rotate

boolean

Nameserver rotation.

Choices:

  • false

  • true

single-request

boolean

Sequential A and AAAA queries.

Choices:

  • false

  • true

single-request-reopen

boolean

Socket reopen for sequential queries.

Choices:

  • false

  • true

timeout

integer

Resolver query timeout in seconds.

trust-ad

boolean

Resolver AD flag trust.

Choices:

  • false

  • true

use-vc

boolean

TCP DNS queries.

Choices:

  • false

  • true

searchdomains

list / elements=string

DNS search domains.

sortlist

list / elements=string

DNS sort list.

runcmd

list / elements=any

Commands to run after cloud-init completes.

snap

dictionary

Snap package manager configuration.

commands

list / elements=any

Snap commands to execute.

ssh_authorized_keys

list / elements=string

SSH public keys to add to the default user.

ssh_deletekeys

boolean

Default SSH host key deletion.

Choices:

  • false

  • true

ssh_genkeytypes

list / elements=string

SSH key types to generate.

ssh_keys

dictionary

Pre-generated SSH host keys.

ecdsa_certificate

string

ECDSA host certificate.

ecdsa_private

string

ECDSA private host key.

ecdsa_public

string

ECDSA public host key.

ed25519_certificate

string

Ed25519 host certificate.

ed25519_private

string

Ed25519 private host key.

ed25519_public

string

Ed25519 public host key.

rsa_certificate

string

RSA host certificate.

rsa_private

string

RSA private host key.

rsa_public

string

RSA public host key.

ssh_publish_hostkeys

dictionary

SSH host key publishing configuration.

blacklist

list / elements=string

Key types to exclude from publishing.

enabled

boolean

Host key publishing.

Choices:

  • false

  • true

ssh_pwauth

boolean

SSH password authentication.

Choices:

  • false

  • true

ssh_quiet_keygen

boolean

SSH key generation output suppression.

Choices:

  • false

  • true

swap

dictionary

Swap configuration.

filename

string

Swap file path.

maxsize

any

Maximum swap size in bytes.

size

any

Swap size in bytes or auto.

timezone

string

System timezone.

user

string

Default user name.

users

list / elements=dictionary

Users to create.

create_groups

boolean

User group creation.

Choices:

  • false

  • true

doas

list / elements=string

Doas rules for the user.

expiredate

string

Account expiration date in YYYY-MM-DD format.

gecos

string

GECOS field for the user.

groups

any

Groups to add the user to.

hashed_passwd

string

Pre-hashed password for the user.

homedir

string

Home directory path.

inactive

string

Days after password expires until account is disabled.

lock_passwd

boolean

User password lock.

Choices:

  • false

  • true

name

string / required

User name.

no_create_home

boolean

Home directory creation skip.

Choices:

  • false

  • true

no_log_init

boolean

User initialization log skip.

Choices:

  • false

  • true

no_user_group

boolean

User group creation skip.

Choices:

  • false

  • true

passwd

string

Hashed password for the user.

plain_text_passwd

string

Plain text password for the user.

primary_group

string

Primary group for the user.

selinux_user

string

SELinux user for login mapping.

shell

string

Login shell for the user.

snapuser

string

Email for Snappy user creation.

ssh_authorized_keys

list / elements=string

SSH public keys to add to the user.

ssh_import_id

list / elements=string

SSH IDs to import public keys from.

ssh_redirect_user

boolean

SSH login redirection to default user.

Choices:

  • false

  • true

sudo

any

Sudo rule for the user.

system

boolean

System user.

Choices:

  • false

  • true

uid

integer

Numeric user ID.

write_files

list / elements=dictionary

Files to create on first boot.

append

boolean

File append mode.

Choices:

  • false

  • true

content

string

Content to write to the file.

defer

boolean

Deferred writing until final stage.

Choices:

  • false

  • true

encoding

string

Content encoding.

Choices:

  • "b64"

  • "base64"

  • "gz"

  • "gzip"

  • "gz+b64"

  • "gzip+b64"

  • "gz+base64"

  • "gzip+base64"

  • "text/plain"

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.

source

dictionary

URL source for file content.

headers

list / elements=dictionary

HTTP headers for the request.

name

string / required

Header name.

value

string / required

Header value.

uri

string / required

URL to fetch content from.

cluster.evacuate

string

Evacuation behavior during cluster evacuation.

Choices:

  • "auto"

  • "live-migrate"

  • "migrate"

  • "stop"

  • "stateful-stop"

  • "force-stop"

environment_variables

list / elements=dictionary

Environment variables to set in the instance.

Each entry is flattened to an environment.NAME config key.

name

string / required

Environment variable name.

value

string / required

Environment variable value.

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

Memory hotplug.

limits.memory.hugepages

boolean

Huge page memory backing.

Choices:

  • false

  • true

limits.memory.oom_priority

integer

OOM killer priority for the instance.

limits.memory.swap

string

Swap encouragement or discouragement.

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

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

Incus-agent metrics exposure.

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

BPFFS mount path in the instance.

security.csm

boolean

Compatibility Support Module.

Choices:

  • false

  • true

security.guestapi

boolean

Guest API.

Choices:

  • false

  • true

security.guestapi.images

boolean

Guest API image access.

Choices:

  • false

  • true

security.idmap.base

integer

Base host UID/GID for the ID map.

security.idmap.isolated

boolean

Unique ID map isolation.

Choices:

  • false

  • true

security.idmap.size

integer

Size of the ID map range.

security.iommu

boolean

IOMMU.

Choices:

  • false

  • true

security.nesting

boolean

Incus nesting support.

Choices:

  • false

  • true

security.privileged

boolean

Privileged mode.

Choices:

  • false

  • true

security.protection.delete

boolean

Deletion protection.

Choices:

  • false

  • true

security.protection.shift

boolean

UID/GID shift protection.

Choices:

  • false

  • true

security.secureboot

boolean

UEFI Secure Boot.

Choices:

  • false

  • true

security.sev

boolean

AMD SEV encryption.

Choices:

  • false

  • true

security.sev.policy.es

boolean

SEV-ES.

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

Compat syscall blocking on amd64.

Choices:

  • false

  • true

security.syscalls.deny_default

boolean

Default syscall deny list.

Choices:

  • false

  • true

security.syscalls.intercept.bpf

boolean

BPF syscall interception.

Choices:

  • false

  • true

security.syscalls.intercept.bpf.devices

boolean

Device-type BPF program allowance.

Choices:

  • false

  • true

security.syscalls.intercept.mknod

boolean

Mknod syscall interception.

Choices:

  • false

  • true

security.syscalls.intercept.mount

boolean

Mount syscall interception.

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

ID-mapped mount shifting for intercepted mounts.

Choices:

  • false

  • true

security.syscalls.intercept.sched_setscheduler

boolean

Sched_setscheduler syscall interception.

Choices:

  • false

  • true

security.syscalls.intercept.setxattr

boolean

Setxattr syscall interception.

Choices:

  • false

  • true

security.syscalls.intercept.sysinfo

boolean

Sysinfo syscall interception.

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

Stopped instance snapshots.

Choices:

  • false

  • true

description

string

Instance 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: []

acceleration

string

Enable hardware offloading (none/sriov/vdpa) (nic, OVN only).

address

string

PCI address of the device (pci only, VMs only).

attached

boolean

Attached or ejected state (disk, nic).

Choices:

  • false

  • true

bind

string

Which side to bind on, host or instance (proxy only).

boot.priority

integer

Boot priority for VMs (disk, nic).

busnum

integer

Bus number the USB device is connected to (usb only).

ceph.cluster_name

string

Ceph cluster name (disk only).

ceph.user_name

string

Ceph user name (disk only).

connect

string

Address and port to connect to (proxy only).

connected

boolean

Host network connection state (nic only).

Choices:

  • false

  • true

dependent

boolean

Instance dependent disk (disk only).

Choices:

  • false

  • true

devnum

integer

Device number of the USB device (usb only).

firmware

boolean

Device option ROM exposure (pci only).

Choices:

  • false

  • true

gid

integer

GID of the device owner in the instance (unix-char, unix-block, unix-hotplug).

gputype

string

GPU type (gpu only).

Choices:

  • "mdev"

  • "mig"

  • "physical"

  • "sriov"

gvrp

boolean

Register VLAN using GARP VLAN Registration Protocol (nic only).

Choices:

  • false

  • true

host_name

string

Name of the interface on the host (nic only).

hwaddr

string

MAC address of the new interface (nic, infiniband).

id

string

DRM card ID of the GPU device (gpu only).

io.bus

string

Override bus for the device, e.g. virtio or usb (disk, nic, VMs only).

io.cache

string

Caching mode for the disk device (disk only).

ipv4.address

string

IPv4 address to assign via DHCP or static allocation (nic only).

ipv4.address.external

string

Select specific external IPv4 address (nic, OVN only).

ipv4.gateway

string

Default IPv4 gateway, e.g. auto or none (nic, routed/ipvlan only).

ipv4.host_address

string

IPv4 address on the host-side veth interface (nic, routed only).

ipv4.host_table

integer

Custom policy routing table ID for IPv4 (nic, deprecated in favor of ipv4.host_tables).

ipv4.host_tables

string

Comma-separated routing table IDs for IPv4 routes (nic, routed only).

ipv4.neighbor_probe

boolean

Parent network IP availability probe (nic, routed only).

Choices:

  • false

  • true

ipv4.routes

string

Comma-delimited IPv4 static routes to add on the host (nic only).

ipv4.routes.external

string

Comma-delimited IPv4 routes to publish via BGP (nic only).

ipv6.address

string

IPv6 address to assign via DHCP or static allocation (nic only).

ipv6.address.external

string

Select specific external IPv6 address (nic, OVN only).

ipv6.gateway

string

Default IPv6 gateway, e.g. auto or none (nic, routed/ipvlan only).

ipv6.host_address

string

IPv6 address on the host-side veth interface (nic, routed only).

ipv6.host_table

integer

Custom policy routing table ID for IPv6 (nic, deprecated in favor of ipv6.host_tables).

ipv6.host_tables

string

Comma-separated routing table IDs for IPv6 routes (nic, routed only).

ipv6.neighbor_probe

boolean

Parent network IP availability probe (nic, routed only).

Choices:

  • false

  • true

ipv6.routes

string

Comma-delimited IPv6 static routes to add on the host (nic only).

ipv6.routes.external

string

Comma-delimited IPv6 routes to publish via BGP (nic only).

limits.egress

string

Outgoing traffic I/O limit in bit/s (nic only).

limits.ingress

string

Incoming traffic I/O limit in bit/s (nic only).

limits.max

string

I/O limit in byte/s or IOPS for both read and write (disk), or combined traffic limit in bit/s (nic).

limits.priority

integer

Outgoing traffic priority for queuing (nic only).

limits.read

string

I/O limit in byte/s or IOPS for read operations (disk only).

limits.write

string

I/O limit in byte/s or IOPS for write operations (disk only).

listen

string

Address and port to bind and listen on (proxy only).

major

integer

Device major number (unix-char, unix-block).

mdev

string

Mediated device profile to use (gpu mdev only, VMs only).

mig.ci

integer

Existing MIG compute instance ID (gpu mig only, containers only).

mig.gi

integer

Existing MIG GPU instance ID (gpu mig only, containers only).

mig.uuid

string

Existing MIG device UUID (gpu mig only, containers only).

minor

integer

Device minor number (unix-char, unix-block).

mode

string

NIC mode, e.g. bridge for macvlan (nic), or device permission mode, e.g. 0660 (unix-char, unix-block, unix-hotplug).

mtu

string

Maximum transmission unit of the new interface (nic, infiniband).

name

string / required

Device name used as the key in the Incus API.

nat

boolean

NAT-based proxying (proxy only).

Choices:

  • false

  • true

nested

string

Parent NIC name to nest this OVN NIC under (nic, OVN only).

network

string

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

nictype

string

NIC type when not using a managed network (nic, infiniband).

parent

string

Parent host device name (nic, infiniband).

path

string

Path inside the instance (disk, tpm, unix-char, unix-block).

pathrm

string

Resource manager path inside the instance, e.g. /dev/tpmrm0 (tpm, containers only).

pci

string

PCI address of the parent host device (nic SR-IOV, unix-hotplug).

pool

string

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

productid

string

Product ID of the parent host device (nic SR-IOV, unix-hotplug).

propagation

string

Controls how a bind-mount is shared between instance and host (disk only).

proxy_protocol

boolean

HAProxy PROXY protocol for sender information (proxy only).

Choices:

  • false

  • true

queue.tx.length

integer

Transmit queue length for the NIC (nic only).

raw.mount.options

string

File system specific mount options (disk only).

readonly

boolean

Read-only mount (disk only).

Choices:

  • false

  • true

recursive

boolean

Recursive source mount (disk only).

Choices:

  • false

  • true

required

boolean

Source existence requirement (disk, unix-char, unix-block, unix-hotplug).

Choices:

  • false

  • true

security.acls

string

Comma-separated list of network ACLs to apply (nic only).

security.acls.default.egress.action

string

Default action for egress traffic not matching any ACL rule (nic only).

security.acls.default.egress.logged

boolean

Unmatched egress traffic logging (nic only).

Choices:

  • false

  • true

security.acls.default.ingress.action

string

Default action for ingress traffic not matching any ACL rule (nic only).

security.acls.default.ingress.logged

boolean

Unmatched ingress traffic logging (nic only).

Choices:

  • false

  • true

security.gid

integer

GID to drop privilege to (proxy only).

security.ipv4_filtering

boolean

IPv4 address spoofing prevention (nic, bridged only).

Choices:

  • false

  • true

security.ipv6_filtering

boolean

IPv6 address spoofing prevention (nic, bridged only).

Choices:

  • false

  • true

security.mac_filtering

boolean

MAC address spoofing prevention (nic only).

Choices:

  • false

  • true

security.port_isolation

boolean

NIC port isolation (nic, bridged only).

Choices:

  • false

  • true

security.promiscuous

boolean

Promiscuous mode for unknown traffic (nic, OVN only).

Choices:

  • false

  • true

security.trusted

boolean

Trusted NIC configuration (nic, SR-IOV only).

Choices:

  • false

  • true

security.uid

integer

UID to drop privilege to (proxy only).

serial

string

Serial number of the USB device (usb only).

shift

boolean

UID/GID shifting overlay (disk, containers only).

Choices:

  • false

  • true

size

string

Disk size limit, e.g. 20GiB (disk only).

size.state

string

Size for the VM runtime state file system (disk, VMs only).

source

string

Source of a file system, block device, or host device path (disk, unix-char, unix-block).

type

string / required

Device type.

Choices:

  • "disk"

  • "gpu"

  • "infiniband"

  • "nic"

  • "none"

  • "pci"

  • "proxy"

  • "tpm"

  • "unix-block"

  • "unix-char"

  • "unix-hotplug"

  • "usb"

uid

integer

UID of the device owner in the instance (unix-char, unix-block, unix-hotplug).

vendorid

string

Vendor ID of the parent host device (nic SR-IOV, unix-hotplug).

vlan

integer

VLAN ID to attach to (nic only).

vlan.tagged

string

Comma-separated VLAN IDs or ranges for tagged traffic (nic only).

vrf

string

VRF name on the host for the host-side interface and routes (nic, routed only).

wwn

boolean

World Wide Name assignment (disk, VMs only).

Choices:

  • false

  • true

ephemeral

boolean

Whether the instance is ephemeral (deleted on stop).

Set on creation only — cannot be changed afterwards.

Choices:

  • false ← (default)

  • true

name

string / required

Name of the instance.

profiles

list / elements=string

List of profiles to apply to the instance.

Default: ["default"]

project

string

Incus project to query.

Default: "default"

server_cert

string

Server certificate content for remote verification.

Requires url. Mutually exclusive with server_cert_path.

server_cert_path

string

Server certificate path for remote verification.

Requires url. Mutually exclusive with server_cert.

socket_path

string

Incus Unix socket path for local connections.

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

source

string

Image reference to copy from, e.g. images:debian/13, ubuntu/24.04, or docker:library/nginx.

remote:alias format auto-resolves well-known remotes (images, ubuntu, ubuntu-daily, docker).

source_protocol

string

Protocol used to communicate with source_server.

Choices:

  • "simplestreams" ← (default)

  • "incus"

  • "oci"

source_server

string

URL of the image server to pull from, e.g. https://images.linuxcontainers.org.

Takes precedence over auto-resolved remotes when source uses the remote:alias format.

state

string

Desired state of the instance.

started ensures the instance exists and is running.

stopped ensures the instance exists and is stopped.

restarted restarts the instance if it is running.

absent ensures the instance does not exist.

Choices:

  • "started" ← (default)

  • "stopped"

  • "restarted"

  • "absent"

target

string

Cluster member to place the instance on.

Only used during creation — ignored for existing instances.

token

string

Token for remote authentication.

Requires url. Mutually exclusive with client_cert.

type

string

Instance type.

Set on creation only — cannot be changed afterwards.

Choices:

  • "container" ← (default)

  • "virtual-machine"

url

string

Remote Incus server URL (e.g. https://host:8443).

If specified, connects via HTTPS instead of Unix socket.

validate_certs

boolean

Server TLS certificate validation.

Choices:

  • false

  • true ← (default)

wait

boolean

Async operation completion wait.

Set to false for fire-and-forget behaviour.

Choices:

  • false

  • true ← (default)

Examples

- name: Ensure container is started
  damex.incus.incus_instance:
    name: mycontainer
    source: ubuntu/22.04
    profiles:
      - default
    config:
      limits.cpu: "2"
      limits.memory: 2GiB

- name: Ensure instance is stopped
  damex.incus.incus_instance:
    name: mycontainer
    state: stopped

- name: Ensure instance on specific cluster member
  damex.incus.incus_instance:
    name: mycontainer
    source: ubuntu/22.04
    target: node1
    profiles:
      - default

- name: Ensure instance is absent
  damex.incus.incus_instance:
    name: mycontainer
    state: absent

Return Values

Common return values are documented here, the following are the fields unique to this module:

Key

Description

changed

boolean

Resource state change indicator.

Returned: always

changed_keys

list / elements=string

Configuration keys that changed.

Returned: always

diff

dictionary

Before and after state for diff mode.

Returned: changed

after

dictionary

State after the change.

Returned: success

before

dictionary

State before the change.

Returned: success

Authors

  • Roman Kuzmitskii (@damex)