damex.incus.incus_project module – Ensure Incus project

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

Synopsis

  • Create, configure, and delete Incus projects via the Incus REST API.

  • Global resource — not scoped to a project.

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

Project configuration.

All values are sent as strings to the Incus API.

Default: {}

backups.compression_algorithm

string

Compression algorithm for backups.

Choices:

  • "bzip2"

  • "gzip"

  • "lz4"

  • "lzma"

  • "xz"

  • "zstd"

  • "none"

features.images

boolean

Enable separate image store for the project.

Choices:

  • false

  • true

features.networks

boolean

Enable separate network management for the project.

Choices:

  • false

  • true

features.networks.zones

boolean

Enable separate network zone management for the project.

Choices:

  • false

  • true

features.profiles

boolean

Enable separate profile store for the project.

Choices:

  • false

  • true

features.storage.buckets

boolean

Enable separate storage bucket management for the project.

Choices:

  • false

  • true

features.storage.volumes

boolean

Enable separate storage volume management for the project.

Choices:

  • false

  • true

images.auto_update_cached

boolean

Whether to auto-update cached images.

Choices:

  • false

  • true

images.auto_update_interval

integer

Interval in hours between image auto-updates.

images.compression_algorithm

string

Compression algorithm for images.

Choices:

  • "bzip2"

  • "gzip"

  • "lz4"

  • "lzma"

  • "xz"

  • "zstd"

  • "none"

images.default_architecture

string

Default architecture for images.

images.remote_cache_expiry

integer

Number of days before cached remote images expire.

limits.containers

integer

Maximum number of containers in the project.

limits.cpu

integer

Maximum number of CPUs allocated to the project.

limits.disk

string

Maximum disk space used by the project.

limits.instances

integer

Maximum number of instances in the project.

limits.memory

string

Maximum memory used by the project.

limits.networks

integer

Maximum number of networks in the project.

limits.processes

integer

Maximum number of processes in the project.

limits.virtual-machines

integer

Maximum number of virtual machines in the project.

network.hwaddr_pattern

string

Pattern for automatically generated MAC addresses.

restricted

boolean

Whether to block access to security-sensitive features.

Choices:

  • false

  • true

restricted.backups

string

Prevent instance or volume backups.

Choices:

  • "allow"

  • "block"

restricted.cluster.groups

string

Comma-separated list of allowed cluster groups.

restricted.cluster.target

string

Whether to allow targeting cluster members.

Choices:

  • "allow"

  • "block"

restricted.containers.interception

string

Whether to allow system call interception in containers.

Choices:

  • "allow"

  • "block"

  • "full"

restricted.containers.lowlevel

string

Whether to allow low-level container options.

Choices:

  • "allow"

  • "block"

restricted.containers.nesting

string

Whether to allow nesting in containers.

Choices:

  • "allow"

  • "block"

restricted.containers.privilege

string

Control privileged container settings.

Choices:

  • "unprivileged"

  • "isolated"

  • "allow"

restricted.devices.disk

string

Control which disk devices can be used.

Choices:

  • "allow"

  • "block"

  • "managed"

restricted.devices.disk.paths

string

Comma-separated list of allowed disk source paths.

restricted.devices.gpu

string

Whether to allow GPU devices in the project.

Choices:

  • "allow"

  • "block"

restricted.devices.infiniband

string

Whether to allow InfiniBand devices in the project.

Choices:

  • "allow"

  • "block"

restricted.devices.nic

string

Control which network devices can be used.

Choices:

  • "allow"

  • "block"

  • "managed"

restricted.devices.pci

string

Whether to allow PCI devices in the project.

Choices:

  • "allow"

  • "block"

restricted.devices.proxy

string

Whether to allow proxy devices in the project.

Choices:

  • "allow"

  • "block"

restricted.devices.unix-block

string

Whether to allow Unix block devices in the project.

Choices:

  • "allow"

  • "block"

restricted.devices.unix-char

string

Whether to allow Unix character devices in the project.

Choices:

  • "allow"

  • "block"

restricted.devices.unix-hotplug

string

Whether to allow Unix hotplug devices in the project.

Choices:

  • "allow"

  • "block"

restricted.devices.usb

string

Whether to allow USB devices in the project.

Choices:

  • "allow"

  • "block"

restricted.idmap.gid

string

Allowed host GID ranges for raw.idmap.

restricted.idmap.uid

string

Allowed host UID ranges for raw.idmap.

restricted.networks.access

string

Comma-separated list of allowed networks for access.

restricted.networks.integrations

string

Comma-separated list of allowed network integrations.

restricted.networks.subnets

string

Comma-separated list of allowed network subnets.

string

Comma-separated list of allowed network uplinks.

restricted.networks.zones

string

Comma-separated list of allowed network zones.

restricted.snapshots

string

Prevent instance or volume snapshots.

Choices:

  • "allow"

  • "block"

restricted.virtual-machines.lowlevel

string

Whether to allow low-level virtual machine options.

Choices:

  • "allow"

  • "block"

description

string

Description of the project.

Default: ""

name

string / required

Name of the project.

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"

state

string

Desired state of the project.

Choices:

  • "present" ← (default)

  • "absent"

token

string

Token for remote authentication.

Requires url. Mutually exclusive with client_cert.

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 project
  damex.incus.incus_project:
    name: myproject
    description: My project
    config:
      features.images: true
      features.networks: false

- name: Ensure project is absent
  damex.incus.incus_project:
    name: myproject
    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)