Merge pull request #12237 from ru-fu/LXD-357-ui-instructions

doc/instances: add UI instructions

doc/howto/instances_configure.md

@@ -13,36 +13,59 @@ To store and reuse different instance configurations, use {ref}`profiles <profil
 ## Configure instance options
 
 You can specify instance options when you {ref}`create an instance <instances-create>`.
+Alternatively, you can update the instance options after the instance is created.
 
 ````{tabs}
 ```{group-tab} CLI
-Alternatively, to update instance options after the instance is created, use the [`lxc config set`](lxc_config_set.md) command.
+Use the [`lxc config set`](lxc_config_set.md) command to update instance options.
 Specify the instance name and the key and value of the instance option:
 
     lxc config set <instance_name> <option_key>=<option_value> <option_key>=<option_value> ...
 ```
 
 ```{group-tab} API
-Alternatively, to update instance options after the instance is created, send a PATCH request to the instance.
+Send a PATCH request to the instance to update instance options.
 Specify the instance name and the key and value of the instance option:
 
     lxc query --request PATCH /1.0/instances/<instance_name> --data '{"config": {"<option_key>":"<option_value>","<option_key>":"<option_value>"}}'
 
 See [`PATCH /1.0/instances/{name}`](swagger:/instances/instance_patch) for more information.
 ```
+
+```{group-tab} UI
+To update instance options, go to the {guilabel}`Configuration` tab of the instance detail page and click {guilabel}`Edit instance`.
+
+Find the configuration option that you want to update and change its value.
+Click {guilabel}`Save changes` to save the updated configuration.
+
+To configure instance options that are not displayed in the UI, follow the instructions in {ref}`instances-configure-edit`.
+```
 ````
 
 See {ref}`instance-options` for a list of available options and information about which options are available for which instance type.
 
-For example, to change the memory limit for your container, enter the following command:
+For example, change the memory limit for your container:
 
 ````{tabs}
 ```{group-tab} CLI
-    lxc config set my-container limits.memory=128MiB
+To set the memory limit to 8 GiB, enter the following command:
+
+    lxc config set my-container limits.memory=8GiB
 ```
 
 ```{group-tab} API
-    lxc query --request PATCH /1.0/instances/my-container --data '{"config": {"limits.memory":"128MiB"}}'
+To set the memory limit to 8 GiB, send the following request:
+
+    lxc query --request PATCH /1.0/instances/my-container --data '{"config": {"limits.memory":"8GiB"}}'
+```
+
+```{group-tab} UI
+To set the memory limit to 8 GiB, go to the {guilabel}`Configuration` tab of the instance detail page and select {guilabel}`Advanced > Resource limits`.
+Then click {guilabel}`Edit instance`.
+
+Select {guilabel}`Override` for the **Memory limit** and enter 8 GiB as the absolute value.
+
+![Setting the memory limit for an instance to 8 GiB](/images/UI/limits_memory_example.png)
 ```
 ````
 
@@ -84,6 +107,11 @@ To unset an instance property, send a PUT request that contains the full instanc
 
 See [`PATCH /1.0/instances/{name}`](swagger:/instances/instance_patch) and [`PUT /1.0/instances/{name}`](swagger:/instances/instance_put) for more information.
 ```
+
+```{group-tab} UI
+The LXD UI does not distinguish between instance options and instance properties.
+Therefore, you can configure instance properties in the same way as you {ref}`configure instance options <instances-configure-options>`.
+```
 ````
 
 (instances-configure-devices)=
@@ -143,6 +171,21 @@ For example, to add the storage at `/share/c1` on the host system to your instan
 
 See [`PATCH /1.0/instances/{name}`](swagger:/instances/instance_patch) for more information.
 ````
+
+````{group-tab} UI
+The UI currently has limited support for devices.
+
+To attach a device to your instance, you must first create it.
+Then you can update your instance configuration (in the same way as you {ref}`configure instance options <instances-configure-options>`) to attach the device to the instance.
+
+```{note}
+Some of the devices that are displayed in the instance configuration are inherited from a {ref}`profile <profiles>` or defined through a {ref}`project <projects>`.
+These devices cannot be edited for an instance.
+```
+
+To add and configure devices that are not currently supported in the UI, follow the instructions in {ref}`instances-configure-edit`.
+````
+
 `````
 
 ## Display instance configuration
@@ -161,6 +204,13 @@ To retrieve the current configuration of your instance, including writable insta
 
 See [`GET /1.0/instances/{name}`](swagger:/instances/instance_get) for more information.
 ```
+
+```{group-tab} UI
+To view the current configuration of your instance, go to {guilabel}`Instances`, select your instance, and then switch to the {guilabel}`Configuration` tab.
+
+To see the full configuration including instance properties, instance options, devices and device options (also the ones that aren't yet supported by the UI), select {guilabel}`YAML configuration`.
+This view shows the full YAML of the instance configuration.
+```
 ````
 
 (instances-configure-edit)=
