Merge pull request #12831 from ru-fu/LXD-561-instances-API

Doc: Add API instructions to instances how-tos

doc/.sphinx/spellingcheck.yaml

@@ -26,3 +26,4 @@ matrix:
       - div.visually-hidden
       - img
       - a.p-navigation__link
+      - kbd

doc/cloud-init.md

@@ -67,7 +67,7 @@ To configure `cloud-init` for an instance, add the corresponding configuration o
 
 When configuring `cloud-init` directly for an instance, keep in mind that `cloud-init` runs only on the first start of the instance.
 That means that you must configure `cloud-init` before you start the instance.
-To do so, create the instance with [`lxc init`](lxc_init.md) instead of [`lxc launch`](lxc_launch.md), and then start it after completing the configuration.
+If you are using the CLI client, create the instance with [`lxc init`](lxc_init.md) instead of [`lxc launch`](lxc_launch.md), and then start it after completing the configuration.
 
 ### YAML format for `cloud-init` configuration
 
@@ -92,6 +92,35 @@ config:
 See {ref}`How to validate user data <cloud-init:check_user_data_cloud_config>` for information on how to check whether the syntax is correct.
 ```
 
+### Configure `cloud-init` through the API
+
+If you are using the API to configure your instance, provide the `cloud-init` configuration as a string with escaped newline characters.
+
+For example:
+
+    lxc query --request PATCH /1.0/instances/<instance_name> --data '{
+      "config": {
+        "cloud-init.user-data": "#cloud-config\npackage_upgrade: true\npackages:\n  - package1\n  - package2"
+      }
+    }'
+
+Alternatively, to avoid mistakes, write the configuration to a file and include that in your request.
+For example, create `cloud-init.txt` with the following content:
+
+    #cloud-config
+    package_upgrade: true
+    packages:
+      - package1
+      - package2
+
+Then send the following request:
+
+    lxc query --request PATCH /1.0/instances/<instance_name> --data '{
+    "config": {
+      "cloud-init.user-data": "'"$(awk -v ORS='\\n' '1' cloud-init.txt)"'"
+      }
+    }'
+
 ## How to check the `cloud-init` status
 
 `cloud-init` runs automatically on the first start of an instance.

doc/howto/instances_access_files.md

@@ -10,27 +10,49 @@ For virtual machines, the `lxd-agent` process must be running inside of the virt
 
 ## Edit instance files
 
+`````{tabs}
+````{group-tab} CLI
 To edit an instance file from your local machine, enter the following command:
 
     lxc file edit <instance_name>/<path_to_file>
 
 For example, to edit the `/etc/hosts` file in the instance, enter the following command:
 
-    lxc file edit my-container/etc/hosts
+    lxc file edit my-instance/etc/hosts
 
 ```{note}
 The file must already exist on the instance.
 You cannot use the `edit` command to create a file on the instance.
 ```
+````
+````{group-tab} API
+There is no API endpoint that lets you edit files directly on an instance.
+Instead, you need to {ref}`pull the content of the file from the instance <instances-access-files-pull>`, edit it, and then {ref}`push the modified content back to the instance <instances-access-files-push>`.
+````
+`````
 
 ## Delete files from the instance
 
+````{tabs}
+```{group-tab} CLI
 To delete a file from your instance, enter the following command:
 
     lxc file delete <instance_name>/<path_to_file>
+```
+```{group-tab} API
+Send the following DELETE request to delete a file from your instance:
+
+    lxc query --request DELETE /1.0/instances/<instance_name>/files?path=<path_to_file>
+
+See [`DELETE /1.0/instances/{name}/files`](swagger:/instances/instance_files_delete) for more information.
+```
+````
 
+(instances-access-files-pull)=
 ## Pull files from the instance to the local machine
 
+````{tabs}
+```{group-tab} CLI
 To pull a file from your instance to your local machine, enter the following command:
 
     lxc file pull <instance_name>/<path_to_file> <local_file_path>
@@ -47,19 +69,65 @@ This can be useful, for example, to check a log file:
 To pull a directory with all contents, enter the following command:
 
     lxc file pull -r <instance_name>/<path_to_directory> <local_location>
+```
+```{group-tab} API
+Send the following request to pull the contents of a file from your instance to your local machine:
+
+    lxc query --request GET /1.0/instances/<instance_name>/files?path=<path_to_file>
+
+You can then write the contents to a local file, or pipe them to stdin of another command.
+
+For example, to pull the contents of the `/etc/hosts` file and write them to a `my-instance-hosts` file in the current directory, enter the following command:
+
+    lxc query --request GET /1.0/instances/my-instance/files?path=/etc/hosts > my-instance-hosts
+
+To examine a log file, enter the following command:
+
+    lxc query --request GET /1.0/instances/<instance_name>/files?path=<file_path> | less
 
+To pull the contents of a directory, send the following request:
+
+    lxc query --request GET /1.0/instances/<instance_name>/files?path=<path_to_directory>
+
+This request returns a list of files in the directory, and you can then pull the contents of each file.
+
+See [`GET /1.0/instances/{name}/files`](swagger:/instances/instance_files_get) for more information.
+```
+````
+
+(instances-access-files-push)=
 ## Push files from the local machine to the instance
 
+````{tabs}
+```{group-tab} CLI
 To push a file from your local machine to your instance, enter the following command:
 
     lxc file push <local_file_path> <instance_name>/<path_to_file>
 
 To push a directory with all contents, enter the following command:
 
     lxc file push -r <local_location> <instance_name>/<path_to_directory>
+```
+```{group-tab} API
+Send the following request to write content to a file on your instance:
+
+    lxc query --request POST /1.0/instances/<instance_name>/files?path=<path_to_file> --data <content>
+
+See [`POST /1.0/instances/{name}/files`](swagger:/instances/instance_files_post) for more information.
+
+To push content directly from a file, you must use a tool that can send raw data from a file, which [`lxc query`](lxc_query.md) does not support.
+For example, with curl:
+
+    curl -X POST -H "Content-Type: application/octet-stream" --data @<local_file_path> \
+    --unix-socket /var/snap/lxd/common/lxd/unix.socket \
+    lxd/1.0/instances/<instance_name>/files?path=<path_to_file>
+```
+````
 
 ## Mount a file system from the instance
 
+`````{tabs}
+````{group-tab} CLI
 You can mount an instance file system into a local path on your client.
 
 To do so, make sure that you have `sshfs` installed.
@@ -111,3 +179,8 @@ For example:
     sshfs [email protected]:/home my-instance-files -p 35147
 
 You can then access the file system of your instance at the specified location on the local machine.
+````
+````{group-tab} API
+Mounting a file system is not directly supported through the API, but requires additional processing logic on the client side.
+````
+`````