@spec create(ExIncus.Client.t(), map(), keyword()) :: result()

Creates an image from an ImagesPost params map - typically pulling from a remote server (see module doc) or publishing an instance ("source" => %{"type" => "instance", "name" => "web1"}).

This can take a while for remote pulls; raise timeout: accordingly.

@spec create_alias(ExIncus.Client.t(), String.t(), String.t(), keyword()) :: result()

Creates an alias pointing at an image fingerprint.

@spec delete(ExIncus.Client.t(), String.t(), keyword()) :: result()

Deletes an image.

@spec delete_alias(ExIncus.Client.t(), String.t(), keyword()) :: result()

Deletes an alias.

@spec export(ExIncus.Client.t(), String.t(), keyword()) ::
  {:ok, binary()} | {:error, ExIncus.Error.t()}

Downloads an image as a unified tarball binary.

Note the whole image is held in memory; export_file/4 writes it to disk.

@spec export_file(ExIncus.Client.t(), String.t(), Path.t(), keyword()) ::
  {:ok, Path.t()} | {:error, ExIncus.Error.t()}

Downloads an image and writes it to dest_path. Returns {:ok, dest_path}.

@spec get(ExIncus.Client.t(), String.t(), keyword()) :: result()

Fetches a single image by fingerprint.

@spec get_alias(ExIncus.Client.t(), String.t(), keyword()) :: result()

Fetches a single image alias.

@spec import_file(ExIncus.Client.t(), Path.t(), keyword()) :: result()

Imports an image tarball from disk - the API equivalent of incus image import file.tar.gz --alias name --reuse:

{:ok, image} =
  ExIncus.Images.import_file(client, "/tmp/converted.tar.gz",
    alias: "myapp", reuse: true)

image["fingerprint"]

The tarball must be in unified format (single file containing metadata.yaml + rootfs - what incus image export and OCI conversion tools produce). Split metadata/rootfs pairs are not supported yet.

See import_tarball/3 for the options; :filename defaults to the file's basename. The file is read into memory for the upload.

@spec import_tarball(ExIncus.Client.t(), binary(), keyword()) :: result()

Imports an image tarball (unified format) given as a binary and returns the resulting image record.

The fingerprint of a unified tarball is its SHA-256, so the import is idempotent: if the image already exists the upload is skipped and only the aliases are checked. The operation is always waited on (aliases can't be assigned before the image exists), so wait: false does not apply here.

Options

• :alias / :aliases - alias name(s) to point at the imported image
• :reuse - if an alias already points at a different image, delete that image and take over the alias (like incus image import --reuse). Without it, a conflicting alias is an error (reason: :alias_conflict).
• :public - make the image available to unauthenticated clients
• :properties - map of descriptive properties (e.g. %{os: "Alpine"})
• :filename - original filename, stored as image metadata
• :timeout / :project - as everywhere else

@spec list(
  ExIncus.Client.t(),
  keyword()
) :: result()

Lists images (full objects by default).

@spec list_aliases(
  ExIncus.Client.t(),
  keyword()
) :: result()

Lists image aliases (full objects by default).

@spec patch(ExIncus.Client.t(), String.t(), map(), keyword()) :: result()

Partially updates image properties (PATCH).

@spec rename_alias(ExIncus.Client.t(), String.t(), String.t(), keyword()) :: result()

Renames an alias.

@spec update(ExIncus.Client.t(), String.t(), map(), keyword()) :: result()

Replaces image properties (PUT with an ImagePut map).

@spec update_alias(ExIncus.Client.t(), String.t(), map(), keyword()) :: result()

Updates an alias (PUT with "target" and/or "description").