damex.incus.incus_image module – Ensure Incus image

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

Synopsis

  • Copy, update, 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).

  • Supports OCI registries such as Docker Hub using the docker:image format.

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

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.

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

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

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 Debian 13 container image
  damex.incus.incus_image:
    alias: debian/13
    source: images:debian/13

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

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

- name: Ensure image is public
  damex.incus.incus_image:
    alias: debian/13
    source: images:debian/13
    public: true

- name: Ensure nginx OCI image from Docker Hub
  damex.incus.incus_image:
    alias: nginx
    source: docker:library/nginx

- name: Ensure image from custom OCI registry
  damex.incus.incus_image:
    alias: myapp
    source: myapp/backend
    source_server: https://ghcr.io
    source_protocol: oci

- name: Ensure image is absent
  damex.incus.incus_image:
    alias: debian/13
    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)