doc/instances: add UI instructions

Add instructions for how to manage and configure instances through
the UI.
This is part of a PoC for how we can present instructional content
for different clients.

Signed-off-by: Ruth Fuchss <ruth.fuchss@canonical.com>

doc/howto/instances_configure.md

@@ -13,37 +13,60 @@ 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 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
+To set the memory limit to 128 MiB, enter the following command:
+
     lxc config set my-container limits.memory=128MiB
 ```
 
 ```{group-tab} API
+To set the memory limit to 128 MiB, send the following request:
+
     lxc query --request PATCH /1.0/instances/my-container --data '{"config": {"limits.memory":"128MiB"}}'
 ```
+
+```{group-tab} UI
+To set the memory limit to 128 MiB, go to the {guilabel}`Configuration` tab of the instance page and select {guilabel}`Configuration options > Resource limits`.
+Then click {guilabel}`Edit instance`.
+
+Select {guilabel}`Override` for the **Memory limit** and enter 128 MiB as the absolute value.
+
+![Setting the memory limit for an instance to 128 MiB](/images/UI/limits_memory_example.png)
+```
 ````
 
 ```{note}
@@ -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,30 @@ 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}
+If you edit the YAML configuration to include any fields that are not supported by the UI, you must do all further configuration of the instance through the YAML configuration.
+You must not use any UI forms to do configuration updates afterwards, even for configuration that is covered by the UI.
+
+When you save updates you did through the UI forms, only the fields defined by those forms are retained, and any custom configuration you did in the YAML configuration is discarded.
+```
+
+To edit the YAML configuration of your instance, go to the instance 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.
+
+Click the instance name to see detailed information.
+```
 ````
 
 ## Start an instance
@@ -104,6 +119,13 @@ 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 (▷).
+
+On the instance page, select the {guilabel}`Console` tab to see information about the instance starting up.
+Once it is running, you can select the {guilabel}`Terminal` tab to access the instance.
+```
 ````
 
 (instances-manage-stop)=
@@ -130,6 +152,20 @@ To stop an instance, send a PUT request to change the instance state:
 ```
 
 ````
+
+````{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.
+If needed, you can choose to force-stop the instance.
+
+<!-- Include start skip confirmation -->
+```{tip}
+To skip the confirmation prompt, hold the {kbd}`Shift` key while clicking.
+```
+<!-- Include end skip confirmation -->
+
+````
+
 `````
 
 ## Delete an instance
@@ -151,6 +187,16 @@ 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 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 -->
+```
 ````
 
 ```{caution}
@@ -200,4 +246,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.
+```
 ````