@@ -188,5 +238,28 @@ See [`PUT /1.0/instances/{name}`](swagger:/instances/instance_put) for more info
 
 ```{note}
 If you include changes to any read-only instance properties in the configuration you provide, they are ignored.
+```
+````
+
+````{group-tab} UI
+Instead of using the UI forms to configure your instance, you can choose to edit the YAML configuration of the instance.
+You must use this method if you need to update any configurations that are not available in the UI.
+
+```{important}
+When doing updates, do not navigate away from the YAML configuration without saving your changes.
+If you do, your updates are lost.
+```
+
+To edit the YAML configuration of your instance, go to the instance detail page, switch to the {guilabel}`Configuration` tab and select {guilabel}`YAML configuration`.
+Then click {guilabel}`Edit instance`.
+
+Edit the YAML configuration as required.
+Then click {guilabel}`Save changes` to save the updated configuration.
+
+```{note}
+For convenience, the YAML contains the full configuration including read-only instance properties.
+However, you cannot edit those properties.
+Any changes are ignored.
+```
 ````
 `````

doc/howto/instances_manage.md

@@ -45,6 +45,15 @@ For example:
 
 See [`GET /1.0/instances`](swagger:/instances/instances_get) for more information.
 ```
+
+```{group-tab} UI
+Go to {guilabel}`Instances` to see a list of all instances.
+
+You can filter the instances that are displayed by status, instance type, or the profile they use by selecting the corresponding filter.
+
+In addition, you can search for instances by entering a search text.
+The text you enter is matched against the name, the description, and the name of the base image.
+```
 ````
 
 ## Show information about an instance
@@ -67,6 +76,12 @@ Query the following endpoint to show detailed information about an instance:
 
 See [`GET /1.0/instances/{name}`](swagger:/instances/instance_get) for more information.
 ```
+
+```{group-tab} UI
+Clicking an instance line in the overview will show a summary of the instance information right next to the instance list.
+
+Click the instance name to go to the instance detail page, which contains detailed information about the instance.
+```
 ````
 
 ## Start an instance
@@ -104,6 +119,15 @@ Use the following query to monitor the state of the instance:
 See [`GET /1.0/instances/{name}/state`](swagger:/instances/instance_state_get) and [`PUT /1.0/instances/{name}/state`](swagger:/instances/instance_state_put)for more information.
 <!-- Include end monitor status -->
 ```
+
+```{group-tab} UI
+To start an instance, go to the instance list or the respective instance and click the {guilabel}`Start` button (▷).
+
+You can also start several instances at the same time by selecting them in the instance list and clicking the {guilabel}`Start` button at the top.
+
+On the instance detail page, select the {guilabel}`Console` tab to see the boot log with information about the instance starting up.
+Once it is running, you can select the {guilabel}`Terminal` tab to access the instance.
+```
 ````
 
 (instances-manage-stop)=
@@ -128,16 +152,32 @@ To stop an instance, send a PUT request to change the instance state:
     :start-after: <!-- Include start monitor status -->
     :end-before: <!-- Include end monitor status -->
 ```
+````
+
+````{group-tab} UI
+To stop an instance, go to the instance list or the respective instance and click the {guilabel}`Stop` button (□).
+You are then prompted to confirm.
+
+<!-- Include start skip confirmation -->
+```{tip}
+To skip the confirmation prompt, hold the {kbd}`Shift` key while clicking.
+```
+<!-- Include end skip confirmation -->
+
+You can choose to force-stop the instance.
+If stopping the instance takes a long time or the instance is not responding to the stop request, click the spinning stop button to go back to the confirmation prompt, where you can select to force-stop the instance.
 
+You can also stop several instances at the same time by selecting them in the instance list and clicking the {guilabel}`Stop` button at the top.
 ````
+
 `````
 
 ## Delete an instance
 
 If you don't need an instance anymore, you can remove it.
 The instance must be stopped before you can delete it.
 
-````{tabs}
+`````{tabs}
 ```{group-tab} CLI
 Enter the following command to delete an instance:
 
@@ -151,7 +191,20 @@ To delete an instance, send a DELETE request to the instance:
 
 See [`DELETE /1.0/instances/{name}`](swagger:/instances/instance_delete) for more information.
 ```
+
+````{group-tab} UI
+To delete an instance, go to its instance detail page and click {guilabel}`Delete instance`.
+You are then prompted to confirm.
+
+% Include content from above
+```{include} ./instances_manage.md
+    :start-after: <!-- Include start skip confirmation -->
+    :end-before: <!-- Include end skip confirmation -->
+```
+
+You can also delete several instances at the same time by selecting them in the instance list and clicking the {guilabel}`Delete` button at the top.
 ````
+`````
 
 ```{caution}
 This command permanently deletes the instance and all its snapshots.
@@ -200,4 +253,8 @@ To rebuild the instance with an empty root disk, specify the source type as `non
 
 See [`POST /1.0/instances/{name}/rebuild`](swagger:/instances/instance_rebuild_post) for more information.
 ```
+
+```{group-tab} UI
+Rebuilding an instance is not yet supported in the UI.
+```
 ````