Merge pull request #13423 from ru-fu/LXD-562-ui-instances

Doc: add UI instructions to instance how-tos

doc/howto/access_ui.md

@@ -7,7 +7,12 @@ The LXD web UI is available as part of the LXD snap.
 See the [LXD-UI GitHub repository](https://github.com/canonical/lxd-ui) for the source code.
 ```
 
-![Graphical console of an instance in the LXD web UI](../images/ui_console.png)
+```{figure} /images/ui_console.png
+:width: 100%
+:alt: Graphical console of an instance in the LXD web UI
+
+Graphical console of an instance in the LXD web UI
+```
 
 ```{youtube} https://www.youtube.com/watch?v=wqEH_d8LC1k
 ```
@@ -25,16 +30,20 @@ Complete the following steps to access the LXD web UI:
    If you have not set up a secure {ref}`authentication-server-certificate`, LXD uses a self-signed certificate, which will cause a security warning in your browser.
    Use your browser's mechanism to continue despite the security warning.
 
-   ![Example for a security warning in Chrome](../images/ui_security_warning.png
-)
+   ```{figure} /images/ui_security_warning.png
+   :width: 80%
+   :alt: Example for a security warning in Chrome
+   ```
 
 1. Set up the certificates that are required for the UI client to authenticate with the LXD server by following the steps presented in the UI.
    These steps include creating a set of certificates, adding the private key to your browser, and adding the public key to the server's trust store.
 
    See {ref}`authentication` for more information.
 
-   ![Instructions for setting up certificates for the UI](../images/ui_set_up_certificates.png
-)
+   ```{figure} /images/ui_set_up_certificates.png
+   :width: 80%
+   :alt: Instructions for setting up certificates for the UI
+   ```
 
 After setting up the certificates, you can start creating instances, editing profiles, or configuring your server.
 

doc/howto/instances_access_files.md

@@ -1,9 +1,13 @@
 (instances-access-files)=
 # How to access files in an instance
 
-You can manage files inside an instance using the LXD client without needing to access the instance through the network.
+You can manage files inside an instance using the LXD client or the API without needing to access the instance through the network.
 Files can be individually edited or deleted, pushed from or pulled to the local machine.
-Alternatively, you can mount the instance's file system onto the local machine.
+Alternatively, if you're using the LXD client, you can mount the instance's file system onto the local machine.
+
+```{note}
+The UI does not currently support accessing files in an instance.
+```
 
 For containers, these file operations always work and are handled directly by LXD.
 For virtual machines, the `lxd-agent` process must be running inside of the virtual machine for them to work.

doc/howto/instances_backup.md

@@ -75,6 +75,19 @@ Note that this feature is not fully supported for containers because of CRIU lim
 
 See [`POST /1.0/instances/{name}/snapshots`](swagger:/instances/instance_snapshots_post) for more information.
 ````
+````{group-tab} UI
+To create a snapshot of an instance, go to the instance detail page and switch to the {guilabel}`Snapshots` tab.
+Click {guilabel}`Create snapshot` to open the dialog to create a snapshot.
+
+The snapshot name is optional.
+If you don't specify one, the name follows the naming pattern defined in {config:option}`instance-snapshots:snapshots.pattern`.
+You can check and update this option by switching to the {guilabel}`Configuration` tab and selecting {guilabel}`Advanced` > {guilabel}`Snapshots`, or simply by clicking {guilabel}`See configuration`.
+
+By default, snapshots are kept forever, unless you specify an expiry date and time, or the {config:option}`instance-snapshots:snapshots.expiry` configuration option is set for the instance.
+
+For virtual machines, you can choose to create a stateful snapshot to capture not only the data included in the instance volume but also the running state of the instance.
+Note that this feature requires {config:option}`instance-migration:migration.stateful` to be enabled.
+````
 `````
 
 (instances-snapshots-delete)=
@@ -133,6 +146,11 @@ To delete a snapshot, send a DELETE request:
 
 See [`GET /1.0/instances/{name}/snapshots`](swagger:/instances/instance_snapshots_get), [`GET /1.0/instances/{name}/snapshots/{snapshot}`](swagger:/instances/instance_snapshot_get), [`PATCH /1.0/instances/{name}/snapshots/{snapshot}`](swagger:/instances/instance_snapshot_patch), and [`DELETE /1.0/instances/{name}/snapshots/{snapshot}`](swagger:/instances/instance_snapshot_delete) for more information.
 
+````
+````{group-tab} UI
+To see all snapshots for an instance, go to the instance detail page and switch to the {guilabel}`Snapshots` tab.
+
+From the snapshot list, you can choose to edit the name or expiry date of a specific snapshot, create an image based on the snapshot, restore it to the instance, or delete it.
 ````
 `````
 
@@ -143,7 +161,7 @@ To do so, set the {config:option}`instance-snapshots:snapshots.schedule` instanc
 
 For example, to configure daily snapshots:
 
-````{tabs}
+`````{tabs}
 ```{group-tab} CLI
     lxc config set <instance_name> snapshots.schedule @daily
 ```
@@ -154,11 +172,17 @@ For example, to configure daily snapshots:
       }
     }'
 ```
+````{group-tab} UI
+```{figure} /images/UI/snapshots_daily.png
+   :width: 80%
+   :alt: Configure daily snapshots
+```
 ````
+`````
 
 To configure taking a snapshot every day at 6 am:
 
