damex.incus.incus_image module – Ensure Incus image

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

Synopsis 

Copy and delete Incus images via the Incus REST API.
Images are project-scoped resources identified by alias.
Copying from remote servers uses the remote:alias format (e.g. images:debian/13).

Parameters 

Parameter	Comments
alias string / required	Alias for the image on the local server. Used to check existence and as the alias assigned on copy.
auto_update boolean	Automatically update the image when a new build is available on the source server. Choices: `false` ← (default) `true`
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`.
copy_aliases boolean	Copy all aliases from the source image. Choices: `false` ← (default) `true`
project string	Incus project to query. Default: `"default"`
public boolean	Make the image available to unauthenticated users. Choices: `false` ← (default) `true`
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"`
source string	Image reference to copy from, e.g. `images:debian/13` or `ubuntu/24.04`. The `remote:alias` format auto-resolves well-known remotes (`images`, `ubuntu`, `ubuntu-daily`).
source_protocol string	Protocol used to communicate with `source_server`. Choices: `"simplestreams"` ← (default) `"incus"`
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 image. Choices: `"present"` ← (default) `"absent"`
token string	Token for remote authentication. Requires `url`. Mutually exclusive with `client_cert`.
type string	Image type to request from the remote server. Choices: `"container"` ← (default) `"virtual-machine"`
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: Copy Debian 13 container image
  damex.incus.incus_image:
    alias: debian/13
    source: images:debian/13

- name: Copy Ubuntu 24.04 VM image
  damex.incus.incus_image:
    alias: ubuntu/24.04
    source: images:ubuntu/24.04
    type: virtual-machine

- name: Copy image with auto-update
  damex.incus.incus_image:
    alias: debian/13
    source: images:debian/13
    auto_update: true

- name: Delete an image
  damex.incus.incus_image:
    alias: debian/13
    state: absent

Authors

Roman Kuzmitskii (@damex)

Collection links