damex.incus.incus_image_import module – Ensure Incus image from file or URL

Note

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

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

Synopsis 

Import and delete Incus images from local files or URLs.
Supports raw and qcow2 disk images for virtual machines.
Raw images are automatically converted to qcow2 using qemu-img.
ZIP archives are automatically extracted.
Images are project-scoped resources identified by alias.
Requires qemu-img on the target host for format detection and conversion.

Parameters 

Parameter	Comments
alias string / required	Primary alias for the image on the local server. Used to check existence and as the first alias assigned on import.
aliases list / elements=string	Additional aliases to assign to the image.
architecture string	Image architecture identifier. Default: `"x86_64"`
checksum string	Expected checksum of the source file for verification. Verified against the downloaded or local source file before any extraction or conversion.
checksum_algorithm string	Hash algorithm used for `checksum` verification. Choices: `"sha256"` ← (default) `"sha512"` `"sha384"` `"md5"`
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	Path to the client certificate 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	Path to the client key for remote authentication. Requires `url` and `client_cert_path`. Mutually exclusive with `client_key`.
force boolean	Delete and re-import the image even when the alias already exists. Useful when the upstream source has been updated at the same URL. Choices: `false` ← (default) `true`
project string	Incus project to query. Default: `"default"`
properties dictionary	Image properties included in the metadata.
description string	Human-readable image description.
name string	Image name.
os string	Operating system name.
release string	Operating system release or version.
serial string	Image serial or build identifier.
variant string	Image variant.
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	Path to the server certificate for remote verification. Requires `url`. Mutually exclusive with `server_cert`.
socket_path string	Path to the Incus Unix socket for local connections. Default: `"/var/lib/incus/unix.socket"`
source string	Path to a local image file or URL to download from. Supports raw and qcow2 disk images. ZIP archives are automatically extracted. Required when `state=present` and the image does not yet exist or `force=true`.
state string	Desired state of the image. Choices: `"present"` ← (default) `"absent"`
timeout integer	Timeout in seconds for downloading the source file from a URL. Only applies when `source` is a URL. Default: `300`
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: Ensure MikroTik CHR image from URL
  damex.incus.incus_image_import:
    alias: chr/7.22
    source: https://download.mikrotik.com/routeros/7.22/chr-7.22.img.zip
    architecture: x86_64
    properties:
      os: RouterOS
      release: "7.22"
      description: MikroTik CHR 7.22

- name: Ensure MikroTik CHR image with checksum verification
  damex.incus.incus_image_import:
    alias: chr/7.22
    source: https://download.mikrotik.com/routeros/7.22/chr-7.22.img.zip
    checksum: e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855
    checksum_algorithm: sha256
    properties:
      os: RouterOS
      release: "7.22"
      description: MikroTik CHR 7.22

- name: Ensure image from local qcow2 file
  damex.incus.incus_image_import:
    alias: custom/1.0
    source: /tmp/custom-image.qcow2
    properties:
      os: CustomOS
      release: "1.0"
      description: Custom OS Image

- name: Ensure image with multiple aliases
  damex.incus.incus_image_import:
    alias: chr
    aliases:
      - chr/7.22
    source: https://download.mikrotik.com/routeros/7.22/chr-7.22.img.zip
    properties:
      os: RouterOS
      release: "7.22"
      description: MikroTik CHR 7.22

- name: Ensure image is re-imported from upstream
  damex.incus.incus_image_import:
    alias: chr/7.22
    source: https://download.mikrotik.com/routeros/7.22/chr-7.22.img.zip
    force: true
    properties:
      os: RouterOS
      release: "7.22"
      description: MikroTik CHR 7.22

- name: Ensure image is absent
  damex.incus.incus_image_import:
    alias: chr/7.22
    state: absent

Authors

Roman Kuzmitskii (@damex)

Collection links