-````{tabs}
+`````{tabs}
 ```{group-tab} CLI
     lxc config set <instance_name> snapshots.schedule "0 6 * * *"
 ```
@@ -169,7 +193,12 @@ To configure taking a snapshot every day at 6 am:
       }
     }'
 ```
-````
+````{group-tab} UI
+```{figure} /images/UI/snapshots_cron.png
+   :width: 80%
+   :alt: Configure snapshots daily at 6am
+```
+`````````
 
 When scheduling regular snapshots, consider setting an automatic expiry ({config:option}`instance-snapshots:snapshots.expiry`) and a naming pattern for snapshots ({config:option}`instance-snapshots:snapshots.pattern`).
 You should also configure whether you want to take snapshots of instances that are not running ({config:option}`instance-snapshots:snapshots.schedule.stopped`).
@@ -202,6 +231,11 @@ If the snapshot is stateful (which means that it contains information about the
 
 See [`PUT /1.0/instances/{name}`](swagger:/instances/instance_put) for more information.
 ```
+```{group-tab} UI
+To restore an instance to a snapshot, click the {guilabel}`Restore snapshot` button ({{restore_button}}) next to the snapshot that you want to restore.
+
+If the snapshot is stateful (which means that it contains information about the running state of the instance), select {guilabel}`Restore the instance state` if you want to restore the state.
+```
 ````
 
 (instances-backup-export)=
@@ -210,6 +244,11 @@ See [`PUT /1.0/instances/{name}`](swagger:/instances/instance_put) for more info
 You can export the full content of your instance to a standalone file that can be stored at any location.
 For highest reliability, store the backup file on a different file system to ensure that it does not get lost or corrupted.
 
+```{note}
+The UI does not currently support exporting and importing instances.
+```
+
+(instances-backup-export-instance)=
 ### Export an instance
 
 `````{tabs}
@@ -271,6 +310,7 @@ See [`POST /1.0/instances/{name}/backups`](swagger:/instances/instance_backups_p
 ````
 `````
 
+(instances-backup-import-instance)=
 ### Restore an instance from an export file
 
 You can import an export file (for example, `/path/to/my-backup.tgz`) as a new instance.

doc/howto/instances_configure.md

@@ -51,7 +51,7 @@ See {ref}`instance-options` for a list of available options and information abou
 
 For example, change the memory limit for your container:
 
-````{tabs}
+`````{tabs}
 ```{group-tab} CLI
 To set the memory limit to 8 GiB, enter the following command:
 
@@ -68,15 +68,18 @@ To set the memory limit to 8 GiB, send the following request:
     }'
 ```
 
-```{group-tab} UI
+````{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)
+```{figure} /images/UI/limits_memory_example.png
+   :width: 80%
+   :alt: Setting the memory limit for an instance to 8 GiB
 ```
 ````
+`````
 
 ```{note}
 Some of the instance options are updated immediately while the instance is running.
@@ -202,14 +205,14 @@ See [`PATCH /1.0/instances/{name}`](swagger:/instances/instance_patch) for more
 ````
 
 ````{group-tab} UI
-The UI currently has limited support for devices.
+The UI does not support all device types yet, but you can configure disk and network devices for your instances.
 
-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.
+To attach a device to your instance, or modify an existing device, update your instance configuration (in the same way as you {ref}`configure instance options <instances-configure-options>`).
+Select {guilabel}`Advanced` > {guilabel}`Disk devices` > {guilabel}`Attach disk device` or {guilabel}`Advanced` > {guilabel}`Network devices` > {guilabel}`Attach network` to create a device and attach it to your 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.
+Depending on the type of device, it might not be possible to edit these devices for an instance.
 ```
 
 To add and configure devices that are not currently supported in the UI, follow the instructions in {ref}`instances-configure-edit`.

doc/howto/instances_console.md

@@ -78,6 +78,9 @@ Alternatively, if you just want to retrieve new log messages from the console in
 See [`GET /1.0/instances/{name}/console`](swagger:/instances/instance_console_get) for more information.
 Note that this operation is supported only for containers, not for VMs.
 ````
+````{group-tab} UI
+Navigate to the instance detail page and switch to the {guilabel}`Console` tab to view the console.
+````
 `````
 
 ## Access the graphical console (for virtual machines)
@@ -109,4 +112,9 @@ To start the VGA console with graphical output for your VM, send a POST request
 
 See [`POST /1.0/instances/{name}/console`](swagger:/instances/instance_console_post) for more information.
 ```
+```{group-tab} UI
+Navigate to the instance detail page and switch to the {guilabel}`Console` tab to view the console.
+
+For virtual machines, you can switch between the graphic console and the text console.
+```
 ````