Merge pull request #12934 from ru-fu/LXD-559-api-docs-images

Doc: add API instructions for images

doc/howto/images_copy.md

@@ -5,6 +5,8 @@ To add images to an image store, you can either copy them from another server or
 
 ## Copy an image from a remote
 
+`````{tabs}
+````{group-tab} CLI
 To copy an image from one server to another, enter the following command:
 
     lxc image copy [<source_remote>:]<image> <target_remote>:
@@ -27,7 +29,13 @@ The most relevant ones are:
 
 `--vm`
 : When copying from an alias, copy the image that can be used to create virtual machines.
+````
+````{group-tab} API
+To copy an image from one server to another, {ref}`export it to your local machine <images-manage-export>` and then {ref}`import it to the other server <images-copy-import>`.
+````
+`````
 
+(images-copy-import)=
 ## Import an image from files
 
 If you have image files that use the required {ref}`image-format`, you can import them into your image store.
@@ -40,6 +48,8 @@ There are several ways of obtaining such image files:
 
 ### Import from the local file system
 
+````{tabs}
+```{group-tab} CLI
 To import an image from the local file system, use the [`lxc image import`](lxc_image_import.md) command.
 This command supports both {ref}`unified images <image-format-unified>` (compressed file or directory) and {ref}`split images <image-format-split>` (two files).
 
@@ -53,6 +63,23 @@ To import a split image, enter the following command:
 
 In both cases, you can assign an alias with the `--alias` flag.
 See [`lxc image import --help`](lxc_image_import.md) for all available flags.
+```
+```{group-tab} API
+To import an image from the local file system, send a POST request to the `/1.0/images` endpoint.
+
+For example, to import a unified image from one file:
+
+    curl -X POST --unix-socket /var/snap/lxd/common/lxd/unix.socket lxd/1.0/images \
+    --data-binary @<image_file_path>
+
+To import a split image from a metadata file and a rootfs file:
+
+    curl -X POST --unix-socket /var/snap/lxd/common/lxd/unix.socket lxd/1.0/images \
+    --form metadata=@<metadata_tarball_path> --form rootfs.img=<rootfs_tarball_path>
+
+See [`POST /1.0/images`](swagger:/images/images_post) for more information.
+```
+````
 
 ### Import from a file on a remote web server
 
@@ -62,11 +89,27 @@ It only requires a basic web server with support for custom headers (see {ref}`i
 
 The image files must be provided as unified images (see {ref}`image-format-unified`).
 
+````{tabs}
+```{group-tab} CLI
 To import an image file from a remote web server, enter the following command:
 
     lxc image import <URL>
 
 You can assign an alias to the local image with the `--alias` flag.
+```
+```{group-tab} API
+To import an image file from a remote web server, send a POST request with the image URL to the `/1.0/images` endpoint:
+
+    lxc query --request POST /1.0/images --data '{
+      "source": {
+        "type": "url",
+        "url": "<URL>"
+      }
+    }'
+
+See [`POST /1.0/images`](swagger:/images/images_post) for more information.
+```
+````
 
 (images-copy-http-headers)=
 #### Custom HTTP headers

doc/howto/images_create.md

@@ -12,8 +12,11 @@ If you want to create and share your own images, you can do this either based on
 
 If you want to be able to use an instance or an instance snapshot as the base for new instances, you should create and publish an image from it.
 
-To publish an image from an instance, make sure that the instance is stopped.
-Then enter the following command:
+When publishing an image from an instance, make sure that the instance is stopped.
+
+````{tabs}
+```{group-tab} CLI
+To publish an image from an instance, enter the following command:
 
     lxc publish <instance_name> [<remote>:]
 
@@ -25,6 +28,45 @@ In both cases, you can specify an alias for the new image with the `--alias` fla
 If an image with the same name already exists, add the `--reuse` flag to overwrite it.
 See [`lxc publish --help`](lxc_publish.md) for a full list of available flags.
 
+```
+```{group-tab} API
+To publish an image from an instance or a snapshot, send a POST request with the suitable source type to the `/1.0/images` endpoint.
+
+To publish an image from an instance:
+
+    lxc query --request POST /1.0/images --data '{
+      "source": {
+        "name": "<instance_name>",
+        "type": "instance"
+      }
+    }'
+
+To publish an image from a snapshot
+
+    lxc query --request POST /1.0/images --data '{
+      "source": {
+        "name": "<instance_name>/<snapshot_name>",
+        "type": "snapshot"
+      }
+    }'
+
+In both cases, you can include additional configuration (for example, you can include aliases, set a custom expiration date, or make the image publicly available).
+For example:
+
+    lxc query --request POST /1.0/images --data '{
+      "aliases": [ { "name": "<alias>" } ],
+      "expires_at": "2025-03-23T20:00:00-04:00",
+      "public": true,
+      "source": {
+        "name": "<instance_name>",
+        "type": "instance"
+      }
+    }'
+
+See [`POST /1.0/images`](swagger:/images/images_post) for more information.
+```
+````
+
 The publishing process can take quite a while because it generates a tarball from the instance or snapshot and then compresses it.
 As this can be particularly I/O and CPU intensive, publish operations are serialized by LXD.
 
@@ -33,8 +75,8 @@ As this can be particularly I/O and CPU intensive, publish operations are serial
 Before you publish an image from an instance, clean up all data that should not be included in the image.
 Usually, this includes the following data:
 
-- Instance metadata (use [`lxc config metadata`](lxc_config_metadata.md) to edit)
-- File templates (use [`lxc config template`](lxc_config_template.md) to edit)
+- Instance metadata (use [`lxc config metadata`](lxc_config_metadata.md) or [`PATCH /1.0/instances/{name}/metadata`](swagger:/instances/instance_metadata_patch)/[`PUT /1.0/instances/{name}/metadata`](swagger:/instances/instance_metadata_put) to edit)
+- File templates (use [`lxc config template`](lxc_config_template.md) or [`POST /1.0/instances/{name}/metadata/templates`](swagger:/instances/instance_metadata_templates_post) to edit)
 - Instance-specific data inside the instance itself (for example, host SSH keys and `dbus/systemd machine-id`)
 
 (images-create-build)=